@openlup/platform 0.15.0 → 0.17.0

package/src/identity/ports.ts

@@ -0,0 +1,158 @@
+import { assessEmailTrust, type EmailTrustPolicy } from "./emailTrustPolicy.js";
+import type { EmailTrustFailureCode } from "./contracts/emailTrust.js";
+
+export interface VerifiedPrincipal {
+  principalId: string;
+  email: string | null;
+  emailVerified: boolean;
+}
+
+
+export interface IdentityVerifierPort {
+  verifyAccessToken(accessToken: string): Promise<VerifiedPrincipal | null>;
+}
+
+export interface CustomerChallengeStore {
+  issue(input: {
+    email: string;
+    tokenHash: string;
+    expiresAt: string;
+  }): Promise<{ deliverable: boolean }>;
+  redeem(input: { tokenHash: string; now: string }): Promise<{
+    principalId: string;
+    email: string;
+  } | null>;
+}
+
+export interface CustomerChallengeDeliveryPort {
+  deliver(input: { email: string; token: string; expiresAt: string }): Promise<void>;
+}
+
+export interface CustomerSessionIssuerPort {
+  issue(input: { principalId: string; email: string }): Promise<{
+    accessToken: string;
+    expiresAt: string;
+  }>;
+}
+
+
+export type LinkClientAuthUserResult =
+  | {
+      ok: true;
+      clientId: string;
+      authUserId: string;
+      created: boolean;
+      alreadyLinked: boolean;
+      adminSelfLink: boolean;
+    }
+  | {
+      ok: false;
+      code: EmailTrustFailureCode | "CLIENT_NOT_FOUND" | "MACHINE_ACTOR_REFUSED" | "CLIENT_AUTH_LINK_CONFLICT";
+      message: string;
+    };
+
+export type SetClientAuthUserIdResult =
+  | { ok: true; alreadyLinked: boolean }
+  | { ok: false; code: "CLIENT_AUTH_LINK_CONFLICT"; existingAuthUserId: string | null };
+
+export interface ClientAuthLinkStore {
+  emailTrustPolicy: EmailTrustPolicy;
+  findClientByEmail(email: string): Promise<{ id: string; authUserId: string | null } | null>;
+  findAuthUserIdByEmail(email: string): Promise<string | null>;
+  findAuthUserEmailById(authUserId: string): Promise<string | null>;
+  /** Provision an unconfirmed principal; null means an existing identity needs lookup. */
+  createAuthUser(email: string): Promise<string | null>;
+  findAdminIdentity(authUserId: string): Promise<{ isMachineActor: boolean } | null>;
+  setClientAuthUserId(clientId: string, authUserId: string): Promise<SetClientAuthUserIdResult>;
+}
+
+/** Link a commerce contact without proving mailbox ownership; failed links never delete identities. */
+export async function linkClientAuthUser(
+  store: ClientAuthLinkStore,
+  rawEmail: string,
+): Promise<LinkClientAuthUserResult> {
+  const email = rawEmail.trim().toLowerCase();
+  const client = await store.findClientByEmail(email);
+  if (!client) return { ok: false, code: "CLIENT_NOT_FOUND", message: "No client row exists for this email; provision the client first." };
+
+  if (client.authUserId) {
+    const linkedEmail = await store.findAuthUserEmailById(client.authUserId);
+    if (linkedEmail?.trim().toLowerCase() !== email) {
+      return { ok: false, code: "CLIENT_AUTH_LINK_CONFLICT", message: "Client account is linked to a different auth identity." };
+    }
+    return { ok: true, clientId: client.id, authUserId: client.authUserId, created: false, alreadyLinked: true, adminSelfLink: false };
+  }
+
+  const trust = await assessEmailTrust(store.emailTrustPolicy);
+  if (!trust.trusted) return { ok: false, code: trust.code, message: "Soft-account provisioning requires a trusted email envelope." };
+
+  const { authUserId, created } = await findOrCreateAuthUserId(store, email);
+  const adminIdentity = await store.findAdminIdentity(authUserId);
+  if (adminIdentity?.isMachineActor) {
+    return { ok: false, code: "MACHINE_ACTOR_REFUSED", message: "Refusing to link a machine/service admin identity to a customer client row." };
+  }
+  const link = await store.setClientAuthUserId(client.id, authUserId);
+  if (!link.ok) {
+    return { ok: false, code: "CLIENT_AUTH_LINK_CONFLICT", message: "Client account was linked to another auth identity concurrently." };
+  }
+  return { ok: true, clientId: client.id, authUserId, created, alreadyLinked: link.alreadyLinked, adminSelfLink: adminIdentity !== null };
+}
+
+
+export type AdminPrincipalRole = "admin" | "distributor";
+
+
+export type AdminAuthorizationResult =
+  | { ok: true; principalId: string; role: AdminPrincipalRole; isMachineActor: boolean }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string };
+
+
+export interface AdminAuthPort {
+  authorize(
+    accessToken: string | null,
+    options?: { allowedRoles?: readonly AdminPrincipalRole[] },
+  ): Promise<AdminAuthorizationResult>;
+}
+
+
+export interface CustomerAccount {
+  id: string;
+  
+  email: string | null;
+  
+  principalId: string | null;
+}
+
+export interface CreateAccountInput {
+  email: string;
+  principalId: string;
+  acquisitionSource: string;
+  lifecycleStage: string;
+}
+
+export type LinkPrincipalResult =
+  | { ok: true; alreadyLinked: boolean }
+  | { ok: false; existingPrincipalId: string | null };
+
+
+export interface AccountLinkStore {
+  findAccountByPrincipalId(principalId: string): Promise<CustomerAccount | null>;
+  findAccountByEmail(email: string): Promise<CustomerAccount | null>;
+  
+  isReservedPrincipal(principalId: string): Promise<boolean>;
+  
+  linkPrincipalToAccount(accountId: string, principalId: string): Promise<LinkPrincipalResult>;
+  createAccount(input: CreateAccountInput): Promise<{ id: string }>;
+}
+
+/** Attempt creation before scanning the existing identity directory. */
+export async function findOrCreateAuthUserId(
+  store: Pick<ClientAuthLinkStore, "createAuthUser" | "findAuthUserIdByEmail">,
+  email: string,
+): Promise<{ authUserId: string; created: boolean }> {
+  const createdId = await store.createAuthUser(email);
+  if (createdId) return { authUserId: createdId, created: true };
+  const existingId = await store.findAuthUserIdByEmail(email);
+  if (!existingId) throw new Error("auth_user_registered_but_unresolved");
+  return { authUserId: existingId, created: false };
+}

