@fonderie/auth 7.17.0 → 7.18.0

package/brain/outcomes.md

@@ -98,6 +98,7 @@ location                 JSONB
 previous_token_hash      TEXT
 previous_valid_until     TIMESTAMPTZ
 last_used_at             TIMESTAMPTZ
+client_kind              TEXT
 -- INDEX idx_fonderie_sessions_expires_at (expires_at)
 -- INDEX idx_fonderie_sessions_sid (sid)
 ```

package/brain/signatures.md

@@ -93,6 +93,7 @@ interface IAuthSecrets {
 interface IAuthRuntimeConfig {
     sessionDuration?: string;
     sessionMaxAge?: string;
+    sessionPolicies?: Partial<Record<ClientKind, ISessionPolicy>>;
     verificationCooldown?: number;
     mfa?: boolean;
     requireVerification?: boolean;
@@ -103,7 +104,7 @@ interface IDataExportContributor {
     collect: (userId: string) => Promise<unknown> | unknown;
 }
 
-const AUTH_CONFIG_KEYS: Record<keyof IAuthRuntimeConfig, string>
+const AUTH_CONFIG_KEYS: Record<Exclude<keyof IAuthRuntimeConfig, 'sessionPolicies'>, string>
 
 const MESSAGE_KEYS: { readonly emailRegistration: "email-registration"; readonly emailVerification: "email-verification"; readonly passwordReset: "password-reset"; readonly phoneOtp: "phone-otp"; readonly mfaEnabled: "mfa-enabled"; readonly mfaDisabled: "mfa-disabled"; readonly mfaBackupCodesRegenerated: "mfa-backup-codes-regenerated"; readonly emailChanged: "email-changed"; readonly phoneChanged: "phone-changed"; readonly passwordRevoked: "password-revoked"; readonly oauthRegistration: "oauth-registration"; readonly oauthLinked: "oauth-linked"; readonly oauthUnlinked: "oauth-unlinked"; }
 
@@ -159,6 +160,7 @@ interface ISessionDTO {
     location: IRequestLocation | null;
     createdAt: string;
     expiresAt: string;
+    clientKind: string | null;
 }
 
 function sanitizeLocation(input: unknown): IRequestLocation | null
@@ -270,4 +272,24 @@ function describeAuthAdminRoutes(store: IStoreAdapter): IAdminRoute[]
 function toAdminUserDTO(user: IUser): IAdminUserDTO
 
 function toAdminUserPageDTO(page: IUserPage): IAdminUserPageDTO
+
+const CLIENT_KINDS: readonly ["mobile", "desktop", "web"]
+
+const SESSION_POLICY_PRESETS: Readonly<Record<ClientKind, ISessionPolicy>>
+
+function clientKindOf(headers: Headers): "mobile" | "desktop" | "web" | null
+
+function configForClient(config: IAuthConfig, runtime: Partial<IAuthRuntimeConfig> | undefined, kind: "mobile" | "desktop" | "web" | null): IAuthConfig
+
+function readAuthRuntimeConfig(read: (key: string) => unknown): Partial<IAuthRuntimeConfig>
+
+function sessionPolicyConfigKeys(kind: "mobile" | "desktop" | "web"): Record<keyof ISessionPolicy, string>
+
+type ClientKind = (typeof CLIENT_KINDS)[number];
+
+interface ISessionPolicy {
+    sessionDuration?: string;
+    sessionMaxAge?: string;
+    accessTokenDuration?: string;
+}
 ```

package/dist/index.cjs

