@aooth/auth 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,386 @@
+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 { CryptoKey } from "jose";
+
+//#region src/errors.d.ts
+type AuthErrorType = "INVALID_TOKEN" | "TOKEN_EXPIRED" | "TOKEN_REVOKED" | "REFRESH_REUSE_DETECTED" | "STATELESS_OPERATION_UNSUPPORTED" | "MAX_CONCURRENT_REACHED" | "INVALID_CONFIG";
+declare class AuthError extends Error {
+  readonly type: AuthErrorType;
+  readonly details?: Record<string, unknown> | undefined;
+  readonly name = "AuthError";
+  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.
+ *
+ * - `Map<token, state>` is the primary index.
+ * - `Map<userId, Set<token>>` is a secondary index for `revokeAllForUser` /
+ *   `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> {
+  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>;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  listForUser(userId: string): Promise<Array<CredentialState<TClaims> & {
+    token: string;
+  }>>;
+  private indexAdd;
+  private indexRemove;
+}
+//#endregion
+//#region src/stores/denylist-memory.d.ts
+/**
+ * In-memory denylist for stateless revocation.
+ *
+ * Stores a map from JTI (or any opaque identifier) to absolute expiry timestamp.
+ * `has` returns false for entries whose TTL has elapsed and lazily removes them.
+ * `cleanup` performs a sweep across the map and returns the number of entries
+ * removed, useful for periodic compaction in long-lived processes.
+ */
+declare class DenylistStoreMemory implements DenylistStore {
+  private readonly entries;
+  private readonly clock;
+  constructor(opts?: {
+    clock?: Clock;
+  });
+  add(jti: string, expiresAt: number): Promise<void>;
+  has(jti: string): Promise<boolean>;
+  cleanup(): Promise<number>;
+}
+//#endregion
+//#region src/stores/jwt.d.ts
+/**
+ * Supported JWT signing algorithms.
+ * - HS256/HS384/HS512: symmetric (shared secret).
+ * - RS*, ES*, EdDSA: asymmetric (private/public keypair).
+ */
+type JwtAlgorithm = "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512" | "ES256" | "ES384" | "ES512" | "EdDSA";
+interface CredentialStoreJwtOptions {
+  /** Signing algorithm. Defaults to 'HS256'. */
+  algorithm?: JwtAlgorithm;
+  /** For HS*: secret string or Uint8Array (>=32 bytes recommended for HS256). */
+  secret?: string | Uint8Array | CryptoKey;
+  /** For asymmetric algorithms: signing (private) key. */
+  privateKey?: CryptoKey | Uint8Array;
+  /** For asymmetric algorithms: verifying (public) key. */
+  publicKey?: CryptoKey | Uint8Array;
+  /** Issuer claim (`iss`). Optional. */
+  issuer?: string;
+  /** Audience claim (`aud`). Optional. */
+  audience?: string;
+  /** Optional denylist for revocation support. */
+  denylist?: DenylistStore;
+  /** Optional clock for testability. */
+  clock?: Clock;
+}
+/**
+ * Stateless credential store that signs the credential state into a JWT.
+ *
+ * The token IS the state — there is no internal map. State is reconstructed
+ * by verifying signature/claims on every retrieve. Revocation requires a
+ * `denylist`; without one, `revoke`/`update`/`consume` throw
+ * STATELESS_OPERATION_UNSUPPORTED.
+ */
+declare class CredentialStoreJwt<TClaims extends object = object> implements CredentialStore<TClaims> {
+  private readonly algorithm;
+  private readonly signingKey;
+  private readonly verifyingKey;
+  private readonly issuer?;
+  private readonly audience?;
+  private readonly denylist?;
+  private readonly clock;
+  /**
+   * Per-user revocation epoch (ms). `revokeAllForUser` sets this to
+   * `clock.now()`; `retrieve` rejects any token whose `iatMs` predates the
+   * user's epoch (same-ms mints are accepted so recovery/invite flows can
+   * revoke and re-issue in one tick). Compensates for JWT statelessness so
+   * password-change cascades invalidate tokens minted before the change.
+   * In-memory: resets on process restart (a known JWT limitation — production
+   * deployments needing durability should back this with an external store).
+   */
+  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>;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  private requireDenylist;
+  /** Convert payload `exp` (seconds) to ms; fall back to a 60s window. */
+  private payloadExpMs;
+  /**
+   * Reject tokens minted before the user's revocation epoch. Same-ms mints
+   * (`iatMs === epoch`) are accepted so a workflow can revoke and re-issue in
+   * one tick. `iatMs` mirrors `iat` at ms precision; we fall back to
+   * `iat * 1000` for tokens that predate the mirror field.
+   */
+  private passesEpoch;
+  private verify;
+  private payloadToState;
+}
+//#endregion
+//#region src/stores/encapsulated.d.ts
+interface CredentialStoreEncapsulatedOptions {
+  /**
+   * Encryption key material. If a 32-byte Buffer/Uint8Array is provided it is
+   * used directly; otherwise it is run through scrypt to derive a 32-byte key.
+   */
+  secret: string | Buffer | Uint8Array;
+  /** Optional denylist for revocation support. */
+  denylist?: DenylistStore;
+  /** Optional clock for testability. */
+  clock?: Clock;
+}
+/**
+ * Stateless credential store that encrypts the credential state with
+ * AES-256-GCM. The token IS the encrypted blob, base64url-encoded as
+ * `iv (12B) || ciphertext || authTag (16B)`.
+ *
+ * Same denylist semantics as {@link CredentialStoreJwt}: revocation /
+ * single-use consume / update require a denylist; otherwise these operations
+ * throw STATELESS_OPERATION_UNSUPPORTED.
+ *
+ * Key derivation:
+ * - A 32-byte `Buffer`/`Uint8Array` `secret` is used as the AES key directly
+ *   (no KDF).
+ * - Any other secret (string, shorter/longer buffer) is run through scrypt
+ *   with a fixed library-scoped salt to produce a 32-byte key. The salt is
+ *   intentionally fixed so keys remain stable across process restarts; if it
+ *   were random, every previously issued token would become undecryptable.
+ *   For maximum protection against rainbow tables on weak passphrases,
+ *   provide a 32-byte random buffer as `secret` (the KDF path is skipped).
+ *
+ * Revocation caveat: `revokeAllForUser` uses an in-memory per-user epoch map.
+ * It does not survive process restart and does not sync across instances —
+ * the same limitation as `CredentialStoreJwt`. Use `CredentialStoreRedis` or
+ * `CredentialStoreAtscriptDb` when you need native enumeration with durable
+ * cross-instance cascade semantics.
+ */
+declare class CredentialStoreEncapsulated<TClaims extends object = object> implements CredentialStore<TClaims> {
+  private readonly key;
+  private readonly denylist?;
+  private readonly clock;
+  /**
+   * Per-user revocation epoch (ms). `revokeAllForUser` sets this to
+   * `clock.now()`; `retrieve`/`consume` reject any decrypted state whose
+   * `issuedAt` is strictly less than the user's epoch (same-ms mints are
+   * accepted so recovery/invite flows can revoke and re-issue in the same
+   * tick). Mirrors the JWT store pattern; see class JSDoc for durability
+   * caveats.
+   */
+  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>;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  /**
+   * Reject decrypted payloads whose `issuedAt` predates the user's revocation
+   * epoch. Same-ms mints (`issuedAt === epoch`) are accepted so a workflow can
+   * revoke and re-issue in one tick. Mirrors `CredentialStoreJwt.passesEpoch`.
+   */
+  private passesEpoch;
+  private requireDenylist;
+  private decrypt;
+}
+//#endregion
+//#region src/credential/auth-credential.d.ts
+interface AuthCredentialOptions<TClaims extends object = object> {
+  /** Pluggable credential store (Memory, JWT, Encapsulated, ...). */
+  store: CredentialStore<TClaims>;
+  /** 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";
+  /** Optional clock for testability. */
+  clock?: Clock;
+}
+interface IssueOptions<TClaims extends object = object> {
+  claims?: TClaims;
+  metadata?: CredentialMetadata;
+}
+/**
+ * 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-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.
+ */
+declare class AuthCredential<TClaims 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 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<TClaims>);
+  issue(userId: string, options?: IssueOptions<TClaims>): Promise<IssueResult>;
+  validate(accessToken: string): Promise<AuthContext<TClaims> | null>;
+  refresh(refreshToken: string): Promise<IssueResult>;
+  private refreshNone;
+  private refreshSliding;
+  revoke(token: string): Promise<void>;
+  revokeAllForUser(userId: string): Promise<number>;
+  listForUser(userId: string): Promise<Array<AuthContext<TClaims>>>;
+  private enforceConcurrencyLimit;
+  private issueAccessFromRefresh;
+  private issueRotatedPair;
+  private lookupConsumedRefresh;
+  private fireRefreshReuseTheftResponse;
+}
+//#endregion
+//#region src/email.d.ts
+/**
+ * Discriminator for auth-related email events emitted by the workflow stack.
+ *
+ * `mfa.code` is reserved for v2 — v1 is TOTP only. `login.pincode`,
+ * `recovery.pincode`, `invite.pincode` and `notifyNewDevice` are added with
+ * BIG 3.1 (login workflow re-implementation).
+ */
+type AuthEmailKind = "recovery.magicLink" | "invite.magicLink" | "mfa.code" | "login.pincode" | "recovery.pincode" | "invite.pincode" | "notifyNewDevice";
+/**
+ * Structured event passed to `EmailSender.send()` from inside the auth
+ * workflows. Flat and serialisable so consumers can route it to any
+ * transport (templated mailer, queue, webhook).
+ */
+interface AuthEmailEvent {
+  kind: AuthEmailKind;
+  recipient: string;
+  /** Resume URL for magic-link events. Absent for code / notify events. */
+  url?: string;
+  /** Numeric OTP for code-bearing events. Absent for magic links / notify. */
+  code?: string;
+  /** Unix-ms timestamp at which the token / code expires. */
+  expiresAt: number;
+  /** Recipient's username when known (omitted for invites to new accounts). */
+  username?: string;
+  /** Free-form payload (e.g. invite-side `roles: string[]`, notify-side `ip`). */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Transport interface implemented by consumers. Aoothjs ships no
+ * implementation — wire SendGrid / SES / Twilio / queue here.
+ *
+ * The workflow `await`s this call, so it should not block on slow downstream
+ * transports — push to a queue and return.
+ */
+interface EmailSender {
+  send(event: AuthEmailEvent): Promise<void>;
+}
+//#endregion
+//#region src/sms.d.ts
+/**
+ * Discriminator for SMS events emitted by the auth workflow stack.
+ *
+ * Mirrors {@link AuthEmailKind} — kept on a separate union because email and
+ * SMS transports do not overlap (email carries `url` for magic links; SMS
+ * never does).
+ */
+type AuthSmsKind = "login.pincode" | "recovery.pincode" | "invite.pincode";
+/**
+ * Structured event passed to {@link SmsSender}`.send()` from inside the auth
+ * workflows. Flat and serialisable so consumers can route it to any
+ * SMS gateway (Twilio, SNS, queue).
+ */
+interface AuthSmsEvent {
+  kind: AuthSmsKind;
+  /** E.164 phone number. */
+  recipient: string;
+  code: string;
+  /** Pincode TTL in ms — convenience for templating "expires in N min". */
+  ttlMs: number;
+  /** User id when known (omitted for pre-resolved flows). */
+  userId?: string;
+}
+/**
+ * Transport interface implemented by consumers. Aoothjs ships no concrete
+ * SMS adapter (Twilio / SNS / etc. are consumer-specific) — only this
+ * interface. Register via `setProvideRegistry([SmsSender, () => mySender])`.
+ *
+ * Boot-time invariant: when a workflow's options include SMS as an MFA
+ * transport, the workflow constructor throws if no `SmsSender` is
+ * registered (fail loud, not at first user attempt).
+ */
+interface SmsSender {
+  send(event: AuthSmsEvent): Promise<void>;
+}
+//#endregion
+//#region src/magic-link.d.ts
+/**
+ * Consumer-supplied URL builder. The consumer chooses route, query
+ * convention, and base URL — aoothjs does not assume a domain or scheme.
+ *
+ * Recommended convention: include the token as `?wfs=<token>` so the
+ * frontend can mount `<AsWfForm initialToken="...">` to resume the flow.
+ */
+type BuildMagicLinkUrl = (kind: AuthEmailKind, token: string) => string;
+/**
+ * 32 bytes of CSPRNG entropy (256 bits) encoded as base64url — 43 chars,
+ * URL-safe. Strong enough to survive short TTLs against online guessing.
+ */
+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 };