@openlup/platform 0.15.0 → 0.17.0

package/dist/identity/customerMagicLinkHandler.js

@@ -0,0 +1,115 @@
+import { createMagicLinkOriginResolver, normalizeMagicLinkReturnPath } from "./authVerifyUrl.js";
+import { createIdentityResponder } from "./response.js";
+import { resolveBundleId } from "../kernel/index.js";
+const MAGIC_LINK_RESPONSE_FLOOR_MS = 400;
+export function createCustomerMagicLinkHandler(options) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(options);
+    const readRequestOrigin = options.resolveOrigin ?? createMagicLinkOriginResolver(options.redirectOrigins ?? []);
+    const { enabled: customerAuthUiEnabled, env: environment, readEnvironment: readCustomerSelfServiceEnv, createCustomerClient, createCustomerServiceClient, checkAttempt: checkAndRecordCustomerMagicLinkAttempt, extractClientIp, padResponseTime, requestSchema: customerMagicLinkRequestSchema, responseSchema: customerMagicLinkResponseSchema, resolveSession, callbackPath: customerAuthCallbackPath } = options;
+    return async (req, res) => {
+        if (!customerAuthUiEnabled()) {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer accounts are disabled", {
+                details: {
+                    feature: "customer_auth",
+                    ...options.disabledDetails,
+                    reason: "feature_flag_disabled",
+                },
+            });
+            return;
+        }
+        if (req.method !== "POST") {
+            sendMethodNotAllowed(res, ["POST"]);
+            return;
+        }
+        const request = customerMagicLinkRequestSchema.safeParse(req.body);
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid magic-link request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        const startedAt = Date.now();
+        const origin = readRequestOrigin(req);
+        if (!origin) {
+            await padResponseTime(startedAt, MAGIC_LINK_RESPONSE_FLOOR_MS);
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link origin is not configured", {
+                details: { reason: "magic_link_origin_not_configured" },
+            });
+            return;
+        }
+        if (resolveBundleId(environment) === "node-postgres") {
+            const resolved = resolveSession(environment);
+            if (!resolved.binding) {
+                await padResponseTime(startedAt, MAGIC_LINK_RESPONSE_FLOOR_MS);
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer auth is not configured", {
+                    details: { feature: "customer_auth", reason: resolved.error },
+                });
+                return;
+            }
+            await resolved.binding.requestChallenge(request.data.email);
+            await padResponseTime(startedAt, MAGIC_LINK_RESPONSE_FLOOR_MS);
+            sendAccepted(res);
+            return;
+        }
+        const env = readCustomerSelfServiceEnv();
+        if (!env) {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer auth is not configured", {
+                details: {
+                    feature: "customer_auth",
+                    requiredEnv: "SUPABASE_URL/SUPABASE_ANON_KEY/SUPABASE_SERVICE_ROLE_KEY",
+                },
+            });
+            return;
+        }
+        const anonymousAuthClient = createCustomerClient(env, null);
+        const rateLimitClient = createCustomerServiceClient(env);
+        const decision = await checkAndRecordCustomerMagicLinkAttempt({
+            client: rateLimitClient,
+            ip: extractClientIp(req.headers),
+            email: request.data.email,
+        });
+        if (!decision.allowed && decision.reason === "rpc_error") {
+            console.warn("customer_magic_link_rate_limit_unavailable", JSON.stringify({ reason: decision.reason }));
+            await padResponseTime(startedAt, MAGIC_LINK_RESPONSE_FLOOR_MS);
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link service temporarily unavailable");
+            return;
+        }
+        if (decision.allowed) {
+            const outcome = await sendMagicLink(anonymousAuthClient, request.data.email, origin, request.data.locale, normalizeMagicLinkReturnPath(request.data.returnTo, origin));
+            console.info("customer_magic_link_outcome", JSON.stringify({ outcome: outcome.status, code: outcome.code ?? null, locale: request.data.locale }));
+        }
+        else {
+            console.warn("customer_magic_link_outcome", JSON.stringify({ outcome: "rate_limited", reason: decision.reason ?? "unknown" }));
+        }
+        await padResponseTime(startedAt, MAGIC_LINK_RESPONSE_FLOOR_MS);
+        sendAccepted(res);
+    };
+    async function sendMagicLink(client, email, origin, locale, returnTo) {
+        try {
+            const callbackUrl = new URL(customerAuthCallbackPath(locale), origin);
+            if (returnTo)
+                callbackUrl.searchParams.set("returnTo", returnTo);
+            const { error } = await client.auth.signInWithOtp({
+                email,
+                options: {
+                    // First login confirms the already provisioned principal through mailbox proof.
+                    shouldCreateUser: false,
+                    emailRedirectTo: callbackUrl.toString(),
+                },
+            });
+            if (error) {
+                console.warn("customer_magic_link_send_failed", JSON.stringify({ code: error.name }));
+                return { status: "auth_error", code: error.name };
+            }
+            return { status: "sent" };
+        }
+        catch (error) {
+            const code = error instanceof Error ? error.name : "unknown";
+            console.warn("customer_magic_link_send_threw", JSON.stringify({ error: code }));
+            return { status: "threw", code };
+        }
+    }
+    function sendAccepted(res) {
+        sendBffSuccess(res, customerMagicLinkResponseSchema.parse({ accepted: true }));
+    }
+}

