@openlup/platform 0.15.0 → 0.16.0

package/src/identity/adminMagicLinkHandler.ts

@@ -0,0 +1,132 @@
+import { createMagicLinkOriginResolver } from "./authVerifyUrl.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { MagicLinkAuthClient, MagicLinkRateLimitClient, MagicLinkDecision } from "./magicLinkPorts.js";
+export interface AdminMagicLinkHandlerOptions extends IdentityResponseOptions {
+  requestSchema: z.ZodType<{ email: string }>;
+  responseSchema: z.ZodType<{ accepted: true }>;
+  readEnvironment: () => { url: string; anonKey: string; serviceRoleKey: string } | null;
+  createRuntime: (env: { url: string; anonKey: string; serviceRoleKey: string }) => {
+    authClient: MagicLinkAuthClient;
+    rateLimitClient: MagicLinkRateLimitClient;
+    platformPort: { checkAdminMagicLinkEligibility(email: string): Promise<string> };
+  };
+  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: string;
+}
+const ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS = 400;
+export function createAdminMagicLinkHandler(options: AdminMagicLinkHandlerOptions) {
+const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(options);
+const readRequestOrigin = options.resolveOrigin ?? createMagicLinkOriginResolver(options.redirectOrigins ?? []);
+const { requestSchema: adminMagicLinkRequestSchema, responseSchema: adminMagicLinkResponseSchema, readEnvironment: readSupabaseAdminServiceEnv, createRuntime: createAdminMagicLinkRuntime, checkAttempt: checkAndRecordAdminMagicLinkAttempt, extractClientIp, padResponseTime } = options;
+return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+  if (req.method !== "POST") {
+    sendMethodNotAllowed(res, ["POST"]);
+    return;
+  }
+
+  const request = adminMagicLinkRequestSchema.safeParse(req.body);
+  if (!request.success) {
+    sendBffError(res, "BAD_REQUEST", "Invalid admin magic-link request", {
+      details: request.error.flatten(),
+    });
+    return;
+  }
+
+  const startedAt = Date.now();
+  const origin = readRequestOrigin(req);
+  if (!origin) {
+    await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link origin is not configured", {
+      details: { reason: "magic_link_origin_not_configured" },
+    });
+    return;
+  }
+
+  const env = readSupabaseAdminServiceEnv();
+  if (!env) {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin auth is not configured", {
+      details: { feature: "admin_auth", requiredEnv: "SUPABASE_SERVICE_ROLE_KEY" },
+    });
+    return;
+  }
+
+  const runtime = createAdminMagicLinkRuntime(env);
+
+  const decision = await checkAndRecordAdminMagicLinkAttempt({
+    client: runtime.rateLimitClient,
+    ip: extractClientIp(req.headers),
+    email: request.data.email,
+  });
+
+  if (!decision.allowed && decision.reason === "rpc_error") {
+    console.warn("admin_magic_link_rate_limit_unavailable", JSON.stringify({ reason: decision.reason }));
+    await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link service temporarily unavailable");
+    return;
+  }
+
+  if (decision.allowed) {
+    let eligibility: Awaited<ReturnType<typeof runtime.platformPort.checkAdminMagicLinkEligibility>>;
+    try {
+      eligibility = await runtime.platformPort.checkAdminMagicLinkEligibility(request.data.email);
+    } catch {
+      console.warn("admin_magic_link_lookup_failed", JSON.stringify({ outcome: "lookup_error" }));
+      await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Magic link service temporarily unavailable");
+      return;
+    }
+
+    if (eligibility === "eligible") {
+      const outcome = await sendMagicLink(runtime.authClient, request.data.email, origin);
+      console.info(
+        "admin_magic_link_outcome",
+        JSON.stringify({ outcome: outcome.status, code: outcome.code ?? null }),
+      );
+    } else {
+      console.warn("admin_magic_link_outcome", JSON.stringify({ outcome: eligibility }));
+    }
+  } else {
+    console.warn(
+      "admin_magic_link_outcome",
+      JSON.stringify({ outcome: "rate_limited", reason: decision.reason ?? "unknown" }),
+    );
+  }
+
+  await padResponseTime(startedAt, ADMIN_MAGIC_LINK_RESPONSE_FLOOR_MS);
+  sendBffSuccess(res, adminMagicLinkResponseSchema.parse({ accepted: true }));
+};
+
+async function sendMagicLink(
+  client: MagicLinkAuthClient,
+  email: string,
+  origin: string,
+): Promise<{ status: "sent" | "auth_error" | "threw"; code?: string }> {
+  try {
+    const { error } = await client.auth.signInWithOtp({
+      email,
+      options: {
+        shouldCreateUser: false,
+        emailRedirectTo: `${origin}${options.callbackPath}`,
+      },
+    });
+
+    if (error) {
+      console.warn("admin_magic_link_send_failed", JSON.stringify({ code: error.name ?? "AuthError" }));
+      return { status: "auth_error", code: error.name ?? "AuthError" };
+    }
+    return { status: "sent" };
+  } catch (error) {
+    const code = error instanceof Error ? error.name : "unknown";
+    console.warn("admin_magic_link_send_threw", JSON.stringify({ error: code }));
+    return { status: "threw", code };
+  }
+}
+
+
+}

