Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Privacy Center Routes — encrypted PII Vault + Trusted Organizations
* registry REST surface (issues #2140, #2141).
*
* Every record-bearing endpoint is scoped to ONE household subject via an
* optional `?subjectId=` (list/read) or body `subjectId` (create). Omitting it
* means the seeded `self` subject, so every pre-#3658 client keeps working.
*
* Mounted at /api/privacy. Vault list/read responses carry `maskedValue`
* only — `value_enc` and plaintext never leave the service except through
* the ONE explicit reveal endpoint. Org holdings responses join the vault's
* masked fields only — never plaintext.
*/
import { Router } from 'express';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { validateRequest, isPaginationRequested, paginateArray } from '../lib/validation.js';
import {
privacySubjectCreateSchema,
privacySubjectUpdateSchema,
privacySubjectIdParamsSchema,
privacySubjectConsentSchema,
privacySubjectConsentRevokeSchema,
privacyChangeListQuerySchema,
privacySubjectScopeQuerySchema,
privacyVaultCreateSchema,
privacyVaultUpdateSchema,
privacyVaultListQuerySchema,
privacyVaultIdParamsSchema,
privacyOrgCreateSchema,
privacyOrgUpdateSchema,
privacyOrgListQuerySchema,
privacyOrgIdParamsSchema,
privacyOrgHoldingsSetSchema,
privacyBrokerListQuerySchema,
privacyBrokerCaseListQuerySchema,
privacyBrokerRefreshSchema,
privacyBrokerIdParamsSchema,
privacyBrokerUpdateSchema,
privacyCaseIdParamsSchema,
privacyCaseTransitionSchema,
privacyScanStartSchema,
privacyChangeDeclareSchema,
privacyChangeIdParamsSchema,
privacyChangeOrgParamsSchema,
privacyOptOutPassSchema,
privacyOptOutVerifySchema,
privacyRecheckConfigSchema,
} from '../lib/privacyValidation.js';
import {
listSubjects,
getSubject,
createSubject,
updateSubject,
deleteSubject,
listSubjectConsents,
recordConsent,
revokeConsent,
assertSubject,
} from '../services/privacySubjects.js';
import {
createVaultRecord,
listVaultRecords,
getVaultRecord,
updateVaultRecord,
deleteVaultRecord,
revealValue,
getVaultStatus,
} from '../services/privacyVault.js';
import {
createOrg,
listOrgs,
getOrg,
updateOrg,
deleteOrg,
setOrgHoldings,
getHoldingsForOrg,
getOrgsBySocialAccounts,
} from '../services/privacyOrgs.js';
import {
listBrokers,
refreshBrokers,
listBrokerCases,
getScanStatus,
setBrokerEnabled,
forceRecheckCase,
transitionCase,
revealCaseEvidence,
clearCaseIdentityEvidence,
} from '../services/privacyBrokers.js';
import { runScanPass } from '../services/privacyScan.js';
import { runOptOutPass, runVerificationPass, getOptOutDigest } from '../services/privacyOptOut.js';
import {
getPrivacyRecheckStatus,
restartPrivacyRecheckScheduler,
} from '../services/privacyRecheckScheduler.js';
import { getSettings, updateSettingsWith } from '../services/settings.js';
import {
declareChange,
listChangeEvents,
getChange,
markOrgUpdated,
markOrgRemoved,
draftUpdateEmail,
} from '../services/privacyChanges.js';
const router = Router();
// ─── Household subjects (issue #3658) ──────────────────────────────────────
// The people the Privacy Center works on behalf of. `self` is seeded and
// undeletable; every other subject requires a recorded consent method at
// creation. Broker purposes are separate, revocable grants — the scan/opt-out
// engines refuse to act without an active grant of their exact scope (#8332).
router.get('/subjects', asyncHandler(async (_req, res) => {
res.json(await listSubjects());
}));
router.post('/subjects', asyncHandler(async (req, res) => {
const data = validateRequest(privacySubjectCreateSchema, req.body);
res.status(201).json(await createSubject(data));
}));
router.get('/subjects/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacySubjectIdParamsSchema, req.params);
const subject = await getSubject(id);
if (!subject) throw new ServerError('Privacy subject not found', { status: 404, code: 'SUBJECT_NOT_FOUND' });
res.json(subject);
}));
router.put('/subjects/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacySubjectIdParamsSchema, req.params);
const patch = validateRequest(privacySubjectUpdateSchema, req.body);
res.json(await updateSubject(id, patch));
}));
// Hard DELETE — cascades the subject's vault records, orgs, holdings, change
// events, broker cases, and consent rows (machine-local, no tombstones).
router.delete('/subjects/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacySubjectIdParamsSchema, req.params);
res.json(await deleteSubject(id));
}));
router.get('/subjects/:id/consents', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacySubjectIdParamsSchema, req.params);
await assertSubject(id);
res.json(await listSubjectConsents(id));
}));
// Grant one purpose (e.g. the subject later agreed to broker scans or opt-outs).
// Appends a grant row; the scope defaults to the local-only `pii_vault`, so a
// broker purpose is only ever granted by naming it (#8332).
router.post('/subjects/:id/consents', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacySubjectIdParamsSchema, req.params);
const { scope, method, note } = validateRequest(privacySubjectConsentSchema, req.body);
res.status(201).json(await recordConsent({ subjectId: id, scope, method, note }));
}));
// Withdraw one broker purpose (`broker_scan` | `broker_optout`) WITHOUT deleting
// the subject: the active grant rows get a `revoked_at` timestamp (audit trail
// kept), and every later direct or scheduled call for that purpose is refused
// by the engine gate (#8332). Local-vault consent is still withdrawn by deleting
// the subject.
router.post('/subjects/:id/consents/revoke', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacySubjectIdParamsSchema, req.params);
const { scope } = validateRequest(privacySubjectConsentRevokeSchema, req.body);
res.json(await revokeConsent({ subjectId: id, scope }));
}));
router.get('/status', asyncHandler(async (req, res) => {
const { subjectId } = validateRequest(privacySubjectScopeQuerySchema, req.query);
res.json(await getVaultStatus({ subjectId }));
}));
router.get('/vault', asyncHandler(async (req, res) => {
const { type, subjectId } = validateRequest(privacyVaultListQuerySchema, req.query);
const records = await listVaultRecords({ type, subjectId });
if (!isPaginationRequested(req.query)) return res.json(records);
res.json(paginateArray(records, req.query, { defaultLimit: 50, maxLimit: 500 }));
}));
router.post('/vault', asyncHandler(async (req, res) => {
const data = validateRequest(privacyVaultCreateSchema, req.body);
res.status(201).json(await createVaultRecord(data));
}));
router.get('/vault/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyVaultIdParamsSchema, req.params);
const record = await getVaultRecord(id);
if (!record) throw new ServerError('Vault record not found', { status: 404, code: 'NOT_FOUND' });
res.json(record);
}));
router.put('/vault/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyVaultIdParamsSchema, req.params);
const patch = validateRequest(privacyVaultUpdateSchema, req.body);
res.json(await updateVaultRecord(id, patch));
}));
router.delete('/vault/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyVaultIdParamsSchema, req.params);
res.json(await deleteVaultRecord(id));
}));
router.post('/vault/:id/reveal', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyVaultIdParamsSchema, req.params);
res.json(await revealValue(id));
}));
// ─── Trusted Organizations registry (issue #2141) ──────────────────────────
router.get('/orgs', asyncHandler(async (req, res) => {
const { limit, offset, ...filters } = validateRequest(privacyOrgListQuerySchema, req.query);
const orgs = await listOrgs(filters);
if (!isPaginationRequested(req.query)) return res.json(orgs);
res.json(paginateArray(orgs, req.query, { defaultLimit: 50, maxLimit: 500 }));
}));
router.post('/orgs', asyncHandler(async (req, res) => {
const data = validateRequest(privacyOrgCreateSchema, req.body);
res.status(201).json(await createOrg(data));
}));
// Digital Twin ↔ org cross-link (issue #2147): which social accounts are in
// the org registry. Declared before `/orgs/:id` so the literal path wins.
router.get('/social-account-links', asyncHandler(async (req, res) => {
const { subjectId } = validateRequest(privacySubjectScopeQuerySchema, req.query);
res.json(await getOrgsBySocialAccounts({ subjectId }));
}));
router.get('/orgs/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyOrgIdParamsSchema, req.params);
const org = await getOrg(id);
if (!org) throw new ServerError('Organization not found', { status: 404, code: 'NOT_FOUND' });
res.json(org);
}));
router.put('/orgs/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyOrgIdParamsSchema, req.params);
const patch = validateRequest(privacyOrgUpdateSchema, req.body);
res.json(await updateOrg(id, patch));
}));
router.delete('/orgs/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyOrgIdParamsSchema, req.params);
res.json(await deleteOrg(id));
}));
router.get('/orgs/:id/holdings', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyOrgIdParamsSchema, req.params);
const org = await getOrg(id);
if (!org) throw new ServerError('Organization not found', { status: 404, code: 'NOT_FOUND' });
res.json(await getHoldingsForOrg(id));
}));
router.put('/orgs/:id/holdings', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyOrgIdParamsSchema, req.params);
const { holdings } = validateRequest(privacyOrgHoldingsSetSchema, req.body);
res.json(await setOrgHoldings(id, holdings));
}));
// ─── Change-of-address events + inventory workflow (issue #2143) ────────────
router.get('/changes', asyncHandler(async (req, res) => {
const { subjectId } = validateRequest(privacyChangeListQuerySchema, req.query);
const events = await listChangeEvents({ subjectId });
if (!isPaginationRequested(req.query)) return res.json(events);
res.json(paginateArray(events, req.query, { defaultLimit: 50, maxLimit: 500 }));
}));
router.post('/changes', asyncHandler(async (req, res) => {
const data = validateRequest(privacyChangeDeclareSchema, req.body);
res.status(201).json(await declareChange(data));
}));
router.get('/changes/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyChangeIdParamsSchema, req.params);
res.json(await getChange(id));
}));
router.post('/changes/:id/orgs/:orgId/updated', asyncHandler(async (req, res) => {
const { id, orgId } = validateRequest(privacyChangeOrgParamsSchema, req.params);
res.json(await markOrgUpdated(id, orgId));
}));
router.post('/changes/:id/orgs/:orgId/removed', asyncHandler(async (req, res) => {
const { id, orgId } = validateRequest(privacyChangeOrgParamsSchema, req.params);
res.json(await markOrgRemoved(id, orgId));
}));
router.post('/changes/:id/orgs/:orgId/draft-email', asyncHandler(async (req, res) => {
const { id, orgId } = validateRequest(privacyChangeOrgParamsSchema, req.params);
res.status(201).json(await draftUpdateEmail(id, orgId));
}));
// ─── Data-broker database + exposure scan + case ledger (issue #2144) ───────
router.get('/brokers', asyncHandler(async (req, res) => {
const { enabled } = validateRequest(privacyBrokerListQuerySchema, req.query);
const brokers = await listBrokers({ enabled });
if (!isPaginationRequested(req.query)) return res.json(brokers);
res.json(paginateArray(brokers, req.query, { defaultLimit: 50, maxLimit: 500 }));
}));
// User-triggered refresh (never at boot) — pulls BADBOOL + CA registry, never
// clobbers curated rows.
router.post('/brokers/refresh', asyncHandler(async (req, res) => {
validateRequest(privacyBrokerRefreshSchema, req.body ?? {});
res.json(await refreshBrokers());
}));
// Per-broker enable/disable toggle (Brokers-tab, #2146). A disabled broker is
// skipped by the scan + opt-out passes.
router.put('/brokers/:id', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyBrokerIdParamsSchema, req.params);
const { enabled } = validateRequest(privacyBrokerUpdateSchema, req.body);
res.json(await setBrokerEnabled(id, enabled));
}));
router.get('/broker-cases', asyncHandler(async (req, res) => {
const { state, subjectId } = validateRequest(privacyBrokerCaseListQuerySchema, req.query);
const cases = await listBrokerCases({ state, subjectId });
if (!isPaginationRequested(req.query)) return res.json(cases);
res.json(paginateArray(cases, req.query, { defaultLimit: 50, maxLimit: 500 }));
}));
// Force a case due for recheck NOW (case drawer "Re-check" control, #2146).
router.post('/broker-cases/:id/recheck', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyCaseIdParamsSchema, req.params);
res.json(await forceRecheckCase(id));
}));
// Sealed identity evidence (#8333): the case list projects only a summary; the
// case drawer reveals the matched name/location + search/listing URLs through
// this explicit action, and can erase them outright.
router.get('/broker-cases/:id/evidence', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyCaseIdParamsSchema, req.params);
res.json(await revealCaseEvidence(id));
}));
router.delete('/broker-cases/:id/evidence', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyCaseIdParamsSchema, req.params);
res.json(await clearCaseIdentityEvidence(id));
}));
// Manual case transition (digest done/dismiss, case-drawer controls, #2146).
// Only human-reachable targets are accepted (schema); the service's state
// machine enforces validity of the specific from→to move on top of that.
router.post('/broker-cases/:id/transition', asyncHandler(async (req, res) => {
const { id } = validateRequest(privacyCaseIdParamsSchema, req.params);
const { toState, reason } = validateRequest(privacyCaseTransitionSchema, req.body);
res.json(await transitionCase(id, toState, reason === undefined ? {} : { reason }));
}));
router.get('/scan/status', asyncHandler(async (req, res) => {
const { subjectId } = validateRequest(privacySubjectScopeQuerySchema, req.query);
res.json(await getScanStatus({ subjectId }));
}));
// User-triggered read-only exposure scan pass over enabled brokers.
router.post('/scan', asyncHandler(async (req, res) => {
const { concurrency, subjectId } = validateRequest(privacyScanStartSchema, req.body ?? {});
res.json(await runScanPass({ ...(concurrency ? { concurrency } : {}), subjectId }));
}));
// ─── Opt-out automation engine (issue #2145) ───────────────────────────────
// User-triggered opt-out pass: submit found/indirect cases via the chosen lane
// (web-form / email), poll verifications. Email drafts are prepared (and
// pre-approved when settings.privacy.recheck.autoApproveOptOutEmails is on,
// default OFF) for the human to send; web forms are queued as human tasks.
router.post('/optout', asyncHandler(async (req, res) => {
const { runVerification, subjectId } = validateRequest(privacyOptOutPassSchema, req.body ?? {});
res.json(await runOptOutPass({
...(runVerification === undefined ? {} : { runVerification }),
subjectId,
}));
}));
// User-triggered verification-only pass (inbox confirmation scan + removal re-scan).
router.post('/optout/verify', asyncHandler(async (req, res) => {
const { subjectId } = validateRequest(privacyOptOutVerifySchema, req.body ?? {});
res.json(await runVerificationPass({ subjectId }));
}));
// Human-task digest: cases that need a person (blocked walls, auto-submit-off
// forms, fax/phone/gov-ID channels) with the prepared request + playbook.
router.get('/optout/digest', asyncHandler(async (req, res) => {
const { subjectId } = validateRequest(privacySubjectScopeQuerySchema, req.query);
res.json(await getOptOutDigest({ subjectId }));
}));
// Recheck-schedule status: enabled, cron, autonomy toggles, next fire time.
router.get('/optout/schedule', asyncHandler(async (_req, res) => {
res.json(await getPrivacyRecheckStatus());
}));
// Enable/disable the recheck cron + autonomy toggles (Brokers-tab run controls,
// #2146). Deep-merges the `privacy.recheck` settings slice, then restarts the
// scheduler so the change takes effect immediately (the cron expression is
// locked in at registration). Enabling creates the cron; disabling removes it.
router.put('/optout/schedule', asyncHandler(async (req, res) => {
// lastRunAt/enabledAt are server-stamped; a client can't set them here.
const { lastRunAt: _lastRunAt, enabledAt: _enabledAt, ...patch } = validateRequest(privacyRecheckConfigSchema, req.body ?? {});
await updateSettingsWith((current) => {
const existing = current.privacy?.recheck || {};
const turningOn = patch.enabled === true && existing.enabled !== true;
return {
...current,
privacy: {
...(current.privacy || {}),
recheck: { ...existing, ...patch, ...(turningOn && { enabledAt: new Date().toISOString() }) },
},
};
});
await restartPrivacyRecheckScheduler();
res.json(await getPrivacyRecheckStatus());
}));
export default router;