package/src/identity/postgresAccountLinkStore.ts

@@ -0,0 +1,49 @@
+import { createPostgresRoleFreeTransactionLane, type PgQueryExecutor } from "../data/index.js";
+import type { AccountLinkStore, CustomerAccount } from "./ports.js";
+/** Trusted contact-link capability; conditional writes never replace an existing principal. */
+export function createPostgresAccountLinkStore(env: { connectionString: string }): AccountLinkStore & { close(): Promise<void> } {
+  const lane = createPostgresRoleFreeTransactionLane(env);
+  const run = <T>(work: (db: PgQueryExecutor) => Promise<T>) => lane.run(db => work(db as PgQueryExecutor));
+  const account = (row: Record<string, unknown> | undefined): CustomerAccount | null => row
+    ? { id: String(row.id), email: row.email === null ? null : String(row.email), principalId: row.principal_id === null ? null : String(row.principal_id) } : null;
+  async function writable(db: PgQueryExecutor, principalId: string, clientId: string | null = null) {
+    // Same receipt-before-contact lock order as privacy erasure; no concurrent resurrection.
+    await db.query("LOCK TABLE public.identity_privacy_erasures IN SHARE MODE");
+    if ((await db.query("SELECT 1 FROM public.identity_privacy_erasures WHERE principal_id = $1 OR client_id = $2 LIMIT 1", [principalId, clientId])).rows.length) throw new Error("account_erased_refused");
+  }
+  return {
+    findAccountByPrincipalId(id) {
+      return run(async db => account((await db.query("SELECT id, email, principal_id FROM public.clients WHERE principal_id = $1", [id])).rows[0]));
+    },
+    findAccountByEmail(email) {
+      return run(async db => {
+        const rows = (await db.query("SELECT id, email, principal_id FROM public.clients WHERE lower(btrim(email)) = $1 LIMIT 2", [email.trim().toLowerCase()])).rows;
+        if (rows.length > 1) throw new Error("account_normalized_email_ambiguous");
+        return account(rows[0]);
+      });
+    },
+    isReservedPrincipal(id) {
+      return run(async db => (await db.query("SELECT 1 FROM public.platform_control_operators WHERE principal_id = $1 UNION ALL SELECT 1 FROM public.identity_privacy_erasures WHERE principal_id = $1 LIMIT 1", [id])).rows.length > 0);
+    },
+    linkPrincipalToAccount(id, principalId) {
+      return run(async db => {
+        await writable(db, principalId, id);
+        const updated = await db.query("UPDATE public.clients SET principal_id = $2 WHERE id = $1 AND principal_id IS NULL RETURNING id", [id, principalId]);
+        if (updated.rows.length) return { ok: true, alreadyLinked: false };
+        const row = (await db.query("SELECT principal_id FROM public.clients WHERE id = $1", [id])).rows[0];
+        return row?.principal_id === principalId ? { ok: true, alreadyLinked: true }
+          : { ok: false, existingPrincipalId: row?.principal_id == null ? null : String(row.principal_id) };
+      });
+    },
+    createAccount(input) {
+      return run(async db => {
+        await writable(db, input.principalId);
+        const row = (await db.query(`INSERT INTO public.clients (email, principal_id, acquisition_source, lifecycle_stage)
+          VALUES ($1, $2, $3, $4) RETURNING id`, [input.email, input.principalId, input.acquisitionSource, input.lifecycleStage])).rows[0];
+        if (!row) throw new Error("account_insert_failed");
+        return { id: String(row.id) };
+      });
+    },
+    close: lane.close,
+  };
+}

