@fonderie/auth 7.14.4 → 7.16.0

package/README.md

@@ -68,6 +68,26 @@ request; its output is sanitized and bounded (coordinates ~1 km); if it throws o
 and the request is unaffected. Country is reliable; region and city are
 approximate.
 
+## Rotating the signing secret (nobody is signed out)
+
+Every token carries the key id of the secret that signed it, and tokens are
+verified against the current secret **and** any previous ones:
+
+```ts
+new AuthModule(store, {
+  jwtSecret: process.env.JWT_SECRET!,                                   // signs new tokens
+  jwtPreviousSecrets: process.env.JWT_PREVIOUS_SECRETS?.split(',') ?? [], // still verify
+});
+```
+
+1. Put the current secret in `JWT_PREVIOUS_SECRETS` and a new one in `JWT_SECRET`; deploy.
+2. Signed-in users keep working; their next refresh gets tokens signed with the new key.
+3. After the longest session lifetime (`sessionDuration`), remove the old secret from
+   `JWT_PREVIOUS_SECRETS` and deploy again.
+
+A weak previous secret fails readiness like a weak current one: it still verifies tokens.
+See `docs/SESSION-DESIGN.md` for the session roadmap.
+
 ## Why this exists
 
 You've shipped this plumbing before — auth, teams, billing, messaging —

package/brain/outcomes.md

@@ -95,6 +95,9 @@ expires_at               TIMESTAMPTZ NOT NULL
 created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
 sid                      UUID
 location                 JSONB
