@openlup/platform 0.15.0 → 0.16.0

package/dist/identity/postgresPrivacy.js

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

package/dist/identity/privacyHandlers.d.ts

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

package/dist/identity/privacyHandlers.js

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

package/dist/identity/privacyPorts.d.ts

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

package/dist/identity/privacyPorts.js

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

package/dist/identity/privacyUseCases.d.ts

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

package/dist/identity/privacyUseCases.js

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

package/dist/identity/reconcileAccountForPrincipal.d.ts

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

package/dist/identity/reconcileAccountForPrincipal.js

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

package/dist/identity/reconcileAccountHandler.d.ts

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

package/dist/identity/reconcileAccountHandler.js

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

package/dist/identity/removeAdminUserUseCase.d.ts

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

package/dist/identity/removeAdminUserUseCase.js

@@ -0,0 +1,60 @@
+import { identityMessages } from "./messages.js";
+export async function runRemoveAdminUserUseCase(request, gateway, messages = identityMessages.en, invitationStore) {
+    try {
+        if (!request.accessToken) {
+            return { status: 401, body: { code: "UNAUTHORIZED", error: messages.unauthorized } };
+        }
+        const { user, error: authError } = await gateway.getUser(request.accessToken);
+        if (authError || !user) {
+            return { status: 401, body: { code: "INVALID_TOKEN", error: messages.invalidToken } };
+        }
+        const callerAdmin = await gateway.findAdminUser(user.id);
+        if (!callerAdmin || callerAdmin.role !== "admin") {
+            return { status: 403, body: { code: "REMOVE_FORBIDDEN", error: messages.removeForbidden } };
+        }
+        if (!request.userId) {
+            return { status: 400, body: { code: "USER_ID_REQUIRED", error: messages.userIdRequired } };
+        }
+        if (request.userId === user.id) {
+            return { status: 403, body: { code: "SELF_REVOKE_FORBIDDEN", error: messages.selfRemoveForbidden } };
+        }
+        if (invitationStore) {
+            try {
+                await invitationStore.remove({ actorPrincipalId: user.id, targetPrincipalId: request.userId });
+                return { status: 200, body: { revoked: true } };
+            }
+            catch (error) {
+                const failure = error;
+                if (failure.identityCode)
+                    return { status: failure.bffCode === "FORBIDDEN" ? 403 : failure.bffCode === "BAD_REQUEST" ? 400 : 409, body: { code: failure.identityCode, error: failure.identityCode } };
+                return mapRevokeError(failure.message ?? "revoke_failed", messages);
+            }
+        }
+        const { error: revokeError } = await gateway.revokeAdminUser(request.userId);
+        if (revokeError) {
+            return mapRevokeError(revokeError.message, messages);
+        }
+        return { status: 200, body: { revoked: true } };
+    }
+    catch (err) {
+        return { status: 500, body: { code: "IDENTITY_ACTION_FAILED", error: String(err) } };
+    }
+}
+function mapRevokeError(message, messages) {
+    if (message.includes("last_active_human_admin") || message.includes("last_admin_lockout")) {
+        return { status: 409, body: { code: "LAST_ACTIVE_HUMAN_ADMIN", error: messages.lastAdmin } };
+    }
+    if (message.includes("self_revoke_forbidden")) {
+        return { status: 403, body: { code: "SELF_REVOKE_FORBIDDEN", error: messages.selfRevoke } };
+    }
+    if (message.includes("machine_actor_revoke_forbidden")) {
+        return { status: 403, body: { code: "MACHINE_ACTOR_REVOKE_FORBIDDEN", error: messages.machineRevoke } };
+    }
+    if (message.includes("target_not_found") || message.includes("target_not_active")) {
+        return { status: 400, body: { code: "ADMIN_NOT_FOUND", error: messages.adminNotFound } };
+    }
+    if (message.includes("forbidden")) {
+        return { status: 403, body: { code: "ADMIN_REQUIRED", error: messages.adminRequired } };
+    }
+    return { status: 500, body: { code: "REVOKE_FAILED", error: messages.revokeFailed(message) } };
+}

package/dist/identity/response.d.ts

@@ -0,0 +1,3 @@
+import { createBffResponder, type BffResponderOptions } from "../bff/index.js";
+export type IdentityResponseOptions = BffResponderOptions;
+export declare const createIdentityResponder: typeof createBffResponder;

package/dist/identity/response.js

@@ -0,0 +1,2 @@
+import { createBffResponder } from "../bff/index.js";
+export const createIdentityResponder = createBffResponder;

package/dist/identity/sql.d.ts

