@warlock.js/auth 4.1.14 → 4.2.0

package/esm/services/jwt.d.mts

@@ -1,6 +1,15 @@
 import { SignerOptions, VerifierOptions } from "fast-jwt";
 
-//#region ../../@warlock.js/auth/src/services/jwt.d.ts
+//#region ../@warlock.js/auth/src/services/jwt.d.ts
+/**
+ * Token class. Stamped as the `tokenType` claim on every signed token and
+ * checked on verify so an access token can never be accepted where a refresh
+ * token is expected (and vice versa) — even when both share the same secret
+ * under the documented refresh-secret fallback. Legacy tokens minted before
+ * this claim existed carry no `tokenType` and remain accepted; a *mismatched*
+ * type is always rejected.
+ */
+type TokenType = "access" | "refresh";
 declare const jwt: {
   /**
    * Generate a new JWT token for the user.
@@ -18,7 +27,7 @@ declare const jwt: {
    * @param token The JWT token to verify.
    * @returns The decoded token payload if verification is successful.
    */
-  verify<T = any>(token: string, {
+  verify<T = unknown>(token: string, {
     key,
     algorithms,
     ...options
@@ -39,7 +48,7 @@ declare const jwt: {
   /**
    * Verify the given refresh token.
    */
-  verifyRefreshToken<T = any>(token: string, {
+  verifyRefreshToken<T = unknown>(token: string, {
     key,
     algorithms,
     ...options
@@ -48,5 +57,5 @@ declare const jwt: {
   }): Promise<T>;
 };
 //#endregion
-export { jwt };
+export { TokenType, jwt };
 //# sourceMappingURL=jwt.d.mts.map

package/esm/services/jwt.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.d.mts","names":[],"sources":["../../../../../../@warlock.js/auth/src/services/jwt.ts"],"mappings":";;;cA0Ba,GAAA;;AAAb;;;;IAMgB,GAAA;IAAA,SAAA;IAAA,GAAA;EAAA,IAKT,aAAA;IAAkB,GAAA;EAAA,IACpB,OAAA;EAAA;;;;;kBAaW,KAAA;IACC,GAAA;IAAA,UAAA;IAAA,GAAA;EAAA,IAKV,eAAA;IAAoB,GAAA;EAAA,IACtB,OAAA,CAAQ,CAAA;EAUG;;;;IAAA,GAAA;IAAA,SAAA;IAAA,SAAA;IAAA,GAAA;EAAA,IAMT,aAAA;IAAkB,GAAA;EAAA,IACpB,OAAA;EAeQ;;;8BAPe,KAAA;IACX,GAAA;IAAA,UAAA;IAAA,GAAA;EAAA,IAKV,eAAA;IAAoB,GAAA;EAAA,IACtB,OAAA,CAAQ,CAAA;AAAA"}
+{"version":3,"file":"jwt.d.mts","names":[],"sources":["../../../../../../../@warlock.js/auth/src/services/jwt.ts"],"mappings":";;;;;AAkBA;;;;AAAqB;AAiBrB;KAjBY,SAAA;AAAA,cAiBC,GAAA;EAMG;;;;;IAAA,GAAA;IAAA,SAAA;IAAA,GAAA;EAAA,IAKT,aAAA;IAAkB,GAAA;EAAA,IACpB,OAAA;EAoBQ;;;;;sBAPG,KAAA;IACC,GAAA;IAAA,UAAA;IAAA,GAAA;EAAA,IAKV,eAAA;IAAoB,GAAA;EAAA,IACtB,OAAA,CAAQ,CAAA;EA8BI;;;;IAhBD,GAAA;IAAA,SAAA;IAAA,SAAA;IAAA,GAAA;EAAA,IAMT,aAAA;IAAkB,GAAA;EAAA,IACpB,OAAA;;;;kCAQuB,KAAA;IACX,GAAA;IAAA,UAAA;IAAA,GAAA;EAAA,IAKV,eAAA;IAAoB,GAAA;EAAA,IACtB,OAAA,CAAQ,CAAA;AAAA"}

package/esm/services/jwt.mjs

@@ -1,11 +1,20 @@
-import { config } from "@warlock.js/core";
-import ms from "ms";
+import { authConfig } from "./auth-config.mjs";
 import { createSigner, createVerifier } from "fast-jwt";
 
-//#region ../../@warlock.js/auth/src/services/jwt.ts
-const getSecretKey = () => config.key("auth.jwt.secret");
-const getAlgorithm = () => config.key("auth.jwt.algorithm", "HS256");
-const getRefreshSecretKey = () => config.key("auth.jwt.refresh.secret") || getSecretKey();
+//#region ../@warlock.js/auth/src/services/jwt.ts
+const getSecretKey = () => authConfig.accessToken.secret();
+const getAlgorithm = () => authConfig.accessToken.algorithm();
+const getRefreshSecretKey = () => authConfig.refreshToken.secret() || getSecretKey();
+const ACCESS_TOKEN_TYPE = "access";
+const REFRESH_TOKEN_TYPE = "refresh";
+/**
+* Reject the token when its `tokenType` claim is present and does not match the
+* expected class. Absent claim ⇒ legacy token, accepted (backward compatible).
+*/
+function assertTokenType(decoded, expected) {
+	const actual = decoded?.tokenType;
+	if (typeof actual === "string" && actual !== expected) throw new Error(`Invalid token type: expected "${expected}", received "${actual}".`);
+}
 const jwt = {
 	/**
 	* Generate a new JWT token for the user.
@@ -16,19 +25,24 @@ const jwt = {
 			key,
 			...options,
 			algorithm
-		})({ ...payload });
+		})({
+			...payload,
+			tokenType: ACCESS_TOKEN_TYPE
+		});
 	},
 	/**
 	* Verify the given token.
 	* @param token The JWT token to verify.
 	* @returns The decoded token payload if verification is successful.
 	*/
-	async verify(token, { key = getSecretKey(), algorithms = getAlgorithm() ? [getAlgorithm()] : void 0, ...options } = {}) {
-		return await createVerifier({
+	async verify(token, { key = getSecretKey(), algorithms = [getAlgorithm()], ...options } = {}) {
+		const decoded = await createVerifier({
 			key,
 			...options,
 			algorithms
 		})(token);
+		assertTokenType(decoded, ACCESS_TOKEN_TYPE);
+		return decoded;
 	},
 	/**
 	* Generate a new refresh token for the user.
@@ -39,17 +53,22 @@ const jwt = {
 			expiresIn,
 			algorithm,
 			...options
-		})({ ...payload });
+		})({
+			...payload,
+			tokenType: REFRESH_TOKEN_TYPE
+		});
 	},
 	/**
 	* Verify the given refresh token.
 	*/
 	async verifyRefreshToken(token, { key = getRefreshSecretKey(), algorithms = [getAlgorithm()], ...options } = {}) {
-		return await createVerifier({
+		const decoded = await createVerifier({
 			key,
 			algorithms,
 			...options
 		})(token);
+		assertTokenType(decoded, REFRESH_TOKEN_TYPE);
+		return decoded;
 	}
 };
 

package/esm/services/jwt.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.mjs","names":[],"sources":["../../../../../../@warlock.js/auth/src/services/jwt.ts"],"sourcesContent":["import { config } from \"@warlock.js/core\";\r\nimport {\r\n  createSigner,\r\n  createVerifier,\r\n  type Algorithm,\r\n  type SignerOptions,\r\n  type VerifierOptions,\r\n} from \"fast-jwt\";\r\nimport ms from \"ms\";\r\n\r\nconst getSecretKey = () => config.key(\"auth.jwt.secret\") as string;\r\nconst getAlgorithm = () => config.key(\"auth.jwt.algorithm\", \"HS256\") as Algorithm;\r\n\r\n// Refresh tokens may declare their own secret. When `auth.jwt.refresh.secret`\r\n// is unset/empty we fall back to the main JWT secret, matching the documented\r\n// optional behavior in `contracts/types.ts`.\r\nconst getRefreshSecretKey = () =>\r\n  (config.key(\"auth.jwt.refresh.secret\") || getSecretKey()) as string;\r\n// Refresh token validity — defaults to 7d when not configured. Opt in to\r\n// no-expiry semantics with `NO_EXPIRATION` (100y) from `contracts/types.ts`.\r\nconst getRefreshTokenValidity = () => {\r\n  const expiresIn = config.key(\"auth.jwt.refresh.expiresIn\") || \"7d\";\r\n\r\n  return ms(expiresIn);\r\n};\r\n\r\nexport const jwt = {\r\n  /**\r\n   * Generate a new JWT token for the user.\r\n   * @param payload The payload to encode in the JWT token.\r\n   */\r\n  async generate(\r\n    payload: any,\r\n    {\r\n      key = getSecretKey(),\r\n      algorithm = getAlgorithm(),\r\n      ...options\r\n    }: SignerOptions & { key?: string } = {},\r\n  ): Promise<string> {\r\n    // Create a signer function with predefined options\r\n    const sign = createSigner({ key, ...options, algorithm });\r\n\r\n    const token = await sign({ ...payload });\r\n    return token;\r\n  },\r\n\r\n  /**\r\n   * Verify the given token.\r\n   * @param token The JWT token to verify.\r\n   * @returns The decoded token payload if verification is successful.\r\n   */\r\n  async verify<T = any>(\r\n    token: string,\r\n    {\r\n      key = getSecretKey(),\r\n      algorithms = getAlgorithm() ? [getAlgorithm()] : undefined,\r\n      ...options\r\n    }: VerifierOptions & { key?: string } = {},\r\n  ): Promise<T> {\r\n    const verify = createVerifier({ key, ...options, algorithms });\r\n\r\n    return await verify(token as string);\r\n  },\r\n\r\n  /**\r\n   * Generate a new refresh token for the user.\r\n   */\r\n  async generateRefreshToken(\r\n    payload: any,\r\n    {\r\n      key = getRefreshSecretKey(),\r\n      expiresIn,\r\n      algorithm = getAlgorithm(),\r\n      ...options\r\n    }: SignerOptions & { key?: string } = {},\r\n  ): Promise<string> {\r\n    const sign = createSigner({ key, expiresIn, algorithm, ...options });\r\n    return sign({ ...payload });\r\n  },\r\n\r\n  /**\r\n   * Verify the given refresh token.\r\n   */\r\n  async verifyRefreshToken<T = any>(\r\n    token: string,\r\n    {\r\n      key = getRefreshSecretKey(),\r\n      algorithms = [getAlgorithm()],\r\n      ...options\r\n    }: VerifierOptions & { key?: string } = {},\r\n  ): Promise<T> {\r\n    const verify = createVerifier({ key, algorithms, ...options });\r\n    return await verify(token);\r\n  },\r\n};\r\n"],"mappings":";;;;;AAUA,MAAM,qBAAqB,OAAO,IAAI,iBAAiB;AACvD,MAAM,qBAAqB,OAAO,IAAI,sBAAsB,OAAO;AAKnE,MAAM,4BACH,OAAO,IAAI,yBAAyB,KAAK,aAAa;AASzD,MAAa,MAAM;;;;;CAKjB,MAAM,SACJ,SACA,EACE,MAAM,aAAa,GACnB,YAAY,aAAa,GACzB,GAAG,YACiC,CAAC,GACtB;EAKjB,OAAO,MAHM,aAAa;GAAE;GAAK,GAAG;GAAS;EAAU,CAEhC,EAAE,EAAE,GAAG,QAAQ,CAAC;CAEzC;;;;;;CAOA,MAAM,OACJ,OACA,EACE,MAAM,aAAa,GACnB,aAAa,aAAa,IAAI,CAAC,aAAa,CAAC,IAAI,QACjD,GAAG,YACmC,CAAC,GAC7B;EAGZ,OAAO,MAFQ,eAAe;GAAE;GAAK,GAAG;GAAS;EAAW,CAE1C,EAAE,KAAe;CACrC;;;;CAKA,MAAM,qBACJ,SACA,EACE,MAAM,oBAAoB,GAC1B,WACA,YAAY,aAAa,GACzB,GAAG,YACiC,CAAC,GACtB;EAEjB,OADa,aAAa;GAAE;GAAK;GAAW;GAAW,GAAG;EAAQ,CACxD,EAAE,EAAE,GAAG,QAAQ,CAAC;CAC5B;;;;CAKA,MAAM,mBACJ,OACA,EACE,MAAM,oBAAoB,GAC1B,aAAa,CAAC,aAAa,CAAC,GAC5B,GAAG,YACmC,CAAC,GAC7B;EAEZ,OAAO,MADQ,eAAe;GAAE;GAAK;GAAY,GAAG;EAAQ,CAC1C,EAAE,KAAK;CAC3B;AACF"}
+{"version":3,"file":"jwt.mjs","names":[],"sources":["../../../../../../../@warlock.js/auth/src/services/jwt.ts"],"sourcesContent":["import { createSigner, createVerifier, type SignerOptions, type VerifierOptions } from \"fast-jwt\";\r\nimport { authConfig } from \"./auth-config\";\r\n\r\nconst getSecretKey = () => authConfig.accessToken.secret();\r\nconst getAlgorithm = () => authConfig.accessToken.algorithm();\r\n\r\n// Refresh tokens may declare their own secret; when unset/empty we fall back to\r\n// the access-token secret (the documented optional behavior).\r\nconst getRefreshSecretKey = () => authConfig.refreshToken.secret() || getSecretKey();\r\n\r\n/**\r\n * Token class. Stamped as the `tokenType` claim on every signed token and\r\n * checked on verify so an access token can never be accepted where a refresh\r\n * token is expected (and vice versa) — even when both share the same secret\r\n * under the documented refresh-secret fallback. Legacy tokens minted before\r\n * this claim existed carry no `tokenType` and remain accepted; a *mismatched*\r\n * type is always rejected.\r\n */\r\nexport type TokenType = \"access\" | \"refresh\";\r\n\r\nconst ACCESS_TOKEN_TYPE: TokenType = \"access\";\r\nconst REFRESH_TOKEN_TYPE: TokenType = \"refresh\";\r\n\r\n/**\r\n * Reject the token when its `tokenType` claim is present and does not match the\r\n * expected class. Absent claim ⇒ legacy token, accepted (backward compatible).\r\n */\r\nfunction assertTokenType(decoded: unknown, expected: TokenType): void {\r\n  const actual = (decoded as { tokenType?: unknown } | null | undefined)?.tokenType;\r\n\r\n  if (typeof actual === \"string\" && actual !== expected) {\r\n    throw new Error(`Invalid token type: expected \"${expected}\", received \"${actual}\".`);\r\n  }\r\n}\r\n\r\nexport const jwt = {\r\n  /**\r\n   * Generate a new JWT token for the user.\r\n   * @param payload The payload to encode in the JWT token.\r\n   */\r\n  async generate(\r\n    payload: any,\r\n    {\r\n      key = getSecretKey(),\r\n      algorithm = getAlgorithm(),\r\n      ...options\r\n    }: SignerOptions & { key?: string } = {},\r\n  ): Promise<string> {\r\n    // Create a signer function with predefined options\r\n    const sign = createSigner({ key, ...options, algorithm });\r\n\r\n    const token = await sign({ ...payload, tokenType: ACCESS_TOKEN_TYPE });\r\n    return token;\r\n  },\r\n\r\n  /**\r\n   * Verify the given token.\r\n   * @param token The JWT token to verify.\r\n   * @returns The decoded token payload if verification is successful.\r\n   */\r\n  async verify<T = unknown>(\r\n    token: string,\r\n    {\r\n      key = getSecretKey(),\r\n      algorithms = [getAlgorithm()],\r\n      ...options\r\n    }: VerifierOptions & { key?: string } = {},\r\n  ): Promise<T> {\r\n    const verify = createVerifier({ key, ...options, algorithms });\r\n\r\n    const decoded = await verify(token as string);\r\n\r\n    assertTokenType(decoded, ACCESS_TOKEN_TYPE);\r\n\r\n    return decoded;\r\n  },\r\n\r\n  /**\r\n   * Generate a new refresh token for the user.\r\n   */\r\n  async generateRefreshToken(\r\n    payload: any,\r\n    {\r\n      key = getRefreshSecretKey(),\r\n      expiresIn,\r\n      algorithm = getAlgorithm(),\r\n      ...options\r\n    }: SignerOptions & { key?: string } = {},\r\n  ): Promise<string> {\r\n    const sign = createSigner({ key, expiresIn, algorithm, ...options });\r\n    return sign({ ...payload, tokenType: REFRESH_TOKEN_TYPE });\r\n  },\r\n\r\n  /**\r\n   * Verify the given refresh token.\r\n   */\r\n  async verifyRefreshToken<T = unknown>(\r\n    token: string,\r\n    {\r\n      key = getRefreshSecretKey(),\r\n      algorithms = [getAlgorithm()],\r\n      ...options\r\n    }: VerifierOptions & { key?: string } = {},\r\n  ): Promise<T> {\r\n    const verify = createVerifier({ key, algorithms, ...options });\r\n\r\n    const decoded = await verify(token);\r\n\r\n    assertTokenType(decoded, REFRESH_TOKEN_TYPE);\r\n\r\n    return decoded;\r\n  },\r\n};\r\n"],"mappings":";;;;AAGA,MAAM,qBAAqB,WAAW,YAAY,OAAO;AACzD,MAAM,qBAAqB,WAAW,YAAY,UAAU;AAI5D,MAAM,4BAA4B,WAAW,aAAa,OAAO,KAAK,aAAa;AAYnF,MAAM,oBAA+B;AACrC,MAAM,qBAAgC;;;;;AAMtC,SAAS,gBAAgB,SAAkB,UAA2B;CACpE,MAAM,SAAU,SAAwD;CAExE,IAAI,OAAO,WAAW,YAAY,WAAW,UAC3C,MAAM,IAAI,MAAM,iCAAiC,SAAS,eAAe,OAAO,GAAG;AAEvF;AAEA,MAAa,MAAM;;;;;CAKjB,MAAM,SACJ,SACA,EACE,MAAM,aAAa,GACnB,YAAY,aAAa,GACzB,GAAG,YACiC,CAAC,GACtB;EAKjB,OAAO,MAHM,aAAa;GAAE;GAAK,GAAG;GAAS;EAAU,CAEhC,CAAC,CAAC;GAAE,GAAG;GAAS,WAAW;EAAkB,CAAC;CAEvE;;;;;;CAOA,MAAM,OACJ,OACA,EACE,MAAM,aAAa,GACnB,aAAa,CAAC,aAAa,CAAC,GAC5B,GAAG,YACmC,CAAC,GAC7B;EAGZ,MAAM,UAAU,MAFD,eAAe;GAAE;GAAK,GAAG;GAAS;EAAW,CAEjC,CAAC,CAAC,KAAe;EAE5C,gBAAgB,SAAS,iBAAiB;EAE1C,OAAO;CACT;;;;CAKA,MAAM,qBACJ,SACA,EACE,MAAM,oBAAoB,GAC1B,WACA,YAAY,aAAa,GACzB,GAAG,YACiC,CAAC,GACtB;EAEjB,OADa,aAAa;GAAE;GAAK;GAAW;GAAW,GAAG;EAAQ,CACxD,CAAC,CAAC;GAAE,GAAG;GAAS,WAAW;EAAmB,CAAC;CAC3D;;;;CAKA,MAAM,mBACJ,OACA,EACE,MAAM,oBAAoB,GAC1B,aAAa,CAAC,aAAa,CAAC,GAC5B,GAAG,YACmC,CAAC,GAC7B;EAGZ,MAAM,UAAU,MAFD,eAAe;GAAE;GAAK;GAAY,GAAG;EAAQ,CAEjC,CAAC,CAAC,KAAK;EAElC,gBAAgB,SAAS,kBAAkB;EAE3C,OAAO;CACT;AACF"}

package/esm/utils/auth-error-codes.d.mts

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/auth/src/utils/auth-error-codes.d.ts
+//#region ../@warlock.js/auth/src/utils/auth-error-codes.d.ts
 declare enum AuthErrorCodes {
   /**
    * Missing Access Token Error Code EC001
@@ -16,7 +16,14 @@ declare enum AuthErrorCodes {
    * Unauthorized Error Code EC003
    * EC003 = Unauthorized
    */
-  Unauthorized = "EC003"
+  Unauthorized = "EC003",
+  // Error Code 003
+  /**
+   * Too Many Attempts Error Code EC004
+   * EC004 = Too Many Attempts — issued by the login-throttle middleware once
+   * a per-account or per-IP failure counter trips its threshold.
+   */
+  TooManyAttempts = "EC004"
 }
 //#endregion
 export { AuthErrorCodes };

package/esm/utils/auth-error-codes.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-error-codes.d.mts","names":[],"sources":["../../../../../../@warlock.js/auth/src/utils/auth-error-codes.ts"],"mappings":";aAAY,cAAA;EAAA;;;;EAKV,kBAAA;EAAA;EAKA;;;AAKY;EALZ,kBAAA;EAAA;;;;;EAKA,YAAA;AAAA"}
+{"version":3,"file":"auth-error-codes.d.mts","names":[],"sources":["../../../../../../../@warlock.js/auth/src/utils/auth-error-codes.ts"],"mappings":";aAAY,cAAA;EAAA;;;;EAKV,kBAAA;EAAA;EAKA;;;;EAAA,kBAAA;EAAA;;;;;EAKA,YAAA;EAAA;;;;;;EAMA,eAAA;AAAA"}

package/esm/utils/auth-error-codes.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/auth/src/utils/auth-error-codes.ts
+//#region ../@warlock.js/auth/src/utils/auth-error-codes.ts
 let AuthErrorCodes = /* @__PURE__ */ function(AuthErrorCodes) {
 	/**
 	* Missing Access Token Error Code EC001
@@ -15,6 +15,12 @@ let AuthErrorCodes = /* @__PURE__ */ function(AuthErrorCodes) {
 	* EC003 = Unauthorized
 	*/
 	AuthErrorCodes["Unauthorized"] = "EC003";
+	/**
+	* Too Many Attempts Error Code EC004
+	* EC004 = Too Many Attempts — issued by the login-throttle middleware once
+	* a per-account or per-IP failure counter trips its threshold.
+	*/
+	AuthErrorCodes["TooManyAttempts"] = "EC004";
 	return AuthErrorCodes;
 }({});
 

package/esm/utils/auth-error-codes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"auth-error-codes.mjs","names":[],"sources":["../../../../../../@warlock.js/auth/src/utils/auth-error-codes.ts"],"sourcesContent":["export enum AuthErrorCodes {\n  /**\n   * Missing Access Token Error Code EC001\n   * EC001 = Missing Access Token\n   */\n  MissingAccessToken = \"EC001\", // Error Code 001\n  /**\n   * Invalid Access Token Error Code EC002\n   * EC002 = Invalid Access Token\n   */\n  InvalidAccessToken = \"EC002\", // Error Code 002\n  /**\n   * Unauthorized Error Code EC003\n   * EC003 = Unauthorized\n   */\n  Unauthorized = \"EC003\", // Error Code 003\n}\n"],"mappings":";AAAA,IAAY,iBAAL;;;;;CAKL;;;;;CAKA;;;;;CAKA;;AACF"}
+{"version":3,"file":"auth-error-codes.mjs","names":[],"sources":["../../../../../../../@warlock.js/auth/src/utils/auth-error-codes.ts"],"sourcesContent":["export enum AuthErrorCodes {\n  /**\n   * Missing Access Token Error Code EC001\n   * EC001 = Missing Access Token\n   */\n  MissingAccessToken = \"EC001\", // Error Code 001\n  /**\n   * Invalid Access Token Error Code EC002\n   * EC002 = Invalid Access Token\n   */\n  InvalidAccessToken = \"EC002\", // Error Code 002\n  /**\n   * Unauthorized Error Code EC003\n   * EC003 = Unauthorized\n   */\n  Unauthorized = \"EC003\", // Error Code 003\n  /**\n   * Too Many Attempts Error Code EC004\n   * EC004 = Too Many Attempts — issued by the login-throttle middleware once\n   * a per-account or per-IP failure counter trips its threshold.\n   */\n  TooManyAttempts = \"EC004\", // Error Code 004\n}\n"],"mappings":";AAAA,IAAY,iBAAL;;;;;CAKL;;;;;CAKA;;;;;CAKA;;;;;;CAMA;;AACF"}

package/llms-full.txt

@@ -64,15 +64,16 @@ export default {
     user: User,
     // admin: Admin,  // for multi-user-type
   },
-  jwt: {
+  accessToken: {
     secret: env("JWT_SECRET"),
     expiresIn: "1h",
-    refresh: {
-      enabled: true,
-      expiresIn: "30d",
-      rotation: true,
-      maxPerUser: 5,
-    },
+  },
+  refreshToken: {
+    secret: env("JWT_REFRESH_SECRET"), // recommended: a separate refresh secret
+    enabled: true,
+    expiresIn: "30d",
+    rotation: true,
+    maxPerUser: 5,
   },
 };
 ```
@@ -96,6 +97,122 @@ export default {
 - Don't run `auth.cleanup` from app boot. Schedule it (cron, scheduler) as a periodic task — see [`@warlock.js/scheduler/scheduler-basics/SKILL.md`](@warlock.js/scheduler/scheduler-basics/SKILL.md).
 
 
+## customize-token-storage  `@warlock.js/auth/customize-token-storage/SKILL.md`
+
+---
+name: customize-token-storage
+description: 'Override the persisted AccessToken / RefreshToken models to add columns (multi-tenant `organization_id`, device metadata), rename, or change storage — without forking the package. Extend the model + `schema.extend(...)`, register it under `config.auth.accessToken.model` / `config.auth.refreshToken.model`, override `issue()` to populate the new column, and add a migration. Triggers: `accessToken.model`, `refreshToken.model`, `AccessToken.issue`, `RefreshToken.issue`, `accessTokenSchema`, `refreshTokenSchema`, "add a column to the token table", "multi-tenant tokens", "organization_id on access token", "override the token model", "custom token storage"; typical import `import { AccessToken, accessTokenSchema } from "@warlock.js/auth"`. Skip: multiple user TYPES (not token storage) — `@warlock.js/auth/customize-user-type/SKILL.md`; the token lifecycle API — `@warlock.js/auth/manage-tokens/SKILL.md`; the config blocks themselves — `@warlock.js/auth/auth-basics/SKILL.md`.'
+---
+
+# Customize token storage
+
+The package ships `AccessToken` and `RefreshToken` models and runs the whole token flow through their **named statics** — `issue`, `findByToken`, `activeFor`, `revokeAllFor`, etc. The auth service never references a column name directly; it resolves the *active* model from config. So you change token storage by **registering a subclass**, not by forking.
+
+Reach for this when you need an extra column on the token tables — the common case is a tenant key (`organization_id`) so tokens are partitioned per organization, or richer device metadata.
+
+## The three pieces
+
+A storage override is always three coordinated steps. Miss any one and it breaks — see the strict-mode note below.
+
+### 1. Extend the model + its schema
+
+`accessTokenSchema` / `refreshTokenSchema` are exported so you compose them with `.extend(...)` instead of re-declaring the base shape. Override `issue()` to populate your new column (the user is in hand there).
+
+```ts title="src/app/auth/models/app-access-token.ts"
+import { AccessToken, accessTokenSchema, type Auth } from "@warlock.js/auth";
+import { v } from "@warlock.js/seal";
+
+export class AppAccessToken extends AccessToken {
+  public static schema = accessTokenSchema.extend({
+    organization_id: v.string().exists("Organization", { column: "id" }),
+  });
+
+  // populate the tenant key on issue — read it off the authenticating user
+  public static issue(user: Auth, token: string, expiresAt: Date) {
+    return this.create({
+      token,
+      user_id: user.id,
+      user_type: user.userType,
+      expires_at: expiresAt,
+      organization_id: user.get("organization_id"),
+    });
+  }
+}
+```
+
+Refresh tokens follow the same shape — extend `refreshTokenSchema`, and override `issue(user, token, options)` (`options` is `{ familyId, expiresAt, deviceInfo? }`) the same way, copying the base fields plus your column.
+
+### 2. Register the subclass in config
+
+```ts title="src/config/auth.ts"
+import { AppAccessToken } from "app/auth/models/app-access-token";
+import { AppRefreshToken } from "app/auth/models/app-refresh-token";
+
+export default {
+  userType: { user: User },
+  accessToken: {
+    model: AppAccessToken,            // ← the override
+    secret: env("JWT_SECRET"),
+    expiresIn: "1h",
+  },
+  refreshToken: {
+    model: AppRefreshToken,           // ← the override
+    secret: env("JWT_REFRESH_SECRET"),
+    expiresIn: "30d",
+  },
+};
+```
+
+From here the service, the middleware, and every `authService` helper transparently use your model — `findByToken`, `revokeAllFor`, `enforceMax`, and the rest all run against your columns.
+
+### 3. Add the column to the migration
+
+The new column needs a real database column. Add it to your token-table migration (the FK + index match your `User` model's tenant convention):
+
+```ts
+this.uuid("organization_id").references("organizations").onDelete("cascade").index();
+```
+
+See [`@warlock.js/cascade/write-migration/SKILL.md`](@warlock.js/cascade/write-migration/SKILL.md) for the migration mechanics.
+
+## Why all three — the strict-mode trap
+
+This is the failure people hit. Cascade's `strictMode: "strip"` **drops any field your schema doesn't declare** before the INSERT. So if you set `organization_id` in `issue()` but don't add it to the schema (step 1), the value is silently stripped, and a NOT-NULL `organization_id` column then **fails the INSERT**. The chain is: `issue()` sets it → the *schema* must declare it so it survives → the *migration* must create the column. All three, or nothing.
+
+## You do NOT need read-side scoping
+
+Token lookups go by the unique `token` string (`findByToken`), which already uniquely identifies a row regardless of tenant. So you don't need a tenant-scoped global query scope on the token model — `organization_id` is there for FK cascade-cleanup when an org is deleted, plus partitioning and analytics, not for lookup safety.
+
+## What you're overriding (the contract)
+
+Your subclass inherits and may override these statics — the service calls them, never raw queries:
+
+| Static | Role |
+| --- | --- |
+| `issue(user, token, …)` | persist a freshly-signed token (override to add columns) |
+| `findByToken(token)` | look a row up by its token string |
+| `findForUser(user, token)` | a user-scoped lookup (logout) |
+| `activeFor(user)` | active, unexpired sessions, newest-first |
+| `revokeAllFor(user)` / `revokeFamily(id)` | revoke a set, returning the revoked rows |
+| `enforceMax(user, max)` | cap concurrent refresh tokens |
+| `purgeExpired()` | delete expired rows (CLI cleanup) |
+
+If you rename a column, override the statics that reference it so they map to your name — the service depends on the method, not the column.
+
+## Things NOT to do
+
+- **Don't set a column without declaring it in `schema.extend(...)`.** `strictMode: "strip"` removes it; a NOT-NULL column then fails the INSERT.
+- **Don't add a tenant-scoped global scope to the token model.** Lookups are by unique token; a leaky scope is a cross-tenant exposure risk for no lookup benefit.
+- **Don't fork the package to add a column.** Extend + register — you keep receiving package fixes.
+- **Don't forget the migration.** The schema declares the field; only the migration creates the database column.
+
+## See also
+
+- [`@warlock.js/auth/customize-user-type/SKILL.md`](@warlock.js/auth/customize-user-type/SKILL.md) — multiple user *types* (a different axis from token *storage*).
+- [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md) — the token lifecycle your statics power.
+- [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md) — extending models and schemas.
+
+
 ## customize-user-type  `@warlock.js/auth/customize-user-type/SKILL.md`
 
 ---
@@ -151,10 +268,15 @@ export default {
     // staff: Staff,
     // client: Client,
   },
-  jwt: {
+  accessToken: {
     secret: env("JWT_SECRET"),
     expiresIn: "1h",
-    refresh: { enabled: true, expiresIn: "30d", rotation: true },
+  },
+  refreshToken: {
+    secret: env("JWT_REFRESH_SECRET"),
+    enabled: true,
+    expiresIn: "30d",
+    rotation: true,
   },
 };
 ```
@@ -337,7 +459,7 @@ async function logoutController(request: Request, response: Response) {
 The contract:
 - **Pass the access token** → that specific access-token row is deleted.
 - **Pass the refresh token** → that specific refresh-token row is revoked.
-- **Omit refresh token** → behavior depends on `config.auth.jwt.refresh.logoutWithoutToken`:
+- **Omit refresh token** → behavior depends on `config.auth.refreshToken.logoutWithoutToken`:
   - `"revoke-all"` (default) — every refresh token for this user is revoked. Fail-safe.
   - `"error"` — throws. Force the client to send the refresh token.
 
@@ -420,7 +542,7 @@ type RefreshTokenOutput = { token: string; expiresAt: string };
 
 type TokenPair = {
   accessToken: AccessTokenOutput;
-  refreshToken?: RefreshTokenOutput;   // omitted if config.auth.jwt.refresh.enabled = false
+  refreshToken?: RefreshTokenOutput;   // omitted if config.auth.refreshToken.enabled = false
 };
 ```
 
@@ -439,7 +561,7 @@ const refresh = await authService.createRefreshToken(user, deviceInfo);
 const pair = await authService.createTokenPair(user, deviceInfo);
 ```
 
-`createTokenPair` is the typical issuance path. It respects `config.auth.jwt.refresh.enabled` — if disabled, returns only `accessToken`.
+`createTokenPair` is the typical issuance path. It respects `config.auth.refreshToken.enabled` — if disabled, returns only `accessToken`.
 
 ## Refresh with rotation — `refreshTokens`
 
@@ -453,7 +575,7 @@ What happens internally:
 1. Verify the JWT signature on the old refresh token.
 2. Find the row in `RefreshToken` — must exist + not be revoked.
 3. Look up the user via `config.auth.userType[token.userType]`.
-4. **Rotation** (default — `config.auth.jwt.refresh.rotation = true`): revoke the old refresh token, create a new pair from the same `family_id`.
+4. **Rotation** (default — `config.auth.refreshToken.rotation = true`): revoke the old refresh token, create a new pair from the same `family_id`.
 5. **No rotation**: mark the old as "used" but keep it valid.
 
 **Replay detection.** If the old refresh token is presented again after rotation (already revoked but still in the DB):
@@ -497,7 +619,7 @@ Use this for "active sessions" UIs. Revoke a specific session by calling `.revok
 await authService.removeAccessToken(user, accessTokenString);
 
 // Specific refresh token (via the RefreshToken instance)
-const rt = await RefreshToken.first({ token: refreshString });
+const rt = await RefreshToken.findByToken(refreshString);
 await rt?.revoke();
 
 // All access tokens for a user
@@ -513,7 +635,7 @@ await authService.revokeTokenFamily(familyId);
 ## Max refresh tokens per user
 
 ```ts
-// In config.auth.jwt.refresh:
+// In config.auth.refreshToken:
 {
   maxPerUser: 5,   // default
 }
@@ -525,7 +647,7 @@ When issuing a new refresh token, the service counts active tokens for the user
 
 ```ts
 const cleaned = await authService.cleanupExpiredTokens();
-// Returns: number of expired refresh tokens removed.
+// Returns: number of expired refresh tokens removed (also purges expired access-token rows).
 // Fires "token.expired" event per token + "cleanup.completed" with the count.
 ```
 
@@ -551,19 +673,19 @@ For low-level JWT signing/verification (outside the authService flow):
 ```ts
 import { jwt } from "@warlock.js/auth";
 
-const token = await jwt.generate(payload, { expiresIn: 3600 });
+const token = await jwt.generate(payload, { expiresIn: "1h" }); // string or ms; a bare number is milliseconds
 const decoded = await jwt.verify(token);
 
 const refreshToken = await jwt.generateRefreshToken(payload, { expiresIn });
 const decodedRefresh = await jwt.verifyRefreshToken(refreshToken);
 ```
 
-The package signs access and refresh tokens with independent secrets — `config.auth.jwt.secret` and `config.auth.jwt.refresh.secret`. Setting a distinct `refresh.secret` is recommended: it prevents an access-token compromise from forging refresh tokens (and vice versa). The refresh secret is **optional** — when `config.auth.jwt.refresh.secret` is unset, refresh tokens fall back to the main `config.auth.jwt.secret`, so refresh works out of the box without a second secret.
+The package signs access and refresh tokens with independent secrets — `config.auth.accessToken.secret` and `config.auth.refreshToken.secret`. Setting a distinct `refresh.secret` is recommended: it prevents an access-token compromise from forging refresh tokens (and vice versa). The refresh secret is **optional** — when `config.auth.refreshToken.secret` is unset, refresh tokens fall back to the main `config.auth.accessToken.secret`, so refresh works out of the box without a second secret.
 
 ## Things NOT to do
 
 - Don't use raw JWT libraries directly. The package handles signing, verification, secret loading, and the access/refresh split.
-- Don't disable rotation (`config.auth.jwt.refresh.rotation = false`) unless you genuinely understand the tradeoff — you lose replay detection.
+- Don't disable rotation (`config.auth.refreshToken.rotation = false`) unless you genuinely understand the tradeoff — you lose replay detection.
 - Don't increase `maxPerUser` to a huge number "to be safe." Each active refresh token is a revocation surface; fewer simultaneous tokens means less attack surface.
 - Don't manually delete `AccessToken` rows in a service. The user might be hitting a request mid-revoke and get an inconsistent state. Use the `authService` helpers.
 
@@ -601,7 +723,7 @@ Your user model extends the `Auth` base model and declares its `userType`. A log
 
 ## Skills index
 
-Seven task skills. Most apps need `auth-basics` + `protect-routes` + `handle-login-and-logout`.
+Nine task skills. Most apps need `auth-basics` + `protect-routes` + `handle-login-and-logout`.
 
 ### Foundations
 
@@ -627,6 +749,12 @@ The token lifecycle — `generateAccessToken`, `createRefreshToken`, `createToke
 #### [`customize-user-type`](@warlock.js/auth/customize-user-type/SKILL.md)
 Support multiple user types in one system — each `Auth` subclass overrides `userType`, `config.auth.userType.<slug>` maps the slug to a model class, `authMiddleware("admin")` / `authMiddleware(["admin", "staff"])` gates per type.
 
+#### [`customize-token-storage`](@warlock.js/auth/customize-token-storage/SKILL.md)
+Override the persisted `AccessToken` / `RefreshToken` models to add columns (multi-tenant `organization_id`), rename, or change storage — extend the model + schema and register it under `config.auth.accessToken.model` / `config.auth.refreshToken.model`.
+
+#### [`throttle-login-attempts`](@warlock.js/auth/throttle-login-attempts/SKILL.md)
+Brute-force / credential-stuffing protection — `loginThrottleMiddleware()` counts only failed logins, resets on success, locks per-account + per-IP after a threshold, and rejects pre-controller with 429. Cache-backed, fails open on a cache outage.
+
 #### [`run-auth-commands`](@warlock.js/auth/run-auth-commands/SKILL.md)
 Two CLI commands — `warlock jwt.generate` (strong JWT secret → `.env`) and `warlock auth.cleanup` (remove expired refresh tokens). Register via `registerJWTSecretGeneratorCommand()` and `registerAuthCleanupCommand()`.
 
@@ -751,6 +879,7 @@ The middleware uses the framework's `response.unauthorized({...})` shape. To ove
 
 - [`@warlock.js/auth/customize-user-type/SKILL.md`](@warlock.js/auth/customize-user-type/SKILL.md) — config and multi-user-type semantics
 - [`@warlock.js/auth/handle-login-and-logout/SKILL.md`](@warlock.js/auth/handle-login-and-logout/SKILL.md) — where the access token gets issued in the first place
+- [`@warlock.js/auth/throttle-login-attempts/SKILL.md`](@warlock.js/auth/throttle-login-attempts/SKILL.md) — brute-force throttle to stack in front of the login route
 
 
 ## register-user  `@warlock.js/auth/register-user/SKILL.md`
@@ -1021,3 +1150,123 @@ Register it the same way as the bundled commands — call the factory inside `de
 - [`@warlock.js/scheduler/scheduler-basics/SKILL.md`](@warlock.js/scheduler/scheduler-basics/SKILL.md) — in-process scheduling
 
 
+## throttle-login-attempts  `@warlock.js/auth/throttle-login-attempts/SKILL.md`
+
+---
+name: throttle-login-attempts
+description: 'Brute-force / credential-stuffing protection via `loginThrottleMiddleware` — a failure-aware route gate that counts only failed logins (resets on success), locks per-account and per-source after a threshold, and rejects pre-controller with 429 so the DB lookup and bcrypt verify are skipped. Cache-backed (shared across replicas), fixed-window, fails open on a cache outage. Triggers: `loginThrottleMiddleware`, `AuthErrorCodes.TooManyAttempts`, `EC004`, "rate limit login", "brute force protection", "lock account after failed logins", "throttle login attempts", "too many login attempts 429"; typical import `import { loginThrottleMiddleware } from "@warlock.js/auth"`. Skip: generic per-route request rate limiting that counts every request (use core `middleware.rateLimit`); gating a route by auth — `@warlock.js/auth/protect-routes/SKILL.md`; issuing tokens — `@warlock.js/auth/handle-login-and-logout/SKILL.md`.'
+---
+
+# Throttle login attempts with `loginThrottleMiddleware`
+
+`loginThrottleMiddleware(options?)` returns a Warlock middleware that defends the login (and refresh / password-reset) routes against brute-force and credential-stuffing — without punishing a user who fat-fingers a password then gets it right.
+
+The trick that makes it different from a plain rate limiter: it's **failure-aware**. It hooks the response *after* your controller runs (`response.onSent`), counts only the attempts that actually failed, and **clears the counter the moment a login succeeds**. A generic request limiter can't do that — it runs before the controller and counts every hit, success or not.
+
+## The shortest version
+
+```ts
+import { loginThrottleMiddleware } from "@warlock.js/auth";
+
+router.post("/auth/login", loginController, {
+  middleware: [loginThrottleMiddleware()], // 5 failures / 15m → 15m lockout, per email + ip
+});
+```
+
+That's the whole feature for most apps. Defaults: **5** failed attempts within a **15m** window trips a **15m** lockout, tracked independently per account (the `email` field) **and** per source IP.
+
+> **Heads-up — account-lockout is a DoS surface.** Because the default tracks per-`email`, an attacker who knows a victim's address can lock them out by spamming failed logins. The per-IP counter mitigates it (the attacker's own IP trips too); for purely anonymous endpoints prefer `by: ["ip"]`, and for high-value accounts consider a CAPTCHA step over a hard lock. See [Gotchas](#gotchas).
+
+## How it behaves
+
+1. **Before the controller** — if the account or the IP is currently locked, it short-circuits with `429` and never touches the database or the bcrypt verify (this is also what neutralises the CPU-DoS angle of brute-forcing). The body carries `AuthErrorCodes.TooManyAttempts` (`EC004`).
+2. **After the controller** — it inspects the outcome. A non-2xx response is a failed login: it bumps a fixed-window counter for each tracked identifier, and once a counter reaches `max` it writes a lock key. A 2xx response is a success: it **clears** the counter and lock for that identifier.
+
+Per-account tracking stops a password-spray against one user from many IPs; per-source tracking stops one IP from stuffing many accounts. A lock on **either** identifier rejects the request — defense-in-depth.
+
+## Options
+
+```ts
+loginThrottleMiddleware({
+  max: 5,                 // failures allowed in the window before lockout
+  window: "15m",          // counting window — ms-format string or seconds (number)
+  lockoutDuration: "15m", // how long the lock lasts once tripped
+  by: ["email", "ip"],    // identifiers tracked, each independently
+  identifierKey: "email", // which credential field is the account key
+  errorMessage: "Too many attempts. Try again later.",
+});
+```
+
+Two escape hatches for non-standard setups:
+
+```ts
+loginThrottleMiddleware({
+  // your controller signals failure with a 200 body instead of a status code
+  isFailure: (response) => response.parsedBody?.ok === false,
+
+  // derive the account key from somewhere other than email/ip
+  identify: (request) => [`tenant.${request.input("tenant")}.${request.input("username")}`],
+});
+```
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `max` | `5` | Failures within the window before lockout |
+| `window` | `"15m"` | Counting window (`ms`-string or seconds) |
+| `lockoutDuration` | `"15m"` | Lock TTL once tripped |
+| `by` | `["email", "ip"]` | Identifiers tracked independently |
+| `identifierKey` | `"email"` | Credential field used as the account key |
+| `errorMessage` | i18n `auth.errors.tooManyAttempts` | 429 message override |
+| `isFailure` | `(res) => !res.isOk` | What counts as a failed attempt |
+| `identify` | built-in email + ip extraction | Custom identifier list |
+
+## The 429 response
+
+On lockout the middleware sends:
+
+```jsonc
+{ "error": "...", "errorCode": "EC004" } // AuthErrorCodes.TooManyAttempts
+```
+
+Define the `auth.errors.tooManyAttempts` translation key (or pass `errorMessage`) so clients see a real message instead of the raw key. Map `EC004` in your error transformer the same way you map the other `AuthErrorCodes`.
+
+## Beyond login
+
+The middleware isn't login-specific — drop it on any route where repeated failures should lock something out. For the refresh and reset endpoints there's no email in the body, so track by IP only:
+
+```ts
+router.post("/auth/refresh-token", refreshController, {
+  middleware: [loginThrottleMiddleware({ by: ["ip"], max: 10, window: "1m" })],
+});
+
+router.post("/auth/forgot-password", forgotController, {
+  middleware: [loginThrottleMiddleware({ max: 3, window: "1h", lockoutDuration: "1h" })],
+});
+```
+
+## When to use this vs core's `rateLimit`
+
+| | `loginThrottleMiddleware` (auth) | `middleware.rateLimit` (core) |
+| --- | --- | --- |
+| Counts | only **failed** logins | **every** request |
+| Resets on a successful login | yes | no |
+| Locks per account / per IP | yes | per key (default IP) |
+| Storage | `@warlock.js/cache` (shared across replicas) | in-process map |
+
+They compose. For a hard ceiling on request volume *and* failure-aware account lockout, stack both: `middleware: [middleware.rateLimit({ max: 30, duration: 60_000 }), loginThrottleMiddleware()]`.
+
+## Gotchas
+
+- **Needs an initialised cache driver.** Storage is `@warlock.js/cache` (a peer dep, transitively present via core). If the driver isn't configured at runtime, the middleware **fails open** — it logs and lets the request through, because a throttle outage must never become an auth outage. That also means: no cache, no protection. Verify your cache config in production.
+- **Account lockout can be weaponised.** An attacker who knows a victim's email can lock them out by spamming failures. The per-IP counter mitigates this (the attacker's IP locks too), but for purely anonymous endpoints prefer `by: ["ip"]`. For high-value accounts, consider a CAPTCHA step instead of a hard lock.
+- **Fixed window, not sliding.** The window is anchored at the first failure and does not extend on each subsequent one — predictable lockout timing. The lock key is independent and always lasts `lockoutDuration`.
+- **Defense-in-depth, not a WAF.** This is application-layer. It won't stop a volumetric L3/L4 flood — pair it with an edge/CDN rate limit for that.
+- **Don't call it per-request.** Like every middleware, call it once at route definition; it returns the function that runs per request.
+
+## See also
+
+- [`@warlock.js/auth/protect-routes/SKILL.md`](@warlock.js/auth/protect-routes/SKILL.md) — gate a route behind a valid token (`authMiddleware`); stack the throttle in front of it on login routes.
+- [`@warlock.js/auth/handle-login-and-logout/SKILL.md`](@warlock.js/auth/handle-login-and-logout/SKILL.md) — the login flow whose failures this middleware counts.
+- [`@warlock.js/core/use-middleware/SKILL.md`](@warlock.js/core/use-middleware/SKILL.md) — `middleware.rateLimit` and the built-in middleware suite.
+
+

package/llms.txt

@@ -7,6 +7,7 @@
 ## Skills
 
 - [auth-basics](@warlock.js/auth/auth-basics/SKILL.md): Start with @warlock.js/auth — JWT auth, Auth base model, authMiddleware route gate, authService (login / logout / refresh), AccessToken + RefreshToken persistence, multi-user-type support. Triggers: `Auth`, `authMiddleware`, `authService`, `AccessToken`, `RefreshToken`, `authMigrations`; "set up auth in a new app", "which auth skill do I need", "JWT authentication overview", "wire warlock auth"; typical import `import { authMiddleware, authService, Auth, authMigrations } from "@warlock.js/auth"`. Skip: routing — `@warlock.js/auth/protect-routes/SKILL.md`; login — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; competing libs `passport`, `next-auth`, `lucia-auth`, `auth0`.
+- [customize-token-storage](@warlock.js/auth/customize-token-storage/SKILL.md): Override the persisted AccessToken / RefreshToken models to add columns (multi-tenant `organization_id`, device metadata), rename, or change storage — without forking the package. Extend the model + `schema.extend(...)`, register it under `config.auth.accessToken.model` / `config.auth.refreshToken.model`, override `issue()` to populate the new column, and add a migration. Triggers: `accessToken.model`, `refreshToken.model`, `AccessToken.issue`, `RefreshToken.issue`, `accessTokenSchema`, `refreshTokenSchema`, "add a column to the token table", "multi-tenant tokens", "organization_id on access token", "override the token model", "custom token storage"; typical import `import { AccessToken, accessTokenSchema } from "@warlock.js/auth"`. Skip: multiple user TYPES (not token storage) — `@warlock.js/auth/customize-user-type/SKILL.md`; the token lifecycle API — `@warlock.js/auth/manage-tokens/SKILL.md`; the config blocks themselves — `@warlock.js/auth/auth-basics/SKILL.md`.
 - [customize-user-type](@warlock.js/auth/customize-user-type/SKILL.md): Support multiple user types (user / admin / client / staff) in one auth system — each Auth subclass overrides userType, config.auth.userType.<slug> maps slug to model class, authMiddleware('admin') gates per type. Triggers: `Auth`, `userType`, `config.auth.userType`, `Authenticable`, `@RegisterModel`, `confirmPassword`; "add admins and users", "multiple user types", "separate client and vendor personas", "per-type login"; typical import `import { Auth } from "@warlock.js/auth"`. Skip: `authMiddleware` semantics — `@warlock.js/auth/protect-routes/SKILL.md`; login flow — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; RBAC libs `casl`, `accesscontrol`, `rbac`.
 - [handle-login-and-logout](@warlock.js/auth/handle-login-and-logout/SKILL.md): Run the full login flow via authService.login(Model, credentials, deviceInfo?) — verify password, create access + refresh token pair, fire events. Logout via authService.logout(user, accessToken?, refreshToken?) revokes tokens. Triggers: `authService.login`, `authService.logout`, `authService.attemptLogin`, `authService.refreshTokens`, `authService.revokeAllTokens`, `authEvents`; "build a login endpoint", "POST /login controller", "logout from all devices", "verify credentials and issue tokens"; typical import `import { authService, authEvents } from "@warlock.js/auth"`. Skip: token internals — `@warlock.js/auth/manage-tokens/SKILL.md`; sign-up — `@warlock.js/auth/register-user/SKILL.md`; competing libs `passport-local`, `next-auth` credentials.
 - [manage-tokens](@warlock.js/auth/manage-tokens/SKILL.md): Token lifecycle — generateAccessToken, createRefreshToken, createTokenPair, refreshTokens (with rotation + replay detection), revokeAllTokens, revokeTokenFamily, cleanupExpiredTokens, getActiveSessions. Triggers: `createTokenPair`, `refreshTokens`, `revokeTokenFamily`, `cleanupExpiredTokens`, `getActiveSessions`, `jwt.generate`, `jwt.verify`, `AccessToken`, `RefreshToken`; "rotate refresh tokens", "detect token replay", "logout from all devices", "list active sessions", "clean up expired tokens"; typical import `import { authService, jwt } from "@warlock.js/auth"`. Skip: login flow — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; CLI cleanup — `@warlock.js/auth/run-auth-commands/SKILL.md`; competing libs `jsonwebtoken`, `jose`, `fast-jwt`.
@@ -14,3 +15,4 @@
 - [protect-routes](@warlock.js/auth/protect-routes/SKILL.md): Gate HTTP routes via authMiddleware(allowedUserType) — the argument is required and a valid token is always required: [] allows any authenticated user, a user-type restricts to those types. Sets request.user + request.decodedAccessToken on success, 401 on failure. Triggers: `authMiddleware`, `request.user`, `request.decodedAccessToken`, `AuthErrorCodes`, `MissingAccessToken`, `InvalidAccessToken`; "how do I protect a route", "restrict route by user type", "require any logged-in user"; typical import `import { authMiddleware } from "@warlock.js/auth"`. Skip: multi-user-type config — `@warlock.js/auth/customize-user-type/SKILL.md`; issuing the token — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; competing libs `passport`, `express-jwt`, `next-auth` middleware.
 - [register-user](@warlock.js/auth/register-user/SKILL.md): Sign up a new user and issue the initial token pair — User.create({...password: await hashPassword(plain)}) then authService.createTokenPair(user). Triggers: `User.create`, `hashPassword`, `verifyPassword`, `authService.createTokenPair`, `toJsonColumns`, `strongPassword`, `authEvents`; "build a register endpoint", "POST /register controller", "sign up a new user", "hash password on signup", "email verification flow"; typical import `import { authService } from "@warlock.js/auth"; import { hashPassword } from "@warlock.js/core"`. Skip: login — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; token internals — `@warlock.js/auth/manage-tokens/SKILL.md`; competing libs `bcrypt`, `bcryptjs`, `argon2`.
 - [run-auth-commands](@warlock.js/auth/run-auth-commands/SKILL.md): Two bundled CLI commands — warlock jwt.generate (creates strong JWT secret + writes to .env) and warlock auth.cleanup (removes expired refresh tokens). Register via registerJWTSecretGeneratorCommand() and registerAuthCleanupCommand(). Triggers: `registerJWTSecretGeneratorCommand`, `registerAuthCleanupCommand`, `warlock jwt.generate`, `warlock auth.cleanup`, `cleanupExpiredTokens`, `command`; "generate JWT secret", "bootstrap .env JWT_SECRET", "cron job for expired tokens", "schedule auth cleanup"; typical import `import { registerJWTSecretGeneratorCommand, registerAuthCleanupCommand } from "@warlock.js/auth"`. Skip: programmatic cleanup — `@warlock.js/auth/manage-tokens/SKILL.md`; in-process scheduling — `@warlock.js/scheduler/scheduler-basics/SKILL.md`; competing tools `dotenv-cli`, `node-cron`.
+- [throttle-login-attempts](@warlock.js/auth/throttle-login-attempts/SKILL.md): Brute-force / credential-stuffing protection via `loginThrottleMiddleware` — a failure-aware route gate that counts only failed logins (resets on success), locks per-account and per-source after a threshold, and rejects pre-controller with 429 so the DB lookup and bcrypt verify are skipped. Cache-backed (shared across replicas), fixed-window, fails open on a cache outage. Triggers: `loginThrottleMiddleware`, `AuthErrorCodes.TooManyAttempts`, `EC004`, "rate limit login", "brute force protection", "lock account after failed logins", "throttle login attempts", "too many login attempts 429"; typical import `import { loginThrottleMiddleware } from "@warlock.js/auth"`. Skip: generic per-route request rate limiting that counts every request (use core `middleware.rateLimit`); gating a route by auth — `@warlock.js/auth/protect-routes/SKILL.md`; issuing tokens — `@warlock.js/auth/handle-login-and-logout/SKILL.md`.