@facilis.dev/auth 0.0.0-stage → 0.1.1

package/dist/tables.js

@@ -0,0 +1,148 @@
+import { sql } from "drizzle-orm";
+import { boolean, index, pgPolicy, pgTable, primaryKey, text, timestamp, uniqueIndex, uuid, } from "drizzle-orm/pg-core";
+import { rlsForTable, tenantColumn } from "@facilis.dev/db";
+const usersRls = rlsForTable({ tenantColumn: "tenant_id" });
+/**
+ * Auth tables (SPEC §5.3). Access is two-class (D-136): a table with RLS is reachable by the
+ * app role under its policies; a table without RLS is system-only (`facilis_app` has no
+ * privilege on it, only the audited system identity can read or write it).
+ *
+ * `role_permissions` and `roles` are the system-only pair: `role_permissions` is a
+ * projection of facilis.config.ts, written only by migrations/seed and never read at runtime
+ * (permissions come from the config through `expandRoles`). `sessions` and `user_roles` are
+ * app-reachable, so they carry an RLS policy that inherits the parent `users` row's
+ * visibility instead of restating tenant isolation.
+ *
+ * Users carry both policies: restrictive tenant isolation (D-008) AND-ed with a permissive
+ * "tenant scope present" policy, since Postgres denies by default when no permissive policy
+ * applies. Net effect: non-superusers only reach users of the tenant in `app.tenant_id`.
+ */
+export const users = pgTable("users", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    email: text("email").notNull().unique(),
+    // The registration insert has no session yet; the column takes the deployment tenant
+    // from the policy-scope GUC (D-040). Postgres fills it before the RLS check runs.
+    tenantId: tenantColumn(),
+    passwordHash: text("password_hash"),
+    // Service accounts exist only to back an API client. They have no password and every
+    // login path rejects them, so the flag is a stored fact the session/SSO code can check.
+    isService: boolean("is_service").notNull().default(false),
+    // null means "never verified" (D-156): a password account starts here and only the
+    // single-use link consumed by the verification route sets the timestamp.
+    emailVerifiedAt: timestamp("email_verified_at"),
+    createdAt: timestamp("created_at").defaultNow(),
+}, (table) => [
+    // Canonical identity: emails are stored normalized, and the unique lower(email) index makes
+    // a case variant rejected by the database too, not only by the app (D-150).
+    uniqueIndex("users_email_lower_idx").on(sql `lower(${table.email})`),
+    ...usersRls.policies,
+    pgPolicy("users_tenant_access", {
+        for: "all",
+        using: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+        withCheck: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+]).enableRLS();
+/**
+ * Inherits the parent `users` row's visibility instead of restating it (the D-053 pattern):
+ * a session or role assignment is reachable exactly when the user it points at is visible in
+ * the current tenant scope. This is what keeps the two tables app-reachable — their rows have
+ * no tenant column of their own (D-136).
+ */
+function parentUserAccessPolicy(name, column) {
+    const predicate = sql `exists (select 1 from ${users} u where u.id = ${column})`;
+    return pgPolicy(name, { for: "all", using: predicate, withCheck: predicate });
+}
+/**
+ * Email verification links (D-156): one active token per user, stored as `sha256(token)`; the raw
+ * link exists only in the delivered email. App-scoped like the other auth tables (D-136), and
+ * reached through the audited system elevation by the verification route, which has no session.
+ */
+const emailVerificationsRls = rlsForTable({ tenantColumn: "tenant_id" });
+export const authEmailVerifications = pgTable("auth_email_verifications", {
+    // sha256(token): a tenant-scoped read of the table cannot be replayed as a verification link.
+    id: text("id").primaryKey(),
+    userId: uuid("user_id")
+        .notNull()
+        .references(() => users.id, { onDelete: "cascade" }),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    expiresAt: timestamp("expires_at").notNull(),
+    tenantId: tenantColumn(),
+}, (table) => [
+    // One lookup per user for "rotate the outstanding link"; the primary key covers the token.
+    index("auth_email_verifications_user_idx").on(table.userId),
+    ...emailVerificationsRls.policies,
+    pgPolicy("auth_email_verifications_tenant_access", {
+        for: "all",
+        using: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+        withCheck: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+]).enableRLS();
+export const sessions = pgTable("sessions", {
+    // sha256(cookie id): the raw credential never reaches the table (D-144).
+    id: text("id").primaryKey(),
+    userId: uuid("user_id")
+        .notNull()
+        .references(() => users.id),
+    expiresAt: timestamp("expires_at").notNull(),
+}, (table) => [parentUserAccessPolicy("sessions_user_access", table.userId)]).enableRLS();
+// System-only (no RLS): seeded by the migration, never read by a route (D-136).
+export const roles = pgTable("roles", {
+    name: text("name").primaryKey(),
+});
+export const rolePermissions = pgTable("role_permissions", {
+    role: text("role")
+        .notNull()
+        .references(() => roles.name),
+    permission: text("permission").notNull(),
+}, (table) => [primaryKey({ columns: [table.role, table.permission] })]);
+export const userRoles = pgTable("user_roles", {
+    userId: uuid("user_id")
+        .notNull()
+        .references(() => users.id),
+    role: text("role")
+        .notNull()
+        .references(() => roles.name),
+    assignedBy: uuid("assigned_by"),
+    assignedAt: timestamp("assigned_at").defaultNow(),
+}, (table) => [
+    primaryKey({ columns: [table.userId, table.role] }),
+    parentUserAccessPolicy("user_roles_user_access", table.userId),
+]).enableRLS();
+/**
+ * Programmatic API clients (V3a). A client is a service user plus a hashed secret and a fixed
+ * role; both new tables are app-scoped through the parent user (D-136), so the RLS boundary
+ * stays the `users` table and a client row is reachable exactly when its service user is.
+ */
+export const apiClients = pgTable("api_clients", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    clientId: text("client_id").notNull().unique(),
+    // Only the SHA-256 of the secret is stored; the plaintext leaves the process once, in
+    // the createApiClient result, and can never be recovered from the database.
+    secretHash: text("secret_hash").notNull(),
+    name: text("name").notNull(),
+    // The client's fixed role: an issued token carries exactly this role, never the user's
+    // interactive roles (a service account has none worth expanding).
+    role: text("role").notNull(),
+    userId: uuid("user_id")
+        .notNull()
+        .references(() => users.id),
+    createdBy: uuid("created_by"),
+    createdAt: timestamp("created_at").defaultNow(),
+    revokedAt: timestamp("revoked_at"),
+    lastUsedAt: timestamp("last_used_at"),
+}, (table) => [parentUserAccessPolicy("api_clients_user_access", table.userId)]).enableRLS();
+export const apiTokens = pgTable("api_tokens", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    // Lookup key for a presented bearer token: SHA-256 of the raw value, never the value.
+    tokenHash: text("token_hash").notNull().unique(),
+    clientId: uuid("client_id")
+        .notNull()
+        .references(() => apiClients.id),
+    userId: uuid("user_id")
+        .notNull()
+        .references(() => users.id),
+    expiresAt: timestamp("expires_at").notNull(),
+    createdAt: timestamp("created_at").defaultNow(),
+    revokedAt: timestamp("revoked_at"),
+    lastUsedAt: timestamp("last_used_at"),
+}, (table) => [parentUserAccessPolicy("api_tokens_user_access", table.userId)]).enableRLS();

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@facilis.dev/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Facilis authentication and RBAC primitives: sessions, role expansion, permission checks.",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "dependencies": {
+    "@facilis.dev/db": "0.1.1",
+    "@node-saml/node-saml": "5.2.0",
+    "drizzle-orm": "0.45.4",
+    "jose": "6.2.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/facilis-dev/facilis.git",
+    "directory": "packages/auth"
+  },
+  "homepage": "https://github.com/facilis-dev/facilis/tree/main/packages/auth#readme",
+  "bugs": {
+    "url": "https://github.com/facilis-dev/facilis/issues"
+  },
+  "keywords": [
+    "facilis",
+    "framework",
+    "vite",
+    "nitro",
+    "low-code"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/api-clients.ts

@@ -0,0 +1,261 @@
+import { and, eq, isNull, lt, or } from "drizzle-orm";
+
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+
+import { constantTimeEqual, randomToken, sha256Hex } from "./crypto.ts";
+import { apiClients, apiTokens, roles, userRoles, users } from "./tables.ts";
+
+/**
+ * Programmatic API clients (V3a): a service user plus a hashed secret, and short-lived
+ * bearer tokens derived from it.
+ *
+ * Nothing secret is ever stored in the clear: the client secret and every access token are
+ * written as SHA-256 hex digests, and the plaintext appears only in the return value of the
+ * call that creates it (a one-time secret, like a password reset). Secrets are compared
+ * through `constantTimeEqual` so verification does not leak the first mismatching byte.
+ */
+
+/** Public credential prefixes: a leaked value is recognisable to secret scanners. */
+const CLIENT_ID_PREFIX = "fcli_";
+const CLIENT_SECRET_PREFIX = "fsec_";
+const ACCESS_TOKEN_PREFIX = "fat_";
+
+const CLIENT_ID_BYTES = 24;
+const CLIENT_SECRET_BYTES = 32;
+const ACCESS_TOKEN_BYTES = 32;
+
+/**
+ * A successful validation stamps `last_used_at` at most once per window instead of on every
+ * request: the column is for operators ("is this client still used?"), not an access log.
+ */
+const LAST_USED_WRITE_WINDOW_MS = 5 * 60 * 1000;
+
+export interface CreateApiClientInput {
+  readonly name: string;
+  readonly role: string;
+  /** Interactive user who created the client, when the caller knows it. */
+  readonly createdBy?: string | null;
+}
+
+export interface CreatedApiClient {
+  readonly id: string;
+  readonly clientId: string;
+  /** One-time plaintext secret: never persisted and not recoverable afterwards. */
+  readonly secret: string;
+  readonly name: string;
+  readonly role: string;
+  readonly userId: string;
+}
+
+/** Management projection of a client: same columns minus `secretHash`, which never leaves. */
+export interface ApiClientSummary {
+  readonly id: string;
+  readonly clientId: string;
+  readonly name: string;
+  readonly role: string;
+  readonly createdAt: Date | null;
+  readonly revokedAt: Date | null;
+  readonly lastUsedAt: Date | null;
+  readonly userId: string;
+}
+
+export interface IssueApiTokenInput {
+  readonly clientId: string;
+  readonly clientSecret: string;
+  readonly ttlMs: number;
+}
+
+export interface IssuedApiToken {
+  readonly accessToken: string;
+  readonly expiresAt: Date;
+}
+
+export interface ValidatedApiToken {
+  readonly userId: string;
+  /** The client's fixed role, not the service user's (empty) interactive roles. */
+  readonly role: string;
+  /** SHA-256 of the raw token: the audit correlation value, safe to log. */
+  readonly tokenHash: string;
+}
+
+/**
+ * Creates a service user, its role assignment and an API client.
+ *
+ * Callers run this under the audited system identity: the `roles` table is system-only
+ * (D-136) and here it is the migration-time projection of `config.auth.roles`
+ * (`seedFromConfig`), so a role the project never declared is rejected before any row is
+ * written. The service user takes its tenant from the policy-scope GUC, exactly like a
+ * registration insert (D-040).
+ */
+export async function createApiClient(
+  db: PolicyScopedDatabase,
+  input: CreateApiClientInput,
+): Promise<CreatedApiClient> {
+  const knownRole = await db
+    .select({ name: roles.name })
+    .from(roles)
+    .where(eq(roles.name, input.role))
+    .limit(1);
+  if (knownRole.length === 0) throw new Error(`createApiClient: unknown role "${input.role}"`);
+
+  const createdUser = await db
+    .insert(users)
+    .values({
+      email: `service+${globalThis.crypto.randomUUID()}@facilis.invalid`,
+      passwordHash: null,
+      isService: true,
+    })
+    .returning({ id: users.id });
+  const user = createdUser[0];
+  if (user === undefined) throw new Error("createApiClient: service user insert returned no row");
+
+  await db.insert(userRoles).values({
+    userId: user.id,
+    role: input.role,
+    assignedBy: input.createdBy ?? null,
+  });
+
+  const clientId = `${CLIENT_ID_PREFIX}${randomToken(CLIENT_ID_BYTES)}`;
+  const secret = `${CLIENT_SECRET_PREFIX}${randomToken(CLIENT_SECRET_BYTES)}`;
+  const createdClient = await db
+    .insert(apiClients)
+    .values({
+      clientId,
+      secretHash: await sha256Hex(secret),
+      name: input.name,
+      role: input.role,
+      userId: user.id,
+      createdBy: input.createdBy ?? null,
+    })
+    .returning({ id: apiClients.id });
+  const client = createdClient[0];
+  if (client === undefined) throw new Error("createApiClient: api client insert returned no row");
+
+  return { id: client.id, clientId, secret, name: input.name, role: input.role, userId: user.id };
+}
+
+/** Lists clients for management; the secret hash is never part of the projection. */
+export async function listApiClients(db: PolicyScopedDatabase): Promise<ApiClientSummary[]> {
+  return db
+    .select({
+      id: apiClients.id,
+      clientId: apiClients.clientId,
+      name: apiClients.name,
+      role: apiClients.role,
+      createdAt: apiClients.createdAt,
+      revokedAt: apiClients.revokedAt,
+      lastUsedAt: apiClients.lastUsedAt,
+      userId: apiClients.userId,
+    })
+    .from(apiClients);
+}
+
+/**
+ * Revokes a client and every token issued to it. Returns false for an unknown id; revoking
+ * twice is a no-op that keeps the first revocation timestamp (it is an audit fact).
+ */
+export async function revokeApiClient(db: PolicyScopedDatabase, id: string): Promise<boolean> {
+  const found = await db
+    .select({ id: apiClients.id })
+    .from(apiClients)
+    .where(eq(apiClients.id, id))
+    .limit(1);
+  if (found.length === 0) return false;
+
+  const now = new Date();
+  await db
+    .update(apiClients)
+    .set({ revokedAt: now })
+    .where(and(eq(apiClients.id, id), isNull(apiClients.revokedAt)));
+  await db
+    .update(apiTokens)
+    .set({ revokedAt: now })
+    .where(and(eq(apiTokens.clientId, id), isNull(apiTokens.revokedAt)));
+  return true;
+}
+
+/**
+ * Exchanges a client id + secret for a bearer token. Returns null for an unknown client, a
+ * wrong secret or a revoked client: the caller cannot tell which one failed.
+ */
+export async function issueApiToken(
+  db: PolicyScopedDatabase,
+  input: IssueApiTokenInput,
+): Promise<IssuedApiToken | null> {
+  const clients = await db
+    .select({
+      id: apiClients.id,
+      userId: apiClients.userId,
+      secretHash: apiClients.secretHash,
+      revokedAt: apiClients.revokedAt,
+    })
+    .from(apiClients)
+    .where(eq(apiClients.clientId, input.clientId))
+    .limit(1);
+  const client = clients[0];
+  if (client === undefined) return null;
+  if (client.revokedAt !== null) return null;
+
+  const presentedHash = await sha256Hex(input.clientSecret);
+  if (!hashesEqual(presentedHash, client.secretHash)) return null;
+
+  const accessToken = `${ACCESS_TOKEN_PREFIX}${randomToken(ACCESS_TOKEN_BYTES)}`;
+  const expiresAt = new Date(Date.now() + input.ttlMs);
+  await db.insert(apiTokens).values({
+    tokenHash: await sha256Hex(accessToken),
+    clientId: client.id,
+    userId: client.userId,
+    expiresAt,
+  });
+  await db.update(apiClients).set({ lastUsedAt: new Date() }).where(eq(apiClients.id, client.id));
+  return { accessToken, expiresAt };
+}
+
+/**
+ * Validates a raw bearer token: revoked/expired tokens and tokens of a revoked client are
+ * rejected. Refreshing `last_used_at` is a conditional UPDATE, so a burst of requests does
+ * not turn into a burst of writes or race on the same row.
+ */
+export async function validateApiToken(
+  db: PolicyScopedDatabase,
+  rawToken: string,
+): Promise<ValidatedApiToken | null> {
+  const tokenHash = await sha256Hex(rawToken);
+  const rows = await db
+    .select({
+      id: apiTokens.id,
+      userId: apiTokens.userId,
+      expiresAt: apiTokens.expiresAt,
+      revokedAt: apiTokens.revokedAt,
+      role: apiClients.role,
+      clientRevokedAt: apiClients.revokedAt,
+    })
+    .from(apiTokens)
+    .innerJoin(apiClients, eq(apiTokens.clientId, apiClients.id))
+    .where(eq(apiTokens.tokenHash, tokenHash))
+    .limit(1);
+
+  const found = rows[0];
+  if (found === undefined) return null;
+  if (found.revokedAt !== null || found.clientRevokedAt !== null) return null;
+  if (found.expiresAt.getTime() <= Date.now()) return null;
+
+  const now = new Date();
+  const staleBefore = new Date(now.getTime() - LAST_USED_WRITE_WINDOW_MS);
+  await db
+    .update(apiTokens)
+    .set({ lastUsedAt: now })
+    .where(
+      and(
+        eq(apiTokens.id, found.id),
+        or(isNull(apiTokens.lastUsedAt), lt(apiTokens.lastUsedAt, staleBefore)),
+      ),
+    );
+
+  return { userId: found.userId, role: found.role, tokenHash };
+}
+
+/** Constant-time comparison of two hex digests (both fixed-length SHA-256 output). */
+function hashesEqual(left: string, right: string): boolean {
+  return constantTimeEqual(new TextEncoder().encode(left), new TextEncoder().encode(right));
+}

package/src/crypto.ts

@@ -0,0 +1,101 @@
+/**
+ * Runtime-agnostic WebCrypto access. @facilis.dev/auth runs inside a browser WebContainer too,
+ * so it uses the standard `globalThis.crypto` surface and never `node:crypto`.
+ */
+
+export interface SubtleCryptoLike {
+  importKey(
+    format: "raw",
+    keyData: Uint8Array,
+    algorithm: "PBKDF2",
+    extractable: boolean,
+    keyUsages: readonly string[],
+  ): Promise<unknown>;
+  deriveBits(
+    algorithm: { name: "PBKDF2"; hash: "SHA-256"; salt: Uint8Array; iterations: number },
+    baseKey: unknown,
+    length: number,
+  ): Promise<ArrayBuffer>;
+  digest(algorithm: "SHA-256", data: Uint8Array): Promise<ArrayBuffer>;
+}
+
+export interface WebCryptoLike {
+  readonly subtle: SubtleCryptoLike;
+  getRandomValues<T extends Uint8Array>(array: T): T;
+}
+
+export function webcrypto(): WebCryptoLike {
+  const crypto = (globalThis as unknown as { crypto?: WebCryptoLike }).crypto;
+  if (crypto === undefined) throw new Error("WebCrypto is unavailable in this runtime");
+  return crypto;
+}
+
+export function randomBytes(length: number): Uint8Array {
+  return webcrypto().getRandomValues(new Uint8Array(length));
+}
+
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+export function encodeBase64(bytes: Uint8Array): string {
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1];
+    const third = bytes[index + 2];
+    const triple = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);
+    output += BASE64_ALPHABET[(triple >> 18) & 63] ?? "";
+    output += BASE64_ALPHABET[(triple >> 12) & 63] ?? "";
+    output += second === undefined ? "=" : (BASE64_ALPHABET[(triple >> 6) & 63] ?? "");
+    output += third === undefined ? "=" : (BASE64_ALPHABET[triple & 63] ?? "");
+  }
+  return output;
+}
+
+export function decodeBase64(value: string): Uint8Array | null {
+  if (value.length % 4 !== 0) return null;
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  const bytes: number[] = [];
+
+  for (let index = 0; index < value.length; index += 4) {
+    const chunk = value.slice(index, index + 4);
+    const symbols = [...chunk].map((character, offset) => {
+      if (character === "=" && offset >= 4 - padding) return 0;
+      return BASE64_ALPHABET.indexOf(character);
+    });
+    if (symbols.some((symbol) => symbol < 0)) return null;
+    const [first = 0, second = 0, third = 0, fourth = 0] = symbols;
+    const triple = (first << 18) | (second << 12) | (third << 6) | fourth;
+    bytes.push((triple >> 16) & 255, (triple >> 8) & 255, triple & 255);
+  }
+
+  const paddingBytes = padding === 0 ? [] : bytes.slice(-padding);
+  if (paddingBytes.some((byte) => byte !== 0)) return null;
+  return new Uint8Array(padding === 0 ? bytes : bytes.slice(0, -padding));
+}
+
+/** URL-safe random token (cookie-friendly, no padding). */
+export function randomToken(byteLength: number): string {
+  return encodeBase64(randomBytes(byteLength))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+/**
+ * SHA-256 of a string as lowercase hex. WebCrypto only, so the session-hash path also runs
+ * inside the browser WebContainer; the raw value is never stored or logged.
+ */
+export async function sha256Hex(value: string): Promise<string> {
+  const digest = await webcrypto().subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Compares secrets without leaking the index of the first mismatch. */
+export function constantTimeEqual(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) return false;
+  let difference = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+  }
+  return difference === 0;
+}

