@ultimat3/auth 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -210,6 +210,23 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `mfa.issuer` is the half that stayed, and it now has a reader: `enrolTotp(auth, { account })`
   takes the `Auth` every other entry point takes, so the product name an authenticator app shows
   is declared once at `defineAuth` instead of restated at every enrolment.
+- **A TOTP secret that decodes to zero bytes is not a weak key, it is NO key** (`As of 2026-08`).
+  `base32Decode` answers `new Uint8Array(0)` for any character outside the alphabet and for `''`,
+  and `new Bun.CryptoHasher('sha1', new Uint8Array(0))` is a perfectly valid HMAC — so `totpCode`
+  returned a six-digit code derived from nothing, every malformed secret in the table shared that
+  one stream, and `verifyTotp` accepted a code an attacker computes without knowing any secret.
+  Reachable: `enrolTotp(auth, { account, secret })` takes an imported secret, `builtin-adapter.ts`
+  maps the column straight through, and a `mfa_secret text not null default ''` column is not
+  `null`, so `login()` still demanded a second factor and then accepted the empty-key code. The
+  file's own header comment asserted the opposite ("fails the decode closed") for as long as it was
+  wrong. Three answers now, one per caller: `verifyTotp` returns `{ ok: false, step: null }` — the
+  **generic failure**, the same rule `verifyAgainst` follows for a stored hash Bun cannot read, so
+  a broken row is neither a 500 nor an oracle; `totpCode` throws `X_MFA_SECRET_INVALID`, because
+  there is no code an unreadable secret is entitled to; `enrolTotp` throws it too, so the value
+  never reaches the table. The secret never reaches `cause:` or `fix:` — it is a credential and
+  both are logged. No minimum LENGTH is enforced beyond one byte: 10-byte secrets are what several
+  authenticator apps issue, so a 16-byte floor would refuse real enrolments to close nothing the
+  zero-byte rule leaves open.
 - **`createTotpReplayGuard`'s table is bounded, and the eviction ORDER is the guarantee.** It
   pruned steps inside one subject's `Set` and never revisited a subject who stopped signing in, so
   the map carried one permanent entry per user for the life of the process. Evicting a subject

package/README.md

@@ -244,7 +244,20 @@ export function secondFactorHolds(userId: string, secret: string, code: string):
 | `createTotpReplayGuard(drift?, maxSubjects?)` | the in-process `{ isUsed, remember, size }`; a fleet passes a Redis-backed pair of the same two methods |
 | `generateRecoveryCodes(count = 10)` | `{ codes, hashes }`. `codes` is shown once and is never re-derivable |
 | `redeemRecoveryCode(code, hashes)` | the **remaining** hashes, or `null`. Persisting that array is what makes a code single-use |
-| `totpStep(at, stepSeconds?)` / `totpCode(secret, step, digits?)` | the RFC 6238 halves, for a test that has to mint a valid code |
+| `totpStep(at, stepSeconds?)` / `totpCode(secret, step, digits?)` | the RFC 6238 halves, for a test that has to mint a valid code. `totpCode` throws `X_MFA_SECRET_INVALID` on a secret that decodes to zero bytes |
+
+**A secret the decoder cannot read verifies nothing, `As of 2026-08`.** `base32Decode` answers
+zero bytes for any character outside the alphabet and for `''`, and an HMAC keyed with zero bytes
+is a valid HMAC — so `totpCode` used to hand back a six-digit code derived from no secret at all,
+one stream *every* malformed row in the table verified against, computable by anyone. Three
+answers now, and they differ because their callers do: `verifyTotp` returns `{ ok: false, step:
+null }` (a broken stored credential is the generic failure, the rule `verifyAgainst` follows for a
+hash Bun cannot read — never a throw into the login path, never an oracle); `totpCode` throws
+`X_MFA_SECRET_INVALID`, because there is no code an unreadable secret is entitled to; and
+`enrolTotp` throws the same code on an imported `secret`, so a value nothing can ever check never
+reaches the table. A minted secret is readable by construction. Note the direction of the failure:
+a `mfa_secret text not null default ''` column now locks that account out of its second factor
+instead of accepting a code nobody had to know — re-enrol it with `enrolTotp(auth, { account })`.
 
 `TOTP_DIGITS` (6), `TOTP_STEP_SECONDS` (30) and `TOTP_DRIFT_STEPS` (±1 window) are exported so an
 app's own copy of the parameters cannot disagree with the verifier's.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "3.0.0",