package/dist/identity/customerMeHandler.d.ts

@@ -0,0 +1,11 @@
+import { type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { customerMeResponseSchema } from "./customerContracts.js";
+import type { CustomerMePort } from "./customerPorts.js";
+import type { CustomerUserAuthenticationResult } from "./customerAuth.js";
+export interface CustomerMeDeps extends IdentityResponseOptions {
+    responseSchema: typeof customerMeResponseSchema;
+    mePort: CustomerMePort;
+    authenticateUser: (req: HttpRequest) => Promise<CustomerUserAuthenticationResult>;
+}
+export declare function createCustomerMeHandler({ mePort, authenticateUser, responseSchema, responseRequestId }: CustomerMeDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/identity/customerMeHandler.js

@@ -0,0 +1,46 @@
+import { createIdentityResponder } from "./response.js";
+import { customerMeRequestSchema, } from "./customerContracts.js";
+export function createCustomerMeHandler({ mePort, authenticateUser, responseSchema, responseRequestId }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+    return async function handler(req, res) {
+        if (req.method !== "GET") {
+            sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        let authentication;
+        try {
+            authentication = await authenticateUser(req);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer authentication failed");
+            return;
+        }
+        if (authentication.ok === false) {
+            sendBffError(res, authentication.code, authentication.message);
+            return;
+        }
+        const request = customerMeRequestSchema.safeParse(req.query ?? {});
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid customer me request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await mePort.getCustomerMe(authentication.userId);
+            if (!result) {
+                sendBffError(res, "FORBIDDEN", "No customer account linked to this session");
+                return;
+            }
+            const response = responseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Customer me returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer me read failed");
+        }
+    };
+}

package/dist/identity/customerPorts.d.ts

@@ -0,0 +1,4 @@
+import type { CustomerMeResponse } from "./customerContracts.js";
+export interface CustomerMePort {
+    getCustomerMe(principalId: string): Promise<CustomerMeResponse | null>;
+}

package/dist/identity/customerPorts.js

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

package/dist/identity/customerSessionBinding.d.ts

@@ -0,0 +1,38 @@
+import type { IdentityJwtLibraryLoader } from "./jwtLibrary.js";
+import type { CustomerChallengeDeliveryPort, CustomerChallengeStore, CustomerSessionIssuerPort } from "./ports.js";
+type Env = Record<string, string | undefined>;
+export type CapturedCustomerChallenge = {
+    readonly email: string;
+    readonly token: string;
+    readonly expiresAt: string;
+};
+/** Deterministic no-egress reference delivery; deployments inject mail. */
+export declare function createCapturedCustomerChallengeDelivery(sink?: (challenge: CapturedCustomerChallenge) => Promise<void>): CustomerChallengeDeliveryPort;
+export interface CustomerSessionBinding {
+    requestChallenge(email: string): Promise<void>;
+    verifyChallenge(token: string): Promise<{
+        accessToken: string;
+        expiresAt: string;
+        user: {
+            id: string;
+            email: string;
+        };
+    } | null>;
+}
+export declare function resolveCustomerSessionBinding(env: Env, options?: {
+    createStore?: (connectionString: string) => CustomerChallengeStore & {
+        close(): Promise<void>;
+    };
+    delivery?: CustomerChallengeDeliveryPort;
+    issuer?: CustomerSessionIssuerPort;
+    loadJwt?: IdentityJwtLibraryLoader;
+    generateToken?: () => string;
+    now?: () => Date;
+}): {
+    binding: CustomerSessionBinding;
+    error?: undefined;
+} | {
+    binding?: undefined;
+    error: string;
+};
+export {};

package/dist/identity/customerSessionBinding.js

@@ -0,0 +1,80 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createCustomerSessionIssuer } from "./customerSessionIssuer.js";
+import { createPostgresCustomerChallengeStore } from "./postgresCustomerRecovery.js";
+import { resolveBundleId } from "../kernel/index.js";
+/** Deterministic no-egress reference delivery; deployments inject mail. */
+export function createCapturedCustomerChallengeDelivery(sink = async () => { }) {
+    return { deliver: sink };
+}
+export function resolveCustomerSessionBinding(env, options = {}) {
+    if (resolveBundleId(env) !== "node-postgres")
+        return { error: "customer_session_external_bundle" };
+    const connectionString = env.DATABASE_URL?.trim() ?? "";
+    if (!connectionString)
+        return { error: "database_url_required" };
+    let issuer;
+    try {
+        if (!options.issuer && !options.loadJwt)
+            throw new Error("identity_jwt_library_required");
+        issuer = options.issuer ?? createCustomerSessionIssuer({
+            audience: env.CUSTOMER_IDENTITY_AUDIENCE ?? "",
+            issuer: env.CUSTOMER_IDENTITY_ISSUER ?? "",
+            keyId: env.CUSTOMER_IDENTITY_KEY_ID ?? "",
+            privateJwk: env.CUSTOMER_IDENTITY_PRIVATE_JWK ?? "",
+            ttlSeconds: readTtl(env.CUSTOMER_IDENTITY_SESSION_TTL_SECONDS, 3_600),
+        }, options.loadJwt);
+    }
+    catch {
+        return { error: "customer_session_issuer_invalid" };
+    }
+    const createStore = options.createStore ?? ((url) => createPostgresCustomerChallengeStore({ connectionString: url }));
+    const delivery = options.delivery ?? createCapturedCustomerChallengeDelivery();
+    const generateToken = options.generateToken ?? (() => randomBytes(32).toString("base64url"));
+    const now = options.now ?? (() => new Date());
+    const challengeTtlSeconds = readTtl(env.CUSTOMER_IDENTITY_CHALLENGE_TTL_SECONDS, 600);
+    return { binding: {
+            async requestChallenge(email) {
+                const normalizedEmail = email.trim().toLowerCase();
+                const token = generateToken();
+                const requestedAt = now();
+                const expiresAt = new Date(requestedAt.getTime() + challengeTtlSeconds * 1000).toISOString();
+                const store = createStore(connectionString);
+                try {
+                    const result = await store.issue({ email: normalizedEmail, tokenHash: hash(token), expiresAt });
+                    if (result.deliverable)
+                        await delivery.deliver({ email: normalizedEmail, token, expiresAt });
+                }
+                finally {
+                    await store.close();
+                }
+            },
+            async verifyChallenge(token) {
+                const store = createStore(connectionString);
+                try {
+                    const redeemed = await store.redeem({ tokenHash: hash(token), now: now().toISOString() });
+                    if (!redeemed)
+                        return null;
+                    const session = await issuer.issue(redeemed);
+                    return {
+                        ...session,
+                        user: { id: redeemed.principalId, email: redeemed.email },
+                    };
+                }
+                finally {
+                    await store.close();
+                }
+            },
+        } };
+}
+function hash(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function readTtl(value, fallback) {
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 300 || parsed > 86_400) {
+        throw new Error("customer identity ttl invalid");
+    }
+    return parsed;
+}

package/dist/identity/customerSessionIssuer.d.ts

@@ -0,0 +1,10 @@
+import type { IdentityJwtLibraryLoader } from "./jwtLibrary.js";
+import type { CustomerSessionIssuerPort } from "./ports.js";
+export interface CustomerSessionIssuerConfig {
+    audience: string;
+    issuer: string;
+    keyId: string;
+    privateJwk: string;
+    ttlSeconds: number;
+}
+export declare function createCustomerSessionIssuer(config: CustomerSessionIssuerConfig, loadJwt: IdentityJwtLibraryLoader): CustomerSessionIssuerPort;

package/dist/identity/customerSessionIssuer.js

@@ -0,0 +1,57 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const KID = /^[A-Za-z0-9._-]{1,64}$/;
+export function createCustomerSessionIssuer(config, loadJwt) {
+    const audience = claim(config.audience, "audience");
+    const issuer = claim(config.issuer, "issuer");
+    if (!KID.test(config.keyId))
+        throw new Error("customer session key id configuration is invalid");
+    if (!Number.isInteger(config.ttlSeconds) || config.ttlSeconds < 300 || config.ttlSeconds > 86_400) {
+        throw new Error("customer session ttl configuration is invalid");
+    }
+    const privateKey = readPrivateKey(config.privateJwk);
+    const library = loadJwt();
+    const key = library.then(({ importJWK }) => importJWK(privateKey, "ES256"));
+    return {
+        async issue({ principalId, email }) {
+            if (!UUID.test(principalId))
+                throw new Error("customer session principal is invalid");
+            const normalizedEmail = email.trim().toLowerCase();
+            if (!normalizedEmail || normalizedEmail.length > 320) {
+                throw new Error("customer session email is invalid");
+            }
+            const issuedAt = Math.floor(Date.now() / 1000);
+            const expiresAt = issuedAt + config.ttlSeconds;
+            const { SignJWT } = await library;
+            const accessToken = await new SignJWT({ email: normalizedEmail, email_verified: true })
+                .setProtectedHeader({ alg: "ES256", kid: config.keyId, typ: "JWT" })
+                .setSubject(principalId)
+                .setIssuer(issuer)
+                .setAudience(audience)
+                .setIssuedAt(issuedAt)
+                .setExpirationTime(expiresAt)
+                .sign(await key);
+            return { accessToken, expiresAt: new Date(expiresAt * 1000).toISOString() };
+        },
+    };
+}
+function readPrivateKey(value) {
+    if (!value || value.length > 16_384)
+        throw new Error("customer session private JWK configuration is invalid");
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error("customer session private JWK configuration is invalid");
+    }
+    if (parsed.kty !== "EC" || parsed.crv !== "P-256" || parsed.alg !== "ES256" || typeof parsed.d !== "string") {
+        throw new Error("customer session private JWK configuration is invalid");
+    }
+    return parsed;
+}
+function claim(value, label) {
+    if (!value || value.length > 256 || value.trim() !== value) {
+        throw new Error(`customer session ${label} configuration is invalid`);
+    }
+    return value;
+}

