@aooth/auth 0.1.1

package/dist/redis.cjs

@@ -0,0 +1,142 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_crypto = require("node:crypto");
+//#region src/redis/index.ts
+/**
+* Redis-backed `CredentialStore`. Token id is a random UUID (the same
+* scheme as `CredentialStoreMemory`) — the token is opaque to the client.
+*
+* Storage shape:
+*   - `<prefix>:t:<token>` → JSON-serialised `CredentialState`
+*   - `<prefix>:u:<userId>` → SET of tokens for that user (for
+*     `revokeAllForUser` and `listForUser`)
+*
+* TTL: when `persist(state, ttl)` is called, the state key gets a `PX` TTL
+* so Redis evicts it on expiry. The user-index set is NOT TTL-bounded — we
+* lazily prune dead members on `listForUser` and `revokeAllForUser`.
+*/
+var CredentialStoreRedis = class {
+	redis;
+	prefix;
+	constructor(opts) {
+		this.redis = opts.redis;
+		this.prefix = opts.prefix ?? "aooth:cred";
+	}
+	tokenKey(token) {
+		return `${this.prefix}:t:${token}`;
+	}
+	userKey(userId) {
+		return `${this.prefix}:u:${userId}`;
+	}
+	async persist(state, ttl) {
+		const token = (0, node_crypto.randomUUID)();
+		const stored = { ...state };
+		if (typeof ttl === "number") stored.expiresAt = Date.now() + ttl;
+		const ttlMs = Math.max(0, stored.expiresAt - Date.now());
+		if (ttlMs <= 0) throw new Error("CredentialStoreRedis.persist: refusing to persist an already-expired credential");
+		await this.redis.set(this.tokenKey(token), JSON.stringify(stored), "PX", ttlMs);
+		await this.redis.sadd(this.userKey(state.userId), token);
+		return token;
+	}
+	async retrieve(token) {
+		const raw = await this.redis.get(this.tokenKey(token));
+		if (raw === null) return null;
+		const state = JSON.parse(raw);
+		if (state.expiresAt <= Date.now()) {
+			await this.redis.del(this.tokenKey(token));
+			await this.redis.srem(this.userKey(state.userId), token);
+			return null;
+		}
+		return state;
+	}
+	async consume(token) {
+		const state = await this.retrieve(token);
+		if (!state) return null;
+		await this.revoke(token);
+		return state;
+	}
+	async update(token, state) {
+		const existingRaw = await this.redis.get(this.tokenKey(token));
+		if (existingRaw === null) return token;
+		const existing = JSON.parse(existingRaw);
+		if (existing.userId !== state.userId) {
+			await this.redis.srem(this.userKey(existing.userId), token);
+			await this.redis.sadd(this.userKey(state.userId), token);
+		}
+		const ttlMs = Math.max(0, state.expiresAt - Date.now());
+		if (ttlMs > 0) await this.redis.set(this.tokenKey(token), JSON.stringify(state), "PX", ttlMs);
+		else await this.revoke(token);
+		return token;
+	}
+	async revoke(token) {
+		const raw = await this.redis.get(this.tokenKey(token));
+		if (raw === null) return;
+		const state = JSON.parse(raw);
+		await this.redis.del(this.tokenKey(token));
+		await this.redis.srem(this.userKey(state.userId), token);
+	}
+	async revokeAllForUser(userId) {
+		const setKey = this.userKey(userId);
+		const tokens = await this.redis.smembers(setKey);
+		if (tokens.length === 0) return 0;
+		const keys = tokens.map((t) => this.tokenKey(t));
+		const removed = await this.redis.del(...keys);
+		await this.redis.srem(setKey, ...tokens);
+		return removed;
+	}
+	async listForUser(userId) {
+		const setKey = this.userKey(userId);
+		const tokens = await this.redis.smembers(setKey);
+		if (tokens.length === 0) return [];
+		const now = Date.now();
+		const out = [];
+		const dead = [];
+		for (const token of tokens) {
+			const raw = await this.redis.get(this.tokenKey(token));
+			if (raw === null) {
+				dead.push(token);
+				continue;
+			}
+			const state = JSON.parse(raw);
+			if (state.expiresAt <= now) {
+				dead.push(token);
+				continue;
+			}
+			out.push({
+				...state,
+				token
+			});
+		}
+		if (dead.length > 0) await this.redis.srem(setKey, ...dead);
+		return out;
+	}
+};
+/**
+* Redis-backed `DenylistStore`. Each `add` writes a key with a `PX` TTL set
+* to `expiresAt - now`, so Redis self-evicts the entry once the underlying
+* token would have expired anyway. `cleanup` is a no-op for that reason.
+*/
+var DenylistStoreRedis = class {
+	redis;
+	prefix;
+	constructor(opts) {
+		this.redis = opts.redis;
+		this.prefix = opts.prefix ?? "aooth:dl";
+	}
+	key(jti) {
+		return `${this.prefix}:${jti}`;
+	}
+	async add(jti, expiresAt) {
+		const ttlMs = expiresAt - Date.now();
+		if (ttlMs <= 0) return;
+		await this.redis.set(this.key(jti), "1", "PX", ttlMs);
+	}
+	async has(jti) {
+		return await this.redis.exists(this.key(jti)) > 0;
+	}
+	async cleanup() {
+		return 0;
+	}
+};
+//#endregion
+exports.CredentialStoreRedis = CredentialStoreRedis;
+exports.DenylistStoreRedis = DenylistStoreRedis;