@@ -0,0 +1,44 @@
+/** A projection of canonical migration units, never a second migration chain. */
+export declare const IDENTITY_MIGRATIONS: readonly [{
+    readonly id: "20260810180001_self_host_actor_auth";
+    readonly catalogPath: "db/platform/migrations/20260810180001_self_host_actor_auth.sql";
+    readonly position: 11;
+    readonly sha256: "84c80d328785151f1fdb5fc4b69220469ffb9c8579054c473ead910a273dfe7b";
+    readonly url: URL;
+}, {
+    readonly id: "20260810204057_customer_identity_read";
+    readonly catalogPath: "db/platform/migrations/20260810204057_customer_identity_read.sql";
+    readonly position: 12;
+    readonly sha256: "1aa626c0187a4ed9d08f152540e0d17c68cd678d2caf3e896ac444b5a38aafe3";
+    readonly url: URL;
+}, {
+    readonly id: "20260814090000_customer_selfservice_recovery";
+    readonly catalogPath: "db/platform/migrations/20260814090000_customer_selfservice_recovery.sql";
+    readonly position: 29;
+    readonly sha256: "ca7f58994533727eb58da148d549ff986fe8f55bb2ffc9eaf61e7d239675ba2e";
+    readonly url: URL;
+}, {
+    readonly id: "20260901143000_admin_membership_authority_foundation";
+    readonly catalogPath: "db/platform/migrations/20260901143000_admin_membership_authority_foundation.sql";
+    readonly position: 60;
+    readonly sha256: "bb4703b669d17e5a0eb4d9a4e8889d12e5286d4b5a813226a77ef2b71df8281f";
+    readonly url: URL;
+}, {
+    readonly id: "20261018120000_identity_operator_invitations";
+    readonly catalogPath: "db/platform/migrations/20261018120000_identity_operator_invitations.sql";
+    readonly position: 67;
+    readonly sha256: "b73034908bd5e27819bcd421d17037a0f00a24aa3df1be1f8f9ca411bf984349";
+    readonly url: URL;
+}, {
+    readonly id: "20261018180000_identity_operator_challenges";
+    readonly catalogPath: "db/platform/migrations/20261018180000_identity_operator_challenges.sql";
+    readonly position: 68;
+    readonly sha256: "191cf0c151a5882ad20d6043624da50afad799df739fff326d67560d3e00a031";
+    readonly url: URL;
+}, {
+    readonly id: "20261018190000_identity_privacy_erasures";
+    readonly catalogPath: "db/platform/migrations/20261018190000_identity_privacy_erasures.sql";
+    readonly position: 69;
+    readonly sha256: "f39b691cb14c0e9ec1a7460d77dc46e16bca4d2448838e4882f78885a6d92351";
+    readonly url: URL;
+}];

package/dist/identity/sql.js

@@ -0,0 +1,10 @@
+/** A projection of canonical migration units, never a second migration chain. */
+export const IDENTITY_MIGRATIONS = [
+    { id: "20260810180001_self_host_actor_auth", catalogPath: "db/platform/migrations/20260810180001_self_host_actor_auth.sql", position: 11, sha256: "84c80d328785151f1fdb5fc4b69220469ffb9c8579054c473ead910a273dfe7b", url: new URL("../../sql/20260810180001_self_host_actor_auth.sql", import.meta.url) },
+    { id: "20260810204057_customer_identity_read", catalogPath: "db/platform/migrations/20260810204057_customer_identity_read.sql", position: 12, sha256: "1aa626c0187a4ed9d08f152540e0d17c68cd678d2caf3e896ac444b5a38aafe3", url: new URL("../../sql/20260810204057_customer_identity_read.sql", import.meta.url) },
+    { id: "20260814090000_customer_selfservice_recovery", catalogPath: "db/platform/migrations/20260814090000_customer_selfservice_recovery.sql", position: 29, sha256: "ca7f58994533727eb58da148d549ff986fe8f55bb2ffc9eaf61e7d239675ba2e", url: new URL("../../sql/20260814090000_customer_selfservice_recovery.sql", import.meta.url) },
+    { id: "20260901143000_admin_membership_authority_foundation", catalogPath: "db/platform/migrations/20260901143000_admin_membership_authority_foundation.sql", position: 60, sha256: "bb4703b669d17e5a0eb4d9a4e8889d12e5286d4b5a813226a77ef2b71df8281f", url: new URL("../../sql/20260901143000_admin_membership_authority_foundation.sql", import.meta.url) },
+    { id: "20261018120000_identity_operator_invitations", catalogPath: "db/platform/migrations/20261018120000_identity_operator_invitations.sql", position: 67, sha256: "b73034908bd5e27819bcd421d17037a0f00a24aa3df1be1f8f9ca411bf984349", url: new URL("../../sql/20261018120000_identity_operator_invitations.sql", import.meta.url) },
+    { id: "20261018180000_identity_operator_challenges", catalogPath: "db/platform/migrations/20261018180000_identity_operator_challenges.sql", position: 68, sha256: "191cf0c151a5882ad20d6043624da50afad799df739fff326d67560d3e00a031", url: new URL("../../sql/20261018180000_identity_operator_challenges.sql", import.meta.url) },
+    { id: "20261018190000_identity_privacy_erasures", catalogPath: "db/platform/migrations/20261018190000_identity_privacy_erasures.sql", position: 69, sha256: "f39b691cb14c0e9ec1a7460d77dc46e16bca4d2448838e4882f78885a6d92351", url: new URL("../../sql/20261018190000_identity_privacy_erasures.sql", import.meta.url) },
+];