@warlock.js/auth 5.7.0 → 5.9.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@warlock.js/auth` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.9.0 - 2026-09-13
+
+_Released in lockstep with the `@warlock.js/*` family; no package-specific changes in 5.9.0._
+
+## 5.8.0 - 2026-09-13
+
+### Added
+
+- Guarded page routes can redirect a logged-out browser to a configurable login path instead of returning a raw JSON 401 — opt-in via `auth.pageAuth.loginPath` (API routes still return the JSON 401).
+
+### Fixed
+
+- The `access_tokens` / `refresh_tokens` migrations now derive the `user_id` column type from the user model's primary key (via `foreignId`), so a fresh app with an integer-PK user can log in — the hardcoded `uuid` `user_id` previously failed the first login with no diagnostic.
+
 ## 5.5.0 - 2026-09-07
 
 ### Fixed

package/esm/contracts/index.d.mts

@@ -1,2 +1,2 @@
-import { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, AuthCredentials, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshTokenConfig, TokenFrom, TokenPair } from "./types.mjs";
+import { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, AuthCredentials, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, PageAuthConfig, RefreshTokenConfig, TokenFrom, TokenPair } from "./types.mjs";
 import { Authenticable } from "./auth-contract.mjs";

package/esm/contracts/types.d.mts

@@ -134,6 +134,28 @@ type LegacyJwtConfig = {
     logoutWithoutToken?: LogoutWithoutTokenBehavior;
   };
 };
+/**
+ * Page-route auth-failure behavior. When a guarded PAGE route (a React-SSR page,
+ * `route.isPage`) rejects a logged-out browser, this decides whether it redirects
+ * to a login page instead of returning the API-style JSON 401.
+ *
+ * Read at runtime through `authConfig.pageAuth` (`auth.pageAuth.*`). API routes
+ * always keep the JSON 401 contract regardless of this setting.
+ */
+type PageAuthConfig = {
+  /**
+   * Login path a guarded page route redirects a logged-out browser to (e.g.
+   * `"/login"`). Unset ⇒ page-route auth failures keep the JSON 401, so the
+   * behavior is opt-in and backward-compatible.
+   */
+  loginPath?: string;
+  /**
+   * Query parameter the redirect carries the originally-requested path in, so
+   * the login flow can send the user back where they were headed.
+   * @default "returnUrl"
+   */
+  returnUrlParam?: string;
+};
 type AuthConfigurations = {
   /**
    * Define all user types — maps a user-type slug to its `Auth` model class so
@@ -155,6 +177,12 @@ type AuthConfigurations = {
    * Refresh-token configuration (rotation, lifetime, cap, model override).
    */
   refreshToken?: RefreshTokenConfig;
+  /**
+   * Page-route auth-failure behavior — set `loginPath` to redirect a logged-out
+   * browser on a guarded PAGE route to a login page instead of the JSON 401.
+   * Opt-in; API routes are unaffected. Read via `authConfig.pageAuth`.
+   */
+  pageAuth?: PageAuthConfig;
   /**
    * @deprecated Use `accessToken` / `refreshToken`. Read via a backward-compatible shim.
    */
@@ -214,5 +242,5 @@ type LoginResult<UserType extends Auth> = {
   tokens: TokenPair;
 };
 //#endregion
-export { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, AuthCredentials, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshTokenConfig, TokenFrom, TokenPair };
+export { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, AuthCredentials, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, PageAuthConfig, RefreshTokenConfig, TokenFrom, TokenPair };
 //# sourceMappingURL=types.d.mts.map

package/esm/contracts/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../auth/src/contracts/types.ts"],"mappings":";;;;;;;;;;;AAyBA;;;;AAA0B;AAO1B;;;;AAAsC;AAGtC;;;;AAAqB;cAVR,aAAA;;;;;;KAOD,0BAAA;;KAGA,SAAA;AAMZ;AAAA,KAHY,eAAA,IAAmB,IAAA,EAAM,IAAA,eAAmB,OAAO;;KAGnD,eAAA,GAAkB,MAAM;EAClC,QAAQ;AAAA;;;;;;;KASE,iBAAA;EAeE;;;AAUH;AAMX;EAzBE,KAAA,UAAe,WAAA;;;;EAIf,MAAA;EA+BA;;;;EA1BA,SAAA,GAAY,SAAS;EAsDrB;;;AAA+C;AASjD;;;;;EArDE,SAAA;AAAA;;;;KAMU,kBAAA;EAsDR;;;;EAjDF,KAAA,UAAe,YAAA;EAoDkC;AAAA;AAInD;;EAnDE,OAAA;EAyDiC;;;;EApDjC,MAAA;EAsEM;;;;;;;EA9DN,SAAA;EAkDkB;;;;EA7ClB,QAAA;EAyDA;;;AAAqB;EApDrB,UAAA;EAuD2B;;;AAQlB;EA1DT,kBAAA,GAAqB,0BAA0B;AAAA;;;;;;;KASrC,eAAA;EACV,MAAA;EACA,SAAA,GAAY,SAAA;EACZ,SAAA;EACA,OAAA;IACE,MAAA;IACA,OAAA;IACA,SAAA;IACA,QAAA;IACA,UAAA;IACA,kBAAA,GAAqB,0BAA0B;EAAA;AAAA;AAAA,KAIvC,kBAAA;EA+EA;;;;EA1EV,QAAA;IAAA,CACG,QAAA,WAAmB,UAAA,CAAW,IAAA;EAAA;EA2EhB;;;;EArEjB,eAAA,GAAkB,eAAA;EAqElB;;;EAjEA,WAAA,GAAc,iBAAA;;;;EAId,YAAA,GAAe,kBAAA;;;;EAIf,GAAA,GAAM,eAAA;AAAA;AAAA,KAGI,iBAAA;;;;EAIV,KAAA;;;;EAIA,SAAS;AAAA;;;;KAMC,SAAA;;;;EAIV,WAAA,EAAa,iBAAA;;;;EAIb,YAAA,GAAe,iBAAiB;AAAA;;;;KAMtB,UAAA;;;;EAIV,SAAA;;;;EAIA,EAAA;;;;EAIA,QAAA;;;;;EAKA,QAAA;;;;EAIA,OAAA,GAAU,MAAM;AAAA;AAAA,KAGN,WAAA,kBAA6B,IAAA;EACvC,IAAA,EAAM,QAAA;EACN,MAAA,EAAQ,SAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../auth/src/contracts/types.ts"],"mappings":";;;;;;;;;;;AAyBA;;;;AAA0B;AAO1B;;;;AAAsC;AAGtC;;;;AAAqB;cAVR,aAAA;;;;;;KAOD,0BAAA;;KAGA,SAAA;AAMZ;AAAA,KAHY,eAAA,IAAmB,IAAA,EAAM,IAAA,eAAmB,OAAO;;KAGnD,eAAA,GAAkB,MAAM;EAClC,QAAQ;AAAA;;;;;;;KASE,iBAAA;EAeE;;;AAUH;AAMX;EAzBE,KAAA,UAAe,WAAA;;;;EAIf,MAAA;EA+BA;;;;EA1BA,SAAA,GAAY,SAAS;EAsDrB;;;AAA+C;AASjD;;;;;EArDE,SAAA;AAAA;;;;KAMU,kBAAA;EAsDR;;;;EAjDF,KAAA,UAAe,YAAA;EAoDkC;AAAA;AAYnD;;EA3DE,OAAA;EAiEA;AAMc;AAGhB;;EArEE,MAAA;EA2EiC;;;;;;;EAnEjC,SAAA;EA2FqB;;;;EAtFrB,QAAA;EAoEA;;;;EA/DA,UAAA;EAuEe;;;;EAlEf,kBAAA,GAAqB,0BAA0B;AAAA;AA4E1B;AAGvB;;;;AAQW;AAXY,KAnEX,eAAA;EACV,MAAA;EACA,SAAA,GAAY,SAAA;EACZ,SAAA;EACA,OAAA;IACE,MAAA;IACA,OAAA;IACA,SAAA;IACA,QAAA;IACA,UAAA;IACA,kBAAA,GAAqB,0BAA0B;EAAA;AAAA;;;;;;;;;KAYvC,cAAA;EAoGA;;;;;EA9FV,SAAA;EAgGiB;;;;;EA1FjB,cAAc;AAAA;AAAA,KAGJ,kBAAA;EAuFO;AAAA;;;EAlFjB,QAAA;IAAA,CACG,QAAA,WAAmB,UAAA,CAAW,IAAA;EAAA;;;;;EAMjC,eAAA,GAAkB,eAAA;;;;EAIlB,WAAA,GAAc,iBAAA;;;;EAId,YAAA,GAAe,kBAAA;;;;;;EAMf,QAAA,GAAW,cAAA;;;;EAIX,GAAA,GAAM,eAAA;AAAA;AAAA,KAGI,iBAAA;;;;EAIV,KAAA;;;;EAIA,SAAS;AAAA;;;;KAMC,SAAA;;;;EAIV,WAAA,EAAa,iBAAA;;;;EAIb,YAAA,GAAe,iBAAiB;AAAA;;;;KAMtB,UAAA;;;;EAIV,SAAA;;;;EAIA,EAAA;;;;EAIA,QAAA;;;;;EAKA,QAAA;;;;EAIA,OAAA,GAAU,MAAM;AAAA;AAAA,KAGN,WAAA,kBAA6B,IAAA;EACvC,IAAA,EAAM,QAAA;EACN,MAAA,EAAQ,SAAA;AAAA"}

package/esm/contracts/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../../../auth/src/contracts/types.ts"],"sourcesContent":["import { type ChildModel } from \"@warlock.js/cascade\";\r\nimport { type Algorithm } from \"fast-jwt\";\r\nimport type { AccessToken } from \"../models/access-token\";\r\nimport type { Auth } from \"../models/auth.model\";\r\nimport type { RefreshToken } from \"../models/refresh-token\";\r\n\r\n/**\r\n * Symbol to indicate no expiration for tokens\r\n * Use this when you explicitly want tokens to never expire\r\n *\r\n * @example\r\n * ```typescript\r\n * // src/config/auth.ts\r\n * import { NO_EXPIRATION, type AuthConfigurations } from \"@warlock.js/auth\";\r\n *\r\n * const authConfigurations: AuthConfigurations = {\r\n *   accessToken: {\r\n *     secret: env(\"JWT_SECRET\"),\r\n *     expiresIn: NO_EXPIRATION,  // Token expires within 100 years\r\n *   },\r\n * };\r\n *\r\n * export default authConfigurations;\r\n * ```\r\n */\r\nexport const NO_EXPIRATION = \"100y\";\r\n\r\n/**\r\n * Behavior when logout is called without a refresh token\r\n * - \"revoke-all\": Revoke all refresh tokens for the user (secure default)\r\n * - \"error\": Return an error requiring the refresh token\r\n */\r\nexport type LogoutWithoutTokenBehavior = \"revoke-all\" | \"error\";\n\n/** The single request credential source an auth middleware instance accepts. */\nexport type TokenFrom = \"header\" | `cookie:${string}`;\n\n/** Application policy that decides whether a resolved user may authenticate. */\nexport type CanAuthenticate = (user: Auth) => boolean | Promise<boolean>;\n\n/** Password credentials plus the application-defined identity fields. */\nexport type AuthCredentials = Record<string, unknown> & {\n  password: string;\n};\n\r\n/**\r\n * Access-token configuration.\r\n *\r\n * `secret` may also be supplied via the deprecated `jwt.secret` (resolved by a\r\n * backward-compatible shim); one of the two is required at runtime.\r\n */\r\nexport type AccessTokenConfig = {\r\n  /**\r\n   * Override the persisted access-token model — extend {@link AccessToken} to\r\n   * add columns (e.g. a tenant key) or rename them, then register the subclass\r\n   * here. Defaults to the package's `AccessToken`.\r\n   */\r\n  model?: typeof AccessToken;\r\n  /**\r\n   * Secret used to sign access tokens.\r\n   */\r\n  secret?: string;\r\n  /**\r\n   * JWT algorithm.\r\n   * @default \"HS256\"\r\n   */\r\n  algorithm?: Algorithm;\r\n  /**\r\n   * Access-token lifetime — a duration string `ms` parses to a **positive**\r\n   * number of milliseconds. A value `ms` cannot parse (`\"30dayz\"`), a\r\n   * non-positive one (`\"0d\"`), or a bare number throws naming this key on the\r\n   * first token issue: each of them would otherwise sign a token with no `exp`\r\n   * claim at all.\r\n   * @example \"1h\" or NO_EXPIRATION\r\n   * @default \"1h\"\r\n   */\r\n  expiresIn?: string;\r\n};\r\n\r\n/**\r\n * Refresh-token configuration.\r\n */\r\nexport type RefreshTokenConfig = {\r\n  /**\r\n   * Override the persisted refresh-token model — extend {@link RefreshToken}.\r\n   * Defaults to the package's `RefreshToken`.\r\n   */\r\n  model?: typeof RefreshToken;\r\n  /**\r\n   * Enable refresh tokens.\r\n   * @default true\r\n   */\r\n  enabled?: boolean;\r\n  /**\r\n   * Separate secret for refresh tokens (recommended for security). Falls back\r\n   * to the access-token secret when omitted.\r\n   */\r\n  secret?: string;\r\n  /**\r\n   * Refresh-token lifetime — a duration string `ms` parses to a **positive**\r\n   * number of milliseconds; an unusable value throws naming this key on issue\r\n   * (see {@link AccessTokenConfig.expiresIn}).\r\n   * @example \"7d\" or \"1w\"\r\n   * @default \"7d\"\r\n   */\r\n  expiresIn?: string;\r\n  /**\r\n   * Rotate the refresh token on each use (old token revoked, replay detected).\r\n   * @default true\r\n   */\r\n  rotation?: boolean;\r\n  /**\r\n   * Maximum active refresh tokens per user; the oldest are revoked past it.\r\n   * @default 5\r\n   */\r\n  maxPerUser?: number;\r\n  /**\r\n   * Behavior when logout is called without a refresh token.\r\n   * @default \"revoke-all\"\r\n   */\r\n  logoutWithoutToken?: LogoutWithoutTokenBehavior;\r\n};\r\n\r\n/**\r\n * Legacy JWT configuration shape. Still honored by the resolver shim with a\r\n * deprecation warning.\r\n *\r\n * @deprecated Use the top-level `accessToken` / `refreshToken` blocks.\r\n */\r\nexport type LegacyJwtConfig = {\r\n  secret?: string;\r\n  algorithm?: Algorithm;\r\n  expiresIn?: string;\r\n  refresh?: {\r\n    secret?: string;\r\n    enabled?: boolean;\r\n    expiresIn?: string;\r\n    rotation?: boolean;\r\n    maxPerUser?: number;\r\n    logoutWithoutToken?: LogoutWithoutTokenBehavior;\r\n  };\r\n};\r\n\r\nexport type AuthConfigurations = {\r\n  /**\r\n   * Define all user types — maps a user-type slug to its `Auth` model class so\r\n   * tokens and the middleware can resolve the right model.\r\n   */\r\n  userType: {\n    [userType: string]: ChildModel<Auth>;\n  };\n  /**\n   * Decide whether a resolved user may authenticate or receive new tokens.\n   * @default () => true\n   */\n  canAuthenticate?: CanAuthenticate;\n  /**\r\n   * Access-token configuration (secret, expiry, algorithm, model override).\r\n   */\r\n  accessToken?: AccessTokenConfig;\r\n  /**\r\n   * Refresh-token configuration (rotation, lifetime, cap, model override).\r\n   */\r\n  refreshToken?: RefreshTokenConfig;\r\n  /**\r\n   * @deprecated Use `accessToken` / `refreshToken`. Read via a backward-compatible shim.\r\n   */\r\n  jwt?: LegacyJwtConfig;\r\n};\r\n\r\nexport type AccessTokenOutput = {\r\n  /**\r\n   * JWT Token\r\n   */\r\n  token: string;\r\n  /**\r\n   * Exprie time in ISO format UTC time\r\n   */\r\n  expiresAt: string;\r\n};\r\n\r\n/**\r\n * Token pair returned after login or token refresh\r\n */\r\nexport type TokenPair = {\r\n  /**\r\n   * JWT access token (short-lived)\r\n   */\r\n  accessToken: AccessTokenOutput;\r\n  /**\r\n   * JWT refresh token (long-lived)\r\n   */\r\n  refreshToken?: AccessTokenOutput;\r\n};\r\n\r\n/**\r\n * Device information for session tracking\r\n */\r\nexport type DeviceInfo = {\r\n  /**\r\n   * User agent string from request\r\n   */\r\n  userAgent?: string;\r\n  /**\r\n   * Client IP address\r\n   */\r\n  ip?: string;\r\n  /**\r\n   * Optional device identifier\r\n   */\r\n  deviceId?: string;\r\n  /**\r\n   * Token family ID (for rotation tracking)\r\n   * @internal\r\n   */\r\n  familyId?: string;\r\n  /**\r\n   * Access token payload\r\n   */\r\n  payload?: Record<string, unknown>;\n};\n\r\nexport type LoginResult<UserType extends Auth> = {\r\n  user: UserType;\r\n  tokens: TokenPair;\r\n};\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,gBAAgB"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../../../auth/src/contracts/types.ts"],"sourcesContent":["import { type ChildModel } from \"@warlock.js/cascade\";\r\nimport { type Algorithm } from \"fast-jwt\";\r\nimport type { AccessToken } from \"../models/access-token\";\r\nimport type { Auth } from \"../models/auth.model\";\r\nimport type { RefreshToken } from \"../models/refresh-token\";\r\n\r\n/**\r\n * Symbol to indicate no expiration for tokens\r\n * Use this when you explicitly want tokens to never expire\r\n *\r\n * @example\r\n * ```typescript\r\n * // src/config/auth.ts\r\n * import { NO_EXPIRATION, type AuthConfigurations } from \"@warlock.js/auth\";\r\n *\r\n * const authConfigurations: AuthConfigurations = {\r\n *   accessToken: {\r\n *     secret: env(\"JWT_SECRET\"),\r\n *     expiresIn: NO_EXPIRATION,  // Token expires within 100 years\r\n *   },\r\n * };\r\n *\r\n * export default authConfigurations;\r\n * ```\r\n */\r\nexport const NO_EXPIRATION = \"100y\";\r\n\r\n/**\r\n * Behavior when logout is called without a refresh token\r\n * - \"revoke-all\": Revoke all refresh tokens for the user (secure default)\r\n * - \"error\": Return an error requiring the refresh token\r\n */\r\nexport type LogoutWithoutTokenBehavior = \"revoke-all\" | \"error\";\r\n\r\n/** The single request credential source an auth middleware instance accepts. */\r\nexport type TokenFrom = \"header\" | `cookie:${string}`;\r\n\r\n/** Application policy that decides whether a resolved user may authenticate. */\r\nexport type CanAuthenticate = (user: Auth) => boolean | Promise<boolean>;\r\n\r\n/** Password credentials plus the application-defined identity fields. */\r\nexport type AuthCredentials = Record<string, unknown> & {\r\n  password: string;\r\n};\r\n\r\n/**\r\n * Access-token configuration.\r\n *\r\n * `secret` may also be supplied via the deprecated `jwt.secret` (resolved by a\r\n * backward-compatible shim); one of the two is required at runtime.\r\n */\r\nexport type AccessTokenConfig = {\r\n  /**\r\n   * Override the persisted access-token model — extend {@link AccessToken} to\r\n   * add columns (e.g. a tenant key) or rename them, then register the subclass\r\n   * here. Defaults to the package's `AccessToken`.\r\n   */\r\n  model?: typeof AccessToken;\r\n  /**\r\n   * Secret used to sign access tokens.\r\n   */\r\n  secret?: string;\r\n  /**\r\n   * JWT algorithm.\r\n   * @default \"HS256\"\r\n   */\r\n  algorithm?: Algorithm;\r\n  /**\r\n   * Access-token lifetime — a duration string `ms` parses to a **positive**\r\n   * number of milliseconds. A value `ms` cannot parse (`\"30dayz\"`), a\r\n   * non-positive one (`\"0d\"`), or a bare number throws naming this key on the\r\n   * first token issue: each of them would otherwise sign a token with no `exp`\r\n   * claim at all.\r\n   * @example \"1h\" or NO_EXPIRATION\r\n   * @default \"1h\"\r\n   */\r\n  expiresIn?: string;\r\n};\r\n\r\n/**\r\n * Refresh-token configuration.\r\n */\r\nexport type RefreshTokenConfig = {\r\n  /**\r\n   * Override the persisted refresh-token model — extend {@link RefreshToken}.\r\n   * Defaults to the package's `RefreshToken`.\r\n   */\r\n  model?: typeof RefreshToken;\r\n  /**\r\n   * Enable refresh tokens.\r\n   * @default true\r\n   */\r\n  enabled?: boolean;\r\n  /**\r\n   * Separate secret for refresh tokens (recommended for security). Falls back\r\n   * to the access-token secret when omitted.\r\n   */\r\n  secret?: string;\r\n  /**\r\n   * Refresh-token lifetime — a duration string `ms` parses to a **positive**\r\n   * number of milliseconds; an unusable value throws naming this key on issue\r\n   * (see {@link AccessTokenConfig.expiresIn}).\r\n   * @example \"7d\" or \"1w\"\r\n   * @default \"7d\"\r\n   */\r\n  expiresIn?: string;\r\n  /**\r\n   * Rotate the refresh token on each use (old token revoked, replay detected).\r\n   * @default true\r\n   */\r\n  rotation?: boolean;\r\n  /**\r\n   * Maximum active refresh tokens per user; the oldest are revoked past it.\r\n   * @default 5\r\n   */\r\n  maxPerUser?: number;\r\n  /**\r\n   * Behavior when logout is called without a refresh token.\r\n   * @default \"revoke-all\"\r\n   */\r\n  logoutWithoutToken?: LogoutWithoutTokenBehavior;\r\n};\r\n\r\n/**\r\n * Legacy JWT configuration shape. Still honored by the resolver shim with a\r\n * deprecation warning.\r\n *\r\n * @deprecated Use the top-level `accessToken` / `refreshToken` blocks.\r\n */\r\nexport type LegacyJwtConfig = {\r\n  secret?: string;\r\n  algorithm?: Algorithm;\r\n  expiresIn?: string;\r\n  refresh?: {\r\n    secret?: string;\r\n    enabled?: boolean;\r\n    expiresIn?: string;\r\n    rotation?: boolean;\r\n    maxPerUser?: number;\r\n    logoutWithoutToken?: LogoutWithoutTokenBehavior;\r\n  };\r\n};\r\n\r\n/**\r\n * Page-route auth-failure behavior. When a guarded PAGE route (a React-SSR page,\r\n * `route.isPage`) rejects a logged-out browser, this decides whether it redirects\r\n * to a login page instead of returning the API-style JSON 401.\r\n *\r\n * Read at runtime through `authConfig.pageAuth` (`auth.pageAuth.*`). API routes\r\n * always keep the JSON 401 contract regardless of this setting.\r\n */\r\nexport type PageAuthConfig = {\r\n  /**\r\n   * Login path a guarded page route redirects a logged-out browser to (e.g.\r\n   * `\"/login\"`). Unset ⇒ page-route auth failures keep the JSON 401, so the\r\n   * behavior is opt-in and backward-compatible.\r\n   */\r\n  loginPath?: string;\r\n  /**\r\n   * Query parameter the redirect carries the originally-requested path in, so\r\n   * the login flow can send the user back where they were headed.\r\n   * @default \"returnUrl\"\r\n   */\r\n  returnUrlParam?: string;\r\n};\r\n\r\nexport type AuthConfigurations = {\r\n  /**\r\n   * Define all user types — maps a user-type slug to its `Auth` model class so\r\n   * tokens and the middleware can resolve the right model.\r\n   */\r\n  userType: {\r\n    [userType: string]: ChildModel<Auth>;\r\n  };\r\n  /**\r\n   * Decide whether a resolved user may authenticate or receive new tokens.\r\n   * @default () => true\r\n   */\r\n  canAuthenticate?: CanAuthenticate;\r\n  /**\r\n   * Access-token configuration (secret, expiry, algorithm, model override).\r\n   */\r\n  accessToken?: AccessTokenConfig;\r\n  /**\r\n   * Refresh-token configuration (rotation, lifetime, cap, model override).\r\n   */\r\n  refreshToken?: RefreshTokenConfig;\r\n  /**\r\n   * Page-route auth-failure behavior — set `loginPath` to redirect a logged-out\r\n   * browser on a guarded PAGE route to a login page instead of the JSON 401.\r\n   * Opt-in; API routes are unaffected. Read via `authConfig.pageAuth`.\r\n   */\r\n  pageAuth?: PageAuthConfig;\r\n  /**\r\n   * @deprecated Use `accessToken` / `refreshToken`. Read via a backward-compatible shim.\r\n   */\r\n  jwt?: LegacyJwtConfig;\r\n};\r\n\r\nexport type AccessTokenOutput = {\r\n  /**\r\n   * JWT Token\r\n   */\r\n  token: string;\r\n  /**\r\n   * Exprie time in ISO format UTC time\r\n   */\r\n  expiresAt: string;\r\n};\r\n\r\n/**\r\n * Token pair returned after login or token refresh\r\n */\r\nexport type TokenPair = {\r\n  /**\r\n   * JWT access token (short-lived)\r\n   */\r\n  accessToken: AccessTokenOutput;\r\n  /**\r\n   * JWT refresh token (long-lived)\r\n   */\r\n  refreshToken?: AccessTokenOutput;\r\n};\r\n\r\n/**\r\n * Device information for session tracking\r\n */\r\nexport type DeviceInfo = {\r\n  /**\r\n   * User agent string from request\r\n   */\r\n  userAgent?: string;\r\n  /**\r\n   * Client IP address\r\n   */\r\n  ip?: string;\r\n  /**\r\n   * Optional device identifier\r\n   */\r\n  deviceId?: string;\r\n  /**\r\n   * Token family ID (for rotation tracking)\r\n   * @internal\r\n   */\r\n  familyId?: string;\r\n  /**\r\n   * Access token payload\r\n   */\r\n  payload?: Record<string, unknown>;\r\n};\r\n\r\nexport type LoginResult<UserType extends Auth> = {\r\n  user: UserType;\r\n  tokens: TokenPair;\r\n};\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,gBAAgB"}

