@aooth/auth 0.1.6 → 0.1.8

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { a as CredentialState, i as CredentialMetadata, n as DenylistStore, o as IssueResult, r as AuthContext, s as RefreshConfig, t as CredentialStore } from "./store-untAtWQz.cjs";
+import { a as CredentialState, c as RefreshConfig, i as CredentialMetadata, l as SessionEnricher, n as DenylistStore, o as EnrichedSession, r as AuthContext, s as IssueResult, t as CredentialStore, u as SessionInfo } from "./store-BG6m6oSJ.cjs";
+import { n as defaultClock, t as Clock } from "./clock-BjXa0LXb.cjs";
 import { CryptoKey } from "jose";
 
 //#region src/errors.d.ts
@@ -10,19 +11,6 @@ declare class AuthError extends Error {
   constructor(type: AuthErrorType, message?: string, details?: Record<string, unknown> | undefined);
 }
 //#endregion
-//#region src/utils/clock.d.ts
-/**
- * Minimal time abstraction shared across stores and orchestrators.
- *
- * Defaults to wall-clock; tests inject a fake clock to deterministically
- * advance time. Kept tiny (single `now()` method) so any timing primitive
- * — Date, performance.now-ish, monotonic, etc. — can be plugged in.
- */
-interface Clock {
-  now(): number;
-}
-declare const defaultClock: Clock;
-//#endregion
 //#region src/stores/memory.d.ts
 /**
  * In-memory implementation of CredentialStore using random opaque token IDs.
@@ -32,20 +20,21 @@ declare const defaultClock: Clock;
  *   `listForUser` without scanning the full primary map.
  * - Both maps are kept in sync on every mutation.
  */
-declare class CredentialStoreMemory<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreMemory<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly states;
   private readonly byUser;
   private readonly clock;
   constructor(opts?: {
     clock?: Clock;
   });
-  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
-  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
-  consume(token: string): Promise<CredentialState<TClaims> | null>;
-  update(token: string, state: CredentialState<TClaims>): Promise<string>;
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
   revoke(token: string): Promise<void>;
+  touch(token: string, at: number): Promise<void>;
   revokeAllForUser(userId: string): Promise<number>;
