@aooth/auth 0.1.49 → 0.1.51

package/dist/atscript-db.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_clock = require("./clock-Bl-H3eqE.cjs");
-const require_payload = require("./payload-BJjvj8AH.cjs");
+const require_payload = require("./payload-HPgyPiek.cjs");
 const require_dynamic_client_store = require("./dynamic-client-store-DykM9QOT.cjs");
 let node_crypto = require("node:crypto");
 //#region src/atscript-db/authz-stores.ts
@@ -324,6 +324,7 @@ function stateToRow(state, token, expiresAt, metadataField) {
 		kind: state.kind,
 		parentCredentialId: state.parentCredentialId,
 		rotatedAt: state.rotatedAt,
+		successor: state.successor,
 		sessionId: state.sessionId,
 		lastSeenAt: state.lastSeenAt
 	};
@@ -351,6 +352,7 @@ function rowToState(row, metadataField) {
 	if (row.kind === "access" || row.kind === "refresh") state.kind = row.kind;
 	if (row.parentCredentialId !== void 0) state.parentCredentialId = row.parentCredentialId;
 	if (row.rotatedAt !== void 0) state.rotatedAt = row.rotatedAt;
+	if (row.successor !== void 0 && row.successor !== null) state.successor = row.successor;
 	if (row.sessionId !== void 0) state.sessionId = row.sessionId;
 	if (row.lastSeenAt !== void 0) state.lastSeenAt = row.lastSeenAt;
 	return state;

package/dist/atscript-db.d.cts

@@ -1,5 +1,5 @@
-import { r as CredentialStore, s as CredentialState, t as Clock } from "./clock-DJ_eroHW.cjs";
-import { c as AuthCodeStore, d as NewAuthCode, h as PendingAuthorizationStore, m as PendingAuthorization, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient } from "./dynamic-client-store-DbiSLOj0.cjs";
+import { c as CredentialSuccessorRef, r as CredentialStore, s as CredentialState, t as Clock } from "./clock-C0O0FCCN.cjs";
+import { c as AuthCodeStore, d as NewAuthCode, h as PendingAuthorizationStore, m as PendingAuthorization, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient } from "./dynamic-client-store-Cujxec8n.cjs";
 
 //#region src/atscript-db/authz-stores.d.ts
 /**
@@ -225,6 +225,7 @@ type AuthCredentialRow<TPayload extends object = object> = {
   kind?: string;
   parentCredentialId?: string;
   rotatedAt?: number;
+  successor?: CredentialSuccessorRef;
   sessionId?: string;
   lastSeenAt?: number;
 } & TPayload;

package/dist/atscript-db.d.mts

@@ -1,5 +1,5 @@
-import { r as CredentialStore, s as CredentialState, t as Clock } from "./clock-DJ_eroHW.mjs";
-import { c as AuthCodeStore, d as NewAuthCode, h as PendingAuthorizationStore, m as PendingAuthorization, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient } from "./dynamic-client-store-DJgtMjPw.mjs";
+import { c as CredentialSuccessorRef, r as CredentialStore, s as CredentialState, t as Clock } from "./clock-C0O0FCCN.mjs";
+import { c as AuthCodeStore, d as NewAuthCode, h as PendingAuthorizationStore, m as PendingAuthorization, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient } from "./dynamic-client-store-DEGFMiTK.mjs";
 
 //#region src/atscript-db/authz-stores.d.ts
 /**
@@ -225,6 +225,7 @@ type AuthCredentialRow<TPayload extends object = object> = {
   kind?: string;
   parentCredentialId?: string;
   rotatedAt?: number;
+  successor?: CredentialSuccessorRef;
   sessionId?: string;
   lastSeenAt?: number;
 } & TPayload;

package/dist/atscript-db.mjs

@@ -1,5 +1,5 @@
 import { t as defaultClock } from "./clock-Bdsep_1j.mjs";
-import { t as credentialPayloadOf } from "./payload-D-DzH5-J.mjs";
+import { t as credentialPayloadOf } from "./payload-DP5zRiXT.mjs";
 import { r as AuthCodeStore, s as PendingAuthorizationStore, t as DynamicClientStore } from "./dynamic-client-store-B1JwFHdP.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/atscript-db/authz-stores.ts
@@ -323,6 +323,7 @@ function stateToRow(state, token, expiresAt, metadataField) {
 		kind: state.kind,
 		parentCredentialId: state.parentCredentialId,
 		rotatedAt: state.rotatedAt,
+		successor: state.successor,
 		sessionId: state.sessionId,
 		lastSeenAt: state.lastSeenAt
 	};
@@ -350,6 +351,7 @@ function rowToState(row, metadataField) {
 	if (row.kind === "access" || row.kind === "refresh") state.kind = row.kind;
 	if (row.parentCredentialId !== void 0) state.parentCredentialId = row.parentCredentialId;
 	if (row.rotatedAt !== void 0) state.rotatedAt = row.rotatedAt;
+	if (row.successor !== void 0 && row.successor !== null) state.successor = row.successor;
 	if (row.sessionId !== void 0) state.sessionId = row.sessionId;
 	if (row.lastSeenAt !== void 0) state.lastSeenAt = row.lastSeenAt;
 	return state;

package/dist/{auth-credential-C3qebKuy.d.mts → auth-credential-C5zD8b0J.d.cts}

@@ -1,4 +1,4 @@
-import { a as AuthContext, c as EnrichedSession, d as RefreshResult, f as SessionEnricher, i as DenylistStore, l as IssueResult, o as CredentialMetadata, p as SessionInfo, r as CredentialStore, s as CredentialState, t as Clock, u as RefreshConfig } from "./clock-DJ_eroHW.mjs";
+import { a as AuthContext, d as RefreshConfig, f as RefreshResult, i as DenylistStore, l as EnrichedSession, m as SessionInfo, o as CredentialMetadata, p as SessionEnricher, r as CredentialStore, s as CredentialState, t as Clock, u as IssueResult } from "./clock-C0O0FCCN.cjs";
 
 //#region src/credential/auth-credential.d.ts
 interface AuthCredentialOptions<TPayload extends object = object> {
@@ -84,16 +84,21 @@ type IssueOptions<TPayload extends object = object> = TPayload & {
    * - `false` — mint NO refresh token even when the instance config exists
    *   (e.g. the authz token endpoint suppressing the paired refresh for a
    *   policy that didn't opt in — no orphaned refresh row).
-   * - `{ ttl? }` — mint a refresh token for this credential; `ttl` (ms)
-   *   overrides the instance `refresh.ttl`. Works WITHOUT an instance config
-   *   (then `ttl` is required). Per-mint families ALWAYS redeem with
+   * - `{ ttl?, graceMs? }` — mint a refresh token for this credential; `ttl`
+   *   (ms) overrides the instance `refresh.ttl`. Works WITHOUT an instance
+   *   config (then `ttl` is required). Per-mint families ALWAYS redeem with
    *   fixed-ceiling (`'always'`) rotation semantics — the family is stamped
    *   `metadata.refreshRotation: "always"` at mint, which `refresh()` honors
    *   over the instance rotation, so rotation never extends the family's
    *   lifetime even on an instance whose sessions rotate `'sliding'`.
+   *   `graceMs` (ms, ≥ 0) fixes the family's rotation grace window the same
+   *   mint-time-authority way (stamped `metadata.rotationGraceMs`, honored
+   *   over the instance `rotationGraceMs`); `0` is strict single-use. Omit to
+   *   inherit the instance window (or its 30 s default).
    */
   refresh?: false | {
     ttl?: number;
+    graceMs?: number;
   };
 };
 /** Options for {@link AuthCredential.refresh}. */