+previous_token_hash      TEXT
+previous_valid_until     TIMESTAMPTZ
+last_used_at             TIMESTAMPTZ
 -- INDEX idx_fonderie_sessions_expires_at (expires_at)
 -- INDEX idx_fonderie_sessions_sid (sid)
 ```

package/brain/signatures.md

@@ -73,6 +73,7 @@ interface IAuthConfig extends IAuthSecrets, IAuthRuntimeConfig {
 
 interface IAuthSecrets {
     jwtSecret: string;
+    jwtPreviousSecrets?: string[];
     mfaSecretKey?: string;
     google?: {
         clientId: string;

package/dist/index.cjs

@@ -325,12 +325,21 @@ var EVENT_KEYS = {
   // Emitted by purgeSoftDeletedUsers (given a bus) once the row is hard-deleted.
   userPurged: "fonderie.user.purged",
   emailVerified: "fonderie.user.email_verified",
-  passwordChanged: "fonderie.user.password_changed"
+  passwordChanged: "fonderie.user.password_changed",
+  // A session the server revoked — today: a refresh token reused after its
+  // grace (theft signal). { userId, sessionId, reason }.
+  sessionRevoked: "fonderie.session.revoked"
 };
 
 // src/services/jwt.ts
 var import_node_crypto = require("crypto");
 var import_jsonwebtoken = __toESM(require("jsonwebtoken"), 1);
+function keyIdOf(secret) {
+  return (0, import_node_crypto.createHash)("sha256").update(secret).digest("hex").slice(0, 16);
+}
+function keyRing(config) {
+  return [config.jwtSecret, ...config.jwtPreviousSecrets ?? []].filter((s) => typeof s === "string" && s.length > 0);
+}
 function issueMfaPendingToken(userId, config, loginMethod) {
   return import_jsonwebtoken.default.sign(
     {
@@ -341,7 +350,7 @@ function issueMfaPendingToken(userId, config, loginMethod) {
       mfaPending: true
     },
     config.jwtSecret,
-    { expiresIn: "5m" }
+    { expiresIn: "5m", keyid: keyIdOf(config.jwtSecret) }
   );
 }
 function issueTokenPair(userId, config, options) {
@@ -349,16 +358,19 @@ function issueTokenPair(userId, config, options) {
   const accessDuration = config.accessTokenDuration ?? "24h";
   const loginMethod = options.loginMethod;
   const phoneVerified = options.phoneVerified ?? false;
-  const sid = (0, import_node_crypto.randomUUID)();
+  const sid = options.sid ?? (0, import_node_crypto.randomUUID)();
   const accessToken = import_jsonwebtoken.default.sign(
     { sub: userId, type: "access", loginMethod, phoneVerified, sid },
     config.jwtSecret,
-    { expiresIn: accessDuration }
+    // jwtid: every token is unique. With the session id kept across rotations,
+    // two tokens issued in the same second would otherwise be byte-identical —
+    // and a rotated-away token indistinguishable from the live one.
+    { expiresIn: accessDuration, keyid: keyIdOf(config.jwtSecret), jwtid: (0, import_node_crypto.randomUUID)() }
   );
   const refreshToken = import_jsonwebtoken.default.sign(
     { sub: userId, type: "refresh", loginMethod, phoneVerified, sid },
     config.jwtSecret,
-    { expiresIn: duration }
+    { expiresIn: duration, keyid: keyIdOf(config.jwtSecret), jwtid: (0, import_node_crypto.randomUUID)() }
   );
   return { accessToken, refreshToken, sid };
 }
@@ -367,11 +379,16 @@ function refreshTokenExpiry(token) {
   return decoded?.exp ? new Date(decoded.exp * 1e3) : new Date(Date.now() + 7 * 24 * 60 * 60 * 1e3);
 }
 function verifyToken(token, config) {
-  try {
-    return import_jsonwebtoken.default.verify(token, config.jwtSecret);
-  } catch {
-    return null;
+  const ring = keyRing(config);
+  const kid = import_jsonwebtoken.default.decode(token, { complete: true })?.header?.kid;
+  const candidates = typeof kid === "string" ? ring.filter((s) => keyIdOf(s) === kid) : ring;
+  for (const secret of candidates) {
+    try {
+      return import_jsonwebtoken.default.verify(token, secret);
+    } catch {
+    }
   }
+  return null;
 }
 
 // src/services/mfa.ts
@@ -897,6 +914,9 @@ var UserModel = class {
 };
 var MAX_LIST_LIMIT = 200;
 
+// src/models/session.model.ts
+var import_node_crypto4 = require("crypto");
+
 // src/services/request-location.ts
 var LOCATION_TIMEOUT_MS = 500;
 var TEXT_MAX = 128;
@@ -979,6 +999,10 @@ async function resolveOnce(resolver, req, timeoutMs) {
 }
 
 // src/models/session.model.ts
+function hashRefreshToken(token) {
+  return (0, import_node_crypto4.createHash)("sha256").update(token).digest("hex");
+}
+var REFRESH_GRACE_MS = 3e4;
 var SessionModel = class {
   // `locate` is IAuthConfig.location. Absent ⇒ sessions carry no location.
   constructor(store, locate) {
@@ -990,12 +1014,12 @@ var SessionModel = class {
   async create(userId, token, expiresAt, sid, meta) {
     const location = this.locate && meta?.headers ? await resolveLocation(this.locate, { ip: meta.ipAddress, headers: meta.headers }) : null;
     await this.store.query(
-      `INSERT INTO fonderie_sessions (user_id, token, expires_at, sid, user_agent, ip_address, location)
-			VALUES ($1, $2, $3, $4, $5, $6, $7)
+      `INSERT INTO fonderie_sessions (user_id, token, expires_at, sid, user_agent, ip_address, location, last_used_at)
+			VALUES ($1, $2, $3, $4, $5, $6, $7, now())
 			ON CONFLICT (token) DO NOTHING`,
       [
         userId,
-        token,
+        hashRefreshToken(token),
         expiresAt,
         sid ?? null,
         meta?.userAgent ?? null,
@@ -1005,7 +1029,56 @@ var SessionModel = class {
     );
   }
   async delete(token) {
-    await this.store.query(`DELETE FROM fonderie_sessions WHERE token = $1`, [token]);
+    await this.store.query(`DELETE FROM fonderie_sessions WHERE token IN ($1, $2)`, [hashRefreshToken(token), token]);
+  }
+  /**
+   * Where a presented refresh token stands: the session's current token, its
+   * previous one within the grace (a retry or race), its previous one AFTER
+   * the grace (reuse — a theft signal), or nothing known.
+   */
+  async match(token) {
+    const hash = hashRefreshToken(token);
+    const [current] = await this.store.query(
+      `SELECT id, user_id, sid, token FROM fonderie_sessions WHERE token IN ($1, $2) AND expires_at > now() LIMIT 1`,
+      [hash, token]
+    );
+    if (current) return { kind: "current", row: toRow(current) };
+    const [previous] = await this.store.query(
+      `SELECT id, user_id, sid, token, (previous_valid_until > now()) AS in_grace
+			   FROM fonderie_sessions WHERE previous_token_hash = $1 AND expires_at > now() LIMIT 1`,
+      [hash]
+    );
+    if (!previous) return { kind: "unknown" };
+    return { kind: previous.in_grace ? "grace" : "reused", row: toRow(previous) };
+  }
+  /**
+   * Rotate a session in place to a new refresh token: same row, same device.
+   * From the CURRENT token it is optimistic — only if the stored token is
+   * still the one matched; a concurrent rotation makes it return false and the
+   * caller re-matches (and now finds the token as the previous one). The old
+   * token becomes the previous, valid for the grace. From the PREVIOUS token
+   * (within the grace) it is authorised by that hash and deadline alone, so
+   * racing retries never starve; the previous and its deadline are kept.
+   */
+  async rotate(row, presented, next, from) {
+    const rows = await this.store.query(
+      `UPDATE fonderie_sessions
+			    SET previous_token_hash  = CASE WHEN $5 THEN $6 ELSE previous_token_hash END,
+			        previous_valid_until = CASE WHEN $5 THEN now() + ($7 || ' milliseconds')::interval ELSE previous_valid_until END,
+			        token        = $3,
+			        expires_at   = $4,
+			        last_used_at = now()
+			  WHERE id = $1
+			    AND CASE WHEN $5 THEN token = $2
+			             ELSE previous_token_hash = $6 AND previous_valid_until > now() END
+			RETURNING id`,
+      [row.id, row.stored, hashRefreshToken(next.token), next.expiresAt, from === "current", hashRefreshToken(presented), String(REFRESH_GRACE_MS)]
+    );
+    return rows.length === 1;
+  }
+  /** Revoke one session by its row id (any user) — reuse detection, admin. */
+  async revokeById(id) {
+    await this.store.query(`DELETE FROM fonderie_sessions WHERE id = $1`, [id]);
   }
   // Delete the session an access token is bound to (by its sid claim). Lets
   // logout revoke the current session without the client resending the refresh