package/dist/identity/customerVerifyOtpHandler.d.ts

@@ -0,0 +1,8 @@
+import { type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { resolveCustomerSessionBinding } from "./customerSessionBinding.js";
+export declare function createCustomerVerifyOtpHandler(options: IdentityResponseOptions & {
+    enabled: () => boolean;
+    env: Record<string, string | undefined>;
+    resolveSession: typeof resolveCustomerSessionBinding;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/identity/customerVerifyOtpHandler.js

@@ -0,0 +1,41 @@
+import { createIdentityResponder } from "./response.js";
+import { z } from "zod";
+z.config({ jitless: true });
+const customerOtpVerifyRequestSchema = z.object({
+    email: z.string().trim().toLowerCase().email().max(160),
+    token: z.string().trim().min(16).max(256),
+}).strict();
+const customerOtpVerifyResponseSchema = z.object({
+    accessToken: z.string().min(1),
+    expiresAt: z.string().datetime({ offset: true }),
+    user: z.object({ id: z.guid(), email: z.string().email() }).strict(),
+}).strict();
+export function createCustomerVerifyOtpHandler(options) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(options);
+    return async (req, res) => {
+        if (!options.enabled()) {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer accounts are disabled");
+            return;
+        }
+        if (req.method !== "POST")
+            return sendMethodNotAllowed(res, ["POST"]);
+        const request = customerOtpVerifyRequestSchema.safeParse(req.body);
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid one-time code request", { details: request.error.flatten() });
+            return;
+        }
+        const resolved = options.resolveSession(options.env);
+        if (!resolved.binding) {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Customer auth is not configured", {
+                details: { feature: "customer_auth", reason: resolved.error },
+            });
+            return;
+        }
+        const session = await resolved.binding.verifyChallenge(request.data.token);
+        if (!session) {
+            sendBffError(res, "UNAUTHORIZED", "One-time code is invalid or expired");
+            return;
+        }
+        sendBffSuccess(res, customerOtpVerifyResponseSchema.parse(session));
+    };
+}