@@ -168,11 +173,18 @@ declare class AuthCredential<TPayload extends object = object> {
   private refreshAlways;
   /**
    * Shared rotation-with-grace mechanism for `sliding` and `always` on stateful
-   * stores. Keeps the old refresh valid + stamps `rotatedAt` on first rotation;
-   * within `rotationGraceMs` of that stamp it re-issues a fresh pair WITHOUT
-   * re-rotating (replay-tolerant); beyond grace it treats the re-presentation
-   * as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs sliding
-   * (`sliding`) expiry for the new refresh token.
+   * stores. The first rotation keeps the old refresh valid and stamps
+   * `rotatedAt` + the {@link CredentialState.successor} pair on it; within the
+   * grace window a re-presentation **re-delivers that same pair verbatim** —
+   * idempotent, minting nothing, with no liveness side effects (no expiry
+   * slide, no `lastSeenAt`) — so a captured stale token teaches an attacker
+   * nothing beyond capturing the original rotation response, and a multi-tab
+   * race converges on one successor. Beyond grace — or once the successor has
+   * itself been rotated or revoked (superseded) — the re-presentation is
+   * treated as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs
+   * sliding (`sliding`) expiry for the new refresh token; the family's
+   * mint-time `metadata.rotationGraceMs` (when stamped) wins over the instance
+   * window, and a window of `0` is strict single-use.
    */
   private rotateWithGrace;
   revoke(token: string): Promise<void>;

package/dist/{auth-credential-CEijxoGU.d.cts → auth-credential-C9xy4X_k.d.mts}

@@ -1,4 +1,4 @@
-import { a as AuthContext, c as EnrichedSession, d as RefreshResult, f as SessionEnricher, i as DenylistStore, l as IssueResult, o as CredentialMetadata, p as SessionInfo, r as CredentialStore, s as CredentialState, t as Clock, u as RefreshConfig } from "./clock-DJ_eroHW.cjs";
+import { a as AuthContext, d as RefreshConfig, f as RefreshResult, i as DenylistStore, l as EnrichedSession, m as SessionInfo, o as CredentialMetadata, p as SessionEnricher, r as CredentialStore, s as CredentialState, t as Clock, u as IssueResult } from "./clock-C0O0FCCN.mjs";
 
 //#region src/credential/auth-credential.d.ts
 interface AuthCredentialOptions<TPayload extends object = object> {
@@ -84,16 +84,21 @@ type IssueOptions<TPayload extends object = object> = TPayload & {
    * - `false` — mint NO refresh token even when the instance config exists
    *   (e.g. the authz token endpoint suppressing the paired refresh for a
    *   policy that didn't opt in — no orphaned refresh row).
-   * - `{ ttl? }` — mint a refresh token for this credential; `ttl` (ms)
-   *   overrides the instance `refresh.ttl`. Works WITHOUT an instance config
-   *   (then `ttl` is required). Per-mint families ALWAYS redeem with
+   * - `{ ttl?, graceMs? }` — mint a refresh token for this credential; `ttl`
+   *   (ms) overrides the instance `refresh.ttl`. Works WITHOUT an instance
+   *   config (then `ttl` is required). Per-mint families ALWAYS redeem with
    *   fixed-ceiling (`'always'`) rotation semantics — the family is stamped
    *   `metadata.refreshRotation: "always"` at mint, which `refresh()` honors
    *   over the instance rotation, so rotation never extends the family's
    *   lifetime even on an instance whose sessions rotate `'sliding'`.
+   *   `graceMs` (ms, ≥ 0) fixes the family's rotation grace window the same
+   *   mint-time-authority way (stamped `metadata.rotationGraceMs`, honored
+   *   over the instance `rotationGraceMs`); `0` is strict single-use. Omit to
+   *   inherit the instance window (or its 30 s default).
    */
   refresh?: false | {
     ttl?: number;
+    graceMs?: number;
   };
 };
 /** Options for {@link AuthCredential.refresh}. */
@@ -168,11 +173,18 @@ declare class AuthCredential<TPayload extends object = object> {
   private refreshAlways;
   /**
    * Shared rotation-with-grace mechanism for `sliding` and `always` on stateful
-   * stores. Keeps the old refresh valid + stamps `rotatedAt` on first rotation;
-   * within `rotationGraceMs` of that stamp it re-issues a fresh pair WITHOUT
-   * re-rotating (replay-tolerant); beyond grace it treats the re-presentation
-   * as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs sliding
-   * (`sliding`) expiry for the new refresh token.
+   * stores. The first rotation keeps the old refresh valid and stamps
+   * `rotatedAt` + the {@link CredentialState.successor} pair on it; within the
+   * grace window a re-presentation **re-delivers that same pair verbatim** —
+   * idempotent, minting nothing, with no liveness side effects (no expiry
+   * slide, no `lastSeenAt`) — so a captured stale token teaches an attacker
+   * nothing beyond capturing the original rotation response, and a multi-tab
+   * race converges on one successor. Beyond grace — or once the successor has
+   * itself been rotated or revoked (superseded) — the re-presentation is
+   * treated as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs
+   * sliding (`sliding`) expiry for the new refresh token; the family's
+   * mint-time `metadata.rotationGraceMs` (when stamped) wins over the instance
+   * window, and a window of `0` is strict single-use.
    */
   private rotateWithGrace;
   revoke(token: string): Promise<void>;

package/dist/authz.cjs

@@ -28,7 +28,10 @@ function tokenPolicyToIssueOptions(policy, clientId) {
 		...policy.payload,
 		...policy.kind !== void 0 && { kind: policy.kind },
 		...policy.ttl !== void 0 && { ttl: policy.ttl },
-		refresh: withRefresh ? { ttl: policy.refresh?.ttl ?? 2592e6 } : false,
+		refresh: withRefresh ? {
+			ttl: policy.refresh?.ttl ?? 2592e6,
+			...policy.refresh?.graceMs !== void 0 && { graceMs: policy.refresh.graceMs }
+		} : false,
 		...withRefresh && { metadata: { authzClientId: clientId } }
 	};
 }

package/dist/authz.d.cts

@@ -1,5 +1,5 @@
-import { t as Clock } from "./clock-DJ_eroHW.cjs";
-import { _ as PendingAuthorizationStoreMemoryOptions, a as DynamicClientStoreMemoryOptions, b as tokenPolicyToIssueOptions, c as AuthCodeStore, d as NewAuthCode, f as DEFAULT_PENDING_TTL_MS, g as PendingAuthorizationStoreMemory, h as PendingAuthorizationStore, i as DynamicClientStoreMemory, l as AuthCodeStoreMemory, m as PendingAuthorization, n as DynamicClientAuthMethod, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient, u as AuthCodeStoreMemoryOptions, v as DEFAULT_AUTHZ_REFRESH_TTL_MS, y as TokenPolicy } from "./dynamic-client-store-DbiSLOj0.cjs";
+import { t as Clock } from "./clock-C0O0FCCN.cjs";
+import { _ as PendingAuthorizationStoreMemoryOptions, a as DynamicClientStoreMemoryOptions, b as tokenPolicyToIssueOptions, c as AuthCodeStore, d as NewAuthCode, f as DEFAULT_PENDING_TTL_MS, g as PendingAuthorizationStoreMemory, h as PendingAuthorizationStore, i as DynamicClientStoreMemory, l as AuthCodeStoreMemory, m as PendingAuthorization, n as DynamicClientAuthMethod, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient, u as AuthCodeStoreMemoryOptions, v as DEFAULT_AUTHZ_REFRESH_TTL_MS, y as TokenPolicy } from "./dynamic-client-store-Cujxec8n.cjs";
 import { JWK } from "jose";
 
 //#region src/authz/authz-errors.d.ts

package/dist/authz.d.mts

@@ -1,5 +1,5 @@
-import { t as Clock } from "./clock-DJ_eroHW.mjs";
-import { _ as PendingAuthorizationStoreMemoryOptions, a as DynamicClientStoreMemoryOptions, b as tokenPolicyToIssueOptions, c as AuthCodeStore, d as NewAuthCode, f as DEFAULT_PENDING_TTL_MS, g as PendingAuthorizationStoreMemory, h as PendingAuthorizationStore, i as DynamicClientStoreMemory, l as AuthCodeStoreMemory, m as PendingAuthorization, n as DynamicClientAuthMethod, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient, u as AuthCodeStoreMemoryOptions, v as DEFAULT_AUTHZ_REFRESH_TTL_MS, y as TokenPolicy } from "./dynamic-client-store-DJgtMjPw.mjs";
+import { t as Clock } from "./clock-C0O0FCCN.mjs";
+import { _ as PendingAuthorizationStoreMemoryOptions, a as DynamicClientStoreMemoryOptions, b as tokenPolicyToIssueOptions, c as AuthCodeStore, d as NewAuthCode, f as DEFAULT_PENDING_TTL_MS, g as PendingAuthorizationStoreMemory, h as PendingAuthorizationStore, i as DynamicClientStoreMemory, l as AuthCodeStoreMemory, m as PendingAuthorization, n as DynamicClientAuthMethod, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient, u as AuthCodeStoreMemoryOptions, v as DEFAULT_AUTHZ_REFRESH_TTL_MS, y as TokenPolicy } from "./dynamic-client-store-DEGFMiTK.mjs";
 import { JWK } from "jose";
 
 //#region src/authz/authz-errors.d.ts

package/dist/authz.mjs

@@ -27,7 +27,10 @@ function tokenPolicyToIssueOptions(policy, clientId) {
 		...policy.payload,
 		...policy.kind !== void 0 && { kind: policy.kind },
 		...policy.ttl !== void 0 && { ttl: policy.ttl },
-		refresh: withRefresh ? { ttl: policy.refresh?.ttl ?? 2592e6 } : false,
+		refresh: withRefresh ? {
+			ttl: policy.refresh?.ttl ?? 2592e6,
+			...policy.refresh?.graceMs !== void 0 && { graceMs: policy.refresh.graceMs }
+		} : false,
 		...withRefresh && { metadata: { authzClientId: clientId } }
 	};
 }

package/dist/{clock-DJ_eroHW.d.cts → clock-C0O0FCCN.d.cts}

@@ -78,6 +78,29 @@ interface CredentialMetadata {
    * sessions are unaffected).
    */
   refreshRotation?: "none" | "always" | "sliding";
+  /**
+   * Per-family rotation grace window in ms — stamped by `issue()` when a
+   * refresh token is minted with a per-mint `graceMs` (e.g. an authz grant's
+   * `TokenPolicy.refresh.graceMs`), and honored by `refresh()` OVER the
+   * instance {@link RefreshConfig.rotationGraceMs}. Same mint-time-authority
+   * mechanism as {@link accessTtl} / {@link refreshRotation}. Absent ⇒ the
+   * instance window (or its 30 s default) applies.
+   */
+  rotationGraceMs?: number;
+}
+/**
+ * The successor pair persisted on a rotated refresh row (see
+ * {@link CredentialState.successor}) so a within-grace re-presentation of the
+ * consumed token re-delivers the SAME tokens the original rotation produced.
+ * Raw token material in a store column matches the store contract's existing
+ * posture: stateful stores already key rows on the raw token, and
+ * {@link CredentialState.parentCredentialId} already carries one.
+ */
+interface CredentialSuccessorRef {
+  accessToken: string;
+  accessExpiresAt: number;
+  refreshToken: string;
+  refreshExpiresAt: number;
 }
 /**
  * Persisted state of a credential — the fixed **envelope**. A consumer's
@@ -99,8 +122,17 @@ interface CredentialState {
   kind?: "access" | "refresh";
   /** For rotated refresh tokens — id of the parent credential this one replaced */
   parentCredentialId?: string;
-  /** Timestamp of rotation; used by sliding rotation grace period */
+  /** Timestamp of rotation; used by the sliding/always rotation grace window */
   rotatedAt?: number;
+  /**
+   * Set alongside {@link rotatedAt} on the OLD refresh row when it is rotated:
+   * the successor pair the rotation produced, re-delivered VERBATIM on a
+   * within-grace re-presentation of this token (idempotent re-delivery — a
+   * grace hit mints nothing, so it grants an attacker no capability beyond
+   * capturing the original rotation response). Dies with the row; only the
+   * family's latest rotation carries a live grace record.
+   */
+  successor?: CredentialSuccessorRef;
   /**
    * Stable id of the session (token family) this credential belongs to. Minted
    * once by `issue()` and copied forward onto every rotation (access + refresh),
@@ -200,11 +232,17 @@ interface RefreshConfig {
    *   activity.
    *
    * Both `'sliding'` and `'always'` are **grace-tolerant** on stateful stores:
-   * a benign concurrent refresh (multi-tab / parallel requests presenting the
-   * just-rotated token) within {@link rotationGraceMs} re-issues a fresh pair
-   * instead of being mistaken for token theft. Because the grace window is
-   * tracked in the store (via {@link CredentialState.rotatedAt}), it is correct
-   * across multiple app instances.
+   * a benign re-presentation of the just-rotated token (multi-tab race, a
+   * rotation response lost to a rolling deploy) within {@link rotationGraceMs}
+   * **re-delivers the SAME successor pair the rotation produced** — idempotent,
+   * minting nothing — instead of being mistaken for token theft. A grace hit
+   * has no liveness side effects: it never slides the refresh expiry and never
+   * stamps `lastSeenAt`, so a captured stale token cannot be used as a
+   * keep-alive. Because the grace window is tracked in the store (via
+   * {@link CredentialState.rotatedAt} + {@link CredentialState.successor}), it
+   * is correct across multiple app instances — and the moment the successor is
+   * itself rotated (or revoked), the old token is dead regardless of the
+   * window (superseded ⇒ the strict theft path).
    *
    * Note: the grace window needs a stateful store (one with `listForUser`).
    * Stateless stores (JWT, Encapsulated) cannot mutate an issued token in place;
@@ -213,7 +251,14 @@ interface RefreshConfig {
    * with a process-local reuse signal (no cross-instance grace).
    */
   rotation?: "none" | "always" | "sliding";
-  /** Grace period for sliding/always rotation, in milliseconds. Defaults to 30_000. */
+  /**
+   * Grace window for sliding/always rotation, in milliseconds. Defaults to
+   * 30_000. Size it to survive a rolling-deploy drain + client retry (30–60 s);
+   * it stays meaningless for offline token theft. An explicit `0` is strict
+   * mode: every re-presentation of a rotated token is treated as theft.
+   * Overridden per family by a per-mint `graceMs`
+   * ({@link CredentialMetadata.rotationGraceMs}).
+   */
   rotationGraceMs?: number;
   /**
    * Revocation scope when refresh-token reuse is detected (replay after grace,
@@ -228,6 +273,16 @@ interface RefreshConfig {
   reuseResponse?: "session" | "user";
   /** Theft detection hook — invoked when a previously-rotated refresh is reused. */
   onRotationReuse?: (state: CredentialState) => void;
+  /**
+   * Audit hook for within-grace re-presentations — invoked with the OLD
+   * (rotated) refresh credential's envelope just before its successor pair is
+   * re-delivered. The benign twin of {@link onRotationReuse}: a trickle of
+   * grace hits correlated with deploys is expected (a rotation response died
+   * with a drained task and the client retried); a spike is someone replaying
+   * tokens. Wire it to the same sink as `onRotationReuse` (e.g. a
+   * `refresh-grace-hit` audit event) to tell the two apart.
+   */
+  onRotationGraceHit?: (state: CredentialState) => void;
 }
 //#endregion
 //#region src/stores/store.d.ts
