@openlup/platform 0.15.0 → 0.17.0

package/dist/identity/emailTrustPolicy.js

@@ -0,0 +1,16 @@
+/** Explicitly retain verifier-only admission. This does not bypass mailbox verification. */
+export function createVerifierResultOnlyEmailTrustPolicy() {
+    return { async assess() { return { trusted: true }; } };
+}
+/** Invalid, absent or throwing JavaScript bindings fail closed, including invalid results. */
+export async function assessEmailTrust(policy) {
+    try {
+        const result = await policy.assess();
+        if (result?.trusted === true)
+            return { trusted: true };
+        if (result?.trusted === false && result.code === "EMAIL_TRUST_ENVELOPE_REFUSED")
+            return result;
+    }
+    catch { /* Do not expose policy or transport details. */ }
+    return { trusted: false, code: "EMAIL_TRUST_SETTINGS_UNAVAILABLE" };
+}

package/dist/identity/identityPersonalDataContributor.d.ts

@@ -0,0 +1,7 @@
+import type { PersonalDataObligation } from "./contracts/privacy.js";
+import { type PersonalDataContributor, type PrivacyStore } from "./privacyPorts.js";
+export interface IdentityPrivacyPolicy {
+    /** Explicit dispositions for populated opaque contact fields; absence refuses erasure. */
+    retainedContactFields: Readonly<Record<string, PersonalDataObligation>>;
+}
+export declare function createIdentityPersonalDataContributor<C>(store: PrivacyStore<C>, policy: IdentityPrivacyPolicy, randomId: () => string): PersonalDataContributor<C>;

package/dist/identity/identityPersonalDataContributor.js

@@ -0,0 +1,46 @@
+import { PrivacyRefusal } from "./privacyPorts.js";
+const owned = new Set(["id", "email", "first_name", "last_name", "phone", "country", "principal_id", "created_at", "updated_at"]);
+const populated = (value) => value !== null && value !== "" && !(typeof value === "object" && Object.keys(value).length === 0);
+export function createIdentityPersonalDataContributor(store, policy, randomId) {
+    function obligations(identity) {
+        const contact = identity.contact;
+        const result = [{ owner: "identity", resource: "identity.audit-and-receipt", disposition: "retain", reasonCode: "PSEUDONYMOUS_AUDIT", remote: false }];
+        if (contact && typeof contact === "object" && !Array.isArray(contact)) {
+            for (const [key, value] of Object.entries(contact)) {
+                if (owned.has(key) || !populated(value))
+                    continue;
+                const declaration = policy.retainedContactFields[key];
+                result.push(declaration?.disposition === "retain" && declaration.resource === `clients.${key}` ? declaration : { owner: "unassigned", resource: `clients.${key}`, disposition: "unresolved", reasonCode: "PRIVACY_OWNERSHIP_UNDECLARED", remote: false });
+            }
+        }
+        return result;
+    }
+    return {
+        id: "identity", version: "identity.personal-data.v1",
+        ownedResources: ["identity.contact-profile", "identity.principal", "identity.membership", "identity.invitations", "identity.audit-and-receipt"],
+        async prepareErasure() { },
+        async export(_context, subject) {
+            const unavailable = Array.isArray(subject.identity.unavailable) ? subject.identity.unavailable.map(String) : [];
+            const data = { ...subject.identity };
+            const contact = data.contact;
+            if (contact && typeof contact === "object" && !Array.isArray(contact)) {
+                data.contact = Object.fromEntries(Object.entries(contact).filter(([key]) => owned.has(key) || key === "auth_user_id"));
+                for (const key of Object.keys(contact))
+                    if (!owned.has(key) && key !== "auth_user_id")
+                        unavailable.push(`contact.${key}`);
+            }
+            return { contributorId: "identity", version: "identity.personal-data.v1", data,
+                coverage: { complete: unavailable.length === 0, included: Object.keys(subject.identity).filter(k => k !== "unavailable"), unavailable }, obligations: obligations(subject.identity) };
+        },
+        async assessErasure(_context, subject) {
+            const declared = obligations(subject.identity);
+            if (declared.some(o => o.disposition === "unresolved"))
+                throw new PrivacyRefusal("PRIVACY_OWNERSHIP_UNDECLARED");
+            return { obligations: declared };
+        },
+        async eraseOrRetain(context, subject, assessment, actor) {
+            await store.eraseIdentity(context, subject, actor, `erased+${randomId()}@identity.invalid`);
+            return { contributorId: "identity", version: "identity.personal-data.v1", obligations: assessment.obligations };
+        },
+    };
+}