package/dist/redis.d.cts

@@ -0,0 +1,91 @@
+import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-untAtWQz.cjs";
+
+//#region src/redis/index.d.ts
+/**
+ * Structural Redis client. Covers the exact set of commands used by
+ * `CredentialStoreRedis` and `DenylistStoreRedis` — no more.
+ *
+ * Compatible by-shape with `ioredis`, `redis@4+`, `@redis/client`, and ad-hoc
+ * test doubles. Consumers are free to wrap whatever client they ship; we
+ * deliberately do not declare a peer dep on any specific package.
+ *
+ * Return types are widened to the union of what real clients return:
+ *   - `set` returns `'OK' | string | null` (null on conditional sets that fail)
+ *   - `del` / `expire` / `exists` / `sadd` / `srem` return `number`
+ *   - `get` returns `string | null`
+ *   - `smembers` returns `string[]`
+ *
+ * The `ttl` arg passed to `set` is in MILLISECONDS — we always call with
+ * `PX`, never `EX`, so callers don't have to translate.
+ */
+interface RedisLike {
+  /** `SET key value [PX ms]` — accepts an optional ms TTL. */
+  set(key: string, value: string, mode?: "PX", ttlMs?: number): Promise<string | null>;
+  get(key: string): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  exists(key: string): Promise<number>;
+  /** `PEXPIRE key ttlMs` — ms TTL on an existing key. */
+  expire(key: string, ttlMs: number): Promise<number>;
+  sadd(key: string, ...members: string[]): Promise<number>;
+  srem(key: string, ...members: string[]): Promise<number>;
+  smembers(key: string): Promise<string[]>;
+}
+interface RedisCredentialStoreOptions {
+  redis: RedisLike;
+  /**
+   * Key prefix for every stored entry. Defaults to `aooth:cred`. Combined
+   * with the token id (`<prefix>:t:<token>`) and per-user index set
+   * (`<prefix>:u:<userId>`).
+   */
+  prefix?: string;
+}
+/**
+ * Redis-backed `CredentialStore`. Token id is a random UUID (the same
+ * scheme as `CredentialStoreMemory`) — the token is opaque to the client.
+ *
+ * Storage shape:
+ *   - `<prefix>:t:<token>` → JSON-serialised `CredentialState`
+ *   - `<prefix>:u:<userId>` → SET of tokens for that user (for
+ *     `revokeAllForUser` and `listForUser`)
+ *
+ * TTL: when `persist(state, ttl)` is called, the state key gets a `PX` TTL
+ * 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> {
+  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>;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  listForUser(userId: string): Promise<Array<CredentialState<TClaims> & {
+    token: string;
+  }>>;
+}
+interface RedisDenylistStoreOptions {
+  redis: RedisLike;
+  /** Key prefix. Defaults to `aooth:dl`. Combined as `<prefix>:<jti>`. */
+  prefix?: string;
+}
+/**
+ * Redis-backed `DenylistStore`. Each `add` writes a key with a `PX` TTL set
+ * to `expiresAt - now`, so Redis self-evicts the entry once the underlying
+ * token would have expired anyway. `cleanup` is a no-op for that reason.
+ */
+declare class DenylistStoreRedis implements DenylistStore {
+  private readonly redis;
+  private readonly prefix;
+  constructor(opts: RedisDenylistStoreOptions);
+  private key;
+  add(jti: string, expiresAt: number): Promise<void>;
+  has(jti: string): Promise<boolean>;
+  cleanup(): Promise<number>;
+}
+//#endregion
+export { CredentialStoreRedis, DenylistStoreRedis, RedisLike };