package/esm/index.d.mts

@@ -3,7 +3,7 @@ import { registerAuthPurgeNeverExpiringCommand } from "./commands/auth-purge-nev
 import { registerJWTSecretGeneratorCommand } from "./commands/jwt-secret-generator-command.mjs";
 import { Auth } from "./models/auth.model.mjs";
 import { AccessToken, accessTokenSchema } from "./models/access-token/access-token.model.mjs";
-import { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, AuthCredentials, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshTokenConfig, TokenFrom, TokenPair } from "./contracts/types.mjs";
+import { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, AuthCredentials, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, PageAuthConfig, RefreshTokenConfig, TokenFrom, TokenPair } from "./contracts/types.mjs";
 import { RefreshToken, RefreshTokenIssueOptions, refreshTokenSchema } from "./models/refresh-token/refresh-token.model.mjs";
 import { Authenticable } from "./contracts/auth-contract.mjs";
 import { authMiddleware } from "./middleware/auth.middleware.mjs";
@@ -15,4 +15,4 @@ import { generateJWTSecret } from "./services/generate-jwt-secret.mjs";
 import { AuthErrorCodes } from "./utils/auth-error-codes.mjs";
 import { TokenType, TokenTypeError, isInvalidCredentialError, jwt } from "./services/jwt.mjs";
 import { isNeverExpiring, isUsableExpiry, tokenHasExpClaim } from "./utils/token-expiry.mjs";
