@openlup/platform 0.15.0 → 0.16.0

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

package/src/identity/customerIdentityVerifier.ts

@@ -0,0 +1,141 @@
+import type { IdentityJwtLibrary, IdentityJwtLibraryLoader, IdentityJwk } from "./jwtLibrary.js";
+import type { IdentityVerifierPort, VerifiedPrincipal } from "./ports.js";
+
+const MAX_JWKS_BYTES = 12_288;
+const MAX_TOKEN_BYTES = 8_192;
+const MAX_CLAIM_BYTES = 256;
+const KID = /^[A-Za-z0-9._-]{1,64}$/;
+const BASE64URL_COORDINATE = /^[A-Za-z0-9_-]{43}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const JWK_FIELDS = new Set(["alg", "crv", "kid", "kty", "use", "x", "y"]);
+type VerificationKey = Awaited<ReturnType<IdentityJwtLibrary["importJWK"]>>;
+
+export interface CustomerIdentityVerifierConfig {
+  audience: string;
+  issuer: string;
+  jwks: string;
+}
+
+interface ExactVerificationJwk extends IdentityJwk {
+  alg: "ES256";
+  crv: "P-256";
+  kid: string;
+  kty: "EC";
+  use: "sig";
+  x: string;
+  y: string;
+}
+
+
+export function createCustomerIdentityVerifier(
+  config: CustomerIdentityVerifierConfig,
+  loadJwt: IdentityJwtLibraryLoader,
+): IdentityVerifierPort {
+  const issuer = readClaim(config.issuer, "issuer");
+  const audience = readClaim(config.audience, "audience");
+  const jwks = readJwks(config.jwks);
+  let keys: Promise<Map<string, VerificationKey>> | null = null;
+  let library: Promise<IdentityJwtLibrary> | undefined;
+  const getLibrary = () => library ??= loadJwt();
+  const importedKeys = () => keys ??= getLibrary().then(({ importJWK }) => Promise.all(
+    jwks.map(async (jwk) => [jwk.kid, await importJWK(jwk, "ES256")] as const),
+  )).then((entries) => new Map<string, VerificationKey>(entries));
+
+  return {
+    async verifyAccessToken(accessToken: string): Promise<VerifiedPrincipal | null> {
+      if (typeof accessToken !== "string" || accessToken.length === 0 || accessToken.length > MAX_TOKEN_BYTES) {
+        return null;
+      }
+      const resolvedKeys = await importedKeys();
+      const { jwtVerify } = await getLibrary();
+
+      try {
+        const verified = await jwtVerify(
+          accessToken,
+          async (header) => {
+            if (header.alg !== "ES256" || typeof header.kid !== "string" || !KID.test(header.kid)) {
+              throw new Error("customer identity token header rejected");
+            }
+            const key = resolvedKeys.get(header.kid);
+            if (!key) throw new Error("customer identity token key rejected");
+            return key;
+          },
+          { algorithms: ["ES256"], audience, issuer },
+        );
+        if (typeof verified.payload.sub !== "string" || !UUID.test(verified.payload.sub)) return null;
+        return { email: null, emailVerified: false, principalId: verified.payload.sub };
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+function readClaim(value: string, label: string): string {
+  if (
+    typeof value !== "string"
+    || value.length === 0
+    || value.length > MAX_CLAIM_BYTES
+    || value.trim() !== value
+    || [...value].some((character) => {
+      const code = character.charCodeAt(0);
+      return code <= 0x1f || code === 0x7f;
+    })
+  ) {
+    throw new Error(`customer identity ${label} configuration is invalid`);
+  }
+  return value;
+}
+
+function readJwks(value: string): ExactVerificationJwk[] {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_JWKS_BYTES) {
+    throw new Error("customer identity JWKS configuration is invalid");
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("customer identity JWKS configuration is invalid");
+  }
+  if (!isRecord(parsed) || !hasOnlyFields(parsed, new Set(["keys"])) || !Array.isArray(parsed.keys)) {
+    throw new Error("customer identity JWKS configuration is invalid");
+  }
+  if (parsed.keys.length < 1 || parsed.keys.length > 2) {
+    throw new Error("customer identity JWKS configuration is invalid");
+  }
+
+  const keys = parsed.keys.map(readJwk);
+  if (new Set(keys.map((key) => key.kid)).size !== keys.length) {
+    throw new Error("customer identity JWKS configuration is invalid");
+  }
+  return keys;
+}
+
+function readJwk(value: unknown): ExactVerificationJwk {
+  if (
+    !isRecord(value)
+    || !hasOnlyFields(value, JWK_FIELDS)
+    || value.kty !== "EC"
+    || value.crv !== "P-256"
+    || value.alg !== "ES256"
+    || value.use !== "sig"
+    || typeof value.kid !== "string"
+    || !KID.test(value.kid)
+    || typeof value.x !== "string"
+    || !BASE64URL_COORDINATE.test(value.x)
+    || typeof value.y !== "string"
+    || !BASE64URL_COORDINATE.test(value.y)
+  ) {
+    throw new Error("customer identity JWKS configuration is invalid");
+  }
+  return value as unknown as ExactVerificationJwk;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOnlyFields(value: Record<string, unknown>, fields: Set<string>): boolean {
+  return Object.keys(value).every((field) => fields.has(field));
+}