@@ -70,19 +70,25 @@ var index_exports = {};
 __export(index_exports, {
   AUTH_CONFIG_KEYS: () => AUTH_CONFIG_KEYS,
   AuthModule: () => AuthModule,
+  CLIENT_KINDS: () => CLIENT_KINDS,
   DEFAULT_TEMPLATES: () => DEFAULT_TEMPLATES,
   MESSAGE_KEYS: () => MESSAGE_KEYS,
+  SESSION_POLICY_PRESETS: () => SESSION_POLICY_PRESETS,
   buildAuthAccountLimiter: () => buildAuthAccountLimiter,
   buildAuthIpLimiter: () => buildAuthIpLimiter,
+  clientKindOf: () => clientKindOf,
+  configForClient: () => configForClient,
   describeAuthAdminRoutes: () => describeAuthAdminRoutes,
   importUser: () => importUser,
   normalizeEmail: () => normalizeEmail,
   normalizeEmailSafe: () => normalizeEmailSafe,
   purgeSoftDeletedUsers: () => purgeSoftDeletedUsers,
+  readAuthRuntimeConfig: () => readAuthRuntimeConfig,
   requireAuth: () => import_middlewares3.requireAuth,
   resolveLocation: () => resolveLocation,
   sanitizeLocation: () => sanitizeLocation,
   schemas: () => schemas_exports,
+  sessionPolicyConfigKeys: () => sessionPolicyConfigKeys,
   startUserRetention: () => startUserRetention,
   toAdminUserDTO: () => toAdminUserDTO,
   toAdminUserPageDTO: () => toAdminUserPageDTO,
@@ -357,8 +363,8 @@ function issueMfaPendingToken(userId, config, loginMethod) {
   );
 }
 function issueTokenPair(userId, config, options) {
-  const duration = config.sessionDuration ?? DEFAULT_SESSION_DURATION;
-  const accessDuration = config.accessTokenDuration ?? DEFAULT_ACCESS_TOKEN_DURATION;
+  const duration = validDuration(config.sessionDuration, DEFAULT_SESSION_DURATION, "sessionDuration");
+  const accessDuration = validDuration(config.accessTokenDuration, DEFAULT_ACCESS_TOKEN_DURATION, "accessTokenDuration");
   const authTime = options.authTime ?? Math.floor(Date.now() / 1e3);
   const loginMethod = options.loginMethod;
   const phoneVerified = options.phoneVerified ?? false;
@@ -401,6 +407,90 @@ function durationMs(value) {
   const scale = { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5, y: 315576e5 };
   return Number(m[1]) * (scale[unit] ?? 1e3);
 }
+var warnedDurations = /* @__PURE__ */ new Set();
+function validDuration(value, fallback, name) {
+  if (value === void 0 || value === null || value === "") return fallback;
+  if (durationMs(String(value)) !== null) return String(value);
+  const key = `${name}=${String(value)}`;
+  if (!warnedDurations.has(key)) {
+    warnedDurations.add(key);
+    console.warn(`[auth] ${name} ${JSON.stringify(value)} is not a duration (e.g. '90d', '1h') \u2014 using ${fallback}`);
+  }
+  return fallback;
+}
+
+// src/services/session-policy.ts
+var CLIENT_KINDS = ["mobile", "desktop", "web"];
+var SESSION_POLICY_PRESETS = {
+  // Personal device; the token lives in the Keychain / Keystore.
+  mobile: { sessionDuration: "90d", sessionMaxAge: "365d" },
+  // Personal, but often a shared workstation.
+  desktop: { sessionDuration: "30d", sessionMaxAge: "180d" },
+  // Shared and public computers; cookies.
+  web: { sessionDuration: "14d", sessionMaxAge: "90d" }
+};
+function clientKindOf(headers) {
+  const v = headers.get("x-client-kind")?.trim().toLowerCase();
+  return CLIENT_KINDS.includes(v ?? "") ? v : null;
+}
+var FIELDS = ["sessionDuration", "sessionMaxAge", "accessTokenDuration"];
+function configForClient(config, runtime, kind) {
+  const rt = runtime ?? {};
+  const code = config;
+  const out = { ...config, ...rt };
+  for (const field of FIELDS) {
+    const value = (kind ? rt.sessionPolicies?.[kind]?.[field] : void 0) ?? rt[field] ?? (kind ? code.sessionPolicies?.[kind]?.[field] : void 0) ?? code[field] ?? (kind ? SESSION_POLICY_PRESETS[kind][field] : void 0);
+    if (value === void 0) delete out[field];
+    else out[field] = value;
+  }
+  return out;
+}
+function sessionPolicyConfigKeys(kind) {
+  return {
+    sessionDuration: `auth.session.duration.${kind}`,
+    sessionMaxAge: `auth.session.max_age.${kind}`,
+    accessTokenDuration: `auth.access.duration.${kind}`
+  };
+}
+function readAuthRuntimeConfig(read) {
+  const text = (key) => {
+    const v = read(key);
+    return typeof v === "string" && v.trim() ? v.trim() : void 0;
+  };
+  const bool2 = (key) => {
+    const v = read(key);
+    if (typeof v === "boolean") return v;
+    if (typeof v === "string" && ["true", "false"].includes(v.trim().toLowerCase())) return v.trim().toLowerCase() === "true";
+    return void 0;
+  };
+  const num = (key) => {
+    const v = read(key);
+    const n = typeof v === "number" ? v : typeof v === "string" && v.trim() ? Number(v) : NaN;
+    return Number.isFinite(n) ? n : void 0;
+  };
+  const out = {};
+  const set = (k, v) => {
+    if (v !== void 0) out[k] = v;
+  };
+  set("sessionDuration", text("auth.session.duration"));
+  set("sessionMaxAge", text("auth.session.max_age"));
+  set("accessTokenDuration", text("auth.access.duration"));
+  set("verificationCooldown", num("auth.verification.cooldown"));
+  set("mfa", bool2("auth.mfa.enabled"));
+  set("requireVerification", bool2("auth.verification.required"));
+  const policies = {};
+  for (const kind of CLIENT_KINDS) {
+    const keys = sessionPolicyConfigKeys(kind);
+    const policy = {};
+    for (const field of FIELDS) {
+      const v = text(keys[field]);
+      if (v !== void 0) policy[field] = v;
+    }
+    if (Object.keys(policy).length) policies[kind] = policy;
+  }
+  if (Object.keys(policies).length) out.sessionPolicies = policies;
+  return out;
+}
 
 // src/services/mfa.ts
 var import_node_crypto2 = require("crypto");
@@ -1025,8 +1115,8 @@ 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, last_used_at)
-			VALUES ($1, $2, $3, $4, $5, $6, $7, now())
+      `INSERT INTO fonderie_sessions (user_id, token, expires_at, sid, user_agent, ip_address, location, last_used_at, client_kind)
+			VALUES ($1, $2, $3, $4, $5, $6, $7, now(), $8)
 			ON CONFLICT (token) DO NOTHING`,
       [
         userId,
@@ -1035,7 +1125,8 @@ var SessionModel = class {
         sid ?? null,
         meta?.userAgent ?? null,
         meta?.ipAddress ?? null,
-        location ? JSON.stringify(location) : null
+        location ? JSON.stringify(location) : null,
+        meta?.clientKind ?? null
       ]
     );
   }
