@oimlsmart/platform-server 0.1.7 → 0.1.8

package/migrations/0022_account_emails.sql

@@ -0,0 +1,45 @@
+-- Migration 0022 — multiple emails per account (TODO.identity-features/01):
+-- the account gains a primary + additional addresses, each verified
+-- independently, the sign-in and the recovery paths resolving by ANY
+-- verified one.
+--
+-- The model:
+--   - the PRIMARY address stays users.email (+ users.email_verified_at):
+--     the OIDC `email` claim never changes shape, every existing reader
+--     (the claims, the registry, the audit chain) is undisturbed, and the
+--     claims keep carrying the primary on a switch;
+--   - account_emails carries the ADDITIONAL addresses only — one row per
+--     (account, address), verified_at NULL until the per-address ceremony
+--     proves the mailbox. An address is globally unique across the estate
+--     of addresses: the unique index keys it here, and the store's writes
+--     check BOTH tables (an additional on account A blocks the address as
+--     a primary or an additional anywhere else);
+--   - the "primary" attribute is represented by WHERE the address lives
+--     (the users row vs account_emails), never a flag to keep in sync —
+--     the store's setPrimaryAccountEmail swaps the two residences with
+--     their verification stamps;
+--   - email_change_tokens gains `kind`: 'change' (the pre-0022 primary
+--     replacement — the default, so existing rows read honestly) and
+--     'add' (the per-address verification of an account_emails row; the
+--     row lands unverified at the request and the token's completion
+--     stamps verified_at). The same one-time, 24 h, atomically-consumed
+--     doctrine carries both.
+-- schema.sql carries the same end state for fresh databases —
+-- test/migrations.test.ts pins the UNION of every migration to
+-- schema.sql's CREATE set.
+
+CREATE TABLE IF NOT EXISTS account_emails (
+  user_id TEXT NOT NULL REFERENCES users(id),
+  email TEXT NOT NULL,
+  verified_at TEXT,
+  added_by TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, email)
+);
+-- An address names at most ONE account across the estate (the sign-in
+-- and recovery resolutions depend on it); the users.email UNIQUE covers
+-- the primaries, this index the additionals, and the store's writes
+-- check across both.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_account_emails_email ON account_emails (email);
+
+ALTER TABLE email_change_tokens ADD COLUMN kind TEXT NOT NULL DEFAULT 'change';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "The OIML SMART platform server kernel: the store seam (ServerStore + the D1 and SQLite implementations), the canonical D1 migration set both deployments apply, the instance profile, the mailer, the RBAC map, the OIDC/OAuth client cones, and the shared role/permission vocabulary. Consumed by the smart monorepo (browser/) and the identity service.",
   "type": "module",
   "repository": {

package/src/store/d1.ts

@@ -21,6 +21,8 @@
 import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
 import {
   DEMO_PASSWORD,
+  type AccountEmail,
+  type AddAccountEmailResult,
   type AdvanceCounterResult,
   type AuthUserPayload,
   type CompleteEmailChangeResult,
@@ -510,6 +512,36 @@ export class D1ServerStore implements ServerStore {
     return this.consentGrantSupportEnsured
   }
 
+  // TODO.identity-features/01 (multiple emails per account): the
+  // account_emails table + the email_change_tokens.kind column arrive
+  // with migration 0022 — a dev D1 migrated from before it lacks both,
+  // so the address methods ensure them defensively (the
+  // ensureConsentGrantSupport posture, memoized per store).
+  private accountEmailSupportEnsured: Promise<void> | null = null
+
+  private ensureAccountEmailSupport(): Promise<void> {
+    if (!this.accountEmailSupportEnsured) {
+      this.accountEmailSupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS account_emails (
+             user_id TEXT NOT NULL REFERENCES users(id),
+             email TEXT NOT NULL,
+             verified_at TEXT,
+             added_by TEXT,
+             created_at TEXT NOT NULL DEFAULT (datetime('now')),
+             PRIMARY KEY (user_id, email)
+           )`,
+        ).run()
+        await this.db.prepare('CREATE UNIQUE INDEX IF NOT EXISTS idx_account_emails_email ON account_emails (email)').run()
+        const tokenCols = await this.db.prepare('PRAGMA table_info(email_change_tokens)').all<{ name: string }>()
+        if (!tokenCols.results.some(c => c.name === 'kind')) {
+          await this.db.prepare("ALTER TABLE email_change_tokens ADD COLUMN kind TEXT NOT NULL DEFAULT 'change'").run()
+        }
+      })()
+    }
+    return this.accountEmailSupportEnsured
+  }
+
   // ── users / sessions ─────────────────────────────────────────────
 
   async seedDemoAccounts(): Promise<void> {
@@ -1374,6 +1406,13 @@ export class D1ServerStore implements ServerStore {
     createdBy?: string | null
   }): Promise<UserAdminRow | null> {
     const id = crypto.randomUUID()
+    // TODO.identity-features/01: the address must be free across BOTH
+    // address tables — an additional on another account blocks the
+    // address as a new account's primary (an address names at most one
+    // account; the users.email UNIQUE remains the race backstop).
+    await this.ensureAccountEmailSupport()
+    const additional = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', input.email.trim().toLowerCase()).first<{ user_id: string }>()
+    if (additional) return null
     try {
       await this.stmt(
         "INSERT INTO users (id, email, name, provider, role) VALUES (?, ?, ?, 'password', ?)",
@@ -1388,14 +1427,28 @@ export class D1ServerStore implements ServerStore {
   }
 
   /** The password sign-in's lookup: the credential + the active flag, by
-   *  (normalized) email. The credential's EXISTENCE is the qualifier. */
+   *  (normalized) email. The credential's EXISTENCE is the qualifier.
+   *  TODO.identity-features/01: the address resolves by ANY of the
+   *  account's VERIFIED addresses — the primary first (the primary owner
+   *  always wins, the deterministic rule), then a proven account_emails
+   *  row; an unverified additional never resolves. */
   async getPasswordLogin(email: string): Promise<{ userId: string; hash: string; active: boolean } | null> {
-    const row = await this.stmt(
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    let row = await this.stmt(
       `SELECT u.id AS user_id, u.active AS active, p.hash AS hash
        FROM users u JOIN passwords p ON p.user_id = u.id
        WHERE u.email = ?`,
-      email.trim().toLowerCase(),
+      normalized,
     ).first<{ user_id: string; active: number; hash: string }>()
+    if (!row) {
+      row = await this.stmt(
+        `SELECT u.id AS user_id, u.active AS active, p.hash AS hash
+         FROM users u JOIN passwords p ON p.user_id = u.id
+         WHERE u.id = (SELECT user_id FROM account_emails WHERE email = ? AND verified_at IS NOT NULL)`,
+        normalized,
+      ).first<{ user_id: string; active: number; hash: string }>()
+    }
     if (!row) return null
     return { userId: row.user_id, hash: row.hash, active: row.active !== 0 }
   }
@@ -1620,6 +1673,10 @@ export class D1ServerStore implements ServerStore {
     // the account (a tombstone never skips a consent page again).
     await this.ensureConsentGrantSupport()
     const consentGrants = await this.stmt('DELETE FROM oidc_consent_grants WHERE user_id = ?', userId).run()
+    // TODO.identity-features/01: the additional addresses die with the
+    // account (a tombstone's addresses never resolve a sign-in again).
+    await this.ensureAccountEmailSupport()
+    const emails = await this.stmt('DELETE FROM account_emails WHERE user_id = ?', userId).run()
     await this.stmt(
       `UPDATE users SET
          email = ?, name = 'Deleted account', provider = 'erased',
@@ -1638,13 +1695,20 @@ export class D1ServerStore implements ServerStore {
         + (challenges.meta.changes ?? 0) + (mfa.meta.changes ?? 0),
       personalAccessTokens: personalAccessTokens.meta.changes ?? 0,
       consentGrants: consentGrants.meta.changes ?? 0,
+      emails: emails.meta.changes ?? 0,
     }
   }
 
   /** The registry's edit act (name/email). The email UNIQUE conflict
-   *  throws 'unique' (the route maps it to a 409, never a silent take). */
+   *  throws 'unique' (the route maps it to a 409, never a silent take).
+   *  TODO.identity-features/01: the conflict read spans BOTH address
+   *  tables — an additional row (on any account, this one included)
+   *  holds the address too. */
   async updateOpAccount(id: string, input: { name?: string; email?: string }): Promise<boolean> {
     if (input.email !== undefined) {
+      await this.ensureAccountEmailSupport()
+      const additional = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', input.email.trim().toLowerCase()).first<{ user_id: string }>()
+      if (additional) throw new Error(`unique: ${input.email}`)
       try {
         // TODO.identity/06: an admin-set address never went through the
         // verify-new-email ceremony, so the verification state resets.
@@ -1717,29 +1781,46 @@ export class D1ServerStore implements ServerStore {
       userId: row.user_id as string,
       newEmail: row.new_email as string,
       deliveredBy: row.delivered_by === 'mailer' ? 'mailer' : 'shown',
+      // TODO.identity-features/01: rows predating the kind column (or a
+      // store over a pre-0022 database) read as the legacy ceremony.
+      kind: row.kind === 'add' ? 'add' : 'change',
       createdAt: row.created_at as string,
       expiresAt: row.expires_at as string,
       consumedAt: (row.consumed_at as string | null) ?? null,
     }
   }
 
-  /** Mint the ceremony's token; the account's earlier pending rows are
-   *  VOIDED first (only the newest link works). */
+  /** Mint the ceremony's token. The void rule keeps ONE live link per
+   *  ceremony target: a 'change' request voids the account's earlier
+   *  pending 'change' rows (only the newest change link works — the
+   *  pre-01 doctrine); an 'add' request voids the account's earlier
+   *  pending 'add' rows FOR THE SAME address (other addresses' links
+   *  stand). */
   async createEmailChangeToken(input: {
     token: string
     userId: string
     newEmail: string
     deliveredBy: 'mailer' | 'shown'
+    kind?: 'change' | 'add'
     ttlMs: number
   }): Promise<EmailChangeToken> {
-    await this.stmt(
-      "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND consumed_at IS NULL",
-      input.userId,
-    ).run()
+    await this.ensureAccountEmailSupport()
+    const kind = input.kind ?? 'change'
+    if (kind === 'change') {
+      await this.stmt(
+        "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'change' AND consumed_at IS NULL",
+        input.userId,
+      ).run()
+    } else {
+      await this.stmt(
+        "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'add' AND new_email = ? AND consumed_at IS NULL",
+        input.userId, input.newEmail.trim().toLowerCase(),
+      ).run()
+    }
     const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
     await this.stmt(
-      'INSERT INTO email_change_tokens (token, user_id, new_email, delivered_by, expires_at) VALUES (?, ?, ?, ?, ?)',
-      input.token, input.userId, input.newEmail.trim().toLowerCase(), input.deliveredBy, expiresAt,
+      'INSERT INTO email_change_tokens (token, user_id, new_email, delivered_by, kind, expires_at) VALUES (?, ?, ?, ?, ?, ?)',
+      input.token, input.userId, input.newEmail.trim().toLowerCase(), input.deliveredBy, kind, expiresAt,
     ).run()
     return (await this.getEmailChangeToken(input.token))!
   }
@@ -1749,12 +1830,15 @@ export class D1ServerStore implements ServerStore {
     return row ? D1ServerStore.toEmailChangeToken(row) : null
   }
 
-  /** The account's pending change (the newest live row), so the console
-   *  can show it. */
+  /** The account's pending PRIMARY change (the newest live 'change'
+   *  row), so the console can show it. The per-address verifications are
+   *  the account_emails rows' own state (verified_at NULL = waiting),
+   *  never a pending read here. */
   async getPendingEmailChange(userId: string): Promise<EmailChangeToken | null> {
+    await this.ensureAccountEmailSupport()
     const row = await this.stmt(
       `SELECT * FROM email_change_tokens
-       WHERE user_id = ? AND consumed_at IS NULL AND expires_at > datetime('now')
+       WHERE user_id = ? AND kind = 'change' AND consumed_at IS NULL AND expires_at > datetime('now')
        ORDER BY created_at DESC LIMIT 1`,
       userId,
     ).first<Record<string, unknown>>()
@@ -1762,20 +1846,34 @@ export class D1ServerStore implements ServerStore {
   }
 
   /** Complete the ceremony: consume ATOMICALLY (a presented link works
-   *  exactly once, expired or not), judge the expiry, re-check the
-   *  address's uniqueness (a conflict burns the token honestly), then
-   *  move the account's email. A 'mailer'-delivered token verifies the
-   *  address; a shown one never does. */
+   *  exactly once, expired or not), judge the expiry, then act on the
+   *  kind. 'change' (the pre-01 primary replacement): re-check the
+   *  address's uniqueness across BOTH address tables (a conflict burns
+   *  the token honestly — an additional row anywhere holds the address
+   *  too, this account's included), then move users.email. 'add' (the
+   *  per-address verification): the account_emails row landed unverified
+   *  at the request; the completion stamps it (a row removed meanwhile
+   *  burns the link as 'unknown'). A 'mailer'-delivered token verifies
+   *  the address; a shown one never does. */
   async completeEmailChange(token: string): Promise<CompleteEmailChangeResult> {
+    await this.ensureAccountEmailSupport()
     const res = await this.stmt(
       "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE token = ? AND consumed_at IS NULL", token,
     ).run()
     if ((res.meta.changes ?? 0) === 0) return { kind: 'unknown' }
     const row = (await this.getEmailChangeToken(token))!
     if (new Date(row.expiresAt).getTime() <= Date.now()) return { kind: 'expired' }
+    const verified = row.deliveredBy === 'mailer'
+    if (row.kind === 'add') {
+      const standing = await this.stmt('SELECT 1 AS ok FROM account_emails WHERE user_id = ? AND email = ?', row.userId, row.newEmail).first<{ ok: number }>()
+      if (!standing) return { kind: 'unknown' }
+      if (verified) await this.markAccountEmailVerified(row.userId, row.newEmail)
+      return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
+    }
     const taken = await this.stmt('SELECT id FROM users WHERE email = ?', row.newEmail).first<{ id: string }>()
     if (taken) return { kind: 'conflict' }
-    const verified = row.deliveredBy === 'mailer'
+    const takenAdditional = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', row.newEmail).first<{ user_id: string }>()
+    if (takenAdditional) return { kind: 'conflict' }
     await this.stmt(
       `UPDATE users SET email = ?, email_verified_at = ${verified ? "datetime('now')" : 'NULL'} WHERE id = ?`,
       row.newEmail, row.userId,
@@ -1783,6 +1881,116 @@ export class D1ServerStore implements ServerStore {
     return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
   }
 
+  // ── multiple emails per account (TODO.identity-features/01) ────────
+
+  private static toAccountEmail(row: Record<string, unknown>, isPrimary: boolean): AccountEmail {
+    return {
+      userId: row.user_id as string,
+      email: row.email as string,
+      verifiedAt: (row.verified_at as string | null) ?? null,
+      isPrimary,
+      addedBy: (row.added_by as string | null) ?? null,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  /** The account's addresses: the PRIMARY first (the users row's email +
+   *  its verification stamp), then the additional account_emails rows
+   *  (oldest first). */
+  async listAccountEmails(userId: string): Promise<AccountEmail[]> {
+    await this.ensureAccountEmailSupport()
+    const primary = await this.stmt(
+      'SELECT id AS user_id, email, email_verified_at AS verified_at, created_at FROM users WHERE id = ?', userId,
+    ).first<Record<string, unknown>>()
+    const res = await this.stmt(
+      'SELECT * FROM account_emails WHERE user_id = ? ORDER BY created_at, email', userId,
+    ).all<Record<string, unknown>>()
+    const out: AccountEmail[] = []
+    if (primary) out.push(D1ServerStore.toAccountEmail(primary, true))
+    out.push(...res.results.map(r => D1ServerStore.toAccountEmail(r, false)))
+    return out
+  }
+
+  /** Resolve the account by ANY of its addresses: the primary always
+   *  names it (and the primary owner always wins — the deterministic
+   *  rule); an additional ONLY when verified. */
+  async findUserByAnyEmail(email: string): Promise<AuthUserPayload | null> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const primary = await this.stmt('SELECT * FROM users WHERE email = ?', normalized).first<UserRecord>()
+    if (primary) return toPayload(primary)
+    const owner = await this.stmt(
+      'SELECT user_id FROM account_emails WHERE email = ? AND verified_at IS NOT NULL', normalized,
+    ).first<{ user_id: string }>()
+    if (!owner) return null
+    const user = await this.stmt('SELECT * FROM users WHERE id = ?', owner.user_id).first<UserRecord>()
+    return user ? toPayload(user) : null
+  }
+
+  /** Add an ADDITIONAL address (normalized lowercase; the row lands
+   *  UNVERIFIED). The account's own existing row answers 'present' (the
+   *  idempotent re-add); any other hold of the address — a primary
+   *  anywhere (this account's included) or another account's additional
+   *  — answers 'conflict'. The unique index is the race backstop. */
+  async addAccountEmail(userId: string, email: string, addedBy?: string | null): Promise<AddAccountEmailResult> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const takenPrimary = await this.stmt('SELECT id FROM users WHERE email = ?', normalized).first<{ id: string }>()
+    if (takenPrimary) return 'conflict'
+    const existing = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', normalized).first<{ user_id: string }>()
+    if (existing) return existing.user_id === userId ? 'present' : 'conflict'
+    try {
+      await this.stmt(
+        'INSERT INTO account_emails (user_id, email, added_by) VALUES (?, ?, ?)',
+        userId, normalized, addedBy ?? null,
+      ).run()
+    } catch (e) {
+      if (String((e as Error).message).includes('UNIQUE')) return 'conflict'
+      throw e
+    }
+    return 'added'
+  }
+
+  /** The verification ceremony's stamp on the account's OWN row: the
+   *  guarded UPDATE flips verified_at, once. */
+  async markAccountEmailVerified(userId: string, email: string): Promise<boolean> {
+    await this.ensureAccountEmailSupport()
+    const res = await this.stmt(
+      "UPDATE account_emails SET verified_at = datetime('now') WHERE user_id = ? AND email = ? AND verified_at IS NULL",
+      userId, email.trim().toLowerCase(),
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** Promote a VERIFIED additional to primary: the promoted address
+   *  becomes users.email with its verification stamp; the outgoing
+   *  primary takes the row's place in account_emails with ITS stamp
+   *  (it stays a verified additional — sign-in by it keeps working). */
+  async setPrimaryAccountEmail(userId: string, email: string): Promise<'ok' | 'unknown' | 'unverified'> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const row = await this.stmt('SELECT * FROM account_emails WHERE user_id = ? AND email = ?', userId, normalized).first<Record<string, unknown>>()
+    if (!row) return 'unknown'
+    if (!row.verified_at) return 'unverified'
+    const current = await this.stmt('SELECT email, email_verified_at FROM users WHERE id = ?', userId).first<{ email: string; email_verified_at: string | null }>()
+    if (!current) return 'unknown'
+    await this.stmt('UPDATE users SET email = ?, email_verified_at = ? WHERE id = ?', normalized, row.verified_at as string, userId).run()
+    await this.stmt('DELETE FROM account_emails WHERE user_id = ? AND email = ?', userId, normalized).run()
+    await this.stmt('INSERT INTO account_emails (user_id, email, verified_at) VALUES (?, ?, ?)', userId, current.email, current.email_verified_at).run()
+    return 'ok'
+  }
+
+  /** Remove an ADDITIONAL address. The primary refuses honestly
+   *  ('primary' — promote another address first). */
+  async removeAccountEmail(userId: string, email: string): Promise<'ok' | 'primary' | 'unknown'> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const current = await this.stmt('SELECT email FROM users WHERE id = ?', userId).first<{ email: string }>()
+    if (current?.email === normalized) return 'primary'
+    const res = await this.stmt('DELETE FROM account_emails WHERE user_id = ? AND email = ?', userId, normalized).run()
+    return (res.meta.changes ?? 0) > 0 ? 'ok' : 'unknown'
+  }
+
   // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03) ──
   // The same SQL as the SQLite half (store/sqlite/factors-store.ts): the
   // one-time consumes are guarded UPDATEs, the counter advance is the

package/src/store/sqlite/op-accounts-store.ts

@@ -13,6 +13,9 @@
 import { randomUUID } from 'crypto'
 import { getDb } from './store'
 import type {
+  AccountEmail,
+  AddAccountEmailResult,
+  AuthUserPayload,
   CompleteEmailChangeResult,
   CompleteEnrollmentResult,
   EmailChangeToken,
@@ -23,6 +26,27 @@ import type {
   UserAdminRow,
 } from '../../store'
 
+/** The AuthUserPayload projection of a users row (the sqlite/store.ts
+ *  userPayload shape — the full assigned role set rides along). */
+function accountPayload(row: Record<string, unknown>): AuthUserPayload {
+  let roles: string[] | undefined
+  try {
+    const parsed = JSON.parse((row.roles as string | null) ?? 'null') as unknown
+    roles = Array.isArray(parsed) && parsed.length ? parsed.filter((v): v is string => typeof v === 'string') : undefined
+  } catch { roles = undefined }
+  return {
+    id: row.id as string,
+    email: row.email as string,
+    name: row.name as string,
+    role: row.role as string,
+    ...(roles?.length ? { roles } : {}),
+    orgId: (row.org_id as string | null) ?? null,
+    avatarUrl: (row.avatar_url as string | null) ?? undefined,
+    provider: row.provider as string,
+    emailVerifiedAt: (row.email_verified_at as string | null) ?? null,
+  }
+}
+
 function toEnrollmentToken(row: Record<string, unknown>): EnrollmentToken {
   return {
     token: row.token as string,
@@ -35,7 +59,9 @@ function toEnrollmentToken(row: Record<string, unknown>): EnrollmentToken {
 }
 
 /** Create the OP password account. Answers null when the email is taken
- *  (the invite route's 409; the UNIQUE constraint is the race backstop). */
+ *  (the invite route's 409; the UNIQUE constraint is the race backstop).
+ *  TODO.identity-features/01: the taken read spans BOTH address tables —
+ *  an additional on another account blocks the address as a primary. */
 export function createOpAccount(input: {
   email: string
   name: string
@@ -44,6 +70,8 @@ export function createOpAccount(input: {
 }): UserAdminRow | null {
   const db = getDb()
   const id = randomUUID()
+  const additional = db.prepare('SELECT user_id FROM account_emails WHERE email = ?').get(input.email.trim().toLowerCase())
+  if (additional) return null
   try {
     db.prepare(
       "INSERT INTO users (id, email, name, provider, role) VALUES (?, ?, ?, 'password', ?)",
@@ -68,13 +96,26 @@ export function createOpAccount(input: {
 
 /** The password sign-in's lookup: the credential + the active flag, by
  *  (normalized) email. The credential's EXISTENCE is the qualifier — an
- *  account that holds a password may sign in with it. */
+ *  account that holds a password may sign in with it.
+ *  TODO.identity-features/01: the address resolves by ANY of the
+ *  account's VERIFIED addresses — the primary first (the primary owner
+ *  always wins, the deterministic rule), then a proven account_emails
+ *  row; an unverified additional never resolves. */
 export function getPasswordLogin(email: string): { userId: string; hash: string; active: boolean } | null {
-  const row = getDb().prepare(
+  const db = getDb()
+  const normalized = email.trim().toLowerCase()
+  let row = db.prepare(
     `SELECT u.id AS user_id, u.active AS active, p.hash AS hash
      FROM users u JOIN passwords p ON p.user_id = u.id
      WHERE u.email = ?`,
-  ).get(email.trim().toLowerCase()) as Record<string, unknown> | undefined
+  ).get(normalized) as Record<string, unknown> | undefined
+  if (!row) {
+    row = db.prepare(
+      `SELECT u.id AS user_id, u.active AS active, p.hash AS hash
+       FROM users u JOIN passwords p ON p.user_id = u.id
+       WHERE u.id = (SELECT user_id FROM account_emails WHERE email = ? AND verified_at IS NOT NULL)`,
+    ).get(normalized) as Record<string, unknown> | undefined
+  }
   if (!row) return null
   return { userId: row.user_id as string, hash: row.hash as string, active: row.active !== 0 }
 }
@@ -272,10 +313,15 @@ export function revokeOpUserCredentials(userId: string): { sessions: number; acc
 /** The registry's edit act (name/email). The email UNIQUE conflict
  *  throws 'unique' (the route maps it to a 409, never a silent take).
  *  TODO.identity/06: an admin-set address never went through the
- *  verify-new-email ceremony, so the verification state resets. */
+ *  verify-new-email ceremony, so the verification state resets.
+ *  TODO.identity-features/01: the conflict read spans BOTH address
+ *  tables — an additional row (on any account, this one included) holds
+ *  the address too. */
 export function updateOpAccount(id: string, input: { name?: string; email?: string }): boolean {
   const db = getDb()
   if (input.email !== undefined) {
+    const additional = db.prepare('SELECT user_id FROM account_emails WHERE email = ?').get(input.email.trim().toLowerCase())
+    if (additional) throw new Error(`unique: ${input.email}`)
     try {
       db.prepare('UPDATE users SET email = ?, email_verified_at = NULL WHERE id = ?').run(input.email.trim().toLowerCase(), id)
     } catch (e) {
@@ -314,6 +360,7 @@ export function eraseOpAccount(userId: string): {
   factors: number
   personalAccessTokens: number
   consentGrants: number
+  emails: number
 } | null {
   const db = getDb()
   const row = db.prepare('SELECT 1 AS ok FROM users WHERE id = ?').get(userId)
@@ -343,6 +390,9 @@ export function eraseOpAccount(userId: string): {
   // TODO.identity-features/12: the remembered consent grants die with the
   // account (a tombstone never skips a consent page again).
   const consentGrants = db.prepare('DELETE FROM oidc_consent_grants WHERE user_id = ?').run(userId).changes
+  // TODO.identity-features/01: the additional addresses die with the
+  // account (a tombstone's addresses never resolve a sign-in again).
+  const emails = db.prepare('DELETE FROM account_emails WHERE user_id = ?').run(userId).changes
   db.prepare(
     `UPDATE users SET
        email = ?, name = 'Deleted account', provider = 'erased',
@@ -350,7 +400,7 @@ export function eraseOpAccount(userId: string): {
        avatar_url = NULL, email_verified_at = NULL, active = 0
      WHERE id = ?`,
   ).run(`deleted-${userId}@erased.invalid`, userId)
-  return { ...revoked, links, clientRoles, memberships, tokens, factors, personalAccessTokens, consentGrants }
+  return { ...revoked, links, clientRoles, memberships, tokens, factors, personalAccessTokens, consentGrants, emails }
 }
 
 /** The last OP-side sign-in per account, FROM THE AUDIT CHAIN: the
@@ -413,29 +463,44 @@ function toEmailChangeToken(row: Record<string, unknown>): EmailChangeToken {
     userId: row.user_id as string,
     newEmail: row.new_email as string,
     deliveredBy: row.delivered_by === 'mailer' ? 'mailer' : 'shown',
+    // TODO.identity-features/01: rows predating the kind column read as
+    // the legacy ceremony.
+    kind: row.kind === 'add' ? 'add' : 'change',
     createdAt: row.created_at as string,
     expiresAt: row.expires_at as string,
     consumedAt: (row.consumed_at as string | null) ?? null,
   }
 }
 
-/** Mint the ceremony's token; the account's earlier pending rows are
- *  VOIDED first (only the newest link works). */
+/** Mint the ceremony's token. The void rule keeps ONE live link per
+ *  ceremony target: a 'change' request voids the account's earlier
+ *  pending 'change' rows (only the newest change link works — the
+ *  pre-01 doctrine); an 'add' request voids the account's earlier
+ *  pending 'add' rows FOR THE SAME address (other addresses' links
+ *  stand). */
 export function createEmailChangeToken(input: {
   token: string
   userId: string
   newEmail: string
   deliveredBy: 'mailer' | 'shown'
+  kind?: 'change' | 'add'
   ttlMs: number
 }): EmailChangeToken {
   const db = getDb()
-  db.prepare(
-    "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND consumed_at IS NULL",
-  ).run(input.userId)
+  const kind = input.kind ?? 'change'
+  if (kind === 'change') {
+    db.prepare(
+      "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'change' AND consumed_at IS NULL",
+    ).run(input.userId)
+  } else {
+    db.prepare(
+      "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'add' AND new_email = ? AND consumed_at IS NULL",
+    ).run(input.userId, input.newEmail.trim().toLowerCase())
+  }
   const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
   db.prepare(
-    'INSERT INTO email_change_tokens (token, user_id, new_email, delivered_by, expires_at) VALUES (?, ?, ?, ?, ?)',
-  ).run(input.token, input.userId, input.newEmail.trim().toLowerCase(), input.deliveredBy, expiresAt)
+    'INSERT INTO email_change_tokens (token, user_id, new_email, delivered_by, kind, expires_at) VALUES (?, ?, ?, ?, ?, ?)',
+  ).run(input.token, input.userId, input.newEmail.trim().toLowerCase(), input.deliveredBy, kind, expiresAt)
   return getEmailChangeToken(input.token)!
 }
 
@@ -444,22 +509,29 @@ export function getEmailChangeToken(token: string): EmailChangeToken | null {
   return row ? toEmailChangeToken(row) : null
 }
 
-/** The account's pending change (the newest live row), so the console
- *  can show it. */
+/** The account's pending PRIMARY change (the newest live 'change' row),
+ *  so the console can show it. The per-address verifications are the
+ *  account_emails rows' own state (verified_at NULL = waiting), never a
+ *  pending read here. */
 export function getPendingEmailChange(userId: string): EmailChangeToken | null {
   const row = getDb().prepare(
     `SELECT * FROM email_change_tokens
-     WHERE user_id = ? AND consumed_at IS NULL AND expires_at > datetime('now')
+     WHERE user_id = ? AND kind = 'change' AND consumed_at IS NULL AND expires_at > datetime('now')
      ORDER BY created_at DESC LIMIT 1`,
   ).get(userId) as Record<string, unknown> | undefined
   return row ? toEmailChangeToken(row) : null
 }
 
 /** Complete the ceremony: consume ATOMICALLY (a presented link works
- *  exactly once, expired or not), judge the expiry, re-check the
- *  address's uniqueness (a conflict burns the token honestly), then move
- *  the account's email. A 'mailer'-delivered token verifies the address;
- *  a shown one applies the change with the address staying unverified. */
+ *  exactly once, expired or not), judge the expiry, then act on the
+ *  kind. 'change' (the pre-01 primary replacement): re-check the
+ *  address's uniqueness across BOTH address tables (a conflict burns the
+ *  token honestly — an additional row anywhere holds the address too,
+ *  this account's included), then move users.email. 'add' (the
+ *  per-address verification): the account_emails row landed unverified
+ *  at the request; the completion stamps it (a row removed meanwhile
+ *  burns the link as 'unknown'). A 'mailer'-delivered token verifies the
+ *  address; a shown one never does. */
 export function completeEmailChange(token: string): CompleteEmailChangeResult {
   const db = getDb()
   const res = db.prepare(
@@ -468,11 +540,123 @@ export function completeEmailChange(token: string): CompleteEmailChangeResult {
   if (res.changes === 0) return { kind: 'unknown' }
   const row = getEmailChangeToken(token)!
   if (new Date(row.expiresAt).getTime() <= Date.now()) return { kind: 'expired' }
+  const verified = row.deliveredBy === 'mailer'
+  if (row.kind === 'add') {
+    const standing = db.prepare('SELECT 1 AS ok FROM account_emails WHERE user_id = ? AND email = ?').get(row.userId, row.newEmail)
+    if (!standing) return { kind: 'unknown' }
+    if (verified) markAccountEmailVerified(row.userId, row.newEmail)
+    return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
+  }
   const taken = db.prepare('SELECT id FROM users WHERE email = ?').get(row.newEmail) as { id: string } | undefined
   if (taken) return { kind: 'conflict' }
-  const verified = row.deliveredBy === 'mailer'
+  const takenAdditional = db.prepare('SELECT user_id FROM account_emails WHERE email = ?').get(row.newEmail) as { user_id: string } | undefined
+  if (takenAdditional) return { kind: 'conflict' }
   db.prepare(
     `UPDATE users SET email = ?, email_verified_at = ${verified ? "datetime('now')" : 'NULL'} WHERE id = ?`,
   ).run(row.newEmail, row.userId)
   return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
 }
+
+// ── multiple emails per account (TODO.identity-features/01) ──────────
+
+function toAccountEmail(row: Record<string, unknown>, isPrimary: boolean): AccountEmail {
+  return {
+    userId: row.user_id as string,
+    email: row.email as string,
+    verifiedAt: (row.verified_at as string | null) ?? null,
+    isPrimary,
+    addedBy: (row.added_by as string | null) ?? null,
+    createdAt: row.created_at as string,
+  }
+}
+
+/** The account's addresses: the PRIMARY first (the users row's email +
+ *  its verification stamp), then the additional account_emails rows
+ *  (oldest first). */
+export function listAccountEmails(userId: string): AccountEmail[] {
+  const db = getDb()
+  const primary = db.prepare(
+    'SELECT id AS user_id, email, email_verified_at AS verified_at, created_at FROM users WHERE id = ?',
+  ).get(userId) as Record<string, unknown> | undefined
+  const rows = db.prepare(
+    'SELECT * FROM account_emails WHERE user_id = ? ORDER BY created_at, email',
+  ).all(userId) as Array<Record<string, unknown>>
+  const out: AccountEmail[] = []
+  if (primary) out.push(toAccountEmail(primary, true))
+  out.push(...rows.map(r => toAccountEmail(r, false)))
+  return out
+}
+
+/** Resolve the account by ANY of its addresses (normalized): the primary
+ *  always names it (and the primary owner always wins — the
+ *  deterministic rule); an additional ONLY when verified. */
+export function findUserByAnyEmail(email: string): AuthUserPayload | null {
+  const db = getDb()
+  const normalized = email.trim().toLowerCase()
+  const primary = db.prepare('SELECT * FROM users WHERE email = ?').get(normalized) as Record<string, unknown> | undefined
+  if (primary) return accountPayload(primary)
+  const owner = db.prepare(
+    'SELECT user_id FROM account_emails WHERE email = ? AND verified_at IS NOT NULL',
+  ).get(normalized) as { user_id: string } | undefined
+  if (!owner) return null
+  const user = db.prepare('SELECT * FROM users WHERE id = ?').get(owner.user_id) as Record<string, unknown> | undefined
+  return user ? accountPayload(user) : null
+}
+
+/** Add an ADDITIONAL address (normalized lowercase; the row lands
+ *  UNVERIFIED). The account's own existing row answers 'present' (the
+ *  idempotent re-add); any other hold of the address — a primary
+ *  anywhere (this account's included) or another account's additional —
+ *  answers 'conflict'. The unique index is the race backstop. */
+export function addAccountEmail(userId: string, email: string, addedBy?: string | null): AddAccountEmailResult {
+  const db = getDb()
+  const normalized = email.trim().toLowerCase()
+  const takenPrimary = db.prepare('SELECT id FROM users WHERE email = ?').get(normalized)
+  if (takenPrimary) return 'conflict'
+  const existing = db.prepare('SELECT user_id FROM account_emails WHERE email = ?').get(normalized) as { user_id: string } | undefined
+  if (existing) return existing.user_id === userId ? 'present' : 'conflict'
+  try {
+    db.prepare('INSERT INTO account_emails (user_id, email, added_by) VALUES (?, ?, ?)').run(userId, normalized, addedBy ?? null)
+  } catch (e) {
+    if (String((e as Error).message).includes('UNIQUE')) return 'conflict'
+    throw e
+  }
+  return 'added'
+}
+
+/** The verification ceremony's stamp on the account's OWN row: the
+ *  guarded UPDATE flips verified_at, once. */
+export function markAccountEmailVerified(userId: string, email: string): boolean {
+  return getDb().prepare(
+    "UPDATE account_emails SET verified_at = datetime('now') WHERE user_id = ? AND email = ? AND verified_at IS NULL",
+  ).run(userId, email.trim().toLowerCase()).changes > 0
+}
+
+/** Promote a VERIFIED additional to primary: the promoted address
+ *  becomes users.email with its verification stamp; the outgoing
+ *  primary takes the row's place in account_emails with ITS stamp (it
+ *  stays a verified additional — sign-in by it keeps working). */
+export function setPrimaryAccountEmail(userId: string, email: string): 'ok' | 'unknown' | 'unverified' {
+  const db = getDb()
+  const normalized = email.trim().toLowerCase()
+  const row = db.prepare('SELECT * FROM account_emails WHERE user_id = ? AND email = ?').get(userId, normalized) as Record<string, unknown> | undefined
+  if (!row) return 'unknown'
+  if (!row.verified_at) return 'unverified'
+  const current = db.prepare('SELECT email, email_verified_at FROM users WHERE id = ?').get(userId) as { email: string; email_verified_at: string | null } | undefined
+  if (!current) return 'unknown'
+  db.prepare('UPDATE users SET email = ?, email_verified_at = ? WHERE id = ?').run(normalized, row.verified_at as string, userId)
+  db.prepare('DELETE FROM account_emails WHERE user_id = ? AND email = ?').run(userId, normalized)
+  db.prepare('INSERT INTO account_emails (user_id, email, verified_at) VALUES (?, ?, ?)').run(userId, current.email, current.email_verified_at)
+  return 'ok'
+}
+
+/** Remove an ADDITIONAL address. The primary refuses honestly
+ *  ('primary' — promote another address first). */
+export function removeAccountEmail(userId: string, email: string): 'ok' | 'primary' | 'unknown' {
+  const db = getDb()
+  const normalized = email.trim().toLowerCase()
+  const current = db.prepare('SELECT email FROM users WHERE id = ?').get(userId) as { email: string } | undefined
+  if (current?.email === normalized) return 'primary'
+  const res = db.prepare('DELETE FROM account_emails WHERE user_id = ? AND email = ?').run(userId, normalized)
+  return res.changes > 0 ? 'ok' : 'unknown'
+}

package/src/store/sqlite/schema.sql

@@ -444,11 +444,15 @@ CREATE INDEX IF NOT EXISTS idx_enrollment_tokens_user ON enrollment_tokens (user
 -- was displayed to the signed-in holder; completing it applies the change
 -- but the address stays unverified, honestly). A fresh request voids the
 -- account's earlier pending rows: only the newest link works.
+-- TODO.identity-features/01: kind names the ceremony — 'change' (the
+-- primary replacement above) or 'add' (the per-address verification of an
+-- account_emails row; completion stamps the row's verified_at).
 CREATE TABLE IF NOT EXISTS email_change_tokens (
   token TEXT PRIMARY KEY,
   user_id TEXT NOT NULL REFERENCES users(id),
   new_email TEXT NOT NULL,
   delivered_by TEXT NOT NULL DEFAULT 'shown',
+  kind TEXT NOT NULL DEFAULT 'change',
   created_at TEXT NOT NULL DEFAULT (datetime('now')),
   expires_at TEXT NOT NULL,
   consumed_at TEXT
@@ -849,3 +853,25 @@ CREATE TABLE IF NOT EXISTS oidc_consent_grants (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_oidc_consent_grants_live
   ON oidc_consent_grants (user_id, client_id, scope) WHERE revoked_at IS NULL;
 CREATE INDEX IF NOT EXISTS idx_oidc_consent_grants_user ON oidc_consent_grants (user_id);
+
+-- ═══════════════════════════════════════════════════════════════════
+-- Multiple emails per account (TODO.identity-features/01): the account
+-- carries a primary + additional addresses. The PRIMARY stays users.email
+-- (the OIDC `email` claim never changes shape); account_emails carries
+-- the ADDITIONAL addresses, one row per (account, address), verified_at
+-- NULL until the per-address ceremony (email_change_tokens kind 'add')
+-- proves the mailbox. The unique index makes an additional address name
+-- at most one account; the store's writes check across BOTH tables, and
+-- the sign-in/recovery resolutions prefer the primary owner
+-- deterministically. The D1 migration set carries the identical end
+-- state (0022_account_emails.sql).
+-- ═══════════════════════════════════════════════════════════════════
+CREATE TABLE IF NOT EXISTS account_emails (
+  user_id TEXT NOT NULL REFERENCES users(id),
+  email TEXT NOT NULL,
+  verified_at TEXT,
+  added_by TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, email)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_account_emails_email ON account_emails (email);

package/src/store/sqlite/store.ts

@@ -144,6 +144,16 @@ function migrateAuthTables(db: Database.Database): void {
   if (!amrTokenCols.some(c => c.name === 'amr')) {
     db.exec('ALTER TABLE oidc_access_tokens ADD COLUMN amr TEXT')
   }
+  // TODO.identity-features/01 (multiple emails per account): the
+  // ceremony token's kind column arrives with migration 0022 — a dev
+  // file predating it grows the column here ('change' — every existing
+  // row is the legacy primary-replacement ceremony). The account_emails
+  // table itself arrives via schema.sql's CREATE IF NOT EXISTS on every
+  // boot.
+  const emailChangeCols = db.prepare('PRAGMA table_info(email_change_tokens)').all() as Array<{ name: string }>
+  if (emailChangeCols.length && !emailChangeCols.some(c => c.name === 'kind')) {
+    db.exec("ALTER TABLE email_change_tokens ADD COLUMN kind TEXT NOT NULL DEFAULT 'change'")
+  }
 }
 
 // AuthUserPayload lives in ./backend (see the re-export above).

package/src/store/sqlite.ts

@@ -143,6 +143,7 @@ import {
   upsertIdentityProvider,
 } from './sqlite/upstream-store'
 import {
+  addAccountEmail,
   completeEmailChange,
   completeEnrollment,
   countSignInMethods,
@@ -155,24 +156,29 @@ import {
   deletePasswordHash,
   deleteSessionById,
   eraseOpAccount,
+  findUserByAnyEmail,
   getEmailChangeToken,
   getEnrollmentToken,
   getOpClientRoles,
   getPasswordLogin,
   getPendingEmailChange,
   lastAccountSignIns,
+  listAccountEmails,
   listAllOpClientRoles,
   listOpClientRoles,
   listOpLiveSessions,
   listUserSessions,
+  markAccountEmailVerified,
+  removeAccountEmail,
   revokeOpUserCredentials,
   setOpClientRoles,
   setPasswordHash,
+  setPrimaryAccountEmail,
   setUserAvatar,
   updateOpAccount,
   updateUserName,
 } from './sqlite/op-accounts-store'
-import { installStore, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EventKeyFilter, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type NotifyDelivery, type NotifyDeliveryStatus, type NotifyEntityMute, type NotifyInboxState, type NotifyPreferences, type NotifyRule, type OAuthInitialAssignment, type OidcAccessToken, type OidcAuthorization, type OidcClient, type OidcClientLaunch, type OidcCode, type OidcConsentGrant, type OidcKeyRow, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PersonalAccessToken, type PlatformEvent, type ServerStore, type SessionView, type SsoSignInState, type UserAdminRow, type AdvanceCounterResult, type MfaPending, type RecoveryCodeState, type TotpSecret, type WebauthnChallenge, type WebauthnCredential } from '../store'
+import { installStore, type AccountEmail, type AddAccountEmailResult, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EventKeyFilter, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type NotifyDelivery, type NotifyDeliveryStatus, type NotifyEntityMute, type NotifyInboxState, type NotifyPreferences, type NotifyRule, type OAuthInitialAssignment, type OidcAccessToken, type OidcAuthorization, type OidcClient, type OidcClientLaunch, type OidcCode, type OidcConsentGrant, type OidcKeyRow, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PersonalAccessToken, type PlatformEvent, type ServerStore, type SessionView, type SsoSignInState, type UserAdminRow, type AdvanceCounterResult, type MfaPending, type RecoveryCodeState, type TotpSecret, type WebauthnChallenge, type WebauthnCredential } from '../store'
 import {
   advanceWebauthnCounter,
   consumeMfaPending,
@@ -781,6 +787,7 @@ export function createSqliteServerStore(): ServerStore {
       userId: string
       newEmail: string
       deliveredBy: 'mailer' | 'shown'
+      kind?: 'change' | 'add'
       ttlMs: number
     }): Promise<EmailChangeToken> {
       return createEmailChangeToken(input)
@@ -795,6 +802,26 @@ export function createSqliteServerStore(): ServerStore {
       return completeEmailChange(token)
     },
 
+    // ── multiple emails per account (TODO.identity-features/01) ──
+    async listAccountEmails(userId: string): Promise<AccountEmail[]> {
+      return listAccountEmails(userId)
+    },
+    async findUserByAnyEmail(email: string): Promise<AuthUserPayload | null> {
+      return findUserByAnyEmail(email)
+    },
+    async addAccountEmail(userId: string, email: string, addedBy?: string | null): Promise<AddAccountEmailResult> {
+      return addAccountEmail(userId, email, addedBy)
+    },
+    async markAccountEmailVerified(userId: string, email: string): Promise<boolean> {
+      return markAccountEmailVerified(userId, email)
+    },
+    async setPrimaryAccountEmail(userId: string, email: string): Promise<'ok' | 'unknown' | 'unverified'> {
+      return setPrimaryAccountEmail(userId, email)
+    },
+    async removeAccountEmail(userId: string, email: string): Promise<'ok' | 'primary' | 'unknown'> {
+      return removeAccountEmail(userId, email)
+    },
+
     // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03) ──
     async createWebauthnChallenge(input: {
       challenge: string

package/src/store.ts

@@ -590,7 +590,10 @@ export interface OpClientRoleAssignment {
  *  account's pending ceremony state). TODO.identity-features/08 adds
  *  `personalAccessTokens`: the developer-token rows (a dead account's
  *  tokens die with it). TODO.identity-features/12 adds `consentGrants`:
- *  the remembered consent rows (a dead account's grants die with it). */
+ *  the remembered consent rows (a dead account's grants die with it).
+ *  TODO.identity-features/01 adds `emails`: the additional-address rows
+ *  (every address of the account goes — the tombstone's primary is the
+ *  anonymized users.email). */
 export interface OpAccountErasure {
   sessions: number
   accessTokens: number
@@ -603,21 +606,28 @@ export interface OpAccountErasure {
   factors: number
   personalAccessTokens: number
   consentGrants: number
+  emails: number
 }
 
 // ── the account console (TODO.identity/06) ───────────────────────────
 
-/** The verify-new-email ceremony's row (the enrollment link's doctrine:
+/** The verify-an-address ceremony's row (the enrollment link's doctrine:
  *  a 256-bit random token backed by the D1 row; one-time, 24 h).
  *  deliveredBy records the channel the link traveled: 'mailer' (sent to
  *  the NEW address; completing verifies it) or 'shown' (no mailer
  *  configured, the link was displayed to the signed-in holder; the change
- *  applies but the address stays unverified, honestly). */
+ *  applies but the address stays unverified, honestly).
+ *  TODO.identity-features/01: kind names the ceremony — 'change' (the
+ *  primary-address replacement; completion moves users.email) or 'add'
+ *  (the per-address verification of an account_emails row; completion
+ *  stamps the row's verified_at). Rows predating the kind column read
+ *  'change' (the migration's default). */
 export interface EmailChangeToken {
   token: string
   userId: string
   newEmail: string
   deliveredBy: 'mailer' | 'shown'
+  kind: 'change' | 'add'
   createdAt: string
   expiresAt: string
   consumedAt: string | null
@@ -635,6 +645,38 @@ export type CompleteEmailChangeResult =
    *  (the token is burned; the change must start over). */
   | { kind: 'conflict' }
 
+// ── multiple emails per account (TODO.identity-features/01) ──────────
+
+/** One of the account's addresses. The PRIMARY is the users row's email
+ *  (isPrimary — the OIDC `email` claim's source, never an
+ *  account_emails row); the ADDITIONAL addresses are the account_emails
+ *  rows. verifiedAt NULL = the mailbox is unproven: an unverified
+ *  additional NEVER names the account (not to sign-in, not to recovery,
+ *  never a notification's target). */
+export interface AccountEmail {
+  userId: string
+  email: string
+  verifiedAt: string | null
+  isPrimary: boolean
+  /** Who added the row (the holder's session email, an admin's); NULL on
+   *  the primary line (the users row carries no such provenance). */
+  addedBy: string | null
+  createdAt: string
+}
+
+/** The additional-address add's honest outcomes. */
+export type AddAccountEmailResult =
+  /** The row landed (unverified — the verification ceremony follows). */
+  | 'added'
+  /** The account ALREADY carries the address as an additional (the add
+   *  is an idempotent no-op; the route re-sends the verification for an
+   *  unverified row). */
+  | 'present'
+  /** Another account holds the address (as its primary or an
+   *  additional), or it IS this account's primary — an address names at
+   *  most one account across the estate. */
+  | 'conflict'
+
 // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03)
 
 /** A registered passkey (the webauthn_credentials row). publicKeyCose is
@@ -1581,7 +1623,13 @@ export interface ServerStore {
   /** The password sign-in's lookup: the credential + the account's
    *  active flag by email (normalized). Null = no such credential — the
    *  route still runs one full-cost verify (the timing-shape rule,
-   *  auth/passwords.ts). The hash never leaves the server. */
+   *  auth/passwords.ts). The hash never leaves the server.
+   *  TODO.identity-features/01: the address resolves by ANY of the
+   *  account's VERIFIED addresses — the primary (users.email) or a
+   *  proven account_emails row. An unverified additional never resolves
+   *  (the mailbox is unproven), and a primary owner always wins over an
+   *  additional row (the deterministic rule — a stray duplicate shadows,
+   *  never ambiguates). */
   getPasswordLogin(email: string): Promise<{ userId: string; hash: string; active: boolean } | null>
   /** Set/replace the account's password credential (enrollment
    *  completion, the account page's change). */
@@ -1680,15 +1728,20 @@ export interface ServerStore {
    *  "sign out everywhere else" action + the password change's
    *  best-practice revocation). Answers the revoked count. */
   deleteOtherSessions(userId: string, keepToken: string): Promise<number>
-  /** Mint the verify-new-email ceremony's token. A fresh request VOIDS
-   *  the account's earlier pending rows (only the newest link works).
-   *  deliveredBy is stamped at request time and decides whether
-   *  completion may verify the address. */
+  /** Mint the verify-an-address ceremony's token. The void rule keeps
+   *  one live link per ceremony target: a 'change' request VOIDS the
+   *  account's earlier pending 'change' rows (only the newest change
+   *  link works — the pre-01 doctrine); an 'add' request voids the
+   *  account's earlier pending 'add' rows FOR THE SAME address (other
+   *  addresses' links stand). deliveredBy is stamped at request time and
+   *  decides whether completion may verify the address. kind defaults
+   *  'change'. */
   createEmailChangeToken(input: {
     token: string
     userId: string
     newEmail: string
     deliveredBy: 'mailer' | 'shown'
+    kind?: 'change' | 'add'
     ttlMs: number
   }): Promise<EmailChangeToken>
   getEmailChangeToken(token: string): Promise<EmailChangeToken | null>
@@ -1696,12 +1749,51 @@ export interface ServerStore {
    *  so the console can show it. */
   getPendingEmailChange(userId: string): Promise<EmailChangeToken | null>
   /** Complete the ceremony: consume the token ATOMICALLY (a presented
-   *  link works exactly once, expired or not), judge the expiry, re-check
-   *  the address's uniqueness (a conflict burns the token honestly), then
-   *  move the account's email. verified = the token traveled by mailer
-   *  (mailbox proven); a shown link never verifies. */
+   *  link works exactly once, expired or not), judge the expiry, then
+   *  act on the kind: 'change' re-checks the address's uniqueness across
+   *  BOTH address tables (a conflict burns the token honestly) and moves
+   *  the account's primary (users.email); 'add' stamps the
+   *  account_emails row's verified_at (a row removed between request and
+   *  completion answers 'unknown'). verified = the token traveled by
+   *  mailer (mailbox proven); a shown link never verifies. */
   completeEmailChange(token: string): Promise<CompleteEmailChangeResult>
 
+  // ── multiple emails per account (TODO.identity-features/01) ──
+  /** The account's addresses, the PRIMARY first (the users row's email +
+   *  its verification stamp), then the additional account_emails rows
+   *  (oldest first). The console's emails section and the security-mail
+   *  fan-out read this. */
+  listAccountEmails(userId: string): Promise<AccountEmail[]>
+  /** Resolve the account by ANY of its addresses (normalized): the
+   *  primary always names it; an additional ONLY when verified (an
+   *  unproven address never names the account — not to sign-in, not to
+   *  recovery). The primary owner wins over an additional row (the
+   *  deterministic rule). */
+  findUserByAnyEmail(email: string): Promise<AuthUserPayload | null>
+  /** Add an ADDITIONAL address (normalized lowercase; the row lands
+   *  UNVERIFIED — the verify-an-address ceremony's kind 'add' token
+   *  proves the mailbox). The tagged result names the outcome; the
+   *  unique index + the cross-table check make an address name at most
+   *  one account. */
+  addAccountEmail(userId: string, email: string, addedBy?: string | null): Promise<AddAccountEmailResult>
+  /** The verification ceremony's stamp on the account's OWN additional
+   *  row (the kind 'add' completion): verified_at flips, once (the
+   *  guarded update). Answers false when no such row stands. */
+  markAccountEmailVerified(userId: string, email: string): Promise<boolean>
+  /** Promote a VERIFIED additional to primary: the promoted address
+   *  becomes users.email (its verification stamp travels, so the claims
+   *  stay verified), and the previous primary takes the row's place in
+   *  account_emails with ITS stamp (it stays a verified additional —
+   *  sign-in by it keeps working). 'unknown' = no such additional row;
+   *  'unverified' = the row stands unproven (a primary is always
+   *  proven). */
+  setPrimaryAccountEmail(userId: string, email: string): Promise<'ok' | 'unknown' | 'unverified'>
+  /** Remove an ADDITIONAL address. 'primary' = the address IS the
+   *  account's primary (promote another first — the primary is never
+   *  removed from under the holder); 'unknown' = no such additional
+   *  row. */
+  removeAccountEmail(userId: string, email: string): Promise<'ok' | 'primary' | 'unknown'>
+
   // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03) ──
   /** The one-time WebAuthn ceremony challenge. The challenge value IS the
    *  key (the clientDataJSON binds it); expires_at = now + ttlMs. */