@open-mercato/shared 0.6.8-develop.6944.1.eef6a0ee1d → 0.6.8-develop.6948.1.8369fc4c97

package/dist/lib/auth/jwt.js

@@ -1,18 +1,97 @@
 import crypto from "node:crypto";
+import { createLogger } from "../logger/index.js";
+import { parseNumberWithDefault } from "../number.js";
+const logger = createLogger("auth").child({ component: "jwt" });
 function base64url(input) {
   return (typeof input === "string" ? Buffer.from(input) : input).toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
 }
 const DEFAULT_ISSUER = "open-mercato";
 const DEFAULT_STAFF_AUDIENCE = "staff";
 const AUDIENCE_SECRET_LABEL = "open-mercato:jwt:v1";
-function getLegacyGraceEnabled() {
+const LEGACY_GRACE_DEFAULT_MINUTES = 480;
+const LEGACY_TOKEN_CLOCK_SKEW_SECONDS = 60;
+function getLegacyGraceMinutes() {
   const raw = process.env.JWT_LEGACY_GRACE_MINUTES;
-  if (raw === "0" || raw === "false" || raw === "off") return false;
-  return true;
+  const normalized = typeof raw === "string" ? raw.trim().toLowerCase() : raw;
+  if (normalized === "false" || normalized === "off") return 0;
+  return parseNumberWithDefault(normalized, LEGACY_GRACE_DEFAULT_MINUTES, { min: 0, integer: true });
+}
+function getLegacyCutoverEpochSeconds() {
+  const raw = process.env.JWT_LEGACY_CUTOVER_AT;
+  if (!raw || !raw.trim()) return null;
+  const parsed = Date.parse(raw.trim());
+  if (Number.isNaN(parsed)) {
+    warnOnce(
+      "jwt-legacy-cutover-unparseable",
+      "JWT_LEGACY_CUTOVER_AT is not a valid ISO-8601 instant \u2014 legacy JWT fallback remains disabled."
+    );
+    return null;
+  }
+  return Math.floor(parsed / 1e3);
+}
+const MIN_SECRET_LENGTH = 32;
+const PLACEHOLDER_SECRETS = /* @__PURE__ */ new Set([
+  "jwt",
+  "jwt-secret",
+  "jwtsecret",
+  "secret",
+  "password",
+  "changeme",
+  "change-me",
+  "change-me-dev-secret",
+  "change-me-dev-auth-secret",
+  "your-strong-jwt-secret",
+  "your-secure-jwt-secret-change-me",
+  "dev",
+  "development",
+  "test"
+]);
+const warnedKeys = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+  if (warnedKeys.has(key)) return;
+  warnedKeys.add(key);
+  logger.warn(message);
+}
+function isProduction() {
+  return process.env.NODE_ENV === "production";
+}
+function inspectSecret(secret) {
+  const value = typeof secret === "string" ? secret.trim() : "";
+  if (!value) return "missing";
+  if (PLACEHOLDER_SECRETS.has(value.toLowerCase())) return "placeholder";
+  if (value.length < MIN_SECRET_LENGTH) return "too_short";
+  return null;
+}
+function describeViolation(name, violation) {
+  switch (violation) {
+    case "missing":
+      return `${name} is not set. Generate one with \`openssl rand -hex 32\`.`;
+    case "placeholder":
+      return `${name} is set to a placeholder value published in this repository's examples, so anyone can forge tokens for this deployment. Generate a real one with \`openssl rand -hex 32\`.`;
+    case "too_short":
+      return `${name} is shorter than ${MIN_SECRET_LENGTH} characters. Generate a stronger one with \`openssl rand -hex 32\`.`;
+  }
+}
+function enforceSecretPolicy(name, secret) {
+  const violation = inspectSecret(secret);
+  if (!violation) return;
+  const message = describeViolation(name, violation);
+  if (isProduction()) {
+    throw new Error(`[auth.jwt] Refusing to run in production with an unsafe signing secret: ${message}`);
+  }
+  warnOnce(`secret-policy:${name}:${violation}`, `${message} This is tolerated outside production only.`);
+}
+function assertJwtSecretPolicy() {
+  enforceSecretPolicy("JWT_SECRET", process.env.JWT_SECRET);
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!/^JWT_[A-Z0-9]+(?:_[A-Z0-9]+)*_SECRET$/.test(key)) continue;
+    enforceSecretPolicy(key, value);
+  }
 }
 function readBaseSecret(explicit) {
   const secret = explicit ?? process.env.JWT_SECRET;
   if (!secret) throw new Error("JWT_SECRET is not set");
+  if (explicit === void 0) enforceSecretPolicy("JWT_SECRET", secret);
   return secret;
 }
 function normalizeAudience(audience) {
@@ -33,7 +112,10 @@ function deriveJwtAudienceSecret(audience, baseSecret) {
   if (!normalized) throw new Error("Audience is required to derive a JWT secret");
   const overrideName = `JWT_${normalized.toUpperCase()}_SECRET`;
   const override = process.env[overrideName];
-  if (override && override.trim().length > 0) return override;
+  if (override && override.trim().length > 0) {
+    enforceSecretPolicy(overrideName, override);
+    return override;
+  }
   const base = readBaseSecret(baseSecret);
   return deriveAudienceSecretFromBase(normalized, base);
 }
@@ -130,15 +212,28 @@ function verifyWithOptions(token, options) {
   }
   return payload;
 }
