@openlup/platform 0.15.0 → 0.17.0

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

package/src/identity/customerMagicLinkHandler.ts

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

package/src/identity/customerMeHandler.ts

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

package/src/identity/customerPorts.ts

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

package/src/identity/customerSessionBinding.ts

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

package/src/identity/customerSessionIssuer.ts

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

package/src/identity/customerVerifyOtpHandler.ts

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