package/src/identity/postgresCustomerMe.ts

@@ -0,0 +1,33 @@
+import type { CustomerMeResponse } from "./customerContracts.js";
+import type { CustomerMePort } from "./customerPorts.js";
+import type { PgGatewayClient } from "../data/index.js";
+
+type CustomerMeRow = {
+  id: string;
+  email: string;
+  first_name: string | null;
+  last_name: string | null;
+  lifecycle_stage: CustomerMeResponse["lifecycleStage"];
+};
+
+
+export function createPostgresCustomerMePort(gateway: PgGatewayClient): CustomerMePort {
+  return {
+    async getCustomerMe(): Promise<CustomerMeResponse | null> {
+      const { data, error } = await gateway
+        .from<CustomerMeRow>("clients")
+        .select("id, email, first_name, last_name, lifecycle_stage")
+        .maybeSingle();
+      if (error) throw error;
+      if (!data) return null;
+
+      return {
+        clientId: data.id,
+        email: data.email,
+        firstName: data.first_name,
+        lastName: data.last_name,
+        lifecycleStage: data.lifecycle_stage as CustomerMeResponse["lifecycleStage"],
+      };
+    },
+  };
+}

package/src/identity/postgresCustomerRecovery.ts

@@ -0,0 +1,72 @@
+import type { CustomerChallengeStore } from "./ports.js";
+import {
+  createPostgresRoleFreeTransactionLane,
+  type PostgresDataGatewayEnv,
+  type PostgresDataGatewayOptions,
+} from "../data/index.js";
+import type { PgQueryExecutor } from "../data/index.js";
+
+export type PostgresCustomerChallengeStore = CustomerChallengeStore & {
+  close(): Promise<void>;
+  pruneChallenges(input: { limit: number }): Promise<{ deleted: number }>;
+};
+
+export function createPostgresCustomerChallengeStore(
+  env: PostgresDataGatewayEnv,
+  options: PostgresDataGatewayOptions = {},
+): PostgresCustomerChallengeStore {
+  const lane = createPostgresRoleFreeTransactionLane(env, options);
+  return {
+    async issue(input) {
+      return lane.run(async (executor) => {
+        const db = executor as PgQueryExecutor;
+        // EXCLUSIVE conflicts with erasure's EXCLUSIVE lock and stays held through the RPC.
+        // Receipt reads use ACCESS SHARE, compatible with erasure's receipt-table lock.
+        await db.query("LOCK TABLE public.customer_identity_challenges IN EXCLUSIVE MODE");
+        const erased = await db.query(`SELECT 1 FROM public.clients c JOIN public.identity_privacy_erasures e ON e.client_id = c.id OR e.principal_id = c.principal_id
+          WHERE lower(c.email) = lower(btrim($1))`, [input.email]);
+        if (erased.rows.length) return { deliverable: false };
+        const { rows } = await db.query(
+          "SELECT public.customer_identity_challenge_issue($1,$2,$3::timestamptz,now()) AS result",
+          [input.email, input.tokenHash, input.expiresAt],
+        );
+        const result = rows[0]?.result;
+        if (!result || typeof result !== "object") throw new Error("customer challenge issue response invalid");
+        return { deliverable: (result as { deliverable?: unknown }).deliverable === true };
+      });
+    },
+    async redeem(input) {
+      return lane.run(async (executor) => {
+        const db = executor as PgQueryExecutor;
+        // EXCLUSIVE conflicts with erasure's EXCLUSIVE lock and stays held through the RPC.
+        // Receipt reads use ACCESS SHARE, compatible with erasure's receipt-table lock.
+        await db.query("LOCK TABLE public.customer_identity_challenges IN EXCLUSIVE MODE");
+        const erased = await db.query(`SELECT 1 FROM public.customer_identity_challenges c
+          JOIN public.identity_privacy_erasures e ON e.client_id = c.client_id OR e.principal_id = c.principal_id WHERE c.token_hash = $1`, [input.tokenHash]);
+        if (erased.rows.length) return null;
+        const { rows } = await db.query(
+          "SELECT public.customer_identity_challenge_redeem($1,$2::timestamptz) AS result",
+          [input.tokenHash, input.now],
+        );
+        const result = rows[0]?.result;
+        if (result === null || result === undefined) return null;
+        if (!result || typeof result !== "object") throw new Error("customer challenge redeem response invalid");
+        const value = result as Record<string, unknown>;
+        if (typeof value.principalId !== "string" || typeof value.email !== "string") {
+          throw new Error("customer challenge redeem response invalid");
+        }
+        return { principalId: value.principalId, email: value.email };
+      });
+    },
+    async pruneChallenges({ limit }) {
+      if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error("customer_prune_limit_invalid");
+      return lane.run(async executor => {
+        const deleted = await (executor as PgQueryExecutor).query(`WITH batch AS (SELECT id FROM public.customer_identity_challenges
+          WHERE expires_at < clock_timestamp() - interval '24 hours' ORDER BY expires_at, id LIMIT $1 FOR UPDATE SKIP LOCKED)
+          DELETE FROM public.customer_identity_challenges c USING batch WHERE c.id = batch.id RETURNING c.id`, [limit]);
+        return { deleted: deleted.rows.length };
+      });
+    },
+    close: lane.close,
+  };
+}

