@openlup/platform 0.15.0 → 0.17.0

package/dist/identity/postgresOperatorIdentity.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { createPostgresRoleFreeTransactionLane } from "../data/index.js";
+import { acceptDirectOperatorInvitationInTransaction } from "./directOperatorInvitationStore.js";
+import { operatorChallengeRequestSchema } from "./contracts/operatorAuth.js";
+const fingerprint = (email) => createHash("sha256").update(email.trim().toLowerCase()).digest("hex");
+const allowed = (role) => role === "admin" || role === "distributor";
+/** Dedicated owner lane: no actor gateway, customer writes or machine grants. */
+export function createPostgresOperatorIdentityStore(env) {
+    const lane = createPostgresRoleFreeTransactionLane(env);
+    const run = (work) => lane.run(db => work(db));
+    async function safeStore(db) {
+        // Includes privileges inherited via memberships/default ACLs, not just explicit grants.
+        const unsafe = (await db.query(`SELECT EXISTS (
+      SELECT 1 FROM pg_roles r WHERE r.rolname IN ('anon', 'authenticated', 'authenticator')
+      AND (has_table_privilege(r.oid, 'public.operator_identity_challenges', 'SELECT,INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER')
+        OR has_any_column_privilege(r.oid, 'public.operator_identity_challenges', 'SELECT,INSERT,UPDATE,REFERENCES'))
+    ) OR EXISTS (SELECT 1 FROM pg_class c, LATERAL aclexplode(coalesce(c.relacl, acldefault('r', c.relowner))) a
+      WHERE c.oid = 'public.operator_identity_challenges'::regclass AND a.grantee = 0)
+      OR EXISTS (SELECT 1 FROM pg_attribute c, LATERAL aclexplode(c.attacl) a
+      WHERE c.attrelid = 'public.operator_identity_challenges'::regclass AND a.grantee = 0) AS unsafe`)).rows[0]?.unsafe;
+        if (unsafe !== false)
+            throw new Error("operator_challenge_store_privileges_unsafe");
+    }
+    async function lockPrincipal(db, email) {
+        // Same serialization key as the invitation lifecycle, before row locks.
+        await db.query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)", [`operator_invitation:${email}`]);
+        const matches = (await db.query("SELECT principal_id, email FROM public.platform_human_principals WHERE lower(btrim(email)) = $1 FOR UPDATE", [email])).rows;
+        if (matches.length > 1)
+            throw new Error("operator_normalized_email_conflict");
+        return matches[0] ?? null;
+    }
+    async function eligible(db, id, email) {
+        if ((await db.query("SELECT 1 FROM public.platform_control_operators WHERE principal_id = $1", [id])).rows.length)
+            return false;
+        const member = (await db.query("SELECT role, membership_state FROM public.platform_human_memberships WHERE principal_id = $1 FOR UPDATE", [id])).rows[0];
+        if (member?.membership_state === "active")
+            return allowed(member.role);
+        const pending = (await db.query(`SELECT role FROM public.identity_operator_invitations WHERE principal_id = $1
+      AND email_key = $2 AND phase = 'invited' AND accepted_at IS NULL AND closed_at IS NULL
+      AND expires_at > clock_timestamp() FOR UPDATE`, [id, email])).rows[0];
+        return !!pending && allowed(pending.role);
+    }
+    return {
+        issue({ email, tokenHash }) {
+            return run(async (db) => {
+                await safeStore(db);
+                const principal = await lockPrincipal(db, email);
+                if (!principal || !await eligible(db, String(principal.principal_id), email))
+                    return { deliverable: false };
+                const stamp = (await db.query("SELECT clock_timestamp() AS at")).rows[0].at;
+                const counts = (await db.query(`SELECT count(*) AS hour_count,
+          count(*) FILTER (WHERE created_at > $2::timestamptz - interval '60 seconds') AS minute_count
+          FROM public.operator_identity_challenges WHERE principal_id = $1 AND created_at > $2::timestamptz - interval '1 hour'`, [principal.principal_id, stamp])).rows[0];
+                if (Number(counts.minute_count) >= 1 || Number(counts.hour_count) >= 5)
+                    return { deliverable: false };
+                const row = (await db.query(`INSERT INTO public.operator_identity_challenges
+          (principal_id, email_fingerprint, token_hash, created_at, expires_at)
+          VALUES ($1, $2, $3, $4, $4::timestamptz + interval '10 minutes') RETURNING expires_at`, [principal.principal_id, fingerprint(email), tokenHash, stamp])).rows[0];
+                return { deliverable: true, email: String(principal.email).trim().toLowerCase(), expiresAt: new Date(String(row.expires_at)).toISOString() };
+            });
+        },
+        redeem({ tokenHash }) {
+            return run(async (db) => {
+                await safeStore(db);
+                const candidate = (await db.query(`SELECT p.email, p.principal_id FROM public.operator_identity_challenges c
+          JOIN public.platform_human_principals p USING (principal_id) WHERE c.token_hash = $1`, [tokenHash])).rows[0];
+                if (!candidate)
+                    return null;
+                const email = String(candidate.email).trim().toLowerCase();
+                const principal = await lockPrincipal(db, email);
+                if (!principal || principal.principal_id !== candidate.principal_id || !await eligible(db, String(principal.principal_id), email))
+                    return null;
+                const challenge = (await db.query(`SELECT * FROM public.operator_identity_challenges WHERE token_hash = $1
+          AND principal_id = $2 AND used_at IS NULL AND expires_at > clock_timestamp() FOR UPDATE`, [tokenHash, principal.principal_id])).rows[0];
+                if (!challenge || challenge.email_fingerprint !== fingerprint(email))
+                    return null;
+                const accepted = await acceptDirectOperatorInvitationInTransaction(db, String(principal.principal_id));
+                if ((accepted.code !== "ACTIVATED" && accepted.code !== "ALREADY_ACTIVE") || !allowed(accepted.role))
+                    return null;
+                const consumed = await db.query(`WITH stamp AS (SELECT clock_timestamp() AS at)
+          UPDATE public.operator_identity_challenges SET used_at = stamp.at FROM stamp
+          WHERE id = $1 AND used_at IS NULL AND expires_at > stamp.at RETURNING id`, [challenge.id]);
+                // Throw to roll activation back if the challenge expired during activation.
+                if (!consumed.rows.length)
+                    throw new Error("operator_challenge_expired_during_activation");
+                return { principalId: String(principal.principal_id), email };
+            }).catch(error => {
+                if (error instanceof Error && error.message === "operator_challenge_expired_during_activation")
+                    return null;
+                throw error;
+            });
+        },
+        findMembership(id) {
+            return run(async (db) => {
+                await safeStore(db);
+                const row = (await db.query(`SELECT p.principal_id, p.email, m.role, m.membership_state
+          FROM public.platform_human_principals p JOIN public.platform_human_memberships m USING (principal_id)
+          WHERE p.principal_id = $1 AND NOT EXISTS (SELECT 1 FROM public.platform_control_operators o WHERE o.principal_id = p.principal_id)`, [id])).rows[0];
+                return row ? { principalId: String(row.principal_id), email: String(row.email), role: row.role, membershipState: String(row.membership_state) } : null;
+            });
+        },
+        bootstrapFirstAdministrator(input) {
+            const { email } = operatorChallengeRequestSchema.parse(input);
+            return run(async (db) => {
+                await safeStore(db);
+                await db.query("LOCK TABLE public.platform_human_memberships, public.identity_operator_invitations IN SHARE ROW EXCLUSIVE MODE");
+                if ((await db.query(`SELECT 1 FROM public.platform_human_memberships UNION ALL SELECT 1 FROM public.identity_operator_invitations LIMIT 1`)).rows.length)
+                    throw new Error("OPERATOR_BOOTSTRAP_ALREADY_INITIALIZED");
+                let principal = await lockPrincipal(db, email);
+                if (!principal)
+                    principal = (await db.query("INSERT INTO public.platform_human_principals (principal_id, email) VALUES (gen_random_uuid(), $1) RETURNING principal_id, email", [email])).rows[0];
+                const id = String(principal.principal_id);
+                if ((await db.query("SELECT 1 FROM public.platform_control_operators WHERE principal_id = $1", [id])).rows.length)
+                    throw new Error("operator_bootstrap_machine_refused");
+                const pending = (await db.query(`WITH stamp AS (SELECT clock_timestamp() AS at)
+          INSERT INTO public.identity_operator_invitations
+          (principal_id, invitation_id, email_key, role, phase, invited_by, invited_at, expires_at)
+          SELECT $1, gen_random_uuid(), $2, 'admin', 'invited', $1, at, at + interval '7 days' FROM stamp RETURNING *`, [id, email])).rows[0];
+                await db.query(`INSERT INTO public.identity_operator_invitation_events
+          (event_id, invitation_id, principal_id, action, actor_kind, old_value, new_value, occurred_at)
+          VALUES (gen_random_uuid(), $1, $2, 'issue', 'system', '{}'::jsonb, $3::jsonb, clock_timestamp())`, [pending.invitation_id, id, JSON.stringify(pending)]);
+                return { principalId: id, membershipState: "invited" };
+            });
+        },
+        pruneChallenges({ limit }) {
+            if (!Number.isInteger(limit) || limit < 1 || limit > 500)
+                throw new Error("operator_prune_limit_invalid");
+            return run(async (db) => {
+                const deleted = await db.query(`WITH batch AS (SELECT id FROM public.operator_identity_challenges
+          WHERE expires_at < clock_timestamp() - interval '24 hours' ORDER BY expires_at, id LIMIT $1 FOR UPDATE SKIP LOCKED)
+          DELETE FROM public.operator_identity_challenges c USING batch WHERE c.id = batch.id RETURNING c.id`, [limit]);
+                return { deleted: deleted.rows.length };
+            });
+        },
+        close: lane.close,
+    };
+}

