@aooth/auth 0.1.47 → 0.1.48

package/dist/atscript-db.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_clock = require("./clock-Bl-H3eqE.cjs");
 const require_payload = require("./payload-BJjvj8AH.cjs");
-const require_dynamic_client_store = require("./dynamic-client-store-DAStgv2j.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
 /**
@@ -170,6 +170,7 @@ var DynamicClientStoreAtscriptDb = class extends require_dynamic_client_store.Dy
 			responseTypes: JSON.stringify(rec.responseTypes),
 			createdAt: this.clock.now(),
 			...rec.clientName !== void 0 && { clientName: rec.clientName },
+			...rec.clientSecretHash !== void 0 && { clientSecretHash: rec.clientSecretHash },
 			...rec.scope !== void 0 && { scope: rec.scope }
 		};
 		await this.table.insertOne(row);
@@ -212,6 +213,7 @@ function rowToDynamicClient(row) {
 		createdAt: row.createdAt
 	};
 	if (row.clientName != null) out.clientName = row.clientName;
+	if (row.clientSecretHash != null) out.clientSecretHash = row.clientSecretHash;
 	if (row.scope != null) out.scope = row.scope;
 	if (row.lastUsedAt != null) out.lastUsedAt = row.lastUsedAt;
 	return out;

package/dist/atscript-db.d.cts

@@ -1,6 +1,5 @@
-import { a as CredentialState, t as CredentialStore } from "./store-BG6m6oSJ.cjs";
-import { t as Clock } from "./clock-BjXa0LXb.cjs";
-import { a as NewDynamicClient, f as NewPendingAuthorization, m as PendingAuthorizationStore, n as DynamicClientStore, o as AuthCode, p as PendingAuthorization, s as AuthCodeStore, t as DynamicClient, u as NewAuthCode } from "./dynamic-client-store-DzqdUwnw.cjs";
+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";
 
 //#region src/atscript-db/authz-stores.d.ts
 /**
@@ -145,6 +144,8 @@ interface DynamicClientRow {
   /** `JSON.stringify(string[])`. */
   redirectUris: string;
   tokenEndpointAuthMethod: string;
+  /** SHA-256 hex digest of the minted secret (confidential clients only). */
+  clientSecretHash?: string;
   /** `JSON.stringify(string[])`. */
   grantTypes: string;
   /** `JSON.stringify(string[])`. */

package/dist/atscript-db.d.mts

@@ -1,6 +1,5 @@
-import { a as CredentialState, t as CredentialStore } from "./store-BG6m6oSJ.mjs";
-import { t as Clock } from "./clock-BjXa0LXb.mjs";
-import { a as NewDynamicClient, f as NewPendingAuthorization, m as PendingAuthorizationStore, n as DynamicClientStore, o as AuthCode, p as PendingAuthorization, s as AuthCodeStore, t as DynamicClient, u as NewAuthCode } from "./dynamic-client-store-oHEsQaJg.mjs";
+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";
 
 //#region src/atscript-db/authz-stores.d.ts
 /**
@@ -145,6 +144,8 @@ interface DynamicClientRow {
   /** `JSON.stringify(string[])`. */
   redirectUris: string;
   tokenEndpointAuthMethod: string;
+  /** SHA-256 hex digest of the minted secret (confidential clients only). */
+  clientSecretHash?: string;
   /** `JSON.stringify(string[])`. */
   grantTypes: string;
   /** `JSON.stringify(string[])`. */

package/dist/atscript-db.mjs

@@ -1,6 +1,6 @@
 import { t as defaultClock } from "./clock-Bdsep_1j.mjs";
 import { t as credentialPayloadOf } from "./payload-D-DzH5-J.mjs";
-import { r as AuthCodeStore, s as PendingAuthorizationStore, t as DynamicClientStore } from "./dynamic-client-store-DLRfntHr.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
 /**
@@ -169,6 +169,7 @@ var DynamicClientStoreAtscriptDb = class extends DynamicClientStore {
 			responseTypes: JSON.stringify(rec.responseTypes),
 			createdAt: this.clock.now(),
 			...rec.clientName !== void 0 && { clientName: rec.clientName },
+			...rec.clientSecretHash !== void 0 && { clientSecretHash: rec.clientSecretHash },
 			...rec.scope !== void 0 && { scope: rec.scope }
 		};
 		await this.table.insertOne(row);
@@ -211,6 +212,7 @@ function rowToDynamicClient(row) {
 		createdAt: row.createdAt
 	};
 	if (row.clientName != null) out.clientName = row.clientName;
+	if (row.clientSecretHash != null) out.clientSecretHash = row.clientSecretHash;
 	if (row.scope != null) out.scope = row.scope;
 	if (row.lastUsedAt != null) out.lastUsedAt = row.lastUsedAt;
 	return out;

package/dist/auth-credential-C3qebKuy.d.mts

@@ -0,0 +1,245 @@
+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";
+
+//#region src/credential/auth-credential.d.ts
+interface AuthCredentialOptions<TPayload extends object = object> {
+  /** Pluggable credential store (Memory, JWT, Encapsulated, ...). */
+  store: CredentialStore<TPayload>;
+  /** Default 'token' — distinguishes session-style from token-style use. */
+  method?: "session" | "token";
+  /** Access token TTL in milliseconds. Defaults to 1 hour. Must be > 0. */
+  accessTtl?: number;
+  /** If provided, refresh tokens are enabled. */
+  refresh?: RefreshConfig;
+  /**
+   * Optional denylist consulted by `validate` keyed on the raw token.
+   *
+   * Note: stateless stores (JWT, Encapsulated) maintain their own denylist
+   * keyed on `jti` for `revoke`/`update`/`consume`. Sharing a single
+   * `DenylistStore` instance across both is safe (the keyspaces are disjoint:
+   * raw tokens vs UUID jti) but conceptually they serve different purposes.
+   */
+  denylist?: DenylistStore;
+  /** Maximum concurrent active access credentials per user. */
+  maxConcurrent?: number;
+  /** Behavior when limit reached: 'reject' (default) or 'evict-oldest'. */
+  onLimit?: "reject" | "evict-oldest";
+  /**
+   * Track per-session activity time (`lastSeenAt`). Default `false` — no extra
+   * writes; `listSessions` falls back to `createdAt`.
+   * - `'refresh'` (cheap): stamp `lastSeenAt` on the newly-minted credentials
+   *   during refresh — piggybacks the rotation write, no extra round-trip.
+   * - `'validate'` (accurate, costly): `store.touch(token, now)` on every
+   *   successful `validate()` — one write per authenticated request. Requires a
+   *   store that implements `touch`; a no-op on stores that don't.
+   */
+  trackLastSeen?: "refresh" | "validate" | false;
+  /** Optional clock for testability. */
+  clock?: Clock;
+}
+/**
+ * Options for {@link AuthCredential.issue}. The credential's typed payload
+ * `TPayload` (the root fields a consumer added to their credential model — e.g.
+ * `@arbac.attenuate.*`-annotated fields) is spread flat alongside the
+ * framework-level hints below. Reserved keys `metadata`, `sessionId`, `ttl`,
+ * `expiresAt`, `kind`, `refresh` (and the {@link CredentialState} envelope keys)
+ * must not be reused as payload field names.
+ */
+type IssueOptions<TPayload extends object = object> = TPayload & {
+  metadata?: CredentialMetadata;
+  /**
+   * Pre-supply the session id. Omit to let `issue()` mint a random opaque one.
+   * Both the access and refresh tokens of this login share it.
+   */
+  sessionId?: string;
+  /**
+   * Per-mint access-token lifetime in **milliseconds**, overriding the
+   * instance-level `accessTtl` for THIS credential only — so one `AuthCredential`
+   * can mint, say, a 30-minute browser session AND a long-lived PAT/CLI token
+   * without a second instance/posture. Must be `> 0`. Mutually exclusive with
+   * {@link expiresAt}. The refresh token (if any) is unaffected — it keeps
+   * `refresh.ttl`.
+   */
+  ttl?: number;
+  /**
+   * Absolute access-token expiry instant (ms since epoch), overriding both
+   * `ttl` and the instance `accessTtl`. Mutually exclusive with {@link ttl}.
+   * Use when the caller already holds the exact instant.
+   */
+  expiresAt?: number;
+  /**
+   * Semantic credential kind for THIS mint — e.g. `"cli-session"` / `"pat"`.
+   * Distinct from the internal access/refresh discriminator
+   * ({@link CredentialState.kind}): it is stored in `metadata.credentialKind`
+   * and carried forward across rotation, so the whole session family is
+   * labelled. Surfaced as {@link SessionInfo.kind} and consumed by the
+   * `listSessions({ kind })` filter to keep non-browser credentials out of the
+   * default "active sessions" view. Omit for an ordinary interactive session.
+   */
+  kind?: string;
+  /**
+   * Per-mint refresh-token control, overriding the instance-level
+   * `AuthCredentialOptions.refresh` for THIS credential only:
+   * - omitted — instance default: a refresh token is minted iff the instance
+   *   `refresh` config exists (today's behavior).
+   * - `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
+   *   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'`.
+   */
+  refresh?: false | {
+    ttl?: number;
+  };
+};
+/** Options for {@link AuthCredential.refresh}. */
+interface RefreshCallOptions<TPayload extends object = object> {
+  /**
+   * Pre-rotation gate: invoked with the stored refresh credential AFTER it
+   * resolved to a live refresh-kind row but BEFORE any rotation or state
+   * change. Throwing aborts the refresh with nothing consumed or rotated —
+   * the seam for caller-level binding checks (e.g. the OAuth token endpoint
+   * verifying `metadata.authzClientId` against the presenting client).
+   */
+  guard?: (state: CredentialState & TPayload) => void | Promise<void>;
+}
+/**
+ * Orchestrates credential issuance, validation, refresh, and revocation
+ * on top of a pluggable {@link CredentialStore}.
+ *
+ * Design notes:
+ * - `credentialId` returned in {@link AuthContext} is a SHA-256 fingerprint of
+ *   the access token, never the token itself. The fingerprint is stable
+ *   per-token, safe to log/persist, and cannot be replayed against the API.
+ *   M3 will switch to a `jti` claim for JWT/encapsulated stores.
+ * - `kind: 'access' | 'refresh'` on {@link CredentialState} discriminates
+ *   tokens stored side-by-side in the same store.
+ * - `listForUser` and `maxConcurrent` consider only access-kind credentials,
+ *   matching how callers typically display "active sessions".
+ * - On detected refresh-reuse, the orchestrator best-effort revokes the
+ *   compromised token family (the OAuth-best-practice theft response). Set
+ *   `refresh.reuseResponse: 'user'` to escalate to revoking ALL of the user's
+ *   sessions. See {@link RefreshConfig.reuseResponse}.
+ */
+declare class AuthCredential<TPayload extends object = object> {
+  private readonly store;
+  private readonly method;
+  private readonly accessTtl;
+  private readonly refreshConfig?;
+  private readonly denylist?;
+  private readonly maxConcurrent?;
+  private readonly onLimit;
+  private readonly trackLastSeen;
+  private readonly clock;
+  /**
+   * Recently-consumed refresh tokens, keyed by the raw refresh token string.
+   * Lets `'always'` rotation detect reuse: stateful stores forget the token
+   * after `consume`, and stateless (JWT) stores hide it behind a denylist hit
+   * on `retrieve`. Without this map the orchestrator can no longer distinguish
+   * "fake token" from "previously valid token replayed". Pruned lazily on
+   * access; bounded by refresh TTL.
+   */
+  private readonly consumedRefreshes;
+  constructor(opts: AuthCredentialOptions<TPayload>);
+  issue(userId: string, options?: IssueOptions<TPayload>): Promise<IssueResult>;
+  validate(accessToken: string): Promise<AuthContext<TPayload> | null>;
+  refresh(refreshToken: string, opts?: RefreshCallOptions<TPayload>): Promise<RefreshResult>;
+  private refreshNone;
+  /**
+   * `sliding` rotation: rotate on every use and slide the refresh expiry
+   * forward (rolling session). Grace-tolerant via the shared store-backed
+   * window.
+   */
+  private refreshSliding;
+  /**
+   * `always` rotation: rotate on every use but keep a FIXED session ceiling —
+   * each rotated token inherits the family's original `expiresAt` (no sliding).
+   *
+   * On a stateful store this reuses the same store-backed grace window as
+   * `sliding` (so a benign concurrent refresh within grace is NOT mistaken for
+   * theft, even across instances). On a stateless store the old token cannot be
+   * kept valid (`update` re-issues), so it falls back to single-use semantics
+   * with a process-local reuse signal — the only mechanism possible there.
+   */
+  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.
+   */
+  private rotateWithGrace;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  listForUser(userId: string): Promise<Array<AuthContext<TPayload>>>;
+  /**
+   * The session id for a credential: its stored `sessionId`, or the token
+   * fingerprint for legacy rows predating sessionId (so they surface as
+   * singleton sessions). The ONE place this fallback rule lives — shared by
+   * `validate()`, `listForUser()`, and the session-family methods so "this
+   * device" matching stays consistent across all of them.
+   */
+  private sessionIdOf;
+  /** Session-grouping key for a stored credential entry (token attached). */
+  private sessionKeyOf;
+  /**
+   * List the user's active sessions, one row per token family (access +
+   * refresh + every rotation collapsed by `sessionId`). Newest first by
+   * `lastSeenAt` (or `createdAt` when activity isn't tracked). Returns `[]` for
+   * stores that can't enumerate (stateless JWT/encapsulated). Pass `enrich` to
+   * map each row through a {@link SessionEnricher} (device/location labels).
+   */
+  listSessions(userId: string, opts?: {
+    enrich?: SessionEnricher;
+    kind?: string | string[];
+  }): Promise<SessionInfo[] | EnrichedSession[]>;
+  /**
+   * Revoke a single session — every token in its family (access + refresh +
+   * rotations). No-op for stores that can't enumerate. Other sessions keep
+   * validating.
+   */
+  revokeSession(userId: string, sessionId: string): Promise<void>;
+  /**
+   * Revoke every session for the user EXCEPT `keepSessionId` ("log out
+   * everywhere else"). Returns the number of distinct sessions revoked. No-op
+   * (returns 0) for stores that can't enumerate.
+   */
+  revokeOtherSessions(userId: string, keepSessionId: string): Promise<number>;
+  /**
+   * Derive a stable 32-byte key from this credential's underlying store secret,
+   * domain-separated by `label`. Lets adjacent subsystems (e.g. workflow-state
+   * encryption) reuse the auth secret without managing a second one. Throws if
+   * the store has no reusable symmetric secret (stateful/asymmetric) — callers
+   * should then require an explicit secret.
+   */
+  deriveStateKey(label?: string): Buffer;
+  private enforceConcurrencyLimit;
+  private issueAccessFromRefresh;
+  /**
+   * Issue a fresh access + refresh pair off an existing refresh credential.
+   * `preserveExpiry` keeps the family's original refresh `expiresAt` (a fixed
+   * session ceiling, used by `always`); otherwise the new refresh slides to
+   * `now + ttl` (used by `sliding`). `rotateOld` stamps the old refresh as
+   * rotated (keeping it valid through the grace window) instead of consuming it.
+   */
+  private issueRotatedPair;
+  private lookupConsumedRefresh;
+  private fireRefreshReuseTheftResponse;
+  /**
+   * Best-effort theft response for a detected refresh-token reuse. Fires the
+   * `onRotationReuse` hook, then revokes per {@link RefreshConfig.reuseResponse}:
+   * the compromised token family (`'session'`, default) or every session for
+   * the user (`'user'`). Falls back to user-wide revocation when the session
+   * can't be targeted (no `sessionId`, or a store that can't enumerate
+   * sessions). Always throws `REFRESH_REUSE_DETECTED`.
+   */
+  private respondToRefreshReuse;
+}
+//#endregion
+export { RefreshCallOptions as i, AuthCredentialOptions as n, IssueOptions as r, AuthCredential as t };