package/src/identity/postgresOperatorIdentity.ts

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { createPostgresRoleFreeTransactionLane, type PgQueryExecutor } from "../data/index.js";
+import { acceptDirectOperatorInvitationInTransaction } from "./directOperatorInvitationStore.js";
+import { operatorChallengeRequestSchema } from "./contracts/operatorAuth.js";
+import type { OperatorIdentityStore } from "./operatorPorts.js";
+const fingerprint = (email: string) => createHash("sha256").update(email.trim().toLowerCase()).digest("hex");
+const allowed = (role: unknown) => role === "admin" || role === "distributor";
+
+/** Dedicated owner lane: no actor gateway, customer writes or machine grants. */
+export function createPostgresOperatorIdentityStore(env: { connectionString: string }): OperatorIdentityStore {
+  const lane = createPostgresRoleFreeTransactionLane(env);
+  const run = <T>(work: (db: PgQueryExecutor) => Promise<T>) => lane.run(db => work(db as PgQueryExecutor));
+  async function safeStore(db: PgQueryExecutor) {
+    // 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: PgQueryExecutor, email: string) {
+    // 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: PgQueryExecutor, id: string, email: string): Promise<boolean> {
+    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/src/identity/postgresPrivacy.ts

@@ -0,0 +1,117 @@
+import { createPostgresRoleFreeTransactionLane, type PgQueryExecutor, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+import { PrivacyRefusal, type PrivacyStore, type ResolvedPrivacySubject, type AuthorizedHumanAdministrator } from "./privacyPorts.js";
+import { erasureReceiptSchema, type PrivacySubjectRef, type PrivacyJson } from "./contracts/privacy.js";
+
+type Row = Record<string, unknown>;
+function json(value: unknown): PrivacyJson { return JSON.parse(JSON.stringify(value)) as PrivacyJson; }
+export function createPostgresPrivacyStore(): PrivacyStore<PgQueryExecutor> {
+  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: PgQueryExecutor, subject: ResolvedPrivacySubject, actor: AuthorizedHumanAdministrator, pseudonym: string): Promise<void> {
+  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 as Row | null;
+    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: PostgresDataGatewayEnv, options: PostgresDataGatewayOptions = {}) {
+  const lane = createPostgresRoleFreeTransactionLane(env, options);
+  return { run: <T>(work: (context: PgQueryExecutor) => Promise<T>) => lane.run(db => work(db as PgQueryExecutor)), close: lane.close };
+}

package/src/identity/privacyHandlers.ts

@@ -0,0 +1,33 @@
+import type { HttpHandler } from "../http/index.js";
+import type { AdminAuthorizationResult } from "./ports.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import { privacyExportRequestSchema, privacyEraseRequestSchema, privacyExportResponseSchema, privacyEraseResponseSchema } from "./contracts/privacy.js";
+import { PrivacyRefusal, type PrivacyOperations } from "./privacyPorts.js";
+export interface PrivacyHandlerDependencies extends IdentityResponseOptions { authorizeAdmin: () => Promise<AdminAuthorizationResult>; operations: PrivacyOperations }
+function handler(deps: PrivacyHandlerDependencies, erase: boolean): HttpHandler {
+  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: PrivacyHandlerDependencies): HttpHandler => handler(deps, false);
+export const createPrivacyEraseHandler = (deps: PrivacyHandlerDependencies): HttpHandler => handler(deps, true);

package/src/identity/privacyPorts.ts

@@ -0,0 +1,52 @@
+import type { PrivacySubjectRef, PrivacyExport, ErasureReceipt, PersonalDataDocument, PersonalDataObligation, PrivacyJson, PrivacyRefusalCode } from "./contracts/privacy.js";
+
+export class PrivacyRefusal extends Error {
+  constructor(readonly code: PrivacyRefusalCode) { super(code); this.name = "PrivacyRefusal"; }
+}
+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" }>;
+}