package/dist/identity/identityReadiness.d.ts

@@ -0,0 +1,10 @@
+import type { ReadinessIssue } from "@openlup/core/readiness";
+import { type EmailTrustPolicy } from "./emailTrustPolicy.js";
+/** The module field stays structural so older core readiness types still compile; no new core code is needed. */
+export declare function identityEmailTrustReadiness(policy: EmailTrustPolicy): Promise<readonly (ReadinessIssue & {
+    module: "identity";
+})[]>;
+/** Discovery and fresh key availability are independent readiness observations. */
+export declare function identityOidcReadiness(verifier: import("./oidcIdentityVerifier.js").OidcIdentityVerifier): Promise<readonly (ReadinessIssue & {
+    module: "identity";
+})[]>;

package/dist/identity/identityReadiness.js

@@ -0,0 +1,25 @@
+import { assessEmailTrust } from "./emailTrustPolicy.js";
+/** The module field stays structural so older core readiness types still compile; no new core code is needed. */
+export async function identityEmailTrustReadiness(policy) {
+    const result = await assessEmailTrust(policy);
+    if (result.trusted)
+        return [];
+    return [{
+            code: "OPENLUP_E_PORT_MISSING", package: "@openlup/platform", module: "identity",
+            subject: "emailTrustPolicy", observation: result.code,
+            fix: result.code === "EMAIL_TRUST_ENVELOPE_REFUSED"
+                ? "Disable automatic confirmation and declare only providers that verify email."
+                : "Restore access to valid public identity settings or bind an explicit email-trust policy.",
+        }];
+}
+/** Discovery and fresh key availability are independent readiness observations. */
+export async function identityOidcReadiness(verifier) {
+    const report = await verifier.readiness();
+    if (report.state === "ready")
+        return [];
+    return [
+        ...(!report.discovery.valid ? ["oidcDiscovery"] : []),
+        ...(!report.jwks.loaded ? ["oidcJwks"] : []),
+    ].map(subject => ({ code: "OPENLUP_E_PORT_MISSING", package: "@openlup/platform", module: "identity", subject,
+        observation: report.code ?? "OIDC_JWKS_INVALID", fix: "Restore valid issuer discovery and fresh same-origin signing keys." }));
+}

package/dist/identity/index.d.ts

@@ -0,0 +1,67 @@
+export * from "./adminMagicLinkHandler.js";
+export * from "./reconcileAccountForPrincipal.js";
+export * from "./customerVerifyOtpHandler.js";
+export * from "./authVerifyUrl.js";
+export * from "./customerIdentityVerifier.js";
+export * from "./operatorTokenAdminAuth.js";
+export * from "./managedIdentityVerifier.js";
+export * from "./managedAdminAuthVerifier.js";
+export * from "./managedCustomerMe.js";
+export * from "./sql.js";
+export * from "./customerMeHandler.js";
+export * from "./messages.js";
+export * from "./managedAccountLinkStore.js";
+export * from "./customerIdentityBinding.js";
+export * from "./adminUserActionPorts.js";
+export * from "./contribution.js";
+export * from "./customerContracts.js";
+export * from "./machineActorWriteFence.js";
+export * from "./managedClient.js";
+export * from "./customerAuthorization.js";
+export * from "./customerSessionIssuer.js";
+export * from "./managedClientAuthLink.js";
+export * from "./customerAuth.js";
+export * from "./reconcileAccountHandler.js";
+export * from "./postgresCustomerMe.js";
+export * from "./ports.js";
+export * from "./postgresCustomerRecovery.js";
+export * from "./customerMagicLinkHandler.js";
+export * from "./customerSessionBinding.js";
+export * from "./adminUserHandlers.js";
+export * from "./adminPreflight.js";
+export * from "./adminAuthBinding.js";
+export * from "./customerPorts.js";
+export * from "./magicLinkPorts.js";
+export * from "./inviteAdminUserUseCase.js";
+export * from "./adminAuthorization.js";
+export * from "./removeAdminUserUseCase.js";
+export * from "./adminMeHandler.js";
+export * from "./managedAdminUserGateways.js";
+export * from "./jwtLibrary.js";
+export * from "./platformAdminAuth.js";
+export * from "./adminContracts.js";
+export * from "./contracts/emailTrust.js";
+export { createVerifierResultOnlyEmailTrustPolicy } from "./emailTrustPolicy.js";
+export type { EmailTrustAssessment, EmailTrustPolicy } from "./emailTrustPolicy.js";
+export * from "./managedEmailTrustPolicy.js";
+export * from "./identityReadiness.js";
+export * from "./operatorInvitationPorts.js";
+export * from "./operatorInvitationLifecycle.js";
+export * from "./directOperatorInvitationStore.js";
+export * from "./operatorPorts.js";
+export * from "./operatorSession.js";
+export * from "./operatorIdentityVerifier.js";
+export * from "./operatorAdminAuth.js";
+export * from "./operatorAuthHandlers.js";
+export * from "./postgresOperatorIdentity.js";
+export * from "./privacyPorts.js";
+export * from "./personalDataRegistry.js";
+export * from "./privacyUseCases.js";
+export * from "./identityPersonalDataContributor.js";
+export * from "./postgresPrivacy.js";
+export * from "./managedPrivacy.js";
+export * from "./privacyHandlers.js";
+export * from "./oidcIdentityVerifier.js";
+export * from "./oidcPrincipal.js";
+export * from "./postgresAccountLinkStore.js";
+export * from "./contracts/oidc.js";

