@openlup/platform 0.15.0 → 0.16.0

package/src/identity/oidcPrincipal.ts

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+/** Frozen UTF-8, domain-separated SHA-256 UUIDv8 mapping of the exact issuer/subject pair. */
+export function deriveOidcPrincipalId(issuer: string, subject: string): string {
+  const bytes = createHash("sha256").update("openlup:oidc-principal:v1\0", "utf8")
+    .update(JSON.stringify([issuer, subject]), "utf8").digest().subarray(0, 16);
+  bytes[6] = (bytes[6]! & 0x0f) | 0x80;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/identity/operatorAdminAuth.ts

@@ -0,0 +1,14 @@
+import type { AdminAuthPort, IdentityVerifierPort } from "./ports.js";
+import type { OperatorIdentityStore } from "./operatorPorts.js";
+export function createOperatorAdminAuth(options: { verifier: IdentityVerifierPort; authority: Pick<OperatorIdentityStore, "findMembership"> }): AdminAuthPort {
+  return { async authorize(token, restrictions) {
+    const principal = token ? await options.verifier.verifyAccessToken(token) : null;
+    if (!principal) return { ok: false, code: "UNAUTHORIZED", message: "Operator authentication required" };
+    const member = await options.authority.findMembership(principal.principalId);
+    if (!member || member.membershipState !== "active" || (member.role !== "admin" && member.role !== "distributor")
+      || (restrictions?.allowedRoles && !restrictions.allowedRoles.includes(member.role))) {
+      return { ok: false, code: "FORBIDDEN", message: "Operator access denied" };
+    }
+    return { ok: true, principalId: principal.principalId, role: member.role, isMachineActor: false };
+  } };
+}

package/src/identity/operatorAuthHandlers.ts

@@ -0,0 +1,52 @@
+import { operatorChallengeRequestSchema, operatorChallengeVerificationSchema, operatorSessionSchema } from "./contracts/operatorAuth.js";
+import { createMagicLinkOriginResolver } from "./authVerifyUrl.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { createOperatorSessionService } from "./operatorSession.js";
+export interface OperatorAuthMessages { invalidRequest: string; forbidden: string; unauthorized: string; unavailable: string }
+export function createOperatorAuthHandlers(options: IdentityResponseOptions & {
+  sessions: ReturnType<typeof createOperatorSessionService>; origin: string; messages: OperatorAuthMessages;
+  padResponseTime(startedAt: number, minimumMs: number): Promise<void>;
+}) {
+  const responder = createIdentityResponder(options);
+  const origin = createMagicLinkOriginResolver([options.origin]);
+  function admitted(req: HttpRequest, res: HttpResponse): boolean {
+    if (req.method !== "POST") { responder.sendMethodNotAllowed(res, ["POST"]); return false; }
+    const configured = origin(req);
+    if (!configured) { responder.sendBffError(res, "UPSTREAM_UNAVAILABLE", options.messages.unavailable); return false; }
+    const supplied = req.headers.origin;
+    const contentType = req.headers["content-type"];
+    if (supplied !== configured || typeof contentType !== "string" || !/^application\/json(?:;|$)/i.test(contentType)) {
+      responder.sendBffError(res, "FORBIDDEN", options.messages.forbidden); return false;
+    }
+    return true;
+  }
+  return {
+    async requestChallenge(req: HttpRequest, res: HttpResponse): Promise<void> {
+      if (!admitted(req, res)) return;
+      const parsed = operatorChallengeRequestSchema.safeParse(req.body);
+      if (!parsed.success) { responder.sendBffError(res, "BAD_REQUEST", options.messages.invalidRequest); return; }
+      const started = Date.now();
+      try {
+        await options.sessions.requestChallenge(parsed.data.email, async () => {
+          await options.padResponseTime(started, 400);
+          responder.sendBffSuccess(res, { accepted: true });
+        });
+      } catch { responder.sendBffError(res, "UPSTREAM_UNAVAILABLE", options.messages.unavailable); }
+    },
+    async verifyChallenge(req: HttpRequest, res: HttpResponse): Promise<void> {
+      if (!admitted(req, res)) return;
+      // A token-shaped refusal is authentication failure; an invalid envelope is a bad request.
+      if (!req.body || typeof req.body !== "object" || Object.keys(req.body).length !== 1 || typeof (req.body as { token?: unknown }).token !== "string") {
+        responder.sendBffError(res, "BAD_REQUEST", options.messages.invalidRequest); return;
+      }
+      const parsed = operatorChallengeVerificationSchema.safeParse(req.body);
+      if (!parsed.success) { responder.sendBffError(res, "UNAUTHORIZED", options.messages.unauthorized); return; }
+      try {
+        const session = await options.sessions.verifyChallenge(parsed.data.token);
+        if (!session) { responder.sendBffError(res, "UNAUTHORIZED", options.messages.unauthorized); return; }
+        responder.sendBffSuccess(res, operatorSessionSchema.parse(session));
+      } catch { responder.sendBffError(res, "UPSTREAM_UNAVAILABLE", options.messages.unavailable); }
+    },
+  };
+}

package/src/identity/operatorIdentityVerifier.ts

@@ -0,0 +1,19 @@
+import { createCustomerIdentityVerifier } from "./customerIdentityVerifier.js";
+import type { IdentityJwtLibraryLoader } from "./jwtLibrary.js";
+import type { IdentityVerifierPort } from "./ports.js";
+export function createOperatorIdentityVerifier(config: { issuer: string; audience: string; customerAudience: string; jwks: string }, loadJwt: IdentityJwtLibraryLoader): IdentityVerifierPort {
+  if (!config.customerAudience.trim() || config.audience === config.customerAudience) throw new Error("operator_audience_must_be_distinct");
+  // Inspect the payload returned by the same cryptographic verification, never an unverified decode.
+  return createCustomerIdentityVerifier(config, async () => {
+    const library = await loadJwt();
+    return { ...library, async jwtVerify(token, key, options) {
+      const verified = await library.jwtVerify(token, key, options);
+      const payload = verified.payload as Record<string, unknown>;
+      const { iat, exp } = payload;
+      if (payload.aud !== config.audience || typeof iat !== "number" || typeof exp !== "number"
+        || !Number.isInteger(iat) || !Number.isInteger(exp) || exp <= iat || exp - iat > 900
+        || iat > Math.floor(Date.now() / 1000) || exp <= Math.floor(Date.now() / 1000)) throw new Error("operator_token_profile_invalid");
+      return verified;
+    } };
+  });
+}

package/src/identity/operatorInvitationLifecycle.ts

@@ -0,0 +1,14 @@
+export function assertOperatorInvitationTtl(value: number): void {
+  if (!Number.isInteger(value) || value < 60 || value > 2592000) throw new Error("operator_invitation_ttl_invalid");
+}
+export function invitationFailure(identityCode: string, bffCode = "CONFLICT"): Error & { identityCode: string; bffCode: string } {
+  return Object.assign(new Error(identityCode), { identityCode, bffCode });
+}
+
+/** Pure parser; direct hosts call it before effects and pass the number to identity. */
+export function parseOperatorInvitationTtl(raw?: string): number {
+  if (raw !== undefined && !/^\d+$/.test(raw)) throw new Error("operator_invitation_ttl_invalid");
+  const value = raw === undefined ? 604800 : Number(raw);
+  assertOperatorInvitationTtl(value);
+  return value;
+}

package/src/identity/operatorInvitationPorts.ts

@@ -0,0 +1,11 @@
+import type { OperatorInvitationAcceptance, OperatorInvitationConflict, OperatorInvitationResult, OperatorMembershipSnapshot, OperatorRole } from "./contracts/operatorInvitations.js";
+export interface OperatorIdentityDirectoryPort {
+  ensurePrincipal(input: { email: string; redirectTo: string }): Promise<{ principalId: string; created: boolean }>;
+}
+export interface OperatorInvitationStore {
+  issue(input: { actorPrincipalId: string; targetPrincipalId: string; email: string; role: OperatorRole; ttlSeconds: number }): Promise<OperatorInvitationResult | { code: OperatorInvitationConflict }>;
+  read(principalId: string): Promise<OperatorMembershipSnapshot | null>;
+  /** Trusted server input only: principal must come from successful authentication. */
+  acceptOperatorInvitation(principalId: string): Promise<OperatorInvitationAcceptance>;
+  remove(input: { actorPrincipalId: string; targetPrincipalId: string; reason?: string }): Promise<{ revoked: true }>;
+}

package/src/identity/operatorPorts.ts

@@ -0,0 +1,11 @@
+export interface OperatorIdentity { principalId: string; email: string }
+export interface OperatorMembership extends OperatorIdentity { membershipState: string; role: unknown }
+export interface OperatorIdentityStore {
+  issue(input: { email: string; tokenHash: string }): Promise<{ deliverable: false } | { deliverable: true; email: string; expiresAt: string }>;
+  /** Activation and consumption commit together before signing. */
+  redeem(input: { tokenHash: string }): Promise<OperatorIdentity | null>;
+  findMembership(principalId: string): Promise<OperatorMembership | null>;
+  bootstrapFirstAdministrator(input: { email: string }): Promise<{ principalId: string; membershipState: "invited" }>;
+  pruneChallenges(input: { limit: number }): Promise<{ deleted: number }>;
+  close(): Promise<void>;
+}

package/src/identity/operatorSession.ts

@@ -0,0 +1,30 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { CustomerChallengeDeliveryPort, CustomerSessionIssuerPort } from "./ports.js";
+import type { OperatorIdentityStore } from "./operatorPorts.js";
+import type { OperatorSession } from "./contracts/operatorAuth.js";
+export function createOperatorSessionService(options: {
+  store: OperatorIdentityStore; delivery: CustomerChallengeDeliveryPort; issuer: CustomerSessionIssuerPort;
+  generateToken?: () => string;
+  deliveryFailed?: (code: "operator_challenge_delivery_failed") => void;
+}) {
+  const hash = (value: string) => createHash("sha256").update(value, "utf8").digest("hex");
+  return {
+    async requestChallenge(email: string, accept?: () => Promise<void>): Promise<void> {
+      const token = options.generateToken?.() ?? randomBytes(32).toString("base64url");
+      if (!/^[A-Za-z0-9_-]{43}$/.test(token)) throw new Error("operator_challenge_generator_invalid");
+      const result = await options.store.issue({ email: email.trim().toLowerCase(), tokenHash: hash(token) });
+      // Send the generic acceptance before mailbox transport, for every eligibility result.
+      await accept?.();
+      if (!result.deliverable) return;
+      try { await options.delivery.deliver({ email: result.email, expiresAt: result.expiresAt, token }); }
+      catch { options.deliveryFailed?.("operator_challenge_delivery_failed"); }
+    },
+    async verifyChallenge(token: string): Promise<OperatorSession | null> {
+      if (!/^[A-Za-z0-9_-]{43}$/.test(token)) return null;
+      const identity = await options.store.redeem({ tokenHash: hash(token) });
+      if (!identity) return null;
+      const session = await options.issuer.issue(identity);
+      return { ...session, user: { id: identity.principalId, email: identity.email } };
+    },
+  };
+}

package/src/identity/operatorTokenAdminAuth.ts

@@ -0,0 +1,79 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+import type {
+  AdminAuthorizationResult,
+  AdminAuthPort,
+  AdminPrincipalRole,
+} from "./ports.js";
+
+const MIN_TOKEN_BYTES = 32;
+const MAX_TOKEN_BYTES = 512;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export type PlatformOperatorAuthConfig = {
+  readonly operatorToken: string;
+  readonly operatorId: string;
+};
+
+export type PlatformOperatorAllowlistCheck = (principalId: string) => Promise<boolean>;
+
+export type PlatformOperatorAuthConfigResolution =
+  | { readonly config: PlatformOperatorAuthConfig; readonly error?: undefined }
+  | { readonly config?: undefined; readonly error: "platform_operator_token_required" | "platform_operator_token_invalid" | "platform_operator_id_required" | "platform_operator_id_invalid" };
+
+function byteLength(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+
+export function resolvePlatformOperatorAuthConfig(
+  env: Record<string, string | undefined>,
+): PlatformOperatorAuthConfigResolution {
+  const operatorToken = env.PLATFORM_OPERATOR_TOKEN?.trim() ?? "";
+  if (!operatorToken) return { error: "platform_operator_token_required" };
+  const tokenBytes = byteLength(operatorToken);
+  if (tokenBytes < MIN_TOKEN_BYTES || tokenBytes > MAX_TOKEN_BYTES) {
+    return { error: "platform_operator_token_invalid" };
+  }
+
+  const operatorId = env.PLATFORM_OPERATOR_ID?.trim() ?? "";
+  if (!operatorId) return { error: "platform_operator_id_required" };
+  if (!UUID_PATTERN.test(operatorId)) return { error: "platform_operator_id_invalid" };
+  return { config: { operatorToken, operatorId: operatorId.toLowerCase() } };
+}
+
+function matchesOperatorToken(candidate: string | null, expected: string): boolean {
+  if (!candidate || byteLength(candidate) > MAX_TOKEN_BYTES) return false;
+  const actualDigest = createHash("sha256").update(candidate, "utf8").digest();
+  const expectedDigest = createHash("sha256").update(expected, "utf8").digest();
+  return timingSafeEqual(actualDigest, expectedDigest);
+}
+
+
+export function createOperatorTokenAdminAuth(
+  config: PlatformOperatorAuthConfig,
+  isOperatorAllowed: PlatformOperatorAllowlistCheck,
+): AdminAuthPort {
+  return {
+    async authorize(
+      accessToken: string | null,
+      options: { allowedRoles?: readonly AdminPrincipalRole[] } = {},
+    ): Promise<AdminAuthorizationResult> {
+      if (!matchesOperatorToken(accessToken, config.operatorToken)) {
+        return { ok: false, code: "UNAUTHORIZED", message: "Admin session required" };
+      }
+      if (options.allowedRoles && !options.allowedRoles.includes("admin")) {
+        return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+      }
+      if (!(await isOperatorAllowed(config.operatorId))) {
+        return { ok: false, code: "FORBIDDEN", message: "Admin role required" };
+      }
+      return {
+        ok: true,
+        principalId: config.operatorId,
+        role: "admin",
+        isMachineActor: true,
+      };
+    },
+  };
+}

package/src/identity/personalDataRegistry.ts

@@ -0,0 +1,8 @@
+import { PrivacyRefusal, type PersonalDataContributor, type PersonalDataContributorRegistry } from "./privacyPorts.js";
+export function createPersonalDataContributorRegistry<Context>(contributors: readonly PersonalDataContributor<Context>[], options: { requiredContributorIds: readonly string[] }): PersonalDataContributorRegistry<Context> {
+  const ids = contributors.map(c => c.id);
+  if (new Set(ids).size !== ids.length) throw new PrivacyRefusal("PRIVACY_CONTRIBUTOR_DUPLICATE");
+  if (contributors.some(c => !/^[a-z][a-z0-9.-]{0,99}$/.test(c.id) || !/^[a-z][a-z0-9.-]*\.v[1-9][0-9]*$/.test(c.version))) throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+  if (contributors.some(c => !Array.isArray(c.ownedResources) || c.ownedResources.length === 0 || c.ownedResources.some(resource => !resource.trim()))) throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+  return Object.freeze({ contributors: Object.freeze([...contributors]), missingContributors: Object.freeze(options.requiredContributorIds.filter(id => !ids.includes(id))) });
+}

package/src/identity/platformAdminAuth.ts

@@ -0,0 +1,7 @@
+export type PlatformAdminAuthorizationResult =
+  | { ok: true }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string };
+
+export type PlatformUserAuthenticationResult =
+  | { ok: true; userId: string }
+  | { ok: false; code: "UNAUTHORIZED"; message: string };

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,
+  };
+}