-    "@ultimat3/db": "3.0.0",
-    "@ultimat3/schema": "3.0.0"
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/db": "4.0.0",
+    "@ultimat3/schema": "4.0.0"
   }
 }

package/src/errors.ts

@@ -16,6 +16,7 @@ export const AUTH_OWNED_ERROR_CODES = [
   'X_UNAUTHENTICATED',
   'X_SESSION_EXPIRED',
   'X_MFA_REQUIRED',
+  'X_MFA_SECRET_INVALID',
   'X_OAUTH_STATE_INVALID',
   'X_OAUTH_EXCHANGE_FAILED',
   'X_OAUTH_TOKEN_INVALID',
@@ -60,6 +61,7 @@ export const AUTH_ERROR_TITLES: Readonly<Record<AuthOwnedErrorCode, string>> = {
   X_UNAUTHENTICATED: 'no authenticated actor for this request',
   X_SESSION_EXPIRED: 'session passed its idle or absolute expiry',
   X_MFA_REQUIRED: 'a second factor is required before this session is usable',
+  X_MFA_SECRET_INVALID: 'the totp secret is not base32, so it carries no key to check a code with',
   X_OAUTH_STATE_INVALID: 'oauth state, nonce or pkce verifier did not match',
   X_OAUTH_EXCHANGE_FAILED: 'the oauth provider refused the exchange or returned no usable identity',
   X_OAUTH_TOKEN_INVALID: 'id token failed its signature, issuer, audience or expiry check',
@@ -174,6 +176,26 @@ export const mfaRequired = (userId: string): AuthError =>
     meta: { userId },
   });
 
+/**
+ * A stored or imported TOTP secret the decoder cannot read. `base32Decode` answers zero bytes for
+ * any character outside the alphabet AND for `''`, and an HMAC keyed with zero bytes is a valid
+ * HMAC — so `totpCode` was handing out a six-digit code derived from no secret at all, one shared
+ * stream every malformed row in the table verified against. A code nobody had to know a secret to
+ * compute is not a second factor, so there is no code to hand back: this refuses instead.
+ *
+ * `verifyTotp` does NOT throw it. A login checking a broken row is the generic failure, exactly as
+ * `verifyAgainst` treats a stored hash Bun cannot read — a coded throw out of the verify path is a
+ * 500 where a credential refusal belongs, and it answers "this account's secret is malformed" to
+ * whoever asked. The secret itself never reaches `cause:` or `fix:`: it is a credential, and both
+ * are logged.
+ */
+export const mfaSecretInvalid = (surface: string): AuthError =>
+  new AuthError({
+    code: 'X_MFA_SECRET_INVALID',
+    cause: `${surface} was given a totp secret that is not RFC 4648 base32, so it decodes to zero bytes`,
+    fix: 'issue a fresh one and store it: const { secret } = enrolTotp(auth, { account: user.email }) — an imported secret must be base32 (A-Z and 2-7, padding, spaces and dashes ignored) and decode to at least one byte',
+  });
+
 /**
  * `defineAuth({ mfa: { required: true } })`, refused where it is declared. The option read as a
  * security guarantee — "this deployment requires a second factor" — and nothing in this package

package/src/id-token-fixture.ts

@@ -3,6 +3,7 @@
 // chances for one to drift from what `decodeIdToken` actually parses. Not part of the public
 // API — `index.ts` deliberately does not re-export it.
 
+import type { IdTokenClaims } from './id-token';
 import { base64Url } from './tokens';
 
 /** `base64Url` takes bytes because every real secret is bytes; a JWT segment is text. */