package/dist/identity/index.js

@@ -0,0 +1,66 @@
+export * from "./adminMagicLinkHandler.js";
+export * from "./reconcileAccountForPrincipal.js";
+export * from "./customerVerifyOtpHandler.js";
+export * from "./authVerifyUrl.js";
+export * from "./customerIdentityVerifier.js";
+export * from "./operatorTokenAdminAuth.js";
+export * from "./managedIdentityVerifier.js";
+export * from "./managedAdminAuthVerifier.js";
+export * from "./managedCustomerMe.js";
+export * from "./sql.js";
+export * from "./customerMeHandler.js";
+export * from "./messages.js";
+export * from "./managedAccountLinkStore.js";
+export * from "./customerIdentityBinding.js";
+export * from "./adminUserActionPorts.js";
+export * from "./contribution.js";
+export * from "./customerContracts.js";
+export * from "./machineActorWriteFence.js";
+export * from "./managedClient.js";
+export * from "./customerAuthorization.js";
+export * from "./customerSessionIssuer.js";
+export * from "./managedClientAuthLink.js";
+export * from "./customerAuth.js";
+export * from "./reconcileAccountHandler.js";
+export * from "./postgresCustomerMe.js";
+export * from "./ports.js";
+export * from "./postgresCustomerRecovery.js";
+export * from "./customerMagicLinkHandler.js";
+export * from "./customerSessionBinding.js";
+export * from "./adminUserHandlers.js";
+export * from "./adminPreflight.js";
+export * from "./adminAuthBinding.js";
+export * from "./customerPorts.js";
+export * from "./magicLinkPorts.js";
+export * from "./inviteAdminUserUseCase.js";
+export * from "./adminAuthorization.js";
+export * from "./removeAdminUserUseCase.js";
+export * from "./adminMeHandler.js";
+export * from "./managedAdminUserGateways.js";
+export * from "./jwtLibrary.js";
+export * from "./platformAdminAuth.js";
+export * from "./adminContracts.js";
+export * from "./contracts/emailTrust.js";
+export { createVerifierResultOnlyEmailTrustPolicy } from "./emailTrustPolicy.js";
+export * from "./managedEmailTrustPolicy.js";
+export * from "./identityReadiness.js";
+export * from "./operatorInvitationPorts.js";
+export * from "./operatorInvitationLifecycle.js";
+export * from "./directOperatorInvitationStore.js";
+export * from "./operatorPorts.js";
+export * from "./operatorSession.js";
+export * from "./operatorIdentityVerifier.js";
+export * from "./operatorAdminAuth.js";
+export * from "./operatorAuthHandlers.js";
+export * from "./postgresOperatorIdentity.js";
+export * from "./privacyPorts.js";
+export * from "./personalDataRegistry.js";
+export * from "./privacyUseCases.js";
+export * from "./identityPersonalDataContributor.js";
+export * from "./postgresPrivacy.js";
+export * from "./managedPrivacy.js";
+export * from "./privacyHandlers.js";
+export * from "./oidcIdentityVerifier.js";
+export * from "./oidcPrincipal.js";
+export * from "./postgresAccountLinkStore.js";
+export * from "./contracts/oidc.js";

