@facilis.dev/auth 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * @facilis.dev/auth — auth tables, RBAC expansion, password hashing, sessions and seeding.
+ */
+
+export {
+  apiClients,
+  apiTokens,
+  authEmailVerifications,
+  rolePermissions,
+  roles,
+  sessions,
+  userRoles,
+  users,
+  type ApiClientRow,
+  type ApiTokenRow,
+  type AuthUser,
+  type EmailVerificationRow,
+  type NewEmailVerificationRow,
+  type NewUserRow,
+  type RolePermissionRow,
+  type RoleRow,
+  type SessionRow,
+  type UserRoleRow,
+  type UserRow,
+} from "./tables.ts";
+export {
+  createApiClient,
+  issueApiToken,
+  listApiClients,
+  revokeApiClient,
+  validateApiToken,
+  type ApiClientSummary,
+  type CreateApiClientInput,
+  type CreatedApiClient,
+  type IssuedApiToken,
+  type IssueApiTokenInput,
+  type ValidatedApiToken,
+} from "./api-clients.ts";
+export { normalizeEmail } from "./email.ts";
+export { expandRoles, hasPermission, type AuthConfig, type AuthContext } from "./roles.ts";
+export {
+  consumeEmailVerification,
+  EMAIL_VERIFICATION_TABLES,
+  issueEmailVerification,
+  markEmailVerified,
+  type IssuedEmailVerification,
+  type IssueEmailVerificationOptions,
+} from "./email-verification.ts";
+export { hashPassword, verifyPassword } from "./password.ts";
+export {
+  createSession,
+  destroySession,
+  SESSION_COOKIE_NAME,
+  sessionMiddleware,
+  validateSession,
+  type CreateSessionOptions,
+  type SessionEvent,
+  type SessionEventContext,
+  type SessionMiddlewareDeps,
+  type ValidatedSession,
+} from "./session.ts";
+export { registerInitialAdmin, seedFromConfig, seedStatements, type SeedEntry } from "./seed.ts";
+export * from "./sso/index.ts";

package/src/password.ts

@@ -0,0 +1,74 @@
+import { constantTimeEqual, decodeBase64, encodeBase64, randomBytes, webcrypto } from "./crypto.ts";
+
+const ALGORITHM = "pbkdf2-sha256";
+const DEFAULT_ITERATIONS = 600_000;
+const MAX_ITERATIONS = 1_000_000;
+const SALT_BYTES = 16;
+const KEY_BITS = 256;
+const KEY_BYTES = KEY_BITS / 8;
+
+/**
+ * Hashes a password with PBKDF2-SHA256 (WebCrypto). Encoding is versioned and
+ * self-describing: `pbkdf2-sha256$<iterations>$<saltB64>$<hashB64>`.
+ */
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT_BYTES);
+  const hash = await deriveKey(password, salt, DEFAULT_ITERATIONS);
+  return [ALGORITHM, String(DEFAULT_ITERATIONS), encodeBase64(salt), encodeBase64(hash)].join("$");
+}
+
+/** Constant-time verification; malformed or unsupported hashes return false, never throw. */
+export async function verifyPassword(hash: string, password: string): Promise<boolean> {
+  const parsed = parsePasswordHash(hash);
+  if (parsed === null) return false;
+  const candidate = await deriveKey(password, parsed.salt, parsed.iterations);
+  return constantTimeEqual(candidate, parsed.hash);
+}
+
+interface ParsedPasswordHash {
+  iterations: number;
+  salt: Uint8Array;
+  hash: Uint8Array;
+}
+
+function parsePasswordHash(value: string): ParsedPasswordHash | null {
+  const parts = value.split("$");
+  if (parts.length !== 4) return null;
+  const [algorithm, iterationsText, saltText, hashText] = parts;
+  if (
+    algorithm !== ALGORITHM ||
+    iterationsText === undefined ||
+    saltText === undefined ||
+    hashText === undefined ||
+    !/^[1-9][0-9]*$/.test(iterationsText)
+  ) {
+    return null;
+  }
+
+  const iterations = Number(iterationsText);
+  if (iterations > MAX_ITERATIONS) return null;
+
+  const salt = decodeBase64(saltText);
+  const hash = decodeBase64(hashText);
+  if (salt === null || hash === null || salt.length !== SALT_BYTES || hash.length !== KEY_BYTES) {
+    return null;
+  }
+  return { iterations, salt, hash };
+}
+
+async function deriveKey(
+  password: string,
+  salt: Uint8Array,
+  iterations: number,
+): Promise<Uint8Array> {
+  const { subtle } = webcrypto();
+  const key = await subtle.importKey("raw", new TextEncoder().encode(password), "PBKDF2", false, [
+    "deriveBits",
+  ]);
+  const bits = await subtle.deriveBits(
+    { name: "PBKDF2", hash: "SHA-256", salt, iterations },
+    key,
+    KEY_BITS,
+  );
+  return new Uint8Array(bits);
+}

