@oimlsmart/platform-server 0.1.7 → 0.1.9

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. */
@@ -1873,6 +1965,11 @@ export interface ServerStore {
   listOrgMemberships(userId: string): Promise<OrgMembership[]>
   /** One org's memberships (the per-org view), every state. */
   listOrgMembers(orgId: string): Promise<OrgMembership[]>
+  /** EVERY membership across organizations, every state (the admin
+   *  registry's org list groups it in memory — one read, never a
+   *  per-org loop of listOrgMembers). Org- then creation-ordered, so a
+   *  caller's group-by-org keeps listOrgMembers' per-org ordering. */
+  listAllOrgMemberships(): Promise<OrgMembership[]>
   getOrgMembership(userId: string, orgId: string): Promise<OrgMembership | null>
   /** Create the membership — the org's admin inviting an EXISTING
    *  account (state 'invited': the holder accepts from the account