@openlup/platform 0.0.0 → 0.16.0

package/src/identity/authVerifyUrl.ts

@@ -0,0 +1,56 @@
+import type { HttpRequest } from "../http/index.js";
+
+function authVerifyType(actionType: string): string {
+  return actionType === "email_change_current" || actionType === "email_change_new"
+    ? "email_change"
+    : actionType;
+}
+
+
+function qpSafeTokenValue(token: string): string {
+  if (token.length === 0) return token;
+  return `%${token.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}${encodeURIComponent(token.slice(1))}`;
+}
+
+export function buildAuthVerifyUrl(authServiceUrl: string, actionType: string, tokenHash: string, redirectTo: string): string {
+  const params = new URLSearchParams({ type: authVerifyType(actionType), redirect_to: redirectTo });
+  return `${authServiceUrl.replace(/\/+$/, "")}/auth/v1/verify?token=${qpSafeTokenValue(tokenHash)}&${params.toString()}`;
+}
+
+/** Only configured HTTP(S) origins authorize the default magic-link destination. */
+export function createMagicLinkOriginResolver(
+  configuredOrigins: readonly string[],
+): (req: HttpRequest) => string | null {
+  const origins = configuredOrigins.map(normalizeOrigin);
+  const origin = origins.length > 0 && origins.every((value) => value !== null)
+    ? (origins[0] ?? null)
+    : null;
+  return () => origin;
+}
+
+function normalizeOrigin(value: string): string | null {
+  const candidate = value.trim();
+  // URL parsing alone accepts paths, credentials and repaired backslashes.
+  if (!/^https?:\/\/[^/?#\\\s]+\/?$/i.test(candidate)) return null;
+  try {
+    const url = new URL(candidate);
+    if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Invalid return targets use the callback's default landing page. */
+export function normalizeMagicLinkReturnPath(value: string | undefined, origin: string): string | undefined {
+  if (!value || !value.startsWith("/") || value.startsWith("//")) return undefined;
+  // Reject encoded separators, controls and nested escapes before any later decoding.
+  if (value.includes("\\") || Array.from(value).some((character) => character.charCodeAt(0) <= 0x20 || character.charCodeAt(0) === 0x7f) || /%(?:2f|5c|0[0-9a-f]|1[0-9a-f]|7f|25)/i.test(value)) return undefined;
+  try {
+    const url = new URL(value, origin);
+    if (url.origin !== new URL(origin).origin || url.pathname.startsWith("//")) return undefined;
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return undefined;
+  }
+}

package/src/identity/contracts/contracts.ts

@@ -0,0 +1,15 @@
+import type { EmailTrustFailureCode } from "./emailTrust.js";
+export const AUTH_RECONCILE_CONTRACT_VERSION = "auth.reconcile.v1" as const;
+export interface AuthReconcileResponse {
+  accountId: string;
+  created: boolean;
+  linked: boolean;
+}
+export type AuthReconcileErrorCode =
+  | EmailTrustFailureCode
+  | "NO_VERIFIED_EMAIL"
+  | "RESERVED_PRINCIPAL_REFUSED"
+  | "ACCOUNT_LINK_CONFLICT"
+  | "EMAIL_OWNED_BY_OTHER_PRINCIPAL"
+  | "PRINCIPAL_EMAIL_MISMATCH";
+// Runtime schemas remain in reference composition until the validator boundary is resolved.

package/src/identity/contracts/emailTrust.ts

@@ -0,0 +1,5 @@
+/** Browser-safe email-association refusal codes. */
+export const EMAIL_TRUST_FAILURE_CODES = [
+  "EMAIL_TRUST_ENVELOPE_REFUSED", "EMAIL_TRUST_SETTINGS_UNAVAILABLE",
+] as const;
+export type EmailTrustFailureCode = typeof EMAIL_TRUST_FAILURE_CODES[number];

package/src/identity/contracts/index.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./ports.js";
+export * from "./providerList.js";
+export * from "./contracts.js";
+export * from "./emailTrust.js";
+export * from "./operatorInvitations.js";
+export * from "./operatorAuth.js";
+export * from "./privacy.js";

package/src/identity/contracts/oidc.ts

@@ -0,0 +1,10 @@
+/** Credential and dependency refusals; no token or transport details are exposed. */
+export const OIDC_FAILURE_CODES = [
+  "OIDC_CONFIGURATION_INVALID", "OIDC_DISCOVERY_UNAVAILABLE", "OIDC_DISCOVERY_INVALID",
+  "OIDC_JWKS_UNAVAILABLE", "OIDC_JWKS_INVALID", "OIDC_JWKS_REFRESH_RATE_LIMITED",
+  "OIDC_JWT_LIBRARY_UNAVAILABLE", "OIDC_TOKEN_INVALID", "OIDC_KID_UNKNOWN",
+  "OIDC_ISSUER_MISMATCH", "OIDC_AUDIENCE_MISMATCH", "OIDC_TOKEN_EXPIRED",
+  "OIDC_TOKEN_NOT_ACTIVE", "OIDC_TOKEN_LIFETIME_INVALID", "OIDC_SUBJECT_INVALID",
+  "OIDC_EMAIL_INVALID", "OIDC_EMAIL_UNVERIFIED", "OIDC_NATIVE_SESSION_REQUIRED",
+] as const;
+export type OidcFailureCode = typeof OIDC_FAILURE_CODES[number];

package/src/identity/contracts/operatorAuth.ts

@@ -0,0 +1,61 @@
+export interface OperatorSession {
+  accessToken: string;
+  expiresAt: string;
+  user: { id: string; email: string };
+}
+export interface OperatorChallengeRequest { email: string }
+export interface OperatorChallengeVerification { token: string }
+export interface OperatorBrowserAuthPort {
+  getSession(): Promise<OperatorSession | null>;
+  requestChallenge(email: string): Promise<void>;
+  verifyChallenge(token: string): Promise<OperatorSession>;
+  signOut(): Promise<void>;
+  onAuthStateChange(listener: (session: OperatorSession | null) => void): () => void;
+}
+/** Strict parsers keep the contracts entry independent of the server validator. */
+export interface OperatorSchema<T> {
+  parse(value: unknown): T;
+  safeParse(value: unknown): { success: true; data: T } | { success: false; error: Error };
+}
+function schema<T>(parse: (value: unknown) => T): OperatorSchema<T> {
+  return { parse, safeParse(value) {
+    try { return { success: true, data: parse(value) }; }
+    catch { return { success: false, error: new Error("operator_contract_invalid") }; }
+  } };
+}
+function fields(value: unknown, keys: string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).length !== keys.length || !keys.every(key => Object.hasOwn(value, key))) throw new Error("operator_contract_invalid");
+  return value as Record<string, unknown>;
+}
+function email(value: unknown): string {
+  if (typeof value !== "string" || value.length > 320 || !/^[a-z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i.test(value)) throw new Error("operator_email_invalid");
+  return value;
+}
+export const operatorChallengeRequestSchema: OperatorSchema<OperatorChallengeRequest> = schema(value => {
+  const row = fields(value, ["email"]);
+  if (typeof row.email !== "string") throw new Error("operator_email_invalid");
+  return { email: email(row.email.trim().toLowerCase()) };
+});
+export const operatorChallengeVerificationSchema: OperatorSchema<OperatorChallengeVerification> = schema(value => {
+  const row = fields(value, ["token"]);
+  if (typeof row.token !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(row.token)) throw new Error("operator_token_invalid");
+  return { token: row.token };
+});
+function timestamp(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const parts = /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.exec(value);
+  if (!parts || !Number.isFinite(Date.parse(value))) return false;
+  const [, year, month, day, hour, minute, second] = parts.map(Number);
+  return year! >= 1970 && month! >= 1 && month! <= 12 && day! >= 1
+    && day! <= new Date(Date.UTC(year!, month!, 0)).getUTCDate()
+    && hour! <= 23 && minute! <= 59 && second! <= 59;
+}
+export const operatorSessionSchema: OperatorSchema<OperatorSession> = schema(value => {
+  const row = fields(value, ["accessToken", "expiresAt", "user"]);
+  const user = fields(row.user, ["id", "email"]);
+  if (typeof row.accessToken !== "string" || !row.accessToken || row.accessToken.length > 8192
+    || !timestamp(row.expiresAt)
+    || typeof user.id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(user.id)) throw new Error("operator_session_invalid");
+  return { accessToken: row.accessToken, expiresAt: row.expiresAt, user: { id: user.id, email: email(user.email) } };
+});

package/src/identity/contracts/operatorInvitations.ts

@@ -0,0 +1,32 @@
+/** Pending invitations confer no authority; only accepted native memberships do. */
+export type OperatorRole = "admin" | "distributor";
+export type OperatorMembershipState = "invited" | "active" | "expired" | "revoked";
+export type OperatorInvitationOutcome = "INVITATION_CREATED" | "ALREADY_INVITED" | "INVITATION_REISSUED";
+export type OperatorInvitationConflict = "MEMBERSHIP_ALREADY_ACTIVE" | "INVITATION_ROLE_CONFLICT" | "IDENTITY_CONFLICT" | "MANAGED_REINVITE_UNSUPPORTED";
+export interface OperatorInvitation {
+  principalId: string;
+  invitationId: string;
+  membershipState: "invited";
+  role: OperatorRole;
+  invitedAt: string;
+  expiresAt: string;
+}
+export interface OperatorInvitationResult extends OperatorInvitation { code: OperatorInvitationOutcome; message?: string }
+export interface OperatorMembershipSnapshot {
+  principalId: string;
+  membershipState: OperatorMembershipState;
+  role: OperatorRole;
+}
+export type OperatorInvitationAcceptance =
+  | { code: "ACTIVATED" | "ALREADY_ACTIVE"; role: OperatorRole }
+  | { code: "INVITATION_EXPIRED" | "INVITATION_REVOKED" | "NO_INVITATION" };
+
+/** Managed invitations activate membership immediately; no pending attempt is stored. */
+export interface ManagedOperatorMembershipResult {
+  principalId: string;
+  membershipState: "active";
+  role: OperatorRole;
+  code: "MEMBERSHIP_CREATED" | "ALREADY_ACTIVE";
+  message?: string;
+}
+export type OperatorInviteResult = OperatorInvitationResult | ManagedOperatorMembershipResult;

package/src/identity/contracts/ports.ts

@@ -0,0 +1,25 @@
+import type {
+  AuthActionResult,
+  AuthSession,
+  AuthStateListener,
+  OAuthProviderKind,
+  Unsubscribe,
+} from "./types.js";
+
+
+export interface CustomerAuthPort {
+  getSession(): Promise<AuthSession | null>;
+  onAuthStateChange(listener: AuthStateListener): Unsubscribe;
+  signInWithOtp(input: { email: string; locale: string }): Promise<AuthActionResult>;
+  
+  verifyOtpCode(input: { email: string; token: string }): Promise<AuthActionResult>;
+  signInWithOAuth(input: {
+    provider: OAuthProviderKind;
+    redirectTo: string;
+  }): Promise<AuthActionResult>;
+  linkIdentity(input: {
+    provider: OAuthProviderKind;
+    redirectTo: string;
+  }): Promise<AuthActionResult>;
+  signOut(): Promise<void>;
+}

package/src/identity/contracts/privacy.ts

@@ -0,0 +1,86 @@
+import type { OperatorSchema } from "./operatorAuth.js";
+
+export type PrivacySubjectRef = { kind: "contact"; contactId: string } | { kind: "principal"; principalId: string };
+export type PrivacyJson = null | boolean | number | string | PrivacyJson[] | { [key: string]: PrivacyJson };
+export interface PersonalDataObligation { owner: string; resource: string; disposition: "erase" | "retain" | "unresolved"; reasonCode: string; remote: boolean }
+export interface PersonalDataDocument {
+  contributorId: string; version: string; data: PrivacyJson;
+  coverage: { complete: boolean; included: string[]; unavailable: string[] };
+  obligations: PersonalDataObligation[];
+}
+export interface ErasureReceipt { version: "identity.erasure.v1"; erasureId: string; completedAt: string; outcome: "ERASED" | "ALREADY_ERASED"; obligations: PersonalDataObligation[] }
+export interface PrivacyEraseRequest { subject: PrivacySubjectRef; idempotencyKey: string }
+export interface PrivacyExport { format: "personal-data.v1"; generatedAt: string; subject: PrivacySubjectRef; documents: PersonalDataDocument[]; missingContributors: string[]; erasure: ErasureReceipt | null }
+function invalid(): never { throw new Error("privacy_contract_invalid"); }
+function schema<T>(parse: (value: unknown) => T): OperatorSchema<T> {
+  return { parse, safeParse(value) { try { return { success: true, data: parse(value) }; } catch { return { success: false, error: new Error("privacy_contract_invalid") }; } } };
+}
+function fields(value: unknown, keys: string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype
+    || Object.keys(value).length !== keys.length || !keys.every(key => Object.hasOwn(value, key))) invalid();
+  return value as Record<string, unknown>;
+}
+function text(value: unknown, max = 200): string {
+  if (typeof value !== "string" || !value.length || value.length > max) invalid();
+  return value;
+}
+function uuid(value: unknown): string {
+  const result = text(value, 36);
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(result)) invalid();
+  return result.toLowerCase();
+}
+function timestamp(value: unknown): string {
+  const result = text(value, 30);
+  if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/.test(result) || !Number.isFinite(Date.parse(result))
+    || new Date(result).toISOString() !== result.replace(/Z$/, result.length === 20 ? ".000Z" : "Z")) invalid();
+  return result;
+}
+function list<T>(value: unknown, parse: (element: unknown) => T): T[] {
+  if (!Array.isArray(value) || value.length > 10000) invalid();
+  return value.map(element => parse(element));
+}
+function boolean(value: unknown): boolean { if (typeof value !== "boolean") invalid(); return value; }
+function choice<T extends string>(value: unknown, allowed: readonly T[]): T { if (!allowed.includes(value as T)) invalid(); return value as T; }
+function json(value: unknown, depth = 0): PrivacyJson {
+  if (depth > 32) invalid();
+  if (value === null || typeof value === "boolean" || typeof value === "string") { if (typeof value === "string" && value.length > 1000000) invalid(); return value; }
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (Array.isArray(value)) return list(value, element => json(element, depth + 1));
+  if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype) invalid();
+  const forbidden = new Set(["__proto__", "constructor", "prototype", "password", "password_hash", "token_hash", "access_token", "refresh_token", "accessToken", "refreshToken", "secret", "credentials"]);
+  const entries = Object.entries(value);
+  if (entries.length > 10000 || entries.some(([key]) => forbidden.has(key))) invalid();
+  return Object.fromEntries(entries.map(([key, child]) => [key, json(child, depth + 1)]));
+}
+export const privacySubjectSchema: OperatorSchema<PrivacySubjectRef> = schema(value => {
+  if (!value || typeof value !== "object" || !("kind" in value)) invalid();
+  if (value.kind === "contact") { const row = fields(value, ["kind", "contactId"]); return { kind: "contact", contactId: uuid(row.contactId) }; }
+  const row = fields(value, ["kind", "principalId"]);
+  return { kind: choice(row.kind, ["principal"]), principalId: uuid(row.principalId) };
+});
+export const personalDataObligationSchema: OperatorSchema<PersonalDataObligation> = schema(value => {
+  const row = fields(value, ["owner", "resource", "disposition", "reasonCode", "remote"]);
+  return { owner: text(row.owner, 100), resource: text(row.resource), disposition: choice(row.disposition, ["erase", "retain", "unresolved"]), reasonCode: text(row.reasonCode, 100), remote: boolean(row.remote) };
+});
+export const personalDataDocumentSchema: OperatorSchema<PersonalDataDocument> = schema(value => {
+  const row = fields(value, ["contributorId", "version", "data", "coverage", "obligations"]), coverage = fields(row.coverage, ["complete", "included", "unavailable"]);
+  const contributorId = text(row.contributorId, 100), version = text(row.version);
+  if (!/^[a-z][a-z0-9.-]{0,99}$/.test(contributorId) || !/^[a-z][a-z0-9.-]*\.v[1-9][0-9]*$/.test(version)) invalid();
+  return { contributorId, version, data: json(row.data), coverage: { complete: boolean(coverage.complete), included: list(coverage.included, text), unavailable: list(coverage.unavailable, text) }, obligations: list(row.obligations, personalDataObligationSchema.parse) };
+});
+export const erasureReceiptSchema: OperatorSchema<ErasureReceipt> = schema(value => {
+  const row = fields(value, ["version", "erasureId", "completedAt", "outcome", "obligations"]);
+  return { version: choice(row.version, ["identity.erasure.v1"]), erasureId: uuid(row.erasureId), completedAt: timestamp(row.completedAt), outcome: choice(row.outcome, ["ERASED", "ALREADY_ERASED"]), obligations: list(row.obligations, personalDataObligationSchema.parse) };
+});
+export const privacyExportRequestSchema: OperatorSchema<{ subject: PrivacySubjectRef }> = schema(value => ({ subject: privacySubjectSchema.parse(fields(value, ["subject"]).subject) }));
+export const privacyEraseRequestSchema: OperatorSchema<PrivacyEraseRequest> = schema(value => {
+  const row = fields(value, ["subject", "idempotencyKey"]); return { subject: privacySubjectSchema.parse(row.subject), idempotencyKey: uuid(row.idempotencyKey) };
+});
+export const privacyExportResponseSchema: OperatorSchema<PrivacyExport> = schema(value => {
+  const row = fields(value, ["format", "generatedAt", "subject", "documents", "missingContributors", "erasure"]);
+  return { format: choice(row.format, ["personal-data.v1"]), generatedAt: timestamp(row.generatedAt), subject: privacySubjectSchema.parse(row.subject), documents: list(row.documents, personalDataDocumentSchema.parse), missingContributors: list(row.missingContributors, text), erasure: row.erasure === null ? null : erasureReceiptSchema.parse(row.erasure) };
+});
+export const privacyEraseResponseSchema = erasureReceiptSchema;
+const refusalCodes = ["PRIVACY_SUBJECT_NOT_FOUND", "PRIVACY_CONTRIBUTOR_DUPLICATE", "PRIVACY_CONTRIBUTOR_MISSING", "PRIVACY_ASSESSMENT_UNAVAILABLE", "PRIVACY_OWNERSHIP_UNDECLARED", "PRIVACY_ACTIVE_SUBSCRIPTION", "PRIVACY_RESUMABLE_SUBSCRIPTION", "PRIVACY_PROTECTED_OPERATOR", "PRIVACY_IDEMPOTENCY_CONFLICT", "PRIVACY_SUBJECT_ERASED", "PRIVACY_STORE_PRIVILEGES_UNSAFE", "MANAGED_PRIVACY_ERASURE_UNAVAILABLE"] as const;
+export type PrivacyRefusalCode = typeof refusalCodes[number];
+export const privacyRefusalCodeSchema: OperatorSchema<PrivacyRefusalCode> = schema(value => choice(value, refusalCodes));