@@ -309,4 +364,4 @@ interface Clock {
 }
 declare const defaultClock: Clock;
 //#endregion
-export { AuthContext as a, EnrichedSession as c, RefreshResult as d, SessionEnricher as f, DenylistStore as i, IssueResult as l, defaultClock as n, CredentialMetadata as o, SessionInfo as p, CredentialStore as r, CredentialState as s, Clock as t, RefreshConfig as u };
+export { AuthContext as a, CredentialSuccessorRef as c, RefreshConfig as d, RefreshResult as f, DenylistStore as i, EnrichedSession as l, SessionInfo as m, defaultClock as n, CredentialMetadata as o, SessionEnricher as p, CredentialStore as r, CredentialState as s, Clock as t, IssueResult as u };

package/dist/{clock-DJ_eroHW.d.mts → clock-C0O0FCCN.d.mts}

@@ -78,6 +78,29 @@ interface CredentialMetadata {
    * sessions are unaffected).
    */
   refreshRotation?: "none" | "always" | "sliding";
+  /**
+   * Per-family rotation grace window in ms — stamped by `issue()` when a
+   * refresh token is minted with a per-mint `graceMs` (e.g. an authz grant's
+   * `TokenPolicy.refresh.graceMs`), and honored by `refresh()` OVER the
+   * instance {@link RefreshConfig.rotationGraceMs}. Same mint-time-authority
+   * mechanism as {@link accessTtl} / {@link refreshRotation}. Absent ⇒ the
+   * instance window (or its 30 s default) applies.
+   */
+  rotationGraceMs?: number;
+}
+/**
+ * The successor pair persisted on a rotated refresh row (see
+ * {@link CredentialState.successor}) so a within-grace re-presentation of the
+ * consumed token re-delivers the SAME tokens the original rotation produced.
+ * Raw token material in a store column matches the store contract's existing
+ * posture: stateful stores already key rows on the raw token, and
+ * {@link CredentialState.parentCredentialId} already carries one.
+ */
+interface CredentialSuccessorRef {
+  accessToken: string;
+  accessExpiresAt: number;
+  refreshToken: string;
+  refreshExpiresAt: number;
 }
 /**
  * Persisted state of a credential — the fixed **envelope**. A consumer's
@@ -99,8 +122,17 @@ interface CredentialState {
   kind?: "access" | "refresh";
   /** For rotated refresh tokens — id of the parent credential this one replaced */
   parentCredentialId?: string;