package/dist/identity/postgresPrivacy.d.ts

@@ -0,0 +1,7 @@
+import { type PgQueryExecutor, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+import { type PrivacyStore } from "./privacyPorts.js";
+export declare function createPostgresPrivacyStore(): PrivacyStore<PgQueryExecutor>;
+export declare function createPostgresPrivacyUnitOfWork(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): {
+    run: <T>(work: (context: PgQueryExecutor) => Promise<T>) => Promise<T>;
+    close: () => Promise<void>;
+};

package/dist/identity/postgresPrivacy.js

@@ -0,0 +1,126 @@
+import { createPostgresRoleFreeTransactionLane } from "../data/index.js";
+import { PrivacyRefusal } from "./privacyPorts.js";
+import { erasureReceiptSchema } from "./contracts/privacy.js";
+function json(value) { return JSON.parse(JSON.stringify(value)); }
+export function createPostgresPrivacyStore() {
+    return {
+        erasureSupported: true,
+        async prepareErasure(db) {
+            await db.query("SET LOCAL lock_timeout = '5s'");
+            await db.query("SET LOCAL statement_timeout = '15s'");
+            // Serialize receipt/key decisions; challenge relation precedes every contact lock.
+            await db.query("LOCK TABLE public.identity_privacy_erasures IN SHARE ROW EXCLUSIVE MODE");
+            const unsafe = (await db.query(`SELECT EXISTS (
+        SELECT 1 FROM pg_roles r WHERE r.rolname IN ('anon', 'authenticated', 'authenticator')
+        AND (has_table_privilege(r.oid, 'public.identity_privacy_erasures', 'SELECT,INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER')
+          OR has_any_column_privilege(r.oid, 'public.identity_privacy_erasures', 'SELECT,INSERT,UPDATE,REFERENCES'))
+      ) OR EXISTS (SELECT 1 FROM pg_class c, LATERAL aclexplode(coalesce(c.relacl, acldefault('r', c.relowner))) a
+        WHERE c.oid = 'public.identity_privacy_erasures'::regclass AND a.grantee = 0)
+        OR EXISTS (SELECT 1 FROM pg_attribute c, LATERAL aclexplode(c.attacl) a
+        WHERE c.attrelid = 'public.identity_privacy_erasures'::regclass AND a.grantee = 0) AS unsafe`)).rows[0]?.unsafe;
+            if (unsafe !== false)
+                throw new PrivacyRefusal("PRIVACY_STORE_PRIVILEGES_UNSAFE");
+            await db.query("LOCK TABLE public.customer_identity_challenges IN EXCLUSIVE MODE");
+        },
+        async authorizeErasure(db, actor) {
+            const row = (await db.query(`SELECT m.role, m.membership_state FROM public.platform_human_memberships m
+        WHERE m.principal_id = $1 AND NOT EXISTS (SELECT 1 FROM public.platform_control_operators o WHERE o.principal_id = m.principal_id)`, [actor.principalId])).rows[0];
+            if (row?.role !== "admin" || row.membership_state !== "active")
+                throw new PrivacyRefusal("PRIVACY_PROTECTED_OPERATOR");
+        },
+        async resolve(db, ref, actor) {
+            const contactPredicate = ref.kind === "contact" ? "c.id = $1" : "c.principal_id = $1";
+            const id = ref.kind === "contact" ? ref.contactId : ref.principalId;
+            let contact = (await db.query(`SELECT c.* FROM public.clients c WHERE ${contactPredicate}`, [id])).rows[0] ?? null;
+            if (ref.kind === "principal" && !contact) {
+                const receipt = (await db.query("SELECT client_id FROM public.identity_privacy_erasures WHERE principal_id = $1", [id])).rows[0];
+                if (receipt?.client_id)
+                    contact = (await db.query("SELECT * FROM public.clients WHERE id = $1", [receipt.client_id])).rows[0] ?? null;
+            }
+            let principalId = ref.kind === "principal" ? ref.principalId : contact?.principal_id ? String(contact.principal_id) : null;
+            if (!principalId && contact) {
+                const receipt = (await db.query("SELECT principal_id FROM public.identity_privacy_erasures WHERE client_id = $1", [contact.id])).rows[0];
+                if (receipt?.principal_id)
+                    principalId = String(receipt.principal_id);
+            }
+            let principal = principalId ? (await db.query("SELECT principal_id, email, created_at FROM public.platform_human_principals WHERE principal_id = $1", [principalId])).rows[0] ?? null : null;
+            if (!contact && !principal)
+                return null;
+            if (actor) {
+                if (principal) {
+                    await db.query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)", [`operator_invitation:${String(principal.email).trim().toLowerCase()}`]);
+                }
+                await db.query("SELECT principal_id FROM public.platform_human_memberships WHERE principal_id = ANY($1::uuid[]) ORDER BY principal_id FOR UPDATE", [[actor.principalId, principalId].filter(Boolean)]);
+                if (contact)
+                    contact = (await db.query("SELECT * FROM public.clients WHERE id = $1 FOR UPDATE", [contact.id])).rows[0] ?? null;
+                if (principal)
+                    principal = (await db.query("SELECT principal_id, email, created_at FROM public.platform_human_principals WHERE principal_id = $1 FOR UPDATE", [principalId])).rows[0] ?? null;
+            }
+            const membership = principalId ? (await db.query("SELECT * FROM public.platform_human_memberships WHERE principal_id = $1", [principalId])).rows[0] ?? null : null;
+            const invitations = principalId ? (await db.query("SELECT * FROM public.identity_operator_invitations WHERE principal_id = $1", [principalId])).rows : [];
+            const invitationHistory = principalId ? (await db.query("SELECT * FROM public.identity_operator_invitation_events WHERE principal_id = $1 ORDER BY occurred_at, event_id", [principalId])).rows : [];
+            const membershipHistory = principalId ? (await db.query("SELECT * FROM public.platform_human_membership_audit_events WHERE target_principal_id = $1 ORDER BY occurred_at, id", [principalId])).rows : [];
+            return { contactId: contact ? String(contact.id) : null, principalId,
+                identity: { contact: json(contact), principal: json(principal), membership: json(membership), invitations: json(invitations), invitationHistory: json(invitationHistory), membershipHistory: json(membershipHistory) } };
+        },
+        async findReceipt(db, ref, key) {
+            const column = ref.kind === "contact" ? "client_id" : "principal_id";
+            const id = ref.kind === "contact" ? ref.contactId : ref.principalId;
+            const rows = (await db.query(`SELECT * FROM public.identity_privacy_erasures WHERE ${column} = $1 OR idempotency_key = $2::uuid`, [id, key ?? null])).rows;
+            if (rows.some(row => row.idempotency_key === key && row[column] !== id))
+                throw new PrivacyRefusal("PRIVACY_IDEMPOTENCY_CONFLICT");
+            const row = rows.find(row => row[column] === id);
+            return row ? erasureReceiptSchema.parse({ version: row.contract_version, erasureId: row.erasure_id, completedAt: row.completed_at instanceof Date ? row.completed_at.toISOString() : new Date(String(row.completed_at)).toISOString(), outcome: "ERASED", obligations: row.retained_obligations }) : null;
+        },
+        async eraseIdentity(db, subject, actor, pseudonym) {
+            await erasePostgresIdentity(db, subject, actor, pseudonym);
+        },
+        async saveReceipt(db, subject, actor, key, receipt, dispositions) {
+            await db.query(`INSERT INTO public.identity_privacy_erasures
+        (erasure_id, idempotency_key, client_id, principal_id, actor_principal_id, contract_version, contributor_versions, dispositions, retained_obligations, completed_at)
+        VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,$8::jsonb,$9::jsonb,$10::timestamptz)`, [receipt.erasureId, key, subject.contactId, subject.principalId, actor.principalId, receipt.version,
+                JSON.stringify(Object.fromEntries(dispositions.map(d => [d.contributorId, d.version]))), JSON.stringify(dispositions), JSON.stringify(receipt.obligations), receipt.completedAt]);
+        },
+    };
+}
+async function erasePostgresIdentity(db, subject, actor, pseudonym) {
+    const id = subject.principalId;
+    if (id) {
+        if (id === actor.principalId || (await db.query("SELECT 1 FROM public.platform_control_operators WHERE principal_id = $1", [id])).rows.length)
+            throw new PrivacyRefusal("PRIVACY_PROTECTED_OPERATOR");
+        const member = subject.identity.membership;
+        if (member?.membership_state === "active") {
+            try {
+                await db.query("SELECT public.platform_revoke_human_membership($1, $2, $3)", [actor.principalId, id, "identity erasure"]);
+            }
+            catch (error) {
+                if (error && typeof error === "object" && "code" in error && ["P0001", "42501"].includes(String(error.code)))
+                    throw new PrivacyRefusal("PRIVACY_PROTECTED_OPERATOR");
+                throw error;
+            }
+        }
+        await db.query("DELETE FROM public.operator_identity_challenges WHERE principal_id = $1", [id]);
+        await db.query("DELETE FROM public.identity_operator_invitations WHERE principal_id = $1 AND phase <> 'accepted'", [id]);
+        await db.query("UPDATE public.identity_operator_invitations SET email_key = $2 WHERE principal_id = $1", [id, pseudonym]);
+        // Rebuild historical identity snapshots from lifecycle fields, never a recursive string replacement.
+        await db.query(`UPDATE public.identity_operator_invitation_events SET
+      old_value = old_value - 'email_key', new_value = new_value - 'email_key' WHERE principal_id = $1`, [id]);
+        await db.query(`UPDATE public.platform_human_membership_audit_events SET reason = NULL,
+      old_value = old_value - 'revocationReason', new_value = new_value - 'revocationReason' WHERE target_principal_id = $1`, [id]);
+        // The existing lifecycle guard also protects free-text redaction on a revoked row.
+        const previous = (await db.query("SELECT current_setting('app.platform_human_membership_revoke', true) AS previous")).rows[0]?.previous;
+        await db.query("SELECT set_config('app.platform_human_membership_revoke', 'true', true)");
+        await db.query("UPDATE public.platform_human_memberships SET membership_revocation_reason = NULL WHERE principal_id = $1 AND membership_state = 'revoked'", [id]);
+        await db.query("SELECT set_config('app.platform_human_membership_revoke', $1, true)", [previous ?? ""]);
+        await db.query("UPDATE public.platform_human_principals SET email = $2 WHERE principal_id = $1", [id, pseudonym]);
+    }
+    if (subject.contactId) {
+        await db.query("DELETE FROM public.customer_identity_challenges WHERE client_id = $1", [subject.contactId]);
+        await db.query(`UPDATE public.clients SET email = $2, first_name = NULL, last_name = NULL, phone = NULL,
+      country = NULL, principal_id = NULL, updated_at = clock_timestamp() WHERE id = $1`, [subject.contactId, pseudonym]);
+    }
+}
+export function createPostgresPrivacyUnitOfWork(env, options = {}) {
+    const lane = createPostgresRoleFreeTransactionLane(env, options);
+    return { run: (work) => lane.run(db => work(db)), close: lane.close };
+}