package/src/email-verification.ts

@@ -0,0 +1,107 @@
+import { eq } from "drizzle-orm";
+
+import type { PolicyScopedDatabase } from "@facilis.dev/db";
+
+import { randomToken, sha256Hex } from "./crypto.ts";
+import { authEmailVerifications, users } from "./tables.ts";
+
+/**
+ * Email verification for password accounts (D-156).
+ *
+ * The primitive is split from delivery on purpose: `@facilis.dev/auth` owns the single-use token and
+ * the `users.email_verified_at` transition, while the project (or the blueprint) owns how the
+ * link reaches the mailbox. Every call runs inside the caller's audited `ctx.system` elevation,
+ * because the verification route is reached before a session exists (same D-099 shape as
+ * registration).
+ *
+ * Tokens are stored as `sha256(token)`: a tenant-scoped read of the table yields no usable link,
+ * exactly like sessions (D-144) and SSO state (D-120).
+ */
+
+export const EMAIL_VERIFICATION_TABLES = ["auth_email_verifications", "users"] as const;
+
+export interface IssueEmailVerificationOptions {
+  /** Link lifetime (`auth.verification.tokenTtlMs`); always validated by the caller's config. */
+  readonly ttlMs: number;
+  /** Injectable clock for tests; defaults to the wall clock. */
+  readonly now?: Date;
+}
+
+export interface IssuedEmailVerification {
+  /** The raw token: only the delivered link carries it, never the database or the logs. */
+  readonly token: string;
+  readonly expiresAt: Date;
+}
+
+/**
+ * Rotates the user's outstanding link and returns the new token. A single active token per user
+ * keeps the table small and makes "the latest email wins" true: re-registering or resending
+ * invalidates the previous link.
+ */
+export async function issueEmailVerification(
+  db: PolicyScopedDatabase,
+  userId: string,
+  options: IssueEmailVerificationOptions,
+): Promise<IssuedEmailVerification> {
+  const now = options.now ?? new Date();
+  const expiresAt = new Date(now.getTime() + options.ttlMs);
+  const token = randomToken(32);
+
+  await db.delete(authEmailVerifications).where(eq(authEmailVerifications.userId, userId));
+  await db.insert(authEmailVerifications).values({
+    id: await sha256Hex(token),
+    userId,
+    createdAt: now,
+    expiresAt,
+  });
+
+  return { token, expiresAt };
+}
+
+/**
+ * Consumes a verification link: marks the user verified and returns the user id, or `null` for an
+ * unknown/expired token. The row is deleted before the expiry check, so a token is single-use even
+ * when it is already stale.
+ */
+export async function consumeEmailVerification(
+  db: PolicyScopedDatabase,
+  token: string,
+  now: Date = new Date(),
+): Promise<{ userId: string } | null> {
+  const id = await sha256Hex(token);
+  const rows = await db
+    .select({ userId: authEmailVerifications.userId, expiresAt: authEmailVerifications.expiresAt })
+    .from(authEmailVerifications)
+    .where(eq(authEmailVerifications.id, id))
+    .limit(1);
+  const row = rows[0];
+  if (row === undefined) return null;
+
+  await db.delete(authEmailVerifications).where(eq(authEmailVerifications.id, id));
+  if (row.expiresAt.getTime() <= now.getTime()) return null;
+
+  const updated = await db
+    .update(users)
+    .set({ emailVerifiedAt: now })
+    .where(eq(users.id, row.userId))
+    .returning({ id: users.id });
+  return updated[0] === undefined ? null : { userId: updated[0].id };
+}
+
+/**
+ * Marks the account verified without a link. Used by the blueprint's development fallback (no
+ * delivery channel configured in `development`/`test`, D-146) and by tests; production always
+ * goes through the token.
+ */
+export async function markEmailVerified(
+  db: PolicyScopedDatabase,
+  userId: string,
+  now: Date = new Date(),
+): Promise<boolean> {
+  const updated = await db
+    .update(users)
+    .set({ emailVerifiedAt: now })
+    .where(eq(users.id, userId))
+    .returning({ id: users.id });
+  return updated[0] !== undefined;
+}

package/src/email.ts

@@ -0,0 +1,9 @@
+/**
+ * Canonical email form (D-150). Registration, login, SSO linking and the bootstrap comparison
+ * all go through this function: the stored value, the unique `lower(email)` index and every
+ * lookup then agree on one identity, so a case variant can never create a second account or
+ * be mistaken for another one during the initial-admin promotion.
+ */
+export function normalizeEmail(email: string): string {
+  return email.trim().toLowerCase();
+}