package/dist/identity/inviteAdminUserUseCase.d.ts

@@ -0,0 +1,89 @@
+import type { ManagedOperatorMembershipResult, OperatorInvitationConflict } from "./contracts/operatorInvitations.js";
+import type { OperatorInvitationStore } from "./operatorInvitationPorts.js";
+import { type IdentityMessages } from "./messages.js";
+export type AdminUserInviteRole = "admin" | "distributor";
+export declare const ADMIN_ROLE_NOTIFICATION_LOCALE: "en";
+export type AdminRoleNotificationSkipReason = "admin_disabled" | "egress_suppressed";
+export type InviteAdminUserResponse = {
+    [key: string]: unknown;
+    success?: boolean;
+    message?: string;
+    error?: string;
+    code?: string;
+    deliveryReference?: string | null;
+    deliveryReferencePresent?: boolean;
+};
+export interface InviteAdminUserGateway {
+    getUser: (accessToken: string) => Promise<{
+        user: {
+            id: string;
+        } | null;
+        error: unknown;
+    }>;
+    findAdminUser: (userId: string) => Promise<{
+        id: string;
+        role: string;
+        membership_state: string;
+        is_machine_actor: boolean;
+    } | null>;
+    findAdminUserByEmail: (email: string) => Promise<{
+        id: string;
+    } | null>;
+    findAuthUserByEmail: (email: string) => Promise<{
+        id: string;
+        email?: string | null;
+    } | null>;
+    inviteAuthUser: (input: {
+        email: string;
+        redirectTo: string;
+        role: AdminUserInviteRole;
+    }) => Promise<{
+        user: {
+            id: string;
+        } | null;
+        error: {
+            message: string;
+        } | null;
+    }>;
+}
+export interface AdminRoleNotificationPort {
+    sendRoleGranted: (input: {
+        email: string;
+        authUserId: string;
+        role: AdminUserInviteRole;
+        locale: "pl" | "en";
+        invitationId?: string;
+        expiresAt?: string;
+    }) => Promise<{
+        ok: boolean;
+        providerMessageId: string | null;
+        providerError: string | null;
+        skipped: boolean;
+        skipReason: AdminRoleNotificationSkipReason | null;
+    }>;
+}
+export declare function runInviteAdminUserUseCase(request: {
+    accessToken: string | null;
+    email: string;
+    role: string;
+}, deps: {
+    gateway: InviteAdminUserGateway;
+    roleNotificationPort: AdminRoleNotificationPort;
+    siteUrl: string;
+    messages?: IdentityMessages;
+    notificationLocale?: "pl" | "en";
+} & ({
+    invitationStore: OperatorInvitationStore;
+    ttlSeconds: number;
+} | {
+    activateMembership: (input: {
+        principalId: string;
+        email: string;
+        role: AdminUserInviteRole;
+    }) => Promise<ManagedOperatorMembershipResult | {
+        code: OperatorInvitationConflict;
+    }>;
+})): Promise<{
+    status: number;
+    body: InviteAdminUserResponse;
+}>;

package/dist/identity/inviteAdminUserUseCase.js