package/src/identity/adminMeHandler.ts

@@ -0,0 +1,64 @@
+import type { OperatorInvitationStore } from "./operatorInvitationPorts.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { adminPlatformMeRequestSchema, adminPlatformMeResponseSchema } from "./adminContracts.js";
+import type { PlatformUserAuthenticationResult } from "./platformAdminAuth.js";
+export interface AdminPlatformMeDeps extends IdentityResponseOptions {
+  invitationStore?: Pick<OperatorInvitationStore, "acceptOperatorInvitation">;
+  platformPort: { getAdminMe(userId: string): Promise<{ isAdmin: boolean; role: "admin" | "distributor" | null }> };
+  authenticateUser: (req: HttpRequest) => Promise<PlatformUserAuthenticationResult>;
+}
+
+export function createAdminPlatformMeHandler({
+  platformPort, invitationStore,
+  authenticateUser, responseRequestId,
+}: AdminPlatformMeDeps) {
+  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: PlatformUserAuthenticationResult;
+    try {
+      authentication = await authenticateUser(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Platform user authentication failed");
+      return;
+    }
+
+    if (authentication.ok === false) {
+      sendBffError(res, authentication.code, authentication.message);
+      return;
+    }
+
+    const request = adminPlatformMeRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid platform me request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      if (invitationStore) {
+        const outcome = await invitationStore.acceptOperatorInvitation(authentication.userId);
+        if (outcome.code === "INVITATION_EXPIRED" || outcome.code === "INVITATION_REVOKED") {
+          sendBffError(res, "FORBIDDEN", outcome.code, { details: { identityCode: outcome.code } });
+          return;
+        }
+      }
+      const result = await platformPort.getAdminMe(authentication.userId);
+      const response = adminPlatformMeResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Platform me returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Platform me read failed");
+    }
+  };
+}

package/src/identity/adminPreflight.ts