package/dist/redis.d.mts

@@ -0,0 +1,91 @@
+import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-B1t8KkfA.mjs";
+
+//#region src/redis/index.d.ts
+/**
+ * Structural Redis client. Covers the exact set of commands used by
+ * `CredentialStoreRedis` and `DenylistStoreRedis` — no more.
+ *
+ * Compatible by-shape with `ioredis`, `redis@4+`, `@redis/client`, and ad-hoc
+ * test doubles. Consumers are free to wrap whatever client they ship; we
+ * deliberately do not declare a peer dep on any specific package.
+ *
+ * Return types are widened to the union of what real clients return:
+ *   - `set` returns `'OK' | string | null` (null on conditional sets that fail)
+ *   - `del` / `expire` / `exists` / `sadd` / `srem` return `number`
+ *   - `get` returns `string | null`
+ *   - `smembers` returns `string[]`
+ *
+ * The `ttl` arg passed to `set` is in MILLISECONDS — we always call with
+ * `PX`, never `EX`, so callers don't have to translate.
+ */
+interface RedisLike {
+  /** `SET key value [PX ms]` — accepts an optional ms TTL. */
+  set(key: string, value: string, mode?: "PX", ttlMs?: number): Promise<string | null>;
+  get(key: string): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  exists(key: string): Promise<number>;
+  /** `PEXPIRE key ttlMs` — ms TTL on an existing key. */
+  expire(key: string, ttlMs: number): Promise<number>;
+  sadd(key: string, ...members: string[]): Promise<number>;
+  srem(key: string, ...members: string[]): Promise<number>;
+  smembers(key: string): Promise<string[]>;
+}
+interface RedisCredentialStoreOptions {
+  redis: RedisLike;
+  /**
+   * Key prefix for every stored entry. Defaults to `aooth:cred`. Combined
+   * with the token id (`<prefix>:t:<token>`) and per-user index set
+   * (`<prefix>:u:<userId>`).
+   */
+  prefix?: string;
+}
+/**
+ * Redis-backed `CredentialStore`. Token id is a random UUID (the same
+ * scheme as `CredentialStoreMemory`) — the token is opaque to the client.
+ *
+ * Storage shape:
+ *   - `<prefix>:t:<token>` → JSON-serialised `CredentialState`
+ *   - `<prefix>:u:<userId>` → SET of tokens for that user (for
+ *     `revokeAllForUser` and `listForUser`)
+ *
+ * TTL: when `persist(state, ttl)` is called, the state key gets a `PX` TTL
+ * 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> {
+  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>;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  listForUser(userId: string): Promise<Array<CredentialState<TClaims> & {
+    token: string;
+  }>>;
+}
+interface RedisDenylistStoreOptions {
+  redis: RedisLike;
+  /** Key prefix. Defaults to `aooth:dl`. Combined as `<prefix>:<jti>`. */
+  prefix?: string;
+}
+/**
+ * Redis-backed `DenylistStore`. Each `add` writes a key with a `PX` TTL set
+ * to `expiresAt - now`, so Redis self-evicts the entry once the underlying
+ * token would have expired anyway. `cleanup` is a no-op for that reason.
+ */
+declare class DenylistStoreRedis implements DenylistStore {
+  private readonly redis;
+  private readonly prefix;
+  constructor(opts: RedisDenylistStoreOptions);
+  private key;
+  add(jti: string, expiresAt: number): Promise<void>;
+  has(jti: string): Promise<boolean>;
+  cleanup(): Promise<number>;
+}
+//#endregion
+export { CredentialStoreRedis, DenylistStoreRedis, RedisLike };