package/dist/identity/privacyHandlers.d.ts

@@ -0,0 +1,10 @@
+import type { HttpHandler } from "../http/index.js";
+import type { AdminAuthorizationResult } from "./ports.js";
+import { type IdentityResponseOptions } from "./response.js";
+import { type PrivacyOperations } from "./privacyPorts.js";
+export interface PrivacyHandlerDependencies extends IdentityResponseOptions {
+    authorizeAdmin: () => Promise<AdminAuthorizationResult>;
+    operations: PrivacyOperations;
+}
+export declare const createPrivacyExportHandler: (deps: PrivacyHandlerDependencies) => HttpHandler;
+export declare const createPrivacyEraseHandler: (deps: PrivacyHandlerDependencies) => HttpHandler;

package/dist/identity/privacyHandlers.js

@@ -0,0 +1,35 @@
+import { createIdentityResponder } from "./response.js";
+import { privacyExportRequestSchema, privacyEraseRequestSchema, privacyExportResponseSchema, privacyEraseResponseSchema } from "./contracts/privacy.js";
+import { PrivacyRefusal } from "./privacyPorts.js";
+function handler(deps, erase) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(deps);
+    return async (req, res) => {
+        res.setHeader("Cache-Control", "no-store");
+        if (req.method !== "POST")
+            return sendMethodNotAllowed(res, ["POST"]);
+        try {
+            const auth = await deps.authorizeAdmin();
+            if (!auth.ok)
+                return sendBffError(res, auth.code, auth.message);
+            if (auth.role !== "admin" || auth.isMachineActor !== false)
+                return sendBffError(res, "FORBIDDEN", "Human administrator required");
+            const parsed = (erase ? privacyEraseRequestSchema : privacyExportRequestSchema).safeParse(req.body);
+            if (!parsed.success)
+                return sendBffError(res, "BAD_REQUEST", "Invalid privacy request");
+            const actor = { principalId: auth.principalId };
+            const result = erase ? privacyEraseResponseSchema.parse(await deps.operations.erase(actor, privacyEraseRequestSchema.parse(parsed.data)))
+                : privacyExportResponseSchema.parse(await deps.operations.export(actor, parsed.data.subject));
+            return sendBffSuccess(res, result);
+        }
+        catch (error) {
+            if (error instanceof PrivacyRefusal) {
+                const code = error.code === "PRIVACY_SUBJECT_NOT_FOUND" ? "NOT_FOUND"
+                    : ["PRIVACY_ACTIVE_SUBSCRIPTION", "PRIVACY_RESUMABLE_SUBSCRIPTION", "PRIVACY_PROTECTED_OPERATOR", "PRIVACY_IDEMPOTENCY_CONFLICT", "PRIVACY_SUBJECT_ERASED"].includes(error.code) ? "CONFLICT" : "UPSTREAM_UNAVAILABLE";
+                return sendBffError(res, code, "Privacy operation refused", { details: { privacyCode: error.code } });
+            }
+            return sendBffError(res, "UPSTREAM_UNAVAILABLE", "Privacy operation unavailable", { details: { privacyCode: "PRIVACY_ASSESSMENT_UNAVAILABLE" } });
+        }
+    };
+}
+export const createPrivacyExportHandler = (deps) => handler(deps, false);
+export const createPrivacyEraseHandler = (deps) => handler(deps, true);