-export { AccessToken, AccessTokenConfig, AccessTokenOutput, Auth, AuthConfigurations, AuthCredentials, AuthErrorCodes, AuthEventCallback, AuthEventName, AuthEventPayloads, Authenticable, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LoginThrottleIdentifier, LoginThrottleOptions, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshToken, RefreshTokenConfig, RefreshTokenIssueOptions, TokenFrom, TokenPair, TokenType, TokenTypeError, accessTokenSchema, authEvents, authMiddleware, authMigrations, authService, generateJWTSecret, isInvalidCredentialError, isNeverExpiring, isUsableExpiry, jwt, loginThrottleMiddleware, refreshTokenSchema, registerAuthCleanupCommand, registerAuthPurgeNeverExpiringCommand, registerJWTSecretGeneratorCommand, tokenHasExpClaim };
+export { AccessToken, AccessTokenConfig, AccessTokenOutput, Auth, AuthConfigurations, AuthCredentials, AuthErrorCodes, AuthEventCallback, AuthEventName, AuthEventPayloads, Authenticable, CanAuthenticate, DeviceInfo, LegacyJwtConfig, LoginResult, LoginThrottleIdentifier, LoginThrottleOptions, LogoutWithoutTokenBehavior, NO_EXPIRATION, PageAuthConfig, RefreshToken, RefreshTokenConfig, RefreshTokenIssueOptions, TokenFrom, TokenPair, TokenType, TokenTypeError, accessTokenSchema, authEvents, authMiddleware, authMigrations, authService, generateJWTSecret, isInvalidCredentialError, isNeverExpiring, isUsableExpiry, jwt, loginThrottleMiddleware, refreshTokenSchema, registerAuthCleanupCommand, registerAuthPurgeNeverExpiringCommand, registerJWTSecretGeneratorCommand, tokenHasExpClaim };

package/esm/middleware/auth.middleware.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.middleware.d.mts","names":[],"sources":["../../../../../../../auth/src/middleware/auth.middleware.ts"],"mappings":";;;;;;AAmEA;;;;;;;;;AAGa;;;;;;;;;;iBAHG,cAAA,CACd,eAAA,qBACA,SAAA,GAAW,SAAA,GACV,UAAU"}
+{"version":3,"file":"auth.middleware.d.mts","names":[],"sources":["../../../../../../../auth/src/middleware/auth.middleware.ts"],"mappings":";;;;;;AAwGA;;;;;;;;;AAGa;;;;;;;;;;iBAHG,cAAA,CACd,eAAA,qBACA,SAAA,GAAW,SAAA,GACV,UAAU"}

package/esm/middleware/auth.middleware.mjs

@@ -1,5 +1,6 @@
 import { AccessToken } from "../models/access-token/access-token.model.mjs";
 import "../models/access-token/index.mjs";
+import { authConfig } from "../services/auth-config.mjs";
 import { AuthErrorCodes } from "../utils/auth-error-codes.mjs";
 import { isInvalidCredentialError, jwt } from "../services/jwt.mjs";
 import { authService } from "../services/auth.service.mjs";