package/src/identity/contracts/providerList.ts

@@ -0,0 +1,13 @@
+import { isOAuthProviderKind, type OAuthProviderKind } from "./types.js";
+
+export const DEFAULT_SOCIAL_PROVIDERS: readonly OAuthProviderKind[] = ["google"];
+
+
+export function parseSocialProviders(raw: string | undefined): OAuthProviderKind[] {
+  if (raw === undefined) return [...DEFAULT_SOCIAL_PROVIDERS];
+  const kinds = raw
+    .split(",")
+    .map((token) => token.trim().toLowerCase())
+    .filter((token) => isOAuthProviderKind(token));
+  return [...new Set(kinds)];
+}

package/src/identity/contracts/types.ts

@@ -0,0 +1,25 @@
+export const OAUTH_PROVIDER_KINDS = ["google", "apple", "facebook"] as const;
+export type OAuthProviderKind = (typeof OAUTH_PROVIDER_KINDS)[number];
+
+export function isOAuthProviderKind(value: string): value is OAuthProviderKind {
+  return (OAUTH_PROVIDER_KINDS as readonly string[]).includes(value);
+}
+
+
+export interface AuthUser {
+  id: string;
+  email: string | null;
+}
+
+export interface AuthSession {
+  accessToken: string;
+  user: AuthUser;
+}
+
+export type AuthStateListener = (session: AuthSession | null) => void;
+export type Unsubscribe = () => void;
+
+
+export interface AuthActionResult {
+  error: string | null;
+}