package/dist/identity/privacyPorts.d.ts

@@ -0,0 +1,72 @@
+import type { PrivacySubjectRef, PrivacyExport, ErasureReceipt, PersonalDataDocument, PersonalDataObligation, PrivacyJson, PrivacyRefusalCode } from "./contracts/privacy.js";
+export declare class PrivacyRefusal extends Error {
+    readonly code: PrivacyRefusalCode;
+    constructor(code: PrivacyRefusalCode);
+}
+export interface AuthorizedHumanAdministrator {
+    principalId: string;
+}
+export interface ResolvedPrivacySubject {
+    contactId: string | null;
+    principalId: string | null;
+    /** Only explicitly selected identity fields; never credentials. */
+    identity: {
+        [key: string]: PrivacyJson;
+    };
+}
+export interface ErasureAssessment {
+    obligations: PersonalDataObligation[];
+}
+export interface ContributorDisposition {
+    contributorId: string;
+    version: string;
+    obligations: PersonalDataObligation[];
+}
+export interface PersonalDataContributor<Context> {
+    readonly id: string;
+    readonly version: string;
+    readonly ownedResources: readonly string[];
+    prepareErasure(context: Context): Promise<void>;
+    export(context: Context, subject: ResolvedPrivacySubject): Promise<PersonalDataDocument>;
+    assessErasure(context: Context, subject: ResolvedPrivacySubject): Promise<ErasureAssessment>;
+    eraseOrRetain(context: Context, subject: ResolvedPrivacySubject, assessment: ErasureAssessment, actor: AuthorizedHumanAdministrator): Promise<ContributorDisposition>;
+}
+export interface PersonalDataContributorRegistry<Context> {
+    readonly contributors: readonly PersonalDataContributor<Context>[];
+    readonly missingContributors: readonly string[];
+}
+export interface PrivacyUnitOfWork<Context> {
+    run<T>(work: (context: Context) => Promise<T>): Promise<T>;
+}
+export interface PrivacyStore<Context> {
+    readonly erasureSupported: boolean;
+    prepareErasure(context: Context): Promise<void>;
+    authorizeErasure(context: Context, actor: AuthorizedHumanAdministrator): Promise<void>;
+    resolve(context: Context, subject: PrivacySubjectRef, actor?: AuthorizedHumanAdministrator): Promise<ResolvedPrivacySubject | null>;
+    findReceipt(context: Context, subject: PrivacySubjectRef, key?: string): Promise<ErasureReceipt | null>;
+    eraseIdentity(context: Context, subject: ResolvedPrivacySubject, actor: AuthorizedHumanAdministrator, pseudonym: string): Promise<void>;
+    saveReceipt(context: Context, subject: ResolvedPrivacySubject, actor: AuthorizedHumanAdministrator, key: string, receipt: ErasureReceipt, dispositions: ContributorDisposition[]): Promise<void>;
+}
+export interface PrivacyUseCaseDependencies<Context> {
+    unitOfWork: PrivacyUnitOfWork<Context>;
+    registry: PersonalDataContributorRegistry<Context>;
+    store: PrivacyStore<Context>;
+    now(): Date;
+    randomId(): string;
+}
+export interface PrivacyOperations {
+    export(actor: AuthorizedHumanAdministrator, subject: PrivacySubjectRef): Promise<PrivacyExport>;
+    erase(actor: AuthorizedHumanAdministrator, input: {
+        subject: PrivacySubjectRef;
+        idempotencyKey: string;
+    }): Promise<ErasureReceipt>;
+}
+/** A host may compose this only after a committed local erasure; never delete an identity. */
+export interface ProviderIdentityErasurePort {
+    disableIdentity(input: {
+        principalId: string;
+        committedErasureId: string;
+    }): Promise<{
+        status: "disabled" | "already_disabled";
+    }>;
+}