@@ -8,6 +9,33 @@ import { log } from "@warlock.js/logger";
 
 //#region ../auth/src/middleware/auth.middleware.ts
 /**
+* Reject an unauthenticated request, choosing the representation by ROUTE KIND.
+*
+* An API route always gets the JSON 401 it has always gotten. A PAGE route
+* (`request.route.isPage` — the React-SSR pages) instead redirects a logged-out
+* browser to the configured login path with a `returnUrl`, so a human
+* navigating to a guarded page lands on the login screen rather than reading a
+* raw JSON error blob — the defect in finding b9ab9804.
+*
+* The redirect is OPT-IN and backward-compatible: with no `auth.pageAuth.loginPath`
+* configured, even a page route falls back to the JSON 401, so an app that has
+* not asked for page-login UX keeps exactly its current behavior. The API 401
+* contract is never changed for API routes.
+*
+* `returnUrl` carries `request.url` — the relative path + query the browser was
+* on — never the absolute URL: a relative target cannot be turned into an
+* open-redirect off this app's origin.
+*/
+function rejectUnauthorized({ request, response }, payload) {
+	const loginPath = authConfig.pageAuth.loginPath();
+	if (loginPath && request.route?.isPage) {
+		const separator = loginPath.includes("?") ? "&" : "?";
+		const returnUrl = encodeURIComponent(request.url);
+		return response.redirect(`${loginPath}${separator}${authConfig.pageAuth.returnUrlParam()}=${returnUrl}`);
+	}
+	return response.unauthorized(payload);
+}
+/**
 * Whether the persisted row says the token is dead.
 *
 * The answer belongs to the model (`AccessToken.isExpired`), so a registered
@@ -55,7 +83,10 @@ function authMiddleware(allowedUserType, tokenFrom = "header") {
 	const allowedTypes = Array.isArray(allowedUserType) ? allowedUserType : [allowedUserType];
 	const auth = async ({ request, response }) => {
 		const authorizationValue = readCredential(request, tokenFrom);
-		if (!authorizationValue) return response.unauthorized({
+		if (!authorizationValue) return rejectUnauthorized({
+			request,
+			response
+		}, {
 			error: t("auth.errors.missingAccessToken"),
 			errorCode: "EC001"
 		});
@@ -66,26 +97,38 @@ function authMiddleware(allowedUserType, tokenFrom = "header") {
 			if (!isInvalidCredentialError(error)) throw error;
 			log.error("http", "auth", error);
 			request.clearCurrentUser();
-			return response.unauthorized({
+			return rejectUnauthorized({
+				request,
+				response
+			}, {
 				error: t("auth.errors.invalidAccessToken"),
 				errorCode: "EC002"
 			});
 		}
 		request.decodedAccessToken = decoded;
 		const accessToken = await config.key("auth.accessToken.model", AccessToken).findByToken(authorizationValue);
-		if (!accessToken) return response.unauthorized({
+		if (!accessToken) return rejectUnauthorized({
+			request,
+			response
+		}, {
 			error: t("auth.errors.invalidAccessToken"),
 			errorCode: "EC002"
 		});
 		if (accessTokenRowIsExpired(accessToken)) {
 			await accessToken.destroy();
-			return response.unauthorized({
+			return rejectUnauthorized({
+				request,
+				response
+			}, {
 				error: t("auth.errors.invalidAccessToken"),
 				errorCode: "EC002"
 			});
 		}
 		const userType = decoded.userType ?? accessToken.userType;
-		if (allowedTypes.length && !allowedTypes.includes(userType)) return response.unauthorized({
+		if (allowedTypes.length && !allowedTypes.includes(userType)) return rejectUnauthorized({
+			request,
+			response
+		}, {
 			error: t("auth.errors.unauthorized"),
 			errorCode: "EC003"
 		});
@@ -94,12 +137,18 @@ function authMiddleware(allowedUserType, tokenFrom = "header") {
 		const currentUser = await UserModel.find(decoded.id);
 		if (!currentUser) {
 			await accessToken.destroy();
-			return response.unauthorized({
+			return rejectUnauthorized({
+				request,
+				response
+			}, {
 				error: t("auth.errors.invalidAccessToken"),
 				errorCode: "EC002"
 			});
 		}
-		if (!await authService.canAuthenticate(currentUser)) return response.unauthorized({
+		if (!await authService.canAuthenticate(currentUser)) return rejectUnauthorized({
+			request,
+			response
+		}, {
 			error: t("auth.errors.unauthorized"),
 			errorCode: "EC003"
 		});

package/esm/middleware/auth.middleware.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"auth.middleware.mjs","names":[],"sources":["../../../../../../../auth/src/middleware/auth.middleware.ts"],"sourcesContent":["import { config, t, type Middleware, type Request } from \"@warlock.js/core\";\nimport { log } from \"@warlock.js/logger\";\nimport type { TokenFrom } from \"../contracts/types\";\nimport { AccessToken } from \"../models/access-token\";\nimport { authService } from \"../services/auth.service\";\nimport { isInvalidCredentialError, jwt } from \"../services/jwt\";\nimport { AuthErrorCodes } from \"../utils/auth-error-codes\";\n\r\n/**\r\n * Decoded access-token claims the middleware reads. The full payload carries\r\n * more (`created_at`, `tokenType`, `iat`, `exp`) but only these drive routing.\r\n */\r\ntype DecodedAccessToken = {\r\n  id: string | number;\r\n  userType?: string;\r\n};\r\n\r\n/**\n * Whether the persisted row says the token is dead.\n *\r\n * The answer belongs to the model (`AccessToken.isExpired`), so a registered\r\n * override that renames or reshapes its expiry column stays authoritative and\r\n * the middleware never touches a column name. A row that cannot answer at all —\r\n * an override that dropped the getter — is treated as **expired**: the failure\r\n * mode of this whole defect class was a check that quietly answered \"fine\" when\r\n * it had nothing to check, and that is not repeated here.\r\n *\r\n * This is independent of the `exp` claim required by `jwt.verify`. That guard\r\n * catches a token whose *claims* carry no deadline; this one catches a token\r\n * whose *row* says the deadline has passed — a logged-out or expired session\r\n * whose JWT is still within its own lifetime. Neither subsumes the other.\r\n */\r\nfunction accessTokenRowIsExpired(accessToken: AccessToken): boolean {\n  return typeof accessToken.isExpired === \"boolean\" ? accessToken.isExpired : true;\n}\n\nfunction readCredential(request: Request, tokenFrom: TokenFrom): string {\n  if (tokenFrom === \"header\") {\n    return request.authorizationValue;\n  }\n\n  const value = request.cookie(tokenFrom.slice(\"cookie:\".length));\n\n  return value ? String(value) : \"\";\n}\n\r\n/**\r\n * Build a route gate that always requires an authenticated request.\r\n *\r\n * The argument is mandatory and selects which user types may pass:\r\n * - `[]` — any authenticated user (token required, type not checked).\r\n * - `\"admin\"` / `[\"admin\", \"staff\"]` — token required AND the user's\r\n *   `userType` must be one of the listed types.\r\n *\r\n * There is no anonymous/optional mode: a request without a valid access\n * token is always rejected with `401`. Routes that should be public\n * simply omit the middleware.\n *\n * `tokenFrom` selects one credential source and defaults to `\"header\"`.\n * A single source avoids making credential precedence depend on array order.\n *\r\n * @example\r\n * router.get(\"/account\", authMiddleware([]), accountController);\r\n * router.get(\"/admin\", authMiddleware(\"admin\"), adminController);\n * router.get(\"/back-office\", authMiddleware([\"admin\", \"staff\"]), backOfficeController);\n * router.get(\"/browser-account\", authMiddleware([], \"cookie:token\"), accountController);\n */\nexport function authMiddleware(\n  allowedUserType: string | string[],\n  tokenFrom: TokenFrom = \"header\",\n): Middleware {\n  const allowedTypes = Array.isArray(allowedUserType) ? allowedUserType : [allowedUserType];\r\n\r\n  const auth: Middleware = async ({ request, response }) => {\r\n    const authorizationValue = readCredential(request, tokenFrom);\n\r\n    if (!authorizationValue) {\r\n      return response.unauthorized({\r\n        error: t(\"auth.errors.missingAccessToken\"),\r\n        errorCode: AuthErrorCodes.MissingAccessToken,\r\n      });\r\n    }\r\n\r\n    let decoded: DecodedAccessToken;\r\n\r\n    // The ONLY try in this middleware, and it wraps a single call. Everything\r\n    // after it is storage and configuration, where an exception means the\r\n    // server is broken rather than the caller (D5).\r\n    try {\r\n      decoded = await jwt.verify<DecodedAccessToken>(authorizationValue);\r\n    } catch (error) {\r\n      if (!isInvalidCredentialError(error)) {\r\n        // A DB/cache outage, a missing `JWT_SECRET`, or any other server-side\r\n        // fault — not a verdict on this credential. Propagate to the request's\r\n        // normal error path (a 500 monitoring can see) instead of answering\r\n        // 401 and clearing the caller's session.\r\n        throw error;\r\n      }\r\n\r\n      // A forged, malformed, expired token — or (D6) a `tokenType` mismatch —\r\n      // is not an incident: it is a request carrying a credential the server\r\n      // will never accept.\r\n      log.error(\"http\", \"auth\", error);\r\n\r\n      request.clearCurrentUser();\r\n\r\n      return response.unauthorized({\r\n        error: t(\"auth.errors.invalidAccessToken\"),\r\n        errorCode: AuthErrorCodes.InvalidAccessToken,\r\n      });\r\n    }\r\n\r\n    request.decodedAccessToken = decoded;\r\n\r\n    // A valid signature is not enough — the token must still exist in storage,\r\n    // so deleting the row (logout) invalidates it before its JWT expiry.\r\n    const AccessTokenModel = config.key(\"auth.accessToken.model\", AccessToken);\r\n    const accessToken = await AccessTokenModel.findByToken(authorizationValue);\r\n\r\n    if (!accessToken) {\r\n      return response.unauthorized({\r\n        error: t(\"auth.errors.invalidAccessToken\"),\r\n        errorCode: AuthErrorCodes.InvalidAccessToken,\r\n      });\r\n    }\r\n\r\n    // ... and the row must still be live. Existence alone was the whole check\r\n    // before 4.12.0, so a row whose own `expires_at` had passed still opened\r\n    // the gate. The stored expiry is now enforced, and the dead row is\r\n    // removed on the way out rather than left for the cleanup command.\r\n    if (accessTokenRowIsExpired(accessToken)) {\r\n      await accessToken.destroy();\r\n\r\n      return response.unauthorized({\r\n        error: t(\"auth.errors.invalidAccessToken\"),\r\n        errorCode: AuthErrorCodes.InvalidAccessToken,\r\n      });\r\n    }\r\n\r\n    const userType = decoded.userType ?? accessToken.userType;\r\n\r\n    if (allowedTypes.length && !allowedTypes.includes(userType)) {\r\n      return response.unauthorized({\r\n        error: t(\"auth.errors.unauthorized\"),\r\n        errorCode: AuthErrorCodes.Unauthorized,\r\n      });\r\n    }\r\n\r\n    const UserModel = config.key(`auth.userType.${userType}`);\r\n\r\n    if (!UserModel) {\r\n      // Configuration, not credentials. Throwing keeps a mis-registered app\r\n      // loudly broken instead of quietly rejecting every request of this type.\r\n      throw new Error(`User type ${userType} is unknown type.`);\r\n    }\r\n\r\n    const currentUser = await UserModel.find(decoded.id);\r\n\r\n    if (!currentUser) {\n      await accessToken.destroy();\n\n      return response.unauthorized({\n        error: t(\"auth.errors.invalidAccessToken\"),\n        errorCode: AuthErrorCodes.InvalidAccessToken,\n      });\n    }\n\n    if (!(await authService.canAuthenticate(currentUser))) {\n      return response.unauthorized({\n        error: t(\"auth.errors.unauthorized\"),\n        errorCode: AuthErrorCodes.Unauthorized,\n      });\n    }\n\n    request.user = currentUser;\n  };\r\n\r\n  return auth;\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAS,wBAAwB,aAAmC;CAClE,OAAO,OAAO,YAAY,cAAc,YAAY,YAAY,YAAY;AAC9E;AAEA,SAAS,eAAe,SAAkB,WAA8B;CACtE,IAAI,cAAc,UAChB,OAAO,QAAQ;CAGjB,MAAM,QAAQ,QAAQ,OAAO,UAAU,MAAM,CAAgB,CAAC;CAE9D,OAAO,QAAQ,OAAO,KAAK,IAAI;AACjC;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,eACd,iBACA,YAAuB,UACX;CACZ,MAAM,eAAe,MAAM,QAAQ,eAAe,IAAI,kBAAkB,CAAC,eAAe;CAExF,MAAM,OAAmB,OAAO,EAAE,SAAS,eAAe;EACxD,MAAM,qBAAqB,eAAe,SAAS,SAAS;EAE5D,IAAI,CAAC,oBACH,OAAO,SAAS,aAAa;GAC3B,OAAO,EAAE,gCAAgC;GACzC;EACF,CAAC;EAGH,IAAI;EAKJ,IAAI;GACF,UAAU,MAAM,IAAI,OAA2B,kBAAkB;EACnE,SAAS,OAAO;GACd,IAAI,CAAC,yBAAyB,KAAK,GAKjC,MAAM;GAMR,IAAI,MAAM,QAAQ,QAAQ,KAAK;GAE/B,QAAQ,iBAAiB;GAEzB,OAAO,SAAS,aAAa;IAC3B,OAAO,EAAE,gCAAgC;IACzC;GACF,CAAC;EACH;EAEA,QAAQ,qBAAqB;EAK7B,MAAM,cAAc,MADK,OAAO,IAAI,0BAA0B,WACrB,CAAC,CAAC,YAAY,kBAAkB;EAEzE,IAAI,CAAC,aACH,OAAO,SAAS,aAAa;GAC3B,OAAO,EAAE,gCAAgC;GACzC;EACF,CAAC;EAOH,IAAI,wBAAwB,WAAW,GAAG;GACxC,MAAM,YAAY,QAAQ;GAE1B,OAAO,SAAS,aAAa;IAC3B,OAAO,EAAE,gCAAgC;IACzC;GACF,CAAC;EACH;EAEA,MAAM,WAAW,QAAQ,YAAY,YAAY;EAEjD,IAAI,aAAa,UAAU,CAAC,aAAa,SAAS,QAAQ,GACxD,OAAO,SAAS,aAAa;GAC3B,OAAO,EAAE,0BAA0B;GACnC;EACF,CAAC;EAGH,MAAM,YAAY,OAAO,IAAI,iBAAiB,UAAU;EAExD,IAAI,CAAC,WAGH,MAAM,IAAI,MAAM,aAAa,SAAS,kBAAkB;EAG1D,MAAM,cAAc,MAAM,UAAU,KAAK,QAAQ,EAAE;EAEnD,IAAI,CAAC,aAAa;GAChB,MAAM,YAAY,QAAQ;GAE1B,OAAO,SAAS,aAAa;IAC3B,OAAO,EAAE,gCAAgC;IACzC;GACF,CAAC;EACH;EAEA,IAAI,CAAE,MAAM,YAAY,gBAAgB,WAAW,GACjD,OAAO,SAAS,aAAa;GAC3B,OAAO,EAAE,0BAA0B;GACnC;EACF,CAAC;EAGH,QAAQ,OAAO;CACjB;CAEA,OAAO;AACT"}
+{"version":3,"file":"auth.middleware.mjs","names":[],"sources":["../../../../../../../auth/src/middleware/auth.middleware.ts"],"sourcesContent":["import { config, type HttpContext, t, type Middleware, type Request } from \"@warlock.js/core\";\r\nimport { log } from \"@warlock.js/logger\";\r\nimport type { TokenFrom } from \"../contracts/types\";\r\nimport { AccessToken } from \"../models/access-token\";\r\nimport { authConfig } from \"../services/auth-config\";\r\nimport { authService } from \"../services/auth.service\";\r\nimport { isInvalidCredentialError, jwt } from \"../services/jwt\";\r\nimport { AuthErrorCodes } from \"../utils/auth-error-codes\";\r\n\r\n/** The 401 body shape every rejection in this middleware carries. */\r\ntype UnauthorizedPayload = { error: string; errorCode: string };\r\n\r\n/**\r\n * Reject an unauthenticated request, choosing the representation by ROUTE KIND.\r\n *\r\n * An API route always gets the JSON 401 it has always gotten. A PAGE route\r\n * (`request.route.isPage` — the React-SSR pages) instead redirects a logged-out\r\n * browser to the configured login path with a `returnUrl`, so a human\r\n * navigating to a guarded page lands on the login screen rather than reading a\r\n * raw JSON error blob — the defect in finding b9ab9804.\r\n *\r\n * The redirect is OPT-IN and backward-compatible: with no `auth.pageAuth.loginPath`\r\n * configured, even a page route falls back to the JSON 401, so an app that has\r\n * not asked for page-login UX keeps exactly its current behavior. The API 401\r\n * contract is never changed for API routes.\r\n *\r\n * `returnUrl` carries `request.url` — the relative path + query the browser was\r\n * on — never the absolute URL: a relative target cannot be turned into an\r\n * open-redirect off this app's origin.\r\n */\r\nfunction rejectUnauthorized({ request, response }: HttpContext, payload: UnauthorizedPayload) {\r\n  const loginPath = authConfig.pageAuth.loginPath();\r\n\r\n  if (loginPath && request.route?.isPage) {\r\n    const separator = loginPath.includes(\"?\") ? \"&\" : \"?\";\r\n    const returnUrl = encodeURIComponent(request.url);\r\n\r\n    return response.redirect(\r\n      `${loginPath}${separator}${authConfig.pageAuth.returnUrlParam()}=${returnUrl}`,\r\n    );\r\n  }\r\n\r\n  return response.unauthorized(payload);\r\n}\r\n\r\n/**\r\n * Decoded access-token claims the middleware reads. The full payload carries\r\n * more (`created_at`, `tokenType`, `iat`, `exp`) but only these drive routing.\r\n */\r\ntype DecodedAccessToken = {\r\n  id: string | number;\r\n  userType?: string;\r\n};\r\n\r\n/**\r\n * Whether the persisted row says the token is dead.\r\n *\r\n * The answer belongs to the model (`AccessToken.isExpired`), so a registered\r\n * override that renames or reshapes its expiry column stays authoritative and\r\n * the middleware never touches a column name. A row that cannot answer at all —\r\n * an override that dropped the getter — is treated as **expired**: the failure\r\n * mode of this whole defect class was a check that quietly answered \"fine\" when\r\n * it had nothing to check, and that is not repeated here.\r\n *\r\n * This is independent of the `exp` claim required by `jwt.verify`. That guard\r\n * catches a token whose *claims* carry no deadline; this one catches a token\r\n * whose *row* says the deadline has passed — a logged-out or expired session\r\n * whose JWT is still within its own lifetime. Neither subsumes the other.\r\n */\r\nfunction accessTokenRowIsExpired(accessToken: AccessToken): boolean {\r\n  return typeof accessToken.isExpired === \"boolean\" ? accessToken.isExpired : true;\r\n}\r\n\r\nfunction readCredential(request: Request, tokenFrom: TokenFrom): string {\r\n  if (tokenFrom === \"header\") {\r\n    return request.authorizationValue;\r\n  }\r\n\r\n  const value = request.cookie(tokenFrom.slice(\"cookie:\".length));\r\n\r\n  return value ? String(value) : \"\";\r\n}\r\n\r\n/**\r\n * Build a route gate that always requires an authenticated request.\r\n *\r\n * The argument is mandatory and selects which user types may pass:\r\n * - `[]` — any authenticated user (token required, type not checked).\r\n * - `\"admin\"` / `[\"admin\", \"staff\"]` — token required AND the user's\r\n *   `userType` must be one of the listed types.\r\n *\r\n * There is no anonymous/optional mode: a request without a valid access\r\n * token is always rejected with `401`. Routes that should be public\r\n * simply omit the middleware.\r\n *\r\n * `tokenFrom` selects one credential source and defaults to `\"header\"`.\r\n * A single source avoids making credential precedence depend on array order.\r\n *\r\n * @example\r\n * router.get(\"/account\", authMiddleware([]), accountController);\r\n * router.get(\"/admin\", authMiddleware(\"admin\"), adminController);\r\n * router.get(\"/back-office\", authMiddleware([\"admin\", \"staff\"]), backOfficeController);\r\n * router.get(\"/browser-account\", authMiddleware([], \"cookie:token\"), accountController);\r\n */\r\nexport function authMiddleware(\r\n  allowedUserType: string | string[],\r\n  tokenFrom: TokenFrom = \"header\",\r\n): Middleware {\r\n  const allowedTypes = Array.isArray(allowedUserType) ? allowedUserType : [allowedUserType];\r\n\r\n  const auth: Middleware = async ({ request, response }) => {\r\n    const authorizationValue = readCredential(request, tokenFrom);\r\n\r\n    if (!authorizationValue) {\r\n      return rejectUnauthorized({ request, response }, {\r\n        error: t(\"auth.errors.missingAccessToken\"),\r\n        errorCode: AuthErrorCodes.MissingAccessToken,\r\n      });\r\n    }\r\n\r\n    let decoded: DecodedAccessToken;\r\n\r\n    // The ONLY try in this middleware, and it wraps a single call. Everything\r\n    // after it is storage and configuration, where an exception means the\r\n    // server is broken rather than the caller (D5).\r\n    try {\r\n      decoded = await jwt.verify<DecodedAccessToken>(authorizationValue);\r\n    } catch (error) {\r\n      if (!isInvalidCredentialError(error)) {\r\n        // A DB/cache outage, a missing `JWT_SECRET`, or any other server-side\r\n        // fault — not a verdict on this credential. Propagate to the request's\r\n        // normal error path (a 500 monitoring can see) instead of answering\r\n        // 401 and clearing the caller's session.\r\n        throw error;\r\n      }\r\n\r\n      // A forged, malformed, expired token — or (D6) a `tokenType` mismatch —\r\n      // is not an incident: it is a request carrying a credential the server\r\n      // will never accept.\r\n      log.error(\"http\", \"auth\", error);\r\n\r\n      request.clearCurrentUser();\r\n\r\n      return rejectUnauthorized({ request, response }, {\r\n        error: t(\"auth.errors.invalidAccessToken\"),\r\n        errorCode: AuthErrorCodes.InvalidAccessToken,\r\n      });\r\n    }\r\n\r\n    request.decodedAccessToken = decoded;\r\n\r\n    // A valid signature is not enough — the token must still exist in storage,\r\n    // so deleting the row (logout) invalidates it before its JWT expiry.\r\n    const AccessTokenModel = config.key(\"auth.accessToken.model\", AccessToken);\r\n    const accessToken = await AccessTokenModel.findByToken(authorizationValue);\r\n\r\n    if (!accessToken) {\r\n      return rejectUnauthorized({ request, response }, {\r\n        error: t(\"auth.errors.invalidAccessToken\"),\r\n        errorCode: AuthErrorCodes.InvalidAccessToken,\r\n      });\r\n    }\r\n\r\n    // ... and the row must still be live. Existence alone was the whole check\r\n    // before 4.12.0, so a row whose own `expires_at` had passed still opened\r\n    // the gate. The stored expiry is now enforced, and the dead row is\r\n    // removed on the way out rather than left for the cleanup command.\r\n    if (accessTokenRowIsExpired(accessToken)) {\r\n      await accessToken.destroy();\r\n\r\n      return rejectUnauthorized({ request, response }, {\r\n        error: t(\"auth.errors.invalidAccessToken\"),\r\n        errorCode: AuthErrorCodes.InvalidAccessToken,\r\n      });\r\n    }\r\n\r\n    const userType = decoded.userType ?? accessToken.userType;\r\n\r\n    if (allowedTypes.length && !allowedTypes.includes(userType)) {\r\n      return rejectUnauthorized({ request, response }, {\r\n        error: t(\"auth.errors.unauthorized\"),\r\n        errorCode: AuthErrorCodes.Unauthorized,\r\n      });\r\n    }\r\n\r\n    const UserModel = config.key(`auth.userType.${userType}`);\r\n\r\n    if (!UserModel) {\r\n      // Configuration, not credentials. Throwing keeps a mis-registered app\r\n      // loudly broken instead of quietly rejecting every request of this type.\r\n      throw new Error(`User type ${userType} is unknown type.`);\r\n    }\r\n\r\n    const currentUser = await UserModel.find(decoded.id);\r\n\r\n    if (!currentUser) {\r\n      await accessToken.destroy();\r\n\r\n      return rejectUnauthorized({ request, response }, {\r\n        error: t(\"auth.errors.invalidAccessToken\"),\r\n        errorCode: AuthErrorCodes.InvalidAccessToken,\r\n      });\r\n    }\r\n\r\n    if (!(await authService.canAuthenticate(currentUser))) {\r\n      return rejectUnauthorized({ request, response }, {\r\n        error: t(\"auth.errors.unauthorized\"),\r\n        errorCode: AuthErrorCodes.Unauthorized,\r\n      });\r\n    }\r\n\r\n    request.user = currentUser;\r\n  };\r\n\r\n  return auth;\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAS,mBAAmB,EAAE,SAAS,YAAyB,SAA8B;CAC5F,MAAM,YAAY,WAAW,SAAS,UAAU;CAEhD,IAAI,aAAa,QAAQ,OAAO,QAAQ;EACtC,MAAM,YAAY,UAAU,SAAS,GAAG,IAAI,MAAM;EAClD,MAAM,YAAY,mBAAmB,QAAQ,GAAG;EAEhD,OAAO,SAAS,SACd,GAAG,YAAY,YAAY,WAAW,SAAS,eAAe,EAAE,GAAG,WACrE;CACF;CAEA,OAAO,SAAS,aAAa,OAAO;AACtC;;;;;;;;;;;;;;;;AA0BA,SAAS,wBAAwB,aAAmC;CAClE,OAAO,OAAO,YAAY,cAAc,YAAY,YAAY,YAAY;AAC9E;AAEA,SAAS,eAAe,SAAkB,WAA8B;CACtE,IAAI,cAAc,UAChB,OAAO,QAAQ;CAGjB,MAAM,QAAQ,QAAQ,OAAO,UAAU,MAAM,CAAgB,CAAC;CAE9D,OAAO,QAAQ,OAAO,KAAK,IAAI;AACjC;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,eACd,iBACA,YAAuB,UACX;CACZ,MAAM,eAAe,MAAM,QAAQ,eAAe,IAAI,kBAAkB,CAAC,eAAe;CAExF,MAAM,OAAmB,OAAO,EAAE,SAAS,eAAe;EACxD,MAAM,qBAAqB,eAAe,SAAS,SAAS;EAE5D,IAAI,CAAC,oBACH,OAAO,mBAAmB;GAAE;GAAS;EAAS,GAAG;GAC/C,OAAO,EAAE,gCAAgC;GACzC;EACF,CAAC;EAGH,IAAI;EAKJ,IAAI;GACF,UAAU,MAAM,IAAI,OAA2B,kBAAkB;EACnE,SAAS,OAAO;GACd,IAAI,CAAC,yBAAyB,KAAK,GAKjC,MAAM;GAMR,IAAI,MAAM,QAAQ,QAAQ,KAAK;GAE/B,QAAQ,iBAAiB;GAEzB,OAAO,mBAAmB;IAAE;IAAS;GAAS,GAAG;IAC/C,OAAO,EAAE,gCAAgC;IACzC;GACF,CAAC;EACH;EAEA,QAAQ,qBAAqB;EAK7B,MAAM,cAAc,MADK,OAAO,IAAI,0BAA0B,WACrB,CAAC,CAAC,YAAY,kBAAkB;EAEzE,IAAI,CAAC,aACH,OAAO,mBAAmB;GAAE;GAAS;EAAS,GAAG;GAC/C,OAAO,EAAE,gCAAgC;GACzC;EACF,CAAC;EAOH,IAAI,wBAAwB,WAAW,GAAG;GACxC,MAAM,YAAY,QAAQ;GAE1B,OAAO,mBAAmB;IAAE;IAAS;GAAS,GAAG;IAC/C,OAAO,EAAE,gCAAgC;IACzC;GACF,CAAC;EACH;EAEA,MAAM,WAAW,QAAQ,YAAY,YAAY;EAEjD,IAAI,aAAa,UAAU,CAAC,aAAa,SAAS,QAAQ,GACxD,OAAO,mBAAmB;GAAE;GAAS;EAAS,GAAG;GAC/C,OAAO,EAAE,0BAA0B;GACnC;EACF,CAAC;EAGH,MAAM,YAAY,OAAO,IAAI,iBAAiB,UAAU;EAExD,IAAI,CAAC,WAGH,MAAM,IAAI,MAAM,aAAa,SAAS,kBAAkB;EAG1D,MAAM,cAAc,MAAM,UAAU,KAAK,QAAQ,EAAE;EAEnD,IAAI,CAAC,aAAa;GAChB,MAAM,YAAY,QAAQ;GAE1B,OAAO,mBAAmB;IAAE;IAAS;GAAS,GAAG;IAC/C,OAAO,EAAE,gCAAgC;IACzC;GACF,CAAC;EACH;EAEA,IAAI,CAAE,MAAM,YAAY,gBAAgB,WAAW,GACjD,OAAO,mBAAmB;GAAE;GAAS;EAAS,GAAG;GAC/C,OAAO,EAAE,0BAA0B;GACnC;EACF,CAAC;EAGH,QAAQ,OAAO;CACjB;CAEA,OAAO;AACT"}

package/esm/models/access-token/migration.mjs

@@ -8,7 +8,7 @@ const AccessTokenMigration = migrate(AccessToken, {
 		this.createTableIfNotExists();
 		this.primaryUuid();
 		this.text("token").unique();
-		this.uuid("user_id").index();
+		this.foreignId("user_id").index();
 		this.string("user_type", 50).nullable();
 		this.timestamp("expires_at").index().nullable();
 		this.timestamps();

package/esm/models/access-token/migration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration.mjs","names":[],"sources":["../../../../../../../../auth/src/models/access-token/migration.ts"],"sourcesContent":["import { migrate } from \"@warlock.js/cascade\";\r\nimport { AccessToken } from \"./access-token.model\";\r\n\r\nexport const AccessTokenMigration = migrate(AccessToken, {\r\n  name: \"accessToken\",\r\n  up() {\r\n    // Create table\r\n    this.createTableIfNotExists();\r\n\r\n    // Primary key\r\n    this.primaryUuid();\r\n\r\n    // Token field\r\n    this.text(\"token\").unique();\r\n\r\n    // User reference (flat columns for cross-driver compatibility)\r\n    this.uuid(\"user_id\").index();\r\n    this.string(\"user_type\", 50).nullable();\r\n\r\n    // Expiry — enables server-side cleanup of stale access-token rows\r\n    this.timestamp(\"expires_at\").index().nullable();\r\n\r\n    // Timestamps\r\n    this.timestamps();\r\n  },\r\n  down() {\r\n    this.dropTableIfExists();\r\n  },\r\n});\r\n"],"mappings":";;;;AAGA,MAAa,uBAAuB,QAAQ,aAAa;CACvD,MAAM;CACN,KAAK;EAEH,KAAK,uBAAuB;EAG5B,KAAK,YAAY;EAGjB,KAAK,KAAK,OAAO,CAAC,CAAC,OAAO;EAG1B,KAAK,KAAK,SAAS,CAAC,CAAC,MAAM;EAC3B,KAAK,OAAO,aAAa,EAAE,CAAC,CAAC,SAAS;EAGtC,KAAK,UAAU,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS;EAG9C,KAAK,WAAW;CAClB;CACA,OAAO;EACL,KAAK,kBAAkB;CACzB;AACF,CAAC"}
+{"version":3,"file":"migration.mjs","names":[],"sources":["../../../../../../../../auth/src/models/access-token/migration.ts"],"sourcesContent":["import { migrate } from \"@warlock.js/cascade\";\r\nimport { AccessToken } from \"./access-token.model\";\r\n\r\nexport const AccessTokenMigration = migrate(AccessToken, {\r\n  name: \"accessToken\",\r\n  up() {\r\n    // Create table\r\n    this.createTableIfNotExists();\r\n\r\n    // Primary key\r\n    this.primaryUuid();\r\n\r\n    // Token field\r\n    this.text(\"token\").unique();\r\n\r\n    // User reference (flat columns for cross-driver compatibility).\r\n    // `foreignId` matches the DataSource's default primary-key type, so the\r\n    // column stays compatible with the user model's `id` whether the app uses\r\n    // integer (the default) or uuid PKs — hardcoding uuid here 500'd every\r\n    // login on a default integer-PK app (finding 5e47bdb3).\r\n    this.foreignId(\"user_id\").index();\r\n    this.string(\"user_type\", 50).nullable();\r\n\r\n    // Expiry — enables server-side cleanup of stale access-token rows\r\n    this.timestamp(\"expires_at\").index().nullable();\r\n\r\n    // Timestamps\r\n    this.timestamps();\r\n  },\r\n  down() {\r\n    this.dropTableIfExists();\r\n  },\r\n});\r\n"],"mappings":";;;;AAGA,MAAa,uBAAuB,QAAQ,aAAa;CACvD,MAAM;CACN,KAAK;EAEH,KAAK,uBAAuB;EAG5B,KAAK,YAAY;EAGjB,KAAK,KAAK,OAAO,CAAC,CAAC,OAAO;EAO1B,KAAK,UAAU,SAAS,CAAC,CAAC,MAAM;EAChC,KAAK,OAAO,aAAa,EAAE,CAAC,CAAC,SAAS;EAGtC,KAAK,UAAU,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS;EAG9C,KAAK,WAAW;CAClB;CACA,OAAO;EACL,KAAK,kBAAkB;CACzB;AACF,CAAC"}

package/esm/models/refresh-token/migration.mjs

@@ -8,7 +8,7 @@ const RefreshTokenMigration = migrate(RefreshToken, {
 		this.createTableIfNotExists();
 		this.primaryUuid();
 		this.text("token").unique();
-		this.uuid("user_id").index();
+		this.foreignId("user_id").index();
 		this.string("user_type", 50).nullable();
 		this.text("family_id").index().nullable();
 		this.timestamp("expires_at").index().nullable();

package/esm/models/refresh-token/migration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration.mjs","names":[],"sources":["../../../../../../../../auth/src/models/refresh-token/migration.ts"],"sourcesContent":["import { migrate } from \"@warlock.js/cascade\";\r\nimport { RefreshToken } from \"./refresh-token.model\";\r\n\r\nexport const RefreshTokenMigration = migrate(RefreshToken, {\r\n  name: \"refreshToken\",\r\n  up() {\r\n    // Create table\r\n    this.createTableIfNotExists();\r\n\r\n    // Primary key\r\n    this.primaryUuid();\r\n\r\n    // Token fields\r\n    this.text(\"token\").unique();\r\n    this.uuid(\"user_id\").index();\r\n    this.string(\"user_type\", 50).nullable();\r\n    this.text(\"family_id\").index().nullable();\r\n    this.timestamp(\"expires_at\").index().nullable();\r\n    this.timestamp(\"last_used_at\").nullable();\r\n    this.timestamp(\"revoked_at\").nullable();\r\n    this.json(\"device_info\").nullable();\r\n\r\n    // Composite index for the per-user active-session lookups\r\n    // (revokeAllFor / enforceMax / activeFor all filter on user_id + user_type).\r\n    this.index([\"user_id\", \"user_type\"]);\r\n\r\n    // Timestamps\r\n    this.timestamps();\r\n  },\r\n  down() {\r\n    this.dropTableIfExists();\r\n  },\r\n});\r\n"],"mappings":";;;;AAGA,MAAa,wBAAwB,QAAQ,cAAc;CACzD,MAAM;CACN,KAAK;EAEH,KAAK,uBAAuB;EAG5B,KAAK,YAAY;EAGjB,KAAK,KAAK,OAAO,CAAC,CAAC,OAAO;EAC1B,KAAK,KAAK,SAAS,CAAC,CAAC,MAAM;EAC3B,KAAK,OAAO,aAAa,EAAE,CAAC,CAAC,SAAS;EACtC,KAAK,KAAK,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS;EACxC,KAAK,UAAU,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS;EAC9C,KAAK,UAAU,cAAc,CAAC,CAAC,SAAS;EACxC,KAAK,UAAU,YAAY,CAAC,CAAC,SAAS;EACtC,KAAK,KAAK,aAAa,CAAC,CAAC,SAAS;EAIlC,KAAK,MAAM,CAAC,WAAW,WAAW,CAAC;EAGnC,KAAK,WAAW;CAClB;CACA,OAAO;EACL,KAAK,kBAAkB;CACzB;AACF,CAAC"}
+{"version":3,"file":"migration.mjs","names":[],"sources":["../../../../../../../../auth/src/models/refresh-token/migration.ts"],"sourcesContent":["import { migrate } from \"@warlock.js/cascade\";\r\nimport { RefreshToken } from \"./refresh-token.model\";\r\n\r\nexport const RefreshTokenMigration = migrate(RefreshToken, {\r\n  name: \"refreshToken\",\r\n  up() {\r\n    // Create table\r\n    this.createTableIfNotExists();\r\n\r\n    // Primary key\r\n    this.primaryUuid();\r\n\r\n    // Token fields\r\n    this.text(\"token\").unique();\r\n    // `foreignId` matches the DataSource's default primary-key type so the\r\n    // column stays compatible with the user model's `id` (integer by default,\r\n    // or uuid) — hardcoding uuid here 500'd login on integer-PK apps (5e47bdb3).\r\n    this.foreignId(\"user_id\").index();\r\n    this.string(\"user_type\", 50).nullable();\r\n    this.text(\"family_id\").index().nullable();\r\n    this.timestamp(\"expires_at\").index().nullable();\r\n    this.timestamp(\"last_used_at\").nullable();\r\n    this.timestamp(\"revoked_at\").nullable();\r\n    this.json(\"device_info\").nullable();\r\n\r\n    // Composite index for the per-user active-session lookups\r\n    // (revokeAllFor / enforceMax / activeFor all filter on user_id + user_type).\r\n    this.index([\"user_id\", \"user_type\"]);\r\n\r\n    // Timestamps\r\n    this.timestamps();\r\n  },\r\n  down() {\r\n    this.dropTableIfExists();\r\n  },\r\n});\r\n"],"mappings":";;;;AAGA,MAAa,wBAAwB,QAAQ,cAAc;CACzD,MAAM;CACN,KAAK;EAEH,KAAK,uBAAuB;EAG5B,KAAK,YAAY;EAGjB,KAAK,KAAK,OAAO,CAAC,CAAC,OAAO;EAI1B,KAAK,UAAU,SAAS,CAAC,CAAC,MAAM;EAChC,KAAK,OAAO,aAAa,EAAE,CAAC,CAAC,SAAS;EACtC,KAAK,KAAK,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS;EACxC,KAAK,UAAU,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS;EAC9C,KAAK,UAAU,cAAc,CAAC,CAAC,SAAS;EACxC,KAAK,UAAU,YAAY,CAAC,CAAC,SAAS;EACtC,KAAK,KAAK,aAAa,CAAC,CAAC,SAAS;EAIlC,KAAK,MAAM,CAAC,WAAW,WAAW,CAAC;EAGnC,KAAK,WAAW;CAClB;CACA,OAAO;EACL,KAAK,kBAAkB;CACzB;AACF,CAAC"}

package/esm/services/auth-config.mjs

@@ -92,6 +92,24 @@ const authConfig = {
 		*/
 		expiresInMs: () => parseDuration("accessToken.expiresIn", authConfig.accessToken.expiresIn() ?? DEFAULT_ACCESS_TOKEN_EXPIRES_IN)
 	},
+	pageAuth: {
+		/**
+		* Login path a guarded PAGE route redirects a logged-out browser to.
+		*
+		* Unset (the default) ⇒ page-route auth failures keep the JSON 401 API
+		* contract, so existing apps see NO behavior change. Set it (e.g. "/login")
+		* to opt a browser-facing app into login-redirect UX: a logged-out human
+		* navigating to a guarded page lands on the login screen instead of reading
+		* a raw JSON error blob. Finding b9ab9804.
+		*/
+		loginPath: () => config.key("auth.pageAuth.loginPath"),
+		/**
+		* Query parameter the redirect carries the originally-requested path in, so
+		* the login flow can send the user back where they were headed. Defaults to
+		* `"returnUrl"`.
+		*/
+		returnUrlParam: () => config.key("auth.pageAuth.returnUrlParam", "returnUrl")
+	},
 	refreshToken: {
 		/** Separate refresh secret (legacy: `auth.jwt.refresh.secret`); empty ⇒ fall back to the access secret. */
 		secret: () => resolve("refreshToken.secret", "jwt.refresh.secret"),

package/esm/services/auth-config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"auth-config.mjs","names":[],"sources":["../../../../../../../auth/src/services/auth-config.ts"],"sourcesContent":["import { config } from \"@warlock.js/core\";\r\nimport { log } from \"@warlock.js/logger\";\r\nimport { type Algorithm } from \"fast-jwt\";\r\nimport ms from \"ms\";\r\nimport type { CanAuthenticate, LogoutWithoutTokenBehavior } from \"../contracts/types\";\nimport type { Auth } from \"../models/auth.model\";\n\nconst warnedLegacyKeys = new Set<string>();\n\nconst permitAuthentication: CanAuthenticate = (): boolean => true;\n\r\n/**\r\n * `ms` accepts anything at runtime and answers `undefined` for a string it\r\n * cannot parse (`\"30dayz\"`), a *formatted string* for a number (`2592000` ⇒\r\n * `\"43m\"`), and throws for `\"\"`. Its published types claim the far narrower\r\n * `(value: ms.StringValue) => number`, which is exactly what let an\r\n * `as ms.StringValue` cast smuggle arbitrary config text past the compiler and\r\n * hand `undefined` to the JWT signer. Declare the honest runtime signature once,\r\n * here, so every caller is forced to deal with the `undefined`.\r\n */\r\nconst parseMs = ms as unknown as (value: unknown) => number | string | undefined;\r\n\r\n/**\r\n * Turn a configured lifetime into a positive number of milliseconds, or throw\r\n * naming the key.\r\n *\r\n * A token lifetime is a security boundary, so an unusable value is a hard error\r\n * rather than a silent fallback: substituting a default would trade one\r\n * unintended lifetime for another, just as quietly — and quiet is the whole\r\n * problem. Every non-positive, non-finite or non-numeric parse is rejected:\r\n *\r\n * - `\"30dayz\"` / `\"thirty days\"` ⇒ `undefined` ⇒ a JWT signed with **no `exp`\r\n *   claim** and an `Invalid Date` written to the token row.\r\n * - `\"0d\"` ⇒ parses cleanly to `0`, which `fast-jwt` treats as falsy and also\r\n *   emits with **no `exp` claim** — it survives any guard that only rejects\r\n *   `undefined`. `\"-1h\"` signs an already-expired token.\r\n * - `2592000` (a bare number) ⇒ `ms` *formats* it as `\"43m\"`, a string, which\r\n *   then turns `Date.now() + expiresIn` into an `Invalid Date`.\r\n */\r\nfunction parseDuration(key: string, raw: unknown): number {\r\n  let parsed: number | string | undefined;\r\n\r\n  try {\r\n    parsed = parseMs(raw);\r\n  } catch {\r\n    // ms throws (rather than returning undefined) for \"\" and non-strings\r\n    parsed = undefined;\r\n  }\r\n\r\n  if (typeof parsed !== \"number\" || !Number.isFinite(parsed) || parsed <= 0) {\r\n    throw new Error(\r\n      `auth.${key}: ${JSON.stringify(raw)} is not a valid ms duration — ` +\r\n        `use a positive duration string such as \"1h\", \"7d\", or NO_EXPIRATION.`,\r\n    );\r\n  }\r\n\r\n  return parsed;\r\n}\r\n\r\n/** Access-token lifetime used when nothing is configured. */\r\nconst DEFAULT_ACCESS_TOKEN_EXPIRES_IN = \"1h\";\r\n\r\n/**\r\n * Resolve an auth setting, preferring the new `auth.accessToken.*` /\r\n * `auth.refreshToken.*` key and falling back to the deprecated `auth.jwt.*`\r\n * shape — warning once per legacy key. Returns `fallback` when neither is set.\r\n *\r\n * This is the backward-compatible shim that lets existing `auth.jwt.*` configs\r\n * keep working after the config split.\r\n */\r\nfunction resolve<T>(newKey: string, legacyKey: string, fallback?: T): T {\r\n  const fromNew = config.key(`auth.${newKey}`);\r\n\r\n  if (fromNew !== undefined && fromNew !== null) {\r\n    return fromNew as T;\r\n  }\r\n\r\n  const fromLegacy = config.key(`auth.${legacyKey}`);\r\n\r\n  if (fromLegacy !== undefined && fromLegacy !== null) {\r\n    if (!warnedLegacyKeys.has(legacyKey)) {\r\n      warnedLegacyKeys.add(legacyKey);\r\n      log.warn(\"auth\", \"config-deprecation\", `auth.${legacyKey} is deprecated — use auth.${newKey}`);\r\n    }\r\n\r\n    return fromLegacy as T;\r\n  }\r\n\r\n  return fallback as T;\r\n}\r\n\r\n/**\r\n * Typed, backward-compatible access to auth configuration. The service and the\r\n * jwt signer read configuration exclusively through here, so the new split\r\n * config and the legacy `auth.jwt.*` shape both resolve the same way.\r\n */\r\nexport const authConfig = {\n  canAuthenticate: async (user: Auth): Promise<boolean> => {\n    const canAuthenticate = config.key<CanAuthenticate>(\n      \"auth.canAuthenticate\",\n      permitAuthentication,\n    );\n\n    return canAuthenticate(user);\n  },\n  accessToken: {\n    /** Signing secret (legacy: `auth.jwt.secret`). Throws if neither is set. */\r\n    secret: (): string => {\r\n      const secret = resolve<string | undefined>(\"accessToken.secret\", \"jwt.secret\");\r\n\r\n      if (!secret) {\r\n        throw new Error(\"auth: no JWT secret configured — set `auth.accessToken.secret`.\");\r\n      }\r\n\r\n      return secret;\r\n    },\r\n    /** Signing algorithm (legacy: `auth.jwt.algorithm`). */\r\n    algorithm: (): Algorithm => resolve(\"accessToken.algorithm\", \"jwt.algorithm\", \"HS256\"),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.expiresIn`). */\r\n    expiresIn: (): string | undefined => resolve(\"accessToken.expiresIn\", \"jwt.expiresIn\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Defaults\r\n     * to 1 hour when unset; throws naming the key when the configured value is\r\n     * not a positive `ms` duration. See {@link parseDuration}.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\r\n        \"accessToken.expiresIn\",\r\n        authConfig.accessToken.expiresIn() ?? DEFAULT_ACCESS_TOKEN_EXPIRES_IN,\r\n      ),\r\n  },\r\n  refreshToken: {\r\n    /** Separate refresh secret (legacy: `auth.jwt.refresh.secret`); empty ⇒ fall back to the access secret. */\r\n    secret: (): string | undefined => resolve(\"refreshToken.secret\", \"jwt.refresh.secret\"),\r\n    /** Whether refresh tokens are enabled (legacy: `auth.jwt.refresh.enabled`). */\r\n    enabled: (): boolean => resolve(\"refreshToken.enabled\", \"jwt.refresh.enabled\", true),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.refresh.expiresIn`). */\r\n    expiresIn: (): string => resolve(\"refreshToken.expiresIn\", \"jwt.refresh.expiresIn\", \"7d\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Throws\r\n     * naming the key when the configured value is not a positive `ms` duration.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\"refreshToken.expiresIn\", authConfig.refreshToken.expiresIn()),\r\n    /** Rotate-on-use (legacy: `auth.jwt.refresh.rotation`). */\r\n    rotation: (): boolean => resolve(\"refreshToken.rotation\", \"jwt.refresh.rotation\", true),\r\n    /** Max active tokens per user (legacy: `auth.jwt.refresh.maxPerUser`). */\r\n    maxPerUser: (): number => resolve(\"refreshToken.maxPerUser\", \"jwt.refresh.maxPerUser\", 5),\r\n    /** Logout-without-token behavior (legacy: `auth.jwt.refresh.logoutWithoutToken`). */\r\n    logoutWithoutToken: (): LogoutWithoutTokenBehavior =>\r\n      resolve(\"refreshToken.logoutWithoutToken\", \"jwt.refresh.logoutWithoutToken\", \"revoke-all\"),\r\n  },\r\n};\r\n"],"mappings":";;;;;AAOA,MAAM,mCAAmB,IAAI,IAAY;AAEzC,MAAM,6BAAuD;;;;;;;;;;AAW7D,MAAM,UAAU;;;;;;;;;;;;;;;;;;AAmBhB,SAAS,cAAc,KAAa,KAAsB;CACxD,IAAI;CAEJ,IAAI;EACF,SAAS,QAAQ,GAAG;CACtB,QAAQ;EAEN,SAAS;CACX;CAEA,IAAI,OAAO,WAAW,YAAY,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,GACtE,MAAM,IAAI,MACR,QAAQ,IAAI,IAAI,KAAK,UAAU,GAAG,EAAE,mGAEtC;CAGF,OAAO;AACT;;AAGA,MAAM,kCAAkC;;;;;;;;;AAUxC,SAAS,QAAW,QAAgB,WAAmB,UAAiB;CACtE,MAAM,UAAU,OAAO,IAAI,QAAQ,QAAQ;CAE3C,IAAI,YAAY,UAAa,YAAY,MACvC,OAAO;CAGT,MAAM,aAAa,OAAO,IAAI,QAAQ,WAAW;CAEjD,IAAI,eAAe,UAAa,eAAe,MAAM;EACnD,IAAI,CAAC,iBAAiB,IAAI,SAAS,GAAG;GACpC,iBAAiB,IAAI,SAAS;GAC9B,IAAI,KAAK,QAAQ,sBAAsB,QAAQ,UAAU,4BAA4B,QAAQ;EAC/F;EAEA,OAAO;CACT;CAEA,OAAO;AACT;;;;;;AAOA,MAAa,aAAa;CACxB,iBAAiB,OAAO,SAAiC;EAMvD,OALwB,OAAO,IAC7B,wBACA,oBAGmB,CAAC,CAAC,IAAI;CAC7B;CACA,aAAa;;EAEX,cAAsB;GACpB,MAAM,SAAS,QAA4B,sBAAsB,YAAY;GAE7E,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,iEAAiE;GAGnF,OAAO;EACT;;EAEA,iBAA4B,QAAQ,yBAAyB,iBAAiB,OAAO;;EAErF,iBAAqC,QAAQ,yBAAyB,eAAe;;;;;;EAMrF,mBACE,cACE,yBACA,WAAW,YAAY,UAAU,KAAK,+BACxC;CACJ;CACA,cAAc;;EAEZ,cAAkC,QAAQ,uBAAuB,oBAAoB;;EAErF,eAAwB,QAAQ,wBAAwB,uBAAuB,IAAI;;EAEnF,iBAAyB,QAAQ,0BAA0B,yBAAyB,IAAI;;;;;EAKxF,mBACE,cAAc,0BAA0B,WAAW,aAAa,UAAU,CAAC;;EAE7E,gBAAyB,QAAQ,yBAAyB,wBAAwB,IAAI;;EAEtF,kBAA0B,QAAQ,2BAA2B,0BAA0B,CAAC;;EAExF,0BACE,QAAQ,mCAAmC,kCAAkC,YAAY;CAC7F;AACF"}
+{"version":3,"file":"auth-config.mjs","names":[],"sources":["../../../../../../../auth/src/services/auth-config.ts"],"sourcesContent":["import { config } from \"@warlock.js/core\";\r\nimport { log } from \"@warlock.js/logger\";\r\nimport { type Algorithm } from \"fast-jwt\";\r\nimport ms from \"ms\";\r\nimport type { CanAuthenticate, LogoutWithoutTokenBehavior } from \"../contracts/types\";\r\nimport type { Auth } from \"../models/auth.model\";\r\n\r\nconst warnedLegacyKeys = new Set<string>();\r\n\r\nconst permitAuthentication: CanAuthenticate = (): boolean => true;\r\n\r\n/**\r\n * `ms` accepts anything at runtime and answers `undefined` for a string it\r\n * cannot parse (`\"30dayz\"`), a *formatted string* for a number (`2592000` ⇒\r\n * `\"43m\"`), and throws for `\"\"`. Its published types claim the far narrower\r\n * `(value: ms.StringValue) => number`, which is exactly what let an\r\n * `as ms.StringValue` cast smuggle arbitrary config text past the compiler and\r\n * hand `undefined` to the JWT signer. Declare the honest runtime signature once,\r\n * here, so every caller is forced to deal with the `undefined`.\r\n */\r\nconst parseMs = ms as unknown as (value: unknown) => number | string | undefined;\r\n\r\n/**\r\n * Turn a configured lifetime into a positive number of milliseconds, or throw\r\n * naming the key.\r\n *\r\n * A token lifetime is a security boundary, so an unusable value is a hard error\r\n * rather than a silent fallback: substituting a default would trade one\r\n * unintended lifetime for another, just as quietly — and quiet is the whole\r\n * problem. Every non-positive, non-finite or non-numeric parse is rejected:\r\n *\r\n * - `\"30dayz\"` / `\"thirty days\"` ⇒ `undefined` ⇒ a JWT signed with **no `exp`\r\n *   claim** and an `Invalid Date` written to the token row.\r\n * - `\"0d\"` ⇒ parses cleanly to `0`, which `fast-jwt` treats as falsy and also\r\n *   emits with **no `exp` claim** — it survives any guard that only rejects\r\n *   `undefined`. `\"-1h\"` signs an already-expired token.\r\n * - `2592000` (a bare number) ⇒ `ms` *formats* it as `\"43m\"`, a string, which\r\n *   then turns `Date.now() + expiresIn` into an `Invalid Date`.\r\n */\r\nfunction parseDuration(key: string, raw: unknown): number {\r\n  let parsed: number | string | undefined;\r\n\r\n  try {\r\n    parsed = parseMs(raw);\r\n  } catch {\r\n    // ms throws (rather than returning undefined) for \"\" and non-strings\r\n    parsed = undefined;\r\n  }\r\n\r\n  if (typeof parsed !== \"number\" || !Number.isFinite(parsed) || parsed <= 0) {\r\n    throw new Error(\r\n      `auth.${key}: ${JSON.stringify(raw)} is not a valid ms duration — ` +\r\n        `use a positive duration string such as \"1h\", \"7d\", or NO_EXPIRATION.`,\r\n    );\r\n  }\r\n\r\n  return parsed;\r\n}\r\n\r\n/** Access-token lifetime used when nothing is configured. */\r\nconst DEFAULT_ACCESS_TOKEN_EXPIRES_IN = \"1h\";\r\n\r\n/**\r\n * Resolve an auth setting, preferring the new `auth.accessToken.*` /\r\n * `auth.refreshToken.*` key and falling back to the deprecated `auth.jwt.*`\r\n * shape — warning once per legacy key. Returns `fallback` when neither is set.\r\n *\r\n * This is the backward-compatible shim that lets existing `auth.jwt.*` configs\r\n * keep working after the config split.\r\n */\r\nfunction resolve<T>(newKey: string, legacyKey: string, fallback?: T): T {\r\n  const fromNew = config.key(`auth.${newKey}`);\r\n\r\n  if (fromNew !== undefined && fromNew !== null) {\r\n    return fromNew as T;\r\n  }\r\n\r\n  const fromLegacy = config.key(`auth.${legacyKey}`);\r\n\r\n  if (fromLegacy !== undefined && fromLegacy !== null) {\r\n    if (!warnedLegacyKeys.has(legacyKey)) {\r\n      warnedLegacyKeys.add(legacyKey);\r\n      log.warn(\"auth\", \"config-deprecation\", `auth.${legacyKey} is deprecated — use auth.${newKey}`);\r\n    }\r\n\r\n    return fromLegacy as T;\r\n  }\r\n\r\n  return fallback as T;\r\n}\r\n\r\n/**\r\n * Typed, backward-compatible access to auth configuration. The service and the\r\n * jwt signer read configuration exclusively through here, so the new split\r\n * config and the legacy `auth.jwt.*` shape both resolve the same way.\r\n */\r\nexport const authConfig = {\r\n  canAuthenticate: async (user: Auth): Promise<boolean> => {\r\n    const canAuthenticate = config.key<CanAuthenticate>(\r\n      \"auth.canAuthenticate\",\r\n      permitAuthentication,\r\n    );\r\n\r\n    return canAuthenticate(user);\r\n  },\r\n  accessToken: {\r\n    /** Signing secret (legacy: `auth.jwt.secret`). Throws if neither is set. */\r\n    secret: (): string => {\r\n      const secret = resolve<string | undefined>(\"accessToken.secret\", \"jwt.secret\");\r\n\r\n      if (!secret) {\r\n        throw new Error(\"auth: no JWT secret configured — set `auth.accessToken.secret`.\");\r\n      }\r\n\r\n      return secret;\r\n    },\r\n    /** Signing algorithm (legacy: `auth.jwt.algorithm`). */\r\n    algorithm: (): Algorithm => resolve(\"accessToken.algorithm\", \"jwt.algorithm\", \"HS256\"),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.expiresIn`). */\r\n    expiresIn: (): string | undefined => resolve(\"accessToken.expiresIn\", \"jwt.expiresIn\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Defaults\r\n     * to 1 hour when unset; throws naming the key when the configured value is\r\n     * not a positive `ms` duration. See {@link parseDuration}.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\r\n        \"accessToken.expiresIn\",\r\n        authConfig.accessToken.expiresIn() ?? DEFAULT_ACCESS_TOKEN_EXPIRES_IN,\r\n      ),\r\n  },\r\n  pageAuth: {\r\n    /**\r\n     * Login path a guarded PAGE route redirects a logged-out browser to.\r\n     *\r\n     * Unset (the default) ⇒ page-route auth failures keep the JSON 401 API\r\n     * contract, so existing apps see NO behavior change. Set it (e.g. \"/login\")\r\n     * to opt a browser-facing app into login-redirect UX: a logged-out human\r\n     * navigating to a guarded page lands on the login screen instead of reading\r\n     * a raw JSON error blob. Finding b9ab9804.\r\n     */\r\n    loginPath: (): string | undefined => config.key(\"auth.pageAuth.loginPath\"),\r\n    /**\r\n     * Query parameter the redirect carries the originally-requested path in, so\r\n     * the login flow can send the user back where they were headed. Defaults to\r\n     * `\"returnUrl\"`.\r\n     */\r\n    returnUrlParam: (): string => config.key(\"auth.pageAuth.returnUrlParam\", \"returnUrl\"),\r\n  },\r\n  refreshToken: {\r\n    /** Separate refresh secret (legacy: `auth.jwt.refresh.secret`); empty ⇒ fall back to the access secret. */\r\n    secret: (): string | undefined => resolve(\"refreshToken.secret\", \"jwt.refresh.secret\"),\r\n    /** Whether refresh tokens are enabled (legacy: `auth.jwt.refresh.enabled`). */\r\n    enabled: (): boolean => resolve(\"refreshToken.enabled\", \"jwt.refresh.enabled\", true),\r\n    /** Lifetime as an `ms`-string (legacy: `auth.jwt.refresh.expiresIn`). */\r\n    expiresIn: (): string => resolve(\"refreshToken.expiresIn\", \"jwt.refresh.expiresIn\", \"7d\"),\r\n    /**\r\n     * Lifetime in milliseconds — the only form a token issuer may use. Throws\r\n     * naming the key when the configured value is not a positive `ms` duration.\r\n     */\r\n    expiresInMs: (): number =>\r\n      parseDuration(\"refreshToken.expiresIn\", authConfig.refreshToken.expiresIn()),\r\n    /** Rotate-on-use (legacy: `auth.jwt.refresh.rotation`). */\r\n    rotation: (): boolean => resolve(\"refreshToken.rotation\", \"jwt.refresh.rotation\", true),\r\n    /** Max active tokens per user (legacy: `auth.jwt.refresh.maxPerUser`). */\r\n    maxPerUser: (): number => resolve(\"refreshToken.maxPerUser\", \"jwt.refresh.maxPerUser\", 5),\r\n    /** Logout-without-token behavior (legacy: `auth.jwt.refresh.logoutWithoutToken`). */\r\n    logoutWithoutToken: (): LogoutWithoutTokenBehavior =>\r\n      resolve(\"refreshToken.logoutWithoutToken\", \"jwt.refresh.logoutWithoutToken\", \"revoke-all\"),\r\n  },\r\n};\r\n"],"mappings":";;;;;AAOA,MAAM,mCAAmB,IAAI,IAAY;AAEzC,MAAM,6BAAuD;;;;;;;;;;AAW7D,MAAM,UAAU;;;;;;;;;;;;;;;;;;AAmBhB,SAAS,cAAc,KAAa,KAAsB;CACxD,IAAI;CAEJ,IAAI;EACF,SAAS,QAAQ,GAAG;CACtB,QAAQ;EAEN,SAAS;CACX;CAEA,IAAI,OAAO,WAAW,YAAY,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,GACtE,MAAM,IAAI,MACR,QAAQ,IAAI,IAAI,KAAK,UAAU,GAAG,EAAE,mGAEtC;CAGF,OAAO;AACT;;AAGA,MAAM,kCAAkC;;;;;;;;;AAUxC,SAAS,QAAW,QAAgB,WAAmB,UAAiB;CACtE,MAAM,UAAU,OAAO,IAAI,QAAQ,QAAQ;CAE3C,IAAI,YAAY,UAAa,YAAY,MACvC,OAAO;CAGT,MAAM,aAAa,OAAO,IAAI,QAAQ,WAAW;CAEjD,IAAI,eAAe,UAAa,eAAe,MAAM;EACnD,IAAI,CAAC,iBAAiB,IAAI,SAAS,GAAG;GACpC,iBAAiB,IAAI,SAAS;GAC9B,IAAI,KAAK,QAAQ,sBAAsB,QAAQ,UAAU,4BAA4B,QAAQ;EAC/F;EAEA,OAAO;CACT;CAEA,OAAO;AACT;;;;;;AAOA,MAAa,aAAa;CACxB,iBAAiB,OAAO,SAAiC;EAMvD,OALwB,OAAO,IAC7B,wBACA,oBAGmB,CAAC,CAAC,IAAI;CAC7B;CACA,aAAa;;EAEX,cAAsB;GACpB,MAAM,SAAS,QAA4B,sBAAsB,YAAY;GAE7E,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,iEAAiE;GAGnF,OAAO;EACT;;EAEA,iBAA4B,QAAQ,yBAAyB,iBAAiB,OAAO;;EAErF,iBAAqC,QAAQ,yBAAyB,eAAe;;;;;;EAMrF,mBACE,cACE,yBACA,WAAW,YAAY,UAAU,KAAK,+BACxC;CACJ;CACA,UAAU;;;;;;;;;;EAUR,iBAAqC,OAAO,IAAI,yBAAyB;;;;;;EAMzE,sBAA8B,OAAO,IAAI,gCAAgC,WAAW;CACtF;CACA,cAAc;;EAEZ,cAAkC,QAAQ,uBAAuB,oBAAoB;;EAErF,eAAwB,QAAQ,wBAAwB,uBAAuB,IAAI;;EAEnF,iBAAyB,QAAQ,0BAA0B,yBAAyB,IAAI;;;;;EAKxF,mBACE,cAAc,0BAA0B,WAAW,aAAa,UAAU,CAAC;;EAE7E,gBAAyB,QAAQ,yBAAyB,wBAAwB,IAAI;;EAEtF,kBAA0B,QAAQ,2BAA2B,0BAA0B,CAAC;;EAExF,0BACE,QAAQ,mCAAmC,kCAAkC,YAAY;CAC7F;AACF"}

package/llms-full.txt

@@ -874,6 +874,32 @@ On failure, the middleware returns one of these 401 responses:
 | `InvalidAccessToken` | Token doesn't verify (signature, missing/passed `exp`, wrong token type), has no DB row, or the row's `expires_at` has passed |
 | `Unauthorized` | Token valid but user-type isn't in the allowed list |
 
+## Page routes: redirect to login instead of the JSON 401
+
+By default every auth failure — API or page — returns the JSON `401` above. That's right for an API client, but a logged-out human who *navigates* to a guarded page route gets a raw JSON error blob instead of a login screen.
+
+Opt into a redirect with `auth.pageAuth` (5.8+). Set `loginPath` and a guarded **page** route (`route.isPage`) that a logged-out browser hits redirects to `loginPath?returnUrl=<original path>` instead of returning the JSON 401:
+
+```ts title="src/config/auth.ts"
+export default {
+  userType: { user: User },
+  pageAuth: {
+    loginPath: "/login",        // set this to turn the redirect on
+    returnUrlParam: "returnUrl", // optional, this is the default
+  },
+};
+```
+
+Behavior, precisely:
+
+- **Page route + `loginPath` set** → `302` redirect to `loginPath?returnUrl=<encoded request path>`. The login flow reads `returnUrl` to send the user back where they were headed. If `loginPath` already carries a query string, the param is appended with `&` instead of `?`.
+- **Page route + `loginPath` unset** → the JSON `401` is unchanged. The redirect is **opt-in**, so an app that hasn't configured `pageAuth` keeps exactly its current behavior.
+- **API route** → always the JSON `401`, regardless of `pageAuth`. The API contract is never altered.
+
+The page-vs-API signal is `request.route.isPage`. Config is typed as `PageAuthConfig` on `AuthConfigurations` (`loginPath?: string`, `returnUrlParam?: string`, default `"returnUrl"`); read at runtime through `authConfig.pageAuth`.
+
+> The redirect approach may be revisited in a later version; this documents the shipped 5.8 behavior.
+
 ## Reading the user in a controller
 
 ```ts

package/package.json

@@ -12,12 +12,12 @@
     "ms": "^2.1.3"
   },
   "peerDependencies": {
-    "@warlock.js/fs": "5.7.0",
-    "@warlock.js/cache": "5.7.0",
-    "@warlock.js/cascade": "5.7.0",
-    "@warlock.js/core": "5.7.0",
-    "@warlock.js/logger": "5.7.0",
-    "@warlock.js/seal": "5.7.0"
+    "@warlock.js/fs": "5.9.0",
+    "@warlock.js/cache": "5.9.0",
+    "@warlock.js/cascade": "5.9.0",
+    "@warlock.js/core": "5.9.0",
+    "@warlock.js/logger": "5.9.0",
+    "@warlock.js/seal": "5.9.0"
   },
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.7.0",
+  "version": "5.9.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/protect-routes/SKILL.md

@@ -58,6 +58,32 @@ On failure, the middleware returns one of these 401 responses:
 | `InvalidAccessToken` | Token doesn't verify (signature, missing/passed `exp`, wrong token type), has no DB row, or the row's `expires_at` has passed |
 | `Unauthorized` | Token valid but user-type isn't in the allowed list |
 
+## Page routes: redirect to login instead of the JSON 401
+
+By default every auth failure — API or page — returns the JSON `401` above. That's right for an API client, but a logged-out human who *navigates* to a guarded page route gets a raw JSON error blob instead of a login screen.
+
+Opt into a redirect with `auth.pageAuth` (5.8+). Set `loginPath` and a guarded **page** route (`route.isPage`) that a logged-out browser hits redirects to `loginPath?returnUrl=<original path>` instead of returning the JSON 401:
+
+```ts title="src/config/auth.ts"
+export default {
+  userType: { user: User },
+  pageAuth: {
+    loginPath: "/login",        // set this to turn the redirect on
+    returnUrlParam: "returnUrl", // optional, this is the default
+  },
+};
+```
+
+Behavior, precisely:
+
+- **Page route + `loginPath` set** → `302` redirect to `loginPath?returnUrl=<encoded request path>`. The login flow reads `returnUrl` to send the user back where they were headed. If `loginPath` already carries a query string, the param is appended with `&` instead of `?`.
+- **Page route + `loginPath` unset** → the JSON `401` is unchanged. The redirect is **opt-in**, so an app that hasn't configured `pageAuth` keeps exactly its current behavior.
+- **API route** → always the JSON `401`, regardless of `pageAuth`. The API contract is never altered.
+
+The page-vs-API signal is `request.route.isPage`. Config is typed as `PageAuthConfig` on `AuthConfigurations` (`loginPath?: string`, `returnUrlParam?: string`, default `"returnUrl"`); read at runtime through `authConfig.pageAuth`.
+
+> `auth.pageAuth` is **not a second auth mechanism** — it is a convenience *adapter* over the same "not authenticated" outcome the gate already produces. It only changes the **representation** of that outcome on a page route (a browser-friendly login redirect) instead of the JSON `401`; the decision that the request is unauthenticated is unchanged. The sanctioned *generic* way to make authentication soft is the app-owned optional-auth middleware below — `pageAuth` is the built-in adapter for the common "redirect a logged-out human to /login" case, so most apps never need to hand-roll it.
+
 ## Reading the user in a controller
 
 ```ts
@@ -85,19 +111,31 @@ router.group({ prefix: "/admin", middleware: [authMiddleware("admin")] }, () =>
 
 Every route inside the group is gated — the group's `middleware` array applies to each route in the callback. Cleaner than repeating the middleware on each route.
 
-## No optional / fallthrough auth
+## Optional auth is an app-owned middleware (the sanctioned pattern)
 
-There is no "hydrate `request.user` if a token is present, otherwise continue" mode. `authMiddleware` always requires a valid token. If a route should be reachable anonymously, leave the middleware off — and read the token yourself in the controller if you want soft personalization:
+`authMiddleware` is a **hard gate** — it always requires a valid token and rejects when one is absent. There is deliberately no built-in "hydrate `request.user` if a token is present, otherwise continue" mode, because the *sanctioned generic pattern* for soft/optional auth is a small **app-owned optional-auth middleware**: resolve the user when a valid token is present, and otherwise leave the route to decide. The app owns it because the "what to do when absent" policy is the app's, not the framework's.
 
-```ts
-import { type RequestHandler } from "@warlock.js/core";
+```ts title="src/app/middleware/optional-auth.middleware.ts"
+import { type Middleware } from "@warlock.js/core";
+import { jwt } from "@warlock.js/auth";
 
-export const feedController: RequestHandler = async ({ request, response }) => {
+// The one sanctioned optional-auth shape: resolve if present, never reject.
+// Middleware receives the context object ({ request, response }), like a handler.
+export const optionalAuth: Middleware = async ({ request }) => {
   const token = request.authorizationValue;
-  // optionally decode/hydrate manually when a token is present
+  if (!token) return; // absent → continue anonymously; the route decides
+  try {
+    const decoded = await jwt.verify(token);
+    // hydrate request.user from your token/user model when valid
+  } catch {
+    // invalid token on an optional route → treat as anonymous, don't reject
+  }
+  // returning nothing (undefined) === continue to the handler
 };
 ```
 
+Wire it like any middleware (`{ middleware: [optionalAuth] }`), then branch on `request.user` in the controller. Use `authMiddleware` when the route must be gated; use this when the route is public but personalizes for a signed-in user. `auth.pageAuth` (above) is the built-in **adapter** over this same "unauthenticated" outcome for the common page-redirect case — it is not a competing mechanism.
+
 ## Custom error responses
 
 The middleware uses the framework's `response.unauthorized({...})` shape. To override the response globally, hook the framework's error transformer to remap `AuthErrorCodes.*` codes.