@ultimat3/auth 1.1.0 → 2.0.0

package/src/adapter.ts

@@ -14,9 +14,23 @@ export interface AuthUser {
   readonly roles: readonly string[];
   /** Direct grants that bypass roles. Rare; used by break-glass accounts. */
   readonly permissions: readonly string[];
+  /**
+   * Capability strings this human may hold, landing on `Actor.scopes` — the field `hasScope()`
+   * reads and `permissions` is not. Without it a user actor's scopes were the hardcoded `[]`, so
+   * a scope-gated human surface (`tenancy:cross`, and every support tool built on one) was
+   * unreachable by any human and could only be reached by minting a `serviceActor`, which throws
+   * the operator's identity away. Empty for almost every account.
+   */
+  readonly scopes: readonly string[];
   /** Base32 TOTP secret, or `null` when MFA is not enrolled. */
   readonly mfaSecret: string | null;
   readonly recoveryCodeHashes: readonly string[];
+  /**
+   * The identifier the IdP knows this person by — SCIM's `externalId`, OIDC's `sub`. Stable
+   * across a rename and across an address change, which is what a provisioning PUT/PATCH lands
+   * on and what an email address cannot be. `null` for an account that arrived by password.
+   */
+  readonly externalId: string | null;
   readonly disabledAt: Date | null;
   readonly createdAt: Date;
 }
@@ -27,6 +41,8 @@ export interface CreateUserInput {
   readonly passwordHash: string | null;
   readonly orgId: string | null;
   readonly roles: readonly string[];
+  readonly scopes?: readonly string[] | undefined;
+  readonly externalId?: string | null | undefined;
   readonly createdAt: Date;
 }
 