package/src/roles.ts

@@ -0,0 +1,77 @@
+/**
+ * Auth context attached to requests once a session is validated (contract §4.1/§6).
+ *
+ * It deliberately carries no tenant (D-040): the tenant is the deployment's, resolved from
+ * FACILIS_TENANT_ID for every request, so a session can neither widen nor change the RLS scope.
+ */
+export interface AuthContext {
+  readonly userId: string;
+  readonly roles: readonly string[];
+  readonly permissions: readonly string[];
+  /**
+   * SHA-256 (hex) of the session id (D-099): the sudo audit log correlates a request with
+   * the session it ran under without ever storing the value of the cookie.
+   */
+  readonly sessionHash?: string;
+  /**
+   * Which credential produced this context (V3a): a browser session or a programmatic API
+   * bearer token. Audit/logging code reads it to separate machine traffic from human sessions.
+   */
+  readonly via?: "session" | "bearer";
+}
+
+/** Shape of `facilis.config.ts`'s `auth` block that @facilis.dev/auth needs. */
+export interface AuthConfig {
+  readonly permissions: readonly string[];
+  readonly roles: Readonly<Record<string, readonly string[]>>;
+  readonly defaultRole: string;
+  readonly sessionDurationMs: number;
+}
+
+const WILDCARD = "*";
+
+/**
+ * Expands app roles into concrete permissions, deterministically: roles keep their input
+ * order, permissions keep config order, duplicates collapse to the first occurrence.
+ * Unknown roles (e.g. a stale `user_roles` row) contribute nothing.
+ */
+export function expandRoles(roles: readonly string[], config: AuthConfig): string[] {
+  const expanded: string[] = [];
+  const seen = new Set<string>();
+
+  const add = (permission: string): void => {
+    if (seen.has(permission)) return;
+    seen.add(permission);
+    expanded.push(permission);
+  };
+
+  for (const role of roles) {
+    const declared = config.roles[role];
+    if (declared === undefined) continue;
+    for (const permission of declared) {
+      if (permission === WILDCARD) {
+        for (const granted of config.permissions) add(granted);
+      } else {
+        add(permission);
+      }
+    }
+  }
+
+  return expanded;
+}
+
+/**
+ * Route RBAC check (contract §4.4): `[]` requires nothing (public route), a non-empty
+ * list requires at least one match, and null means no session. A literal "*" permission
+ * on the subject grants everything as a safety net for hand-built contexts.
+ */
+export function hasPermission(
+  subject: Pick<AuthContext, "permissions"> | null,
+  permission: string | readonly string[],
+): boolean {
+  const required = typeof permission === "string" ? [permission] : permission;
+  if (required.length === 0) return true;
+  if (subject === null) return false;
+  if (subject.permissions.includes(WILDCARD)) return true;
+  return required.some((candidate) => subject.permissions.includes(candidate));
+}

package/src/seed.ts