package/src/identity/contribution.ts

@@ -0,0 +1,29 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Host-selected schema inventory: managed and direct installations have different objects. */
+export function createIdentityContribution(options: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  routes?: Contribution["routes"];
+  requiredPorts?: readonly string[];
+}): Contribution {
+  const routes = options.routes ?? [];
+  return {
+    manifest: {
+      name: "@openlup/platform", version: options.version, kind: "rail",
+      module: {
+        id: "identity", kind: "capability", provides: ["./identity", "./identity/contracts"],
+        dependsOn: [
+          { module: "bff", entries: ["./bff"] },
+          { module: "data", entries: ["./data"] },
+          { module: "kernel", entries: ["./kernel"] },
+          { module: "http", entries: ["./http"] },
+        ],
+      },
+      requiredSchema: options.requiredSchema,
+      emits: [], handles: [], schedules: [], routes: routes.map((route) => route.id),
+      requiredPorts: [...new Set(["emailTrustPolicy", ...(options.requiredPorts ?? [])])], env: [],
+    },
+    handlers: [], schedules: [], routes,
+  };
+}

package/src/identity/customerAuth.ts

@@ -0,0 +1,3 @@
+export type CustomerUserAuthenticationResult =
+  | { ok: true; userId: string }
+  | { ok: false; code: "UNAUTHORIZED"; message: string };

