@ultimat3/auth 1.1.0 → 2.0.0

package/src/session.ts

@@ -12,13 +12,34 @@ import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
 export interface SessionPolicy {
   /** Hard ceiling from creation. Never extended. */
   readonly absoluteTtlMs: number;
-  /** Measured from `lastSeenAt`, refreshed on every verified request. */
+  /** Measured from `lastSeenAt`, refreshed at most once per `idleSlideMs`. */
   readonly idleTtlMs: number;
+  /**
+   * How stale `lastSeenAt` may get before a verified request writes it forward. Absent means
+   * `idleTtlMs / IDLE_SLIDE_DIVISOR`, derived rather than a constant so an app that shortens
+   * `idleTtlMs` does not silently get a slide longer than its own idle window — which would
+   * pin every session to its creation time and expire it on the dot.
+   *
+   * It exists because `verifySession` used to write on EVERY authenticated request: one request
+   * was a SELECT, an `UPDATE … RETURNING *` and a second SELECT, before the app's own first
+   * query. At 20k rps that is 20k writes a second on one hot table, autovacuum falls behind, and
+   * the incident reads as "the database is slow" rather than "authentication is a write path".
+   * The trade is bounded: idle expiry is now precise to within one `idleSlideMs`.
+   */
+  readonly idleSlideMs?: number | undefined;
   readonly cookieName: string;
   /** Mint a new session id whenever roles/scopes change — closes session fixation. */
   readonly rotateOnPrivilegeChange: boolean;
 }
 
