@aooth/auth 0.1.6 → 0.1.8

package/dist/redis.d.mts

@@ -1,4 +1,4 @@
-import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-B1t8KkfA.mjs";
+import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-BG6m6oSJ.mjs";
 
 //#region src/redis/index.d.ts
 /**
@@ -52,19 +52,20 @@ interface RedisCredentialStoreOptions {
  * so Redis evicts it on expiry. The user-index set is NOT TTL-bounded — we
  * lazily prune dead members on `listForUser` and `revokeAllForUser`.
  */
-declare class CredentialStoreRedis<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreRedis<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly redis;
   private readonly prefix;
   constructor(opts: RedisCredentialStoreOptions);
   private tokenKey;
   private userKey;
-  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;
   }>>;
 }

package/dist/redis.mjs

@@ -73,6 +73,15 @@ var CredentialStoreRedis = class {
 		await this.redis.del(this.tokenKey(token));
 		await this.redis.srem(this.userKey(state.userId), token);
 	}
+	async touch(token, at) {
+		const raw = await this.redis.get(this.tokenKey(token));
+		if (raw === null) return;
+		const state = JSON.parse(raw);
+		state.lastSeenAt = at;
+		const ttlMs = Math.max(0, state.expiresAt - Date.now());
+		if (ttlMs <= 0) return;
+		await this.redis.set(this.tokenKey(token), JSON.stringify(state), "PX", ttlMs);
+	}
 	async revokeAllForUser(userId) {
 		const setKey = this.userKey(userId);
 		const tokens = await this.redis.smembers(setKey);

package/dist/store-BG6m6oSJ.d.cts

@@ -0,0 +1,263 @@
+//#region src/credential/types.d.ts
+/**
+ * The read-time envelope a successful auth check always produces — the fixed
+ * fields, before the credential's typed payload is merged in. See
+ * {@link AuthContext}.
+ */
+interface AuthContextBase {
+  userId: string;
+  method: "session" | "token";
+  credentialId: string;
+  /**
+   * Stable id of the session (token family) that authenticated this request.
+   * Survives refresh-token rotation (see {@link CredentialState.sessionId}).
+   * Legacy tokens issued before sessionId existed fall back to the token
+   * fingerprint, so a session is always identifiable. Lets a consumer match
+   * "this device" against {@link SessionInfo} and pass `keepSessionId` to
+   * `revokeOtherSessions`.
+   */
+  sessionId?: string;
+  expiresAt: number;
+}
+/**
+ * What a successful auth check produces: the {@link AuthContextBase} envelope
+ * intersected with the credential's **typed payload** `TPayload` — the root
+ * fields a consumer adds to their credential model (e.g. an
+ * `@arbac.attenuate.*`-annotated field read by `@aooth/arbac-moost`). There is
+ * no free-form `claims` container; per-token data is typed, validated root
+ * fields that round-trip through the store and surface here by name.
+ */
+type AuthContext<TPayload extends object = object> = AuthContextBase & TPayload;
+/**
+ * Display metadata for stateful credentials.
+ * Extensible via TypeScript declaration merging:
+ *   declare module '@aooth/auth' {
+ *     interface CredentialMetadata { geoCountry?: string }
+ *   }
+ */
+interface CredentialMetadata {
+  ip?: string;
+  userAgent?: string;
+  fingerprint?: string;
+  label?: string;
+  /**
+   * Semantic credential kind — e.g. `"cli-session"` / `"pat"` — distinct from
+   * the internal {@link CredentialState.kind} (`access`/`refresh`) discriminator.
+   * Set from `IssueOptions.kind` at mint time and carried forward across
+   * rotation with the rest of `metadata`, so the whole session family shares it.
+   * Stored here (not as a top-level envelope column) so it round-trips through
+   * every store with no schema change; surfaced as {@link SessionInfo.kind} and
+   * the `listSessions({ kind })` filter. Absent ⇒ an ordinary interactive session.
+   */
+  credentialKind?: string;
+}
+/**
+ * Persisted state of a credential — the fixed **envelope**. A consumer's
+ * per-token payload is NOT a field here; it is carried as additional typed
+ * root fields intersected via `CredentialState & TPayload` (the orchestrator,
+ * stores, and atscript-db adapter are generic over that payload). Reserved
+ * envelope keys (see {@link credentialPayloadOf}) must not be reused as
+ * payload field names.
+ */
+interface CredentialState {
+  userId: string;
+  issuedAt: number;
+  expiresAt: number;
+  metadata?: CredentialMetadata;
+  /**
+   * Discriminant between access and refresh credentials persisted in the same store.
+   * Defaults to "access" when omitted.
+   */
+  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 */
+  rotatedAt?: number;
+  /**
+   * Stable id of the session (token family) this credential belongs to. Minted
+   * once by `issue()` and copied forward onto every rotation (access + refresh),
+   * so a single login = one `sessionId` for its whole lifetime. The keystone for
+   * grouping access/refresh/rotations into one row in {@link SessionInfo} and for
+   * per-session revoke. Opaque + random; never derived from token material.
+   */
+  sessionId?: string;
+  /**
+   * Last activity timestamp for the session. Only written when
+   * `AuthCredential` is configured with `trackLastSeen`; otherwise undefined and
+   * consumers fall back to `issuedAt`. See {@link SessionInfo.lastSeenAt}.
+   */
+  lastSeenAt?: number;
+}
+/**
+ * One logical session — a token family collapsed into a single row. Returned by
+ * `AuthCredential.listSessions`; the public surface the "active sessions" UI
+ * reads (richer than {@link AuthContext}, additive). Stores only raw facts;
+ * device/browser/os/location are derived at read time via {@link SessionEnricher}.
+ */
+interface SessionInfo {
+  /** Stable across rotation; see {@link CredentialState.sessionId}. */
+  sessionId: string;
+  userId: string;
+  /** `issuedAt` of the session's origin credential. */
+  createdAt: number;
+  /** Newest activity time across the family; falls back to `createdAt` when untracked. */
+  lastSeenAt?: number;
+  /** Expiry of the session's live refresh token (or access token when no refresh). */
+  expiresAt: number;
+  /** Set by the caller (e.g. `SessionsController`) when this is the caller's own session. */
+  current?: boolean;
+  metadata?: CredentialMetadata;
+  /**
+   * Semantic credential kind of the family (`metadata.credentialKind`) — e.g.
+   * `"cli-session"` / `"pat"`. Omitted for ordinary interactive sessions. Lets a
+   * UI segment non-browser credentials into their own bucket; the matching
+   * filter is `listSessions({ kind })`.
+   */
+  kind?: string;
+}
+/**
+ * A {@link SessionInfo} enriched with derived, non-stored fields. Produced by a
+ * consumer-supplied {@link SessionEnricher} at read time so aooth ships no
+ * UA-parser or geo dependency and stores no derived data.
+ */
+interface EnrichedSession extends SessionInfo {
+  device?: string;
+  browser?: string;
+  os?: string;
+  location?: string;
+  geo?: {
+    country?: string;
+    city?: string;
+  };
+}
+/**
+ * Read-time enrichment hook. Maps a raw {@link SessionInfo} to an
+ * {@link EnrichedSession} (e.g. parse `metadata.userAgent`, GeoIP-lookup
+ * `metadata.ip`). Plugged in via `listSessions(userId, { enrich })`.
+ */
+type SessionEnricher = (s: SessionInfo) => EnrichedSession | Promise<EnrichedSession>;
+/**
+ * Result of issuing a credential or refreshing it.
+ */
+interface IssueResult {
+  accessToken: string;
+  refreshToken?: string;
+  accessExpiresAt: number;
+  refreshExpiresAt?: number;
+}
+/**
+ * Refresh token configuration.
+ */
+interface RefreshConfig {
+  /** Refresh token lifetime in milliseconds. */
+  ttl: number;
+  /**
+   * Rotation strategy. Defaults to 'sliding'.
+   *
+   * - `'none'` — issue a new access token only; the refresh token stays in place.
+   * - `'sliding'` — rotate the refresh token on every use and **slide** its
+   *   expiry forward (`now + ttl`); a rolling session that lives as long as it
+   *   keeps being used.
+   * - `'always'` — rotate the refresh token on every use but keep a **fixed**
+   *   session ceiling: each rotated token inherits the family's original
+   *   `expiresAt`, so the session has an absolute maximum lifetime regardless of
+   *   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.
+   *
+   * Note: the grace window needs a stateful store (one with `listForUser`).
+   * Stateless stores (JWT, Encapsulated) cannot mutate an issued token in place;
+   * after the first rotation the old refresh becomes unusable, so on those
+   * stores both `'sliding'` and `'always'` fall back to single-use semantics
+   * 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. */
+  rotationGraceMs?: number;
+  /**
+   * Revocation scope when refresh-token reuse is detected (replay after grace,
+   * or — on stateless stores — replay of a single-use token). Defaults to
+   * `'session'`: revoke only the compromised token family
+   * ({@link AuthCredential.revokeSession}), the OAuth-best-practice response.
+   * `'user'` revokes every session for the user
+   * ({@link AuthCredential.revokeAllForUser}) — more aggressive, opt-in. On
+   * stateless stores that cannot enumerate sessions, `'session'` falls back to
+   * the user-wide revocation epoch regardless.
+   */
+  reuseResponse?: "session" | "user";
+  /** Theft detection hook — invoked when a previously-rotated refresh is reused. */
+  onRotationReuse?: (state: CredentialState) => void;
+}
+//#endregion
+//#region src/stores/store.d.ts
+/**
+ * Pluggable credential storage. Implementations: Memory, JWT, Encapsulated.
+ * Same shape works for stateful and stateless stores. Stateless stores treat
+ * the token as the state itself (sign/encrypt on persist, verify/decrypt on retrieve).
+ *
+ * The store is generic over the credential's typed **payload** `TPayload` — the
+ * root fields a consumer adds to their credential model. Every state it handles
+ * is `CredentialState & TPayload` (the envelope plus those flat root fields; no
+ * `claims` container). `TPayload extends object` widens to arrays/classes, so
+ * pass a plain object type (e.g. `{ scope: string; tier: number }`) whose
+ * values survive a JSON round-trip on stateless stores.
+ */
+interface CredentialStore<TPayload extends object = object> {
+  /** Persist state, return token. For stateless stores, token IS the state. */
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  /** Retrieve state from token. Returns null if expired/invalid/revoked. */
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  /** Retrieve + invalidate (single-use). For stateless: needs denylist. */
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  /**
+   * Update state. The returned token MAY differ from the input — stateful
+   * stores typically return the same token, while stateless stores re-issue
+   * a new token (denylisting the old). Callers must use the returned value.
+   */
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
+  /** Revoke a single token. For stateless: requires denylist; otherwise throws. */
+  revoke(token: string): Promise<void>;
+  /**
+   * Revoke all credentials for a user. Returns count revoked.
+   * Stateless stores cannot enumerate individual tokens; they MAY implement
+   * the cascade via a per-user revocation epoch (see `CredentialStoreJwt`)
+   * and return a sentinel `1` to indicate "revocation took effect".
+   */
+  revokeAllForUser(userId: string): Promise<number>;
+  /** List active credentials for a user (stateful only). */
+  listForUser?(userId: string): Promise<Array<CredentialState & TPayload & {
+    token: string;
+  }>>;
+  /**
+   * Optional last-activity stamp. Set `state.lastSeenAt = at` for the token if
+   * it exists; no-op otherwise. Backs `AuthCredential`'s
+   * `trackLastSeen: 'validate'` mode. Stateless stores omit it (the token is
+   * immutable once issued).
+   */
+  touch?(token: string, at: number): Promise<void>;
+  /**
+   * Derive a stable, domain-separated 32-byte subkey from this store's
+   * symmetric secret via HKDF-SHA256. Used so other subsystems (e.g. the
+   * workflow-state encryption key) can reuse the auth secret WITHOUT the raw
+   * secret ever leaving the store. Only implemented by stores backed by a
+   * symmetric secret (JWT-HMAC, Encapsulated); stateful/asymmetric stores
+   * omit it. `label` provides domain separation (different label → different key).
+   */
+  deriveSubkey?(label: string): Buffer;
+}
+/**
+ * Denylist for stateless revocation. Stores revoked-but-not-yet-expired token IDs.
+ * Auto-bounded by token TTLs.
+ */
+interface DenylistStore {
+  add(jti: string, expiresAt: number): Promise<void>;
+  has(jti: string): Promise<boolean>;
+  cleanup(): Promise<number>;
+}
+//#endregion
+export { CredentialState as a, RefreshConfig as c, CredentialMetadata as i, SessionEnricher as l, DenylistStore as n, EnrichedSession as o, AuthContext as r, IssueResult as s, CredentialStore as t, SessionInfo as u };

package/dist/store-BG6m6oSJ.d.mts

@@ -0,0 +1,263 @@
+//#region src/credential/types.d.ts
+/**
+ * The read-time envelope a successful auth check always produces — the fixed
+ * fields, before the credential's typed payload is merged in. See
+ * {@link AuthContext}.
+ */
+interface AuthContextBase {
+  userId: string;
+  method: "session" | "token";
+  credentialId: string;
+  /**
+   * Stable id of the session (token family) that authenticated this request.
+   * Survives refresh-token rotation (see {@link CredentialState.sessionId}).
+   * Legacy tokens issued before sessionId existed fall back to the token
+   * fingerprint, so a session is always identifiable. Lets a consumer match
+   * "this device" against {@link SessionInfo} and pass `keepSessionId` to
+   * `revokeOtherSessions`.
+   */
+  sessionId?: string;
+  expiresAt: number;
+}
+/**
+ * What a successful auth check produces: the {@link AuthContextBase} envelope
+ * intersected with the credential's **typed payload** `TPayload` — the root
+ * fields a consumer adds to their credential model (e.g. an
+ * `@arbac.attenuate.*`-annotated field read by `@aooth/arbac-moost`). There is
+ * no free-form `claims` container; per-token data is typed, validated root
+ * fields that round-trip through the store and surface here by name.
+ */
+type AuthContext<TPayload extends object = object> = AuthContextBase & TPayload;
+/**
+ * Display metadata for stateful credentials.
+ * Extensible via TypeScript declaration merging:
+ *   declare module '@aooth/auth' {
+ *     interface CredentialMetadata { geoCountry?: string }
+ *   }
+ */
+interface CredentialMetadata {
+  ip?: string;
+  userAgent?: string;
+  fingerprint?: string;
+  label?: string;
+  /**
+   * Semantic credential kind — e.g. `"cli-session"` / `"pat"` — distinct from
+   * the internal {@link CredentialState.kind} (`access`/`refresh`) discriminator.
+   * Set from `IssueOptions.kind` at mint time and carried forward across
+   * rotation with the rest of `metadata`, so the whole session family shares it.
+   * Stored here (not as a top-level envelope column) so it round-trips through
+   * every store with no schema change; surfaced as {@link SessionInfo.kind} and
+   * the `listSessions({ kind })` filter. Absent ⇒ an ordinary interactive session.
+   */
+  credentialKind?: string;
+}
+/**
+ * Persisted state of a credential — the fixed **envelope**. A consumer's
+ * per-token payload is NOT a field here; it is carried as additional typed
+ * root fields intersected via `CredentialState & TPayload` (the orchestrator,
+ * stores, and atscript-db adapter are generic over that payload). Reserved
+ * envelope keys (see {@link credentialPayloadOf}) must not be reused as
+ * payload field names.
+ */
+interface CredentialState {
+  userId: string;
+  issuedAt: number;
+  expiresAt: number;
+  metadata?: CredentialMetadata;
+  /**
+   * Discriminant between access and refresh credentials persisted in the same store.
+   * Defaults to "access" when omitted.
+   */
+  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 */
+  rotatedAt?: number;
+  /**
+   * Stable id of the session (token family) this credential belongs to. Minted
+   * once by `issue()` and copied forward onto every rotation (access + refresh),
+   * so a single login = one `sessionId` for its whole lifetime. The keystone for
+   * grouping access/refresh/rotations into one row in {@link SessionInfo} and for
+   * per-session revoke. Opaque + random; never derived from token material.
+   */
+  sessionId?: string;
+  /**
+   * Last activity timestamp for the session. Only written when
+   * `AuthCredential` is configured with `trackLastSeen`; otherwise undefined and
+   * consumers fall back to `issuedAt`. See {@link SessionInfo.lastSeenAt}.
+   */
+  lastSeenAt?: number;
+}
+/**
+ * One logical session — a token family collapsed into a single row. Returned by
+ * `AuthCredential.listSessions`; the public surface the "active sessions" UI
+ * reads (richer than {@link AuthContext}, additive). Stores only raw facts;
+ * device/browser/os/location are derived at read time via {@link SessionEnricher}.
+ */
+interface SessionInfo {
+  /** Stable across rotation; see {@link CredentialState.sessionId}. */
+  sessionId: string;
+  userId: string;
+  /** `issuedAt` of the session's origin credential. */
+  createdAt: number;
+  /** Newest activity time across the family; falls back to `createdAt` when untracked. */
+  lastSeenAt?: number;
+  /** Expiry of the session's live refresh token (or access token when no refresh). */
+  expiresAt: number;
+  /** Set by the caller (e.g. `SessionsController`) when this is the caller's own session. */
+  current?: boolean;
+  metadata?: CredentialMetadata;
+  /**
+   * Semantic credential kind of the family (`metadata.credentialKind`) — e.g.
+   * `"cli-session"` / `"pat"`. Omitted for ordinary interactive sessions. Lets a
+   * UI segment non-browser credentials into their own bucket; the matching
+   * filter is `listSessions({ kind })`.
+   */
+  kind?: string;
+}
+/**
+ * A {@link SessionInfo} enriched with derived, non-stored fields. Produced by a
+ * consumer-supplied {@link SessionEnricher} at read time so aooth ships no
+ * UA-parser or geo dependency and stores no derived data.
+ */
+interface EnrichedSession extends SessionInfo {
+  device?: string;
+  browser?: string;
+  os?: string;
+  location?: string;
+  geo?: {
+    country?: string;
+    city?: string;
+  };
+}
+/**
+ * Read-time enrichment hook. Maps a raw {@link SessionInfo} to an
+ * {@link EnrichedSession} (e.g. parse `metadata.userAgent`, GeoIP-lookup
+ * `metadata.ip`). Plugged in via `listSessions(userId, { enrich })`.
+ */
+type SessionEnricher = (s: SessionInfo) => EnrichedSession | Promise<EnrichedSession>;
+/**
+ * Result of issuing a credential or refreshing it.
+ */
+interface IssueResult {
+  accessToken: string;
+  refreshToken?: string;
+  accessExpiresAt: number;
+  refreshExpiresAt?: number;
+}
+/**
+ * Refresh token configuration.
+ */
+interface RefreshConfig {
+  /** Refresh token lifetime in milliseconds. */
+  ttl: number;
+  /**
+   * Rotation strategy. Defaults to 'sliding'.
+   *
+   * - `'none'` — issue a new access token only; the refresh token stays in place.
+   * - `'sliding'` — rotate the refresh token on every use and **slide** its
+   *   expiry forward (`now + ttl`); a rolling session that lives as long as it
+   *   keeps being used.
+   * - `'always'` — rotate the refresh token on every use but keep a **fixed**
+   *   session ceiling: each rotated token inherits the family's original
+   *   `expiresAt`, so the session has an absolute maximum lifetime regardless of
+   *   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.
+   *
+   * Note: the grace window needs a stateful store (one with `listForUser`).
+   * Stateless stores (JWT, Encapsulated) cannot mutate an issued token in place;
+   * after the first rotation the old refresh becomes unusable, so on those
+   * stores both `'sliding'` and `'always'` fall back to single-use semantics
+   * 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. */
+  rotationGraceMs?: number;
+  /**
+   * Revocation scope when refresh-token reuse is detected (replay after grace,
+   * or — on stateless stores — replay of a single-use token). Defaults to
+   * `'session'`: revoke only the compromised token family
+   * ({@link AuthCredential.revokeSession}), the OAuth-best-practice response.
+   * `'user'` revokes every session for the user
+   * ({@link AuthCredential.revokeAllForUser}) — more aggressive, opt-in. On
+   * stateless stores that cannot enumerate sessions, `'session'` falls back to
+   * the user-wide revocation epoch regardless.
+   */
+  reuseResponse?: "session" | "user";
+  /** Theft detection hook — invoked when a previously-rotated refresh is reused. */
+  onRotationReuse?: (state: CredentialState) => void;
+}
+//#endregion
+//#region src/stores/store.d.ts
+/**
+ * Pluggable credential storage. Implementations: Memory, JWT, Encapsulated.
+ * Same shape works for stateful and stateless stores. Stateless stores treat
+ * the token as the state itself (sign/encrypt on persist, verify/decrypt on retrieve).
+ *
+ * The store is generic over the credential's typed **payload** `TPayload` — the
+ * root fields a consumer adds to their credential model. Every state it handles
+ * is `CredentialState & TPayload` (the envelope plus those flat root fields; no
+ * `claims` container). `TPayload extends object` widens to arrays/classes, so
+ * pass a plain object type (e.g. `{ scope: string; tier: number }`) whose
+ * values survive a JSON round-trip on stateless stores.
+ */
+interface CredentialStore<TPayload extends object = object> {
+  /** Persist state, return token. For stateless stores, token IS the state. */
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  /** Retrieve state from token. Returns null if expired/invalid/revoked. */
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  /** Retrieve + invalidate (single-use). For stateless: needs denylist. */
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  /**
+   * Update state. The returned token MAY differ from the input — stateful
+   * stores typically return the same token, while stateless stores re-issue
+   * a new token (denylisting the old). Callers must use the returned value.
+   */
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
+  /** Revoke a single token. For stateless: requires denylist; otherwise throws. */
+  revoke(token: string): Promise<void>;
+  /**
+   * Revoke all credentials for a user. Returns count revoked.
+   * Stateless stores cannot enumerate individual tokens; they MAY implement
+   * the cascade via a per-user revocation epoch (see `CredentialStoreJwt`)
+   * and return a sentinel `1` to indicate "revocation took effect".
+   */
+  revokeAllForUser(userId: string): Promise<number>;
+  /** List active credentials for a user (stateful only). */
+  listForUser?(userId: string): Promise<Array<CredentialState & TPayload & {
+    token: string;
+  }>>;
+  /**
+   * Optional last-activity stamp. Set `state.lastSeenAt = at` for the token if
+   * it exists; no-op otherwise. Backs `AuthCredential`'s
+   * `trackLastSeen: 'validate'` mode. Stateless stores omit it (the token is
+   * immutable once issued).
+   */
+  touch?(token: string, at: number): Promise<void>;
+  /**
+   * Derive a stable, domain-separated 32-byte subkey from this store's
+   * symmetric secret via HKDF-SHA256. Used so other subsystems (e.g. the
+   * workflow-state encryption key) can reuse the auth secret WITHOUT the raw
+   * secret ever leaving the store. Only implemented by stores backed by a
+   * symmetric secret (JWT-HMAC, Encapsulated); stateful/asymmetric stores
+   * omit it. `label` provides domain separation (different label → different key).
+   */
+  deriveSubkey?(label: string): Buffer;
+}
+/**
+ * Denylist for stateless revocation. Stores revoked-but-not-yet-expired token IDs.
+ * Auto-bounded by token TTLs.
+ */
+interface DenylistStore {
+  add(jti: string, expiresAt: number): Promise<void>;
+  has(jti: string): Promise<boolean>;
+  cleanup(): Promise<number>;
+}
+//#endregion
+export { CredentialState as a, RefreshConfig as c, CredentialMetadata as i, SessionEnricher as l, DenylistStore as n, EnrichedSession as o, AuthContext as r, IssueResult as s, CredentialStore as t, SessionInfo as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/auth",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Auth method layer for aoothjs (sessions, tokens, password reset, MFA primitives)",
   "keywords": [
     "aoothjs",
@@ -25,7 +25,8 @@
   },
   "files": [
     "dist",
-    "src/atscript-db/auth-credential.as"
+    "src/atscript-db/auth-credential.as",
+    "src/atscript-db/auth-credential.as.d.ts"
   ],
   "type": "module",
   "sideEffects": false,
@@ -43,12 +44,29 @@
       "import": "./dist/redis.mjs",
       "require": "./dist/redis.cjs"
     },
+    "./client": {
+      "types": "./dist/client.d.mts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.cjs"
+    },
+    "./authz": {
+      "types": "./dist/authz.d.mts",
+      "import": "./dist/authz.mjs",
+      "require": "./dist/authz.cjs"
+    },
     "./atscript-db": {
       "types": "./dist/atscript-db.d.mts",
       "import": "./dist/atscript-db.mjs",
       "require": "./dist/atscript-db.cjs"
     },
-    "./atscript-db/model.as": "./src/atscript-db/auth-credential.as",
+    "./atscript-db/model": {
+      "types": "./src/atscript-db/auth-credential.as.d.ts",
+      "default": "./src/atscript-db/auth-credential.as"
+    },
+    "./atscript-db/model.as": {
+      "types": "./src/atscript-db/auth-credential.as.d.ts",
+      "default": "./src/atscript-db/auth-credential.as"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -56,17 +74,17 @@
   },
   "dependencies": {
     "jose": "^6.2.3",
-    "@aooth/user": "0.1.6"
+    "@aooth/user": "0.1.8"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.64",
-    "@atscript/db": "^0.1.90",
-    "@atscript/db-sql-tools": "^0.1.90",
-    "@atscript/db-sqlite": "^0.1.90",
-    "@atscript/typescript": "^0.1.64",
+    "@atscript/core": "^0.1.69",
+    "@atscript/db": "^0.1.96",
+    "@atscript/db-sql-tools": "^0.1.96",
+    "@atscript/db-sqlite": "^0.1.96",
+    "@atscript/typescript": "^0.1.69",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.6.2",
-    "unplugin-atscript": "^0.1.64"
+    "unplugin-atscript": "^0.1.69"
   },
   "peerDependencies": {
     "@atscript/db": ">=0.1.79"