@fonderie/auth 7.14.3 → 7.15.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/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

@@ -331,6 +331,12 @@ var EVENT_KEYS = {
 // 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 +347,7 @@ function issueMfaPendingToken(userId, config, loginMethod) {
       mfaPending: true
     },
     config.jwtSecret,
-    { expiresIn: "5m" }
+    { expiresIn: "5m", keyid: keyIdOf(config.jwtSecret) }
   );
 }
 function issueTokenPair(userId, config, options) {
@@ -353,12 +359,12 @@ function issueTokenPair(userId, config, options) {
   const accessToken = import_jsonwebtoken.default.sign(
     { sub: userId, type: "access", loginMethod, phoneVerified, sid },
     config.jwtSecret,
-    { expiresIn: accessDuration }
+    { expiresIn: accessDuration, keyid: keyIdOf(config.jwtSecret) }
   );
   const refreshToken = import_jsonwebtoken.default.sign(
     { sub: userId, type: "refresh", loginMethod, phoneVerified, sid },
     config.jwtSecret,
-    { expiresIn: duration }
+    { expiresIn: duration, keyid: keyIdOf(config.jwtSecret) }
   );
   return { accessToken, refreshToken, sid };
 }
@@ -367,11 +373,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
@@ -3271,6 +3282,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 +3579,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.3";
+  version = "7.15.0";
   // Users, sessions, login history, suspend — only through @fonderie/admin.
   describeAdmin() {
     return { routes: describeAuthAdminRoutes(this.store) };