@@ -0,0 +1,75 @@
+import { assertOperatorInvitationTtl } from "./operatorInvitationLifecycle.js";
+import { identityMessages } from "./messages.js";
+export const ADMIN_ROLE_NOTIFICATION_LOCALE = "en";
+export async function runInviteAdminUserUseCase(request, deps) {
+    const messages = deps.messages ?? identityMessages.en;
+    try {
+        if ("invitationStore" in deps)
+            assertOperatorInvitationTtl(deps.ttlSeconds);
+        if (!request.accessToken) {
+            return { status: 401, body: { code: "UNAUTHORIZED", error: messages.unauthorized } };
+        }
+        const { user, error: authError } = await deps.gateway.getUser(request.accessToken);
+        if (authError || !user) {
+            return { status: 401, body: { code: "INVALID_TOKEN", error: messages.invalidToken } };
+        }
+        const callerAdmin = await deps.gateway.findAdminUser(user.id);
+        if (!callerAdmin || callerAdmin.role !== "admin" || callerAdmin.membership_state !== "active" || callerAdmin.is_machine_actor !== false) {
+            return { status: 403, body: { code: "INVITE_FORBIDDEN", error: messages.inviteForbidden } };
+        }
+        if (!request.email) {
+            return { status: 400, body: { code: "EMAIL_REQUIRED", error: messages.emailRequired } };
+        }
+        if (!isInviteRole(request.role)) {
+            return { status: 400, body: { code: "INVALID_ROLE", error: messages.invalidRole } };
+        }
+        const role = request.role;
+        const email = request.email.trim().toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+            return { status: 400, body: { code: "INVALID_EMAIL", error: "Invalid email" } };
+        const existingMembership = await deps.gateway.findAdminUserByEmail(email);
+        let principal = await deps.gateway.findAuthUserByEmail(email);
+        if (existingMembership && existingMembership.id !== principal?.id)
+            return { status: 409, body: { code: "IDENTITY_CONFLICT", error: "IDENTITY_CONFLICT" } };
+        if (!principal) {
+            const invite = await deps.gateway.inviteAuthUser({ email, role, redirectTo: new URL("/admin/auth/callback", deps.siteUrl).toString() });
+            if (invite.error || !invite.user) {
+                // A provider duplicate race reuses the durable identity. Never delete it.
+                principal = await deps.gateway.findAuthUserByEmail(email);
+                if (!principal)
+                    throw new Error("operator_identity_creation_failed");
+            }
+            else
+                principal = invite.user;
+        }
+        const issued = "invitationStore" in deps
+            ? await deps.invitationStore.issue({ actorPrincipalId: user.id, targetPrincipalId: principal.id, email, role, ttlSeconds: deps.ttlSeconds })
+            : await deps.activateMembership({ principalId: principal.id, email, role });
+        if (!("membershipState" in issued))
+            return { status: 409, body: { code: issued.code, error: issued.code } };
+        let delivery = {};
+        if (issued.code !== "ALREADY_INVITED" && issued.code !== "ALREADY_ACTIVE") {
+            try {
+                const notification = await deps.roleNotificationPort.sendRoleGranted({ email, authUserId: principal.id, role, locale: deps.notificationLocale ?? ADMIN_ROLE_NOTIFICATION_LOCALE, ...(issued.membershipState === "invited" ? { invitationId: issued.invitationId, expiresAt: issued.expiresAt } : {}) });
+                if (!notification.ok)
+                    throw new Error("operator_invitation_notification_failed");
+                delivery = { deliveryReference: notification.skipped ? null : notification.providerMessageId, deliveryReferencePresent: !notification.skipped && Boolean(notification.providerMessageId) };
+            }
+            catch {
+                return { status: 503, body: issued.membershipState === "invited"
+                        ? { code: "INVITATION_NOTIFICATION_FAILED", error: "Invitation persisted; notification unavailable", invitationId: issued.invitationId }
+                        : { ...issued, code: "INVITATION_NOTIFICATION_FAILED", error: "Membership active; notification unavailable" } };
+            }
+        }
+        return { status: 200, body: { success: true, ...issued, ...delivery, message: issued.membershipState === "invited" ? `Invitation pending until ${issued.expiresAt}` : "Operator membership active" } };
+    }
+    catch (err) {
+        const failure = err;
+        if (failure.identityCode)
+            return { status: failure.bffCode === "FORBIDDEN" ? 403 : 409, body: { code: failure.identityCode, error: failure.identityCode } };
+        return { status: 503, body: { code: "IDENTITY_ACTION_FAILED", error: String(err) } };
+    }
+}
+function isInviteRole(value) {
+    return value === "admin" || value === "distributor";
+}

package/dist/identity/jwtLibrary.d.ts

