@openlup/platform 0.15.0 → 0.16.0

package/dist/identity/operatorTokenAdminAuth.js

@@ -0,0 +1,50 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+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;
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+export function resolvePlatformOperatorAuthConfig(env) {
+    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, expected) {
+    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, isOperatorAllowed) {
+    return {
+        async authorize(accessToken, options = {}) {
+            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/dist/identity/personalDataRegistry.d.ts

@@ -0,0 +1,4 @@
+import { type PersonalDataContributor, type PersonalDataContributorRegistry } from "./privacyPorts.js";
+export declare function createPersonalDataContributorRegistry<Context>(contributors: readonly PersonalDataContributor<Context>[], options: {
+    requiredContributorIds: readonly string[];
+}): PersonalDataContributorRegistry<Context>;

package/dist/identity/personalDataRegistry.js

@@ -0,0 +1,11 @@
+import { PrivacyRefusal } from "./privacyPorts.js";
+export function createPersonalDataContributorRegistry(contributors, options) {
+    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/dist/identity/platformAdminAuth.d.ts

@@ -0,0 +1,15 @@
+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/dist/identity/platformAdminAuth.js

@@ -0,0 +1 @@
+export {};

package/dist/identity/ports.d.ts

@@ -0,0 +1,127 @@
+import { 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 declare function linkClientAuthUser(store: ClientAuthLinkStore, rawEmail: string): Promise<LinkClientAuthUserResult>;
+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 declare function findOrCreateAuthUserId(store: Pick<ClientAuthLinkStore, "createAuthUser" | "findAuthUserIdByEmail">, email: string): Promise<{
+    authUserId: string;
+    created: boolean;
+}>;

package/dist/identity/ports.js

@@ -0,0 +1,38 @@
+import { assessEmailTrust } from "./emailTrustPolicy.js";
+/** Link a commerce contact without proving mailbox ownership; failed links never delete identities. */
+export async function linkClientAuthUser(store, rawEmail) {
+    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 };
+}
+/** Attempt creation before scanning the existing identity directory. */
+export async function findOrCreateAuthUserId(store, email) {
+    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/dist/identity/postgresAccountLinkStore.d.ts

@@ -0,0 +1,7 @@
+import type { AccountLinkStore } from "./ports.js";
+/** Trusted contact-link capability; conditional writes never replace an existing principal. */
+export declare function createPostgresAccountLinkStore(env: {
+    connectionString: string;
+}): AccountLinkStore & {
+    close(): Promise<void>;
+};

package/dist/identity/postgresAccountLinkStore.js

@@ -0,0 +1,52 @@
+import { createPostgresRoleFreeTransactionLane } from "../data/index.js";
+/** Trusted contact-link capability; conditional writes never replace an existing principal. */
+export function createPostgresAccountLinkStore(env) {
+    const lane = createPostgresRoleFreeTransactionLane(env);
+    const run = (work) => lane.run(db => work(db));
+    const account = (row) => 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, principalId, clientId = 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/dist/identity/postgresCustomerMe.d.ts

@@ -0,0 +1,3 @@
+import type { CustomerMePort } from "./customerPorts.js";
+import type { PgGatewayClient } from "../data/index.js";
+export declare function createPostgresCustomerMePort(gateway: PgGatewayClient): CustomerMePort;

package/dist/identity/postgresCustomerMe.js

@@ -0,0 +1,21 @@
+export function createPostgresCustomerMePort(gateway) {
+    return {
+        async getCustomerMe() {
+            const { data, error } = await gateway
+                .from("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,
+            };
+        },
+    };
+}

package/dist/identity/postgresCustomerRecovery.d.ts

@@ -0,0 +1,11 @@
+import type { CustomerChallengeStore } from "./ports.js";
+import { type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+export type PostgresCustomerChallengeStore = CustomerChallengeStore & {
+    close(): Promise<void>;
+    pruneChallenges(input: {
+        limit: number;
+    }): Promise<{
+        deleted: number;
+    }>;
+};
+export declare function createPostgresCustomerChallengeStore(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): PostgresCustomerChallengeStore;

package/dist/identity/postgresCustomerRecovery.js

@@ -0,0 +1,57 @@
+import { createPostgresRoleFreeTransactionLane, } from "../data/index.js";
+export function createPostgresCustomerChallengeStore(env, options = {}) {
+    const lane = createPostgresRoleFreeTransactionLane(env, options);
+    return {
+        async issue(input) {
+            return lane.run(async (executor) => {
+                const db = executor;
+                // 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.deliverable === true };
+            });
+        },
+        async redeem(input) {
+            return lane.run(async (executor) => {
+                const db = executor;
+                // 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;
+                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.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/dist/identity/postgresOperatorIdentity.d.ts

@@ -0,0 +1,5 @@
+import type { OperatorIdentityStore } from "./operatorPorts.js";
+/** Dedicated owner lane: no actor gateway, customer writes or machine grants. */
+export declare function createPostgresOperatorIdentityStore(env: {
+    connectionString: string;
+}): OperatorIdentityStore;

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