package/dist/identity/privacyPorts.js

@@ -0,0 +1,8 @@
+export class PrivacyRefusal extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "PrivacyRefusal";
+    }
+}

package/dist/identity/privacyUseCases.d.ts

@@ -0,0 +1,5 @@
+import { type PrivacyUseCaseDependencies, type AuthorizedHumanAdministrator, type PrivacyOperations } from "./privacyPorts.js";
+import type { PrivacySubjectRef, PrivacyEraseRequest, PrivacyExport, ErasureReceipt } from "./contracts/privacy.js";
+export declare function exportPersonalData<C>(deps: PrivacyUseCaseDependencies<C>, actor: AuthorizedHumanAdministrator, input: PrivacySubjectRef): Promise<PrivacyExport>;
+export declare function erasePersonalData<C>(deps: PrivacyUseCaseDependencies<C>, actor: AuthorizedHumanAdministrator, request: PrivacyEraseRequest): Promise<ErasureReceipt>;
+export declare function createPrivacyOperations<C>(deps: PrivacyUseCaseDependencies<C>): PrivacyOperations;

package/dist/identity/privacyUseCases.js

@@ -0,0 +1,55 @@
+import { privacyExportResponseSchema, erasureReceiptSchema, privacySubjectSchema, privacyEraseRequestSchema } from "./contracts/privacy.js";
+import { PrivacyRefusal } from "./privacyPorts.js";
+export async function exportPersonalData(deps, actor, input) {
+    const subject = privacySubjectSchema.parse(input);
+    return deps.unitOfWork.run(async (context) => {
+        const resolved = await deps.store.resolve(context, subject);
+        if (!resolved)
+            throw new PrivacyRefusal("PRIVACY_SUBJECT_NOT_FOUND");
+        const documents = [];
+        for (const contributor of deps.registry.contributors) {
+            const document = await contributor.export(context, resolved);
+            if (document.contributorId !== contributor.id || document.version !== contributor.version)
+                throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+            documents.push(document);
+        }
+        return privacyExportResponseSchema.parse({ format: "personal-data.v1", generatedAt: deps.now().toISOString(), subject, documents, missingContributors: [...deps.registry.missingContributors], erasure: await deps.store.findReceipt(context, subject) });
+    });
+}
+export async function erasePersonalData(deps, actor, request) {
+    const input = privacyEraseRequestSchema.parse(request);
+    // Capability refusal precedes even opening a managed transaction or provider request.
+    if (!deps.store.erasureSupported)
+        throw new PrivacyRefusal("MANAGED_PRIVACY_ERASURE_UNAVAILABLE");
+    if (deps.registry.missingContributors.length || !deps.registry.contributors.some(c => c.id === "identity"))
+        throw new PrivacyRefusal("PRIVACY_CONTRIBUTOR_MISSING");
+    return deps.unitOfWork.run(async (context) => {
+        await deps.store.prepareErasure(context);
+        // Domain relation locks precede subject/member row locks and remain held to commit.
+        for (const contributor of deps.registry.contributors)
+            await contributor.prepareErasure(context);
+        const resolved = await deps.store.resolve(context, input.subject, actor);
+        await deps.store.authorizeErasure(context, actor);
+        const previous = await deps.store.findReceipt(context, input.subject, input.idempotencyKey);
+        if (previous)
+            return erasureReceiptSchema.parse({ ...previous, outcome: "ALREADY_ERASED" });
+        if (!resolved)
+            throw new PrivacyRefusal("PRIVACY_SUBJECT_NOT_FOUND");
+        const assessments = [];
+        for (const contributor of deps.registry.contributors) {
+            const assessment = await contributor.assessErasure(context, resolved);
+            if (assessment.obligations.some(o => o.disposition === "unresolved"))
+                throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+            assessments.push(assessment);
+        }
+        const dispositions = [];
+        for (let i = 0; i < deps.registry.contributors.length; i++)
+            dispositions.push(await deps.registry.contributors[i].eraseOrRetain(context, resolved, assessments[i], actor));
+        const receipt = erasureReceiptSchema.parse({ version: "identity.erasure.v1", erasureId: deps.randomId(), completedAt: deps.now().toISOString(), outcome: "ERASED", obligations: dispositions.flatMap(d => d.obligations) });
+        await deps.store.saveReceipt(context, resolved, actor, input.idempotencyKey, receipt, dispositions);
+        return receipt;
+    });
+}
+export function createPrivacyOperations(deps) {
+    return { export: (actor, subject) => exportPersonalData(deps, actor, subject), erase: (actor, input) => erasePersonalData(deps, actor, input) };
+}