@@ -1050,12 +1141,12 @@ var SessionModel = class {
   async match(token) {
     const hash = hashRefreshToken(token);
     const [current] = await this.store.query(
-      `SELECT id, user_id, sid, token, created_at FROM fonderie_sessions WHERE token IN ($1, $2) AND expires_at > now() LIMIT 1`,
+      `SELECT id, user_id, sid, token, created_at, client_kind 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, created_at, (previous_valid_until > now()) AS in_grace
+      `SELECT id, user_id, sid, token, created_at, client_kind, (previous_valid_until > now()) AS in_grace
 			   FROM fonderie_sessions WHERE previous_token_hash = $1 AND expires_at > now() LIMIT 1`,
       [hash]
     );
@@ -1121,7 +1212,7 @@ var SessionModel = class {
   // No token — that never leaves the server.
   async listLiveByUser(userId) {
     return this.store.query(
-      `SELECT id, sid,
+      `SELECT id, sid, client_kind AS "clientKind",
 			        user_agent AS "userAgent",
 			        ip_address AS "ipAddress",
 			        location,
@@ -1170,7 +1261,8 @@ var SessionModel = class {
   }
 };
 function toRow(r) {
-  return { id: r.id, userId: r.user_id, sid: r.sid, stored: r.token, createdAt: r.created_at ? new Date(r.created_at) : /* @__PURE__ */ new Date() };
+  const kind = CLIENT_KINDS.includes(r.client_kind ?? "") ? r.client_kind : null;
+  return { id: r.id, userId: r.user_id, sid: r.sid, stored: r.token, createdAt: r.created_at ? new Date(r.created_at) : /* @__PURE__ */ new Date(), clientKind: kind };
 }
 
 // src/models/backup-code.model.ts
@@ -1301,7 +1393,8 @@ function requestMeta(ctx) {
   const meta = {
     ipAddress: typeof ip === "string" && ip.length > 0 ? ip : null,
     userAgent: ua && ua.length > 0 ? ua.slice(0, UA_MAX) : null,
-    headers: ctx.request.headers
+    headers: ctx.request.headers,
+    clientKind: clientKindOf(ctx.request.headers)
   };
   if (meta.ipAddress === null && meta.userAgent === null) warnIfIdentityless(ctx);
   return meta;
@@ -1416,7 +1509,7 @@ function mfaController(store, config, issuer, bus) {
           await users.enableMfa(ctx.user.id);
         }
       }
-      const { accessToken, refreshToken, sid } = issueTokenPair(ctx.user.id, config, {
+      const { accessToken, refreshToken, sid } = issueTokenPair(ctx.user.id, configForClient(config, config.resolve?.(ctx), clientKindOf(ctx.request.headers)), {
         loginMethod: ctx.user.loginMethod,
         phoneVerified: ctx.user.phoneVerified
       });
@@ -1778,7 +1871,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
           },
           reqOpts
         ));
-        const { accessToken, refreshToken, sid } = issueTokenPair(user.id, config, {
+        const { accessToken, refreshToken, sid } = issueTokenPair(user.id, configForClient(config, config.resolve?.(ctx), clientKindOf(ctx.request.headers)), {
           loginMethod: "email"
         });
         const registerMeta = requestMeta(ctx);
@@ -1921,7 +2014,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
             mfaToken
           });
         }
-        const { accessToken, refreshToken, sid } = issueTokenPair(user.id, config, {
+        const { accessToken, refreshToken, sid } = issueTokenPair(user.id, configForClient(config, config.resolve?.(ctx), clientKindOf(ctx.request.headers)), {
           loginMethod: "email"
         });
         await sessions.create(user.id, refreshToken, refreshTokenExpiry(refreshToken), sid, meta);
@@ -2014,8 +2107,7 @@ 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 resolvedRefresh = { ...config, ...config.resolve?.(ctx) };
-      const maxAgeMs = durationMs(resolvedRefresh.sessionMaxAge);
+      const runtime = config.resolve?.(ctx);
       let issued = null;
       for (let attempt = 0; attempt < 3 && !issued; attempt++) {
         const found = await sessions.match(token);
@@ -2029,6 +2121,8 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
           );
           return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "TOKEN_REFRESH_FAILED", "Session expired or already revoked");
         }
+        const resolvedRefresh = configForClient(config, runtime, found.row.clientKind);
+        const maxAgeMs = resolvedRefresh.sessionMaxAge ? durationMs(String(resolvedRefresh.sessionMaxAge)) : null;
         if (maxAgeMs !== null && Date.now() - found.row.createdAt.getTime() > maxAgeMs) {
           await sessions.revokeById(found.row.id);
           return (0, import_core6.setApiResponse)(import_core6.HTTP.UNAUTHORIZED, "TOKEN_REFRESH_FAILED", "Session reached its maximum age \u2014 sign in again");
@@ -2210,7 +2304,7 @@ function authController(store, config, bus, locales = (0, import_core6.defineLoc
           );
         }
         await phoneVerif.deleteByUser(ctx.user.id);
-        const { accessToken, refreshToken, sid } = issueTokenPair(ctx.user.id, config, {
+        const { accessToken, refreshToken, sid } = issueTokenPair(ctx.user.id, configForClient(config, config.resolve?.(ctx), clientKindOf(ctx.request.headers)), {
           loginMethod: "phone",
           phoneVerified: true
         });
@@ -2387,6 +2481,7 @@ function toSessionDTO(row, currentSid) {
     ipAddress: row.ipAddress,
     userAgent: row.userAgent,
     location: sanitizeLocation(row.location),
+    clientKind: row.clientKind ?? null,
     createdAt: row.createdAt instanceof Date ? row.createdAt.toISOString() : String(row.createdAt),
     expiresAt: row.expiresAt instanceof Date ? row.expiresAt.toISOString() : String(row.expiresAt)
   };
@@ -2935,7 +3030,7 @@ function oauthController(store, config, bus) {
       return (0, import_core9.setApiResponse)(import_core9.HTTP.SERVER_ERROR, "SERVER_ERROR", "Apple login failed");
     }
     await announceOAuthUpsert(ctx, upserted, "apple", fullUser);
-    const { accessToken, refreshToken, sid } = issueTokenPair(upserted.id, config, { loginMethod: "apple" });
+    const { accessToken, refreshToken, sid } = issueTokenPair(upserted.id, configForClient(config, config.resolve?.(ctx), clientKindOf(ctx.request.headers)), { loginMethod: "apple" });
     await sessions.create(upserted.id, refreshToken, refreshTokenExpiry(refreshToken), sid, meta);
     await loginEvents.recordSafe({
       userId: upserted.id,
@@ -3086,7 +3181,7 @@ function oauthController(store, config, bus) {
         return (0, import_core9.setApiResponse)(import_core9.HTTP.SERVER_ERROR, "SERVER_ERROR", "OAuth login failed");
       }
       await announceOAuthUpsert(ctx, upserted, "google", fullUser);
-      const { accessToken, refreshToken, sid } = issueTokenPair(upserted.id, config, {
+      const { accessToken, refreshToken, sid } = issueTokenPair(upserted.id, configForClient(config, config.resolve?.(ctx), clientKindOf(ctx.request.headers)), {
         loginMethod: "google"
       });
       await sessions.create(upserted.id, refreshToken, refreshTokenExpiry(refreshToken), sid, meta);
@@ -3674,7 +3769,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.17.0";
+  version = "7.18.0";
   // Users, sessions, login history, suspend — only through @fonderie/admin.
   describeAdmin() {
     return { routes: describeAuthAdminRoutes(this.store) };
@@ -4270,19 +4365,25 @@ function startUserRetention(store, options) {
 0 && (module.exports = {
   AUTH_CONFIG_KEYS,
   AuthModule,
+  CLIENT_KINDS,
   DEFAULT_TEMPLATES,
   MESSAGE_KEYS,
+  SESSION_POLICY_PRESETS,
   buildAuthAccountLimiter,
   buildAuthIpLimiter,
+  clientKindOf,
+  configForClient,
   describeAuthAdminRoutes,
   importUser,
   normalizeEmail,
   normalizeEmailSafe,
   purgeSoftDeletedUsers,
+  readAuthRuntimeConfig,
   requireAuth,
   resolveLocation,
   sanitizeLocation,
   schemas,
+  sessionPolicyConfigKeys,
   startUserRetention,
   toAdminUserDTO,
   toAdminUserPageDTO,