@draftlab/auth 0.15.0 → 0.16.0

package/dist/types/revocation.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Token revocation management for Draft Auth.
+ * Handles blacklisting of revoked tokens to prevent their use.
+ *
+ * ## Overview
+ *
+ * Revocation allows users to invalidate specific tokens before their natural expiration.
+ * This is essential for logout functionality and security in case of token compromise.
+ *
+ * ## Storage Structure
+ *
+ * Revoked tokens are stored with their expiration time to allow automatic cleanup:
+ * ```
+ * revocation:token:{tokenHash} → { revokedAt: timestamp, expiresAt: timestamp }
+ * ```
+ *
+ * ## Security Considerations
+ *
+ * - Revoked tokens are checked on every use
+ * - Storage automatically cleans up expired revocations
+ * - Hash tokens for storage to reduce memory usage
+ * - Use constant-time comparison for hash verification
+ *
+ * @packageDocumentation
+ */
+import { type StorageAdapter } from "./storage/storage";
+/**
+ * Data stored for a revoked token.
+ * Tracks when the token was revoked and when it naturally expires.
+ */
+export interface RevocationRecord {
+    /** Timestamp when the token was revoked (milliseconds) */
+    revokedAt: number;
+    /** Timestamp when the token naturally expires (milliseconds) */
+    expiresAt: number;
+}
+/**
+ * Token revocation manager.
+ * Provides methods to revoke tokens and check if a token has been revoked.
+ */
+export declare const Revocation: {
+    /**
+     * Revokes a token, preventing it from being used even if not yet expired.
+     *
+     * @param storage - Storage adapter to use
+     * @param token - The token to revoke (access or refresh token)
+     * @param expiresAt - When the token naturally expires (milliseconds since epoch)
+     * @returns Promise that resolves when revocation is stored
+     *
+     * @example
+     * ```ts
+     * // Revoke a refresh token on logout
+     * await Revocation.revoke(storage, refreshToken, expiresAt)
+     * ```
+     */
+    readonly revoke: (storage: StorageAdapter, token: string, expiresAt: number) => Promise<void>;
+    /**
+     * Checks if a token has been revoked.
+     * Returns false if token is not in revocation list (never revoked or already expired).
+     *
+     * @param storage - Storage adapter to use
+     * @param token - The token to check
+     * @returns Promise resolving to true if token is revoked, false otherwise
+     *
+     * @example
+     * ```ts
+     * // Check if token was revoked before using it
+     * const isRevoked = await Revocation.isRevoked(storage, accessToken)
+     * if (isRevoked) {
+     *   throw new InvalidAccessTokenError()
+     * }
+     * ```
+     */
+    readonly isRevoked: (storage: StorageAdapter, token: string) => Promise<boolean>;
+};
+//# sourceMappingURL=revocation.d.ts.map

package/dist/types/revocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocation.d.ts","sourceRoot":"","sources":["../../src/revocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEhE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAA;IACjB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAA;CACjB;AAeD;;;GAGG;AACH,eAAO,MAAM,UAAU;IACtB;;;;;;;;;;;;;OAaG;+BACqB,cAAc,SAAS,MAAM,aAAa,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;IAgBxF;;;;;;;;;;;;;;;;OAgBG;kCACwB,cAAc,SAAS,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;CASlE,CAAA"}

package/dist/{storage/memory.d.mts → types/storage/memory.d.ts}

@@ -1,7 +1,4 @@
-import { StorageAdapter } from "./storage.mjs";
-
-//#region src/storage/memory.d.ts
-
+import { type StorageAdapter } from "./storage";
 /**
  * In-memory storage adapter for Draft Auth with optional file persistence.
  *
@@ -38,20 +35,20 @@ import { StorageAdapter } from "./storage.mjs";
 /**
  * Configuration options for the memory storage adapter.
  */