package/dist/identity/reconcileAccountForPrincipal.d.ts

@@ -0,0 +1,20 @@
+import { type EmailTrustPolicy } from "./emailTrustPolicy.js";
+import type { EmailTrustFailureCode } from "./contracts/emailTrust.js";
+import type { AccountLinkStore } from "./ports.js";
+export interface ReconcileAccountInput {
+    principalId: string;
+    email: string | null;
+    emailVerified: boolean;
+}
+export type ReconcileAccountErrorCode = EmailTrustFailureCode | "NO_VERIFIED_EMAIL" | "RESERVED_PRINCIPAL_REFUSED" | "PRINCIPAL_EMAIL_MISMATCH" | "ACCOUNT_LINK_CONFLICT" | "EMAIL_OWNED_BY_OTHER_PRINCIPAL";
+export type ReconcileAccountResult = {
+    ok: true;
+    accountId: string;
+    created: boolean;
+    linked: boolean;
+} | {
+    ok: false;
+    code: ReconcileAccountErrorCode;
+    existingPrincipalId?: string | null;
+};
+export declare function reconcileAccountForPrincipal(store: AccountLinkStore, input: ReconcileAccountInput, emailTrustPolicy: EmailTrustPolicy): Promise<ReconcileAccountResult>;

package/dist/identity/reconcileAccountForPrincipal.js