@@ -0,0 +1,54 @@
+export interface IdentityJwk {
+    [key: string]: unknown;
+    kty?: string;
+    alg?: string;
+    crv?: string;
+    kid?: string;
+    use?: string;
+    x?: string;
+    y?: string;
+    d?: string;
+}
+type Key = CryptoKey | Uint8Array;
+interface Signer {
+    setProtectedHeader(header: {
+        alg: string;
+        kid: string;
+        typ: string;
+    }): Signer;
+    setSubject(value: string): Signer;
+    setIssuer(value: string): Signer;
+    setAudience(value: string): Signer;
+    setIssuedAt(value: number): Signer;
+    setExpirationTime(value: number): Signer;
+    sign(key: Key): Promise<string>;
+}
+/** The host loads its selected JWT implementation only for the selected adapter. */
+export interface IdentityJwtLibrary {
+    importJWK(jwk: IdentityJwk, alg: string): Promise<Key>;
+    jwtVerify(token: string, key: (header: {
+        alg?: string;
+        kid?: string;
+    }) => Promise<Key>, options: {
+        algorithms: string[];
+        audience: string;
+        issuer: string;
+        currentDate?: Date;
+        clockTolerance?: number;
+    }): Promise<{
+        payload: IdentityJwtClaims;
+    }>;
+    SignJWT: new (payload: Record<string, unknown>) => Signer;
+}
+export type IdentityJwtLibraryLoader = () => Promise<IdentityJwtLibrary>;
+/** Claims returned only after signature verification by the host library. */
+export interface IdentityJwtClaims {
+    [claim: string]: unknown;
+    sub?: string;
+    iss?: string;
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+}
+export {};

package/dist/identity/jwtLibrary.js

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

package/dist/identity/machineActorWriteFence.d.ts

@@ -0,0 +1,4 @@
+import type { HttpResponse } from "../http/index.js";
+import { type IdentityResponseOptions } from "./response.js";
+export declare function refusesMachineActorRequest(route: string, method: string | undefined, isMachineActor: boolean | undefined, writeRoutes?: readonly string[]): boolean;
+export declare function sendMachineActorWriteRefused(res: HttpResponse, options?: IdentityResponseOptions): void;

package/dist/identity/machineActorWriteFence.js

@@ -0,0 +1,13 @@
+import { createIdentityResponder } from "./response.js";
+export function refusesMachineActorRequest(route, method, isMachineActor, writeRoutes = []) {
+    if (isMachineActor === false)
+        return false;
+    const verb = (method ?? "").toUpperCase();
+    return verb !== "GET" && verb !== "HEAD" && !writeRoutes.includes(route);
+}
+export function sendMachineActorWriteRefused(res, options = {}) {
+    const { sendBffError } = createIdentityResponder(options);
+    sendBffError(res, "FORBIDDEN", "Human operator required", {
+        details: { reason: "machine_actor_write_refused" },
+    });
+}

package/dist/identity/magicLinkPorts.d.ts

