@ultimat3/auth 23.0.0 → 25.0.0

package/src/revocation.ts

@@ -7,7 +7,7 @@
 import { logger } from '@ultimat3/core';
 import type { AuthUser } from './adapter';
 import type { Auth } from './auth';
-import { authNotImplemented, authWriteFailed } from './errors';
+import { authWriteFailed } from './errors';
 
 /**
  * Every revocation is logged before it runs, with the reason the caller gave. An incident review
@@ -18,22 +18,14 @@ const record = (operation: string, scope: string, reason: string): void => {
   logger.warn('auth.revocation', { operation, scope, reason });
 };
 
-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 session this user holds, their current one included. Returns how many died. */
 export async function revokeUserSessions(
   auth: Auth,
   userId: string,
   reason: string,
 ): Promise<number> {
-  const remove = auth.adapter.deleteSessionsForUser?.bind(auth.adapter);
-  if (remove === undefined) throw unsupported('deleteSessionsForUser', auth.adapter.name);
   record('revokeUserSessions', userId, reason);
-  return await remove(userId);
+  return await auth.adapter.deleteSessionsForUser(userId);
 }
 
 /**
@@ -45,10 +37,8 @@ export async function revokeOrgSessions(
   orgId: string,
   reason: string,
 ): Promise<number> {
-  const remove = auth.adapter.deleteSessionsForOrg?.bind(auth.adapter);
-  if (remove === undefined) throw unsupported('deleteSessionsForOrg', auth.adapter.name);
   record('revokeOrgSessions', orgId, reason);
-  return await remove(orgId);
+  return await auth.adapter.deleteSessionsForOrg(orgId);
 }
 
 /**
@@ -61,37 +51,47 @@ export async function revokeSessionsCreatedBefore(
   before: Date,
   reason: string,
 ): Promise<number> {
-  const remove = auth.adapter.deleteSessionsCreatedBefore?.bind(auth.adapter);
-  if (remove === undefined) throw unsupported('deleteSessionsCreatedBefore', auth.adapter.name);
   record('revokeSessionsCreatedBefore', before.toISOString(), reason);
-  return await remove(before);
+  return await auth.adapter.deleteSessionsCreatedBefore(before);
 }
 
 export interface DisabledUser {
   readonly user: AuthUser;
   readonly sessionsRevoked: number;
+  /** Live api keys this user owned, now revoked. A key is the owner's credential too. */
+  readonly apiKeysRevoked: number;
 }
 
 /**
- * `disabledAt` is read by `login`, by `authenticate` and by the OAuth path — and until this
- * function existed, no code path anywhere ever SET it. Offboarding was an UPDATE somebody typed.
+ * `disabledAt` is read by `login`, by `authenticate`, by `verifyApiKey` and by the OAuth path.
+ *
+ * Stamping the column is not enough on its own: every one of those readers re-reads the user row,
+ * so a disabled account stops working on its next request, but the live session rows are still
+ * there and still slide, and the api keys still read as live in every listing. Both go in the
+ * same call, in that order — stamp first, so a request racing the revocation finds the row
+ * already disabled. Re-enabling restores neither.
  *
- * Stamping the column is not enough on its own: `authenticate` re-reads the user row on every
- * request, so a disabled account stops working on its next request, but the live session row is
- * still there and still slides. The sessions go in the same call, in that order — stamp first, so
- * a request racing the revocation finds the row already disabled.
+ * The log line is written before the first write, as every revocation's is: an incident review
+ * must find the reason even when the write that followed it failed.
  */
 export async function disableUser(
   auth: Auth,
   userId: string,
   reason: string,
 ): Promise<DisabledUser> {
-  const user = await auth.adapter.updateUser(userId, { disabledAt: auth.clock.now() });
+  record('disableUser', userId, reason);
+  const now = auth.clock.now();
+  const user = await auth.adapter.updateUser(userId, { disabledAt: now });
   // No row came back: either there is no such user, or the adapter did not return the update.
   // Both mean the account is not known to be disabled, and reporting success would be a lie.
   if (user === null) throw authWriteFailed('updateUser', 'x_users');
-  record('disableUser', userId, reason);
-  return { user, sessionsRevoked: await revokeUserSessions(auth, userId, reason) };
+  const sessionsRevoked = await auth.adapter.deleteSessionsForUser(userId);
+  let apiKeysRevoked = 0;
+  for (const key of await auth.adapter.listApiKeys(userId)) {
+    if (key.revokedAt !== null) continue;
+    if (await auth.adapter.revokeApiKey(key.id, now)) apiKeysRevoked += 1;
+  }
+  return { user, sessionsRevoked, apiKeysRevoked };
 }
 
 /** The inverse. No sessions are restored — a re-enabled account signs in again, deliberately. */