@@ -0,0 +1,66 @@
+import { assessEmailTrust } from "./emailTrustPolicy.js";
+export async function reconcileAccountForPrincipal(store, input, emailTrustPolicy) {
+    const email = normalizeEmail(input.email);
+    if (!email || !input.emailVerified) {
+        return { ok: false, code: "NO_VERIFIED_EMAIL" };
+    }
+    if (await store.isReservedPrincipal(input.principalId)) {
+        return { ok: false, code: "RESERVED_PRINCIPAL_REFUSED" };
+    }
+    const byPrincipal = await store.findAccountByPrincipalId(input.principalId);
+    if (byPrincipal) {
+        const accountEmail = normalizeEmail(byPrincipal.email);
+        if (accountEmail && accountEmail !== email) {
+            return { ok: false, code: "PRINCIPAL_EMAIL_MISMATCH", existingPrincipalId: input.principalId };
+        }
+        return { ok: true, accountId: byPrincipal.id, created: false, linked: false };
+    }
+    const trust = await assessEmailTrust(emailTrustPolicy);
+    if (!trust.trusted)
+        return { ok: false, code: trust.code };
+    const viaEmail = await resolveByEmail(store, email, input.principalId);
+    if (viaEmail)
+        return viaEmail;
+    try {
+        const created = await store.createAccount({
+            email,
+            principalId: input.principalId,
+            acquisitionSource: "social_signup",
+            lifecycleStage: "lead",
+        });
+        return { ok: true, accountId: created.id, created: true, linked: true };
+    }
+    catch (err) {
+        const retry = await resolveByEmail(store, email, input.principalId);
+        if (retry)
+            return retry;
+        throw err;
+    }
+}
+function normalizeEmail(email) {
+    return (email ?? "").trim().toLowerCase();
+}
+async function resolveByEmail(store, email, principalId) {
+    const account = await store.findAccountByEmail(email);
+    if (!account)
+        return null;
+    if (account.principalId === principalId) {
+        return { ok: true, accountId: account.id, created: false, linked: false };
+    }
+    if (account.principalId !== null) {
+        return {
+            ok: false,
+            code: "EMAIL_OWNED_BY_OTHER_PRINCIPAL",
+            existingPrincipalId: account.principalId,
+        };
+    }
+    const link = await store.linkPrincipalToAccount(account.id, principalId);
+    if (link.ok === true) {
+        return { ok: true, accountId: account.id, created: false, linked: true };
+    }
+    return {
+        ok: false,
+        code: "ACCOUNT_LINK_CONFLICT",
+        existingPrincipalId: link.existingPrincipalId,
+    };
+}