package/src/identity/customerAuthorization.ts

@@ -0,0 +1,38 @@
+import type { CustomerUserAuthenticationResult } from "./customerAuth.js";
+import type { IdentityVerifierPort } from "./ports.js";
+import type { ManagedIdentityClient } from "./managedClient.js";
+import { createSupabaseIdentityVerifier } from "./managedIdentityVerifier.js";
+export async function authenticateCustomerUserWith(
+  verifier: IdentityVerifierPort,
+  accessToken: string | null,
+): Promise<CustomerUserAuthenticationResult> {
+  if (!accessToken) {
+    return { ok: false, code: "UNAUTHORIZED", message: "Customer session required" };
+  }
+
+  const principal = await verifier.verifyAccessToken(accessToken);
+  if (!principal) {
+    return { ok: false, code: "UNAUTHORIZED", message: "Customer session required" };
+  }
+
+  return { ok: true, userId: principal.principalId };
+}
+
+
+export async function optionalCustomerSubject(
+  rawClient: unknown,
+  accessToken: string | null,
+): Promise<string | null> {
+  const client = rawClient as ManagedIdentityClient;
+  if (!accessToken) return null;
+  const result = await authenticateCustomerUser(client, accessToken);
+  return result.ok ? result.userId : null;
+}
+
+export async function authenticateCustomerUser(
+  rawClient: unknown,
+  accessToken: string | null,
+): Promise<CustomerUserAuthenticationResult> {
+  const client = rawClient as ManagedIdentityClient;
+  return authenticateCustomerUserWith(createSupabaseIdentityVerifier(client), accessToken);
+}