@@ -0,0 +1,46 @@
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { AdminAuthPort, AdminPrincipalRole } from "./ports.js";
+import { readBearerToken } from "./adminAuthorization.js";
+import { refusesMachineActorRequest, sendMachineActorWriteRefused } from "./machineActorWriteFence.js";
+
+export interface AdminAuthBinding {
+  readonly identity: string;
+  run<T>(accessToken: string | null, work: (auth: AdminAuthPort) => Promise<T>): Promise<T>;
+}
+export function createAdminBffPreflight(options: IdentityResponseOptions & {
+  allowedRoles: (route: string) => readonly AdminPrincipalRole[] | null;
+  resolveBinding: () => { binding?: AdminAuthBinding; error?: string };
+  machineWriteRoutes?: readonly string[];
+  managedEnvironmentMessage?: string;
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder(options);
+  return async (req: HttpRequest, res: HttpResponse, route: string): Promise<boolean> => {
+    const allowedRoles = options.allowedRoles(route);
+    if (!allowedRoles) return true;
+    const resolved = options.resolveBinding();
+    if (!resolved.binding) {
+      if (resolved.error === "managed_admin_auth_env_required") {
+        sendBffError(res, "INTERNAL", options.managedEnvironmentMessage ?? "Identity environment is not configured");
+      } else sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return false;
+    }
+    const accessToken = readBearerToken(req);
+    try {
+      const authz = await resolved.binding.run(accessToken, (auth) => auth.authorize(accessToken, { allowedRoles }));
+      if (authz.ok === false) {
+        sendBffError(res, authz.code, authz.message);
+        return false;
+      }
+      if (resolved.binding.identity !== "node-postgres"
+        && refusesMachineActorRequest(route, req.method, authz.isMachineActor, options.machineWriteRoutes)) {
+        sendMachineActorWriteRefused(res, options);
+        return false;
+      }
+      return true;
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return false;
+    }
+  };
+}

package/src/identity/adminUserActionPorts.ts

@@ -0,0 +1,78 @@
+import { adminUserInviteResponseSchema } from "./adminContracts.js";
+import type { IdentityAdminActionsPort } from "./adminUserHandlers.js";
+import type { runInviteAdminUserUseCase } from "./inviteAdminUserUseCase.js";
+import type { runRemoveAdminUserUseCase } from "./removeAdminUserUseCase.js";
+export interface AdminUserInviteErrorDetails {
+  identityCode?: string;
+  invitationId?: string;
+  principalId?: string;
+  membershipState?: "active";
+  role?: "admin" | "distributor";
+}
+type AdminUserActionRuntimeEnv = Record<string, string | undefined>;
+type AdminUserInviteRunner = (request: { accessToken: string | null; email: string; role: "admin" | "distributor" }, env?: AdminUserActionRuntimeEnv) => ReturnType<typeof runInviteAdminUserUseCase>;
+type AdminUserRemoveRunner = (request: { accessToken: string | null; userId: string }, env?: AdminUserActionRuntimeEnv) => ReturnType<typeof runRemoveAdminUserUseCase>;
+export function createAdminUserInvitePort(options: {
+  accessToken: string | null;
+  env?: AdminUserActionRuntimeEnv;
+  runInviteAdminUser: AdminUserInviteRunner;
+}): Pick<IdentityAdminActionsPort, "inviteAdminUser"> {
+  const runInviteAdminUser = options.runInviteAdminUser;
+  return {
+    async inviteAdminUser(request) {
+      const result = await runInviteAdminUser({
+        accessToken: options.accessToken,
+        email: request.email,
+        role: request.role,
+      }, options.env);
+      if (result.status < 200 || result.status >= 300) {
+        const details: AdminUserInviteErrorDetails = {
+          identityCode: result.body.code,
+          ...(typeof result.body.invitationId === "string" ? { invitationId: result.body.invitationId } : {}),
+          ...(result.body.membershipState === "active" && typeof result.body.principalId === "string"
+            && (result.body.role === "admin" || result.body.role === "distributor")
+            ? { principalId: result.body.principalId, membershipState: "active", role: result.body.role } : {}),
+        };
+        throw Object.assign(new Error(String(result.body.error ?? `invite_admin_user_http_${result.status}`)), { bffCode: ({ 400: "BAD_REQUEST", 401: "UNAUTHORIZED", 403: "FORBIDDEN", 409: "CONFLICT" } as Record<number, string>)[result.status] ?? "UPSTREAM_UNAVAILABLE", inviteDetails: details });
+      }
+      if (result.body.error) throw new Error(result.body.error);
+
+      return adminUserInviteResponseSchema.parse(result.body);
+    },
+  };
+}
+
+export function createAdminUserRemovePort(options: {
+  accessToken: string | null;
+  env?: AdminUserActionRuntimeEnv;
+  runRemoveAdminUser: AdminUserRemoveRunner;
+}): Pick<IdentityAdminActionsPort, "removeAdminUser"> {
+  const runRemoveAdminUser = options.runRemoveAdminUser;
+  return {
+    async removeAdminUser(request) {
+      const result = await runRemoveAdminUser({
+        accessToken: options.accessToken,
+        userId: request.userId,
+      }, options.env);
+      if (result.status < 200 || result.status >= 300) {
+        throw removePortError(
+          result.status,
+          String(result.body.error ?? `remove_admin_user_http_${result.status}`),
+        );
+      }
+      if (result.body.error) throw new Error(result.body.error);
+
+      if (result.body.revoked !== true) {
+        throw new Error("admin_revoke_admin_user returned an invalid response");
+      }
+      return { revoked: true };
+    },
+  };
+}
+
+function removePortError(status: number, message: string): Error {
+  const bffCode = ({ 400: "BAD_REQUEST", 403: "FORBIDDEN", 409: "CONFLICT" } as const)[status]
+    ?? "UPSTREAM_UNAVAILABLE";
+  return Object.assign(new Error(message), { bffCode });
+}
+

package/src/identity/adminUserHandlers.ts

@@ -0,0 +1,174 @@
+import type { AdminUserInviteErrorDetails } from "./adminUserActionPorts.js";
+import { createIdentityResponder, type IdentityResponseOptions } from "./response.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { adminUserRoleUpdateRequestSchema, adminUserRoleUpdateResponseSchema, adminUserInviteRequestSchema, adminUserInviteResponseSchema, adminUserRemoveRequestSchema, adminUserRemoveResponseSchema } from "./adminContracts.js";
+import type { PlatformAdminAuthorizationResult } from "./platformAdminAuth.js";
+import type { OperatorInviteResult } from "./contracts/operatorInvitations.js";
+export interface IdentityAdminActionsPort {
+  inviteAdminUser(request: { email: string; role: "admin" | "distributor" }): Promise<OperatorInviteResult>;
+  removeAdminUser(request: { userId: string }): Promise<{ revoked: true }>;
+  updateAdminUserRole(request: { userId: string; role: "admin" | "distributor" }): Promise<{ userId: string; role: "admin" | "distributor"; saved: true }>;
+}
+export interface AdminUserRoleUpdateDeps extends IdentityResponseOptions { settingsPort: Pick<IdentityAdminActionsPort, "updateAdminUserRole">; authorizeAdmin: (req: HttpRequest) => Promise<PlatformAdminAuthorizationResult> }
+export interface AdminUserInviteDeps extends IdentityResponseOptions { settingsPort: Pick<IdentityAdminActionsPort, "inviteAdminUser">; authorizeAdmin: (req: HttpRequest) => Promise<PlatformAdminAuthorizationResult> }
+export interface AdminUserRemoveDeps extends IdentityResponseOptions { settingsPort: Pick<IdentityAdminActionsPort, "removeAdminUser">; authorizeAdmin: (req: HttpRequest) => Promise<PlatformAdminAuthorizationResult> }
+export function createAdminUserRoleUpdateHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminUserRoleUpdateDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: PlatformAdminAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminUserRoleUpdateRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin user role update request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.updateAdminUserRole(request.data);
+      const response = adminUserRoleUpdateResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin user role update returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      const bffCode = (error as { bffCode?: string })?.bffCode;
+      if (bffCode) {
+        sendBffError(res, bffCode as Parameters<typeof sendBffError>[1], (error as Error).message);
+        return;
+      }
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin user role update failed");
+    }
+  };
+}
+
+export function createAdminUserInviteHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminUserInviteDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: PlatformAdminAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminUserInviteRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin user invite request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.inviteAdminUser(request.data);
+      const response = adminUserInviteResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin user invite returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      const failure = error as { bffCode?: string; inviteDetails?: AdminUserInviteErrorDetails };
+      sendBffError(res, (failure.bffCode ?? "UPSTREAM_UNAVAILABLE") as Parameters<typeof sendBffError>[1], errorMessage(error, "Admin user invite failed"), failure.inviteDetails ? { details: failure.inviteDetails } : {});
+    }
+  };
+}
+
+export function createAdminUserRemoveHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminUserRemoveDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createIdentityResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: PlatformAdminAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminUserRemoveRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin user remove request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.removeAdminUser(request.data);
+      const response = adminUserRemoveResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin user remove returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      sendMutationError(res, error, "Admin user revoke failed", responseRequestId);
+    }
+  };
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message ? error.message : fallback;
+}
+
+function sendMutationError(res: HttpResponse, error: unknown, fallback: string, responseRequestId: IdentityResponseOptions["responseRequestId"]): void {
+  const { sendBffError } = createIdentityResponder({ responseRequestId });
+  const bffCode = (error as { bffCode?: string })?.bffCode;
+  if (bffCode) {
+    sendBffError(res, bffCode as Parameters<typeof sendBffError>[1], errorMessage(error, fallback));
+    return;
+  }
+  sendBffError(res, "UPSTREAM_UNAVAILABLE", errorMessage(error, fallback));
+}

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