-interface MemoryStorageOptions {
-  /**
-   * File path for persisting the in-memory store to disk.
-   * When specified, the store will be saved to this file on changes
-   * and loaded from it on startup if it exists.
-   *
-   * @example
-   * ```ts
-   * {
-   *   persist: "./data/auth-storage.json"
-   * }
-   * ```
-   */
-  readonly persist?: string;
+export interface MemoryStorageOptions {
+    /**
+     * File path for persisting the in-memory store to disk.
+     * When specified, the store will be saved to this file on changes
+     * and loaded from it on startup if it exists.
+     *
+     * @example
+     * ```ts
+     * {
+     *   persist: "./data/auth-storage.json"
+     * }
+     * ```
+     */
+    readonly persist?: string;
 }
 /**
  * Creates an in-memory storage adapter with optional file persistence.
@@ -77,6 +74,5 @@ interface MemoryStorageOptions {
  * })
  * ```
  */
-declare const MemoryStorage: (options?: MemoryStorageOptions) => StorageAdapter;
-//#endregion
-export { MemoryStorage, MemoryStorageOptions };
+export declare const MemoryStorage: (options?: MemoryStorageOptions) => StorageAdapter;
+//# sourceMappingURL=memory.d.ts.map

package/dist/types/storage/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/storage/memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,cAAc,EAAY,MAAM,WAAW,CAAA;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CACzB;AAaD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,oBAAoB,KAAG,cA2J9D,CAAA"}

package/dist/types/storage/storage.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Storage abstraction layer for Draft Auth persistence operations.
+ * Provides a unified interface for different storage backends with key encoding,
+ * TTL support, and type-safe operations.
+ */
+/**
+ * Abstract storage adapter interface that must be implemented by all storage backends.
+ * Defines the core operations needed for OAuth data persistence.
+ */
+export interface StorageAdapter {
+    /**
+     * Retrieves a value by its key path.
+     *
+     * @param key - Array of key segments forming the storage path
+     * @returns Promise resolving to the stored value or undefined if not found
+     */
+    get(key: string[]): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Removes a value by its key path.
+     *
+     * @param key - Array of key segments forming the storage path
+     * @returns Promise that resolves when removal is complete
+     */
+    remove(key: string[]): Promise<void>;
+    /**
+     * Stores a value with an optional expiration date.
+     *
+     * @param key - Array of key segments forming the storage path
+     * @param value - The value to store
+     * @param expiry - Optional expiration date for automatic cleanup
+     * @returns Promise that resolves when storage is complete
+     */
+    set(key: string[], value: unknown, expiry?: Date): Promise<void>;
+    /**
+     * Scans for keys matching a prefix pattern.
+     *
+     * @param prefix - Array of key segments to use as prefix filter
+     * @returns Async iterable of key-value pairs matching the prefix
+     */
+    scan(prefix: string[]): AsyncIterable<readonly [string[], unknown]>;
+}
+/**
+ * Joins an array of key segments into a single string using the separator.
+ * Segments are properly escaped to handle any input, including separators and escape characters.
+ *
+ * @param key - Array of key segments to join
+ * @returns Single string representing the full key path
+ *
+ * @example
+ * ```ts
+ * joinKey(['user', 'data\x1fwith\x1fseparators'])
+ * // Returns: "user\x1fdata\\x1fwith\\x1fseparators"
+ * ```
+ */
+export declare const joinKey: (key: string[]) => string;
+/**
+ * Splits a joined key string back into its component segments.
+ * Handles escaped characters properly.
+ *
+ * @param key - Joined key string to split
+ * @returns Array of individual key segments
+ *
+ * @example
+ * ```ts
+ * splitKey("user\x1fdata\\x1fwith\\x1fseparators")
+ * // Returns: ['user', 'data\x1fwith\x1fseparators']
+ * ```
+ */
+export declare const splitKey: (key: string) => string[];
+/**
+ * High-level storage operations with key encoding and type safety.
+ * Provides a convenient interface over storage adapters with additional features
+ * like TTL validation and secure key encoding to prevent collisions.
+ */
+export declare const Storage: {
+    /**
+     * Encodes key segments by escaping special characters.
+     * Ensures storage keys don't contain unescaped separator characters that could cause collisions.
+     *
+     * @param key - Array of key segments to encode
+     * @returns Array of properly escaped key segments
+     *
+     * @throws {Error} If any segment is empty or whitespace-only
+     *
+     * @example
+     * ```ts
+     * Storage.encode(['user', 'data\x1fwith\x1fseparators'])
+     * // Returns: ['user', 'data\\x1fwith\\x1fseparators']
+     * ```
+     */
+    readonly encode: (key: string[]) => string[];
+    /**
+     * Decodes key segments by unescaping special characters.
+     * Reverse operation of encode().
+     *
+     * @param key - Array of encoded key segments
+     * @returns Array of decoded key segments
+     *
+     * @internal
+     */
+    readonly decode: (key: string[]) => string[];
+    /**
+     * Retrieves a typed value from storage.
+     *
+     * @template T - Expected type of the stored value
+     * @param adapter - Storage adapter to use
+     * @param key - Array of key segments identifying the value
+     * @returns Promise resolving to the typed value or null if not found
+     *
+     * @example
+     * ```ts
+     * interface UserSession {
+     *   userId: string
+     *   expiresAt: number
+     * }
+     *
+     * const session = await Storage.get<UserSession>(adapter, ['sessions', sessionId])
+     * if (session) {
+     *   // Fully typed: session.userId
+     * }
+     * ```
+     */
+    readonly get: <T = Record<string, unknown>>(adapter: StorageAdapter, key: string[]) => Promise<T | null>;
+    /**
+     * Stores a value with optional time-to-live in seconds.
+     * Validates that TTL is a positive integer to prevent edge cases like negative or overflow values.
+     *
+     * @param adapter - Storage adapter to use
+     * @param key - Array of key segments identifying where to store
+     * @param value - The value to store
+     * @param ttlSeconds - Optional TTL in seconds for automatic expiration
+     * @returns Promise that resolves when storage is complete
+     *
+     * @throws {RangeError} If TTL is invalid (negative, non-integer, or exceeds maximum)
+     *
+     * @example
+     * ```ts
+     * // Store with 1 hour TTL
+     * await Storage.set(adapter, ['sessions', sessionId], sessionData, 3600)
+     *
+     * // Store permanently (no expiration)
+     * await Storage.set(adapter, ['users', userId], userData)
+     * ```
+     */
+    readonly set: (adapter: StorageAdapter, key: string[], value: unknown, ttlSeconds?: number) => Promise<void>;
+    /**
+     * Removes a value from storage.
+     *
+     * @param adapter - Storage adapter to use
+     * @param key - Array of key segments identifying the value to remove
+     * @returns Promise that resolves when removal is complete
+     *
+     * @example
+     * ```ts
+     * await Storage.remove(adapter, ['sessions', expiredSessionId])
+     * ```
+     */
+    readonly remove: (adapter: StorageAdapter, key: string[]) => Promise<void>;
+    /**
+     * Scans for entries matching a key prefix with type safety.
+     *
+     * @template T - Expected type of the stored values
+     * @param adapter - Storage adapter to use
+     * @param prefix - Array of key segments to use as prefix filter
+     * @returns Async iterable of typed key-value pairs
+     *
+     * @example
+     * ```ts
+     * // Find all user sessions
+     * for await (const [key, session] of Storage.scan<UserSession>(adapter, ['sessions'])) {
+     *   // Session: `${key.join('/')} expires at ${session.expiresAt}`
+     * }
+     * ```
+     */
+    readonly scan: <T = Record<string, unknown>>(adapter: StorageAdapter, prefix: string[]) => AsyncIterable<readonly [string[], T]>;
+};
+//# sourceMappingURL=storage.d.ts.map

package/dist/types/storage/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/storage/storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAA;IAEhE;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpC;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhE;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC,CAAA;CACnE;AAcD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,KAAG,MAEvC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAAM,EAE5C,CAAA;AAsCD;;;;GAIG;AACH,eAAO,MAAM,OAAO;IACnB;;;;;;;;;;;;;;OAcG;2BACW,MAAM,EAAE,KAAG,MAAM,EAAE;IAIjC;;;;;;;;OAQG;2BACW,MAAM,EAAE,KAAG,MAAM,EAAE;IAIjC;;;;;;;;;;;;;;;;;;;;OAoBG;mBACG,CAAC,qCACG,cAAc,OAClB,MAAM,EAAE,KACX,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAIpB;;;;;;;;;;;;;;;;;;;;OAoBG;4BAEO,cAAc,OAClB,MAAM,EAAE,SACN,OAAO,eACD,MAAM,KACjB,OAAO,CAAC,IAAI,CAAC;IAwBhB;;;;;;;;;;;OAWG;+BACe,cAAc,OAAO,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAAC;IAI/D;;;;;;;;;;;;;;;OAeG;oBACI,CAAC,qCACE,cAAc,UACf,MAAM,EAAE,KACd,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;CAG/B,CAAA"}

package/dist/{storage/turso.d.mts → types/storage/turso.d.ts}

@@ -1,8 +1,5 @@
-import { StorageAdapter } from "./storage.mjs";
-import { Client } from "@libsql/client";
-
-//#region src/storage/turso.d.ts
-
+import type { Client } from "@libsql/client";
+import { type StorageAdapter } from "./storage";
 /**
  * Creates a Turso storage adapter using the provided LibSQL client.
  * Automatically initializes the required database table and implements
@@ -26,6 +23,5 @@ import { Client } from "@libsql/client";
  * const app = issuer({ storage, ... })
  * ```
  */
-declare const TursoStorage: (client: Client) => StorageAdapter;
-//#endregion
-export { TursoStorage };
+export declare const TursoStorage: (client: Client) => StorageAdapter;
+//# sourceMappingURL=turso.d.ts.map

package/dist/types/storage/turso.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turso.d.ts","sourceRoot":"","sources":["../../../src/storage/turso.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAW,KAAK,cAAc,EAAY,MAAM,WAAW,CAAA;AAyClE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,KAAG,cA2H7C,CAAA"}

package/dist/{storage/unstorage.d.mts → types/storage/unstorage.d.ts}

@@ -1,8 +1,12 @@
-import { StorageAdapter } from "./storage.mjs";
-import { Driver } from "unstorage";
-
-//#region src/storage/unstorage.d.ts
-
+/**
+ * Universal storage adapter for Draft Auth using Unstorage drivers.
+ * Provides seamless integration with any Unstorage-compatible backend including
+ * Redis, Cloudflare KV, Vercel KV, and more.
+ *
+ * @packageDocumentation
+ */
+import { type Driver as UnstorageDriver } from "unstorage";
+import { type StorageAdapter } from "./storage";
 /**
  * Creates a Draft Auth storage adapter using Unstorage drivers.
  * Supports automatic expiration, error handling, and any Unstorage driver.
@@ -29,10 +33,7 @@ import { Driver } from "unstorage";
  * const memoryStorage = UnStorage()
  * ```
  */
-declare const UnStorage: ({
-  driver
-}?: {
-  driver?: Driver;
+export declare const UnStorage: ({ driver }?: {
+    driver?: UnstorageDriver;
 }) => StorageAdapter;
-//#endregion
-export { UnStorage };
+//# sourceMappingURL=unstorage.d.ts.map

package/dist/types/storage/unstorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unstorage.d.ts","sourceRoot":"","sources":["../../../src/storage/unstorage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAiB,KAAK,MAAM,IAAI,eAAe,EAAE,MAAM,WAAW,CAAA;AACzE,OAAO,EAAW,KAAK,cAAc,EAAY,MAAM,WAAW,CAAA;AAalE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,SAAS,GAAI,aAAY;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAO,KAAG,cA6GzE,CAAA"}

package/dist/types/subject.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Subjects define the structure of data stored in access tokens after successful authentication.
+ * They represent the different types of entities that can be authenticated (users, admins, etc.)
+ * and are encoded as JWT claims in the resulting access tokens.
+ *
+ * ## Quick Start
+ *
+ * ### 1. Define your subjects
+ * ```ts title="subjects.ts"
+ * import { object, string } from "valibot"
+ * import { createSubjects } from "@draftlab/auth/subject"
+ *
+ * export const subjects = createSubjects({
+ *   user: object({
+ *     userID: string()
+ *   }),
+ *   admin: object({
+ *     userID: string(),
+ *     workspaceID: string()
+ *   })
+ * })
+ * ```
+ *
+ * ### 2. Use in your issuer
+ * ```ts title="issuer.ts"
+ * import { subjects } from "./subjects"
+ *
+ * const app = issuer({
+ *   { ... }
+ *   subjects,
+ *   async success(ctx, value) {
+ *     const userID = await lookupUser(value.email)
+ *     return ctx.subject("user", { userID })
+ *   }
+ * })
+ * ```
+ *
+ * ### 3. Verify tokens in your app
+ * ```ts title="middleware.ts"
+ * import { subjects } from "./subjects"
+ *
+ * const verified = await client.verify(subjects, accessToken)
+ * if (verified.success) {
+ *  // Fully typed: verified.data.subject.properties.userID
+ * }
+ * ```
+ *
+ * ## Important Notes
+ *
+ * - Only store data that doesn't change frequently (avoid usernames, emails that might change)
+ * - Keep payload small as it's embedded in every access token
+ * - Use any validation library compatible with standard-schema specification
+ *
+ * @packageDocumentation
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Prettify } from "./util";
+/**
+ * Schema definition for subjects, mapping subject type names to their validation schemas.
+ * Each key represents a subject type, and each value is a schema that validates
+ * the properties for that subject type.
+ *
+ * @example
+ * ```ts
+ * const schema: SubjectSchema = {
+ *   user: object({ userID: string() }),
+ *   admin: object({ userID: string(), workspaceID: string() })
+ * }
+ * ```
+ */
+export type SubjectSchema = Record<string, StandardSchemaV1>;
+/**
+ * Internal type that transforms a SubjectSchema into a union of subject payload objects.
+ * Each payload contains the subject type and its validated properties.
+ *
+ * @template T - The subject schema to transform
+ * @internal
+ */
+export type SubjectPayload<T extends SubjectSchema> = Prettify<{
+    [K in keyof T & string]: {
+        type: K;
+        properties: StandardSchemaV1.InferOutput<T[K]>;
+    };
+}[keyof T & string]>;
+/**
+ * Creates a strongly-typed subject schema that can be used throughout your application.
+ * The returned schema maintains type information for excellent IDE support and runtime validation.
+ *
+ * @template Schema - The subject schema type being created
+ * @param types - Object mapping subject type names to their validation schemas
+ * @returns The same schema object with preserved type information
+ *
+ * @example
+ * ```ts
+ * import { object, string, number } from "valibot"
+ *
+ * const subjects = createSubjects({
+ *   user: object({
+ *     userID: string(),
+ *     createdAt: number()
+ *   }),
+ *   admin: object({
+ *     userID: string(),
+ *     workspaceID: string(),
+ *     permissions: array(string())
+ *   }),
+ *   service: object({
+ *     serviceID: string(),
+ *     apiVersion: string()
+ *   })
+ * })
+ * ```
+ */
+export declare const createSubjects: <Schema extends SubjectSchema>(types: Schema) => Schema;
+//# sourceMappingURL=subject.d.ts.map

package/dist/types/subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,aAAa,IAAI,QAAQ,CAC7D;KACE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG;QACxB,IAAI,EAAE,CAAC,CAAA;QACP,UAAU,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;KAC9C;CACD,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,aAAa,EAAE,OAAO,MAAM,KAAG,MAE5E,CAAA"}