package/src/identity/customerContracts.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+z.config({ jitless: true });
+const platformCurrencySchema = z.string().regex(/^[A-Z]{3}$/);
+export const customerLifecycleStageSchema = z.enum([
+  "lead",
+  "tester",
+  "customer",
+  "inactive",
+]);
+
+export const customerMeRequestSchema = z.object({}).strict();
+
+export const customerMeResponseSchema = z.object({
+  clientId: z.string().min(1),
+  email: z.string().min(1),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  lifecycleStage: customerLifecycleStageSchema,
+  subscriptions: z
+    .array(
+      z
+        .object({
+          subscriptionId: z.guid(),
+          status: z.string().min(1),
+          cadenceDays: z.number().int().positive(),
+          nextCycleAt: z.string().datetime({ offset: true }).nullable(),
+          paymentMethodKind: z.string().nullable(),
+        })
+        .strict(),
+    )
+    .optional(),
+  recentOrders: z
+    .array(
+      z
+        .object({
+          orderId: z.guid(),
+          orderRef: z.string().regex(/^order_[a-z0-9-]+$/),
+          status: z.string().min(1),
+          mode: z.enum(["one_time", "subscription_cycle"]),
+          total: z.object({
+            amountMinor: z.number().int().nonnegative(),
+            currency: platformCurrencySchema,
+          }),
+          createdAt: z.string().datetime({ offset: true }),
+        })
+        .strict(),
+    )
+    .optional(),
+});
+
+
+export type CustomerMeResponse = z.infer<typeof customerMeResponseSchema>;