@@ -0,0 +1,28 @@
+export interface MagicLinkAuthClient {
+    auth: {
+        signInWithOtp(input: {
+            email: string;
+            options: {
+                shouldCreateUser: false;
+                emailRedirectTo: string;
+            };
+        }): Promise<{
+            error: {
+                name?: string;
+                message?: string;
+            } | null;
+        }>;
+    };
+}
+export interface MagicLinkRateLimitClient {
+    rpc(fn: string, args: Record<string, unknown>): Promise<{
+        data: unknown;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+}
+export interface MagicLinkDecision {
+    allowed: boolean;
+    reason?: string;
+}

package/dist/identity/magicLinkPorts.js

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

package/dist/identity/managedAccountLinkStore.d.ts

@@ -0,0 +1,2 @@
+import type { AccountLinkStore } from "./ports.js";
+export declare function createSupabaseAccountLinkStore(rawClient: unknown): AccountLinkStore;

package/dist/identity/managedAccountLinkStore.js

@@ -0,0 +1,93 @@
+export function createSupabaseAccountLinkStore(rawClient) {
+    const client = rawClient;
+    return {
+        async findAccountByPrincipalId(principalId) {
+            const { data, error } = await client
+                .from("clients")
+                .select("id, email, auth_user_id")
+                .eq("auth_user_id", principalId)
+                .maybeSingle();
+            if (error)
+                throw error;
+            if (!data)
+                return null;
+            return { id: data.id, email: data.email ?? null, principalId: data.auth_user_id ?? null };
+        },
+        async findAccountByEmail(email) {
+            const rows = await findManagedContactsByEmail(client, email, false);
+            if (rows.length > 1) {
+                throw Object.assign(new Error("multiple rows returned"), { code: "PGRST116" });
+            }
+            const data = rows[0];
+            if (!data)
+                return null;
+            return { id: data.id, email: data.email ?? null, principalId: data.auth_user_id ?? null };
+        },
+        async isReservedPrincipal(principalId) {
+            const { data, error } = await client
+                .from("admin_users")
+                .select("id, is_machine_actor")
+                .eq("id", principalId)
+                .maybeSingle();
+            if (error)
+                throw error;
+            if (!data)
+                return false;
+            return data.is_machine_actor !== false;
+        },
+        async linkPrincipalToAccount(accountId, principalId) {
+            const { data, error } = await client
+                .from("clients")
+                .update({ auth_user_id: principalId })
+                .eq("id", accountId)
+                .is("auth_user_id", null)
+                .select("auth_user_id")
+                .maybeSingle();
+            if (error)
+                throw error;
+            if (data?.auth_user_id === principalId) {
+                return { ok: true, alreadyLinked: false };
+            }
+            const { data: current, error: currentError } = await client
+                .from("clients")
+                .select("auth_user_id")
+                .eq("id", accountId)
+                .maybeSingle();
+            if (currentError)
+                throw currentError;
+            if (current?.auth_user_id === principalId) {
+                return { ok: true, alreadyLinked: true };
+            }
+            return { ok: false, existingPrincipalId: current?.auth_user_id ?? null };
+        },
+        async createAccount(input) {
+            const { data, error } = await client
+                .from("clients")
+                .insert({
+                email: input.email,
+                auth_user_id: input.principalId,
+                acquisition_source: input.acquisitionSource,
+                lifecycle_stage: input.lifecycleStage,
+            })
+                .select("id")
+                .single();
+            if (error)
+                throw error;
+            return { id: data.id };
+        },
+    };
+}
+async function findManagedContactsByEmail(client, email, oldestFirst) {
+    const normalized = email.trim().toLowerCase();
+    // Escaping bounds the database prefilter; Unicode regex folding can still
+    // widen it, so only exact normalized addresses may cross this boundary.
+    let query = client.from("clients")
+        .select("id, email, auth_user_id")
+        .filter("email", "imatch", `^${normalized.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&")}$`);
+    if (oldestFirst)
+        query = query.order("created_at", { ascending: true });
+    const { data, error } = await query.limit(10);
+    if (error)
+        throw error;
+    return (data ?? []).filter((row) => row.email?.trim().toLowerCase() === normalized);
+}

package/dist/identity/managedAdminAuthVerifier.d.ts

@@ -0,0 +1,7 @@
+import type { SupabaseCreateClient } from "../data/index.js";
+import type { AdminAuthPort } from "./ports.js";
+export declare function createSupabaseAdminAuth(rawClient: unknown): AdminAuthPort;
+export declare function createSupabaseAdminAuthFromEnv(env: {
+    url: string;
+    anonKey: string;
+}, accessToken: string | null, createClient: SupabaseCreateClient): AdminAuthPort;

package/dist/identity/managedAdminAuthVerifier.js

@@ -0,0 +1,27 @@
+import { authorizeAdminWithUser } from "./adminAuthorization.js";
+export function createSupabaseAdminAuth(rawClient) {
+    const client = rawClient;
+    return {
+        async authorize(accessToken, options) {
+            const authz = await authorizeAdminWithUser(client, accessToken, options);
+            if (authz.ok === false) {
+                return { ok: false, code: authz.code, message: authz.message };
+            }
+            return {
+                ok: true,
+                principalId: authz.userId,
+                role: authz.role,
+                isMachineActor: authz.isMachineActor,
+            };
+        },
+    };
+}
+export function createSupabaseAdminAuthFromEnv(env, accessToken, createClient) {
+    const client = createClient(env.url, env.anonKey, {
+        auth: { persistSession: false, autoRefreshToken: false },
+        global: {
+            headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
+        },
+    });
+    return createSupabaseAdminAuth(client);
+}