@@ -12,5 +13,8 @@ export const base64UrlText = (value: string): string => base64Url(new TextEncode
  * Header, payload, and a signature that is not one. Signatures are never checked here — the
  * token is only ever read straight off the token endpoint — so a fixture needs no signer.
  */
-export const unsignedJwt = (claims: Readonly<Record<string, unknown>>): string =>
+// The union, and not `Record<string, unknown>` alone: `IdTokenClaims` is an `interface`, so it has
+// no implicit index signature and the one shape this fixture exists to serialise was the one shape
+// it refused. The record arm stays for the malformed payloads `id-token.test.ts` builds by hand.
+export const unsignedJwt = (claims: IdTokenClaims | Readonly<Record<string, unknown>>): string =>
   `${base64UrlText('{"alg":"RS256"}')}.${base64UrlText(JSON.stringify(claims))}.signature`;

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   kdfOverloaded,
   mfaRequired,
   mfaRequiredUnenforceable,
+  mfaSecretInvalid,
   oauthAccountNotLinked,
   oauthDenied,
   oauthExchangeFailed,

package/src/mfa.ts

@@ -4,6 +4,7 @@
 // and single-use, so a database dump is not a permanent MFA bypass.
 
 import type { Auth } from './auth';
+import { mfaSecretInvalid } from './errors';
 import { randomBytes, sha256Hex, timingSafeEqual } from './tokens';
 
 const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
@@ -30,8 +31,16 @@ export function base32Encode(bytes: Uint8Array): string {
 }
 
 /**
- * Tolerant by design: padding, spaces and the dashes authenticator apps display are skipped,
- * and any other character fails the decode closed (empty output -> no code ever matches).
+ * Tolerant by design: padding, spaces and the dashes authenticator apps display are skipped, and
+ * any other character answers zero bytes.
+ *
+ * Zero bytes is NOT a decode that failed closed — this comment claimed it was, and it was the
+ * whole defect. An HMAC keyed with zero bytes is a perfectly valid HMAC, so `totpCode` derived a
+ * six-digit code from no secret at all and every unreadable secret in the table shared that one
+ * stream: a code an attacker computes without knowing anything verified against all of them.
+ * Zero bytes is therefore refused by both callers that need a key (`totpCode`, `enrolTotp`) and
+ * read as a non-verdict by `verifyTotp`. The decoder itself still answers rather than throwing,
+ * because "can this be read" is a question `enrolTotp` asks about a value it has not accepted yet.
  */
 export function base32Decode(value: string): Uint8Array {
   const bytes: number[] = [];
@@ -81,6 +90,10 @@ export interface EnrolTotpInput {
  */
 export function enrolTotp(auth: Auth, input: EnrolTotpInput): TotpEnrolment {
   const secret = input.secret ?? generateTotpSecret();
+  // Defence in depth, on the one path that puts a caller's own bytes in front of the table: a
+  // secret nothing can ever derive a code from is refused before it is written, not after a user
+  // is locked out by it. A minted secret is readable by construction, so only an import gets here.
+  if (base32Decode(secret).length === 0) throw mfaSecretInvalid('enrolTotp');
   const issuer = input.issuer ?? auth.mfa.issuer;
   const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(input.account)}`;
   const query = new URLSearchParams({
@@ -115,6 +128,10 @@ function counterBytes(step: number): Uint8Array {
 /** HMAC-SHA1 + RFC 4226 dynamic truncation. SHA1 here is a spec requirement, not a choice. */
 export function totpCode(secret: string, step: number, digits: number = TOTP_DIGITS): string {
   const key = base32Decode(secret);
+  // A zero-length key is not a weak key, it is no key: the hasher below accepts it and answers a
+  // code every other unreadable secret answers too. There is no code an unreadable secret is
+  // entitled to, so this returns none.
+  if (key.length === 0) throw mfaSecretInvalid('totpCode');
   const mac = Uint8Array.from(
     new Bun.CryptoHasher('sha1', key).update(counterBytes(step)).digest(),
   );
@@ -143,6 +160,12 @@ export interface VerifyTotpInput {
 }
 
 export function verifyTotp(input: VerifyTotpInput): TotpVerification {
+  // A non-verdict, not a verdict and not a throw. It is the rule `verifyAgainst` (`password.ts`)
+  // follows for a stored hash Bun cannot read: a broken stored credential is the generic failure,
+  // because a coded throw out of a verify path is a 500 where a refusal belongs and it answers
+  // "this account's secret is malformed" to whoever asked. It also keeps `totpCode`'s refusal off
+  // the login path entirely — nothing below can reach it with a zero-length key.
+  if (base32Decode(input.secret).length === 0) return { ok: false, step: null };
   const drift = input.drift ?? TOTP_DRIFT_STEPS;
   const current = totpStep(input.at);
   const candidate = input.code.replaceAll(' ', '');