@@ -0,0 +1,146 @@
+import { eq, sql } from "drizzle-orm";
+
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+
+import { constantTimeEqual, sha256Hex } from "./crypto.ts";
+import { normalizeEmail } from "./email.ts";
+import type { AuthConfig } from "./roles.ts";
+import { userRoles, users } from "./tables.ts";
+
+const INITIAL_ADMIN_ROLE = "admin";
+
+export interface SeedEntry {
+  readonly role: string;
+  readonly permission: string;
+}
+
+/**
+ * Pure projection of `config.auth.roles` into `role_permissions` rows (SPEC §5.3/§8.4.2).
+ * Wildcards stay literal ("*") exactly as the reference seed shows; the table is written
+ * only at migration time, never at runtime.
+ */
+export function seedFromConfig(config: AuthConfig): SeedEntry[] {
+  const entries: SeedEntry[] = [];
+  const seen = new Set<string>();
+
+  for (const [role, permissions] of Object.entries(config.roles)) {
+    for (const permission of permissions) {
+      const key = `${role}\u0000${permission}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      entries.push({ role, permission });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Deterministic, idempotent SQL for the migration/seed step: roles first, then
+ * role_permissions, every statement guarded by ON CONFLICT DO NOTHING.
+ */
+export function seedStatements(config: AuthConfig): string[] {
+  const statements: string[] = [];
+
+  for (const role of Object.keys(config.roles)) {
+    statements.push(
+      `INSERT INTO roles (name) VALUES (${sqlLiteral(role)}) ON CONFLICT DO NOTHING;`,
+    );
+  }
+  for (const { role, permission } of seedFromConfig(config)) {
+    statements.push(
+      `INSERT INTO role_permissions (role, permission) VALUES (${sqlLiteral(role)}, ${sqlLiteral(permission)}) ON CONFLICT DO NOTHING;`,
+    );
+  }
+
+  return statements;
+}
+
+/**
+ * Grants `admin` to the user whose email matches FACILIS_INITIAL_ADMIN (SPEC §8.4.3).
+ *
+ * The email alone is not a credential: it is public and the registration route is public, so
+ * the promotion ALSO requires the operator's one-time FACILIS_INITIAL_ADMIN_TOKEN (D-150).
+ * Both variables must be set; a missing token fails closed, the token is compared in constant
+ * time, and the promotion happens only while no admin exists yet, so a deploy that keeps the
+ * token configured after bootstrap cannot be re-triggered. Accepts a user id or email; returns
+ * false when any condition fails.
+ */
+export async function registerInitialAdmin(
+  db: PolicyScopedDatabase,
+  userIdOrEmail: string,
+  bootstrapToken?: string,
+): Promise<boolean> {
+  const expected = readInitialAdminEmail();
+  if (expected === null) return false;
+  const expectedToken = readInitialAdminToken();
+  if (expectedToken === null || bootstrapToken === undefined) return false;
+  if (!(await tokenMatches(bootstrapToken, expectedToken))) return false;
+  // One-time: an admin already assigned means bootstrap is over, even if the env stays set.
+  if (await hasAdmin(db)) return false;
+
+  const user = await findUser(db, userIdOrEmail.trim());
+  if (user === null) return false;
+  // Emails compare in canonical form: a case variant of the configured address is not the
+  // configured address (the unique lower(email) index makes the two the same account, D-150).
+  if (normalizeEmail(user.email) !== expected) return false;
+
+  await db
+    .insert(userRoles)
+    .values({ userId: user.id, role: INITIAL_ADMIN_ROLE })
+    .onConflictDoNothing();
+  return true;
+}
+
+function readInitialAdminEmail(): string | null {
+  const configured = process.env.FACILIS_INITIAL_ADMIN?.trim();
+  return configured === undefined || configured.length === 0 ? null : normalizeEmail(configured);
+}
+
+function readInitialAdminToken(): string | null {
+  const configured = process.env.FACILIS_INITIAL_ADMIN_TOKEN?.trim();
+  return configured === undefined || configured.length === 0 ? null : configured;
+}
+
+/**
+ * Hash-then-compare keeps the comparison independent of the two input lengths, so a wrong
+ * token leaks neither its length nor the index of the first wrong character.
+ */
+async function tokenMatches(provided: string, expected: string): Promise<boolean> {
+  const [left, right] = await Promise.all([sha256Hex(provided), sha256Hex(expected)]);
+  return constantTimeEqual(new TextEncoder().encode(left), new TextEncoder().encode(right));
+}
+
+async function hasAdmin(db: PolicyScopedDatabase): Promise<boolean> {
+  const rows = await db
+    .select({ role: userRoles.role })
+    .from(userRoles)
+    .where(eq(userRoles.role, INITIAL_ADMIN_ROLE))
+    .limit(1);
+  return rows.length > 0;
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+async function findUser(
+  db: PolicyScopedDatabase,
+  userIdOrEmail: string,
+): Promise<{ id: string; email: string } | null> {
+  const rows = UUID_PATTERN.test(userIdOrEmail)
+    ? await db
+        .select({ id: users.id, email: users.email })
+        .from(users)
+        .where(eq(users.id, userIdOrEmail))
+        .limit(1)
+    : await db
+        .select({ id: users.id, email: users.email })
+        .from(users)
+        .where(sql`lower(${users.email}) = ${normalizeEmail(userIdOrEmail)}`)
+        .limit(1);
+
+  return rows[0] ?? null;
+}
+
+function sqlLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}

package/src/session.ts

@@ -0,0 +1,209 @@
+import { eq } from "drizzle-orm";
+
+import { runWithPolicyScope, type FacilisDb, type PolicyScopedDatabase } from "@facilis.dev/db";
+
+import { validateApiToken } from "./api-clients.ts";
+import { randomToken, sha256Hex } from "./crypto.ts";
+import { expandRoles, type AuthConfig } from "./roles.ts";
+import { sessions, userRoles, users, type AuthUser, type SessionRow } from "./tables.ts";
+
+/** Cookie name fixed by contract §4.4; HttpOnly/Path=/SameSite=Lax/Secure-in-prod. The cookie
+ * carries the raw 32-byte token; the sessions row stores only its SHA-256 (D-144). */
+export const SESSION_COOKIE_NAME = "facilis_session";
+
+const DEFAULT_SESSION_TTL_MS = 1000 * 60 * 60 * 24 * 7;
+
+export interface CreateSessionOptions {
+  readonly ttlMs?: number;
+}
+
+export interface ValidatedSession {
+  readonly user: AuthUser;
+  readonly session: SessionRow;
+}
+
+/** Creates an opaque session row; callers set the cookie themselves (route blueprint). */
+export async function createSession(
+  db: PolicyScopedDatabase,
+  userId: string,
+  options: CreateSessionOptions = {},
+): Promise<{ id: string; expiresAt: Date }> {
+  // A service account exists only for machine credentials: minting a cookie session for one
+  // would make it loggable in a browser, so refuse here even if a caller missed the flag.
+  const serviceAccount = await db
+    .select({ isService: users.isService })
+    .from(users)
+    .where(eq(users.id, userId))
+    .limit(1);
+  if (serviceAccount[0]?.isService === true) {
+    throw new Error("createSession: service accounts cannot log in");
+  }
+
+  const id = randomToken(32);
+  const expiresAt = new Date(Date.now() + (options.ttlMs ?? DEFAULT_SESSION_TTL_MS));
+  // The row key is the SHA-256 of the cookie value: the raw id is the credential and never
+  // reaches the database, so a SELECT on sessions (RLS-scoped, tenant-visible) cannot be
+  // replayed as a session. The cookie keeps the raw value; lookups hash it again.
+  await db.insert(sessions).values({ id: await sha256Hex(id), userId, expiresAt });
+  return { id, expiresAt };
+}
+
+/**
+ * Joins the session to its user; expired or unknown sessions yield null.
+ *
+ * Callers pass a policy-scoped client (`runWithPolicyScope`) with app.tenant_id set: users
+ * carries tenant RLS, so an unscoped read as the non-superuser facilis_app role cannot see
+ * the joined user row at all.
+ */
+export async function validateSession(
+  db: PolicyScopedDatabase,
+  sessionId: string,
+): Promise<ValidatedSession | null> {
+  // Rows hold sha256(cookie id): the caller passes the raw cookie and the lookup hashes it.
+  const rows = await db
+    .select({
+      session: sessions,
+      user: {
+        id: users.id,
+        email: users.email,
+        tenantId: users.tenantId,
+        createdAt: users.createdAt,
+      },
+      isService: users.isService,
+    })
+    .from(sessions)
+    .innerJoin(users, eq(sessions.userId, users.id))
+    .where(eq(sessions.id, await sha256Hex(sessionId)))
+    .limit(1);
+
+  const found = rows[0];
+  if (found === undefined) return null;
+  // Defense in depth: a service account never validates a cookie session, even one inserted
+  // before createSession started refusing them.
+  if (found.isService) return null;
+  if (found.session.expiresAt.getTime() <= Date.now()) return null;
+  return { user: found.user, session: found.session };
+}
+
+/** Deletes a session row; deleting an unknown id is a no-op. */
+export async function destroySession(db: PolicyScopedDatabase, sessionId: string): Promise<void> {
+  // Deleting an unknown id stays a no-op; the stored key is the hash of the cookie value.
+  await db.delete(sessions).where(eq(sessions.id, await sha256Hex(sessionId)));
+}
+
+/**
+ * Structural event type: an H3/Nitro event satisfies it without importing h3 here.
+ * `context` stays a plain record because h3's H3EventContext exposes unknown values
+ * through an index signature; middleware writes `context.auth` (AuthContext | null).
+ */
+export type SessionEventContext = Record<string, unknown>;
+
+export interface SessionEvent {
+  context: SessionEventContext;
+  req: { headers: { get(name: string): string | null } };
+}
+
+export interface SessionMiddlewareDeps {
+  /** Database the middleware scopes; the runtime may connect as the facilis_app role. */
+  readonly db: FacilisDb;
+  readonly config: AuthConfig;
+  /** The deployment's tenant; a session whose user row names another one is rejected (D-040). */
+  readonly tenantId: string;
+}
+
+/**
+ * Builds the `facilis-session` middleware handler. An `Authorization: Bearer` token wins
+ * over the session cookie; otherwise it reads the cookie, then validates the session and
+ * loads app roles inside ONE deployment-tenant policy scope (`runWithPolicyScope`), expands
+ * the roles from config (SPEC §8.4.4) and sets `context.auth` with the auth channel in `via`.
+ *
+ * The scope matters: production connects as the non-superuser facilis_app role, so `users`
+ * is RLS-filtered and an unscoped read cannot see any user row. Running both queries in the
+ * tenant's transaction is what makes sessions work without a privileged client (D-068).
+ */
+export function sessionMiddleware(
+  deps: SessionMiddlewareDeps,
+): (event: SessionEvent) => Promise<void> {
+  return async (event) => {
+    const bearerToken = readBearerToken(event.req.headers.get("authorization"));
+    if (bearerToken !== null) {
+      // A bearer request never falls back to the cookie: the client chose token auth, so an
+      // invalid token is anonymous rather than a browser session. The raw token is only ever
+      // hashed here — it must never be logged or stored (D-099).
+      event.context.auth = await runWithPolicyScope(
+        deps.db,
+        { tenantId: deps.tenantId },
+        async (tx) => {
+          const validated = await validateApiToken(tx, bearerToken);
+          if (validated === null) return null;
+          return {
+            userId: validated.userId,
+            roles: [validated.role],
+            permissions: expandRoles([validated.role], deps.config),
+            sessionHash: validated.tokenHash,
+            via: "bearer" as const,
+          };
+        },
+      );
+      return;
+    }
+
+    const sessionId = readCookie(event.req.headers.get("cookie"), SESSION_COOKIE_NAME);
+    if (sessionId === null) {
+      event.context.auth = null;
+      return;
+    }
+
+    const auth = await runWithPolicyScope(deps.db, { tenantId: deps.tenantId }, async (tx) => {
+      const found = await validateSession(tx, sessionId);
+      if (found === null) return null;
+      // The tenant is the deployment's, never the session's (D-040). RLS already hides another
+      // tenant's user row from the lookup; this explicit check keeps the rule even on a
+      // connection where RLS would not apply (defense in depth).
+      if (found.user.tenantId !== deps.tenantId) return null;
+
+      const roles = await loadUserRoles(tx, found.user.id);
+      return {
+        userId: found.user.id,
+        roles,
+        permissions: expandRoles(roles, deps.config),
+      };
+    });
+    // Only a valid session gets a hash: the audit trail correlates requests with a session
+    // without ever storing the cookie value (D-099).
+    event.context.auth =
+      auth === null ? null : { ...auth, sessionHash: await sha256Hex(sessionId), via: "session" };
+  };
+}
+
+async function loadUserRoles(db: PolicyScopedDatabase, userId: string): Promise<string[]> {
+  const rows = await db
+    .select({ role: userRoles.role })
+    .from(userRoles)
+    .where(eq(userRoles.userId, userId));
+  return rows.map((row) => row.role);
+}
+
+/**
+ * Extracts the token from an `Authorization: Bearer <token>` header. The scheme is
+ * case-insensitive (RFC 7235) and the token is returned verbatim; an empty, absent or
+ * malformed header yields null, i.e. "no bearer auth".
+ */
+export function readBearerToken(header: string | null): string | null {
+  if (header === null || header.length === 0) return null;
+  const match = /^Bearer[ \t]+(.+)$/i.exec(header.trim());
+  const token = match?.[1]?.trim();
+  return token === undefined || token.length === 0 ? null : token;
+}
+
+function readCookie(header: string | null, name: string): string | null {
+  if (header === null || header.length === 0) return null;
+  for (const part of header.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator === -1) continue;
+    if (part.slice(0, separator).trim() !== name) continue;
+    const value = part.slice(separator + 1).trim();
+    return value.length === 0 ? null : value;
+  }
+  return null;
+}

package/src/sso/contracts.ts

@@ -0,0 +1,71 @@
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+
+/**
+ * Structural contracts shared by the SSO modules (D-120).
+ *
+ * @facilis.dev/core depends on @facilis.dev/auth (route.ts imports the RBAC helpers), so auth cannot
+ * import core without a package cycle. A system elevation is therefore described structurally:
+ * `ctx.system` from `defineAuthorizedHandler` satisfies {@link SystemRunner} without auth
+ * owning a copy of the core type.
+ */
+
+/** What a system elevation must say about itself; all fields are audited (D-099). */
+export interface SystemElevationOptions {
+  readonly actor: `system:${string}`;
+  readonly operation: string;
+  readonly reason: string;
+  /** Non-empty subset of the route's `dbTables`. */
+  readonly tables: readonly string[];
+}
+
+/** The audited system elevation passed into the SSO flow: never a raw database client. */
+export type SystemRunner = <T>(
+  options: SystemElevationOptions,
+  fn: (systemDb: PolicyScopedDatabase) => Promise<T>,
+) => Promise<T>;
+
+/** The identity an IdP asserts: the key, the email and whether that email is verified. */
+export interface IdentityClaims {
+  readonly provider: string;
+  readonly subject: string;
+  readonly email: string;
+  readonly emailVerified: boolean;
+}
+
+/** The audit input subset the SSO flow writes through `ctx.log.audit` (D-119). */
+export interface SsoAuditInput {
+  readonly operation: string;
+  readonly outcome?: "succeeded" | "failed";
+  readonly errorCode?: string;
+  readonly reason?: string;
+  readonly tables?: readonly string[];
+  readonly details?: Record<string, unknown>;
+}
+
+/** A narrower audit sink: `ctx.log.audit` satisfies it structurally. */
+export type SsoAudit = (input: SsoAuditInput) => void;
+
+/** The subset of the Fetch API the OAuth/OIDC/OAuth2 HTTP calls need (no Node dependency). */
+export interface FetchInit {
+  readonly method?: string;
+  readonly headers?: Record<string, string>;
+  readonly body?: string;
+}
+
+export interface FetchResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+
+export type FetchLike = (url: string, init?: FetchInit) => Promise<FetchResponse>;
+
+/** The runtime fetch, narrowed to {@link FetchLike}; tests inject their own. */
+export function runtimeFetch(): FetchLike {
+  const candidate = (globalThis as unknown as { fetch?: unknown }).fetch;
+  if (typeof candidate !== "function") {
+    throw new Error("facilis: the runtime has no fetch implementation for SSO");
+  }
+  return candidate as FetchLike;
+}

package/src/sso/errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Safe machine codes for the SSO namespace (D-120).
+ *
+ * The browser is redirected to `failureRedirect?sso_error=<code>`; an internal message, a token,
+ * an authorization code or a SAML payload never reaches the client. Callers log the cause
+ * server-side through `ctx.log` and expose only the code.
+ */
+
+export const SSO_ERROR_CODES = [
+  "sso_provider_unknown",
+  "sso_provider_unavailable",
+  "sso_state_invalid",
+  "sso_exchange_failed",
+  "sso_identity_invalid",
+  "sso_email_unverified",
+  // Verified IdP email matched a PASSWORD account that is not verified, in a deployment where
+  // email verification is off: linking it would be account pre-hijacking (SEC-02, D-156).
+  "sso_email_conflict",
+  "sso_account_not_found",
+  "sso_internal_error",
+] as const;
+
+export type SsoErrorCode = (typeof SSO_ERROR_CODES)[number];
+
+/** Thrown inside the flow; the route maps it to a redirect code, never to its message. */
+export class SsoError extends Error {
+  readonly code: SsoErrorCode;
+
+  constructor(code: SsoErrorCode, message?: string, options?: ErrorOptions) {
+    super(message ?? code, options);
+    this.name = "SsoError";
+    this.code = code;
+  }
+}
+
+export function isSsoError(error: unknown): error is SsoError {
+  return error instanceof SsoError;
+}
+
+/** Normalises any thrown value to a safe code; an unexpected failure is `sso_internal_error`. */
+export function ssoErrorCode(error: unknown): SsoErrorCode {
+  return isSsoError(error) ? error.code : "sso_internal_error";
+}
+
+/**
+ * Appends `sso_error=<code>` to the configured failure redirect, keeping its existing query
+ * string and fragment-free path. The redirect is same-origin by config validation (D-120).
+ */
+export function failureRedirectPath(failureRedirect: string, code: SsoErrorCode): string {
+  const url = new URL(failureRedirect, "http://facilis.invalid");
+  url.searchParams.set("sso_error", code);
+  return `${url.pathname}${url.search}`;
+}