+function isWithinLegacyWindow(payload, graceMinutes) {
+  const cutoverAt = getLegacyCutoverEpochSeconds();
+  const now = Math.floor(Date.now() / 1e3);
+  if (cutoverAt === null || now >= cutoverAt) return false;
+  const issuedAt = payload.iat;
+  if (typeof issuedAt !== "number" || !Number.isFinite(issuedAt)) return false;
+  if (issuedAt > now + LEGACY_TOKEN_CLOCK_SKEW_SECONDS) return false;
+  return now - issuedAt <= graceMinutes * 60;
+}
 function verifyJwt(token, secretOrOptions) {
   const options = toVerifyOptions(secretOrOptions);
   const result = verifyWithOptions(token, options);
-  if (result) return result;
-  if (secretOrOptions === void 0 && getLegacyGraceEnabled()) {
+  if (result) {
+    if (result._legacyToken !== void 0) delete result._legacyToken;
+    return result;
+  }
+  if (secretOrOptions === void 0) {
+    const graceMinutes = getLegacyGraceMinutes();
     const rawSecret = process.env.JWT_SECRET;
-    if (rawSecret) {
+    if (graceMinutes > 0 && rawSecret) {
       const legacyResult = verifyWithOptions(token, { secret: rawSecret });
-      if (legacyResult) {
+      if (legacyResult && isWithinLegacyWindow(legacyResult, graceMinutes)) {
         legacyResult._legacyToken = true;
         return legacyResult;
       }
@@ -153,6 +248,7 @@ function verifyAudienceJwt(audience, token) {
   return verifyJwt(token, { audience });
 }
 export {
+  assertJwtSecretPolicy,
   deriveJwtAudienceSecret,
   signAudienceJwt,
   signJwt,

package/dist/lib/auth/jwt.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/auth/jwt.ts"],
-  "sourcesContent": ["import crypto from 'node:crypto'\n\nfunction base64url(input: Buffer | string) {\n  return (typeof input === 'string' ? Buffer.from(input) : input)\n    .toString('base64')\n    .replace(/=/g, '')\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n}\n\nexport type JwtPayload = Record<string, any>\n\nexport type JwtAudience = 'staff' | 'customer' | (string & {})\n\nexport type SignJwtOptions = {\n  secret?: string\n  expiresInSec?: number\n  audience?: string\n  issuer?: string\n}\n\nexport type VerifyJwtOptions = {\n  secret?: string\n  audience?: string\n  issuer?: string\n}\n\nconst DEFAULT_ISSUER = 'open-mercato'\nconst DEFAULT_STAFF_AUDIENCE: JwtAudience = 'staff'\nconst AUDIENCE_SECRET_LABEL = 'open-mercato:jwt:v1'\n\n/**\n * When set to a positive number (minutes), `verifyJwt` will attempt a legacy fallback using the\n * raw `JWT_SECRET` when the audience-derived verification fails. This supports rolling deployments\n * and lets existing sessions expire gracefully instead of force-logging-out every user on deploy.\n *\n * Set via `JWT_LEGACY_GRACE_MINUTES` env var. Defaults to 480 (8 hours \u2014 one full token TTL).\n * Set to 0 to disable the fallback (hard cutover).\n */\nfunction getLegacyGraceEnabled(): boolean {\n  const raw = process.env.JWT_LEGACY_GRACE_MINUTES\n  if (raw === '0' || raw === 'false' || raw === 'off') return false\n  return true\n}\n\nfunction readBaseSecret(explicit?: string): string {\n  const secret = explicit ?? process.env.JWT_SECRET\n  if (!secret) throw new Error('JWT_SECRET is not set')\n  return secret\n}\n\nfunction normalizeAudience(audience: string): string {\n  return audience.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_')\n}\n\nconst derivedSecretCache = new Map<string, string>()\n\nfunction deriveAudienceSecretFromBase(normalized: string, base: string): string {\n  const cacheKey = `${normalized}::${base}`\n  const cached = derivedSecretCache.get(cacheKey)\n  if (cached !== undefined) return cached\n  const label = `${AUDIENCE_SECRET_LABEL}:${normalized}`\n  const derived = crypto.createHmac('sha256', base).update(label).digest('hex')\n  derivedSecretCache.set(cacheKey, derived)\n  return derived\n}\n\n/**\n * Derive a per-audience signing key from the base `JWT_SECRET`.\n *\n * - If `JWT_${AUDIENCE}_SECRET` env var is set, it is used verbatim (allows operators to rotate a\n *   single audience independently).\n * - Otherwise, the key is derived deterministically via HMAC-SHA256 from the base secret using a\n *   versioned label. This ensures that a staff JWT signature cannot verify against the customer\n *   key (and vice versa) even though both share the same base `JWT_SECRET`.\n * - Derived values are memoized per `(audience, baseSecret)` for the process lifetime.\n */\nexport function deriveJwtAudienceSecret(audience: string, baseSecret?: string): string {\n  const normalized = normalizeAudience(audience)\n  if (!normalized) throw new Error('Audience is required to derive a JWT secret')\n  const overrideName = `JWT_${normalized.toUpperCase()}_SECRET`\n  const override = process.env[overrideName]\n  if (override && override.trim().length > 0) return override\n  const base = readBaseSecret(baseSecret)\n  return deriveAudienceSecretFromBase(normalized, base)\n}\n\nfunction isSignOptions(value: string | SignJwtOptions | undefined): value is SignJwtOptions {\n  return typeof value === 'object' && value !== null\n}\n\nfunction isVerifyOptions(value: string | VerifyJwtOptions | undefined): value is VerifyJwtOptions {\n  return typeof value === 'object' && value !== null\n}\n\nfunction toSignOptions(secretOrOptions?: string | SignJwtOptions, expiresInSec?: number): { secret: string; expiresInSec: number; audience?: string; issuer?: string } {\n  if (isSignOptions(secretOrOptions)) {\n    const audience = secretOrOptions.audience ?? DEFAULT_STAFF_AUDIENCE\n    const secret = secretOrOptions.secret ?? deriveJwtAudienceSecret(audience)\n    if (!secret) throw new Error('JWT_SECRET is not set')\n    return {\n      secret,\n      expiresInSec: secretOrOptions.expiresInSec ?? 60 * 60 * 8,\n      audience,\n      issuer: secretOrOptions.issuer ?? DEFAULT_ISSUER,\n    }\n  }\n  if (typeof secretOrOptions === 'string') {\n    // Legacy: explicit raw secret supplied by caller \u2014 keep audience/issuer off by default so\n    // existing tests and callers that BYO secret see unchanged behavior.\n    if (!secretOrOptions) throw new Error('JWT_SECRET is not set')\n    return {\n      secret: secretOrOptions,\n      expiresInSec: expiresInSec ?? 60 * 60 * 8,\n    }\n  }\n  // Default path: staff-audience derived secret + iss/aud claims.\n  return {\n    secret: deriveJwtAudienceSecret(DEFAULT_STAFF_AUDIENCE),\n    expiresInSec: expiresInSec ?? 60 * 60 * 8,\n    audience: DEFAULT_STAFF_AUDIENCE,\n    issuer: DEFAULT_ISSUER,\n  }\n}\n\nfunction toVerifyOptions(secretOrOptions?: string | VerifyJwtOptions): { secret: string; audience?: string; issuer?: string } {\n  if (isVerifyOptions(secretOrOptions)) {\n    const audience = secretOrOptions.audience ?? DEFAULT_STAFF_AUDIENCE\n    const secret = secretOrOptions.secret ?? deriveJwtAudienceSecret(audience)\n    if (!secret) throw new Error('JWT_SECRET is not set')\n    return {\n      secret,\n      audience,\n      issuer: secretOrOptions.issuer ?? DEFAULT_ISSUER,\n    }\n  }\n  if (typeof secretOrOptions === 'string') {\n    if (!secretOrOptions) throw new Error('JWT_SECRET is not set')\n    // Legacy explicit secret: no audience/issuer enforcement.\n    return { secret: secretOrOptions }\n  }\n  return {\n    secret: deriveJwtAudienceSecret(DEFAULT_STAFF_AUDIENCE),\n    audience: DEFAULT_STAFF_AUDIENCE,\n    issuer: DEFAULT_ISSUER,\n  }\n}\n\nexport function signJwt(\n  payload: JwtPayload,\n  secretOrOptions?: string | SignJwtOptions,\n  expiresInSec?: number,\n) {\n  const options = toSignOptions(secretOrOptions, expiresInSec)\n  const header = { alg: 'HS256', typ: 'JWT' }\n  const now = Math.floor(Date.now() / 1000)\n  const body: JwtPayload = { iat: now, exp: now + options.expiresInSec, ...payload }\n  if (options.issuer && body.iss === undefined) body.iss = options.issuer\n  if (options.audience && body.aud === undefined) body.aud = options.audience\n  const encHeader = base64url(JSON.stringify(header))\n  const encBody = base64url(JSON.stringify(body))\n  const data = `${encHeader}.${encBody}`\n  const sig = crypto.createHmac('sha256', options.secret).update(data).digest()\n  const encSig = base64url(sig)\n  return `${data}.${encSig}`\n}\n\nfunction verifyWithOptions(token: string, options: { secret: string; audience?: string; issuer?: string }): JwtPayload | null {\n  const parts = token.split('.')\n  if (parts.length !== 3) return null\n  const [h, p, s] = parts\n  const data = `${h}.${p}`\n  const expected = base64url(crypto.createHmac('sha256', options.secret).update(data).digest())\n  const providedSignature = Buffer.from(s)\n  const expectedSignature = Buffer.from(expected)\n  if (providedSignature.length !== expectedSignature.length) return null\n  if (!crypto.timingSafeEqual(providedSignature, expectedSignature)) return null\n  let payload: JwtPayload\n  try {\n    payload = JSON.parse(Buffer.from(p, 'base64').toString('utf8'))\n  } catch {\n    return null\n  }\n  const now = Math.floor(Date.now() / 1000)\n  if (payload.exp && now > payload.exp) return null\n  if (options.audience !== undefined) {\n    if (payload.aud !== options.audience) return null\n  }\n  if (options.issuer !== undefined) {\n    if (payload.iss !== options.issuer) return null\n  }\n  return payload\n}\n\nexport function verifyJwt(token: string, secretOrOptions?: string | VerifyJwtOptions) {\n  const options = toVerifyOptions(secretOrOptions)\n  const result = verifyWithOptions(token, options)\n  if (result) return result\n\n  // Legacy fallback: when the caller used the default path (no explicit secret) and the new\n  // audience-derived verification failed, try verifying with the raw JWT_SECRET. This allows\n  // pre-migration tokens to remain valid during rolling deployments and graceful migration.\n  if (secretOrOptions === undefined && getLegacyGraceEnabled()) {\n    const rawSecret = process.env.JWT_SECRET\n    if (rawSecret) {\n      const legacyResult = verifyWithOptions(token, { secret: rawSecret })\n      if (legacyResult) {\n        legacyResult._legacyToken = true\n        return legacyResult\n      }\n    }\n  }\n\n  return null\n}\n\n/**\n * Sign a JWT for a specific audience using an audience-derived signing key. The resulting token\n * carries `iss` and `aud` claims and cannot be verified with the base `JWT_SECRET` directly \u2014\n * callers must use `verifyAudienceJwt` with the same audience.\n */\nexport function signAudienceJwt(\n  audience: string,\n  payload: JwtPayload,\n  expiresInSec: number = 60 * 60 * 8,\n): string {\n  return signJwt(payload, { audience, expiresInSec })\n}\n\n/**\n * Verify a JWT that was signed with an audience-scoped secret. Rejects tokens that are missing\n * or carry a mismatched `aud`/`iss` claim, so a staff JWT cannot be replayed against the\n * customer portal (and vice versa) even when the base `JWT_SECRET` is shared.\n */\nexport function verifyAudienceJwt(audience: string, token: string): JwtPayload | null {\n  return verifyJwt(token, { audience })\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import crypto from 'node:crypto'\nimport { createLogger } from '../logger'\nimport { parseNumberWithDefault } from '../number'\n\nconst logger = createLogger('auth').child({ component: 'jwt' })\n\nfunction base64url(input: Buffer | string) {\n  return (typeof input === 'string' ? Buffer.from(input) : input)\n    .toString('base64')\n    .replace(/=/g, '')\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n}\n\nexport type JwtPayload = Record<string, any>\n\nexport type JwtAudience = 'staff' | 'customer' | (string & {})\n\nexport type SignJwtOptions = {\n  secret?: string\n  expiresInSec?: number\n  audience?: string\n  issuer?: string\n}\n\nexport type VerifyJwtOptions = {\n  secret?: string\n  audience?: string\n  issuer?: string\n}\n\nconst DEFAULT_ISSUER = 'open-mercato'\nconst DEFAULT_STAFF_AUDIENCE: JwtAudience = 'staff'\nconst AUDIENCE_SECRET_LABEL = 'open-mercato:jwt:v1'\n\nconst LEGACY_GRACE_DEFAULT_MINUTES = 480\nconst LEGACY_TOKEN_CLOCK_SKEW_SECONDS = 60\n\n/**\n * How long after a token was issued (`iat`) the raw-`JWT_SECRET` fallback in `verifyJwt` keeps\n * accepting it. The fallback exists so a rolling deployment of the audience-derived signing\n * scheme does not force-log-out every user; it is a migration window, not a permanent mode.\n *\n * Set via `JWT_LEGACY_GRACE_MINUTES`. Defaults to 480 (8 hours \u2014 one full token TTL).\n * `0`, `false` or `off` disables the fallback entirely (hard cutover). Values that do not parse\n * fall back to the default rather than silently disabling authentication.\n */\nfunction getLegacyGraceMinutes(): number {\n  const raw = process.env.JWT_LEGACY_GRACE_MINUTES\n  const normalized = typeof raw === 'string' ? raw.trim().toLowerCase() : raw\n  if (normalized === 'false' || normalized === 'off') return 0\n  return parseNumberWithDefault(normalized, LEGACY_GRACE_DEFAULT_MINUTES, { min: 0, integer: true })\n}\n\n/**\n * Required absolute deadline for the legacy fallback, as an ISO-8601 instant in\n * `JWT_LEGACY_CUTOVER_AT`. Without a valid deadline the fallback stays disabled: token `iat` is\n * attacker-controlled by anyone who knows the former raw secret, so a relative age check alone\n * cannot make the migration window finite.\n */\nfunction getLegacyCutoverEpochSeconds(): number | null {\n  const raw = process.env.JWT_LEGACY_CUTOVER_AT\n  if (!raw || !raw.trim()) return null\n  const parsed = Date.parse(raw.trim())\n  if (Number.isNaN(parsed)) {\n    warnOnce(\n      'jwt-legacy-cutover-unparseable',\n      'JWT_LEGACY_CUTOVER_AT is not a valid ISO-8601 instant \u2014 legacy JWT fallback remains disabled.',\n    )\n    return null\n  }\n  return Math.floor(parsed / 1000)\n}\n\nconst MIN_SECRET_LENGTH = 32\n\n/**\n * Signing secrets that ship in this repository's own examples, compose files, and docs. A\n * deployment reaching production with one of these is not \"weakly configured\" \u2014 it is publicly\n * forgeable by anyone who has read the repository.\n */\nconst PLACEHOLDER_SECRETS = new Set([\n  'jwt',\n  'jwt-secret',\n  'jwtsecret',\n  'secret',\n  'password',\n  'changeme',\n  'change-me',\n  'change-me-dev-secret',\n  'change-me-dev-auth-secret',\n  'your-strong-jwt-secret',\n  'your-secure-jwt-secret-change-me',\n  'dev',\n  'development',\n  'test',\n])\n\nexport type JwtSecretViolation = 'missing' | 'placeholder' | 'too_short'\n\nconst warnedKeys = new Set<string>()\n\nfunction warnOnce(key: string, message: string): void {\n  if (warnedKeys.has(key)) return\n  warnedKeys.add(key)\n  logger.warn(message)\n}\n\nfunction isProduction(): boolean {\n  return process.env.NODE_ENV === 'production'\n}\n\nfunction inspectSecret(secret: string | undefined | null): JwtSecretViolation | null {\n  const value = typeof secret === 'string' ? secret.trim() : ''\n  if (!value) return 'missing'\n  if (PLACEHOLDER_SECRETS.has(value.toLowerCase())) return 'placeholder'\n  if (value.length < MIN_SECRET_LENGTH) return 'too_short'\n  return null\n}\n\nfunction describeViolation(name: string, violation: JwtSecretViolation): string {\n  switch (violation) {\n    case 'missing':\n      return `${name} is not set. Generate one with \\`openssl rand -hex 32\\`.`\n    case 'placeholder':\n      return `${name} is set to a placeholder value published in this repository's examples, so anyone can forge tokens for this deployment. Generate a real one with \\`openssl rand -hex 32\\`.`\n    case 'too_short':\n      return `${name} is shorter than ${MIN_SECRET_LENGTH} characters. Generate a stronger one with \\`openssl rand -hex 32\\`.`\n  }\n}\n\n/**\n * Fail closed in production, warn in every other environment. Called on every secret read so\n * worker, scheduler, and CLI processes \u2014 which never run the app's startup hook \u2014 are covered\n * too. `assertJwtSecretPolicy` runs the same check eagerly at server startup.\n */\nfunction enforceSecretPolicy(name: string, secret: string | undefined | null): void {\n  const violation = inspectSecret(secret)\n  if (!violation) return\n  const message = describeViolation(name, violation)\n  if (isProduction()) {\n    throw new Error(`[auth.jwt] Refusing to run in production with an unsafe signing secret: ${message}`)\n  }\n  warnOnce(`secret-policy:${name}:${violation}`, `${message} This is tolerated outside production only.`)\n}\n\n/**\n * Validate every JWT signing secret this process would use. Call it once at startup so a\n * misconfigured production deployment fails immediately and loudly instead of at the first login\n * attempt. Throws in production; logs a warning elsewhere.\n */\nexport function assertJwtSecretPolicy(): void {\n  enforceSecretPolicy('JWT_SECRET', process.env.JWT_SECRET)\n  for (const [key, value] of Object.entries(process.env)) {\n    if (!/^JWT_[A-Z0-9]+(?:_[A-Z0-9]+)*_SECRET$/.test(key)) continue\n    enforceSecretPolicy(key, value)\n  }\n}\n\nfunction readBaseSecret(explicit?: string): string {\n  const secret = explicit ?? process.env.JWT_SECRET\n  if (!secret) throw new Error('JWT_SECRET is not set')\n  if (explicit === undefined) enforceSecretPolicy('JWT_SECRET', secret)\n  return secret\n}\n\nfunction normalizeAudience(audience: string): string {\n  return audience.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_')\n}\n\nconst derivedSecretCache = new Map<string, string>()\n\nfunction deriveAudienceSecretFromBase(normalized: string, base: string): string {\n  const cacheKey = `${normalized}::${base}`\n  const cached = derivedSecretCache.get(cacheKey)\n  if (cached !== undefined) return cached\n  const label = `${AUDIENCE_SECRET_LABEL}:${normalized}`\n  const derived = crypto.createHmac('sha256', base).update(label).digest('hex')\n  derivedSecretCache.set(cacheKey, derived)\n  return derived\n}\n\n/**\n * Derive a per-audience signing key from the base `JWT_SECRET`.\n *\n * - If `JWT_${AUDIENCE}_SECRET` env var is set, it is used verbatim (allows operators to rotate a\n *   single audience independently).\n * - Otherwise, the key is derived deterministically via HMAC-SHA256 from the base secret using a\n *   versioned label. This ensures that a staff JWT signature cannot verify against the customer\n *   key (and vice versa) even though both share the same base `JWT_SECRET`.\n * - Derived values are memoized per `(audience, baseSecret)` for the process lifetime.\n */\nexport function deriveJwtAudienceSecret(audience: string, baseSecret?: string): string {\n  const normalized = normalizeAudience(audience)\n  if (!normalized) throw new Error('Audience is required to derive a JWT secret')\n  const overrideName = `JWT_${normalized.toUpperCase()}_SECRET`\n  const override = process.env[overrideName]\n  if (override && override.trim().length > 0) {\n    enforceSecretPolicy(overrideName, override)\n    return override\n  }\n  const base = readBaseSecret(baseSecret)\n  return deriveAudienceSecretFromBase(normalized, base)\n}\n\nfunction isSignOptions(value: string | SignJwtOptions | undefined): value is SignJwtOptions {\n  return typeof value === 'object' && value !== null\n}\n\nfunction isVerifyOptions(value: string | VerifyJwtOptions | undefined): value is VerifyJwtOptions {\n  return typeof value === 'object' && value !== null\n}\n\nfunction toSignOptions(secretOrOptions?: string | SignJwtOptions, expiresInSec?: number): { secret: string; expiresInSec: number; audience?: string; issuer?: string } {\n  if (isSignOptions(secretOrOptions)) {\n    const audience = secretOrOptions.audience ?? DEFAULT_STAFF_AUDIENCE\n    const secret = secretOrOptions.secret ?? deriveJwtAudienceSecret(audience)\n    if (!secret) throw new Error('JWT_SECRET is not set')\n    return {\n      secret,\n      expiresInSec: secretOrOptions.expiresInSec ?? 60 * 60 * 8,\n      audience,\n      issuer: secretOrOptions.issuer ?? DEFAULT_ISSUER,\n    }\n  }\n  if (typeof secretOrOptions === 'string') {\n    // Legacy: explicit raw secret supplied by caller \u2014 keep audience/issuer off by default so\n    // existing tests and callers that BYO secret see unchanged behavior.\n    if (!secretOrOptions) throw new Error('JWT_SECRET is not set')\n    return {\n      secret: secretOrOptions,\n      expiresInSec: expiresInSec ?? 60 * 60 * 8,\n    }\n  }\n  // Default path: staff-audience derived secret + iss/aud claims.\n  return {\n    secret: deriveJwtAudienceSecret(DEFAULT_STAFF_AUDIENCE),\n    expiresInSec: expiresInSec ?? 60 * 60 * 8,\n    audience: DEFAULT_STAFF_AUDIENCE,\n    issuer: DEFAULT_ISSUER,\n  }\n}\n\nfunction toVerifyOptions(secretOrOptions?: string | VerifyJwtOptions): { secret: string; audience?: string; issuer?: string } {\n  if (isVerifyOptions(secretOrOptions)) {\n    const audience = secretOrOptions.audience ?? DEFAULT_STAFF_AUDIENCE\n    const secret = secretOrOptions.secret ?? deriveJwtAudienceSecret(audience)\n    if (!secret) throw new Error('JWT_SECRET is not set')\n    return {\n      secret,\n      audience,\n      issuer: secretOrOptions.issuer ?? DEFAULT_ISSUER,\n    }\n  }\n  if (typeof secretOrOptions === 'string') {\n    if (!secretOrOptions) throw new Error('JWT_SECRET is not set')\n    // Legacy explicit secret: no audience/issuer enforcement.\n    return { secret: secretOrOptions }\n  }\n  return {\n    secret: deriveJwtAudienceSecret(DEFAULT_STAFF_AUDIENCE),\n    audience: DEFAULT_STAFF_AUDIENCE,\n    issuer: DEFAULT_ISSUER,\n  }\n}\n\nexport function signJwt(\n  payload: JwtPayload,\n  secretOrOptions?: string | SignJwtOptions,\n  expiresInSec?: number,\n) {\n  const options = toSignOptions(secretOrOptions, expiresInSec)\n  const header = { alg: 'HS256', typ: 'JWT' }\n  const now = Math.floor(Date.now() / 1000)\n  const body: JwtPayload = { iat: now, exp: now + options.expiresInSec, ...payload }\n  if (options.issuer && body.iss === undefined) body.iss = options.issuer\n  if (options.audience && body.aud === undefined) body.aud = options.audience\n  const encHeader = base64url(JSON.stringify(header))\n  const encBody = base64url(JSON.stringify(body))\n  const data = `${encHeader}.${encBody}`\n  const sig = crypto.createHmac('sha256', options.secret).update(data).digest()\n  const encSig = base64url(sig)\n  return `${data}.${encSig}`\n}\n\nfunction verifyWithOptions(token: string, options: { secret: string; audience?: string; issuer?: string }): JwtPayload | null {\n  const parts = token.split('.')\n  if (parts.length !== 3) return null\n  const [h, p, s] = parts\n  const data = `${h}.${p}`\n  const expected = base64url(crypto.createHmac('sha256', options.secret).update(data).digest())\n  const providedSignature = Buffer.from(s)\n  const expectedSignature = Buffer.from(expected)\n  if (providedSignature.length !== expectedSignature.length) return null\n  if (!crypto.timingSafeEqual(providedSignature, expectedSignature)) return null\n  let payload: JwtPayload\n  try {\n    payload = JSON.parse(Buffer.from(p, 'base64').toString('utf8'))\n  } catch {\n    return null\n  }\n  const now = Math.floor(Date.now() / 1000)\n  if (payload.exp && now > payload.exp) return null\n  if (options.audience !== undefined) {\n    if (payload.aud !== options.audience) return null\n  }\n  if (options.issuer !== undefined) {\n    if (payload.iss !== options.issuer) return null\n  }\n  return payload\n}\n\n/**\n * Whether a raw-secret token is still inside the migration window. A token is only ever legacy\n * for a bounded period after it was issued, so `iat` is mandatory: a token that cannot prove its\n * age cannot prove it is inside the window either, and accepting it would make the window\n * unbounded \u2014 which is exactly the defect this guard closes.\n */\nfunction isWithinLegacyWindow(payload: JwtPayload, graceMinutes: number): boolean {\n  const cutoverAt = getLegacyCutoverEpochSeconds()\n  const now = Math.floor(Date.now() / 1000)\n  if (cutoverAt === null || now >= cutoverAt) return false\n  const issuedAt = payload.iat\n  if (typeof issuedAt !== 'number' || !Number.isFinite(issuedAt)) return false\n  if (issuedAt > now + LEGACY_TOKEN_CLOCK_SKEW_SECONDS) return false\n  return now - issuedAt <= graceMinutes * 60\n}\n\nexport function verifyJwt(token: string, secretOrOptions?: string | VerifyJwtOptions) {\n  const options = toVerifyOptions(secretOrOptions)\n  const result = verifyWithOptions(token, options)\n  if (result) {\n    // `_legacyToken` is assigned by this function alone. Strip any same-named claim carried in\n    // the token body so a payload can never talk callers (staff session integrity, portal auth)\n    // into treating a modern, session-bound token as a sessionless legacy one.\n    if (result._legacyToken !== undefined) delete result._legacyToken\n    return result\n  }\n\n  // Legacy fallback: when the caller used the default path (no explicit secret) and the new\n  // audience-derived verification failed, try verifying with the raw JWT_SECRET. This keeps\n  // pre-migration tokens working across a rolling deployment \u2014 but only until the token's own\n  // `iat` leaves the configured grace window, or the configured cutover instant passes.\n  if (secretOrOptions === undefined) {\n    const graceMinutes = getLegacyGraceMinutes()\n    const rawSecret = process.env.JWT_SECRET\n    if (graceMinutes > 0 && rawSecret) {\n      const legacyResult = verifyWithOptions(token, { secret: rawSecret })\n      if (legacyResult && isWithinLegacyWindow(legacyResult, graceMinutes)) {\n        legacyResult._legacyToken = true\n        return legacyResult\n      }\n    }\n  }\n\n  return null\n}\n\n/**\n * Sign a JWT for a specific audience using an audience-derived signing key. The resulting token\n * carries `iss` and `aud` claims and cannot be verified with the base `JWT_SECRET` directly \u2014\n * callers must use `verifyAudienceJwt` with the same audience.\n */\nexport function signAudienceJwt(\n  audience: string,\n  payload: JwtPayload,\n  expiresInSec: number = 60 * 60 * 8,\n): string {\n  return signJwt(payload, { audience, expiresInSec })\n}\n\n/**\n * Verify a JWT that was signed with an audience-scoped secret. Rejects tokens that are missing\n * or carry a mismatched `aud`/`iss` claim, so a staff JWT cannot be replayed against the\n * customer portal (and vice versa) even when the base `JWT_SECRET` is shared.\n */\nexport function verifyAudienceJwt(audience: string, token: string): JwtPayload | null {\n  return verifyJwt(token, { audience })\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.6944.1.eef6a0ee1d";
+const APP_VERSION = "0.6.8-develop.6948.1.8369fc4c97";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6944.1.eef6a0ee1d';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6948.1.8369fc4c97';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.6944.1.eef6a0ee1d",
+  "version": "0.6.8-develop.6948.1.8369fc4c97",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -105,7 +105,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.6944.1.eef6a0ee1d",
+    "@open-mercato/cache": "0.6.8-develop.6948.1.8369fc4c97",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

package/src/lib/auth/__tests__/jwt.test.ts

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto'
 
 import {
+  assertJwtSecretPolicy,
   deriveJwtAudienceSecret,
   signAudienceJwt,
   signJwt,
@@ -233,18 +234,26 @@ describe('jwt helpers', () => {
     const baseSecret = 'test-secret'
     const originalJwtSecret = process.env.JWT_SECRET
     const originalGrace = process.env.JWT_LEGACY_GRACE_MINUTES
+    const originalCutover = process.env.JWT_LEGACY_CUTOVER_AT
 
     beforeEach(() => {
       process.env.JWT_SECRET = baseSecret
       delete process.env.JWT_LEGACY_GRACE_MINUTES
+      process.env.JWT_LEGACY_CUTOVER_AT = new Date(now.getTime() + 48 * 60 * 60 * 1000).toISOString()
     })
 
     afterEach(() => {
       process.env.JWT_SECRET = originalJwtSecret
       if (originalGrace === undefined) delete process.env.JWT_LEGACY_GRACE_MINUTES
       else process.env.JWT_LEGACY_GRACE_MINUTES = originalGrace
+      if (originalCutover === undefined) delete process.env.JWT_LEGACY_CUTOVER_AT
+      else process.env.JWT_LEGACY_CUTOVER_AT = originalCutover
     })
 
+    function advanceMinutes(minutes: number): void {
+      jest.spyOn(Date, 'now').mockReturnValue(now.getTime() + minutes * 60 * 1000)
+    }
+
     it('verifies a pre-migration token signed with raw JWT_SECRET via legacy fallback', () => {
       // Simulate a pre-migration token: signed with raw secret, no aud/iss
       const legacyToken = signJwt({ sub: 'legacy-user', roles: ['admin'] }, baseSecret, 3600)
@@ -275,5 +284,189 @@ describe('jwt helpers', () => {
       expect(payload).toMatchObject({ sub: 'new-user', aud: 'staff', iss: 'open-mercato' })
       expect((payload as Record<string, unknown>)._legacyToken).toBeUndefined()
     })
+
+    it('rejects a legacy token issued longer ago than the configured grace window', () => {
+      process.env.JWT_LEGACY_GRACE_MINUTES = '1'
+      // Long TTL so `exp` is still in the future: this must fail on the grace window alone,
+      // otherwise the test would pass even with an unbounded fallback.
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 30 * 24 * 3600)
+      expect(verifyJwt(legacyToken)).not.toBeNull()
+      advanceMinutes(120)
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('keeps accepting a legacy token while it is still inside the grace window', () => {
+      process.env.JWT_LEGACY_GRACE_MINUTES = '60'
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 30 * 24 * 3600)
+      advanceMinutes(59)
+      const payload = verifyJwt(legacyToken)
+      expect(payload).not.toBeNull()
+      expect((payload as Record<string, unknown>)._legacyToken).toBe(true)
+    })
+
+    it('rejects a legacy token that carries no iat, since its age cannot be bounded', () => {
+      const header = base64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))
+      const body = base64url(JSON.stringify({ sub: 'legacy-user', exp: Math.floor(now.getTime() / 1000) + 3600 }))
+      const token = `${header}.${body}.${signTokenParts(header, body, baseSecret)}`
+      expect(verifyJwt(token)).toBeNull()
+    })
+
+    it('rejects legacy fallback unless an explicit absolute cutover is configured', () => {
+      delete process.env.JWT_LEGACY_CUTOVER_AT
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 30 * 24 * 3600)
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('rejects a legacy token issued beyond the allowed clock skew', () => {
+      const futureIssuedAt = Math.floor(now.getTime() / 1000) + 61
+      const legacyToken = signJwt(
+        { sub: 'legacy-user', iat: futureIssuedAt },
+        baseSecret,
+        30 * 24 * 3600,
+      )
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('accepts one minute of issuer clock skew during an explicitly bounded migration', () => {
+      const futureIssuedAt = Math.floor(now.getTime() / 1000) + 60
+      const legacyToken = signJwt(
+        { sub: 'legacy-user', iat: futureIssuedAt },
+        baseSecret,
+        30 * 24 * 3600,
+      )
+      expect(verifyJwt(legacyToken)).not.toBeNull()
+    })
+
+    it('rejects legacy tokens once the configured cutover instant has passed', () => {
+      process.env.JWT_LEGACY_GRACE_MINUTES = '480'
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 30 * 24 * 3600)
+      process.env.JWT_LEGACY_CUTOVER_AT = new Date(now.getTime() + 60 * 60 * 1000).toISOString()
+      advanceMinutes(30)
+      expect(verifyJwt(legacyToken)).not.toBeNull()
+      advanceMinutes(90)
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('treats false and off as a disabled fallback, like 0', () => {
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 3600)
+      process.env.JWT_LEGACY_GRACE_MINUTES = 'false'
+      expect(verifyJwt(legacyToken)).toBeNull()
+      process.env.JWT_LEGACY_GRACE_MINUTES = 'off'
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('accepts a legacy token at exactly the edge of the grace window', () => {
+      process.env.JWT_LEGACY_GRACE_MINUTES = '60'
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 30 * 24 * 3600)
+      advanceMinutes(60)
+      expect(verifyJwt(legacyToken)).not.toBeNull()
+      advanceMinutes(61)
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('rejects a legacy token at exactly the cutover instant, not a second later', () => {
+      process.env.JWT_LEGACY_GRACE_MINUTES = '480'
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 30 * 24 * 3600)
+      process.env.JWT_LEGACY_CUTOVER_AT = new Date(now.getTime() + 60 * 60 * 1000).toISOString()
+      advanceMinutes(59)
+      expect(verifyJwt(legacyToken)).not.toBeNull()
+      advanceMinutes(60)
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('normalizes the grace value for case and surrounding whitespace', () => {
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 3600)
+      process.env.JWT_LEGACY_GRACE_MINUTES = '  OFF  '
+      expect(verifyJwt(legacyToken)).toBeNull()
+      process.env.JWT_LEGACY_GRACE_MINUTES = ' False '
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('disables legacy fallback when the configured cutover is unparseable', () => {
+      process.env.JWT_LEGACY_GRACE_MINUTES = '60'
+      process.env.JWT_LEGACY_CUTOVER_AT = 'not-a-date'
+      const legacyToken = signJwt({ sub: 'legacy-user' }, baseSecret, 30 * 24 * 3600)
+      expect(verifyJwt(legacyToken)).toBeNull()
+    })
+
+    it('ignores a _legacyToken claim smuggled into a modern token payload', () => {
+      const token = signJwt({ sub: 'staff-user', _legacyToken: true })
+      const payload = verifyJwt(token) as Record<string, unknown> | null
+      expect(payload).not.toBeNull()
+      expect(payload?._legacyToken).toBeUndefined()
+    })
+  })
+
+  describe('signing secret policy', () => {
+    const originalJwtSecret = process.env.JWT_SECRET
+    const originalNodeEnv = process.env.NODE_ENV
+    const strongSecret = 'a'.repeat(64)
+
+    afterEach(() => {
+      process.env.JWT_SECRET = originalJwtSecret
+      process.env.NODE_ENV = originalNodeEnv
+      delete process.env.JWT_CUSTOMER_SECRET
+    })
+
+    it('refuses to sign in production with the placeholder secret published in the compose files', () => {
+      process.env.NODE_ENV = 'production'
+      process.env.JWT_SECRET = 'JWT'
+      // Assert the reason, not merely that it threw: `JWT` is also under the length floor, so a
+      // policy that had stopped recognizing placeholders would still throw here for the wrong
+      // reason and the test would pass while the placeholder set had quietly become dead code.
+      expect(() => signJwt({ sub: 'user-1' })).toThrow(/placeholder value published/i)
+    })
+
+    it('refuses the 32-character placeholder shipped in the previous production guide', () => {
+      process.env.NODE_ENV = 'production'
+      process.env.JWT_SECRET = 'your-secure-jwt-secret-change-me'
+      expect(() => signJwt({ sub: 'user-1' })).toThrow(/placeholder value published/i)
+    })
+
+    it('refuses to sign in production with a secret shorter than 32 characters', () => {
+      process.env.NODE_ENV = 'production'
+      process.env.JWT_SECRET = 'short-secret'
+      expect(() => signJwt({ sub: 'user-1' })).toThrow(/unsafe signing secret/i)
+    })
+
+    it('accepts a secret of exactly the minimum length and rejects one character less', () => {
+      process.env.NODE_ENV = 'production'
+      process.env.JWT_SECRET = 'a'.repeat(32)
+      expect(() => signJwt({ sub: 'user-1' })).not.toThrow()
+      process.env.JWT_SECRET = 'a'.repeat(31)
+      expect(() => signJwt({ sub: 'user-1' })).toThrow(/shorter than 32 characters/i)
+    })
+
+    it('signs normally in production with a strong secret', () => {
+      process.env.NODE_ENV = 'production'
+      process.env.JWT_SECRET = strongSecret
+      expect(() => signJwt({ sub: 'user-1' })).not.toThrow()
+    })
+
+    it('tolerates a weak secret outside production so local development keeps working', () => {
+      process.env.NODE_ENV = 'development'
+      process.env.JWT_SECRET = 'JWT'
+      expect(() => signJwt({ sub: 'user-1' })).not.toThrow()
+    })
+
+    it('assertJwtSecretPolicy rejects a missing secret in production', () => {
+      process.env.NODE_ENV = 'production'
+      delete process.env.JWT_SECRET
+      expect(() => assertJwtSecretPolicy()).toThrow(/JWT_SECRET is not set/i)
+    })
+
+    it('assertJwtSecretPolicy rejects a weak per-audience override in production', () => {
+      process.env.NODE_ENV = 'production'
+      process.env.JWT_SECRET = strongSecret
+      process.env.JWT_CUSTOMER_SECRET = 'secret'
+      expect(() => assertJwtSecretPolicy()).toThrow(/JWT_CUSTOMER_SECRET/)
+    })
+
+    it('assertJwtSecretPolicy passes in production when every secret is strong', () => {
+      process.env.NODE_ENV = 'production'
+      process.env.JWT_SECRET = strongSecret
+      process.env.JWT_CUSTOMER_SECRET = 'b'.repeat(64)
+      expect(() => assertJwtSecretPolicy()).not.toThrow()
+    })
   })
 })

package/src/lib/auth/jwt.ts

@@ -1,4 +1,8 @@
 import crypto from 'node:crypto'
+import { createLogger } from '../logger'
+import { parseNumberWithDefault } from '../number'
+
+const logger = createLogger('auth').child({ component: 'jwt' })
 
 function base64url(input: Buffer | string) {
   return (typeof input === 'string' ? Buffer.from(input) : input)
@@ -29,23 +33,134 @@ const DEFAULT_ISSUER = 'open-mercato'
 const DEFAULT_STAFF_AUDIENCE: JwtAudience = 'staff'
 const AUDIENCE_SECRET_LABEL = 'open-mercato:jwt:v1'
 
+const LEGACY_GRACE_DEFAULT_MINUTES = 480
+const LEGACY_TOKEN_CLOCK_SKEW_SECONDS = 60
+
 /**
- * When set to a positive number (minutes), `verifyJwt` will attempt a legacy fallback using the
- * raw `JWT_SECRET` when the audience-derived verification fails. This supports rolling deployments
- * and lets existing sessions expire gracefully instead of force-logging-out every user on deploy.
+ * How long after a token was issued (`iat`) the raw-`JWT_SECRET` fallback in `verifyJwt` keeps
+ * accepting it. The fallback exists so a rolling deployment of the audience-derived signing
+ * scheme does not force-log-out every user; it is a migration window, not a permanent mode.
  *
- * Set via `JWT_LEGACY_GRACE_MINUTES` env var. Defaults to 480 (8 hours — one full token TTL).
- * Set to 0 to disable the fallback (hard cutover).
+ * Set via `JWT_LEGACY_GRACE_MINUTES`. Defaults to 480 (8 hours — one full token TTL).
+ * `0`, `false` or `off` disables the fallback entirely (hard cutover). Values that do not parse
+ * fall back to the default rather than silently disabling authentication.
  */
-function getLegacyGraceEnabled(): boolean {
+function getLegacyGraceMinutes(): number {
   const raw = process.env.JWT_LEGACY_GRACE_MINUTES
-  if (raw === '0' || raw === 'false' || raw === 'off') return false
-  return true
+  const normalized = typeof raw === 'string' ? raw.trim().toLowerCase() : raw
+  if (normalized === 'false' || normalized === 'off') return 0
+  return parseNumberWithDefault(normalized, LEGACY_GRACE_DEFAULT_MINUTES, { min: 0, integer: true })
+}
+
+/**
+ * Required absolute deadline for the legacy fallback, as an ISO-8601 instant in
+ * `JWT_LEGACY_CUTOVER_AT`. Without a valid deadline the fallback stays disabled: token `iat` is
+ * attacker-controlled by anyone who knows the former raw secret, so a relative age check alone
+ * cannot make the migration window finite.
+ */
+function getLegacyCutoverEpochSeconds(): number | null {
+  const raw = process.env.JWT_LEGACY_CUTOVER_AT
+  if (!raw || !raw.trim()) return null
+  const parsed = Date.parse(raw.trim())
+  if (Number.isNaN(parsed)) {
+    warnOnce(
+      'jwt-legacy-cutover-unparseable',
+      'JWT_LEGACY_CUTOVER_AT is not a valid ISO-8601 instant — legacy JWT fallback remains disabled.',
+    )
+    return null
+  }
+  return Math.floor(parsed / 1000)
+}
+
+const MIN_SECRET_LENGTH = 32
+
+/**
+ * Signing secrets that ship in this repository's own examples, compose files, and docs. A
+ * deployment reaching production with one of these is not "weakly configured" — it is publicly
+ * forgeable by anyone who has read the repository.
+ */
+const PLACEHOLDER_SECRETS = new Set([
+  'jwt',
+  'jwt-secret',
+  'jwtsecret',
+  'secret',
+  'password',
+  'changeme',
+  'change-me',
+  'change-me-dev-secret',
+  'change-me-dev-auth-secret',
+  'your-strong-jwt-secret',
+  'your-secure-jwt-secret-change-me',
+  'dev',
+  'development',
+  'test',
+])
+
+export type JwtSecretViolation = 'missing' | 'placeholder' | 'too_short'
+
+const warnedKeys = new Set<string>()
+
+function warnOnce(key: string, message: string): void {
+  if (warnedKeys.has(key)) return
+  warnedKeys.add(key)
+  logger.warn(message)
+}
+
+function isProduction(): boolean {
+  return process.env.NODE_ENV === 'production'
+}
+
+function inspectSecret(secret: string | undefined | null): JwtSecretViolation | null {
+  const value = typeof secret === 'string' ? secret.trim() : ''
+  if (!value) return 'missing'
+  if (PLACEHOLDER_SECRETS.has(value.toLowerCase())) return 'placeholder'
+  if (value.length < MIN_SECRET_LENGTH) return 'too_short'
+  return null
+}
+
+function describeViolation(name: string, violation: JwtSecretViolation): string {
+  switch (violation) {
+    case 'missing':
+      return `${name} is not set. Generate one with \`openssl rand -hex 32\`.`
+    case 'placeholder':
+      return `${name} is set to a placeholder value published in this repository's examples, so anyone can forge tokens for this deployment. Generate a real one with \`openssl rand -hex 32\`.`
+    case 'too_short':
+      return `${name} is shorter than ${MIN_SECRET_LENGTH} characters. Generate a stronger one with \`openssl rand -hex 32\`.`
+  }
+}
+
+/**
+ * Fail closed in production, warn in every other environment. Called on every secret read so
+ * worker, scheduler, and CLI processes — which never run the app's startup hook — are covered
+ * too. `assertJwtSecretPolicy` runs the same check eagerly at server startup.
+ */
+function enforceSecretPolicy(name: string, secret: string | undefined | null): void {
+  const violation = inspectSecret(secret)
+  if (!violation) return
+  const message = describeViolation(name, violation)
+  if (isProduction()) {
+    throw new Error(`[auth.jwt] Refusing to run in production with an unsafe signing secret: ${message}`)
+  }
+  warnOnce(`secret-policy:${name}:${violation}`, `${message} This is tolerated outside production only.`)
+}
+
+/**
+ * Validate every JWT signing secret this process would use. Call it once at startup so a
+ * misconfigured production deployment fails immediately and loudly instead of at the first login
+ * attempt. Throws in production; logs a warning elsewhere.
+ */
+export function assertJwtSecretPolicy(): void {
+  enforceSecretPolicy('JWT_SECRET', process.env.JWT_SECRET)
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!/^JWT_[A-Z0-9]+(?:_[A-Z0-9]+)*_SECRET$/.test(key)) continue
+    enforceSecretPolicy(key, value)
+  }
 }
 
 function readBaseSecret(explicit?: string): string {
   const secret = explicit ?? process.env.JWT_SECRET
   if (!secret) throw new Error('JWT_SECRET is not set')
+  if (explicit === undefined) enforceSecretPolicy('JWT_SECRET', secret)
   return secret
 }
 
@@ -80,7 +195,10 @@ export function deriveJwtAudienceSecret(audience: string, baseSecret?: string):
   if (!normalized) throw new Error('Audience is required to derive a JWT secret')
   const overrideName = `JWT_${normalized.toUpperCase()}_SECRET`
   const override = process.env[overrideName]
-  if (override && override.trim().length > 0) return override
+  if (override && override.trim().length > 0) {
+    enforceSecretPolicy(overrideName, override)
+    return override
+  }
   const base = readBaseSecret(baseSecret)
   return deriveAudienceSecretFromBase(normalized, base)
 }
@@ -192,19 +310,43 @@ function verifyWithOptions(token: string, options: { secret: string; audience?:
   return payload
 }
 
+/**
+ * Whether a raw-secret token is still inside the migration window. A token is only ever legacy
+ * for a bounded period after it was issued, so `iat` is mandatory: a token that cannot prove its
+ * age cannot prove it is inside the window either, and accepting it would make the window
+ * unbounded — which is exactly the defect this guard closes.
+ */
+function isWithinLegacyWindow(payload: JwtPayload, graceMinutes: number): boolean {
+  const cutoverAt = getLegacyCutoverEpochSeconds()
+  const now = Math.floor(Date.now() / 1000)
+  if (cutoverAt === null || now >= cutoverAt) return false
+  const issuedAt = payload.iat
+  if (typeof issuedAt !== 'number' || !Number.isFinite(issuedAt)) return false
+  if (issuedAt > now + LEGACY_TOKEN_CLOCK_SKEW_SECONDS) return false
+  return now - issuedAt <= graceMinutes * 60
+}
+
 export function verifyJwt(token: string, secretOrOptions?: string | VerifyJwtOptions) {
   const options = toVerifyOptions(secretOrOptions)
   const result = verifyWithOptions(token, options)
-  if (result) return result
+  if (result) {
+    // `_legacyToken` is assigned by this function alone. Strip any same-named claim carried in
+    // the token body so a payload can never talk callers (staff session integrity, portal auth)
+    // into treating a modern, session-bound token as a sessionless legacy one.
+    if (result._legacyToken !== undefined) delete result._legacyToken
+    return result
+  }
 
   // Legacy fallback: when the caller used the default path (no explicit secret) and the new
-  // audience-derived verification failed, try verifying with the raw JWT_SECRET. This allows
-  // pre-migration tokens to remain valid during rolling deployments and graceful migration.
-  if (secretOrOptions === undefined && getLegacyGraceEnabled()) {
+  // audience-derived verification failed, try verifying with the raw JWT_SECRET. This keeps
+  // pre-migration tokens working across a rolling deployment — but only until the token's own
+  // `iat` leaves the configured grace window, or the configured cutover instant passes.
+  if (secretOrOptions === undefined) {
+    const graceMinutes = getLegacyGraceMinutes()
     const rawSecret = process.env.JWT_SECRET
-    if (rawSecret) {
+    if (graceMinutes > 0 && rawSecret) {
       const legacyResult = verifyWithOptions(token, { secret: rawSecret })
-      if (legacyResult) {
+      if (legacyResult && isWithinLegacyWindow(legacyResult, graceMinutes)) {
         legacyResult._legacyToken = true
         return legacyResult
       }