-  /** Timestamp of rotation; used by sliding rotation grace period */
+  /** Timestamp of rotation; used by the sliding/always rotation grace window */
   rotatedAt?: number;
+  /**
+   * Set alongside {@link rotatedAt} on the OLD refresh row when it is rotated:
+   * the successor pair the rotation produced, re-delivered VERBATIM on a
+   * within-grace re-presentation of this token (idempotent re-delivery — a
+   * grace hit mints nothing, so it grants an attacker no capability beyond
+   * capturing the original rotation response). Dies with the row; only the
+   * family's latest rotation carries a live grace record.
+   */
+  successor?: CredentialSuccessorRef;
   /**
    * Stable id of the session (token family) this credential belongs to. Minted
    * once by `issue()` and copied forward onto every rotation (access + refresh),
@@ -200,11 +232,17 @@ interface RefreshConfig {
    *   activity.
    *
    * Both `'sliding'` and `'always'` are **grace-tolerant** on stateful stores:
-   * a benign concurrent refresh (multi-tab / parallel requests presenting the
-   * just-rotated token) within {@link rotationGraceMs} re-issues a fresh pair
-   * instead of being mistaken for token theft. Because the grace window is
-   * tracked in the store (via {@link CredentialState.rotatedAt}), it is correct
-   * across multiple app instances.
+   * a benign re-presentation of the just-rotated token (multi-tab race, a
+   * rotation response lost to a rolling deploy) within {@link rotationGraceMs}
+   * **re-delivers the SAME successor pair the rotation produced** — idempotent,
+   * minting nothing — instead of being mistaken for token theft. A grace hit
+   * has no liveness side effects: it never slides the refresh expiry and never
+   * stamps `lastSeenAt`, so a captured stale token cannot be used as a
+   * keep-alive. Because the grace window is tracked in the store (via
+   * {@link CredentialState.rotatedAt} + {@link CredentialState.successor}), it
+   * is correct across multiple app instances — and the moment the successor is
+   * itself rotated (or revoked), the old token is dead regardless of the
+   * window (superseded ⇒ the strict theft path).
    *
    * Note: the grace window needs a stateful store (one with `listForUser`).
    * Stateless stores (JWT, Encapsulated) cannot mutate an issued token in place;
@@ -213,7 +251,14 @@ interface RefreshConfig {
    * with a process-local reuse signal (no cross-instance grace).
    */
   rotation?: "none" | "always" | "sliding";