package/dist/identity/directOperatorInvitationStore.d.ts

@@ -0,0 +1,19 @@
+import { type PgQueryExecutor, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+import type { OperatorInvitationStore } from "./operatorInvitationPorts.js";
+/** Owner-authority lane, never the actor gateway. One transaction per command. */
+export declare function createDirectOperatorInvitationStore(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): OperatorInvitationStore & {
+    close(): Promise<void>;
+};
+/** Principal creation commits independently; an invitation failure leaves it reusable. */
+export declare function createDirectOperatorIdentityDirectory(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): {
+    ensurePrincipal(input: {
+        email: string;
+        redirectTo: string;
+    }): Promise<{
+        principalId: string;
+        created: boolean;
+    }>;
+    close: () => Promise<void>;
+};
+/** Trusted authentication only; caller owns the transaction, including challenge consumption. */
+export declare function acceptDirectOperatorInvitationInTransaction(db: PgQueryExecutor, id: string): Promise<import("./contracts/operatorInvitations.js").OperatorInvitationAcceptance>;

package/dist/identity/directOperatorInvitationStore.js

@@ -0,0 +1,193 @@
+import { createPostgresRoleFreeTransactionLane } from "../data/index.js";
+import { assertOperatorInvitationTtl, invitationFailure } from "./operatorInvitationLifecycle.js";
+const iso = (value) => value instanceof Date ? value.toISOString() : new Date(String(value)).toISOString();
+const role = (value) => value === "distributor" ? "distributor" : "admin";
+const snapshot = (row) => ({ principalId: String(row.principal_id), role: role(row.role) });
+function result(row, code) {
+    return { ...snapshot(row), code, membershipState: "invited", invitationId: String(row.invitation_id), invitedAt: iso(row.invited_at), expiresAt: iso(row.expires_at) };
+}
+async function event(db, action, before, after, actor) {
+    await db.query(`INSERT INTO public.identity_operator_invitation_events
+    (event_id, invitation_id, principal_id, action, actor_kind, actor_principal_id, old_value, new_value, occurred_at)
+    VALUES (gen_random_uuid(), $1, $2, $3, $4, $5, $6::jsonb, $7::jsonb, clock_timestamp())`, [after.invitation_id, after.principal_id, action, actor ? "human" : "system", actor, JSON.stringify(before ?? {}), JSON.stringify(after)]);
+}
+async function lock(db, id) {
+    const principal = (await db.query("SELECT principal_id, email FROM public.platform_human_principals WHERE principal_id = $1", [id])).rows[0];
+    if (!principal)
+        return null;
+    await db.query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)", [`operator_invitation:${String(principal.email).trim().toLowerCase()}`]);
+    return principal;
+}
+async function membership(db, id) {
+    return (await db.query("SELECT * FROM public.platform_human_memberships WHERE principal_id = $1 FOR UPDATE", [id])).rows[0] ?? null;
+}
+async function machine(db, id) {
+    return (await db.query("SELECT EXISTS (SELECT 1 FROM public.platform_control_operators WHERE principal_id = $1) AS present", [id])).rows[0]?.present === true;
+}
+async function lockCommandMemberships(db, actor, target) {
+    // Lock both rows in the same order before taking either actor or target locks.
+    await db.query("SELECT principal_id FROM public.platform_human_memberships WHERE principal_id = ANY($1::uuid[]) ORDER BY principal_id FOR UPDATE", [[actor, target]]);
+}
+async function administrator(db, id) {
+    const row = (await db.query("SELECT role, membership_state FROM public.platform_human_memberships WHERE principal_id = $1 FOR SHARE", [id])).rows[0];
+    if (row?.role !== "admin" || row.membership_state !== "active" || await machine(db, id))
+        throw invitationFailure("HUMAN_ADMIN_REQUIRED", "FORBIDDEN");
+}
+async function invitation(db, id) {
+    const row = (await db.query("SELECT * FROM public.identity_operator_invitations WHERE principal_id = $1 FOR UPDATE", [id])).rows[0];
+    if (!row)
+        return null;
+    // Capture the database clock after serialization; equality is already expired.
+    const expiredNow = (await db.query("SELECT clock_timestamp() >= $1::timestamptz AS expired", [row.expires_at])).rows[0].expired;
+    if (row.phase === "invited" && expiredNow === true) {
+        const expired = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'expired', closed_at = expires_at WHERE principal_id = $1 RETURNING *", [id])).rows[0];
+        await event(db, "expire", row, expired, null);
+        return expired;
+    }
+    return row;
+}
+/** Owner-authority lane, never the actor gateway. One transaction per command. */
+export function createDirectOperatorInvitationStore(env, options = {}) {
+    const lane = createPostgresRoleFreeTransactionLane(env, options);
+    const run = (work) => lane.run((db) => work(db));
+    return {
+        issue(input) {
+            assertOperatorInvitationTtl(input.ttlSeconds);
+            return run(async (db) => {
+                // Serialize same-target commands, then lock both memberships in order.
+                const principal = await lock(db, input.targetPrincipalId);
+                await lockCommandMemberships(db, input.actorPrincipalId, input.targetPrincipalId);
+                await administrator(db, input.actorPrincipalId);
+                if ((await db.query("SELECT 1 FROM public.identity_privacy_erasures WHERE principal_id = $1", [input.targetPrincipalId])).rows.length)
+                    return { code: "IDENTITY_CONFLICT" };
+                const email = input.email.trim().toLowerCase();
+                if (!principal || String(principal.email).trim().toLowerCase() !== email || await machine(db, input.targetPrincipalId))
+                    return { code: "IDENTITY_CONFLICT" };
+                const member = await membership(db, input.targetPrincipalId);
+                if (member?.membership_state === "active")
+                    return { code: "MEMBERSHIP_ALREADY_ACTIVE" };
+                const previous = await invitation(db, input.targetPrincipalId);
+                if (previous?.phase === "invited")
+                    return previous.role === input.role ? result(previous, "ALREADY_INVITED") : { code: "INVITATION_ROLE_CONFLICT" };
+                const collision = (await db.query("SELECT principal_id FROM public.identity_operator_invitations WHERE email_key = $1", [email])).rows[0];
+                if (collision && collision.principal_id !== input.targetPrincipalId)
+                    return { code: "IDENTITY_CONFLICT" };
+                const row = (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, $3, 'invited', $4, stamp.at, stamp.at + $5 * interval '1 second' FROM stamp WHERE true
+          ON CONFLICT (principal_id) DO UPDATE SET invitation_id = EXCLUDED.invitation_id, email_key = EXCLUDED.email_key,
+          role = EXCLUDED.role, phase = 'invited', invited_by = EXCLUDED.invited_by, invited_at = EXCLUDED.invited_at,
+          expires_at = EXCLUDED.expires_at, accepted_at = NULL, closed_at = NULL RETURNING *`, [input.targetPrincipalId, email, input.role, input.actorPrincipalId, input.ttlSeconds])).rows[0];
+                await event(db, previous || member ? "reissue" : "issue", previous, row, input.actorPrincipalId);
+                return result(row, previous || member ? "INVITATION_REISSUED" : "INVITATION_CREATED");
+            });
+        },
+        read(id) {
+            return run(async (db) => {
+                if (!await lock(db, id))
+                    return null;
+                const member = await membership(db, id);
+                if (member?.membership_state === "active")
+                    return { ...snapshot(member), membershipState: "active" };
+                const pending = await invitation(db, id);
+                if (pending && pending.phase !== "accepted")
+                    return { ...snapshot(pending), membershipState: pending.phase === "invited" ? "invited" : pending.phase === "expired" ? "expired" : "revoked" };
+                return member ? { ...snapshot(member), membershipState: "revoked" } : null;
+            });
+        },
+        acceptOperatorInvitation(id) {
+            return run((db) => acceptDirectOperatorInvitationInTransaction(db, id));
+        },
+        remove(input) {
+            return run(async (db) => {
+                const principal = await lock(db, input.targetPrincipalId);
+                await lockCommandMemberships(db, input.actorPrincipalId, input.targetPrincipalId);
+                await administrator(db, input.actorPrincipalId);
+                if (input.actorPrincipalId === input.targetPrincipalId)
+                    throw invitationFailure("SELF_REVOKE_FORBIDDEN", "FORBIDDEN");
+                if (!principal || await machine(db, input.targetPrincipalId))
+                    throw invitationFailure("IDENTITY_CONFLICT");
+                const member = await membership(db, input.targetPrincipalId);
+                const pending = await invitation(db, input.targetPrincipalId);
+                if (pending?.phase === "invited") {
+                    const cancelled = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'cancelled', closed_at = clock_timestamp() WHERE principal_id = $1 RETURNING *", [input.targetPrincipalId])).rows[0];
+                    await event(db, "cancel", pending, cancelled, input.actorPrincipalId);
+                }
+                if (member?.membership_state === "active")
+                    await db.query("SELECT public.platform_revoke_human_membership($1, $2, $3)", [input.actorPrincipalId, input.targetPrincipalId, input.reason ?? null]);
+                if (!member && !pending)
+                    throw invitationFailure("ADMIN_NOT_FOUND", "BAD_REQUEST");
+                return { revoked: true };
+            });
+        },
+        close: lane.close,
+    };
+}
+/** Principal creation commits independently; an invitation failure leaves it reusable. */
+export function createDirectOperatorIdentityDirectory(env, options = {}) {
+    const lane = createPostgresRoleFreeTransactionLane(env, options);
+    return {
+        ensurePrincipal(input) {
+            const email = input.email.trim().toLowerCase();
+            return lane.run(async (executor) => {
+                const db = executor;
+                await db.query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)", [`operator_invitation:${email}`]);
+                const matches = (await db.query("SELECT principal_id FROM public.platform_human_principals WHERE lower(btrim(email)) = $1", [email])).rows;
+                if (matches.length > 1)
+                    throw invitationFailure("IDENTITY_CONFLICT");
+                if (matches[0]) {
+                    const principalId = String(matches[0].principal_id);
+                    if (await machine(db, principalId))
+                        throw invitationFailure("IDENTITY_CONFLICT");
+                    return { principalId, created: false };
+                }
+                const row = (await db.query("INSERT INTO public.platform_human_principals (principal_id, email) VALUES (gen_random_uuid(), $1) RETURNING principal_id", [email])).rows[0];
+                return { principalId: String(row.principal_id), created: true };
+            });
+        },
+        close: lane.close,
+    };
+}
+/** Trusted authentication only; caller owns the transaction, including challenge consumption. */
+export async function acceptDirectOperatorInvitationInTransaction(db, id) {
+    if (!await lock(db, id) || await machine(db, id))
+        return { code: "NO_INVITATION" };
+    if ((await db.query("SELECT 1 FROM public.identity_privacy_erasures WHERE principal_id = $1", [id])).rows.length)
+        return { code: "INVITATION_REVOKED" };
+    const member = await membership(db, id);
+    if (member?.membership_state === "active") {
+        if (member.role !== "admin" && member.role !== "distributor")
+            return { code: "NO_INVITATION" };
+        return { code: "ALREADY_ACTIVE", role: member.role };
+    }
+    const pending = await invitation(db, id);
+    if (!pending)
+        return { code: "NO_INVITATION" };
+    if (pending.phase === "expired")
+        return { code: "INVITATION_EXPIRED" };
+    if (pending.phase !== "invited" || (pending.role !== "admin" && pending.role !== "distributor"))
+        return { code: "INVITATION_REVOKED" };
+    const clock = (await db.query("WITH stamp AS (SELECT clock_timestamp() AS at) SELECT at, at >= $1::timestamptz AS expired FROM stamp", [pending.expires_at])).rows[0];
+    const at = clock.at;
+    if (clock.expired === true) {
+        const expired = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'expired', closed_at = expires_at WHERE principal_id = $1 RETURNING *", [id])).rows[0];
+        await event(db, "expire", pending, expired, null);
+        return { code: "INVITATION_EXPIRED" };
+    }
+    if (member) {
+        const setting = (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_state = 'active', membership_provenance = 'invitation',
+      membership_accepted_at = $2, membership_revoked_at = NULL, membership_revoked_by = NULL, membership_revocation_reason = NULL WHERE principal_id = $1`, [id, at]);
+        await db.query("UPDATE public.platform_human_memberships SET role = $2 WHERE principal_id = $1", [id, pending.role]);
+        await db.query("SELECT set_config('app.platform_human_membership_revoke', $1, true)", [setting ?? ""]);
+    }
+    else {
+        await db.query(`INSERT INTO public.platform_human_memberships (principal_id, role, membership_state, membership_provenance, membership_accepted_at)
+      VALUES ($1, $2, 'active', 'invitation', $3)`, [id, pending.role, at]);
+    }
+    const accepted = (await db.query("UPDATE public.identity_operator_invitations SET phase = 'accepted', accepted_at = $2, closed_at = $2 WHERE principal_id = $1 RETURNING *", [id, at])).rows[0];
+    await event(db, "accept", pending, accepted, id);
+    return { code: "ACTIVATED", role: role(pending.role) };
+}

package/dist/identity/emailTrustPolicy.d.ts

@@ -0,0 +1,14 @@
+import type { EmailTrustFailureCode } from "./contracts/emailTrust.js";
+export type EmailTrustAssessment = {
+    trusted: true;
+} | {
+    trusted: false;
+    code: EmailTrustFailureCode;
+};
+export interface EmailTrustPolicy {
+    assess(): Promise<EmailTrustAssessment>;
+}
+/** Explicitly retain verifier-only admission. This does not bypass mailbox verification. */
+export declare function createVerifierResultOnlyEmailTrustPolicy(): EmailTrustPolicy;
+/** Invalid, absent or throwing JavaScript bindings fail closed, including invalid results. */
+export declare function assessEmailTrust(policy: EmailTrustPolicy): Promise<EmailTrustAssessment>;