@@ -37,6 +53,16 @@ export interface UserPatch {
   readonly recoveryCodeHashes?: readonly string[] | undefined;
   readonly disabledAt?: Date | null | undefined;
   readonly roles?: readonly string[] | undefined;
+  readonly permissions?: readonly string[] | undefined;
+  readonly scopes?: readonly string[] | undefined;
+  readonly orgId?: string | null | undefined;
+  readonly externalId?: string | null | undefined;
+}
+
+/** What `listUsersByOrg` filters on. Absent means every member of the org. */
+export interface UserQuery {
+  readonly role?: string | undefined;
+  readonly includeDisabled?: boolean | undefined;
 }
 
 export interface UserStore {
@@ -44,6 +70,15 @@ export interface UserStore {
   findUserById(id: string): Promise<AuthUser | null>;
   createUser(input: CreateUserInput): Promise<AuthUser>;
   updateUser(id: string, patch: UserPatch): Promise<AuthUser | null>;
+  /**
+   * Optional so an adapter written against 1.2's seam still compiles; both shipped adapters
+   * implement it, and `directory.ts` answers `X_NOT_IMPLEMENTED` with the method name when one
+   * does not. The alternative was a required member, which is a breaking change to every
+   * third-party `AuthAdapter` for a capability most of them will never be asked for.
+   */
+  findUserByExternalId?(externalId: string): Promise<AuthUser | null>;
+  /** Enumeration, which nothing in the seam could do — a quarterly access review needs it. */
+  listUsersByOrg?(orgId: string, query?: UserQuery): Promise<readonly AuthUser[]>;
 }
 
 export interface AuthSession {
@@ -77,6 +112,20 @@ export interface SessionStore {
   /** Returns how many were killed — the "sign out everywhere else" number shown to the user. */
   deleteOtherSessions(userId: string, keepSessionId: string): Promise<number>;
   listSessions(userId: string): Promise<readonly AuthSession[]>;
+  /**
+   * Every session this user holds, including the caller's own. `deleteOtherSessions` cannot
+   * express it — there is no session id to keep — and a password change or a disable has to.
+   *
+   * Optional for the reason `findUserByExternalId` is: adding a required member to a shipped
+   * seam breaks every third-party adapter. `revocation.ts` refuses with `X_NOT_IMPLEMENTED` and
+   * names the method when an adapter has not got it.
+   */
+  deleteSessionsForUser?(userId: string): Promise<number>;
+  /**
+   * Everything issued before an instant. The credential-compromise sweep: rotate the secret,
+   * then kill everything minted under the old one, without enumerating users.
+   */
+  deleteSessionsCreatedBefore?(before: Date): Promise<number>;
 }
 
 export interface AuthAccount {
@@ -112,10 +161,18 @@ export interface VerificationStore {
   /** Upsert on `(purpose, identifier)` — issuing a new token invalidates the previous one. */
   putVerification(record: AuthVerification): Promise<void>;
   /**
-   * Read **and consume** in one atomic step. Single-use is a storage guarantee, not a
-   * caller convention: two concurrent redemptions must not both see an unconsumed row.
+   * Read **and consume** in one atomic step, and only when `tokenHash` is the live row's.
+   * Single-use is a storage guarantee, not a caller convention: two concurrent redemptions must
+   * not both see an unconsumed row. The hash belongs to that same step for the same reason — a
+   * store that consumes first and lets the caller compare afterwards lets an unauthenticated
+   * wrong guess destroy the victim's live token, which is a password-reset denial of service
+   * against any address an attacker can name. A non-match consumes nothing and answers `null`.
    */
-  takeVerification(purpose: string, identifier: string): Promise<AuthVerification | null>;
+  takeVerification(
+    purpose: string,
+    identifier: string,
+    tokenHash: string,
+  ): Promise<AuthVerification | null>;
 }
 
 export interface AuthApiKeyRecord {
@@ -152,6 +209,14 @@ export interface AuthAdapter
     AccountStore,
     VerificationStore,
     ApiKeyStore {
-  /** Shown by `x auth doctor --json` so the driver in use is never a guess. */
+  /** Reported by `Auth.adapter.name` so the driver in use is never a guess. */
   readonly name: string;
+  /**
+   * Every session held by every member of one org. It spans two tables — `x_sessions` carries no
+   * `org_id` and deliberately does not gain one, because org membership lives on the user and a
+   * denormalised copy goes stale the moment somebody moves org, which makes the 03:00 sweep miss
+   * exactly the sessions it was run for. So it joins through `x_users`, which is why it sits on
+   * the full adapter rather than on `SessionStore`.
+   */
+  deleteSessionsForOrg?(orgId: string): Promise<number>;
 }

package/src/auth.ts

@@ -6,9 +6,10 @@
 import { type Clock, systemClock, uuid } from '@ultimat3/core';
 import { t } from '@ultimat3/schema';
 import type { AuthAdapter, AuthSession, AuthUser } from './adapter';
+import { normaliseEmail } from './email';
 import { mfaRequired, sessionUnknown } from './errors';
 import type { OAuthProviderId } from './oauth';
-import { OAUTH_PROVIDER_IDS } from './oauth';
+import { oauthProviderIds } from './oauth-registry';
 import {
   checkPasswordStrength,
   DEFAULT_PASSWORD_POLICY,
@@ -21,10 +22,13 @@ import {
   type AuthLimiter,
   type AuthRateLimitPolicy,
   accountKey,
+  assertAuthLimiterPolicy,
   createAuthLimiter,
   DEFAULT_AUTH_RATE_LIMIT,
   ipKey,
   loginFailed,
+  orgKey,
+  orgRateLimit,
 } from './rate-limit';
 import {
   createSession,
@@ -35,6 +39,7 @@ import {
   sessionCookie,
   verifySession,
 } from './session';
+import { sha256Hex, timingSafeEqual } from './tokens';
 
 // The projections safe to hand to a client or an MCP tool: no password hash, no TOTP secret,
 // no token hash. The private columns live in `adapter.ts` and never leave the server.
@@ -45,6 +50,8 @@ export const UserSchema = t.object({
   orgId: t.optional(t.uuid),
   roles: t.array(t.string),
   permissions: t.array(t.string),
+  scopes: t.array(t.string),
+  externalId: t.optional(t.string),
   mfaEnrolled: t.boolean,
   createdAt: t.date,
 });
@@ -63,7 +70,9 @@ export const SessionSchema = t.object({
 export const AccountSchema = t.object({
   id: t.uuid,
   userId: t.uuid,
-  provider: t.enum(['github', 'google', 'apple']),
+  // Any registered provider id, not the three built-ins: an app that registers its own OP has
+  // account rows carrying that id, and an enum of three would refuse to parse its own data.
+  provider: t.string,
   providerAccountId: t.string,
   expiresAt: t.optional(t.date),
   createdAt: t.date,
@@ -78,6 +87,25 @@ export const VerificationSchema = t.object({
   createdAt: t.date,
 });
 
+/**
+ * When a provider identity with no linked account is allowed to become an EXISTING local user.
+ *
+ * There are two values and there is deliberately no third. The dangerous one an app would reach
+ * for — "link on whatever address the provider sent" — is not spelled here at all, because a
+ * provider that does not verify addresses turns it into account takeover: register the victim's
+ * address at a sloppy provider, press the button, inherit the account. Unrepresentable beats
+ * explicit, the same way `PkcePair.method` is the literal `'S256'` and never `'plain'`.
+ *
+ * | value | a provider identity becomes an existing user when |
+ * |---|---|
+ * | `'verified-email'` (default) | the provider asserted the address verified AND that user had verified it too |
+ * | `'never'` | never — an address collision is refused and the caller signs in with their own credentials |
+ *
+ * An app that genuinely wants something else composes it: wrap `signInWithOAuth` and resolve the
+ * user yourself. That is the seam, and it keeps the framework from shipping the loose default.
+ */
+export type OAuthLinkPolicy = 'verified-email' | 'never';
+
 export interface AuthMfaPolicy {
   /** Shown in the authenticator app. Usually the product name. */
   readonly issuer: string;
@@ -90,8 +118,22 @@ export interface AuthConfigInput {
   readonly session?: Partial<SessionPolicy> | undefined;
   readonly password?: Partial<PasswordPolicy> | undefined;
   readonly rateLimit?: Partial<AuthRateLimitPolicy> | undefined;
+  /**
+   * Where failed attempts are counted. Omitted means `createAuthLimiter`, which is one process'
+   * worth of state — correct for dev and tests, and `maxAttempts × N` for N replicas. An app that
+   * runs more than one declares `rateLimit.scope: 'shared'` and passes a limiter that says the
+   * same, or `defineAuth` refuses here rather than at 3am on the first spray.
+   */
+  readonly limiter?: AuthLimiter | undefined;
+  /**
+   * Where the per-TENANT counters live. Same rule as `limiter`, and a separate instance because
+   * it enforces a separate `maxAttempts` — `rateLimit.orgMaxAttempts`, which a whole org shares.
+   */
+  readonly orgLimiter?: AuthLimiter | undefined;
   readonly mfa?: Partial<AuthMfaPolicy> | undefined;
   readonly providers?: readonly OAuthProviderId[] | undefined;
+  /** Defaults to `'verified-email'` — both halves proven. See `OAuthLinkPolicy`. */
+  readonly link?: OAuthLinkPolicy | undefined;
 }
 
 export interface Auth {
@@ -101,8 +143,12 @@ export interface Auth {
   readonly password: PasswordPolicy;
   readonly rateLimit: AuthRateLimitPolicy;
   readonly limiter: AuthLimiter;
+  /** The tenant bucket's own policy — `rateLimit` with `orgMaxAttempts` as its `maxAttempts`. */
+  readonly orgRateLimit: AuthRateLimitPolicy;
+  readonly orgLimiter: AuthLimiter;
   readonly mfa: AuthMfaPolicy;
   readonly providers: readonly OAuthProviderId[];
+  readonly link: OAuthLinkPolicy;
 }
 
 export function defineAuth(config: AuthConfigInput): Auth {
@@ -110,15 +156,30 @@ export function defineAuth(config: AuthConfigInput): Auth {
   const session: SessionPolicy = { ...DEFAULT_SESSION_POLICY, ...config.session };
   const password: PasswordPolicy = { ...DEFAULT_PASSWORD_POLICY, ...config.password };
   const rateLimit: AuthRateLimitPolicy = { ...DEFAULT_AUTH_RATE_LIMIT, ...config.rateLimit };
+  const limiter = config.limiter ?? createAuthLimiter(clock, rateLimit);
+  assertAuthLimiterPolicy(rateLimit, limiter);
+  // The tenant bucket is a noisy-neighbour cap, not a credential-guessing allowance, so an app
+  // that declares `scope: 'shared'` for its LOCKOUT is not also required to ship a shared limiter
+  // for this one — per replica it approximates to `orgMaxAttempts × replicas`, which is a
+  // throughput ceiling and discloses nothing. An INJECTED org limiter is still compared, because
+  // then the app has made a claim about what it enforces and `Auth.orgRateLimit` reports it.
+  const orgLimits = orgRateLimit(rateLimit);
+  const orgLimiter = config.orgLimiter ?? createAuthLimiter(clock, orgLimits);
+  if (config.orgLimiter !== undefined) assertAuthLimiterPolicy(orgLimits, config.orgLimiter);
   return Object.freeze({
     adapter: config.adapter,
     clock,
     sessions: { store: config.adapter, policy: session, clock },
     password,
     rateLimit,
-    limiter: createAuthLimiter(clock, rateLimit),
+    limiter,
+    // What the limiter in use actually enforces, not the derivation — the two differ in `scope`
+    // exactly when the app declared 'shared' and left this limiter to the default.
+    orgRateLimit: orgLimiter.policy,
+    orgLimiter,
     mfa: { issuer: config.mfa?.issuer ?? 'Ultimate', required: config.mfa?.required ?? false },
-    providers: config.providers ?? OAUTH_PROVIDER_IDS,
+    providers: config.providers ?? oauthProviderIds(),
+    link: config.link ?? 'verified-email',
   });
 }
 
@@ -134,7 +195,7 @@ export async function register(auth: Auth, input: RegisterInput): Promise<AuthUs
   checkPasswordStrength(input.password, { policy: auth.password });
   return await auth.adapter.createUser({
     id: uuid(auth.clock),
-    email: input.email.trim().toLowerCase(),
+    email: normaliseEmail(input.email),
     passwordHash: await hashPassword(input.password, auth.password.params),
     orgId: input.orgId ?? null,
     roles: input.roles ?? [],
@@ -165,10 +226,16 @@ export interface LoginResult {
 export async function login(auth: Auth, input: LoginInput): Promise<LoginResult> {
   const account = accountKey(input.email);
   const ip = input.ip ?? null;
-  auth.limiter.assertAllowed(account);
-  if (ip !== null) auth.limiter.assertAllowed(ipKey(ip));
+  await auth.limiter.assertAllowed(account);
+  if (ip !== null) await auth.limiter.assertAllowed(ipKey(ip));
+
+  const user = await auth.adapter.findUserByEmail(normaliseEmail(input.email));
+  // The tenant bucket can only be consulted once the address resolves to an org, which is still
+  // before the KDF runs — the expensive half of this function — so it costs one map lookup and
+  // caps a spray that per-IP and per-account buckets both let through.
+  const org = user?.orgId ?? null;
+  if (org !== null) await auth.orgLimiter.assertAllowed(orgKey(org));
 
-  const user = await auth.adapter.findUserByEmail(input.email.trim().toLowerCase());
   const usable = user !== null && user.disabledAt === null;
   const verification = await verifyPassword({
     hash: usable ? user.passwordHash : null,
@@ -177,13 +244,17 @@ export async function login(auth: Auth, input: LoginInput): Promise<LoginResult>
   });
 
   if (!verification.ok || user === null) {
-    auth.limiter.recordFailure(account);
-    if (ip !== null) auth.limiter.recordFailure(ipKey(ip));
+    await auth.limiter.recordFailure(account);
+    if (ip !== null) await auth.limiter.recordFailure(ipKey(ip));
+    if (org !== null) await auth.orgLimiter.recordFailure(orgKey(org));
     throw loginFailed();
   }
 
-  auth.limiter.recordSuccess(account);
-  if (ip !== null) auth.limiter.recordSuccess(ipKey(ip));
+  await auth.limiter.recordSuccess(account);
+  if (ip !== null) await auth.limiter.recordSuccess(ipKey(ip));
+  // No `recordSuccess` on the tenant bucket, and that asymmetry is the point: one member signing
+  // in successfully must not clear the count a broken integration is running up beside them, or
+  // the tenant cap is cleared by exactly the traffic that proves the tenant is still in use.
 
   // Parameters were raised since this hash was written: upgrade it now, while we hold the
   // plaintext. This is the only moment it is possible without asking the user for anything.
@@ -193,8 +264,10 @@ export async function login(auth: Auth, input: LoginInput): Promise<LoginResult>
     });
   }
 
-  // Password proven, second factor not. The client finishes at POST /auth/mfa/verify, which is
-  // what mints the session — no half-authenticated session is written here.
+  // Password proven, second factor not. No half-authenticated session is written here and nothing
+  // is persisted to correlate the two legs — finishing MFA is the app's, and `X_MFA_REQUIRED`'s
+  // `fix:` is the instruction. The framework's own second leg is blocked on a sealed pending-MFA
+  // credential; the constraint is written down in `packages/auth/CLAUDE.md`.
   if (user.mfaSecret !== null) throw mfaRequired(user.id);
 
   const issued = await createSession(auth.sessions, {
@@ -226,8 +299,17 @@ export async function authenticate(auth: Auth, token: string | null): Promise<Po
   return resolveActor({ kind: 'user', user, session });
 }
 
+/**
+ * The SECRET half is checked before the row is deleted, exactly as `verifySession` checks it. The
+ * id half is not a credential — it is in a device list, in a log line and in an audit row — so
+ * deleting on it alone made "sign this person out" an unauthenticated write for anyone who had
+ * ever seen one. Constant-time, and `false` for every failure, so it stays a poor oracle too.
+ */
 export async function logout(auth: Auth, token: string): Promise<boolean> {
   const parsed = parseSessionToken(token);
   if (parsed === null) return false;
+  const session = await auth.adapter.getSession(parsed.id);
+  if (session === null) return false;
+  if (!timingSafeEqual(sha256Hex(parsed.secret), session.tokenHash)) return false;
   return await auth.adapter.deleteSession(parsed.id);
 }

package/src/builtin-adapter.ts

@@ -14,6 +14,7 @@ import type {
   CreateUserInput,
   SessionPatch,
   UserPatch,
+  UserQuery,
 } from './adapter';
 import { authWriteFailed } from './errors';
 
@@ -54,8 +55,10 @@ const toUser = (row: Row): AuthUser => ({
   orgId: textOrNull(row, 'org_id'),
   roles: list(row, 'roles'),
   permissions: list(row, 'permissions'),
+  scopes: list(row, 'scopes'),
   mfaSecret: textOrNull(row, 'mfa_secret'),
   recoveryCodeHashes: list(row, 'recovery_code_hashes'),
+  externalId: textOrNull(row, 'external_id'),
   disabledAt: dateOrNull(row, 'disabled_at'),
   createdAt: date(row, 'created_at'),
 });
@@ -131,9 +134,11 @@ export class BuiltinAdapter implements AuthAdapter {
 
   async createUser(input: CreateUserInput): Promise<AuthUser> {
     const row = await this.#db.one<Row>(sql`
-      insert into x_users (id, email, password_hash, org_id, roles, created_at)
+      insert into x_users (id, email, password_hash, org_id, roles, scopes, external_id,
+                           created_at)
       values (${input.id}, ${input.email}, ${input.passwordHash}, ${input.orgId},
-              ${[...input.roles]}, ${input.createdAt})
+              ${[...input.roles]}, ${[...(input.scopes ?? [])]}, ${input.externalId ?? null},
+              ${input.createdAt})
       returning *`);
     // An empty `returning` means no row landed. A user fabricated from `{}` would travel back
     // out of `register()` as a successful registration with no identity in it.
@@ -155,12 +160,44 @@ export class BuiltinAdapter implements AuthAdapter {
         disabled_at = case when ${patch.disabledAt !== undefined}
           then ${patch.disabledAt ?? null} else disabled_at end,
         roles = case when ${patch.roles !== undefined}
-          then ${[...(patch.roles ?? [])]} else roles end
+          then ${[...(patch.roles ?? [])]} else roles end,
+        permissions = case when ${patch.permissions !== undefined}
+          then ${[...(patch.permissions ?? [])]} else permissions end,
+        scopes = case when ${patch.scopes !== undefined}
+          then ${[...(patch.scopes ?? [])]} else scopes end,
+        org_id = case when ${patch.orgId !== undefined}
+          then ${patch.orgId ?? null} else org_id end,
+        external_id = case when ${patch.externalId !== undefined}
+          then ${patch.externalId ?? null} else external_id end
       where id = ${id}
       returning *`);
     return row === null ? null : toUser(row);
   }
 
+  async findUserByExternalId(externalId: string): Promise<AuthUser | null> {
+    const row = await this.#db.one<Row>(
+      sql`select * from x_users where external_id = ${externalId}`,
+    );
+    return row === null ? null : toUser(row);
+  }
+
+  /**
+   * One statement, and the two filters are conditional predicates rather than assembled SQL, for
+   * the reason `updateUser`'s columns are: the statement text stays constant and nothing is
+   * interpolated. Disabled members are excluded by default — an access review reads who can sign
+   * in today — and `includeDisabled` is what an offboarding audit passes.
+   */
+  async listUsersByOrg(orgId: string, query?: UserQuery): Promise<readonly AuthUser[]> {
+    const role = query?.role ?? null;
+    const rows = await this.#db.query<Row>(sql`
+      select * from x_users
+      where org_id = ${orgId}
+        and (${query?.includeDisabled === true} or disabled_at is null)
+        and (${role === null} or ${role} = any (roles))
+      order by email asc`);
+    return rows.map(toUser);
+  }
+
   async getSession(id: string): Promise<AuthSession | null> {
     const row = await this.#db.one<Row>(sql`select * from x_sessions where id = ${id}`);
     return row === null ? null : toSession(row);
@@ -201,6 +238,26 @@ export class BuiltinAdapter implements AuthAdapter {
     );
   }
 
+  async deleteSessionsForUser(userId: string): Promise<number> {
+    return await this.#db.execute(sql`delete from x_sessions where user_id = ${userId}`);
+  }
+
+  /**
+   * Joins through `x_users` rather than reading an `org_id` off the session. The column does not
+   * exist on `x_sessions` and is not being added: a copy of the membership goes stale the moment
+   * somebody changes org, and a stale row means the 03:00 sweep leaves live exactly the sessions
+   * it was run to kill.
+   */
+  async deleteSessionsForOrg(orgId: string): Promise<number> {
+    return await this.#db.execute(sql`
+      delete from x_sessions
+      where user_id in (select id from x_users where org_id = ${orgId})`);
+  }
+
+  async deleteSessionsCreatedBefore(before: Date): Promise<number> {
+    return await this.#db.execute(sql`delete from x_sessions where created_at < ${before}`);
+  }
+
   async listSessions(userId: string): Promise<readonly AuthSession[]> {
     const rows = await this.#db.query<Row>(
       sql`select * from x_sessions where user_id = ${userId} order by last_seen_at desc`,
@@ -244,11 +301,31 @@ export class BuiltinAdapter implements AuthAdapter {
             consumed_at = null`);
   }
 
-  /** The `consumed_at is null` predicate is what makes redemption single-use under concurrency. */
-  async takeVerification(purpose: string, identifier: string): Promise<AuthVerification | null> {
+  /**
+   * One conditional UPDATE, and every part of the predicate is load-bearing. `consumed_at is null`
+   * on the UPDATE itself is what makes redemption single-use under concurrency — inside the
+   * subselect alone, two racing redemptions both pick the row and both consume it. `token_hash`
+   * is what keeps a wrong guess from consuming anything: a consume that happens before the
+   * comparison turns any unauthenticated POST into a way to kill the victim's emailed link. The
+   * predicate compares the digest and never the token, so it leaks what a `=` on a hash leaks.
+   * `order by created_at desc limit 1` addresses exactly one row: `unique (purpose, identifier)`
+   * (`tables.ts`) already allows only one, but an unbounded `update … where` consumes every row
+   * that matches, so a table missing that constraint would redeem links nobody presented.
+   */
+  async takeVerification(
+    purpose: string,
+    identifier: string,
+    tokenHash: string,
+  ): Promise<AuthVerification | null> {
     const row = await this.#db.one<Row>(sql`
       update x_verifications set consumed_at = now()
-      where purpose = ${purpose} and identifier = ${identifier} and consumed_at is null
+      where consumed_at is null and id = (
+        select id from x_verifications
+        where purpose = ${purpose} and identifier = ${identifier}
+          and consumed_at is null and token_hash = ${tokenHash}
+        order by created_at desc
+        limit 1
+      )
       returning *`);
     return row === null ? null : toVerification(row);
   }

package/src/directory.ts

@@ -0,0 +1,77 @@
+// Single responsibility: reading accounts back out, safely. A quarterly access review — "who in
+// this org holds `admin`, and is any of them gone?" — was unanswerable: `UserStore` could find one
+// user by address or by id and nothing else, so there was no way to enumerate an org's members at
+// all. The projection is `describeApiKey`'s shape and its rule: never the password hash, never the
+// TOTP secret, never a recovery code hash.
+
+import type { AuthUser, UserQuery } from './adapter';
+import type { Auth } from './auth';
+import { authNotImplemented } from './errors';
+
+/** Safe to render in an admin page, return from an MCP tool, or paste into a review ticket. */
+export interface AuthUserSummary {
+  readonly id: string;
+  readonly email: string;
+  readonly orgId: string | null;
+  readonly roles: readonly string[];
+  readonly permissions: readonly string[];
+  readonly scopes: readonly string[];
+  readonly externalId: string | null;
+  /** Whether a second factor is enrolled. The secret itself never leaves the server. */
+  readonly mfaEnrolled: boolean;
+  readonly emailVerifiedAt: Date | null;
+  readonly disabledAt: Date | null;
+  readonly createdAt: Date;
+}
+
+/**
+ * The one projection. An allow-list rather than a delete-list, because a column added to
+ * `AuthUser` later must not appear here by default — that is how a `mfaSecret` ends up in an
+ * admin JSON response one refactor after somebody was careful.
+ */
+export function describeUser(user: AuthUser): AuthUserSummary {
+  return {
+    id: user.id,
+    email: user.email,
+    orgId: user.orgId,
+    roles: user.roles,
+    permissions: user.permissions,
+    scopes: user.scopes,
+    externalId: user.externalId,
+    mfaEnrolled: user.mfaSecret !== null,
+    emailVerifiedAt: user.emailVerifiedAt,
+    disabledAt: user.disabledAt,
+    createdAt: user.createdAt,
+  };
+}
+
+const unsupported = (method: string, adapterName: string) =>
+  authNotImplemented(
+    `${adapterName}.${method}()`,
+    `implement ${method}() on your AuthAdapter — BuiltinAdapter (Postgres) and MemoryAdapter are the two reference implementations, in packages/auth/src`,
+  );
+
+/** Every member of one org, as summaries. `query.role` narrows it to one role's holders. */
+export async function listOrgUsers(
+  auth: Auth,
+  orgId: string,
+  query?: UserQuery,
+): Promise<readonly AuthUserSummary[]> {
+  const list = auth.adapter.listUsersByOrg?.bind(auth.adapter);
+  if (list === undefined) throw unsupported('listUsersByOrg', auth.adapter.name);
+  return (await list(orgId, query)).map(describeUser);
+}
+
+/**
+ * The account a provisioning system already knows by its own id. This is what a SCIM `PUT` or
+ * `PATCH` resolves against — an email address cannot be, because a rename changes it and the
+ * subject stays the same person.
+ */
+export async function findUserByExternalId(
+  auth: Auth,
+  externalId: string,
+): Promise<AuthUser | null> {
+  const find = auth.adapter.findUserByExternalId?.bind(auth.adapter);
+  if (find === undefined) throw unsupported('findUserByExternalId', auth.adapter.name);
+  return await find(externalId);
+}

package/src/email.ts

@@ -0,0 +1,17 @@
+// Single responsibility: the ONE normalisation an email address gets before anything uses it as an
+// identity key — a user lookup, a user insert, or the lockout bucket that has to key the same way
+// those two do. It lives above the `AuthAdapter` seam because an adapter that normalises hides a
+// caller that forgot to: `MemoryAdapter` did and `BuiltinAdapter` did not, so "does this account
+// exist" had two answers, one under `x dev` and another in production.
+
+/**
+ * Trim, then lowercase. Nothing else, deliberately: stripping a `+tag` or a gmail dot would MERGE
+ * two addresses a person kept apart on purpose, which is an account takeover between colleagues at
+ * one domain rather than a convenience. RFC 5321 makes the local part case-sensitive in theory and
+ * no mail provider in practice treats it that way, so folding case is what stops one human holding
+ * two accounts at one address — and `x_users.email` is a plain `text ... unique`, whose uniqueness
+ * is exactly this string.
+ */
+export function normaliseEmail(email: string): string {
+  return email.trim().toLowerCase();
+}