package/dist/redis.mjs

@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto";
+//#region src/redis/index.ts
+/**
+* Redis-backed `CredentialStore`. Token id is a random UUID (the same
+* scheme as `CredentialStoreMemory`) — the token is opaque to the client.
+*
+* Storage shape:
+*   - `<prefix>:t:<token>` → JSON-serialised `CredentialState`
+*   - `<prefix>:u:<userId>` → SET of tokens for that user (for
+*     `revokeAllForUser` and `listForUser`)
+*
+* TTL: when `persist(state, ttl)` is called, the state key gets a `PX` TTL
+* so Redis evicts it on expiry. The user-index set is NOT TTL-bounded — we
+* lazily prune dead members on `listForUser` and `revokeAllForUser`.
+*/
+var CredentialStoreRedis = class {
+	redis;
+	prefix;
+	constructor(opts) {
+		this.redis = opts.redis;
+		this.prefix = opts.prefix ?? "aooth:cred";
+	}
+	tokenKey(token) {
+		return `${this.prefix}:t:${token}`;
+	}
+	userKey(userId) {
+		return `${this.prefix}:u:${userId}`;
+	}
+	async persist(state, ttl) {
+		const token = randomUUID();
+		const stored = { ...state };
+		if (typeof ttl === "number") stored.expiresAt = Date.now() + ttl;
+		const ttlMs = Math.max(0, stored.expiresAt - Date.now());
+		if (ttlMs <= 0) throw new Error("CredentialStoreRedis.persist: refusing to persist an already-expired credential");
+		await this.redis.set(this.tokenKey(token), JSON.stringify(stored), "PX", ttlMs);
+		await this.redis.sadd(this.userKey(state.userId), token);
+		return token;
+	}
+	async retrieve(token) {
+		const raw = await this.redis.get(this.tokenKey(token));
+		if (raw === null) return null;
+		const state = JSON.parse(raw);
+		if (state.expiresAt <= Date.now()) {
+			await this.redis.del(this.tokenKey(token));
+			await this.redis.srem(this.userKey(state.userId), token);
+			return null;
+		}
+		return state;
+	}
+	async consume(token) {
+		const state = await this.retrieve(token);
+		if (!state) return null;
+		await this.revoke(token);
+		return state;
+	}
+	async update(token, state) {
+		const existingRaw = await this.redis.get(this.tokenKey(token));
+		if (existingRaw === null) return token;
+		const existing = JSON.parse(existingRaw);
+		if (existing.userId !== state.userId) {
+			await this.redis.srem(this.userKey(existing.userId), token);
+			await this.redis.sadd(this.userKey(state.userId), token);
+		}
+		const ttlMs = Math.max(0, state.expiresAt - Date.now());
+		if (ttlMs > 0) await this.redis.set(this.tokenKey(token), JSON.stringify(state), "PX", ttlMs);
+		else await this.revoke(token);
+		return token;
+	}
+	async revoke(token) {
+		const raw = await this.redis.get(this.tokenKey(token));
+		if (raw === null) return;
+		const state = JSON.parse(raw);
+		await this.redis.del(this.tokenKey(token));
+		await this.redis.srem(this.userKey(state.userId), token);
+	}
+	async revokeAllForUser(userId) {
+		const setKey = this.userKey(userId);
+		const tokens = await this.redis.smembers(setKey);
+		if (tokens.length === 0) return 0;
+		const keys = tokens.map((t) => this.tokenKey(t));
+		const removed = await this.redis.del(...keys);
+		await this.redis.srem(setKey, ...tokens);
+		return removed;
+	}
+	async listForUser(userId) {
+		const setKey = this.userKey(userId);
+		const tokens = await this.redis.smembers(setKey);
+		if (tokens.length === 0) return [];
+		const now = Date.now();
+		const out = [];
+		const dead = [];
+		for (const token of tokens) {
+			const raw = await this.redis.get(this.tokenKey(token));
+			if (raw === null) {
+				dead.push(token);
+				continue;
+			}
+			const state = JSON.parse(raw);
+			if (state.expiresAt <= now) {
+				dead.push(token);
+				continue;
+			}
+			out.push({
+				...state,
+				token
+			});
+		}
+		if (dead.length > 0) await this.redis.srem(setKey, ...dead);
+		return out;
+	}
+};
+/**
+* Redis-backed `DenylistStore`. Each `add` writes a key with a `PX` TTL set
+* to `expiresAt - now`, so Redis self-evicts the entry once the underlying
+* token would have expired anyway. `cleanup` is a no-op for that reason.
+*/
+var DenylistStoreRedis = class {
+	redis;
+	prefix;
+	constructor(opts) {
+		this.redis = opts.redis;
+		this.prefix = opts.prefix ?? "aooth:dl";
+	}
+	key(jti) {
+		return `${this.prefix}:${jti}`;
+	}
+	async add(jti, expiresAt) {
+		const ttlMs = expiresAt - Date.now();
+		if (ttlMs <= 0) return;
+		await this.redis.set(this.key(jti), "1", "PX", ttlMs);
+	}
+	async has(jti) {
+		return await this.redis.exists(this.key(jti)) > 0;
+	}
+	async cleanup() {
+		return 0;
+	}
+};
+//#endregion
+export { CredentialStoreRedis, DenylistStoreRedis };