package/src/session.ts

@@ -5,10 +5,11 @@
 // to them without this package importing it (same-tier packages must not depend on each other).
 
 import type { Clock } from '@ultimat3/core';
+import { readCookie, serializeSetCookie, timingSafeEqual } from '@ultimat3/core';
 import type { AuthSession, SessionStore } from './adapter';
-import { sessionExpired, sessionUnknown } from './errors';
+import { AuthError, sessionExpired, sessionUnknown } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
-import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+import { randomToken, sha256Hex } from './tokens';
 
 export interface SessionPolicy {
   /** Hard ceiling from creation. Never extended. */
@@ -91,8 +92,38 @@ export interface CreateSessionInput {
   readonly ip?: string | null | undefined;
   readonly userAgent?: string | null | undefined;
   readonly mfaSatisfied?: boolean | undefined;
+  /**
+   * The lifetime a rotation inherits. Absent means a new login: born now, ceiling one
+   * `absoluteTtlMs` away. Either way the ceiling is clamped to `createdAt + absoluteTtlMs` and
+   * `createdAt` to now, so an inherited value can only ever shorten a session — never buy it time.
+   */
+  readonly createdAt?: Date | undefined;
+  readonly absoluteExpiresAt?: Date | undefined;
 }
 
+/**
+ * An inherited instant that is not one. `X_CONFIG_INVALID`, core's code borrowed as
+ * `authPolicyNumberInvalid` borrows it: a caller handed this package a value it cannot honour. An
+ * Invalid Date ceiling is not a short session but one that never ends — `now >= NaN` is false.
+ */
+const inheritedInstantInvalid = (field: 'createdAt' | 'absoluteExpiresAt'): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `createSession({ ${field} }) is an Invalid Date, and stored as a ceiling it would never expire, because every comparison against NaN is false`,
+    fix: `createSession(runtime, { userId, createdAt: session.createdAt, absoluteExpiresAt: session.absoluteExpiresAt }) with the Dates read off a live session, or omit both for a new login`,
+    meta: { field },
+  });
+
+const inheritedMs = (
+  field: 'createdAt' | 'absoluteExpiresAt',
+  value: Date | undefined,
+): number | undefined => {
+  if (value === undefined) return undefined;
+  const ms = value.getTime();
+  if (!Number.isFinite(ms)) throw inheritedInstantInvalid(field);
+  return ms;
+};
+
 /** `<id>.<secret>`: the id is the row key, the secret is the half that is hashed. */
 export function parseSessionToken(token: string): { id: string; secret: string } | null {
   const dot = token.indexOf('.');
@@ -105,14 +136,20 @@ export async function createSession(
   input: CreateSessionInput,
 ): Promise<IssuedSession> {
   const now = runtime.clock.now();
+  // Screened ABOVE the write: `Math.min(NaN, …)` is NaN, so an Invalid Date stored a ceiling
+  // nothing ever reaches.
+  const inheritedBorn = inheritedMs('createdAt', input.createdAt);
+  const inheritedCeiling = inheritedMs('absoluteExpiresAt', input.absoluteExpiresAt);
   const id = randomToken(12);
   const secret = randomToken(32);
+  const born = Math.min(inheritedBorn ?? now.getTime(), now.getTime());
+  const ceiling = born + runtime.policy.absoluteTtlMs;
   const session = await runtime.store.createSession({
     id,
     userId: input.userId,
     tokenHash: sha256Hex(secret),
-    createdAt: now,
-    absoluteExpiresAt: new Date(now.getTime() + runtime.policy.absoluteTtlMs),
+    createdAt: new Date(born),
+    absoluteExpiresAt: new Date(Math.min(inheritedCeiling ?? ceiling, ceiling)),
     lastSeenAt: now,
     ip: input.ip ?? null,
     userAgent: input.userAgent ?? null,
@@ -183,21 +220,39 @@ export async function verifySession(
 /**
  * Privilege change (role grant, MFA satisfied, password change) must not reuse the old id:
  * whoever already holds the old cookie would inherit the new privileges.
+ *
+ * A new id, never a new lifetime: `createdAt` and the absolute ceiling carry over. Minting them
+ * fresh let a session rotated often enough (a weekly role toggle) live forever, and hid it from
+ * `revokeSessionsCreatedBefore` — the sweep run after a leak, keyed on exactly that column.
  */
 export async function rotateSession(
   runtime: SessionRuntime,
   session: AuthSession,
   patch?: { readonly mfaSatisfied?: boolean | undefined },
 ): Promise<IssuedSession> {
-  await runtime.store.deleteSession(session.id);
+  // The delete IS the claim, in one atomic step — the `consumeRecoveryCode` contract. Ignoring its
+  // answer resurrected a session revoked between verify and rotate, and let two concurrent
+  // rotations fork one session into two live ones. Only the caller whose delete landed mints S'.
+  if (!(await runtime.store.deleteSession(session.id))) throw sessionUnknown();
   return await createSession(runtime, {
     userId: session.userId,
     ip: session.ip,
     userAgent: session.userAgent,
     mfaSatisfied: patch?.mfaSatisfied ?? session.mfaSatisfied,
+    createdAt: session.createdAt,
+    absoluteExpiresAt: session.absoluteExpiresAt,
   });
 }
 
+/**
+ * `Max-Age` for a cookie carrying `session`: the seconds left until its absolute ceiling, never
+ * below zero. A rotated session's cookie needs this rather than the policy's full TTL, or the
+ * client keeps the cookie for weeks after the server stopped honouring it.
+ */
+export function remainingMaxAgeSeconds(session: AuthSession, now: Date): number {
+  return Math.max(0, Math.floor((session.absoluteExpiresAt.getTime() - now.getTime()) / 1000));
+}
+
 export async function revokeSession(runtime: SessionRuntime, sessionId: string): Promise<boolean> {
   return await runtime.store.deleteSession(sessionId);
 }
@@ -269,45 +324,22 @@ export function sessionCookie(
           'the cookie carries an attribute that is not delta-seconds, so the browser drops it and keeps the session cookie for the whole browsing session',
           0,
         );
-  return `${name}=${token}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
-}
-
-/** Same attributes, empty value, `Max-Age=0` — a mismatched attribute set leaves a live twin. */
-export function clearSessionCookie(policy: SessionPolicy, name?: string): string {
-  return `${name ?? policy.cookieName}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+  return serializeSetCookie(name, token, { maxAge });
 }
 
 /**
- * The one `Cookie:` parser in this package — the oauth handshake reads through it too, so it never
- * throws: a missing or unreadable cookie is `null` or the raw value, never an exception.
+ * Same attributes, empty value, `Max-Age=0` — a mismatched attribute set leaves a live twin. Both
+ * go through core's `serializeSetCookie`, whose defaults ARE `Path=/; HttpOnly; Secure;
+ * SameSite=Lax`, so the two lines cannot drift apart by one hand-edited attribute.
  */
-export function readCookie(request: RequestLike, name: string): string | null {
-  const header = request.headers.get('cookie');
-  if (header === null) return null;
-  for (const part of header.split(';')) {
-    const equals = part.indexOf('=');
-    if (equals < 0) continue;
-    if (part.slice(0, equals).trim() !== name) continue;
-    return decodeCookieValue(part.slice(equals + 1).trim());
-  }
-  return null;
+export function clearSessionCookie(policy: SessionPolicy, name?: string): string {
+  return serializeSetCookie(name ?? policy.cookieName, '', { maxAge: 0 });
 }
 
 /**
- * A `Cookie:` header is attacker-controlled, and `decodeURIComponent('%')` throws a bare
- * `URIError` — which escapes every coded path that reads through here: an OAuth callback would
- * answer 500 instead of `X_OAUTH_STATE_INVALID`. The raw value is returned instead, so the
- * caller's own rejection stays the readable failure. Nothing is loosened by it: a raw value is
- * still checked against a signature or a stored hash, and neither matches a mangled one.
+ * The session token off the request, through core's `readCookie` — the oauth handshake reads
+ * through the same one, so neither throws: a missing or unreadable cookie is `null` or the raw value.
  */
-function decodeCookieValue(raw: string): string {
-  try {
-    return decodeURIComponent(raw);
-  } catch {
-    return raw;
-  }
-}
-
 export function readSessionCookie(request: RequestLike, policy: SessionPolicy): string | null {
-  return readCookie(request, policy.cookieName);
+  return readCookie(request.headers.get('cookie'), policy.cookieName);
 }

package/src/tables.ts

@@ -1,4 +1,4 @@
-// Single responsibility: the DDL `BuiltinAdapter` expects, as `AUTH_TABLES` — applied at every boot
+// Single responsibility: the DDL `PostgresAuthAdapter` expects, as `AUTH_TABLES` — applied at every boot
 // by `@ultimat3/cli`'s `FRAMEWORK_SCHEMA`, upgrades of an older table included. Plain strings, so
 // what auth stores is verifiable by reading, never by trusting. There is nothing to paste into a
 // migration any more: the per-table exports and `X_USERS_MIGRATION_1_3` are gone (22.0.0).
@@ -9,16 +9,15 @@
 // |---|---|
 // | `x_users.password_hash` | an argon2id digest, never the password |
 // | `x_users.recovery_code_hashes` | SHA-256 digests, never the codes (`mfa.ts`) |
-// | `x_users.mfa_secret` | **the base32 TOTP seed, in the clear** — see below |
+// | `x_users.mfa_secret` | the TOTP seed SEALED under the app's master key (`mfa-secret.ts`) |
 // | `x_accounts.access_token` / `refresh_token` | **nothing.** The framework writes `null` |
 // | `x_sessions.*`, `x_verifications.token_hash` | digests and metadata, never a token |
 //
-// `mfa_secret` is the one plaintext secret this schema still holds, and it is stated here rather
-// than glossed: a TOTP seed is symmetric, so verifying a code requires the seed itself and a
-// digest cannot replace it. Encrypting it needs a key-management seam this package does not have,
-// which is a design change and not a patch — DEFERRED, deliberately, and written down so nobody
-// reads the header above as covering it. `mfa.ts`'s "a database dump is not a permanent MFA
-// bypass" is true of the recovery CODES and not of the seed.
+// `mfa_secret` cannot be a digest: a TOTP seed is symmetric, so verifying a code needs the seed
+// itself. It is sealed with `purpose: 'auth:x_users.mfa_secret'`, written by `saveTotpSecret` and
+// opened by `openTotpSecret`, which REFUSES a value that is not sealed (`X_MFA_SECRET_UNSEALED`).
+// The column type is unchanged, so there is no DDL to upgrade — a row written before sealing is
+// sealed in place by `x auth seal-mfa`, once.
 //
 // The two `x_accounts` token columns are kept in the DDL and written `null`: they held live
 // provider credentials in the clear and nothing in this package ever read them back
@@ -36,8 +35,7 @@ export const X_USERS_TABLE = `create table if not exists x_users (
   permissions           text[] not null default '{}',
   scopes                text[] not null default '{}',
   external_id           text unique,
-  -- The base32 TOTP seed, in the clear. A seed is symmetric: a digest cannot verify a code.
-  -- Encryption at rest is deferred and needs a key-management seam - see the header.
+  -- The TOTP seed, sealed (x1.<keyId>.<iv>.<ciphertext>). Never base32 in the clear.
   mfa_secret            text,
   recovery_code_hashes  text[] not null default '{}',
   disabled_at           timestamptz,

package/src/tokens.ts

@@ -1,14 +1,11 @@
 // Single responsibility: the secret primitives every other file in this package shares —
 // CSPRNG tokens and SHA-256 hashing. Centralised so no call site can quietly reach for `===` on
 // a secret, which leaks the shared prefix length one request at a time. The constant-time
-// comparison itself lives in `@ultimat3/core` (`timingSafeEqual`) — `@ultimat3/storage` needs the
-// exact same one, and re-exporting it here keeps every existing `from '@ultimat3/auth'` import
-// working.
+// comparison itself is `@ultimat3/core`'s `timingSafeEqual` — `@ultimat3/storage` needs the exact
+// same one — imported from core by every caller, never re-exported here (`X_HELPER_COPY`).
 
 import { finiteCount, timingSafeEqual } from '@ultimat3/core';
 
-export { timingSafeEqual };
-
 const BASE64URL_UNSAFE = /[+/=]/g;
 const BASE64URL_REPLACEMENTS: Readonly<Record<string, string>> = { '+': '-', '/': '_', '=': '' };
 

package/src/verify.ts

@@ -1,14 +1,15 @@
 // Single responsibility: email verification and password reset — the two flows where a link in
 // an inbox is a credential. Tokens are single-use, expiring, stored hashed and compared in
-// constant time. Mail leaves through an injected `MailSender` port: the app wires
-// `@ultimat3/mail`'s `send` into it, because auth must not depend on a sideways tier-3 package.
+// constant time. Mail leaves through an injected structural `MailSender` port: `@ultimat3/mail` is
+// tier 4 and auth is tier 2, so the app wires mail's `send` in and auth imports nothing upward.
 
 import type { Clock } from '@ultimat3/core';
+import { timingSafeEqual } from '@ultimat3/core';
 import type { AuthVerification, VerificationStore } from './adapter';
 import { normaliseEmail } from './email';
 import { AuthError } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
-import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+import { randomToken, sha256Hex } from './tokens';
 
 /**
  * `locale` is required, not optional: an inferred locale is how a user gets a security email