-  /** Grace period for sliding/always rotation, in milliseconds. Defaults to 30_000. */
+  /**
+   * Grace window for sliding/always rotation, in milliseconds. Defaults to
+   * 30_000. Size it to survive a rolling-deploy drain + client retry (30–60 s);
+   * it stays meaningless for offline token theft. An explicit `0` is strict
+   * mode: every re-presentation of a rotated token is treated as theft.
+   * Overridden per family by a per-mint `graceMs`
+   * ({@link CredentialMetadata.rotationGraceMs}).
+   */
   rotationGraceMs?: number;
   /**
    * Revocation scope when refresh-token reuse is detected (replay after grace,
@@ -228,6 +273,16 @@ interface RefreshConfig {
   reuseResponse?: "session" | "user";
   /** Theft detection hook — invoked when a previously-rotated refresh is reused. */
   onRotationReuse?: (state: CredentialState) => void;
+  /**
+   * Audit hook for within-grace re-presentations — invoked with the OLD
+   * (rotated) refresh credential's envelope just before its successor pair is
+   * re-delivered. The benign twin of {@link onRotationReuse}: a trickle of
+   * grace hits correlated with deploys is expected (a rotation response died
+   * with a drained task and the client retried); a spike is someone replaying
+   * tokens. Wire it to the same sink as `onRotationReuse` (e.g. a
+   * `refresh-grace-hit` audit event) to tell the two apart.
+   */
+  onRotationGraceHit?: (state: CredentialState) => void;
 }
 //#endregion
 //#region src/stores/store.d.ts
@@ -309,4 +364,4 @@ interface Clock {
 }
 declare const defaultClock: Clock;
 //#endregion
-export { AuthContext as a, EnrichedSession as c, RefreshResult as d, SessionEnricher as f, DenylistStore as i, IssueResult as l, defaultClock as n, CredentialMetadata as o, SessionInfo as p, CredentialStore as r, CredentialState as s, Clock as t, RefreshConfig as u };
+export { AuthContext as a, CredentialSuccessorRef as c, RefreshConfig as d, RefreshResult as f, DenylistStore as i, EnrichedSession as l, SessionInfo as m, defaultClock as n, CredentialMetadata as o, SessionEnricher as p, CredentialStore as r, CredentialState as s, Clock as t, IssueResult as u };

package/dist/{dynamic-client-store-DJgtMjPw.d.mts → dynamic-client-store-Cujxec8n.d.cts}