+/** 20 → roughly 5% of the idle window, so the write rate falls ~20× and the drift stays small. */
+export const IDLE_SLIDE_DIVISOR = 20;
+
+/** The resolved slide, wherever it is read. One derivation, so the two readers cannot disagree. */
+export function idleSlideMs(policy: SessionPolicy): number {
+  return Math.max(0, policy.idleSlideMs ?? Math.floor(policy.idleTtlMs / IDLE_SLIDE_DIVISOR));
+}
+
 export const DEFAULT_SESSION_POLICY: SessionPolicy = Object.freeze({
   absoluteTtlMs: 30 * 24 * 60 * 60 * 1000,
   idleTtlMs: 7 * 24 * 60 * 60 * 1000,
@@ -134,10 +155,18 @@ export async function verifySession(
     throw sessionExpired(expiry.absoluteExpired ? 'absolute' : 'idle', session.id);
   }
 
+  const ip = observed?.ip ?? session.ip;
+  const userAgent = observed?.userAgent ?? session.userAgent;
+  // The window slides only when it has actually moved. A second request inside the slide issues
+  // no write at all — the read path stays a read — while a changed address or user agent is
+  // written immediately, because that is the row a device list and an incident review read.
+  const stale = now.getTime() - session.lastSeenAt.getTime() >= idleSlideMs(runtime.policy);
+  if (!stale && ip === session.ip && userAgent === session.userAgent) return session;
+
   const touched = await runtime.store.updateSession(session.id, {
-    lastSeenAt: now,
-    ip: observed?.ip ?? session.ip,
-    userAgent: observed?.userAgent ?? session.userAgent,
+    lastSeenAt: stale ? now : session.lastSeenAt,
+    ip,
+    userAgent,
   });
   return touched ?? session;
 }

package/src/tables.ts

@@ -10,11 +10,26 @@ export const X_USERS_TABLE = `create table if not exists x_users (
   org_id                uuid,
   roles                 text[] not null default '{}',
   permissions           text[] not null default '{}',
+  scopes                text[] not null default '{}',
+  external_id           text unique,
   mfa_secret            text,
   recovery_code_hashes  text[] not null default '{}',
   disabled_at           timestamptz,
   created_at            timestamptz not null default now()
-)`;
+);
+create index if not exists x_users_org_id_idx on x_users (org_id)`;
+
+/**
+ * The two columns `x_users` gained in 1.3.0, as the statements an app already running 1.2 runs
+ * once. Both are additive and both have a default, so the migration is not a rewrite and takes no
+ * exclusive lock beyond the catalog update.
+ */
+export const X_USERS_MIGRATION_1_3: readonly string[] = Object.freeze([
+  `alter table x_users add column if not exists scopes text[] not null default '{}'`,
+  'alter table x_users add column if not exists external_id text',
+  'create unique index if not exists x_users_external_id_key on x_users (external_id)',
+  'create index if not exists x_users_org_id_idx on x_users (org_id)',
+]);
 
 // `id` is the public half of the cookie; `token_hash` is sha256 of the secret half.
 export const X_SESSIONS_TABLE = `create table if not exists x_sessions (
@@ -29,7 +44,8 @@ export const X_SESSIONS_TABLE = `create table if not exists x_sessions (
   mfa_satisfied         boolean not null default false
 );
 create index if not exists x_sessions_user_id_idx on x_sessions (user_id);
-create index if not exists x_sessions_absolute_expires_at_idx on x_sessions (absolute_expires_at)`;
+create index if not exists x_sessions_absolute_expires_at_idx on x_sessions (absolute_expires_at);
+create index if not exists x_sessions_created_at_idx on x_sessions (created_at)`;
 
 export const X_ACCOUNTS_TABLE = `create table if not exists x_accounts (
   id                    uuid primary key,

package/src/tokens.ts

@@ -1,7 +1,13 @@
 // Single responsibility: the secret primitives every other file in this package shares —
-// CSPRNG tokens, SHA-256 hashing and a comparison whose duration does not depend on where
-// two strings first differ. Centralised so no call site can quietly reach for `===` on a
-// secret, which leaks the shared prefix length one request at a time.
+// 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.
+
+import { timingSafeEqual } from '@ultimat3/core';
+
+export { timingSafeEqual };
 
 const BASE64URL_UNSAFE = /[+/=]/g;
 const BASE64URL_REPLACEMENTS: Readonly<Record<string, string>> = { '+': '-', '/': '_', '=': '' };
@@ -23,6 +29,23 @@ export function randomToken(byteLength = 32): string {
   return base64Url(randomBytes(byteLength));
 }
 
+/**
+ * The inverse of `base64Url`, for the segments of a JWT. Answers `null` rather than throwing
+ * because every caller is reading an attacker-supplied string — a `URIError` or an `InvalidCharacterError`
+ * escaping from here would turn a coded refusal into a 500, the same reason `readCookie` never throws.
+ */
+export function base64UrlBytes(segment: string): Uint8Array<ArrayBuffer> | null {
+  const padded = segment
+    .replaceAll('-', '+')
+    .replaceAll('_', '/')
+    .padEnd(Math.ceil(segment.length / 4) * 4, '=');
+  try {
+    return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+
 export function sha256Hex(value: string): string {
   return new Bun.CryptoHasher('sha256').update(value).digest('hex');
 }
@@ -31,20 +54,6 @@ export function sha256Bytes(value: string): Uint8Array {
   return Uint8Array.from(new Bun.CryptoHasher('sha256').update(value).digest());
 }
 
-/**
- * Length is compared first and non-constant-time on purpose: every secret this package
- * compares is a fixed-width hash or token, so the length carries no information, and the
- * XOR accumulator below is what has to be branch-free.
- */
-export function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let index = 0; index < a.length; index += 1) {
-    diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
-  }
-  return diff === 0;
-}
-
 /** Hash-then-compare. The plaintext never has to be held next to the stored value. */
 export function matchesHash(plaintext: string, storedHash: string): boolean {
   return timingSafeEqual(sha256Hex(plaintext), storedHash);

package/src/verify.ts

@@ -108,19 +108,26 @@ export interface ConsumeVerificationInput {
 }
 
 /**
- * The store consumes the row atomically, so a second redemption finds nothing even if it
- * races the first. The hash comparison happens after, on the row we already own.
+ * The hash goes INTO the consume, it is not compared after one: the store consumes the row only
+ * when the hash is the live row's, atomically, so a second redemption finds nothing even if it
+ * races the first *and* a wrong guess leaves the row live. Comparing afterwards made an
+ * unauthenticated POST with any token at all destroy the victim's emailed link — one request per
+ * address for permanent password-reset denial.
  */
 export async function consumeVerification(
   runtime: VerificationRuntime,
   input: ConsumeVerificationInput,
 ): Promise<AuthVerification> {
-  const record = await runtime.store.takeVerification(input.purpose, input.identifier);
+  const tokenHash = sha256Hex(input.token);
+  const record = await runtime.store.takeVerification(input.purpose, input.identifier, tokenHash);
   if (record === null) throw verificationInvalid(input.purpose);
-  if (runtime.clock.now().getTime() >= record.expiresAt.getTime()) {
+  // Kept for the seam, not for the blessed adapters: `VerificationStore` is implementable by an
+  // app, and one that ignores the third argument would otherwise redeem any token. Constant-time
+  // because this package never compares a secret — or a digest of one — with `===`.
+  if (!timingSafeEqual(tokenHash, record.tokenHash)) {
     throw verificationInvalid(input.purpose);
   }
-  if (!timingSafeEqual(sha256Hex(input.token), record.tokenHash)) {
+  if (runtime.clock.now().getTime() >= record.expiresAt.getTime()) {
     throw verificationInvalid(input.purpose);
   }
   return record;

package/src/workload.ts

@@ -0,0 +1,131 @@
+// Single responsibility: verifying a workload's own JWT and turning it into a `ServiceIdentity`.
+// Before this, `ServiceIdentity` was a plain struct with no non-test caller and nothing in the
+// framework verified a service credential at all — no workload identity, no `client_credentials`,
+// no token exchange — so two Ultimate services could only trust each other through a long-lived
+// shared secret in an env var, with no rotation and no per-caller identity.
+//
+// One function covers the three shapes in practice, because they are all the same JWT: a
+// Kubernetes projected service-account token, a SPIFFE JWT-SVID, and a cloud IMDS token. It is
+// also the shape RFC 8693's `subject_token` takes, so a token-exchange endpoint reads through it.
+//
+// mTLS is deliberately out of scope: TLS termination is the mesh's job (axiom 7), and the
+// framework's part is reading a trusted `x-forwarded-client-cert` through `@ultimat3/http`'s
+// trusted-proxy seam — which is that package's to own, not this one's.
+
+import type { Clock } from '@ultimat3/core';
+import { AuthError } from './errors';
+import { ID_TOKEN_CLOCK_SKEW_MS } from './id-token';
+import { decodeJwtSegment } from './json';
+import { type JwksKeySource, verifyJwtSignature } from './jwks';
+import type { ServiceIdentity } from './policy-bridge';
+
+/** The claims a workload token is read for. Everything else the issuer sends is ignored. */
+export interface WorkloadClaims {
+  readonly iss: string;
+  readonly sub: string;
+  readonly aud: readonly string[];
+  readonly exp: number;
+  readonly nbf?: number | undefined;
+  readonly iat?: number | undefined;
+  /** `scope` (space-delimited, RFC 8693 / OAuth) or `scp` (an array). Absent means none. */
+  readonly scopes: readonly string[];
+}
+
+export interface WorkloadToken {
+  readonly claims: WorkloadClaims;
+  /** Feed this to `actorFromService()` — the same funnel every other credential goes through. */
+  readonly identity: ServiceIdentity;
+}
+
+export interface VerifyWorkloadTokenInput {
+  readonly token: string;
+  /** Every issuer this caller may claim. A list, never a wildcard: an unpinned `iss` is no check. */
+  readonly issuers: readonly string[];
+  /** This service's own audience. A token addressed elsewhere is a token being replayed here. */
+  readonly audience: string;
+  /** Required. There is no trusted-channel exemption for a token that arrived in a header. */
+  readonly keys: JwksKeySource;
+  readonly clock: Clock;
+  /** Optional tenant, when the deployment gives a workload one. Never guessed from the token. */
+  readonly orgId?: string | null | undefined;
+}
+
+const refused = (reason: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `the presented workload token was refused: ${reason}`,
+    // A service credential names no human, so a precise cause enumerates nothing — and the
+    // reader of this line is an operator holding a misconfigured deployment, not an attacker.
+    fix: "confirm the workload token's issuer, audience and key set match verifyWorkloadToken({ issuers, audience, keys })",
+  });
+
+const readScopes = (payload: Record<string, unknown>): readonly string[] => {
+  const scope = payload['scope'];
+  if (typeof scope === 'string') return scope.split(' ').filter((one) => one !== '');
+  const scp = payload['scp'];
+  return Array.isArray(scp) ? scp.filter((one): one is string => typeof one === 'string') : [];
+};
+
+const readAudience = (value: unknown): readonly string[] => {
+  if (typeof value === 'string') return [value];
+  return Array.isArray(value) ? value.filter((one): one is string => typeof one === 'string') : [];
+};
+
+/**
+ * Signature first, then issuer, audience and the two time bounds. The order matters for the same
+ * reason it does in `verifyIdToken`: a claim is only worth reading once something proved who
+ * wrote it, and every check below would otherwise pass for a token the caller minted themselves.
+ */
+export async function verifyWorkloadToken(input: VerifyWorkloadTokenInput): Promise<WorkloadToken> {
+  if (!(await verifyJwtSignature(input.token, input.keys))) {
+    throw refused('the signature does not verify against the published key set');
+  }
+
+  const payloadSegment = input.token.split('.')[1];
+  const parsed = payloadSegment === undefined ? null : decodeJwtSegment(payloadSegment);
+  if (parsed === null) {
+    throw refused('the payload is not base64url-encoded JSON describing an object');
+  }
+
+  const iss = parsed['iss'];
+  const sub = parsed['sub'];
+  const exp = parsed['exp'];
+  if (typeof iss !== 'string' || typeof sub !== 'string' || sub === '') {
+    throw refused('the payload carries no iss or sub');
+  }
+  if (typeof exp !== 'number') throw refused('the payload carries no numeric exp');
+  if (!input.issuers.includes(iss)) throw refused('the issuer is not one this service accepts');
+
+  const aud = readAudience(parsed['aud']);
+  if (!aud.includes(input.audience)) throw refused('the token is addressed to another audience');
+
+  const nowMs = input.clock.now().getTime();
+  // The same skew the id token path allows, from the same declaration: two servers rarely agree
+  // on the second, and a second number here would drift from that one.
+  if (exp * 1000 + ID_TOKEN_CLOCK_SKEW_MS <= nowMs) throw refused('the token is already expired');
+  const nbf = parsed['nbf'];
+  if (typeof nbf === 'number' && nbf * 1000 - ID_TOKEN_CLOCK_SKEW_MS > nowMs) {
+    throw refused('the token is not valid yet');
+  }
+  const iat = parsed['iat'];
+
+  const claims: WorkloadClaims = {
+    iss,
+    sub,
+    aud,
+    exp,
+    scopes: readScopes(parsed),
+    ...(typeof nbf === 'number' ? { nbf } : {}),
+    ...(typeof iat === 'number' ? { iat } : {}),
+  };
+  return {
+    claims,
+    identity: {
+      // The SPIFFE ID, the service account's `system:serviceaccount:ns:name`, or the IMDS
+      // principal — whichever the issuer put there. Never rewritten, so a trace names the caller.
+      id: claims.sub,
+      scopes: claims.scopes,
+      ...(input.orgId === undefined ? {} : { orgId: input.orgId }),
+    },
+  };
+}