@@ -1071,8 +1144,8 @@ var SessionModel = class {
   }
   async exists(token) {
     const rows = await this.store.query(
-      `SELECT id FROM fonderie_sessions WHERE token = $1 AND expires_at > now()`,
-      [token]
+      `SELECT id FROM fonderie_sessions WHERE token IN ($1, $2) AND expires_at > now()`,
+      [hashRefreshToken(token), token]
     );
     return rows.length > 0;
   }
@@ -1085,6 +1158,9 @@ var SessionModel = class {
     return rows.length > 0;
   }
 };
+function toRow(r) {
+  return { id: r.id, userId: r.user_id, sid: r.sid, stored: r.token };
+}
 
 // src/models/backup-code.model.ts
 var BackupCodeModel = class {
@@ -1419,7 +1495,7 @@ function mfaController(store, config, issuer, bus) {
 }
 
 // src/controllers/auth.controller.ts
-var import_node_crypto5 = require("crypto");
+var import_node_crypto6 = require("crypto");
 var import_events2 = require("@fonderie/events");
 var import_core6 = require("@fonderie/core");
 
@@ -1466,8 +1542,8 @@ function normalizeEmailSafe(email2) {
 }
 
 // src/models/password-reset.model.ts
-var import_node_crypto4 = require("crypto");
-var hashSecret = (value) => (0, import_node_crypto4.createHash)("sha256").update(value).digest("hex");
+var import_node_crypto5 = require("crypto");
+var hashSecret = (value) => (0, import_node_crypto5.createHash)("sha256").update(value).digest("hex");
 var PasswordResetModel = class {
   constructor(store) {
     this.store = store;
@@ -1661,7 +1737,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
         if (!row) {
           return (0, import_core6.setApiResponse)(import_core6.HTTP.SERVER_ERROR, "SERVER_ERROR", "Registration failed");
         }
-        const pin = (0, import_node_crypto5.randomInt)(1e5, 1e6).toString();
+        const pin = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
         const expiresAt = new Date(Date.now() + 1e3 * 60 * 60 * 24);
         await emailVerif.create(row.id, pin, expiresAt);
         const user = await users.findById(row.id);
@@ -1732,7 +1808,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
           lastName ?? null,
           locale
         );
-        const otp = (0, import_node_crypto5.randomInt)(1e5, 1e6).toString();
+        const otp = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
         const expiresAt = new Date(Date.now() + OTP_TTL_MS);
         await phoneVerif.upsert(id, normalizePhone(phone2), otp, expiresAt);
         const user = await users.findById(id);
@@ -1876,7 +1952,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
             "Account suspended. Please contact support."
           );
         }