@@ -1,5 +1,5 @@
-import { t as Clock } from "./clock-DJ_eroHW.mjs";
-import { r as IssueOptions } from "./auth-credential-C3qebKuy.mjs";
+import { t as Clock } from "./clock-C0O0FCCN.cjs";
+import { r as IssueOptions } from "./auth-credential-C5zD8b0J.cjs";
 
 //#region src/authz/token-policy.d.ts
 /**
@@ -37,9 +37,19 @@ interface TokenPolicy {
    * dynamic clients) — the family is stamped with `metadata.authzClientId` and
    * a refresh token redeems only for that client. A clientless (Tier-1
    * loopback) grant has nothing to bind to, so the flag is IGNORED there.
+   *
+   * `graceMs` (ms, ≥ 0) fixes the family's rotation grace window — the window
+   * within which re-presenting a just-rotated refresh token idempotently
+   * re-delivers the same successor pair instead of tripping theft detection
+   * (a connector refreshing against a redeploying server survives the lost
+   * response instead of bricking until re-consent). Stamped at mint
+   * (`metadata.rotationGraceMs`) and honored over the credential instance's
+   * `rotationGraceMs`; `0` is strict single-use. Absent ⇒ the instance window
+   * (or its 30 s default).
    */
   refresh?: {
     ttl?: number;
+    graceMs?: number;
   };
 }
 /**

package/dist/{dynamic-client-store-DbiSLOj0.d.cts → dynamic-client-store-DEGFMiTK.d.mts}

@@ -1,5 +1,5 @@
-import { t as Clock } from "./clock-DJ_eroHW.cjs";
-import { r as IssueOptions } from "./auth-credential-CEijxoGU.cjs";
+import { t as Clock } from "./clock-C0O0FCCN.mjs";
+import { r as IssueOptions } from "./auth-credential-C9xy4X_k.mjs";
 
 //#region src/authz/token-policy.d.ts
 /**
@@ -37,9 +37,19 @@ interface TokenPolicy {
    * dynamic clients) — the family is stamped with `metadata.authzClientId` and
    * a refresh token redeems only for that client. A clientless (Tier-1
    * loopback) grant has nothing to bind to, so the flag is IGNORED there.
+   *
+   * `graceMs` (ms, ≥ 0) fixes the family's rotation grace window — the window
+   * within which re-presenting a just-rotated refresh token idempotently
+   * re-delivers the same successor pair instead of tripping theft detection
+   * (a connector refreshing against a redeploying server survives the lost
+   * response instead of bricking until re-consent). Stamped at mint
+   * (`metadata.rotationGraceMs`) and honored over the credential instance's
+   * `rotationGraceMs`; `0` is strict single-use. Absent ⇒ the instance window
+   * (or its 30 s default).
    */
   refresh?: {
     ttl?: number;
+    graceMs?: number;
   };
 }
 /**

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_clock = require("./clock-Bl-H3eqE.cjs");
-const require_payload = require("./payload-BJjvj8AH.cjs");
+const require_payload = require("./payload-HPgyPiek.cjs");
 const require_opaque_token = require("./opaque-token-CaZgD2i6.cjs");
 let node_crypto = require("node:crypto");
 let jose = require("jose");
@@ -583,6 +583,8 @@ var AuthCredential = class {
 		this.clock = opts.clock ?? require_clock.defaultClock;
 		if (this.accessTtl <= 0) throw new AuthError("INVALID_CONFIG", `accessTtl must be > 0 (got ${this.accessTtl})`);
 		if (this.refreshConfig && this.refreshConfig.ttl <= 0) throw new AuthError("INVALID_CONFIG", `refresh.ttl must be > 0 (got ${this.refreshConfig.ttl})`);
+		const graceMs = this.refreshConfig?.rotationGraceMs;
+		if (graceMs !== void 0 && graceMs < 0) throw new AuthError("INVALID_CONFIG", `refresh.rotationGraceMs must be >= 0 (got ${graceMs})`);
 	}
 	async issue(userId, options) {
 		if (this.maxConcurrent !== void 0 && this.store.listForUser) await this.enforceConcurrencyLimit(userId);
@@ -594,6 +596,7 @@ var AuthCredential = class {
 			refreshTtl = refresh.ttl ?? this.refreshConfig?.ttl;
 			if (refreshTtl === void 0) throw new AuthError("INVALID_CONFIG", "issue: per-mint refresh needs a ttl when no instance refresh config exists");
 			if (refreshTtl <= 0) throw new AuthError("INVALID_CONFIG", `issue: refresh.ttl must be > 0 (got ${refreshTtl})`);
+			if (refresh.graceMs !== void 0 && refresh.graceMs < 0) throw new AuthError("INVALID_CONFIG", `issue: refresh.graceMs must be >= 0 (got ${refresh.graceMs})`);
 		}
 		const perMintRefresh = refresh !== void 0 && refresh !== false;
 		const stampAccessTtl = refreshTtl !== void 0 && ttl !== void 0;
@@ -601,7 +604,8 @@ var AuthCredential = class {
 			...metadata,
 			...kind !== void 0 && { credentialKind: kind },
 			...stampAccessTtl && { accessTtl: ttl },
-			...perMintRefresh && { refreshRotation: "always" }
+			...perMintRefresh && { refreshRotation: "always" },
+			...perMintRefresh && refresh.graceMs !== void 0 && { rotationGraceMs: refresh.graceMs }
 		} : metadata;
 		if (ttl !== void 0 && expiresAt !== void 0) throw new AuthError("INVALID_CONFIG", "issue: pass either `ttl` or `expiresAt`, not both");
 		if (ttl !== void 0 && ttl <= 0) throw new AuthError("INVALID_CONFIG", `issue: ttl must be > 0 (got ${ttl})`);
@@ -715,23 +719,48 @@ var AuthCredential = class {
 	}
 	/**
 	* Shared rotation-with-grace mechanism for `sliding` and `always` on stateful
-	* stores. Keeps the old refresh valid + stamps `rotatedAt` on first rotation;
-	* within `rotationGraceMs` of that stamp it re-issues a fresh pair WITHOUT
-	* re-rotating (replay-tolerant); beyond grace it treats the re-presentation
-	* as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs sliding
-	* (`sliding`) expiry for the new refresh token.
+	* stores. The first rotation keeps the old refresh valid and stamps
+	* `rotatedAt` + the {@link CredentialState.successor} pair on it; within the
+	* grace window a re-presentation **re-delivers that same pair verbatim** —
+	* idempotent, minting nothing, with no liveness side effects (no expiry
+	* slide, no `lastSeenAt`) — so a captured stale token teaches an attacker
+	* nothing beyond capturing the original rotation response, and a multi-tab
+	* race converges on one successor. Beyond grace — or once the successor has
+	* itself been rotated or revoked (superseded) — the re-presentation is
+	* treated as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs
+	* sliding (`sliding`) expiry for the new refresh token; the family's
+	* mint-time `metadata.rotationGraceMs` (when stamped) wins over the instance
+	* window, and a window of `0` is strict single-use.
 	*/
 	async rotateWithGrace(oldState, refreshToken, now, preserveExpiry) {
-		const graceMs = this.refreshConfig?.rotationGraceMs ?? DEFAULT_ROTATION_GRACE_MS;
+		const graceMs = oldState.metadata?.rotationGraceMs ?? this.refreshConfig?.rotationGraceMs ?? DEFAULT_ROTATION_GRACE_MS;
 		if (typeof oldState.rotatedAt !== "number") return await this.issueRotatedPair(oldState, refreshToken, true, now, preserveExpiry);
-		if (now - oldState.rotatedAt > graceMs) await this.respondToRefreshReuse({
+		const reuse = {
 			userId: oldState.userId,
 			sessionId: oldState.sessionId,
 			issuedAt: oldState.issuedAt,
 			expiresAt: oldState.expiresAt,
 			rotatedAt: oldState.rotatedAt
+		};
+		if (graceMs <= 0 || now - oldState.rotatedAt > graceMs) return await this.respondToRefreshReuse(reuse);
+		const successor = oldState.successor;
+		const successorState = successor === void 0 ? null : await this.store.retrieve(successor.refreshToken);
+		if (successor === void 0 || successorState === null || typeof successorState.rotatedAt === "number") return await this.respondToRefreshReuse(reuse);
+		this.refreshConfig?.onRotationGraceHit?.({
+			userId: oldState.userId,
+			issuedAt: oldState.issuedAt,
+			expiresAt: oldState.expiresAt,
+			kind: "refresh",
+			rotatedAt: oldState.rotatedAt,
+			...oldState.sessionId !== void 0 && { sessionId: oldState.sessionId }
 		});
-		return await this.issueRotatedPair(oldState, refreshToken, false, now, preserveExpiry);
+		return {
+			accessToken: successor.accessToken,
+			accessExpiresAt: successor.accessExpiresAt,
+			refreshToken: successor.refreshToken,
+			refreshExpiresAt: successor.refreshExpiresAt,
+			userId: oldState.userId
+		};
 	}
 	async revoke(token) {
 		await this.store.revoke(token);
@@ -909,7 +938,13 @@ var AuthCredential = class {
 		if (rotateOld) {
 			const rotatedState = {
 				...oldRefreshState,
-				rotatedAt: now
+				rotatedAt: now,
+				successor: {
+					accessToken: access.token,
+					accessExpiresAt: access.expiresAt,
+					refreshToken: newRefreshToken,
+					refreshExpiresAt
+				}
 			};
 			await this.store.update(oldRefreshToken, rotatedState);
 		}

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { a as AuthContext, c as EnrichedSession, d as RefreshResult, f as SessionEnricher, i as DenylistStore, l as IssueResult, n as defaultClock, o as CredentialMetadata, p as SessionInfo, r as CredentialStore, s as CredentialState, t as Clock, u as RefreshConfig } from "./clock-DJ_eroHW.cjs";
-import { i as RefreshCallOptions, n as AuthCredentialOptions, r as IssueOptions, t as AuthCredential } from "./auth-credential-CEijxoGU.cjs";
-import { n as RateLimitStoreMemory, t as RateLimitStore } from "./store-BYnpA7VK.cjs";
+import { a as AuthContext, d as RefreshConfig, f as RefreshResult, i as DenylistStore, l as EnrichedSession, m as SessionInfo, n as defaultClock, o as CredentialMetadata, p as SessionEnricher, r as CredentialStore, s as CredentialState, t as Clock, u as IssueResult } from "./clock-C0O0FCCN.cjs";
+import { i as RefreshCallOptions, n as AuthCredentialOptions, r as IssueOptions, t as AuthCredential } from "./auth-credential-C5zD8b0J.cjs";
+import { n as RateLimitStoreMemory, t as RateLimitStore } from "./store-C6DU6VZk.cjs";
 import { CryptoKey } from "jose";
 
 //#region src/errors.d.ts

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { a as AuthContext, c as EnrichedSession, d as RefreshResult, f as SessionEnricher, i as DenylistStore, l as IssueResult, n as defaultClock, o as CredentialMetadata, p as SessionInfo, r as CredentialStore, s as CredentialState, t as Clock, u as RefreshConfig } from "./clock-DJ_eroHW.mjs";
-import { i as RefreshCallOptions, n as AuthCredentialOptions, r as IssueOptions, t as AuthCredential } from "./auth-credential-C3qebKuy.mjs";
-import { n as RateLimitStoreMemory, t as RateLimitStore } from "./store-pKh0ZaGG.mjs";
+import { a as AuthContext, d as RefreshConfig, f as RefreshResult, i as DenylistStore, l as EnrichedSession, m as SessionInfo, n as defaultClock, o as CredentialMetadata, p as SessionEnricher, r as CredentialStore, s as CredentialState, t as Clock, u as IssueResult } from "./clock-C0O0FCCN.mjs";
+import { i as RefreshCallOptions, n as AuthCredentialOptions, r as IssueOptions, t as AuthCredential } from "./auth-credential-C9xy4X_k.mjs";
+import { n as RateLimitStoreMemory, t as RateLimitStore } from "./store-y7K7z1EF.mjs";
 import { CryptoKey } from "jose";
 
 //#region src/errors.d.ts

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { t as defaultClock } from "./clock-Bdsep_1j.mjs";
-import { t as credentialPayloadOf } from "./payload-D-DzH5-J.mjs";
+import { t as credentialPayloadOf } from "./payload-DP5zRiXT.mjs";
 import { t as generateOpaqueToken } from "./opaque-token-BaMOrC1A.mjs";
 import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, randomUUID, scryptSync } from "node:crypto";
 import { SignJWT, jwtVerify } from "jose";
@@ -582,6 +582,8 @@ var AuthCredential = class {
 		this.clock = opts.clock ?? defaultClock;
 		if (this.accessTtl <= 0) throw new AuthError("INVALID_CONFIG", `accessTtl must be > 0 (got ${this.accessTtl})`);
 		if (this.refreshConfig && this.refreshConfig.ttl <= 0) throw new AuthError("INVALID_CONFIG", `refresh.ttl must be > 0 (got ${this.refreshConfig.ttl})`);
+		const graceMs = this.refreshConfig?.rotationGraceMs;
+		if (graceMs !== void 0 && graceMs < 0) throw new AuthError("INVALID_CONFIG", `refresh.rotationGraceMs must be >= 0 (got ${graceMs})`);
 	}
 	async issue(userId, options) {
 		if (this.maxConcurrent !== void 0 && this.store.listForUser) await this.enforceConcurrencyLimit(userId);
@@ -593,6 +595,7 @@ var AuthCredential = class {
 			refreshTtl = refresh.ttl ?? this.refreshConfig?.ttl;
 			if (refreshTtl === void 0) throw new AuthError("INVALID_CONFIG", "issue: per-mint refresh needs a ttl when no instance refresh config exists");
 			if (refreshTtl <= 0) throw new AuthError("INVALID_CONFIG", `issue: refresh.ttl must be > 0 (got ${refreshTtl})`);
+			if (refresh.graceMs !== void 0 && refresh.graceMs < 0) throw new AuthError("INVALID_CONFIG", `issue: refresh.graceMs must be >= 0 (got ${refresh.graceMs})`);
 		}
 		const perMintRefresh = refresh !== void 0 && refresh !== false;
 		const stampAccessTtl = refreshTtl !== void 0 && ttl !== void 0;
@@ -600,7 +603,8 @@ var AuthCredential = class {
 			...metadata,
 			...kind !== void 0 && { credentialKind: kind },
 			...stampAccessTtl && { accessTtl: ttl },
-			...perMintRefresh && { refreshRotation: "always" }
+			...perMintRefresh && { refreshRotation: "always" },
+			...perMintRefresh && refresh.graceMs !== void 0 && { rotationGraceMs: refresh.graceMs }
 		} : metadata;
 		if (ttl !== void 0 && expiresAt !== void 0) throw new AuthError("INVALID_CONFIG", "issue: pass either `ttl` or `expiresAt`, not both");
 		if (ttl !== void 0 && ttl <= 0) throw new AuthError("INVALID_CONFIG", `issue: ttl must be > 0 (got ${ttl})`);
@@ -714,23 +718,48 @@ var AuthCredential = class {
 	}
 	/**
 	* Shared rotation-with-grace mechanism for `sliding` and `always` on stateful
-	* stores. Keeps the old refresh valid + stamps `rotatedAt` on first rotation;
-	* within `rotationGraceMs` of that stamp it re-issues a fresh pair WITHOUT
-	* re-rotating (replay-tolerant); beyond grace it treats the re-presentation
-	* as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs sliding
-	* (`sliding`) expiry for the new refresh token.
+	* stores. The first rotation keeps the old refresh valid and stamps
+	* `rotatedAt` + the {@link CredentialState.successor} pair on it; within the
+	* grace window a re-presentation **re-delivers that same pair verbatim** —
+	* idempotent, minting nothing, with no liveness side effects (no expiry
+	* slide, no `lastSeenAt`) — so a captured stale token teaches an attacker
+	* nothing beyond capturing the original rotation response, and a multi-tab
+	* race converges on one successor. Beyond grace — or once the successor has
+	* itself been rotated or revoked (superseded) — the re-presentation is
+	* treated as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs
+	* sliding (`sliding`) expiry for the new refresh token; the family's
+	* mint-time `metadata.rotationGraceMs` (when stamped) wins over the instance
+	* window, and a window of `0` is strict single-use.
 	*/
 	async rotateWithGrace(oldState, refreshToken, now, preserveExpiry) {
-		const graceMs = this.refreshConfig?.rotationGraceMs ?? DEFAULT_ROTATION_GRACE_MS;
+		const graceMs = oldState.metadata?.rotationGraceMs ?? this.refreshConfig?.rotationGraceMs ?? DEFAULT_ROTATION_GRACE_MS;
 		if (typeof oldState.rotatedAt !== "number") return await this.issueRotatedPair(oldState, refreshToken, true, now, preserveExpiry);
-		if (now - oldState.rotatedAt > graceMs) await this.respondToRefreshReuse({
+		const reuse = {
 			userId: oldState.userId,
 			sessionId: oldState.sessionId,
 			issuedAt: oldState.issuedAt,
 			expiresAt: oldState.expiresAt,
 			rotatedAt: oldState.rotatedAt
+		};
+		if (graceMs <= 0 || now - oldState.rotatedAt > graceMs) return await this.respondToRefreshReuse(reuse);
+		const successor = oldState.successor;
+		const successorState = successor === void 0 ? null : await this.store.retrieve(successor.refreshToken);
+		if (successor === void 0 || successorState === null || typeof successorState.rotatedAt === "number") return await this.respondToRefreshReuse(reuse);
+		this.refreshConfig?.onRotationGraceHit?.({
+			userId: oldState.userId,
+			issuedAt: oldState.issuedAt,
+			expiresAt: oldState.expiresAt,
+			kind: "refresh",
+			rotatedAt: oldState.rotatedAt,
+			...oldState.sessionId !== void 0 && { sessionId: oldState.sessionId }
 		});
-		return await this.issueRotatedPair(oldState, refreshToken, false, now, preserveExpiry);
+		return {
+			accessToken: successor.accessToken,
+			accessExpiresAt: successor.accessExpiresAt,
+			refreshToken: successor.refreshToken,
+			refreshExpiresAt: successor.refreshExpiresAt,
+			userId: oldState.userId
+		};
 	}
 	async revoke(token) {
 		await this.store.revoke(token);
@@ -908,7 +937,13 @@ var AuthCredential = class {
 		if (rotateOld) {
 			const rotatedState = {
 				...oldRefreshState,
-				rotatedAt: now
+				rotatedAt: now,
+				successor: {
+					accessToken: access.token,
+					accessExpiresAt: access.expiresAt,
+					refreshToken: newRefreshToken,
+					refreshExpiresAt
+				}
 			};
 			await this.store.update(oldRefreshToken, rotatedState);
 		}

package/dist/{payload-D-DzH5-J.mjs → payload-DP5zRiXT.mjs}

@@ -7,6 +7,7 @@ const ENVELOPE_KEYS = new Set(Object.keys({
 	kind: true,
 	parentCredentialId: true,
 	rotatedAt: true,
+	successor: true,
 	sessionId: true,
 	lastSeenAt: true,
 	token: true

package/dist/{payload-BJjvj8AH.cjs → payload-HPgyPiek.cjs}

@@ -7,6 +7,7 @@ const ENVELOPE_KEYS = new Set(Object.keys({
 	kind: true,
 	parentCredentialId: true,
 	rotatedAt: true,
+	successor: true,
 	sessionId: true,
 	lastSeenAt: true,
 	token: true

package/dist/redis.d.cts

@@ -1,5 +1,5 @@
-import { i as DenylistStore, r as CredentialStore, s as CredentialState } from "./clock-DJ_eroHW.cjs";
-import { t as RateLimitStore } from "./store-BYnpA7VK.cjs";
+import { i as DenylistStore, r as CredentialStore, s as CredentialState } from "./clock-C0O0FCCN.cjs";
+import { t as RateLimitStore } from "./store-C6DU6VZk.cjs";
 
 //#region src/redis/index.d.ts
 /**

package/dist/redis.d.mts

@@ -1,5 +1,5 @@
-import { i as DenylistStore, r as CredentialStore, s as CredentialState } from "./clock-DJ_eroHW.mjs";
-import { t as RateLimitStore } from "./store-pKh0ZaGG.mjs";
+import { i as DenylistStore, r as CredentialStore, s as CredentialState } from "./clock-C0O0FCCN.mjs";
+import { t as RateLimitStore } from "./store-y7K7z1EF.mjs";
 
 //#region src/redis/index.d.ts
 /**

package/dist/{store-BYnpA7VK.d.cts → store-C6DU6VZk.d.cts}

@@ -1,4 +1,4 @@
-import { t as Clock } from "./clock-DJ_eroHW.cjs";
+import { t as Clock } from "./clock-C0O0FCCN.cjs";
 
 //#region src/rate-limit/store.d.ts
 /**

package/dist/{store-pKh0ZaGG.d.mts → store-y7K7z1EF.d.mts}

@@ -1,4 +1,4 @@
-import { t as Clock } from "./clock-DJ_eroHW.mjs";
+import { t as Clock } from "./clock-C0O0FCCN.mjs";
 
 //#region src/rate-limit/store.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/auth",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "description": "Auth method layer for aoothjs (sessions, tokens, password reset, MFA primitives)",
   "keywords": [
     "aoothjs",
@@ -104,18 +104,18 @@
   },
   "dependencies": {
     "jose": "^6.2.3",
-    "@aooth/user": "0.1.49"
+    "@aooth/user": "0.1.51"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.82",
-    "@atscript/db": "^0.1.115",
-    "@atscript/db-sql-tools": "^0.1.115",
-    "@atscript/db-sqlite": "^0.1.115",
-    "@atscript/typescript": "^0.1.82",
+    "@atscript/core": "^0.1.83",
+    "@atscript/db": "^0.1.116",
+    "@atscript/db-sql-tools": "^0.1.116",
+    "@atscript/db-sqlite": "^0.1.116",
+    "@atscript/typescript": "^0.1.83",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.6.2",
     "ioredis": "^5.11.1",
-    "unplugin-atscript": "^0.1.82"
+    "unplugin-atscript": "^0.1.83"
   },
   "peerDependencies": {
     "@atscript/db": ">=0.1.79"

package/src/atscript-db/auth-credential.as

@@ -45,6 +45,12 @@ export type AoothCredentialMetadataBase = {
      * slides. Stored as a plain string (same portability rule as `kind`).
      */
     refreshRotation?: string
+    /**
+     * Per-family rotation grace window (ms) — stamped when a refresh token
+     * is minted with a per-mint `graceMs` (e.g. `TokenPolicy.refresh.graceMs`),
+     * honored over the instance `rotationGraceMs`. 0 = strict single-use.
+     */
+    rotationGraceMs?: number
 }
 
 @db.table 'aooth_credentials'
@@ -84,6 +90,19 @@ export interface AoothAuthCredential {
     parentCredentialId?: string
     rotatedAt?: number.timestamp
 
+    /**
+     * Set alongside `rotatedAt` on a rotated refresh row: the successor pair
+     * the rotation produced, re-delivered verbatim on a within-grace
+     * re-presentation of this token (idempotent grace hits mint nothing).
+     */
+    @db.json
+    successor?: {
+        accessToken: string
+        accessExpiresAt: number.timestamp
+        refreshToken: string
+        refreshExpiresAt: number.timestamp
+    }
+
     /**
      * Stable session-family id. Minted once at login, copied forward on every
      * rotation. Indexed so a store could group/revoke a family natively (the

package/src/atscript-db/auth-credential.as.d.ts

@@ -22,6 +22,7 @@ export type AoothCredentialMetadataBase = {
   authzClientId?: string
   accessTtl?: number
   refreshRotation?: string
+  rotationGraceMs?: number
 }
 declare namespace AoothCredentialMetadataBase {
   const __is_atscript_annotated_type: true
@@ -36,7 +37,7 @@ declare namespace AoothCredentialMetadataBase {
 
 /**
  * Atscript interface **AoothAuthCredential**
- * @see {@link ./auth-credential.as:52:18}
+ * @see {@link ./auth-credential.as:58:18}
  */
 export declare class AoothAuthCredential {
   token: string
@@ -46,6 +47,12 @@ export declare class AoothAuthCredential {
   kind?: string
   parentCredentialId?: string
   rotatedAt?: number /* timestamp */
+  successor?: {
+    accessToken: string
+    accessExpiresAt: number /* timestamp */
+    refreshToken: string
+    refreshExpiresAt: number /* timestamp */
+  }
   sessionId?: string
   lastSeenAt?: number /* timestamp */
   static __is_atscript_annotated_type: true
@@ -64,6 +71,7 @@ export declare class AoothAuthCredential {
     "kind"?: string
     "parentCredentialId"?: string
     "rotatedAt"?: number /* timestamp */
+    "successor"?: string
     "sessionId"?: string
     "lastSeenAt"?: number /* timestamp */
   }
@@ -75,6 +83,7 @@ export declare class AoothAuthCredential {
     "kind"?: string
     "parentCredentialId"?: string
     "rotatedAt"?: number /* timestamp */
+    "successor"?: string
     "sessionId"?: string
     "lastSeenAt"?: number /* timestamp */
   }