package/src/identity/customerIdentityBinding.ts

@@ -0,0 +1,125 @@
+import type { IdentityJwtLibraryLoader } from "./jwtLibrary.js";
+import type { ManagedIdentityClient } from "./managedClient.js";
+import {
+  authenticateCustomerUser,
+  authenticateCustomerUserWith,
+} from "./customerAuthorization.js";
+import {
+  readBearerToken,
+} from "./adminAuthorization.js";
+import { createPostgresCustomerMePort } from "./postgresCustomerMe.js";
+import type { PgGatewayClient } from "../data/index.js";
+import { createSupabaseCustomerMePort as createManagedCustomerMePort } from "./managedCustomerMe.js";
+import { createCustomerIdentityVerifier } from "./customerIdentityVerifier.js";
+import type { CustomerMeDeps } from "./customerMeHandler.js";
+import type { CustomerMePort } from "./customerPorts.js";
+import { resolveBundleId } from "../kernel/index.js";
+
+type Env = Record<string, string | undefined>;
+type CustomerRequest = Parameters<typeof readBearerToken>[0];
+type ManagedReadEnv = { url: string; anonKey: string };
+type CreateCustomerClient = (env: ManagedReadEnv, token: string | null) => unknown;
+type ActorGateway = {
+  asActor<T>(
+    claims: { role: "authenticated"; sub: string },
+    work: (gateway: unknown) => Promise<T>,
+  ): Promise<T>;
+};
+
+export type CustomerIdentityBindingOptions = {
+  authenticateManaged?: typeof authenticateCustomerUser;
+  createManagedClient?: CreateCustomerClient;
+  createManagedPort?: typeof createManagedCustomerMePort;
+  readManagedEnv?: () => ManagedReadEnv | null;
+  readToken?: typeof readBearerToken;
+  createPostgresGateway?: (env: Env) => ActorGateway;
+  createPostgresPort?: typeof createPostgresCustomerMePort;
+  createVerifier?: (config: Parameters<typeof createCustomerIdentityVerifier>[0]) => ReturnType<typeof createCustomerIdentityVerifier>;
+  resolveBundle?: typeof resolveBundleId;
+};
+
+/**
+ * Select the customer identity/read composition for one request. The direct
+ * path constructs its profile port only inside one actor-scoped transaction;
+ * it never uses a generic service lane or caller-provided token role.
+ */
+export function createCustomerIdentityBindingFactory(defaults: {
+  loadJwt: IdentityJwtLibraryLoader;
+  createManagedClient: CreateCustomerClient;
+  readManagedEnv: (env: Env) => ManagedReadEnv | null;
+  bindRequestActorDataPort: (token: string, env: Env) => ActorGateway | null;
+}) {
+return function createCustomerIdentityBinding(
+  req: CustomerRequest,
+  env: Env,
+  options: CustomerIdentityBindingOptions = {},
+): Omit<CustomerMeDeps, "responseSchema"> | null {
+  const accessToken = (options.readToken ?? readBearerToken)(req);
+  const bundleId = (options.resolveBundle ?? resolveBundleId)(env);
+
+  if (bundleId !== "node-postgres") {
+    const readEnv = options.readManagedEnv ?? (() => defaults.readManagedEnv(env));
+    const managedEnv = readEnv();
+    if (!managedEnv) return null;
+    const client = (options.createManagedClient ?? defaults.createManagedClient)(
+      managedEnv,
+      accessToken,
+    );
+    return {
+      authenticateUser: () =>
+        (options.authenticateManaged ?? authenticateCustomerUser)(
+          client,
+          accessToken,
+        ),
+      mePort: (options.createManagedPort ?? createManagedCustomerMePort)(
+        client,
+      ),
+    };
+  }
+
+  const gateway = (options.createPostgresGateway ?? createActorGateway)(env);
+  const createPort = options.createPostgresPort ?? createPostgresCustomerMePort;
+  const createVerifier =
+    options.createVerifier ?? ((config) => createCustomerIdentityVerifier(config, defaults.loadJwt));
+  const verifierConfig = {
+    audience: env.CUSTOMER_IDENTITY_AUDIENCE ?? "",
+    issuer: env.CUSTOMER_IDENTITY_ISSUER ?? "",
+    jwks: env.CUSTOMER_IDENTITY_JWKS ?? "",
+  };
+  let verifiedPrincipalId: string | null = null;
+  const mePort: CustomerMePort = {
+    getCustomerMe: (principalId) => {
+      if (principalId !== verifiedPrincipalId) {
+        return Promise.reject(new Error("customer_principal_mismatch"));
+      }
+      return gateway.asActor(
+        { role: "authenticated", sub: verifiedPrincipalId },
+        (actorGateway) =>
+          createPort(actorGateway as PgGatewayClient).getCustomerMe(
+            principalId,
+          ),
+      );
+    },
+  };
+
+  return {
+    async authenticateUser() {
+      const authentication = await authenticateCustomerUserWith(
+        createVerifier(verifierConfig),
+        accessToken,
+      );
+      if (authentication.ok) verifiedPrincipalId = authentication.userId;
+      return authentication;
+    },
+    mePort,
+  };
+}
+
+function createActorGateway(env: Env): ActorGateway {
+  const gateway = defaults.bindRequestActorDataPort("", env);
+  if (!gateway)
+    throw new Error("customer identity data gateway is unavailable");
+  return gateway as ActorGateway;
+}
+
+}