@warlock.js/auth 4.1.14 → 4.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog — @warlock.js/auth
+
+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.
+
+## [Unreleased]
+
+## 4.2.0
+
+### Added
+
+- `loginThrottleMiddleware` — failure-aware brute-force / credential-stuffing protection that counts only failed logins, resets on a successful one, locks per-account and per-IP, and rejects pre-controller with `429` (cache-backed, fails open on a cache outage). Adds `AuthErrorCodes.TooManyAttempts` (`EC004`).
+- `accessToken` / `refreshToken` configuration blocks, making a separate refresh-token secret first-class.
+- Overridable token storage — register a custom model under `config.auth.accessToken.model` / `config.auth.refreshToken.model` and `.extend()` the exported `accessTokenSchema` / `refreshTokenSchema` to add columns (e.g. a multi-tenant `organization_id`). Models own issuance through `issue()` and expose named statics, so the service hard-codes no column names.
+- `tokenType` (`access` | `refresh`) claim, stamped on issue and verified on read, so an access token can no longer be presented as a refresh token.
+- `expires_at` on access tokens; `warlock auth.cleanup` now purges expired access tokens as well as refresh tokens.
+
+### Fixed
+
+- Default access-token lifetime was ~3.6 seconds (a numeric `expiresIn` interpreted as milliseconds) and is now **1 hour**.
+- Targeted revocation queried `userId` instead of the `user_id` column, so logout and refresh-token removal threw on Postgres and silently no-oped on MongoDB. The service now routes every token query through named model statics, so no column name is hard-coded.
+- Token deletions were fire-and-forget inside `Promise<void>` methods (false success for callers, uncatchable rejections) and are now awaited.
+- The route middleware matched on `userType` instead of the `user_type` column.
+- `revokeAllTokens` / `revokeTokenFamily` reported an empty set — a re-query on `revoked_at: null` after the update matched nothing — so the `token.revoked` / `token.familyRevoked` events never fired. The revoked rows are now captured before revocation.
+- A throwing synchronous auth-event listener no longer turns a completed login into a `500`.
+
+### Security
+
+- `warlock jwt.generate` now derives `JWT_SECRET` / `JWT_REFRESH_SECRET` from a CSPRNG (`Random.token`) instead of `Math.random()`-backed `Random.string`.
+- Refresh-token rotation is atomic: a guarded conditional `UPDATE` means two concurrent rotations of the same token can never both succeed, and a replayed token revokes its entire family.
+
+### Deprecated
+
+- The `auth.jwt.*` configuration block (`jwt: { secret, expiresIn, refresh }`). Use `accessToken` / `refreshToken` instead — the legacy shape is still read and mapped forward with a one-time deprecation warning.
+
+### Removed
+
+- Unread `access_tokens` columns `is_active` and `last_access`.
+- The unused `auth.password.salt` configuration key.
+
+## 4.1.15
+
+- Baseline — per-package changelog tracking starts at this version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,37 +1,78 @@
-# Warlock Auth
-
-Auth System for Warlock.js
-
-## Installation
-
-`yarn create @warlock.js/auth`
-
-Or
-
-`npx create @warlock.js/auth`
-
-Or
-
-`pnpm create @warlock.js/auth`
-
-## Generate JWT Secret
-
-To generate JWT secret key, we need to add the following code to the `warlock.config.ts` file.
-
-```ts
-import { registerJWTSecretGeneratorCommand } from "@warlock.js/auth";
-import { defineConfig } from "@warlock.js/core";
-
-export default defineConfig({
-  // Other configurations
-  cli: {
-    commands: [registerJWTSecretGeneratorCommand()],
-  },
-});
-```
-
-Then run the following command:
-
-`warlock jwt.generate`
-
-It will generate 
+# Warlock Auth
+
+JWT authentication for [Warlock.js](https://github.com/warlockjs/core) applications — a base `Auth` model your user types extend, an `authMiddleware` route gate, an `authService` for login / logout / refresh (with refresh-token rotation + replay detection), persisted access + refresh tokens, multi-user-type support, lifecycle events, brute-force throttling, and two CLI commands.
+
+## Installation
+
+```bash
+yarn add @warlock.js/auth
+```
+
+`@warlock.js/auth` is coupled to `@warlock.js/core` — install it inside a Warlock project.
+
+## Configure
+
+```ts title="src/config/auth.ts"
+import { type AuthConfigurations } from "@warlock.js/auth";
+import { env } from "@warlock.js/core";
+import { User } from "app/users/models/user";
+
+const authConfigurations: AuthConfigurations = {
+  userType: { user: User },
+  accessToken: {
+    secret: env("JWT_SECRET"),
+    expiresIn: "1h",
+  },
+  refreshToken: {
+    secret: env("JWT_REFRESH_SECRET"),
+    expiresIn: "30d",
+    rotation: true,
+  },
+};
+
+export default authConfigurations;
+```
+
+The legacy `jwt: { secret, expiresIn, refresh: {…} }` block is still honored (with a deprecation warning), but prefer the `accessToken` / `refreshToken` blocks.
+
+## Documentation
+
+Task-focused guides live under [`skills/`](./skills):
+
+- **overview** — what the package does and when to reach for it
+- **auth-basics** — the `Auth` model, middleware, and service
+- **handle-login-and-logout** — issue and revoke tokens
+- **register-user** — sign up + first token pair
+- **protect-routes** — gate routes with `authMiddleware`
+- **manage-tokens** — the full token lifecycle (rotation, revocation, cleanup)
+- **customize-user-type** — multiple user types in one system
+- **customize-token-storage** — override the token models (multi-tenant columns, custom storage)
+- **throttle-login-attempts** — brute-force protection via `loginThrottleMiddleware`
+- **run-auth-commands** — the bundled CLI commands
+
+## Generate the JWT secret
+
+Register the command in `warlock.config.ts`:
+
+```ts
+import { registerJWTSecretGeneratorCommand } from "@warlock.js/auth";
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  cli: {
+    commands: [registerJWTSecretGeneratorCommand()],
+  },
+});
+```
+
+Then run:
+
+```bash
+warlock jwt.generate
+```
+
+It generates cryptographically-strong `JWT_SECRET` and `JWT_REFRESH_SECRET` values and writes them to your `.env` file. Existing values are left untouched, so it's safe to re-run.
+
+## License
+
+MIT © Hasan Zohdy

package/esm/commands/auth-cleanup-command.d.mts

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/auth/src/commands/auth-cleanup-command.d.ts
+//#region ../@warlock.js/auth/src/commands/auth-cleanup-command.d.ts
 /**
  * Register the auth:cleanup CLI command
  *

package/esm/commands/auth-cleanup-command.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-cleanup-command.d.mts","names":[],"sources":["../../../../../../@warlock.js/auth/src/commands/auth-cleanup-command.ts"],"mappings":";;AAYA;;;;AAA0C;;;iBAA1B,0BAAA,CAAA"}
+{"version":3,"file":"auth-cleanup-command.d.mts","names":[],"sources":["../../../../../../../@warlock.js/auth/src/commands/auth-cleanup-command.ts"],"mappings":";;AAYA;;;;AAA0C;;;iBAA1B,0BAAA"}

package/esm/commands/auth-cleanup-command.mjs

@@ -2,7 +2,7 @@ import { authService } from "../services/auth.service.mjs";
 import { colors } from "@mongez/copper";
 import { command } from "@warlock.js/core";
 
-//#region ../../@warlock.js/auth/src/commands/auth-cleanup-command.ts
+//#region ../@warlock.js/auth/src/commands/auth-cleanup-command.ts
 /**
 * Register the auth:cleanup CLI command
 *

package/esm/commands/auth-cleanup-command.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"auth-cleanup-command.mjs","names":[],"sources":["../../../../../../@warlock.js/auth/src/commands/auth-cleanup-command.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { command } from \"@warlock.js/core\";\nimport { authService } from \"../services/auth.service\";\n\n/**\n * Register the auth:cleanup CLI command\n *\n * @example\n * ```bash\n * warlock auth:cleanup\n * ```\n */\nexport function registerAuthCleanupCommand() {\n  return command({\n    name: \"auth.cleanup\",\n    description: \"Remove expired refresh tokens from the database\",\n    preload: {\n      env: true,\n      config: [\"auth\", \"database\"],\n      connectors: [\"database\"],\n    },\n    action: async () => {\n      console.log(colors.cyan(\"🧹 Cleaning up expired tokens...\"));\n\n      const count = await authService.cleanupExpiredTokens();\n\n      if (count === 0) {\n        console.log(colors.green(\"✅ No expired tokens found.\"));\n      } else {\n        console.log(colors.green(`✅ Removed ${count} expired token(s).`));\n      }\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,6BAA6B;CAC3C,OAAO,QAAQ;EACb,MAAM;EACN,aAAa;EACb,SAAS;GACP,KAAK;GACL,QAAQ,CAAC,QAAQ,UAAU;GAC3B,YAAY,CAAC,UAAU;EACzB;EACA,QAAQ,YAAY;GAClB,QAAQ,IAAI,OAAO,KAAK,kCAAkC,CAAC;GAE3D,MAAM,QAAQ,MAAM,YAAY,qBAAqB;GAErD,IAAI,UAAU,GACZ,QAAQ,IAAI,OAAO,MAAM,4BAA4B,CAAC;QAEtD,QAAQ,IAAI,OAAO,MAAM,aAAa,MAAM,mBAAmB,CAAC;EAEpE;CACF,CAAC;AACH"}
+{"version":3,"file":"auth-cleanup-command.mjs","names":[],"sources":["../../../../../../../@warlock.js/auth/src/commands/auth-cleanup-command.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { command } from \"@warlock.js/core\";\nimport { authService } from \"../services/auth.service\";\n\n/**\n * Register the auth:cleanup CLI command\n *\n * @example\n * ```bash\n * warlock auth:cleanup\n * ```\n */\nexport function registerAuthCleanupCommand() {\n  return command({\n    name: \"auth.cleanup\",\n    description: \"Remove expired refresh tokens from the database\",\n    preload: {\n      env: true,\n      config: [\"auth\", \"database\"],\n      connectors: [\"database\"],\n    },\n    action: async () => {\n      console.log(colors.cyan(\"🧹 Cleaning up expired tokens...\"));\n\n      const count = await authService.cleanupExpiredTokens();\n\n      if (count === 0) {\n        console.log(colors.green(\"✅ No expired tokens found.\"));\n      } else {\n        console.log(colors.green(`✅ Removed ${count} expired token(s).`));\n      }\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,6BAA6B;CAC3C,OAAO,QAAQ;EACb,MAAM;EACN,aAAa;EACb,SAAS;GACP,KAAK;GACL,QAAQ,CAAC,QAAQ,UAAU;GAC3B,YAAY,CAAC,UAAU;EACzB;EACA,QAAQ,YAAY;GAClB,QAAQ,IAAI,OAAO,KAAK,kCAAkC,CAAC;GAE3D,MAAM,QAAQ,MAAM,YAAY,qBAAqB;GAErD,IAAI,UAAU,GACZ,QAAQ,IAAI,OAAO,MAAM,4BAA4B,CAAC;QAEtD,QAAQ,IAAI,OAAO,MAAM,aAAa,MAAM,mBAAmB,CAAC;EAEpE;CACF,CAAC;AACH"}

package/esm/commands/jwt-secret-generator-command.d.mts

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/auth/src/commands/jwt-secret-generator-command.d.ts
+//#region ../@warlock.js/auth/src/commands/jwt-secret-generator-command.d.ts
 declare function registerJWTSecretGeneratorCommand(): any;
 //#endregion
 export { registerJWTSecretGeneratorCommand };

package/esm/commands/jwt-secret-generator-command.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-secret-generator-command.d.mts","names":[],"sources":["../../../../../../@warlock.js/auth/src/commands/jwt-secret-generator-command.ts"],"mappings":";iBAGgB,iCAAA,CAAA"}
+{"version":3,"file":"jwt-secret-generator-command.d.mts","names":[],"sources":["../../../../../../../@warlock.js/auth/src/commands/jwt-secret-generator-command.ts"],"mappings":";iBAGgB,iCAAA"}

package/esm/commands/jwt-secret-generator-command.mjs

@@ -1,7 +1,7 @@
 import { generateJWTSecret } from "../services/generate-jwt-secret.mjs";
 import { command } from "@warlock.js/core";
 
-//#region ../../@warlock.js/auth/src/commands/jwt-secret-generator-command.ts
+//#region ../@warlock.js/auth/src/commands/jwt-secret-generator-command.ts
 function registerJWTSecretGeneratorCommand() {
 	return command({
 		name: "jwt.generate",

package/esm/commands/jwt-secret-generator-command.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-secret-generator-command.mjs","names":[],"sources":["../../../../../../@warlock.js/auth/src/commands/jwt-secret-generator-command.ts"],"sourcesContent":["import { command } from \"@warlock.js/core\";\r\nimport { generateJWTSecret } from \"../services/generate-jwt-secret\";\r\n\r\nexport function registerJWTSecretGeneratorCommand() {\r\n  return command({\r\n    name: \"jwt.generate\",\r\n    description: \"Generate JWT Secret key in .env file\",\r\n    action: generateJWTSecret,\r\n  });\r\n}\r\n"],"mappings":";;;;AAGA,SAAgB,oCAAoC;CAClD,OAAO,QAAQ;EACb,MAAM;EACN,aAAa;EACb,QAAQ;CACV,CAAC;AACH"}
+{"version":3,"file":"jwt-secret-generator-command.mjs","names":[],"sources":["../../../../../../../@warlock.js/auth/src/commands/jwt-secret-generator-command.ts"],"sourcesContent":["import { command } from \"@warlock.js/core\";\r\nimport { generateJWTSecret } from \"../services/generate-jwt-secret\";\r\n\r\nexport function registerJWTSecretGeneratorCommand() {\r\n  return command({\r\n    name: \"jwt.generate\",\r\n    description: \"Generate JWT Secret key in .env file\",\r\n    action: generateJWTSecret,\r\n  });\r\n}\r\n"],"mappings":";;;;AAGA,SAAgB,oCAAoC;CAClD,OAAO,QAAQ;EACb,MAAM;EACN,aAAa;EACb,QAAQ;CACV,CAAC;AACH"}

package/esm/contracts/auth-contract.d.mts

@@ -1,7 +1,7 @@
-import { RefreshToken } from "../models/refresh-token/refresh-token.model.mjs";
 import { AccessTokenOutput, DeviceInfo, TokenPair } from "./types.mjs";
+import { RefreshToken } from "../models/refresh-token/refresh-token.model.mjs";
 
-//#region ../../@warlock.js/auth/src/contracts/auth-contract.d.ts
+//#region ../@warlock.js/auth/src/contracts/auth-contract.d.ts
 /**
  * Surface every authenticable user model exposes once it extends the
  * `Auth` base. The `Auth` class implements this contract; subclasses only

package/esm/contracts/auth-contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/auth/src/contracts/auth-contract.ts"],"mappings":";;;;;;AAWA;;;;;;UAAiB,aAAA;EAiBwC;;;;EAAA,IAZnD,QAAA;EAsB+B;;;;EAhBnC,mBAAA,CAAoB,OAAA,GAAU,MAAA,oBAA0B,OAAA,CAAQ,iBAAA;EAAlC;;;;EAM9B,oBAAA,CAAqB,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,YAAA;EAArB;;;EAKlC,eAAA,CAAgB,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,SAAA;EAAlD;;;EAKA,eAAA,CAAgB,QAAA,WAAmB,OAAA;AAAA"}
+{"version":3,"file":"auth-contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/auth/src/contracts/auth-contract.ts"],"mappings":";;;;;;AAWA;;;;;;UAAiB,aAAA;EAiBwC;;;;EAAA,IAZnD,QAAA;EAsB+B;;;;EAhBnC,mBAAA,CAAoB,OAAA,GAAU,MAAA,oBAA0B,OAAA,CAAQ,iBAAA;EAAlC;;;;EAM9B,oBAAA,CAAqB,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,YAAA;EAArB;;;EAKlC,eAAA,CAAgB,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,SAAA;EAAlD;;;EAKA,eAAA,CAAgB,QAAA,WAAmB,OAAA;AAAA"}

package/esm/contracts/index.d.mts

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

package/esm/contracts/types.d.mts

@@ -1,8 +1,10 @@
 import { Auth } from "../models/auth.model.mjs";
+import { AccessToken } from "../models/access-token/access-token.model.mjs";
+import { RefreshToken } from "../models/refresh-token/refresh-token.model.mjs";
 import { ChildModel } from "@warlock.js/cascade";
 import { Algorithm } from "fast-jwt";
 
-//#region ../../@warlock.js/auth/src/contracts/types.d.ts
+//#region ../@warlock.js/auth/src/contracts/types.d.ts
 /**
  * Symbol to indicate no expiration for tokens
  * Use this when you explicitly want tokens to never expire
@@ -13,7 +15,7 @@ import { Algorithm } from "fast-jwt";
  * import { NO_EXPIRATION, type AuthConfigurations } from "@warlock.js/auth";
  *
  * const authConfigurations: AuthConfigurations = {
- *   jwt: {
+ *   accessToken: {
  *     secret: env("JWT_SECRET"),
  *     expiresIn: NO_EXPIRATION,  // Token expires within 100 years
  *   },
@@ -29,88 +31,115 @@ declare const NO_EXPIRATION = "100y";
  * - "error": Return an error requiring the refresh token
  */
 type LogoutWithoutTokenBehavior = "revoke-all" | "error";
+/**
+ * Access-token configuration.
+ *
+ * `secret` may also be supplied via the deprecated `jwt.secret` (resolved by a
+ * backward-compatible shim); one of the two is required at runtime.
+ */
+type AccessTokenConfig = {
+  /**
+   * Override the persisted access-token model — extend {@link AccessToken} to
+   * add columns (e.g. a tenant key) or rename them, then register the subclass
+   * here. Defaults to the package's `AccessToken`.
+   */
+  model?: typeof AccessToken;
+  /**
+   * Secret used to sign access tokens.
+   */
+  secret?: string;
+  /**
+   * JWT algorithm.
+   * @default "HS256"
+   */
+  algorithm?: Algorithm;
+  /**
+   * Access-token lifetime — any value the `ms` package accepts.
+   * @example "1h" or NO_EXPIRATION
+   * @default "1h"
+   */
+  expiresIn?: string;
+};
+/**
+ * Refresh-token configuration.
+ */
+type RefreshTokenConfig = {
+  /**
+   * Override the persisted refresh-token model — extend {@link RefreshToken}.
+   * Defaults to the package's `RefreshToken`.
+   */
+  model?: typeof RefreshToken;
+  /**
+   * Enable refresh tokens.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Separate secret for refresh tokens (recommended for security). Falls back
+   * to the access-token secret when omitted.
+   */
+  secret?: string;
+  /**
+   * Refresh-token lifetime — any value the `ms` package accepts.
+   * @example "7d" or "1w"
+   * @default "7d"
+   */
+  expiresIn?: string;
+  /**
+   * Rotate the refresh token on each use (old token revoked, replay detected).
+   * @default true
+   */
+  rotation?: boolean;
+  /**
+   * Maximum active refresh tokens per user; the oldest are revoked past it.
+   * @default 5
+   */
+  maxPerUser?: number;
+  /**
+   * Behavior when logout is called without a refresh token.
+   * @default "revoke-all"
+   */
+  logoutWithoutToken?: LogoutWithoutTokenBehavior;
+};
+/**
+ * Legacy JWT configuration shape. Still honored by the resolver shim with a
+ * deprecation warning.
+ *
+ * @deprecated Use the top-level `accessToken` / `refreshToken` blocks.
+ */
+type LegacyJwtConfig = {
+  secret?: string;
+  algorithm?: Algorithm;
+  expiresIn?: string;
+  refresh?: {
+    secret?: string;
+    enabled?: boolean;
+    expiresIn?: string;
+    rotation?: boolean;
+    maxPerUser?: number;
+    logoutWithoutToken?: LogoutWithoutTokenBehavior;
+  };
+};
 type AuthConfigurations = {
   /**
-   * Define all user types
-   * This is important to differentiate between user types when validating and generating tokens
+   * Define all user types — maps a user-type slug to its `Auth` model class so
+   * tokens and the middleware can resolve the right model.
    */
   userType: {
     [userType: string]: ChildModel<Auth>;
   };
   /**
-   * JWT configurations
-   */
-  jwt: {
-    /**
-     * JWT secret key for signing access tokens
-     */
-    secret: string;
-    /**
-     * JWT algorithm
-     * @default "HS256"
-     */
-    algorithm?: Algorithm;
-    /**
-     * Access token expiration time
-     * It accepts any value `ms` package accepts
-     * @example "1h" or NO_EXPIRATION
-     * @default "1h"
-     */
-    expiresIn?: string;
-    /**
-     * Refresh token configurations
-     */
-    refresh?: {
-      /**
-       * Separate secret for refresh tokens (recommended for security)
-       * If not provided, falls back to main JWT secret
-       */
-      secret?: string;
-      /**
-       * Enable refresh token
-       * @default true
-       */
-      enabled?: boolean;
-      /**
-       * Refresh token expiration time
-       * It accepts any value `ms` package accepts
-       * @example "7d" or "1w"
-       * @default "7d"
-       */
-      expiresIn?: string;
-      /**
-       * Enable token rotation (issue new refresh token on each use)
-       * Old refresh token is invalidated after use
-       * @default true
-       */
-      rotation?: boolean;
-      /**
-       * Maximum number of active refresh tokens per user
-       * When exceeded, oldest tokens are revoked
-       * @default 5
-       */
-      maxPerUser?: number;
-      /**
-       * Behavior when logout is called without a refresh token
-       * - "revoke-all": Revoke all tokens for security (default)
-       * - "error": Require refresh token, return error if missing
-       * @default "revoke-all"
-       */
-      logoutWithoutToken?: LogoutWithoutTokenBehavior;
-    };
-  };
+   * Access-token configuration (secret, expiry, algorithm, model override).
+   */
+  accessToken?: AccessTokenConfig;
   /**
-   * Password configurations
+   * Refresh-token configuration (rotation, lifetime, cap, model override).
    */
-  password?: {
-    /**
-     * Password salt
-     * The higher the salt, the more secure the password is
-     * But, it will take more time to generate the password
-     * @default 12
-     */
-    salt?: number;
-  };
+  refreshToken?: RefreshTokenConfig;
+  /**
+   * @deprecated Use `accessToken` / `refreshToken`. Read via a backward-compatible shim.
+   */
+  jwt?: LegacyJwtConfig;
 };
 type AccessTokenOutput = {
   /**
@@ -166,5 +195,5 @@ type LoginResult<UserType extends Auth> = {
   tokens: TokenPair;
 };
 //#endregion
-export { AccessTokenOutput, AuthConfigurations, DeviceInfo, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, TokenPair };
+export { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshTokenConfig, TokenPair };
 //# sourceMappingURL=types.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../@warlock.js/auth/src/contracts/types.ts"],"mappings":";;;;;;;AAuBA;;;;AAA0B;AAO1B;;;;AAAsC;AAEtC;;;;;;;cATa,aAAA;;;;;;KAOD,0BAAA;AAAA,KAEA,kBAAA;EAoBR;;;;EAfF,QAAA;IAAA,CACG,QAAA,WAAmB,UAAA,CAAW,IAAA;EAAA;EAgD7B;;;EA3CJ,GAAA;IA8DA;;;IA1DE,MAAA;IAqEQ;;;;IAhER,SAAA,GAAY,SAAA;IA8EJ;;;;;;IAvER,SAAA;IA+Ea;;AAAiB;IA3E9B,OAAA;MAiFkB;;;;MA5EhB,MAAA;MAwFJ;;;;MAnFI,OAAA;MA4FY;AAGlB;;;;;MAxFM,SAAA;MA0Fa;;;;;MApFb,QAAA;MAoFJ;;;AAAiB;;MA9Eb,UAAA;;;;;;;MAOA,kBAAA,GAAqB,0BAAA;IAAA;EAAA;;;;EAMzB,QAAA;;;;;;;IAOE,IAAA;EAAA;AAAA;AAAA,KAIQ,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":["../../../../../../../@warlock.js/auth/src/contracts/types.ts"],"mappings":";;;;;;;;;;;AAyBA;;;;AAA0B;AAO1B;;;;AAAsC;AAQtC;;;;;cAfa,aAAA;;;;;;KAOD,0BAAA;AAmCZ;;;;;;AAAA,KA3BY,iBAAA;EA0CV;;;;;EApCA,KAAA,UAAe,WAAA;EAyDgC;AAAA;AASjD;EA9DE,MAAA;;;;;EAKA,SAAA,GAAY,SAAS;EA4DrB;;;;;EAtDA,SAAA;AAAA;;;;KAMU,kBAAA;EA2DA;;;;EAtDV,KAAA,UAAe,YAAA;EAiED;;;;EA5Dd,OAAA;EAsDA;;;;EAjDA,MAAA;EAuDc;;;;;EAjDd,SAAA;EAyDqB;AAGvB;;;EAvDE,QAAA;EA+DS;AAMX;;;EAhEE,UAAA;EAoEA;;;;EA/DA,kBAAA,GAAqB,0BAA0B;AAAA;AAyEjD;;;;;;AAAA,KAhEY,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;EA0EY;;;;EArEtB,QAAA;IAAA,CACG,QAAA,WAAmB,UAAA,CAAW,IAAA;EAAA;EAsEhB;;;EAjEjB,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"}

package/esm/contracts/types.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/auth/src/contracts/types.ts
+//#region ../@warlock.js/auth/src/contracts/types.ts
 /**
 * Symbol to indicate no expiration for tokens
 * Use this when you explicitly want tokens to never expire
@@ -9,7 +9,7 @@
 * import { NO_EXPIRATION, type AuthConfigurations } from "@warlock.js/auth";
 *
 * const authConfigurations: AuthConfigurations = {
-*   jwt: {
+*   accessToken: {
 *     secret: env("JWT_SECRET"),
 *     expiresIn: NO_EXPIRATION,  // Token expires within 100 years
 *   },

package/esm/contracts/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../../@warlock.js/auth/src/contracts/types.ts"],"sourcesContent":["import { ChildModel } from \"@warlock.js/cascade\";\r\nimport { type Algorithm } from \"fast-jwt\";\r\nimport type { Auth } from \"../models/auth.model\";\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 *   jwt: {\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\nexport type AuthConfigurations = {\r\n  /**\r\n   * Define all user types\r\n   * This is important to differentiate between user types when validating and generating tokens\r\n   */\r\n  userType: {\r\n    [userType: string]: ChildModel<Auth>;\r\n  };\r\n  /**\r\n   * JWT configurations\r\n   */\r\n  jwt: {\r\n    /**\r\n     * JWT secret key for signing 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 expiration time\r\n     * It accepts any value `ms` package accepts\r\n     * @example \"1h\" or NO_EXPIRATION\r\n     * @default \"1h\"\r\n     */\r\n    expiresIn?: string;\r\n    /**\r\n     * Refresh token configurations\r\n     */\r\n    refresh?: {\r\n      /**\r\n       * Separate secret for refresh tokens (recommended for security)\r\n       * If not provided, falls back to main JWT secret\r\n       */\r\n      secret?: string;\r\n      /**\r\n       * Enable refresh token\r\n       * @default true\r\n       */\r\n      enabled?: boolean;\r\n      /**\r\n       * Refresh token expiration time\r\n       * It accepts any value `ms` package accepts\r\n       * @example \"7d\" or \"1w\"\r\n       * @default \"7d\"\r\n       */\r\n      expiresIn?: string;\r\n      /**\r\n       * Enable token rotation (issue new refresh token on each use)\r\n       * Old refresh token is invalidated after use\r\n       * @default true\r\n       */\r\n      rotation?: boolean;\r\n      /**\r\n       * Maximum number of active refresh tokens per user\r\n       * When exceeded, oldest tokens are revoked\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       * - \"revoke-all\": Revoke all tokens for security (default)\r\n       * - \"error\": Require refresh token, return error if missing\r\n       * @default \"revoke-all\"\r\n       */\r\n      logoutWithoutToken?: LogoutWithoutTokenBehavior;\r\n    };\r\n  };\r\n  /**\r\n   * Password configurations\r\n   */\r\n  password?: {\r\n    /**\r\n     * Password salt\r\n     * The higher the salt, the more secure the password is\r\n     * But, it will take more time to generate the password\r\n     * @default 12\r\n     */\r\n    salt?: number;\r\n  };\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, any>;\r\n};\r\n\r\nexport type LoginResult<UserType extends Auth> = {\r\n  user: UserType;\r\n  tokens: TokenPair;\r\n};\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,gBAAgB"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../../../@warlock.js/auth/src/contracts/types.ts"],"sourcesContent":["import { type ChildModel } from \"@warlock.js/cascade\";\nimport { type Algorithm } from \"fast-jwt\";\nimport type { AccessToken } from \"../models/access-token\";\nimport type { Auth } from \"../models/auth.model\";\nimport type { RefreshToken } from \"../models/refresh-token\";\n\n/**\n * Symbol to indicate no expiration for tokens\n * Use this when you explicitly want tokens to never expire\n *\n * @example\n * ```typescript\n * // src/config/auth.ts\n * import { NO_EXPIRATION, type AuthConfigurations } from \"@warlock.js/auth\";\n *\n * const authConfigurations: AuthConfigurations = {\n *   accessToken: {\n *     secret: env(\"JWT_SECRET\"),\n *     expiresIn: NO_EXPIRATION,  // Token expires within 100 years\n *   },\n * };\n *\n * export default authConfigurations;\n * ```\n */\nexport const NO_EXPIRATION = \"100y\";\n\n/**\n * Behavior when logout is called without a refresh token\n * - \"revoke-all\": Revoke all refresh tokens for the user (secure default)\n * - \"error\": Return an error requiring the refresh token\n */\nexport type LogoutWithoutTokenBehavior = \"revoke-all\" | \"error\";\n\n/**\n * Access-token configuration.\n *\n * `secret` may also be supplied via the deprecated `jwt.secret` (resolved by a\n * backward-compatible shim); one of the two is required at runtime.\n */\nexport type AccessTokenConfig = {\n  /**\n   * Override the persisted access-token model — extend {@link AccessToken} to\n   * add columns (e.g. a tenant key) or rename them, then register the subclass\n   * here. Defaults to the package's `AccessToken`.\n   */\n  model?: typeof AccessToken;\n  /**\n   * Secret used to sign access tokens.\n   */\n  secret?: string;\n  /**\n   * JWT algorithm.\n   * @default \"HS256\"\n   */\n  algorithm?: Algorithm;\n  /**\n   * Access-token lifetime — any value the `ms` package accepts.\n   * @example \"1h\" or NO_EXPIRATION\n   * @default \"1h\"\n   */\n  expiresIn?: string;\n};\n\n/**\n * Refresh-token configuration.\n */\nexport type RefreshTokenConfig = {\n  /**\n   * Override the persisted refresh-token model — extend {@link RefreshToken}.\n   * Defaults to the package's `RefreshToken`.\n   */\n  model?: typeof RefreshToken;\n  /**\n   * Enable refresh tokens.\n   * @default true\n   */\n  enabled?: boolean;\n  /**\n   * Separate secret for refresh tokens (recommended for security). Falls back\n   * to the access-token secret when omitted.\n   */\n  secret?: string;\n  /**\n   * Refresh-token lifetime — any value the `ms` package accepts.\n   * @example \"7d\" or \"1w\"\n   * @default \"7d\"\n   */\n  expiresIn?: string;\n  /**\n   * Rotate the refresh token on each use (old token revoked, replay detected).\n   * @default true\n   */\n  rotation?: boolean;\n  /**\n   * Maximum active refresh tokens per user; the oldest are revoked past it.\n   * @default 5\n   */\n  maxPerUser?: number;\n  /**\n   * Behavior when logout is called without a refresh token.\n   * @default \"revoke-all\"\n   */\n  logoutWithoutToken?: LogoutWithoutTokenBehavior;\n};\n\n/**\n * Legacy JWT configuration shape. Still honored by the resolver shim with a\n * deprecation warning.\n *\n * @deprecated Use the top-level `accessToken` / `refreshToken` blocks.\n */\nexport type LegacyJwtConfig = {\n  secret?: string;\n  algorithm?: Algorithm;\n  expiresIn?: string;\n  refresh?: {\n    secret?: string;\n    enabled?: boolean;\n    expiresIn?: string;\n    rotation?: boolean;\n    maxPerUser?: number;\n    logoutWithoutToken?: LogoutWithoutTokenBehavior;\n  };\n};\n\nexport type AuthConfigurations = {\n  /**\n   * Define all user types — maps a user-type slug to its `Auth` model class so\n   * tokens and the middleware can resolve the right model.\n   */\n  userType: {\n    [userType: string]: ChildModel<Auth>;\n  };\n  /**\n   * Access-token configuration (secret, expiry, algorithm, model override).\n   */\n  accessToken?: AccessTokenConfig;\n  /**\n   * Refresh-token configuration (rotation, lifetime, cap, model override).\n   */\n  refreshToken?: RefreshTokenConfig;\n  /**\n   * @deprecated Use `accessToken` / `refreshToken`. Read via a backward-compatible shim.\n   */\n  jwt?: LegacyJwtConfig;\n};\n\nexport type AccessTokenOutput = {\n  /**\n   * JWT Token\n   */\n  token: string;\n  /**\n   * Exprie time in ISO format UTC time\n   */\n  expiresAt: string;\n};\n\n/**\n * Token pair returned after login or token refresh\n */\nexport type TokenPair = {\n  /**\n   * JWT access token (short-lived)\n   */\n  accessToken: AccessTokenOutput;\n  /**\n   * JWT refresh token (long-lived)\n   */\n  refreshToken?: AccessTokenOutput;\n};\n\n/**\n * Device information for session tracking\n */\nexport type DeviceInfo = {\n  /**\n   * User agent string from request\n   */\n  userAgent?: string;\n  /**\n   * Client IP address\n   */\n  ip?: string;\n  /**\n   * Optional device identifier\n   */\n  deviceId?: string;\n  /**\n   * Token family ID (for rotation tracking)\n   * @internal\n   */\n  familyId?: string;\n  /**\n   * Access token payload\n   */\n  payload?: Record<string, any>;\n};\n\nexport type LoginResult<UserType extends Auth> = {\n  user: UserType;\n  tokens: TokenPair;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,gBAAgB"}

package/esm/index.d.mts

@@ -1,15 +1,16 @@
 import { registerAuthCleanupCommand } from "./commands/auth-cleanup-command.mjs";
 import { registerJWTSecretGeneratorCommand } from "./commands/jwt-secret-generator-command.mjs";
-import { RefreshToken } from "./models/refresh-token/refresh-token.model.mjs";
 import { Auth } from "./models/auth.model.mjs";
-import { AccessTokenOutput, AuthConfigurations, DeviceInfo, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, TokenPair } from "./contracts/types.mjs";
+import { AccessToken, accessTokenSchema } from "./models/access-token/access-token.model.mjs";
+import { AccessTokenConfig, AccessTokenOutput, AuthConfigurations, DeviceInfo, LegacyJwtConfig, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshTokenConfig, 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";
-import { AccessToken } from "./models/access-token/access-token.model.mjs";
+import { LoginThrottleIdentifier, LoginThrottleOptions, loginThrottleMiddleware } from "./middleware/login-throttle.middleware.mjs";
 import { authMigrations } from "./models/index.mjs";
 import { AuthEventCallback, AuthEventName, AuthEventPayloads, authEvents } from "./services/auth-events.mjs";
 import { authService } from "./services/auth.service.mjs";
 import { generateJWTSecret } from "./services/generate-jwt-secret.mjs";
-import { jwt } from "./services/jwt.mjs";
+import { TokenType, jwt } from "./services/jwt.mjs";
 import { AuthErrorCodes } from "./utils/auth-error-codes.mjs";
-export { AccessToken, AccessTokenOutput, Auth, AuthConfigurations, AuthErrorCodes, AuthEventCallback, AuthEventName, AuthEventPayloads, Authenticable, DeviceInfo, LoginResult, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshToken, TokenPair, authEvents, authMiddleware, authMigrations, authService, generateJWTSecret, jwt, registerAuthCleanupCommand, registerJWTSecretGeneratorCommand };
+export { AccessToken, AccessTokenConfig, AccessTokenOutput, Auth, AuthConfigurations, AuthErrorCodes, AuthEventCallback, AuthEventName, AuthEventPayloads, Authenticable, DeviceInfo, LegacyJwtConfig, LoginResult, LoginThrottleIdentifier, LoginThrottleOptions, LogoutWithoutTokenBehavior, NO_EXPIRATION, RefreshToken, RefreshTokenConfig, RefreshTokenIssueOptions, TokenPair, TokenType, accessTokenSchema, authEvents, authMiddleware, authMigrations, authService, generateJWTSecret, jwt, loginThrottleMiddleware, refreshTokenSchema, registerAuthCleanupCommand, registerJWTSecretGeneratorCommand };

package/esm/index.mjs

@@ -1,5 +1,5 @@
-import { AccessToken } from "./models/access-token/access-token.model.mjs";
-import { RefreshToken } from "./models/refresh-token/refresh-token.model.mjs";
+import { AccessToken, accessTokenSchema } from "./models/access-token/access-token.model.mjs";
+import { RefreshToken, refreshTokenSchema } from "./models/refresh-token/refresh-token.model.mjs";
 import { authEvents } from "./services/auth-events.mjs";
 import { jwt } from "./services/jwt.mjs";
 import { authService } from "./services/auth.service.mjs";
@@ -9,9 +9,10 @@ import { registerJWTSecretGeneratorCommand } from "./commands/jwt-secret-generat
 import { NO_EXPIRATION } from "./contracts/types.mjs";
 import { AuthErrorCodes } from "./utils/auth-error-codes.mjs";
 import { authMiddleware } from "./middleware/auth.middleware.mjs";
+import { loginThrottleMiddleware } from "./middleware/login-throttle.middleware.mjs";
 import "./middleware/index.mjs";
 import "./services/index.mjs";
 import { Auth } from "./models/auth.model.mjs";
 import { authMigrations } from "./models/index.mjs";
 
-export { AccessToken, Auth, AuthErrorCodes, NO_EXPIRATION, RefreshToken, authEvents, authMiddleware, authMigrations, authService, generateJWTSecret, jwt, registerAuthCleanupCommand, registerJWTSecretGeneratorCommand };
+export { AccessToken, Auth, AuthErrorCodes, NO_EXPIRATION, RefreshToken, accessTokenSchema, authEvents, authMiddleware, authMigrations, authService, generateJWTSecret, jwt, loginThrottleMiddleware, refreshTokenSchema, registerAuthCleanupCommand, registerJWTSecretGeneratorCommand };

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

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/auth/src/middleware/auth.middleware.d.ts
+//#region ../@warlock.js/auth/src/middleware/auth.middleware.d.ts
 /**
  * Build a route gate that always requires an authenticated request.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"auth.middleware.d.mts","names":[],"sources":["../../../../../../@warlock.js/auth/src/middleware/auth.middleware.ts"],"mappings":";;AAuBA;;;;AAAiE;;;;;;;;;;;;iBAAjD,cAAA,CAAe,eAAA,sBAAkC,UAAA"}
+{"version":3,"file":"auth.middleware.d.mts","names":[],"sources":["../../../../../../../@warlock.js/auth/src/middleware/auth.middleware.ts"],"mappings":";;AAgCA;;;;AAAiE;;;;;;;;;;;;iBAAjD,cAAA,CAAe,eAAA,sBAAkC,UAAA"}