@warlock.js/auth 5.18.0 → 5.19.1

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

@@ -23,6 +23,9 @@ const refreshTokenSchema = v.object({
 	expires_at: v.date().required(),
 	last_used_at: v.date().default(() => /* @__PURE__ */ new Date()),
 	revoked_at: v.date().optional(),
+	/** The successor pair a bounded concurrent renewal may reuse. */
+	successor_access_token_id: v.string().optional(),
+	successor_refresh_token_id: v.string().optional(),
 	device_info: v.record(v.any()).optional()
 });
 /**
@@ -140,6 +143,20 @@ var RefreshToken = class extends Model {
 			user_id: user.id
 		});
 	}
+	/** Find any member of a family, including an already-revoked legacy member. */
+	static findInFamily(familyId) {
+		return this.first({ family_id: familyId });
+	}
+	/**
+	* Every refresh lineage for a user, including rotated rows. Logout uses this
+	* to bootstrap durable family records before it starts family revocations.
+	*/
+	static familiesForUser(user) {
+		return this.query().where({
+			user_id: user.id,
+			user_type: user.userType
+		}).get();
+	}
 	/**
 	* Delete a specific refresh token belonging to the user.
 	*/

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

@@ -1 +1 @@
-{"version":3,"file":"refresh-token.model.mjs","names":[],"sources":["../../../../../../../../auth/src/models/refresh-token/refresh-token.model.ts"],"sourcesContent":["import { Model } from \"@warlock.js/cascade\";\r\nimport { v } from \"@warlock.js/seal\";\r\nimport type { DeviceInfo } from \"../../contracts/types\";\r\nimport { isNeverExpiring, isUsableExpiry } from \"../../utils/token-expiry\";\r\nimport type { Auth } from \"../auth.model\";\r\n\r\n/**\r\n * Seal schema for the persisted refresh-token record. Exported so an override\r\n * can spread it and add columns (e.g. a tenant key) without re-declaring the\r\n * base shape:\r\n *\r\n * @example\r\n * export class AppRefreshToken extends RefreshToken {\r\n *   public static schema = refreshTokenSchema.extend({\r\n *     organization_id: v.string().required(),\r\n *   });\r\n * }\r\n */\r\nexport const refreshTokenSchema = v.object({\r\n  token: v.string().required(),\r\n  user_id: v.scalar().required(),\r\n  user_type: v.string().required(),\r\n  family_id: v.string().required(),\r\n  expires_at: v.date().required(),\r\n  last_used_at: v.date().default(() => new Date()),\r\n  revoked_at: v.date().optional(),\r\n  device_info: v.record(v.any()).optional(),\r\n});\r\n\r\n/**\r\n * Extra attributes captured when a refresh token is issued.\r\n */\r\nexport type RefreshTokenIssueOptions = {\r\n  familyId: string;\r\n  expiresAt: string;\r\n  deviceInfo?: DeviceInfo;\r\n};\r\n\r\n/**\r\n * Persisted refresh-token record + the data layer for refresh tokens.\r\n *\r\n * **Role.** Owns every refresh-token read, write, and lifecycle transition.\r\n * The auth service drives refresh-token state exclusively through this model's\r\n * named statics and instance methods, so it never hard-codes a column name —\r\n * which is what makes a snake/camel mismatch (the historical `userId` bug)\r\n * structurally impossible and lets an override rename or add columns by\r\n * extending this class and registering it under `config.auth.refreshToken.model`.\r\n */\r\nexport class RefreshToken extends Model {\r\n  public static table = \"refresh_tokens\";\r\n\r\n  public static schema = refreshTokenSchema;\r\n\r\n  /**\r\n   * The raw signed refresh JWT is a bearer credential — never serialize it.\r\n   * `hidden` only strips it from `toJSON()` / `JSON.stringify(model)` (e.g. a\r\n   * session list returned via `response.json`); `get(\"token\")`,\r\n   * `findByToken` / `findForUser` and every query still read the column.\r\n   */\r\n  public static hidden = [\"token\"];\r\n\r\n  /**\r\n   * Permanent regardless of the data source default — Mongo's driver default\r\n   * is `\"trash\"`, which would copy live credential material (the JWT itself)\r\n   * into `refresh_tokensTrash` on every `destroy()` (expiry purge,\r\n   * never-expiring purge). A purged refresh token must not survive anywhere.\r\n   */\r\n  public static deleteStrategy = \"permanent\" as const;\r\n\r\n  /** Token family this row belongs to (rotation / replay grouping). */\r\n  public get familyId(): string {\r\n    return this.get(\"family_id\");\r\n  }\r\n\r\n  /**\r\n   * Whether the token's `expires_at` is in the past.\r\n   *\r\n   * **Fails closed as of 4.12.0**: a missing or unparseable `expires_at` now\r\n   * counts as expired. It previously answered `false` for both — \"no expiry\r\n   * recorded ⇒ never expires\" — which handed an unlimited life to precisely the\r\n   * malformed rows, including the `Invalid Date` a pre-4.12.0 unparseable\r\n   * `expiresIn` could write. `expires_at` is `required` in the schema, so a row\r\n   * that cannot say when it dies is malformed, not immortal.\r\n   */\r\n  public get isExpired(): boolean {\r\n    const expiresAt = this.get(\"expires_at\");\r\n\r\n    if (!isUsableExpiry(expiresAt)) return true;\r\n\r\n    return new Date().getTime() > new Date(expiresAt).getTime();\r\n  }\r\n\r\n  /**\r\n   * Whether nothing can ever retire this row — an unusable `expires_at`, or a\r\n   * token carrying no `exp` claim. See {@link isNeverExpiring}.\r\n   */\r\n  public get neverExpires(): boolean {\r\n    return isNeverExpiring(this.get(\"token\"), this.get(\"expires_at\"));\r\n  }\r\n\r\n  /** Whether the token has been revoked. */\r\n  public get isRevoked(): boolean {\r\n    return !!this.get(\"revoked_at\");\r\n  }\r\n\r\n  /** Whether the token is still usable (not expired and not revoked). */\r\n  public get isValid(): boolean {\r\n    return !this.isExpired && !this.isRevoked;\r\n  }\r\n\r\n  /**\r\n   * Unconditionally stamp `revoked_at` on this token.\r\n   */\r\n  public async revoke(): Promise<this> {\r\n    return this.merge({ revoked_at: new Date() }).save();\r\n  }\r\n\r\n  /**\r\n   * Atomically revoke this token ONLY if it is still active. Resolves to `true`\r\n   * when this call performed the revoke, `false` when a concurrent request had\r\n   * already revoked it — the win/lose signal that powers rotation replay\r\n   * detection. Uses a conditional UPDATE so two concurrent rotations of the\r\n   * same token can never both succeed.\r\n   */\r\n  public async revokeIfActive(): Promise<boolean> {\r\n    const modelClass = this.constructor as typeof RefreshToken;\r\n\r\n    const revokedCount = await modelClass.atomic(\r\n      { id: this.id, revoked_at: null },\r\n      { $set: { revoked_at: new Date() } },\r\n    );\r\n\r\n    return revokedCount > 0;\r\n  }\r\n\r\n  /**\r\n   * Touch `last_used_at` without revoking — the non-rotating refresh path.\r\n   */\r\n  public async markAsUsed(): Promise<void> {\r\n    await this.merge({ last_used_at: new Date() }).save();\r\n  }\r\n\r\n  /**\r\n   * Persist a freshly-signed refresh token for the user.\r\n   */\r\n  public static issue(user: Auth, token: string, options: RefreshTokenIssueOptions) {\r\n    return this.create({\r\n      token,\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      family_id: options.familyId,\r\n      expires_at: options.expiresAt,\r\n      device_info: options.deviceInfo\r\n        ? {\r\n            userAgent: options.deviceInfo.userAgent,\r\n            ip: options.deviceInfo.ip,\r\n            deviceId: options.deviceInfo.deviceId,\r\n          }\r\n        : undefined,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Find a refresh-token row by its raw token string.\r\n   */\r\n  public static findByToken(token: string): Promise<RefreshToken | null> {\r\n    return this.first({ token });\r\n  }\r\n\r\n  /**\r\n   * Find a refresh token scoped to a user — used by logout so a caller can only\r\n   * revoke a token that actually belongs to them.\r\n   */\r\n  public static findForUser(user: Auth, token: string): Promise<RefreshToken | null> {\r\n    return this.first({ token, user_id: user.id });\r\n  }\r\n\r\n  /**\r\n   * Delete a specific refresh token belonging to the user.\r\n   */\r\n  public static deleteForUser(user: Auth, token: string) {\r\n    return this.delete({ token, user_id: user.id });\r\n  }\r\n\r\n  /**\r\n   * Active, unexpired sessions for the user, newest first.\r\n   */\r\n  public static activeFor(user: Auth): Promise<RefreshToken[]> {\r\n    return this.query()\r\n      .where({ user_id: user.id, user_type: user.userType, revoked_at: null })\r\n      .where(\"expires_at\", \">\", new Date())\r\n      .orderBy(\"created_at\", \"desc\")\r\n      .get();\r\n  }\r\n\r\n  /**\r\n   * Revoke every still-active refresh token for the user, returning the rows\r\n   * that were revoked so the caller can emit a per-token event for each.\r\n   *\r\n   * Rows are fetched BEFORE they are revoked: a bulk `findAndUpdate` keyed on\r\n   * `revoked_at: null` would re-query the same predicate after the update and\r\n   * match nothing, returning an empty set.\r\n   */\r\n  public static async revokeAllFor(user: Auth): Promise<RefreshToken[]> {\r\n    const tokens = await this.query()\r\n      .where({ user_id: user.id, user_type: user.userType, revoked_at: null })\r\n      .get();\r\n\r\n    for (const token of tokens) {\r\n      await token.revoke();\r\n    }\r\n\r\n    return tokens;\r\n  }\r\n\r\n  /**\r\n   * Revoke every still-active token in a family (rotation breach containment),\r\n   * returning the revoked rows (fetched before revocation — see `revokeAllFor`).\r\n   */\r\n  public static async revokeFamily(familyId: string): Promise<RefreshToken[]> {\r\n    const tokens = await this.query().where({ family_id: familyId, revoked_at: null }).get();\r\n\r\n    for (const token of tokens) {\r\n      await token.revoke();\r\n    }\r\n\r\n    return tokens;\r\n  }\r\n\r\n  /**\r\n   * Revoke the oldest active tokens so at most `max - 1` remain — making room\r\n   * for the about-to-be-issued one. Bounded by `max`, so the per-row loop is\r\n   * small.\r\n   */\r\n  public static async enforceMax(user: Auth, max: number): Promise<void> {\r\n    const activeTokens = await this.query()\r\n      .where({ user_id: user.id, user_type: user.userType, revoked_at: null })\r\n      .orderBy(\"created_at\", \"asc\")\r\n      .get();\r\n\r\n    if (activeTokens.length < max) return;\r\n\r\n    const tokensToRevoke = activeTokens.slice(0, activeTokens.length - max + 1);\r\n\r\n    for (const token of tokensToRevoke) {\r\n      await token.revoke();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Hard-delete every expired refresh token, returning the deleted rows so the\r\n   * caller can emit a per-token event. Runs from the `auth.cleanup` CLI command\r\n   * (a cold batch path).\r\n   */\r\n  public static async purgeExpired(): Promise<RefreshToken[]> {\r\n    const expiredTokens = await this.query().where(\"expires_at\", \"<\", new Date()).get();\r\n\r\n    for (const token of expiredTokens) {\r\n      await token.destroy();\r\n    }\r\n\r\n    return expiredTokens;\r\n  }\r\n\r\n  /**\r\n   * Every row that can never retire itself — see {@link neverExpires}. A full\r\n   * scan filtered in memory, for the reason given on\r\n   * {@link AccessToken.findNeverExpiring}: neither an `Invalid Date` nor a\r\n   * missing `exp` claim is expressible as a `where`.\r\n   */\r\n  public static async findNeverExpiring(): Promise<RefreshToken[]> {\r\n    const tokens = await this.query().get();\r\n\r\n    return tokens.filter((token: RefreshToken) => token.neverExpires);\r\n  }\r\n\r\n  /**\r\n   * Hard-delete every never-expiring row, returning the rows removed.\r\n   *\r\n   * Deleted rather than `revoked_at`-stamped: a revoked row is still a row this\r\n   * table has to carry, and one of the two shapes being removed is a row whose\r\n   * date column cannot be compared at all — leaving it in place keeps a\r\n   * permanently unpurgeable record. Rotation replay-detection is unaffected;\r\n   * these rows can no longer be presented successfully either way.\r\n   */\r\n  public static async purgeNeverExpiring(): Promise<RefreshToken[]> {\r\n    const tokens = await this.findNeverExpiring();\r\n\r\n    for (const token of tokens) {\r\n      await token.destroy();\r\n    }\r\n\r\n    return tokens;\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;AAkBA,MAAa,qBAAqB,EAAE,OAAO;CACzC,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS;CAC3B,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS;CAC7B,WAAW,EAAE,OAAO,CAAC,CAAC,SAAS;CAC/B,WAAW,EAAE,OAAO,CAAC,CAAC,SAAS;CAC/B,YAAY,EAAE,KAAK,CAAC,CAAC,SAAS;CAC9B,cAAc,EAAE,KAAK,CAAC,CAAC,8BAAc,IAAI,KAAK,CAAC;CAC/C,YAAY,EAAE,KAAK,CAAC,CAAC,SAAS;CAC9B,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS;AAC1C,CAAC;;;;;;;;;;;AAqBD,IAAa,eAAb,cAAkC,MAAM;;eAChB;;;gBAEC;;;gBAQA,CAAC,OAAO;;;wBAQA;;;CAG/B,IAAW,WAAmB;EAC5B,OAAO,KAAK,IAAI,WAAW;CAC7B;;;;;;;;;;;CAYA,IAAW,YAAqB;EAC9B,MAAM,YAAY,KAAK,IAAI,YAAY;EAEvC,IAAI,CAAC,eAAe,SAAS,GAAG,OAAO;EAEvC,wBAAO,IAAI,KAAK,EAAC,CAAC,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,QAAQ;CAC5D;;;;;CAMA,IAAW,eAAwB;EACjC,OAAO,gBAAgB,KAAK,IAAI,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC;CAClE;;CAGA,IAAW,YAAqB;EAC9B,OAAO,CAAC,CAAC,KAAK,IAAI,YAAY;CAChC;;CAGA,IAAW,UAAmB;EAC5B,OAAO,CAAC,KAAK,aAAa,CAAC,KAAK;CAClC;;;;CAKA,MAAa,SAAwB;EACnC,OAAO,KAAK,MAAM,EAAE,4BAAY,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK;CACrD;;;;;;;;CASA,MAAa,iBAAmC;EAQ9C,OAAO,MAPY,KAAK,YAEc,OACpC;GAAE,IAAI,KAAK;GAAI,YAAY;EAAK,GAChC,EAAE,MAAM,EAAE,4BAAY,IAAI,KAAK,EAAE,EAAE,CACrC,IAEsB;CACxB;;;;CAKA,MAAa,aAA4B;EACvC,MAAM,KAAK,MAAM,EAAE,8BAAc,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK;CACtD;;;;CAKA,OAAc,MAAM,MAAY,OAAe,SAAmC;EAChF,OAAO,KAAK,OAAO;GACjB;GACA,SAAS,KAAK;GACd,WAAW,KAAK;GAChB,WAAW,QAAQ;GACnB,YAAY,QAAQ;GACpB,aAAa,QAAQ,aACjB;IACE,WAAW,QAAQ,WAAW;IAC9B,IAAI,QAAQ,WAAW;IACvB,UAAU,QAAQ,WAAW;GAC/B,IACA;EACN,CAAC;CACH;;;;CAKA,OAAc,YAAY,OAA6C;EACrE,OAAO,KAAK,MAAM,EAAE,MAAM,CAAC;CAC7B;;;;;CAMA,OAAc,YAAY,MAAY,OAA6C;EACjF,OAAO,KAAK,MAAM;GAAE;GAAO,SAAS,KAAK;EAAG,CAAC;CAC/C;;;;CAKA,OAAc,cAAc,MAAY,OAAe;EACrD,OAAO,KAAK,OAAO;GAAE;GAAO,SAAS,KAAK;EAAG,CAAC;CAChD;;;;CAKA,OAAc,UAAU,MAAqC;EAC3D,OAAO,KAAK,MAAM,CAAC,CAChB,MAAM;GAAE,SAAS,KAAK;GAAI,WAAW,KAAK;GAAU,YAAY;EAAK,CAAC,CAAC,CACvE,MAAM,cAAc,qBAAK,IAAI,KAAK,CAAC,CAAC,CACpC,QAAQ,cAAc,MAAM,CAAC,CAC7B,IAAI;CACT;;;;;;;;;CAUA,aAAoB,aAAa,MAAqC;EACpE,MAAM,SAAS,MAAM,KAAK,MAAM,CAAC,CAC9B,MAAM;GAAE,SAAS,KAAK;GAAI,WAAW,KAAK;GAAU,YAAY;EAAK,CAAC,CAAC,CACvE,IAAI;EAEP,KAAK,MAAM,SAAS,QAClB,MAAM,MAAM,OAAO;EAGrB,OAAO;CACT;;;;;CAMA,aAAoB,aAAa,UAA2C;EAC1E,MAAM,SAAS,MAAM,KAAK,MAAM,CAAC,CAAC,MAAM;GAAE,WAAW;GAAU,YAAY;EAAK,CAAC,CAAC,CAAC,IAAI;EAEvF,KAAK,MAAM,SAAS,QAClB,MAAM,MAAM,OAAO;EAGrB,OAAO;CACT;;;;;;CAOA,aAAoB,WAAW,MAAY,KAA4B;EACrE,MAAM,eAAe,MAAM,KAAK,MAAM,CAAC,CACpC,MAAM;GAAE,SAAS,KAAK;GAAI,WAAW,KAAK;GAAU,YAAY;EAAK,CAAC,CAAC,CACvE,QAAQ,cAAc,KAAK,CAAC,CAC5B,IAAI;EAEP,IAAI,aAAa,SAAS,KAAK;EAE/B,MAAM,iBAAiB,aAAa,MAAM,GAAG,aAAa,SAAS,MAAM,CAAC;EAE1E,KAAK,MAAM,SAAS,gBAClB,MAAM,MAAM,OAAO;CAEvB;;;;;;CAOA,aAAoB,eAAwC;EAC1D,MAAM,gBAAgB,MAAM,KAAK,MAAM,CAAC,CAAC,MAAM,cAAc,qBAAK,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI;EAElF,KAAK,MAAM,SAAS,eAClB,MAAM,MAAM,QAAQ;EAGtB,OAAO;CACT;;;;;;;CAQA,aAAoB,oBAA6C;EAG/D,QAAO,MAFc,KAAK,MAAM,CAAC,CAAC,IAAI,EAEzB,CAAC,QAAQ,UAAwB,MAAM,YAAY;CAClE;;;;;;;;;;CAWA,aAAoB,qBAA8C;EAChE,MAAM,SAAS,MAAM,KAAK,kBAAkB;EAE5C,KAAK,MAAM,SAAS,QAClB,MAAM,MAAM,QAAQ;EAGtB,OAAO;CACT;AACF"}
+{"version":3,"file":"refresh-token.model.mjs","names":[],"sources":["../../../../../../../../auth/src/models/refresh-token/refresh-token.model.ts"],"sourcesContent":["import { Model } from \"@warlock.js/cascade\";\r\nimport { v } from \"@warlock.js/seal\";\r\nimport type { DeviceInfo } from \"../../contracts/types\";\r\nimport { isNeverExpiring, isUsableExpiry } from \"../../utils/token-expiry\";\r\nimport type { Auth } from \"../auth.model\";\r\n\r\n/**\r\n * Seal schema for the persisted refresh-token record. Exported so an override\r\n * can spread it and add columns (e.g. a tenant key) without re-declaring the\r\n * base shape:\r\n *\r\n * @example\r\n * export class AppRefreshToken extends RefreshToken {\r\n *   public static schema = refreshTokenSchema.extend({\r\n *     organization_id: v.string().required(),\r\n *   });\r\n * }\r\n */\r\nexport const refreshTokenSchema = v.object({\r\n  token: v.string().required(),\r\n  user_id: v.scalar().required(),\r\n  user_type: v.string().required(),\r\n  family_id: v.string().required(),\r\n  expires_at: v.date().required(),\r\n  last_used_at: v.date().default(() => new Date()),\r\n  revoked_at: v.date().optional(),\r\n  /** The successor pair a bounded concurrent renewal may reuse. */\r\n  successor_access_token_id: v.string().optional(),\r\n  successor_refresh_token_id: v.string().optional(),\r\n  device_info: v.record(v.any()).optional(),\r\n});\r\n\r\n/**\r\n * Extra attributes captured when a refresh token is issued.\r\n */\r\nexport type RefreshTokenIssueOptions = {\r\n  familyId: string;\r\n  expiresAt: string;\r\n  deviceInfo?: DeviceInfo;\r\n};\r\n\r\n/**\r\n * Persisted refresh-token record + the data layer for refresh tokens.\r\n *\r\n * **Role.** Owns every refresh-token read, write, and lifecycle transition.\r\n * The auth service drives refresh-token state exclusively through this model's\r\n * named statics and instance methods, so it never hard-codes a column name —\r\n * which is what makes a snake/camel mismatch (the historical `userId` bug)\r\n * structurally impossible and lets an override rename or add columns by\r\n * extending this class and registering it under `config.auth.refreshToken.model`.\r\n */\r\nexport class RefreshToken extends Model {\r\n  public static table = \"refresh_tokens\";\r\n\r\n  public static schema = refreshTokenSchema;\r\n\r\n  /**\r\n   * The raw signed refresh JWT is a bearer credential — never serialize it.\r\n   * `hidden` only strips it from `toJSON()` / `JSON.stringify(model)` (e.g. a\r\n   * session list returned via `response.json`); `get(\"token\")`,\r\n   * `findByToken` / `findForUser` and every query still read the column.\r\n   */\r\n  public static hidden = [\"token\"];\r\n\r\n  /**\r\n   * Permanent regardless of the data source default — Mongo's driver default\r\n   * is `\"trash\"`, which would copy live credential material (the JWT itself)\r\n   * into `refresh_tokensTrash` on every `destroy()` (expiry purge,\r\n   * never-expiring purge). A purged refresh token must not survive anywhere.\r\n   */\r\n  public static deleteStrategy = \"permanent\" as const;\r\n\r\n  /** Token family this row belongs to (rotation / replay grouping). */\r\n  public get familyId(): string {\r\n    return this.get(\"family_id\");\r\n  }\r\n\r\n  /**\r\n   * Whether the token's `expires_at` is in the past.\r\n   *\r\n   * **Fails closed as of 4.12.0**: a missing or unparseable `expires_at` now\r\n   * counts as expired. It previously answered `false` for both — \"no expiry\r\n   * recorded ⇒ never expires\" — which handed an unlimited life to precisely the\r\n   * malformed rows, including the `Invalid Date` a pre-4.12.0 unparseable\r\n   * `expiresIn` could write. `expires_at` is `required` in the schema, so a row\r\n   * that cannot say when it dies is malformed, not immortal.\r\n   */\r\n  public get isExpired(): boolean {\r\n    const expiresAt = this.get(\"expires_at\");\r\n\r\n    if (!isUsableExpiry(expiresAt)) return true;\r\n\r\n    return new Date().getTime() > new Date(expiresAt).getTime();\r\n  }\r\n\r\n  /**\r\n   * Whether nothing can ever retire this row — an unusable `expires_at`, or a\r\n   * token carrying no `exp` claim. See {@link isNeverExpiring}.\r\n   */\r\n  public get neverExpires(): boolean {\r\n    return isNeverExpiring(this.get(\"token\"), this.get(\"expires_at\"));\r\n  }\r\n\r\n  /** Whether the token has been revoked. */\r\n  public get isRevoked(): boolean {\r\n    return !!this.get(\"revoked_at\");\r\n  }\r\n\r\n  /** Whether the token is still usable (not expired and not revoked). */\r\n  public get isValid(): boolean {\r\n    return !this.isExpired && !this.isRevoked;\r\n  }\r\n\r\n  /**\r\n   * Unconditionally stamp `revoked_at` on this token.\r\n   */\r\n  public async revoke(): Promise<this> {\r\n    return this.merge({ revoked_at: new Date() }).save();\r\n  }\r\n\r\n  /**\r\n   * Atomically revoke this token ONLY if it is still active. Resolves to `true`\r\n   * when this call performed the revoke, `false` when a concurrent request had\r\n   * already revoked it — the win/lose signal that powers rotation replay\r\n   * detection. Uses a conditional UPDATE so two concurrent rotations of the\r\n   * same token can never both succeed.\r\n   */\r\n  public async revokeIfActive(): Promise<boolean> {\r\n    const modelClass = this.constructor as typeof RefreshToken;\r\n\r\n    const revokedCount = await modelClass.atomic(\r\n      { id: this.id, revoked_at: null },\r\n      { $set: { revoked_at: new Date() } },\r\n    );\r\n\r\n    return revokedCount > 0;\r\n  }\r\n\r\n  /**\r\n   * Touch `last_used_at` without revoking — the non-rotating refresh path.\r\n   */\r\n  public async markAsUsed(): Promise<void> {\r\n    await this.merge({ last_used_at: new Date() }).save();\r\n  }\r\n\r\n  /**\r\n   * Persist a freshly-signed refresh token for the user.\r\n   */\r\n  public static issue(user: Auth, token: string, options: RefreshTokenIssueOptions) {\r\n    return this.create({\r\n      token,\r\n      user_id: user.id,\r\n      user_type: user.userType,\r\n      family_id: options.familyId,\r\n      expires_at: options.expiresAt,\r\n      device_info: options.deviceInfo\r\n        ? {\r\n            userAgent: options.deviceInfo.userAgent,\r\n            ip: options.deviceInfo.ip,\r\n            deviceId: options.deviceInfo.deviceId,\r\n          }\r\n        : undefined,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Find a refresh-token row by its raw token string.\r\n   */\r\n  public static findByToken(token: string): Promise<RefreshToken | null> {\r\n    return this.first({ token });\r\n  }\r\n\r\n  /**\r\n   * Find a refresh token scoped to a user — used by logout so a caller can only\r\n   * revoke a token that actually belongs to them.\r\n   */\r\n  public static findForUser(user: Auth, token: string): Promise<RefreshToken | null> {\r\n    return this.first({ token, user_id: user.id });\r\n  }\r\n\r\n  /** Find any member of a family, including an already-revoked legacy member. */\r\n  public static findInFamily(familyId: string): Promise<RefreshToken | null> {\r\n    return this.first({ family_id: familyId });\r\n  }\r\n\r\n  /**\r\n   * Every refresh lineage for a user, including rotated rows. Logout uses this\r\n   * to bootstrap durable family records before it starts family revocations.\r\n   */\r\n  public static familiesForUser(user: Auth): Promise<RefreshToken[]> {\r\n    return this.query().where({ user_id: user.id, user_type: user.userType }).get();\r\n  }\r\n\r\n  /**\r\n   * Delete a specific refresh token belonging to the user.\r\n   */\r\n  public static deleteForUser(user: Auth, token: string) {\r\n    return this.delete({ token, user_id: user.id });\r\n  }\r\n\r\n  /**\r\n   * Active, unexpired sessions for the user, newest first.\r\n   */\r\n  public static activeFor(user: Auth): Promise<RefreshToken[]> {\r\n    return this.query()\r\n      .where({ user_id: user.id, user_type: user.userType, revoked_at: null })\r\n      .where(\"expires_at\", \">\", new Date())\r\n      .orderBy(\"created_at\", \"desc\")\r\n      .get();\r\n  }\r\n\r\n  /**\r\n   * Revoke every still-active refresh token for the user, returning the rows\r\n   * that were revoked so the caller can emit a per-token event for each.\r\n   *\r\n   * Rows are fetched BEFORE they are revoked: a bulk `findAndUpdate` keyed on\r\n   * `revoked_at: null` would re-query the same predicate after the update and\r\n   * match nothing, returning an empty set.\r\n   */\r\n  public static async revokeAllFor(user: Auth): Promise<RefreshToken[]> {\r\n    const tokens = await this.query()\r\n      .where({ user_id: user.id, user_type: user.userType, revoked_at: null })\r\n      .get();\r\n\r\n    for (const token of tokens) {\r\n      await token.revoke();\r\n    }\r\n\r\n    return tokens;\r\n  }\r\n\r\n  /**\r\n   * Revoke every still-active token in a family (rotation breach containment),\r\n   * returning the revoked rows (fetched before revocation — see `revokeAllFor`).\r\n   */\r\n  public static async revokeFamily(familyId: string): Promise<RefreshToken[]> {\r\n    const tokens = await this.query().where({ family_id: familyId, revoked_at: null }).get();\r\n\r\n    for (const token of tokens) {\r\n      await token.revoke();\r\n    }\r\n\r\n    return tokens;\r\n  }\r\n\r\n  /**\r\n   * Revoke the oldest active tokens so at most `max - 1` remain — making room\r\n   * for the about-to-be-issued one. Bounded by `max`, so the per-row loop is\r\n   * small.\r\n   */\r\n  public static async enforceMax(user: Auth, max: number): Promise<void> {\r\n    const activeTokens = await this.query()\r\n      .where({ user_id: user.id, user_type: user.userType, revoked_at: null })\r\n      .orderBy(\"created_at\", \"asc\")\r\n      .get();\r\n\r\n    if (activeTokens.length < max) return;\r\n\r\n    const tokensToRevoke = activeTokens.slice(0, activeTokens.length - max + 1);\r\n\r\n    for (const token of tokensToRevoke) {\r\n      await token.revoke();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Hard-delete every expired refresh token, returning the deleted rows so the\r\n   * caller can emit a per-token event. Runs from the `auth.cleanup` CLI command\r\n   * (a cold batch path).\r\n   */\r\n  public static async purgeExpired(): Promise<RefreshToken[]> {\r\n    const expiredTokens = await this.query().where(\"expires_at\", \"<\", new Date()).get();\r\n\r\n    for (const token of expiredTokens) {\r\n      await token.destroy();\r\n    }\r\n\r\n    return expiredTokens;\r\n  }\r\n\r\n  /**\r\n   * Every row that can never retire itself — see {@link neverExpires}. A full\r\n   * scan filtered in memory, for the reason given on\r\n   * {@link AccessToken.findNeverExpiring}: neither an `Invalid Date` nor a\r\n   * missing `exp` claim is expressible as a `where`.\r\n   */\r\n  public static async findNeverExpiring(): Promise<RefreshToken[]> {\r\n    const tokens = await this.query().get();\r\n\r\n    return tokens.filter((token: RefreshToken) => token.neverExpires);\r\n  }\r\n\r\n  /**\r\n   * Hard-delete every never-expiring row, returning the rows removed.\r\n   *\r\n   * Deleted rather than `revoked_at`-stamped: a revoked row is still a row this\r\n   * table has to carry, and one of the two shapes being removed is a row whose\r\n   * date column cannot be compared at all — leaving it in place keeps a\r\n   * permanently unpurgeable record. Rotation replay-detection is unaffected;\r\n   * these rows can no longer be presented successfully either way.\r\n   */\r\n  public static async purgeNeverExpiring(): Promise<RefreshToken[]> {\r\n    const tokens = await this.findNeverExpiring();\r\n\r\n    for (const token of tokens) {\r\n      await token.destroy();\r\n    }\r\n\r\n    return tokens;\r\n  }\r\n}\r\n"],"mappings":"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"}

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

@@ -0,0 +1,22 @@
+import { RefreshToken } from "./refresh-token.model.mjs";
+import { migrate } from "@warlock.js/cascade";
+
+//#region ../auth/src/models/refresh-token/successor-association.migration.ts
+/** Adds nullable successor links for bounded concurrent refresh coalescing. */
+const RefreshTokenSuccessorAssociationMigration = migrate(RefreshToken, {
+	name: "refreshTokenSuccessorAssociation",
+	up() {
+		this.uuid("successor_access_token_id").nullable().index();
+		this.uuid("successor_refresh_token_id").nullable().index();
+	},
+	down() {
+		this.dropIndex("successor_access_token_id");
+		this.dropIndex("successor_refresh_token_id");
+		this.dropColumn("successor_access_token_id");
+		this.dropColumn("successor_refresh_token_id");
+	}
+});
+
+//#endregion
+export { RefreshTokenSuccessorAssociationMigration };
+//# sourceMappingURL=successor-association.migration.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"successor-association.migration.mjs","names":[],"sources":["../../../../../../../../auth/src/models/refresh-token/successor-association.migration.ts"],"sourcesContent":["import { migrate } from \"@warlock.js/cascade\";\nimport { RefreshToken } from \"./refresh-token.model\";\n\n/** Adds nullable successor links for bounded concurrent refresh coalescing. */\nexport const RefreshTokenSuccessorAssociationMigration = migrate(RefreshToken, {\n  name: \"refreshTokenSuccessorAssociation\",\n  up() {\n    this.uuid(\"successor_access_token_id\").nullable().index();\n    this.uuid(\"successor_refresh_token_id\").nullable().index();\n  },\n  down() {\n    this.dropIndex(\"successor_access_token_id\");\n    this.dropIndex(\"successor_refresh_token_id\");\n    this.dropColumn(\"successor_access_token_id\");\n    this.dropColumn(\"successor_refresh_token_id\");\n  },\n});\n"],"mappings":";;;;;AAIA,MAAa,4CAA4C,QAAQ,cAAc;CAC7E,MAAM;CACN,KAAK;EACH,KAAK,KAAK,2BAA2B,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM;EACxD,KAAK,KAAK,4BAA4B,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM;CAC3D;CACA,OAAO;EACL,KAAK,UAAU,2BAA2B;EAC1C,KAAK,UAAU,4BAA4B;EAC3C,KAAK,WAAW,2BAA2B;EAC3C,KAAK,WAAW,4BAA4B;CAC9C;AACF,CAAC"}

package/esm/services/auth.service.d.mts

@@ -37,6 +37,13 @@ declare class AuthService {
    */
   generateAccessToken(user: Auth, payload?: Record<string, unknown>): Promise<AccessTokenOutput>;
   private issueRefreshToken;
+  /**
+   * Keep issuance into an explicitly reused family in the same durable
+   * transition boundary as rotation and revocation. A new, caller-unspecified
+   * family has no concurrent session to protect and retains the lightweight
+   * issuance path.
+   */
+  private issueInSuppliedFamily;
   /**
    * Sign + persist a refresh token for the user (enforcing the per-user cap
    * first). Resolves to `undefined` when refresh tokens are disabled in config.
@@ -53,6 +60,20 @@ declare class AuthService {
    * is treated as a breach — the whole family is revoked and the request fails.
    */
   refreshTokens(refreshTokenString: string, deviceInfo?: DeviceInfo): Promise<TokenPair | null>;
+  /**
+   * Opt-in browser-session renewal. Unlike {@link refreshTokens}, this permits
+   * a short duplicate presentation to receive the exact committed successor
+   * pair. It is deliberately not used by the legacy/public refresh API.
+   */
+  renewAutomaticSession(refreshTokenString: string, expectedUserType: string, options?: {
+    overlapMs?: number;
+    deviceInfo?: DeviceInfo;
+  }): Promise<TokenPair | null>;
+  private automaticOverlapMs;
+  private refreshIdentityMatches;
+  private hasSuccessor;
+  private isAutomaticOverlapOpen;
+  private readAutomaticSuccessor;
   /**
    * Verify a plaintext password against a stored hash.
    */
@@ -108,7 +129,7 @@ declare class AuthService {
   removeRefreshToken(user: Auth, token: string): Promise<void>;
   /**
    * Revoke every active refresh token for the user and delete their access
-   * tokens — "log out of all devices". Revocation is a single bulk update; an
+   * tokens — "log out of all devices". Each durable family is first marked through its revision coordinator; an
    * event fires per revoked token.
    */
   revokeAllTokens(user: Auth): Promise<void>;

package/esm/services/auth.service.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.service.d.mts","names":[],"sources":["../../../../../../../auth/src/services/auth.service.ts"],"mappings":";;;;;;;;cA0BM,WAAA;;;;AALiD;;;cAYzC,gBAAA;EAqBgC;;;EAAA,YAdhC,iBAAA;EAwDA;;;EAAA,YAjDA,iBAAA;EA0FG;;;EAnFR,uBAAA,CAAwB,IAAA,EAAM,IAAA,GAAO,MAAA;EAsHU;EA7GzC,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EAAA,QAI5B,qBAAA;EAAA,QAMA,gBAAA;EAiHH;;;;;EA5FE,mBAAA,CACX,IAAA,EAAM,IAAA,EACN,OAAA,GAAU,MAAA,oBACT,OAAA,CAAQ,iBAAA;EAAA,QAMG,iBAAA;EA4KN;;;;EA5IK,kBAAA,CACX,IAAA,EAAM,IAAA,EACN,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,YAAA;EAAA,QAQG,cAAA;EAoKC;;;EA1IF,eAAA,CAAgB,IAAA,EAAM,IAAA,EAAM,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,SAAA;EA4IxE;;;;;EAjIU,aAAA,CACX,kBAAA,UACA,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,SAAA;EAoJR;;;EA5EU,cAAA,CAAe,aAAA,UAAuB,cAAA,WAAyB,OAAA;EA2IjB;;;EApI9C,YAAA,CAAa,QAAA,WAAmB,OAAA;EAkJe;;;;EA1I/C,YAAA,WAAuB,IAAA,EAClC,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,IAAA,EAAM,eAAA,GACL,OAAA,CAAQ,CAAA;EAqMK;;;;EArKH,KAAA,WAAgB,IAAA,EAC3B,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,WAAA,EAAa,eAAA,EACb,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,WAAA,CAAY,CAAA;EAsM6B;;;;;;;;;EAnLvC,aAAA,WAAwB,IAAA,EACnC,IAAA,EAAM,CAAA,EACN,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,WAAA,CAAY,CAAA;EAtSX;EAAA,QA6SE,aAAA;EA/RP;;;;;;;;;;EA0TM,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,WAAA,WAAsB,YAAA,YAAwB,OAAA;EAjRtE;;;EA8SK,iBAAA,CAAkB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EA5SxD;;;EAmTU,qBAAA,CAAsB,IAAA,EAAM,IAAA,GAAO,OAAA;EA5QxC;;;EAmRK,kBAAA,CAAmB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EAjRzD;;;;;EA0RU,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EAxPY;;;EAuQzC,iBAAA,CAAkB,QAAA,WAAmB,OAAA;EA5PrC;;;;;;EAwQA,oBAAA,IAAwB,OAAA;EA7LT;;;;;;;;;;EAsNf,uBAAA,IAA2B,OAAA;IACtC,YAAA,EAAc,WAAA;IACd,aAAA,EAAe,YAAA;EAAA;EAtMd;;;;;;;;EAsNU,wBAAA,IAA4B,OAAA;IACvC,YAAA;IACA,aAAA;EAAA;EApLC;;;EAsMU,iBAAA,CAAkB,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,YAAA;EAnLzB;;;;;EAAA,QA4LnB,qBAAA;EAzLL;;;;;;;;;;;;;;;;;;;;;EAwNI,aAAA,CACL,QAAA,EAAU,QAAA,EACV,KAAA,WAAgB,iBAAA,EAChB,OAAA,GAAS,oBAAA;EA9IiC;;;;;;;;;;EAsKrC,eAAA,CAAgB,QAAA,EAAU,QAAA,EAAU,OAAA,GAAS,sBAAA;AAAA;AAAA,cAQzC,WAAA,EAAW,WAAoB"}
+{"version":3,"file":"auth.service.d.mts","names":[],"sources":["../../../../../../../auth/src/services/auth.service.ts"],"mappings":";;;;;;;;cAiCM,WAAA;;;;AAViD;;;cAiBzC,gBAAA;EAqBgC;;;EAAA,YAdhC,iBAAA;EA6DA;;;EAAA,YAtDA,iBAAA;EAwIG;;;EAjIR,uBAAA,CAAwB,IAAA,EAAM,IAAA,GAAO,MAAA;EA8LU;EArLzC,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EAAA,QAI5B,qBAAA;EAAA,QAMA,gBAAA;EA+LH;;;;;EArKE,mBAAA,CACX,IAAA,EAAM,IAAA,EACN,OAAA,GAAU,MAAA,oBACT,OAAA,CAAQ,iBAAA;EAAA,QAMG,iBAAA;EA0asB;;;;;;EAAA,QAjYtB,qBAAA;EAqaM;;;;EArYP,kBAAA,CACX,IAAA,EAAM,IAAA,EACN,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,YAAA;EAAA,QAcG,cAAA;EAuXX;;;EAzUU,eAAA,CAAgB,IAAA,EAAM,IAAA,EAAM,UAAA,GAAa,UAAA,GAAa,OAAA,CAAQ,SAAA;EA+VpD;;;;;EA9UV,aAAA,CACX,kBAAA,UACA,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,SAAA;EA0YgD;;;;;EAhT9C,qBAAA,CACX,kBAAA,UACA,gBAAA,UACA,OAAA;IAAW,SAAA;IAAoB,UAAA,GAAa,UAAA;EAAA,IAC3C,OAAA,CAAQ,SAAA;EAAA,QAiGH,kBAAA;EAAA,QAMA,sBAAA;EAAA,QAWA,YAAA;EAAA,QAMA,sBAAA;EAAA,QAOM,sBAAA;EA2WsC;;;EAzUvC,cAAA,CAAe,aAAA,UAAuB,cAAA,WAAyB,OAAA;EAoXjE;;;EA7WE,YAAA,CAAa,QAAA,WAAmB,OAAA;EAqYkC;;;;EA7XlE,YAAA,WAAuB,IAAA,EAClC,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,IAAA,EAAM,eAAA,GACL,OAAA,CAAQ,CAAA;EAne0B;;;;EAmgBxB,KAAA,WAAgB,IAAA,EAC3B,KAAA,EAAO,UAAA,CAAW,CAAA,GAClB,WAAA,EAAa,eAAA,EACb,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,WAAA,CAAY,CAAA;EA9fM;;;;;;;;;EAihBhB,aAAA,WAAwB,IAAA,EACnC,IAAA,EAAM,CAAA,EACN,UAAA,GAAa,UAAA,GACZ,OAAA,CAAQ,WAAA,CAAY,CAAA;EA7eZ;EAAA,QAofG,aAAA;EArcA;;;;;;;;;;EAgeD,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,WAAA,WAAsB,YAAA,YAAwB,OAAA;EAjYjD;;;EA8ZhB,iBAAA,CAAkB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EA9ZgB;;;EAqa9D,qBAAA,CAAsB,IAAA,EAAM,IAAA,GAAO,OAAA;EAlZ9C;;;EAyZW,kBAAA,CAAmB,IAAA,EAAM,IAAA,EAAM,KAAA,WAAgB,OAAA;EA7T1D;;;;;EAsUW,eAAA,CAAgB,IAAA,EAAM,IAAA,GAAO,OAAA;EAnUvC;;;EAkWU,iBAAA,CAAkB,QAAA,WAAmB,OAAA;EAhP1C;;;;;;EAyTK,oBAAA,IAAwB,OAAA;EAnQxB;;;;;;;;;;EA4RA,uBAAA,IAA2B,OAAA;IACtC,YAAA,EAAc,WAAA;IACd,aAAA,EAAe,YAAA;EAAA;EAnPE;;;;;;;;EAmQN,wBAAA,IAA4B,OAAA;IACvC,YAAA;IACA,aAAA;EAAA;EA9OW;;;EAgQA,iBAAA,CAAkB,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,YAAA;EA/PlD;;;;;EAAA,QAwQM,qBAAA;EA/PM;;;;;;;;;;;;;;;;;;;;;EA8RP,aAAA,CACL,QAAA,EAAU,QAAA,EACV,KAAA,WAAgB,iBAAA,EAChB,OAAA,GAAS,oBAAA;EAlNwB;;;;;;;;;;EA0O5B,eAAA,CAAgB,QAAA,EAAU,QAAA,EAAU,OAAA,GAAS,sBAAA;AAAA;AAAA,cAQzC,WAAA,EAAW,WAAoB"}

package/esm/services/auth.service.mjs

@@ -1,5 +1,7 @@
 import { AccessToken } from "../models/access-token/access-token.model.mjs";
 import "../models/access-token/index.mjs";
+import { AuthTokenFamily } from "../models/auth-token-family/auth-token-family.model.mjs";
+import "../models/auth-token-family/index.mjs";
 import { OneTimeToken } from "../models/one-time-token/one-time-token.model.mjs";
 import "../models/one-time-token/index.mjs";
 import { RefreshToken } from "../models/refresh-token/refresh-token.model.mjs";
@@ -7,8 +9,10 @@ import "../models/refresh-token/index.mjs";
 import { authConfig } from "./auth-config.mjs";
 import { authEvents } from "./auth-events.mjs";
 import { isInvalidCredentialError, jwt } from "./jwt.mjs";
+import { TokenFamilyUnavailableError, afterTokenFamilyOperation, runTokenFamilyOperation } from "./token-family-operation.mjs";
 import { Random } from "@mongez/reinforcements";
 import { ForbiddenError, config, hashPassword, verifyPassword } from "@warlock.js/core";
+import { randomUUID } from "node:crypto";
 
 //#region ../auth/src/services/auth.service.ts
 var AuthService = class {
@@ -50,12 +54,16 @@ var AuthService = class {
 	async assertCanAuthenticate(user) {
 		if (!await this.canAuthenticate(user)) throw new ForbiddenError("This user cannot authenticate.");
 	}
-	async issueAccessToken(user, payload) {
-		const data = payload || this.buildAccessTokenPayload(user);
+	async issueAccessToken(user, payload, familyId) {
+		const data = {
+			...payload || this.buildAccessTokenPayload(user),
+			jti: randomUUID()
+		};
 		const expiresIn = authConfig.accessToken.expiresInMs();
 		const token = await jwt.generate(data, { expiresIn });
 		const expiresAt = new Date(Date.now() + expiresIn);
-		await this.accessTokenModel.issue(user, token, expiresAt);
+		if (familyId) await this.accessTokenModel.issue(user, token, expiresAt, familyId);
+		else await this.accessTokenModel.issue(user, token, expiresAt);
 		return {
 			token,
 			expiresAt: expiresAt.toISOString()
@@ -74,10 +82,12 @@ var AuthService = class {
 		if (!authConfig.refreshToken.enabled()) return;
 		const expiresIn = authConfig.refreshToken.expiresInMs();
 		const familyId = deviceInfo?.familyId || Random.string(32);
+		if ((await AuthTokenFamily.ensure(user, familyId)).isRevoked) throw new Error("Cannot issue tokens for a revoked token family");
 		const payload = {
 			userId: user.id,
 			userType: user.userType,
-			familyId
+			familyId,
+			jti: randomUUID()
 		};
 		const expiresAt = new Date(Date.now() + expiresIn).toISOString();
 		await this.refreshTokenModel.enforceMax(user, authConfig.refreshToken.maxPerUser());
@@ -89,17 +99,41 @@ var AuthService = class {
 		});
 	}
 	/**
+	* Keep issuance into an explicitly reused family in the same durable
+	* transition boundary as rotation and revocation. A new, caller-unspecified
+	* family has no concurrent session to protect and retains the lightweight
+	* issuance path.
+	*/
+	async issueInSuppliedFamily(user, familyId, issue) {
+		if ((await AuthTokenFamily.ensure(user, familyId)).isRevoked) throw new Error("Cannot issue tokens for a revoked token family");
+		try {
+			return await runTokenFamilyOperation(familyId, async () => issue());
+		} catch (error) {
+			if (error instanceof TokenFamilyUnavailableError) throw new Error("Cannot issue tokens for a revoked token family");
+			throw error;
+		}
+	}
+	/**
 	* Sign + persist a refresh token for the user (enforcing the per-user cap
 	* first). Resolves to `undefined` when refresh tokens are disabled in config.
 	*/
 	async createRefreshToken(user, deviceInfo) {
 		if (!authConfig.refreshToken.enabled()) return;
 		await this.assertCanAuthenticate(user);
+		if (deviceInfo?.familyId) return this.issueInSuppliedFamily(user, deviceInfo.familyId, () => this.issueRefreshToken(user, deviceInfo));
 		return this.issueRefreshToken(user, deviceInfo);
 	}
 	async issueTokenPair(user, deviceInfo) {
-		const accessToken = await this.issueAccessToken(user, deviceInfo?.payload);
-		const refreshToken = await this.issueRefreshToken(user, deviceInfo);
+		const refreshEnabled = authConfig.refreshToken.enabled();
+		const familyId = deviceInfo?.familyId || Random.string(32);
+		if (refreshEnabled) {
+			if ((await AuthTokenFamily.ensure(user, familyId)).isRevoked) throw new Error("Cannot issue tokens for a revoked token family");
+		}
+		const accessToken = await this.issueAccessToken(user, deviceInfo?.payload, refreshEnabled ? familyId : void 0);
+		const refreshToken = await this.issueRefreshToken(user, refreshEnabled ? {
+			...deviceInfo,
+			familyId
+		} : deviceInfo);
 		const tokenPair = {
 			accessToken,
 			refreshToken: refreshToken ? {
@@ -107,8 +141,8 @@ var AuthService = class {
 				expiresAt: refreshToken.get("expires_at")
 			} : void 0
 		};
-		authEvents.emit("token.created", user, tokenPair);
-		if (refreshToken) authEvents.emit("session.created", user, refreshToken, deviceInfo);
+		afterTokenFamilyOperation(() => authEvents.emit("token.created", user, tokenPair));
+		if (refreshToken) afterTokenFamilyOperation(() => authEvents.emit("session.created", user, refreshToken, deviceInfo));
 		return tokenPair;
 	}
 	/**
@@ -116,6 +150,7 @@ var AuthService = class {
 	*/
 	async createTokenPair(user, deviceInfo) {
 		await this.assertCanAuthenticate(user);
+		if (authConfig.refreshToken.enabled() && deviceInfo?.familyId) return this.issueInSuppliedFamily(user, deviceInfo.familyId, () => this.issueTokenPair(user, deviceInfo));
 		return this.issueTokenPair(user, deviceInfo);
 	}
 	/**
@@ -132,28 +167,137 @@ var AuthService = class {
 			throw error;
 		}
 		if (!decoded) return null;
-		const refreshToken = await this.refreshTokenModel.findByToken(refreshTokenString);
-		if (!refreshToken?.isValid) {
-			if (refreshToken) await this.revokeTokenFamily(refreshToken.familyId);
-			return null;
+		const presentedToken = await this.refreshTokenModel.findByToken(refreshTokenString);
+		if (!presentedToken || !this.refreshIdentityMatches(presentedToken, decoded)) return null;
+		await AuthTokenFamily.ensure({
+			id: decoded.userId,
+			userType: decoded.userType
+		}, presentedToken.familyId);
+		return runTokenFamilyOperation(presentedToken.familyId, async () => {
+			const refreshToken = await this.refreshTokenModel.findByToken(refreshTokenString);
+			if (!refreshToken || !this.refreshIdentityMatches(refreshToken, decoded)) return null;
+			if (!refreshToken.isValid) {
+				if (refreshToken) await this.revokeTokenFamily(refreshToken.familyId);
+				return null;
+			}
+			const UserModel = config.key(`auth.userType.${decoded.userType}`);
+			if (!UserModel) throw new Error(`User type ${decoded.userType} is unknown type.`);
+			const user = await UserModel.find(decoded.userId);
+			if (!user) return null;
+			if (!await this.canAuthenticate(user)) return null;
+			if (authConfig.refreshToken.rotation()) {
+				if (!await refreshToken.revokeIfActive()) {
+					await this.revokeTokenFamily(refreshToken.familyId);
+					return null;
+				}
+			} else await refreshToken.markAsUsed();
+			const newTokenPair = await this.issueTokenPair(user, {
+				...deviceInfo,
+				familyId: refreshToken.familyId
+			});
+			afterTokenFamilyOperation(() => authEvents.emit("token.refreshed", user, newTokenPair, refreshToken));
+			return newTokenPair;
+		}).catch((error) => {
+			if (error instanceof TokenFamilyUnavailableError) return null;
+			throw error;
+		});
+	}
+	/**
+	* Opt-in browser-session renewal. Unlike {@link refreshTokens}, this permits
+	* a short duplicate presentation to receive the exact committed successor
+	* pair. It is deliberately not used by the legacy/public refresh API.
+	*/
+	async renewAutomaticSession(refreshTokenString, expectedUserType, options = {}) {
+		let decoded;
+		try {
+			decoded = await jwt.verifyRefreshToken(refreshTokenString);
+		} catch (error) {
+			if (isInvalidCredentialError(error)) return null;
+			throw error;
 		}
-		const UserModel = config.key(`auth.userType.${decoded.userType}`);
-		if (!UserModel) throw new Error(`User type ${decoded.userType} is unknown type.`);
-		const user = await UserModel.find(decoded.userId);
-		if (!user) return null;
-		if (!await this.canAuthenticate(user)) return null;
-		if (authConfig.refreshToken.rotation()) {
-			if (!await refreshToken.revokeIfActive()) {
-				await this.revokeTokenFamily(refreshToken.familyId);
+		if (!decoded || decoded.userType !== expectedUserType) return null;
+		const presentedToken = await this.refreshTokenModel.findByToken(refreshTokenString);
+		if (!presentedToken || !this.refreshIdentityMatches(presentedToken, decoded)) return null;
+		await AuthTokenFamily.ensure({
+			id: decoded.userId,
+			userType: decoded.userType
+		}, presentedToken.familyId);
+		return runTokenFamilyOperation(presentedToken.familyId, async () => {
+			const oldToken = await this.refreshTokenModel.findByToken(refreshTokenString);
+			if (!oldToken || !this.refreshIdentityMatches(oldToken, decoded)) return null;
+			if (!oldToken.isValid) {
+				const successor = await this.readAutomaticSuccessor(oldToken, decoded, options.overlapMs);
+				if (successor) return successor;
+				if (this.isAutomaticOverlapOpen(oldToken, options.overlapMs) && this.hasSuccessor(oldToken)) return null;
+				await this.revokeTokenFamily(oldToken.familyId);
 				return null;
 			}
-		} else await refreshToken.markAsUsed();
-		const newTokenPair = await this.issueTokenPair(user, {
-			...deviceInfo,
-			familyId: refreshToken.familyId
+			const UserModel = config.key(`auth.userType.${decoded.userType}`);
+			if (!UserModel) throw new Error(`User type ${decoded.userType} is unknown type.`);
+			const user = await UserModel.find(decoded.userId);
+			if (!user || !await this.canAuthenticate(user)) return null;
+			if (!await oldToken.revokeIfActive()) {
+				const currentToken = await this.refreshTokenModel.findByToken(refreshTokenString);
+				if (!currentToken) return null;
+				const successor = await this.readAutomaticSuccessor(currentToken, decoded, options.overlapMs);
+				if (successor) return successor;
+				if (this.isAutomaticOverlapOpen(currentToken, options.overlapMs) && this.hasSuccessor(currentToken)) return null;
+				await this.revokeTokenFamily(oldToken.familyId);
+				return null;
+			}
+			const pair = await this.issueTokenPair(user, {
+				...options.deviceInfo,
+				familyId: oldToken.familyId
+			});
+			const successorAccess = await this.accessTokenModel.findByToken(pair.accessToken.token);
+			const successorRefresh = pair.refreshToken ? await this.refreshTokenModel.findByToken(pair.refreshToken.token) : null;
+			if (!successorAccess || !successorRefresh) throw new Error("Automatic renewal did not persist a complete successor pair");
+			if (await this.refreshTokenModel.atomic({ id: oldToken.id }, { $set: {
+				successor_access_token_id: successorAccess.id,
+				successor_refresh_token_id: successorRefresh.id
+			} }) !== 1) throw new Error("Automatic renewal could not link its successor pair");
+			afterTokenFamilyOperation(() => authEvents.emit("token.refreshed", user, pair, oldToken));
+			return pair;
+		}).catch((error) => {
+			if (error instanceof TokenFamilyUnavailableError) return null;
+			throw error;
 		});
-		authEvents.emit("token.refreshed", user, newTokenPair, refreshToken);
-		return newTokenPair;
+	}
+	automaticOverlapMs(overlapMs) {
+		return typeof overlapMs === "number" && Number.isFinite(overlapMs) ? Math.max(0, Math.min(1e4, overlapMs)) : 5e3;
+	}
+	refreshIdentityMatches(token, decoded) {
+		return token.familyId === decoded.familyId && token.get("user_id") === decoded.userId && token.get("user_type") === decoded.userType;
+	}
+	hasSuccessor(oldToken) {
+		return Boolean(oldToken.get("successor_access_token_id") && oldToken.get("successor_refresh_token_id"));
+	}
+	isAutomaticOverlapOpen(oldToken, overlapMs) {
+		const revokedAt = oldToken.get("revoked_at");
+		const window = this.automaticOverlapMs(overlapMs);
+		const elapsed = revokedAt ? Date.now() - new Date(revokedAt).getTime() : NaN;
+		return window > 0 && elapsed >= 0 && elapsed <= window;
+	}
+	async readAutomaticSuccessor(oldToken, decoded, overlapMs) {
+		if (!this.isAutomaticOverlapOpen(oldToken, overlapMs)) return null;
+		const accessId = oldToken.get("successor_access_token_id");
+		const refreshId = oldToken.get("successor_refresh_token_id");
+		if (!accessId || !refreshId) return null;
+		const [access, refresh] = await Promise.all([this.accessTokenModel.find(accessId), this.refreshTokenModel.find(refreshId)]);
+		if (!access || access.isExpired || !refresh?.isValid) return null;
+		if (access.get("family_id") !== decoded.familyId || refresh.get("family_id") !== decoded.familyId || access.get("user_id") !== decoded.userId || refresh.get("user_id") !== decoded.userId || access.get("user_type") !== decoded.userType || refresh.get("user_type") !== decoded.userType) return null;
+		const accessExpiry = new Date(access.get("expires_at")).getTime();
+		if (!Number.isFinite(accessExpiry) || accessExpiry <= Date.now()) return null;
+		return {
+			accessToken: {
+				token: access.get("token"),
+				expiresAt: access.get("expires_at")
+			},
+			refreshToken: {
+				token: refresh.get("token"),
+				expiresAt: refresh.get("expires_at")
+			}
+		};
 	}
 	/**
 	* Verify a plaintext password against a stored hash.
@@ -239,7 +383,7 @@ var AuthService = class {
 		if (refreshToken) {
 			const token = await this.refreshTokenModel.findForUser(user, refreshToken);
 			if (token) {
-				await token.revoke();
+				await this.revokeTokenFamily(token.familyId);
 				authEvents.emit("session.destroyed", user, token);
 			}
 		} else {
@@ -269,12 +413,16 @@ var AuthService = class {
 	}
 	/**
 	* Revoke every active refresh token for the user and delete their access
-	* tokens — "log out of all devices". Revocation is a single bulk update; an
+	* tokens — "log out of all devices". Each durable family is first marked through its revision coordinator; an
 	* event fires per revoked token.
 	*/
 	async revokeAllTokens(user) {
-		const revokedTokens = await this.refreshTokenModel.revokeAllFor(user);
-		for (const token of revokedTokens) authEvents.emit("token.revoked", user, token);
+		const existingRows = await this.refreshTokenModel.familiesForUser(user);
+		for (const token of existingRows) await AuthTokenFamily.ensure(user, token.familyId);
+		const families = await AuthTokenFamily.activeFor(user);
+		for (const family of families) await this.revokeTokenFamily(family.get("family_id"));
+		const legacyTokens = await this.refreshTokenModel.revokeAllFor(user);
+		for (const token of legacyTokens) authEvents.emit("token.revoked", user, token);
 		await this.removeAllAccessTokens(user);
 		authEvents.emit("logout.all", user);
 	}
@@ -282,8 +430,44 @@ var AuthService = class {
 	* Revoke an entire token family — rotation breach containment.
 	*/
 	async revokeTokenFamily(familyId) {
-		const revokedTokens = await this.refreshTokenModel.revokeFamily(familyId);
-		authEvents.emit("token.familyRevoked", familyId, revokedTokens);
+		let family = await AuthTokenFamily.findByFamilyId(familyId);
+		if (!family) {
+			const legacyToken = await this.refreshTokenModel.findInFamily(familyId);
+			if (!legacyToken) return;
+			family = await AuthTokenFamily.ensure({
+				id: legacyToken.get("user_id"),
+				userType: legacyToken.get("user_type")
+			}, familyId);
+		}
+		const user = {
+			id: family.get("user_id"),
+			userType: family.get("user_type")
+		};
+		if (family.isRevoked) {
+			const revokedTokens = await this.refreshTokenModel.revokeFamily(familyId);
+			await this.accessTokenModel.deleteFamilyAndLegacyForUser(user, familyId);
+			afterTokenFamilyOperation(() => authEvents.emit("token.familyRevoked", familyId, revokedTokens));
+			return;
+		}
+		let revokedTokens;
+		try {
+			revokedTokens = await runTokenFamilyOperation(familyId, async (currentFamily) => {
+				const familyUser = {
+					id: currentFamily.get("user_id"),
+					userType: currentFamily.get("user_type")
+				};
+				const revision = currentFamily.get("revision");
+				if (await AuthTokenFamily.revoke(familyId, revision) !== 1) throw new Error("Token family revoke lost its revision transition");
+				const familyTokens = await this.refreshTokenModel.revokeFamily(familyId);
+				await this.accessTokenModel.deleteFamilyAndLegacyForUser(familyUser, familyId);
+				return familyTokens;
+			});
+		} catch (error) {
+			if (!(error instanceof TokenFamilyUnavailableError)) throw error;
+			revokedTokens = await this.refreshTokenModel.revokeFamily(familyId);
+			await this.accessTokenModel.deleteFamilyAndLegacyForUser(user, familyId);
+		}
+		afterTokenFamilyOperation(() => authEvents.emit("token.familyRevoked", familyId, revokedTokens));
 	}
 	/**
 	* Delete expired tokens (refresh + access) and spent one-time tokens