package/dist/identity/reconcileAccountHandler.d.ts

@@ -0,0 +1,11 @@
+import type { EmailTrustPolicy } from "./emailTrustPolicy.js";
+import { type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { AccountLinkStore, IdentityVerifierPort } from "./ports.js";
+import { type ReconcileAccountErrorCode } from "./reconcileAccountForPrincipal.js";
+export declare function createReconcileAccountHandler(options: IdentityResponseOptions & {
+    verifier: IdentityVerifierPort;
+    store: AccountLinkStore;
+    emailTrustPolicy: EmailTrustPolicy;
+    message?: (code: ReconcileAccountErrorCode) => string;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/identity/reconcileAccountHandler.js

@@ -0,0 +1,30 @@
+import { createIdentityResponder } from "./response.js";
+import { reconcileAccountForPrincipal } from "./reconcileAccountForPrincipal.js";
+import { readBearerToken } from "./adminAuthorization.js";
+export function createReconcileAccountHandler(options) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(options);
+    return async (req, res) => {
+        if (req.method !== "POST")
+            return sendMethodNotAllowed(res, ["POST"]);
+        const token = readBearerToken(req);
+        if (!token)
+            return sendBffError(res, "UNAUTHORIZED", "Customer session required");
+        try {
+            const principal = await options.verifier.verifyAccessToken(token);
+            if (!principal)
+                return sendBffError(res, "UNAUTHORIZED", "Customer session required");
+            const result = await reconcileAccountForPrincipal(options.store, principal, options.emailTrustPolicy);
+            if (!result.ok) {
+                const code = result.code === "NO_VERIFIED_EMAIL" ? "BAD_REQUEST"
+                    : result.code === "EMAIL_TRUST_SETTINGS_UNAVAILABLE" ? "UPSTREAM_UNAVAILABLE"
+                        : result.code === "RESERVED_PRINCIPAL_REFUSED" || result.code === "EMAIL_TRUST_ENVELOPE_REFUSED" ? "FORBIDDEN" : "CONFLICT";
+                sendBffError(res, code, options.message?.(result.code) ?? result.code, { details: { code: result.code } });
+                return;
+            }
+            sendBffSuccess(res, { accountId: result.accountId, created: result.created, linked: result.linked });
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Account reconciliation failed");
+        }
+    };
+}

package/dist/identity/removeAdminUserUseCase.d.ts

@@ -0,0 +1,31 @@
+import type { OperatorInvitationStore } from "./operatorInvitationPorts.js";
+import { type IdentityMessages } from "./messages.js";
+export type RemoveAdminUserResponse = {
+    revoked?: true;
+    error?: string;
+    code?: string;
+};
+export interface RemoveAdminUserGateway {
+    getUser: (accessToken: string) => Promise<{
+        user: {
+            id: string;
+        } | null;
+        error: unknown;
+    }>;
+    findAdminUser: (userId: string) => Promise<{
+        id: string;
+        role: string;
+    } | null>;
+    revokeAdminUser: (userId: string) => Promise<{
+        error: {
+            message: string;
+        } | null;
+    }>;
+}
+export declare function runRemoveAdminUserUseCase(request: {
+    accessToken: string | null;
+    userId: string;
+}, gateway: RemoveAdminUserGateway, messages?: IdentityMessages, invitationStore?: Pick<OperatorInvitationStore, "remove">): Promise<{
+    status: number;
+    body: RemoveAdminUserResponse;
+}>;