package/dist/store-B1t8KkfA.d.mts

@@ -0,0 +1,124 @@
+//#region src/credential/types.d.ts
+/**
+ * What a successful auth check produces.
+ * Generic over TClaims for typed custom claims.
+ */
+interface AuthContext<TClaims extends object = object> {
+  userId: string;
+  method: "session" | "token";
+  credentialId: string;
+  expiresAt: number;
+  claims?: TClaims;
+}
+/**
+ * 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;
+}
+/**
+ * Persisted state of a credential.
+ */
+interface CredentialState<TClaims extends object = object> {
+  userId: string;
+  issuedAt: number;
+  expiresAt: number;
+  claims?: TClaims;
+  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;
+}
+/**
+ * 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'.
+   *
+   * Note: 'sliding' grace-period replay tolerance only works against stateful
+   * stores (e.g. {@link CredentialStoreMemory}). Stateless stores (JWT,
+   * Encapsulated) cannot mutate an issued token in place; after the first
+   * rotation the old refresh becomes unusable, so 'sliding' degrades to
+   * 'always' semantics. Use 'always' explicitly for stateless deployments.
+   */
+  rotation?: "none" | "always" | "sliding";
+  /** Grace period for sliding rotation, in milliseconds. Defaults to 30_000. */
+  rotationGraceMs?: number;
+  /** 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).
+ *
+ * `TClaims` is constrained to `extends object`, which TypeScript widens to
+ * include arrays, class instances, and `Function`. Pass a plain object type
+ * (e.g. `{ role: string; tenant: string }`); using arrays/classes will type-
+ * check but won't survive JSON-serialised stateless storage round-trips.
+ */
+interface CredentialStore<TClaims extends object = object> {
+  /** Persist state, return token. For stateless stores, token IS the state. */
+  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
+  /** Retrieve state from token. Returns null if expired/invalid/revoked. */
+  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
+  /** Retrieve + invalidate (single-use). For stateless: needs denylist. */
+  consume(token: string): Promise<CredentialState<TClaims> | 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<TClaims>): 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<TClaims> & {
+    token: string;
+  }>>;
+}
+/**
+ * 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, CredentialMetadata as i, DenylistStore as n, IssueResult as o, AuthContext as r, RefreshConfig as s, CredentialStore as t };