package/dist/auth-credential-CEijxoGU.d.cts

@@ -0,0 +1,245 @@
+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";
+
+//#region src/credential/auth-credential.d.ts
+interface AuthCredentialOptions<TPayload extends object = object> {
+  /** Pluggable credential store (Memory, JWT, Encapsulated, ...). */
+  store: CredentialStore<TPayload>;
+  /** Default 'token' — distinguishes session-style from token-style use. */
+  method?: "session" | "token";
+  /** Access token TTL in milliseconds. Defaults to 1 hour. Must be > 0. */
+  accessTtl?: number;
+  /** If provided, refresh tokens are enabled. */
+  refresh?: RefreshConfig;
+  /**
+   * Optional denylist consulted by `validate` keyed on the raw token.
+   *
+   * Note: stateless stores (JWT, Encapsulated) maintain their own denylist
+   * keyed on `jti` for `revoke`/`update`/`consume`. Sharing a single
+   * `DenylistStore` instance across both is safe (the keyspaces are disjoint:
+   * raw tokens vs UUID jti) but conceptually they serve different purposes.
+   */
+  denylist?: DenylistStore;
+  /** Maximum concurrent active access credentials per user. */
+  maxConcurrent?: number;
+  /** Behavior when limit reached: 'reject' (default) or 'evict-oldest'. */
+  onLimit?: "reject" | "evict-oldest";
+  /**
+   * Track per-session activity time (`lastSeenAt`). Default `false` — no extra
+   * writes; `listSessions` falls back to `createdAt`.
+   * - `'refresh'` (cheap): stamp `lastSeenAt` on the newly-minted credentials
+   *   during refresh — piggybacks the rotation write, no extra round-trip.
+   * - `'validate'` (accurate, costly): `store.touch(token, now)` on every
+   *   successful `validate()` — one write per authenticated request. Requires a
+   *   store that implements `touch`; a no-op on stores that don't.
+   */
+  trackLastSeen?: "refresh" | "validate" | false;
+  /** Optional clock for testability. */
+  clock?: Clock;
+}
+/**
+ * Options for {@link AuthCredential.issue}. The credential's typed payload
+ * `TPayload` (the root fields a consumer added to their credential model — e.g.
+ * `@arbac.attenuate.*`-annotated fields) is spread flat alongside the
+ * framework-level hints below. Reserved keys `metadata`, `sessionId`, `ttl`,
+ * `expiresAt`, `kind`, `refresh` (and the {@link CredentialState} envelope keys)
+ * must not be reused as payload field names.
+ */
+type IssueOptions<TPayload extends object = object> = TPayload & {
+  metadata?: CredentialMetadata;
+  /**
+   * Pre-supply the session id. Omit to let `issue()` mint a random opaque one.
+   * Both the access and refresh tokens of this login share it.
+   */
+  sessionId?: string;
+  /**
+   * Per-mint access-token lifetime in **milliseconds**, overriding the
+   * instance-level `accessTtl` for THIS credential only — so one `AuthCredential`
+   * can mint, say, a 30-minute browser session AND a long-lived PAT/CLI token
+   * without a second instance/posture. Must be `> 0`. Mutually exclusive with
+   * {@link expiresAt}. The refresh token (if any) is unaffected — it keeps
+   * `refresh.ttl`.
+   */
+  ttl?: number;
+  /**
+   * Absolute access-token expiry instant (ms since epoch), overriding both
+   * `ttl` and the instance `accessTtl`. Mutually exclusive with {@link ttl}.
+   * Use when the caller already holds the exact instant.
+   */
+  expiresAt?: number;
+  /**
+   * Semantic credential kind for THIS mint — e.g. `"cli-session"` / `"pat"`.
+   * Distinct from the internal access/refresh discriminator
+   * ({@link CredentialState.kind}): it is stored in `metadata.credentialKind`
+   * and carried forward across rotation, so the whole session family is
+   * labelled. Surfaced as {@link SessionInfo.kind} and consumed by the
+   * `listSessions({ kind })` filter to keep non-browser credentials out of the
+   * default "active sessions" view. Omit for an ordinary interactive session.
+   */
+  kind?: string;
+  /**
+   * Per-mint refresh-token control, overriding the instance-level
+   * `AuthCredentialOptions.refresh` for THIS credential only:
+   * - omitted — instance default: a refresh token is minted iff the instance
+   *   `refresh` config exists (today's behavior).
+   * - `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
+   *   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'`.
+   */
+  refresh?: false | {
+    ttl?: number;
+  };
+};
+/** Options for {@link AuthCredential.refresh}. */
+interface RefreshCallOptions<TPayload extends object = object> {
+  /**
+   * Pre-rotation gate: invoked with the stored refresh credential AFTER it
+   * resolved to a live refresh-kind row but BEFORE any rotation or state
+   * change. Throwing aborts the refresh with nothing consumed or rotated —
+   * the seam for caller-level binding checks (e.g. the OAuth token endpoint
+   * verifying `metadata.authzClientId` against the presenting client).
+   */
+  guard?: (state: CredentialState & TPayload) => void | Promise<void>;
+}
+/**
+ * Orchestrates credential issuance, validation, refresh, and revocation
+ * on top of a pluggable {@link CredentialStore}.
+ *
+ * Design notes:
+ * - `credentialId` returned in {@link AuthContext} is a SHA-256 fingerprint of
+ *   the access token, never the token itself. The fingerprint is stable
+ *   per-token, safe to log/persist, and cannot be replayed against the API.
+ *   M3 will switch to a `jti` claim for JWT/encapsulated stores.
+ * - `kind: 'access' | 'refresh'` on {@link CredentialState} discriminates
+ *   tokens stored side-by-side in the same store.
+ * - `listForUser` and `maxConcurrent` consider only access-kind credentials,
+ *   matching how callers typically display "active sessions".
+ * - On detected refresh-reuse, the orchestrator best-effort revokes the
+ *   compromised token family (the OAuth-best-practice theft response). Set
+ *   `refresh.reuseResponse: 'user'` to escalate to revoking ALL of the user's
+ *   sessions. See {@link RefreshConfig.reuseResponse}.
+ */
+declare class AuthCredential<TPayload extends object = object> {
+  private readonly store;
+  private readonly method;
+  private readonly accessTtl;
+  private readonly refreshConfig?;
+  private readonly denylist?;
+  private readonly maxConcurrent?;
+  private readonly onLimit;
+  private readonly trackLastSeen;
+  private readonly clock;
+  /**
+   * Recently-consumed refresh tokens, keyed by the raw refresh token string.
+   * Lets `'always'` rotation detect reuse: stateful stores forget the token
+   * after `consume`, and stateless (JWT) stores hide it behind a denylist hit
+   * on `retrieve`. Without this map the orchestrator can no longer distinguish
+   * "fake token" from "previously valid token replayed". Pruned lazily on
+   * access; bounded by refresh TTL.
+   */
+  private readonly consumedRefreshes;
+  constructor(opts: AuthCredentialOptions<TPayload>);
+  issue(userId: string, options?: IssueOptions<TPayload>): Promise<IssueResult>;
+  validate(accessToken: string): Promise<AuthContext<TPayload> | null>;
+  refresh(refreshToken: string, opts?: RefreshCallOptions<TPayload>): Promise<RefreshResult>;
+  private refreshNone;
+  /**
+   * `sliding` rotation: rotate on every use and slide the refresh expiry
+   * forward (rolling session). Grace-tolerant via the shared store-backed
+   * window.
+   */
+  private refreshSliding;
+  /**
+   * `always` rotation: rotate on every use but keep a FIXED session ceiling —
+   * each rotated token inherits the family's original `expiresAt` (no sliding).
+   *
+   * On a stateful store this reuses the same store-backed grace window as
+   * `sliding` (so a benign concurrent refresh within grace is NOT mistaken for
+   * theft, even across instances). On a stateless store the old token cannot be
+   * kept valid (`update` re-issues), so it falls back to single-use semantics
+   * with a process-local reuse signal — the only mechanism possible there.
+   */
+  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.
+   */
+  private rotateWithGrace;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  listForUser(userId: string): Promise<Array<AuthContext<TPayload>>>;
+  /**
+   * The session id for a credential: its stored `sessionId`, or the token
+   * fingerprint for legacy rows predating sessionId (so they surface as
+   * singleton sessions). The ONE place this fallback rule lives — shared by
+   * `validate()`, `listForUser()`, and the session-family methods so "this
+   * device" matching stays consistent across all of them.
+   */
+  private sessionIdOf;
+  /** Session-grouping key for a stored credential entry (token attached). */
+  private sessionKeyOf;
+  /**
+   * List the user's active sessions, one row per token family (access +
+   * refresh + every rotation collapsed by `sessionId`). Newest first by
+   * `lastSeenAt` (or `createdAt` when activity isn't tracked). Returns `[]` for
+   * stores that can't enumerate (stateless JWT/encapsulated). Pass `enrich` to
+   * map each row through a {@link SessionEnricher} (device/location labels).
+   */
+  listSessions(userId: string, opts?: {
+    enrich?: SessionEnricher;
+    kind?: string | string[];
+  }): Promise<SessionInfo[] | EnrichedSession[]>;
+  /**
+   * Revoke a single session — every token in its family (access + refresh +
+   * rotations). No-op for stores that can't enumerate. Other sessions keep
+   * validating.
+   */
+  revokeSession(userId: string, sessionId: string): Promise<void>;
+  /**
+   * Revoke every session for the user EXCEPT `keepSessionId` ("log out
+   * everywhere else"). Returns the number of distinct sessions revoked. No-op
+   * (returns 0) for stores that can't enumerate.
+   */
+  revokeOtherSessions(userId: string, keepSessionId: string): Promise<number>;
+  /**
+   * Derive a stable 32-byte key from this credential's underlying store secret,
+   * domain-separated by `label`. Lets adjacent subsystems (e.g. workflow-state
+   * encryption) reuse the auth secret without managing a second one. Throws if
+   * the store has no reusable symmetric secret (stateful/asymmetric) — callers
+   * should then require an explicit secret.
+   */
+  deriveStateKey(label?: string): Buffer;
+  private enforceConcurrencyLimit;
+  private issueAccessFromRefresh;
+  /**
+   * Issue a fresh access + refresh pair off an existing refresh credential.
+   * `preserveExpiry` keeps the family's original refresh `expiresAt` (a fixed
+   * session ceiling, used by `always`); otherwise the new refresh slides to
+   * `now + ttl` (used by `sliding`). `rotateOld` stamps the old refresh as
+   * rotated (keeping it valid through the grace window) instead of consuming it.
+   */
+  private issueRotatedPair;
+  private lookupConsumedRefresh;
+  private fireRefreshReuseTheftResponse;
+  /**
+   * Best-effort theft response for a detected refresh-token reuse. Fires the
+   * `onRotationReuse` hook, then revokes per {@link RefreshConfig.reuseResponse}:
+   * the compromised token family (`'session'`, default) or every session for
+   * the user (`'user'`). Falls back to user-wide revocation when the session
+   * can't be targeted (no `sessionId`, or a store that can't enumerate
+   * sessions). Always throws `REFRESH_REUSE_DETECTED`.
+   */
+  private respondToRefreshReuse;
+}
+//#endregion
+export { RefreshCallOptions as i, AuthCredentialOptions as n, IssueOptions as r, AuthCredential as t };