@oimlsmart/platform-server 0.2.3 → 0.2.5

package/migrations/0024_oidc_code_auth_time.sql

@@ -0,0 +1,10 @@
+-- Migration 0024 — the SSO wave-A tail (TODO.identity-sso: RP-initiated
+-- logout + prompt=login): the one-time code carries the consenting
+-- session's authentication instant (sessions.created_at, verbatim), so
+-- the token endpoint emits the ID token's auth_time — the forced
+-- re-authentication's freshness proof the RP verifies. NULL = no
+-- instant recorded (a code minted before this wave).
+-- schema.sql carries the same end state for fresh databases —
+-- src/__tests__/d1-store.test.ts pins the UNION of every migration to
+-- schema.sql's CREATE set.
+ALTER TABLE oidc_codes ADD COLUMN auth_time TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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

@@ -640,6 +640,11 @@ export class D1ServerStore implements ServerStore {
       if (!codeCols.results.some(c => c.name === 'amr')) {
         await this.db.prepare('ALTER TABLE oidc_codes ADD COLUMN amr TEXT').run()
       }
+      // TODO.identity-sso (the wave-A tail): the code carries the
+      // consenting session's authentication instant (migration 0024).
+      if (!codeCols.results.some(c => c.name === 'auth_time')) {
+        await this.db.prepare('ALTER TABLE oidc_codes ADD COLUMN auth_time TEXT').run()
+      }
       const tokenCols = await this.db.prepare('PRAGMA table_info(oidc_access_tokens)').all<{ name: string }>()
       if (!tokenCols.results.some(c => c.name === 'amr')) {
         await this.db.prepare('ALTER TABLE oidc_access_tokens ADD COLUMN amr TEXT').run()
@@ -862,11 +867,11 @@ export class D1ServerStore implements ServerStore {
     // reassignment takes effect on the next request; deactivation ends
     // the session at once.
     const session = await this.stmt(
-      `SELECT s.user_id, s.active_org, s.amr, u.email, u.name, u.role, u.roles, u.org_id, u.avatar_url, u.provider, u.email_verified_at
+      `SELECT s.user_id, s.active_org, s.amr, s.created_at, u.email, u.name, u.role, u.roles, u.org_id, u.avatar_url, u.provider, u.email_verified_at
        FROM sessions s JOIN users u ON s.user_id = u.id
        WHERE s.token = ? AND s.expires_at > datetime('now') AND u.active = 1`,
       token,
-    ).first<{ user_id: string; active_org: string | null; amr: string | null; email: string; name: string; role: string; roles: string | null; org_id: string | null; avatar_url: string | null; provider: string; email_verified_at: string | null }>()
+    ).first<{ user_id: string; active_org: string | null; amr: string | null; created_at: string; email: string; name: string; role: string; roles: string | null; org_id: string | null; avatar_url: string | null; provider: string; email_verified_at: string | null }>()
     if (!session) return null
     const amr = parseRoles(session.amr)
     const payload: AuthUserPayload = {
@@ -880,6 +885,9 @@ export class D1ServerStore implements ServerStore {
       provider: session.provider,
       emailVerifiedAt: session.email_verified_at ?? null,
       ...(amr?.length ? { amr } : {}),
+      // TODO.identity-sso (the wave-A tail): the authentication instant —
+      // the ID token's auth_time derives from it (the consumer converts).
+      sessionCreatedAt: session.created_at,
     }
     // TODO.identity/11: the active-org context (the membership model) —
     // the payload's org/roles follow the session's stamped context. The
@@ -1295,16 +1303,20 @@ export class D1ServerStore implements ServerStore {
      *  (stored as JSON; the token endpoint emits it as the ID token's
      *  amr). Absent = no provenance recorded. */
     amr?: string[] | null
+    /** TODO.identity-sso (the wave-A tail): the consenting session's
+     *  authentication instant (verbatim; absent = none recorded) — the
+     *  token endpoint emits it as the ID token's auth_time. */
+    authTime?: string | null
     ttlMs: number
   }): Promise<void> {
     await this.ensureMembershipSupport()
     const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
     await this.ensureOidcColumns()
     await this.stmt(
-      `INSERT INTO oidc_codes (code, client_id, redirect_uri, scope, nonce, code_challenge, user_id, context_org, amr, expires_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO oidc_codes (code, client_id, redirect_uri, scope, nonce, code_challenge, user_id, context_org, amr, auth_time, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       input.code, input.clientId, input.redirectUri, input.scope, input.nonce, input.codeChallenge, input.userId, input.contextOrg ?? null,
-      input.amr?.length ? JSON.stringify(input.amr) : null, expiresAt,
+      input.amr?.length ? JSON.stringify(input.amr) : null, input.authTime ?? null, expiresAt,
     ).run()
   }
 
@@ -1330,6 +1342,7 @@ export class D1ServerStore implements ServerStore {
       userId: row.user_id as string,
       contextOrg: (row.context_org as string | null) ?? null,
       amr: parseRoles((row.amr as string | null) ?? null) ?? null,
+      authTime: (row.auth_time as string | null) ?? null,
       expiresAt: row.expires_at as string,
     }
   }
@@ -1996,8 +2009,9 @@ export class D1ServerStore implements ServerStore {
       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',
+      // store over a pre-0022 database) read as the legacy ceremony; the
+      // 0.2.4 'verify' kind reads by its name.
+      kind: row.kind === 'add' ? 'add' : row.kind === 'verify' ? 'verify' : 'change',
       createdAt: row.created_at as string,
       expiresAt: row.expires_at as string,
       consumedAt: (row.consumed_at as string | null) ?? null,
@@ -2009,13 +2023,15 @@ export class D1ServerStore implements ServerStore {
    *  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). */
+   *  stand); a 'verify' request voids the account's earlier pending
+   *  'verify' rows (the target is the current primary — one per
+   *  account, the change doctrine's scoping). */
   async createEmailChangeToken(input: {
     token: string
     userId: string
     newEmail: string
     deliveredBy: 'mailer' | 'shown'
-    kind?: 'change' | 'add'
+    kind?: 'change' | 'add' | 'verify'
     ttlMs: number
   }): Promise<EmailChangeToken> {
     await this.ensureAccountEmailSupport()
@@ -2025,6 +2041,11 @@ export class D1ServerStore implements ServerStore {
         "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'change' AND consumed_at IS NULL",
         input.userId,
       ).run()
+    } else if (kind === 'verify') {
+      await this.stmt(
+        "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'verify' 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",
@@ -2067,8 +2088,13 @@ export class D1ServerStore implements ServerStore {
    *  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. */
+   *  burns the link as 'unknown'). 'verify' (the 0.2.4 kind): the
+   *  re-verification of the address the account ALREADY holds as its
+   *  primary — the completion stamps users.email_verified_at when the
+   *  token's new_email IS STILL the primary (a primary moved meanwhile
+   *  burns the link as 'unknown', the vanished-target doctrine).
+   *  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(
@@ -2084,6 +2110,15 @@ export class D1ServerStore implements ServerStore {
       if (verified) await this.markAccountEmailVerified(row.userId, row.newEmail)
       return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
     }
+    if (row.kind === 'verify') {
+      // The address never changes hands in this ceremony — 'conflict'
+      // does not exist here; the honest burns are the moved primary and
+      // the gone account, both read from the users row.
+      const current = await this.stmt('SELECT email FROM users WHERE id = ?', row.userId).first<{ email: string }>()
+      if (!current || current.email !== row.newEmail) return { kind: 'unknown' }
+      if (verified) await this.stmt("UPDATE users SET email_verified_at = datetime('now') WHERE id = ?", row.userId).run()
+      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 takenAdditional = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', row.newEmail).first<{ user_id: string }>()

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

@@ -469,8 +469,8 @@ function toEmailChangeToken(row: Record<string, unknown>): EmailChangeToken {
     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',
+    // the legacy ceremony; the 0.2.4 'verify' kind reads by its name.
+    kind: row.kind === 'add' ? 'add' : row.kind === 'verify' ? 'verify' : 'change',
     createdAt: row.created_at as string,
     expiresAt: row.expires_at as string,
     consumedAt: (row.consumed_at as string | null) ?? null,
@@ -482,13 +482,15 @@ function toEmailChangeToken(row: Record<string, unknown>): EmailChangeToken {
  *  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). */
+ *  stand); a 'verify' request voids the account's earlier pending
+ *  'verify' rows (the target is the current primary — one per account,
+ *  the change doctrine's scoping). */
 export function createEmailChangeToken(input: {
   token: string
   userId: string
   newEmail: string
   deliveredBy: 'mailer' | 'shown'
-  kind?: 'change' | 'add'
+  kind?: 'change' | 'add' | 'verify'
   ttlMs: number
 }): EmailChangeToken {
   const db = getDb()
@@ -497,6 +499,10 @@ export function createEmailChangeToken(input: {
     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 if (kind === 'verify') {
+    db.prepare(
+      "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'verify' 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",
@@ -535,8 +541,14 @@ export function getPendingEmailChange(userId: string): EmailChangeToken | null {
  *  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. */
+ *  burns the link as 'unknown'). 'verify' (the 0.2.4 kind): the
+ *  re-verification of the address the account ALREADY holds as its
+ *  primary — the completion stamps users.email_verified_at when the
+ *  token's new_email IS STILL the primary (a primary moved meanwhile —
+ *  a completed 'change', an admin re-address — burns the link as
+ *  'unknown', the vanished-target doctrine; the erasure's token sweep
+ *  burns it earlier). 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(
@@ -552,6 +564,15 @@ export function completeEmailChange(token: string): CompleteEmailChangeResult {
     if (verified) markAccountEmailVerified(row.userId, row.newEmail)
     return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
   }
+  if (row.kind === 'verify') {
+    // The address NEVER changes hands in this ceremony — 'conflict' does
+    // not exist here; the honest burns are the moved primary and the
+    // gone account, both read from the users row.
+    const current = db.prepare('SELECT email FROM users WHERE id = ?').get(row.userId) as { email: string } | undefined
+    if (!current || current.email !== row.newEmail) return { kind: 'unknown' }
+    if (verified) db.prepare("UPDATE users SET email_verified_at = datetime('now') WHERE id = ?").run(row.userId)
+    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 takenAdditional = db.prepare('SELECT user_id FROM account_emails WHERE email = ?').get(row.newEmail) as { user_id: string } | undefined

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

@@ -174,14 +174,18 @@ export function createOidcCode(input: {
    *  (stored as JSON; the token endpoint emits it as the ID token's
    *  amr). Absent = no provenance recorded. */
   amr?: string[] | null
+  /** TODO.identity-sso (the wave-A tail): the consenting session's
+   *  authentication instant (verbatim; absent = none recorded) — the
+   *  token endpoint emits it as the ID token's auth_time. */
+  authTime?: string | null
   ttlMs: number
 }): void {
   const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
   getDb().prepare(`
-    INSERT INTO oidc_codes (code, client_id, redirect_uri, scope, nonce, code_challenge, user_id, context_org, amr, expires_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO oidc_codes (code, client_id, redirect_uri, scope, nonce, code_challenge, user_id, context_org, amr, auth_time, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(input.code, input.clientId, input.redirectUri, input.scope, input.nonce, input.codeChallenge, input.userId,
-    input.contextOrg ?? null, input.amr?.length ? JSON.stringify(input.amr) : null, expiresAt)
+    input.contextOrg ?? null, input.amr?.length ? JSON.stringify(input.amr) : null, input.authTime ?? null, expiresAt)
 }
 
 /** Atomically consume the code: the UPDATE flips consumed_at exactly
@@ -204,6 +208,7 @@ export function consumeOidcCode(code: string): OidcCode | null {
     userId: row.user_id as string,
     contextOrg: (row.context_org as string | null) ?? null,
     amr: parseJsonStringList(row.amr),
+    authTime: (row.auth_time as string | null) ?? null,
     expiresAt: row.expires_at as string,
   }
 }

package/src/store/sqlite/schema.sql

@@ -339,6 +339,10 @@ CREATE TABLE IF NOT EXISTS oidc_codes (
   -- TODO.identity-sso/02+03: the consenting session's amr provenance (a
   -- JSON array; NULL = none recorded), carried into the ID token.
   amr TEXT,
+  -- TODO.identity-sso (the wave-A tail): the consenting session's
+  -- authentication instant (sessions.created_at, verbatim; NULL = none
+  -- recorded), carried into the ID token's auth_time.
+  auth_time TEXT,
   created_at TEXT NOT NULL DEFAULT (datetime('now')),
   expires_at TEXT NOT NULL,
   consumed_at TEXT
@@ -459,6 +463,11 @@ CREATE INDEX IF NOT EXISTS idx_enrollment_tokens_user ON enrollment_tokens (user
 -- 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).
+-- The 0.2.4 kind: 'verify' — the re-verification of the account's CURRENT
+-- primary (new_email carries it as requested; a mailer-delivered
+-- completion stamps users.email_verified_at while the address still IS
+-- the primary). A value, never a column: the kind TEXT carries it, so no
+-- migration rides the 0.2.4 seam change.
 CREATE TABLE IF NOT EXISTS email_change_tokens (
   token TEXT PRIMARY KEY,
   user_id TEXT NOT NULL REFERENCES users(id),

package/src/store/sqlite/store.ts

@@ -323,6 +323,10 @@ export function getSessionUser(token: string): AuthUserPayload | null {
   ).run(token)
   // s.* carries the SESSION's id — the payload's id is the USER's.
   const payload = toAuthPayload({ ...session, id: session.user_id })
+  // TODO.identity-sso (the wave-A tail): the session's authentication
+  // instant (sessions.created_at, verbatim) — the ID token's auth_time
+  // derives from it (the consumer converts to the OIDC NumericDate).
+  payload.sessionCreatedAt = session.created_at as string
   // TODO.identity/11: the active-org context (the membership model) —
   // the payload's org/roles follow the session's stamped context.
   return applySessionOrgContext(session.active_org ?? null, payload)

package/src/store/sqlite.ts

@@ -791,7 +791,7 @@ export function createSqliteServerStore(): ServerStore {
       userId: string
       newEmail: string
       deliveredBy: 'mailer' | 'shown'
-      kind?: 'change' | 'add'
+      kind?: 'change' | 'add' | 'verify'
       ttlMs: number
     }): Promise<EmailChangeToken> {
       return createEmailChangeToken(input)

package/src/store.ts

@@ -65,6 +65,13 @@ export interface AuthUserPayload {
    *  read (getSessionUser) only; ABSENT = no OP-side credential event
    *  recorded (an upstream-provider sign-in, a legacy row). */
   amr?: string[]
+  /** TODO.identity-sso (the wave-A tail): the SESSION's authentication
+   *  instant (sessions.created_at, the column verbatim — the sign-in's
+   *  wall-clock stamp). Projected by the session-backed read
+   *  (getSessionUser) only. The ID token's auth_time derives from it (the
+   *  OIDC NumericDate conversion is the consumer's — the column's storage
+   *  format is the store's own). */
+  sessionCreatedAt?: string
 }
 
 // ── identity federation (TODO.federation/10) ─────────────────────────
@@ -425,6 +432,10 @@ export interface OidcCode {
   /** TODO.identity-sso/02+03: the consenting session's amr provenance
    *  (parsed from the row's JSON; null = none recorded). */
   amr: string[] | null
+  /** TODO.identity-sso (the wave-A tail): the consenting session's
+   *  authentication instant (sessions.created_at, verbatim; null = none
+   *  recorded) — the token endpoint emits it as the ID token's auth_time. */
+  authTime: string | null
   expiresAt: string
 }
 
@@ -637,13 +648,19 @@ export interface OpAccountErasure {
  *  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). */
+ *  'change' (the migration's default).
+ *  The 0.2.4 kind: 'verify' — the re-verification of the address the
+ *  account ALREADY holds as its primary (the invited-not-yet-set-up and
+ *  the admin-re-addressed postures, whose primary never went through a
+ *  mailbox proof). new_email carries the primary AS REQUESTED;
+ *  completion stamps users.email_verified_at when the address is STILL
+ *  the account's primary and the link traveled by mailer. */
 export interface EmailChangeToken {
   token: string
   userId: string
   newEmail: string
   deliveredBy: 'mailer' | 'shown'
-  kind: 'change' | 'add'
+  kind: 'change' | 'add' | 'verify'
   createdAt: string
   expiresAt: string
   consumedAt: string | null
@@ -653,7 +670,9 @@ export interface EmailChangeToken {
 export type CompleteEmailChangeResult =
   | { kind: 'ok'; userId: string; newEmail: string; verified: boolean }
   /** Never existed or already consumed (indistinguishable, the
-   *  enrollment rule). */
+   *  enrollment rule) — or the ceremony's target vanished between
+   *  request and completion: the 'add' row removed, the 'verify'
+   *  primary moved (the link burns the same, honestly). */
   | { kind: 'unknown' }
   /** Past the TTL: burned on presentation, never redeemable later. */
   | { kind: 'expired' }
@@ -1572,6 +1591,11 @@ export interface ServerStore {
      *  (stored as JSON; the token endpoint emits it as the ID token's
      *  amr). Absent = no provenance recorded. */
     amr?: string[] | null
+    /** TODO.identity-sso (the wave-A tail): the consenting session's
+     *  authentication instant (sessions.created_at, verbatim; absent =
+     *  none recorded) — the token endpoint emits it as the ID token's
+     *  auth_time. */
+    authTime?: string | null
     ttlMs: number
   }): Promise<void>
   /** Atomically consume the code: answers the row exactly once (a
@@ -1787,7 +1811,10 @@ export interface ServerStore {
    *  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
+   *  addresses' links stand); a 'verify' request voids the account's
+   *  earlier pending 'verify' rows (the target is the CURRENT primary —
+   *  one per account, the change doctrine's scoping; cross-kind links
+   *  never touch each other). deliveredBy is stamped at request time and
    *  decides whether completion may verify the address. kind defaults
    *  'change'. */
   createEmailChangeToken(input: {
@@ -1795,12 +1822,14 @@ export interface ServerStore {
     userId: string
     newEmail: string
     deliveredBy: 'mailer' | 'shown'
-    kind?: 'change' | 'add'
+    kind?: 'change' | 'add' | 'verify'
     ttlMs: number
   }): Promise<EmailChangeToken>
   getEmailChangeToken(token: string): Promise<EmailChangeToken | null>
   /** The account's pending change (the newest unconsumed, unexpired row),
-   *  so the console can show it. */
+   *  so the console can show it. 'verify' rows have NO pending read: the
+   *  waiting state IS users.email_verified_at NULL (the 'add' doctrine —
+   *  the account_emails rows carry their own). */
   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, then
@@ -1808,8 +1837,16 @@ export interface ServerStore {
    *  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. */
+   *  completion answers 'unknown'); 'verify' (the 0.2.4 kind, the
+   *  resend-verification act for the CURRENT primary) stamps
+   *  users.email_verified_at when the token's new_email IS STILL the
+   *  account's primary — a primary moved meanwhile (a completed 'change',
+   *  an admin re-address, the erasure) burns the link as 'unknown', and
+   *  'conflict' never applies (no address changes hands). verified = the
+   *  token traveled by mailer (mailbox proven); a shown link never
+   *  verifies. The answer carries { userId, newEmail, verified } for
+   *  every kind, so the consumer's completion route audits a proven
+   *  'verify' exactly as it audits an 'add' (its account.email_verified). */
   completeEmailChange(token: string): Promise<CompleteEmailChangeResult>
 
   // ── multiple emails per account (TODO.identity-features/01) ──