-        const otp = (0, import_node_crypto5.randomInt)(1e5, 1e6).toString();
+        const otp = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
         const expiresAt = new Date(Date.now() + OTP_TTL_MS);
         await phoneVerif.upsert(user.id, normalizePhone(phone2), otp, expiresAt);
         await (0, import_core6.background)(bus?.emit(import_events2.NOTIFICATION_EVENT, {
@@ -1927,24 +2003,35 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
       if (!payload || payload.type !== "refresh") {
         return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "TOKEN_REFRESH_FAILED", "Invalid refresh token");
       }
-      const valid = await sessions.exists(token);
-      if (!valid) {
-        return (0, import_core6.setApiResponse)(
-          import_core6.HTTP.UNAUTHORIZED,
-          "TOKEN_REFRESH_FAILED",
-          "Session expired or already revoked"
-        );
+      let issued = null;
+      for (let attempt = 0; attempt < 3 && !issued; attempt++) {
+        const found = await sessions.match(token);
+        if (found.kind === "unknown") {
+          return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "TOKEN_REFRESH_FAILED", "Session expired or already revoked");
+        }
+        if (found.kind === "reused") {
+          await sessions.revokeById(found.row.id);
+          await (0, import_core6.background)(
+            bus?.emit(EVENT_KEYS.sessionRevoked, { userId: found.row.userId, sessionId: found.row.id, reason: "refresh-reuse" })
+          );
+          return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "TOKEN_REFRESH_FAILED", "Session expired or already revoked");
+        }
+        const user = await users.findById(found.row.userId);
+        if (!user || user.suspended || user.deletedAt || user.id !== payload.sub) {
+          return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "UNAUTHORIZED", "Unauthorized");
+        }
+        const pair = issueTokenPair(user.id, config, {
+          loginMethod: payload.loginMethod ?? "email",
+          phoneVerified: payload.phoneVerified ?? false,
+          ...found.row.sid ? { sid: found.row.sid } : {}
+        });
+        const next = { token: pair.refreshToken, expiresAt: refreshTokenExpiry(pair.refreshToken) };
+        if (await sessions.rotate(found.row, token, next, found.kind)) issued = pair;
       }
-      const user = await users.findById(payload.sub);
-      if (!user || user.suspended || user.deletedAt) {
-        return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "UNAUTHORIZED", "Unauthorized");
+      if (!issued) {
+        return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "TOKEN_REFRESH_FAILED", "Session expired or already revoked");
       }
-      await sessions.delete(token);
-      const { accessToken, refreshToken, sid } = issueTokenPair(user.id, config, {
-        loginMethod: payload.loginMethod ?? "email",
-        phoneVerified: payload.phoneVerified ?? false
-      });
-      await sessions.create(user.id, refreshToken, refreshTokenExpiry(refreshToken), sid, requestMeta(ctx));
+      const { accessToken, refreshToken } = issued;
       return Response.json(
         {
           reason: "TOKENS_REFRESHED",
@@ -1985,8 +2072,8 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
           "Password reset email sent (if account exists)."
         );
       }
-      const pin = (0, import_node_crypto5.randomInt)(1e5, 1e6).toString();
-      const token = (0, import_node_crypto5.randomBytes)(32).toString("hex");
+      const pin = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
+      const token = (0, import_node_crypto6.randomBytes)(32).toString("hex");
       const expiresAt = new Date(Date.now() + 1e3 * 60 * 60);
       await passwordReset.create(user.id, pin, token, expiresAt);
       const base = resolved.passwordResetUrl;
@@ -2192,7 +2279,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
             }
           );
         }
-        const otp = (0, import_node_crypto5.randomInt)(1e5, 1e6).toString();
+        const otp = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
         const expiresAt2 = new Date(Date.now() + OTP_TTL_MS);
         await phoneVerif.upsert(ctx.user.id, phone2, otp, expiresAt2);
         await (0, import_core6.background)(bus?.emit(import_events2.NOTIFICATION_EVENT, {
@@ -2231,7 +2318,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
           }
         );
       }