-  listForUser(userId: string): Promise<Array<CredentialState<TClaims> & {
+  listForUser(userId: string): Promise<Array<CredentialState & TPayload & {
     token: string;
   }>>;
   private indexAdd;
@@ -105,7 +94,7 @@ interface CredentialStoreJwtOptions {
  * `denylist`; without one, `revoke`/`update`/`consume` throw
  * STATELESS_OPERATION_UNSUPPORTED.
  */
-declare class CredentialStoreJwt<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreJwt<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly algorithm;
   private readonly signingKey;
   private readonly verifyingKey;
@@ -124,12 +113,13 @@ declare class CredentialStoreJwt<TClaims extends object = object> implements Cre
    */
   private readonly epochs;
   constructor(opts: CredentialStoreJwtOptions);
-  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
-  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
-  consume(token: string): Promise<CredentialState<TClaims> | null>;
-  update(token: string, state: CredentialState<TClaims>): Promise<string>;
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
   revoke(token: string): Promise<void>;
   revokeAllForUser(userId: string): Promise<number>;
+  deriveSubkey(label: string): Buffer;
   private requireDenylist;
   /** Convert payload `exp` (seconds) to ms; fall back to a 60s window. */
   private payloadExpMs;
@@ -181,7 +171,7 @@ interface CredentialStoreEncapsulatedOptions {
  * `CredentialStoreAtscriptDb` when you need native enumeration with durable
  * cross-instance cascade semantics.
  */
-declare class CredentialStoreEncapsulated<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreEncapsulated<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly key;
   private readonly denylist?;
   private readonly clock;
@@ -195,12 +185,13 @@ declare class CredentialStoreEncapsulated<TClaims extends object = object> imple
    */
   private readonly epochs;
   constructor(opts: CredentialStoreEncapsulatedOptions);
-  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
-  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
-  consume(token: string): Promise<CredentialState<TClaims> | null>;
-  update(token: string, state: CredentialState<TClaims>): Promise<string>;
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
   revoke(token: string): Promise<void>;
   revokeAllForUser(userId: string): Promise<number>;
+  deriveSubkey(label: string): Buffer;
   /**
    * Reject decrypted payloads whose `issuedAt` predates the user's revocation
    * epoch. Same-ms mints (`issuedAt === epoch`) are accepted so a workflow can
@@ -212,9 +203,9 @@ declare class CredentialStoreEncapsulated<TClaims extends object = object> imple
 }
 //#endregion
 //#region src/credential/auth-credential.d.ts
-interface AuthCredentialOptions<TClaims extends object = object> {
+interface AuthCredentialOptions<TPayload extends object = object> {
   /** Pluggable credential store (Memory, JWT, Encapsulated, ...). */
-  store: CredentialStore<TClaims>;
+  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. */
@@ -234,13 +225,60 @@ interface AuthCredentialOptions<TClaims extends object = object> {
   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;
 }
-interface IssueOptions<TClaims extends object = object> {
-  claims?: TClaims;
+/**
+ * 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` (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;
+};
 /**
  * Orchestrates credential issuance, validation, refresh, and revocation
  * on top of a pluggable {@link CredentialStore}.
@@ -254,11 +292,12 @@ interface IssueOptions<TClaims extends object = object> {
  *   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-after-grace, the orchestrator best-effort
- *   revokes ALL credentials for the affected user (access + refresh).
- *   This is OAuth-best-practice theft response; documented and intentional.
+ * - 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<TClaims extends object = object> {
+declare class AuthCredential<TPayload extends object = object> {
   private readonly store;
   private readonly method;
   private readonly accessTtl;
@@ -266,6 +305,7 @@ declare class AuthCredential<TClaims extends object = object> {
   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.
@@ -276,20 +316,102 @@ declare class AuthCredential<TClaims extends object = object> {
    * access; bounded by refresh TTL.
    */
   private readonly consumedRefreshes;
-  constructor(opts: AuthCredentialOptions<TClaims>);
-  issue(userId: string, options?: IssueOptions<TClaims>): Promise<IssueResult>;
-  validate(accessToken: string): Promise<AuthContext<TClaims> | null>;
+  constructor(opts: AuthCredentialOptions<TPayload>);
+  issue(userId: string, options?: IssueOptions<TPayload>): Promise<IssueResult>;
+  validate(accessToken: string): Promise<AuthContext<TPayload> | null>;
   refresh(refreshToken: string): Promise<IssueResult>;
   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<TClaims>>>;
+  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
 //#region src/email.d.ts
@@ -391,4 +513,4 @@ type BuildMagicLinkUrl = (kind: AuthEmailKind, token: string, ctx?: {
  */
 declare function generateMagicLinkToken(): string;
 //#endregion
-export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, type DenylistStore, DenylistStoreMemory, type EmailSender, type IssueOptions, type IssueResult, type JwtAlgorithm, type RefreshConfig, type SmsSender, defaultClock, generateMagicLinkToken };
+export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, type DenylistStore, DenylistStoreMemory, type EmailSender, type EnrichedSession, type IssueOptions, type IssueResult, type JwtAlgorithm, type RefreshConfig, type SessionEnricher, type SessionInfo, type SmsSender, defaultClock, generateMagicLinkToken };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { a as CredentialState, i as CredentialMetadata, n as DenylistStore, o as IssueResult, r as AuthContext, s as RefreshConfig, t as CredentialStore } from "./store-B1t8KkfA.mjs";
+import { a as CredentialState, c as RefreshConfig, i as CredentialMetadata, l as SessionEnricher, n as DenylistStore, o as EnrichedSession, r as AuthContext, s as IssueResult, t as CredentialStore, u as SessionInfo } from "./store-BG6m6oSJ.mjs";
+import { n as defaultClock, t as Clock } from "./clock-BjXa0LXb.mjs";
 import { CryptoKey } from "jose";
 
 //#region src/errors.d.ts
@@ -10,19 +11,6 @@ declare class AuthError extends Error {
   constructor(type: AuthErrorType, message?: string, details?: Record<string, unknown> | undefined);
 }
 //#endregion
-//#region src/utils/clock.d.ts
-/**
- * Minimal time abstraction shared across stores and orchestrators.
- *
- * Defaults to wall-clock; tests inject a fake clock to deterministically
- * advance time. Kept tiny (single `now()` method) so any timing primitive
- * — Date, performance.now-ish, monotonic, etc. — can be plugged in.
- */
-interface Clock {
-  now(): number;
-}
-declare const defaultClock: Clock;
-//#endregion
 //#region src/stores/memory.d.ts
 /**
  * In-memory implementation of CredentialStore using random opaque token IDs.
@@ -32,20 +20,21 @@ declare const defaultClock: Clock;
  *   `listForUser` without scanning the full primary map.
  * - Both maps are kept in sync on every mutation.
  */
-declare class CredentialStoreMemory<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreMemory<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly states;
   private readonly byUser;
   private readonly clock;
   constructor(opts?: {
     clock?: Clock;
   });
-  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
-  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
-  consume(token: string): Promise<CredentialState<TClaims> | null>;
-  update(token: string, state: CredentialState<TClaims>): Promise<string>;
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
   revoke(token: string): Promise<void>;
+  touch(token: string, at: number): Promise<void>;
   revokeAllForUser(userId: string): Promise<number>;
-  listForUser(userId: string): Promise<Array<CredentialState<TClaims> & {
+  listForUser(userId: string): Promise<Array<CredentialState & TPayload & {
     token: string;
   }>>;
   private indexAdd;
@@ -105,7 +94,7 @@ interface CredentialStoreJwtOptions {
  * `denylist`; without one, `revoke`/`update`/`consume` throw
  * STATELESS_OPERATION_UNSUPPORTED.
  */
-declare class CredentialStoreJwt<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreJwt<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly algorithm;
   private readonly signingKey;
   private readonly verifyingKey;
@@ -124,12 +113,13 @@ declare class CredentialStoreJwt<TClaims extends object = object> implements Cre
    */
   private readonly epochs;
   constructor(opts: CredentialStoreJwtOptions);
-  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
-  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
-  consume(token: string): Promise<CredentialState<TClaims> | null>;
-  update(token: string, state: CredentialState<TClaims>): Promise<string>;
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
   revoke(token: string): Promise<void>;
   revokeAllForUser(userId: string): Promise<number>;
+  deriveSubkey(label: string): Buffer;
   private requireDenylist;
   /** Convert payload `exp` (seconds) to ms; fall back to a 60s window. */
   private payloadExpMs;
@@ -181,7 +171,7 @@ interface CredentialStoreEncapsulatedOptions {
  * `CredentialStoreAtscriptDb` when you need native enumeration with durable
  * cross-instance cascade semantics.
  */
-declare class CredentialStoreEncapsulated<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreEncapsulated<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly key;
   private readonly denylist?;
   private readonly clock;
@@ -195,12 +185,13 @@ declare class CredentialStoreEncapsulated<TClaims extends object = object> imple
    */
   private readonly epochs;
   constructor(opts: CredentialStoreEncapsulatedOptions);
-  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
-  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
-  consume(token: string): Promise<CredentialState<TClaims> | null>;
-  update(token: string, state: CredentialState<TClaims>): Promise<string>;
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
   revoke(token: string): Promise<void>;
   revokeAllForUser(userId: string): Promise<number>;
+  deriveSubkey(label: string): Buffer;
   /**
    * Reject decrypted payloads whose `issuedAt` predates the user's revocation
    * epoch. Same-ms mints (`issuedAt === epoch`) are accepted so a workflow can
@@ -212,9 +203,9 @@ declare class CredentialStoreEncapsulated<TClaims extends object = object> imple
 }
 //#endregion
 //#region src/credential/auth-credential.d.ts
-interface AuthCredentialOptions<TClaims extends object = object> {
+interface AuthCredentialOptions<TPayload extends object = object> {
   /** Pluggable credential store (Memory, JWT, Encapsulated, ...). */
-  store: CredentialStore<TClaims>;
+  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. */
@@ -234,13 +225,60 @@ interface AuthCredentialOptions<TClaims extends object = object> {
   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;
 }
-interface IssueOptions<TClaims extends object = object> {
-  claims?: TClaims;
+/**
+ * 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` (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;
+};
 /**
  * Orchestrates credential issuance, validation, refresh, and revocation
  * on top of a pluggable {@link CredentialStore}.
@@ -254,11 +292,12 @@ interface IssueOptions<TClaims extends object = object> {
  *   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-after-grace, the orchestrator best-effort
- *   revokes ALL credentials for the affected user (access + refresh).
- *   This is OAuth-best-practice theft response; documented and intentional.
+ * - 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<TClaims extends object = object> {
+declare class AuthCredential<TPayload extends object = object> {
   private readonly store;
   private readonly method;
   private readonly accessTtl;
@@ -266,6 +305,7 @@ declare class AuthCredential<TClaims extends object = object> {
   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.
@@ -276,20 +316,102 @@ declare class AuthCredential<TClaims extends object = object> {
    * access; bounded by refresh TTL.
    */
   private readonly consumedRefreshes;
-  constructor(opts: AuthCredentialOptions<TClaims>);
-  issue(userId: string, options?: IssueOptions<TClaims>): Promise<IssueResult>;
-  validate(accessToken: string): Promise<AuthContext<TClaims> | null>;
+  constructor(opts: AuthCredentialOptions<TPayload>);
+  issue(userId: string, options?: IssueOptions<TPayload>): Promise<IssueResult>;
+  validate(accessToken: string): Promise<AuthContext<TPayload> | null>;
   refresh(refreshToken: string): Promise<IssueResult>;
   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<TClaims>>>;
+  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
 //#region src/email.d.ts
@@ -391,4 +513,4 @@ type BuildMagicLinkUrl = (kind: AuthEmailKind, token: string, ctx?: {
  */
 declare function generateMagicLinkToken(): string;
 //#endregion
-export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, type DenylistStore, DenylistStoreMemory, type EmailSender, type IssueOptions, type IssueResult, type JwtAlgorithm, type RefreshConfig, type SmsSender, defaultClock, generateMagicLinkToken };
+export { type AuthContext, AuthCredential, type AuthCredentialOptions, type AuthEmailEvent, type AuthEmailKind, AuthError, type AuthErrorType, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type Clock, type CredentialMetadata, type CredentialState, type CredentialStore, CredentialStoreEncapsulated, type CredentialStoreEncapsulatedOptions, CredentialStoreJwt, type CredentialStoreJwtOptions, CredentialStoreMemory, type DenylistStore, DenylistStoreMemory, type EmailSender, type EnrichedSession, type IssueOptions, type IssueResult, type JwtAlgorithm, type RefreshConfig, type SessionEnricher, type SessionInfo, type SmsSender, defaultClock, generateMagicLinkToken };