-      const pin = (0, import_node_crypto5.randomInt)(1e5, 1e6).toString();
+      const pin = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
       const expiresAt = new Date(Date.now() + 1e3 * 60 * 60 * 24);
       await emailVerif.replace(ctx.user.id, pin, expiresAt);
       await (0, import_core6.background)(bus?.emit(import_events2.NOTIFICATION_EVENT, {
@@ -2248,7 +2335,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
 }
 
 // src/controllers/user.controller.ts
-var import_node_crypto6 = require("crypto");
+var import_node_crypto7 = require("crypto");
 var import_core8 = require("@fonderie/core");
 var import_events3 = require("@fonderie/events");
 
@@ -2442,7 +2529,7 @@ function userController(store, config, bus) {
       if (existing) {
         return (0, import_core8.setApiResponse)(import_core8.HTTP.CONFLICT, "EMAIL_IN_USE", "Email already in use");
       }
-      const pin = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
+      const pin = (0, import_node_crypto7.randomInt)(1e5, 1e6).toString();
       const expiresAt = new Date(Date.now() + 1e3 * 60 * 60 * 24);
       await emailVerif.replace(ctx.user.id, pin, expiresAt);
       await users.updateEmail(ctx.user.id, normalised);
@@ -2484,7 +2571,7 @@ function userController(store, config, bus) {
       if (existing) {
         return (0, import_core8.setApiResponse)(import_core8.HTTP.CONFLICT, "PHONE_IN_USE", "Phone number already in use");
       }
-      const otp = (0, import_node_crypto6.randomInt)(1e5, 1e6).toString();
+      const otp = (0, import_node_crypto7.randomInt)(1e5, 1e6).toString();
       const expiresAt = new Date(Date.now() + 10 * 60 * 1e3);
       await phoneVerif.upsert(ctx.user.id, normalised, otp, expiresAt);
       await users.updatePhone(ctx.user.id, normalised);
@@ -2634,7 +2721,7 @@ function userController(store, config, bus) {
 }
 
 // src/controllers/oauth.controller.ts
-var import_node_crypto7 = require("crypto");
+var import_node_crypto8 = require("crypto");
 var import_jsonwebtoken2 = __toESM(require("jsonwebtoken"), 1);
 var import_core9 = require("@fonderie/core");
 var import_events4 = require("@fonderie/events");
@@ -2709,7 +2796,7 @@ async function getApplePublicKey(kid) {
   }
   if (!jwk) return null;
   try {
-    return (0, import_node_crypto7.createPublicKey)({ key: jwk, format: "jwk" });
+    return (0, import_node_crypto8.createPublicKey)({ key: jwk, format: "jwk" });
   } catch {
     return null;
   }
@@ -2867,7 +2954,7 @@ function oauthController(store, config, bus) {
           "Google OAuth not configured"
         );
       }
-      const state = (0, import_node_crypto7.randomBytes)(16).toString("hex");
+      const state = (0, import_node_crypto8.randomBytes)(16).toString("hex");
       const params = new URLSearchParams({
         client_id: google.clientId,
         redirect_uri: google.redirectUri,
@@ -3015,7 +3102,7 @@ function oauthController(store, config, bus) {
       if (!apple) {
         return (0, import_core9.setApiResponse)(import_core9.HTTP.NOT_IMPLEMENTED, "NOT_CONFIGURED", "Apple OAuth not configured");
       }
-      const state = (0, import_node_crypto7.randomBytes)(16).toString("hex");
+      const state = (0, import_node_crypto8.randomBytes)(16).toString("hex");
       const params = new URLSearchParams({
         client_id: apple.clientId,
         redirect_uri: apple.redirectUri,
@@ -3111,7 +3198,7 @@ function oauthController(store, config, bus) {
         });
         return (0, import_core9.setApiResponse)(import_core9.HTTP.UNAUTHORIZED, "APPLE_AUTH_FAILED", "Invalid Apple identity token");
       }
-      const tokenHash = (0, import_node_crypto7.createHash)("sha256").update(identityToken).digest("hex");
+      const tokenHash = (0, import_node_crypto8.createHash)("sha256").update(identityToken).digest("hex");
       const expMs = typeof claims.exp === "number" ? claims.exp * 1e3 : Date.now() + 5 * 60 * 1e3;
       const firstUse = await consumedTokens.consumeOnce(tokenHash, new Date(expMs));
       if (!firstUse) {
@@ -3271,6 +3358,18 @@ function collectAuthConfigProblems(config) {
       reason: "JWT_SECRET_PLACEHOLDER"
     });
   }
+  (config.jwtPreviousSecrets ?? []).forEach((previous, index) => {
+    if ((0, import_core11.secretStrengthProblem)(previous ?? "")) {
+      problems.push({
+        module: MODULE,
+        severity: "error",
+        message: `jwtPreviousSecrets[${index}] is too short or a placeholder \u2014 it still verifies tokens`,
+        domain: "auth",
+        reason: "JWT_PREVIOUS_SECRET_WEAK",
+        metadata: { index }
+      });
+    }
+  });
   if (config.secureCookies === false) {
     problems.push({
       module: MODULE,
@@ -3556,7 +3655,7 @@ var AuthModule = class {
   name = "@fonderie/auth";
   // Baked in at build time by tsup.base, so the operator's Modules page can
   // say what is actually deployed rather than 'not reported'.
-  version = "7.14.4";
+  version = "7.16.0";
   // Users, sessions, login history, suspend — only through @fonderie/admin.
   describeAdmin() {
     return { routes: describeAuthAdminRoutes(this.store) };