@draftlab/auth 0.0.3 → 0.0.4

package/dist/provider/provider.d.ts

@@ -1,3 +1,227 @@
-import "../storage-CxKerLlc.js";
-import { Provider, ProviderError, ProviderOptions, ProviderRoute, ProviderUnknownError } from "../provider-tndlqCzp.js";
+import { StorageAdapter } from "../storage/storage.js";
+import { Router } from "@draftlab/auth-router";
+import { RouterContext } from "@draftlab/auth-router/types";
+
+//#region src/provider/provider.d.ts
+
+/**
+ * OAuth provider system for Draft Auth.
+ * Defines the interfaces and utilities for implementing authentication providers
+ * that integrate with various OAuth 2.0 services.
+ *
+ * ## Creating a Provider
+ *
+ * ```ts
+ * export const MyProvider = (config: MyConfig): Provider<MyUserData> => ({
+ *   type: "my-provider",
+ *
+ *   init(routes, ctx) {
+ *     routes.get("/authorize", async (c) => {
+ *       // Redirect to provider's auth URL
+ *       return c.redirect(authUrl)
+ *     })
+ *
+ *     routes.get("/callback", async (c) => {
+ *       // Handle callback and extract user data
+ *       const userData = await processCallback(c)
+ *       return await ctx.success(c, userData)
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * ## Using Providers
+ *
+ * ```ts
+ * export default issuer({
+ *   providers: {
+ *     github: GithubProvider({ ... }),
+ *     google: GoogleProvider({ ... })
+ *   }
+ * })
+ * ```
+ */
+/**
+ * Router instance used for provider route definitions.
+ * Providers use this to register their authorization and callback endpoints.
+ */
+type ProviderRoute = Router;
+/**
+ * Authentication provider interface that handles OAuth flows.
+ * Each provider implements authentication with a specific service (GitHub, Google, etc.).
+ *
+ * @template Properties - Type of user data returned by successful authentication
+ */
+interface Provider<Properties = Record<string, unknown>> {
+  /**
+   * Unique identifier for this provider type.
+   * Used in URLs and provider selection UI.
+   *
+   * @example "github", "google", "steam"
+   */
+  readonly type: string;
+  /**
+   * Initializes the provider by registering required routes.
+   * Called during issuer setup to configure authorization and callback endpoints.
+   *
+   * @param route - Router instance for registering provider endpoints
+   * @param options - Provider utilities and configuration
+   *
+   * @example
+   * ```ts
+   * init(routes, ctx) {
+   *   routes.get("/authorize", async (c) => {
+   *     // Redirect to OAuth provider
+   *     return c.redirect(buildAuthUrl())
+   *   })
+   *
+   *   routes.get("/callback", async (c) => {
+   *     // Process callback and return user data
+   *     const userData = await handleCallback(c)
+   *     return await ctx.success(c, userData)
+   *   })
+   * }
+   * ```
+   */
+  init: (route: ProviderRoute, options: ProviderOptions<Properties>) => void;
+}
+/**
+ * Utilities and callbacks provided to providers during initialization.
+ * Contains methods for state management, user flow completion, and storage access.
+ *
+ * @template Properties - Type of user data handled by the provider
+ */
+interface ProviderOptions<Properties> {
+  /**
+   * Name of the provider instance as configured in the issuer.
+   * Corresponds to the key used in the providers object.
+   */
+  readonly name: string;
+  /**
+   * Completes the authentication flow with user data.
+   * Called when the provider successfully authenticates a user.
+   *
+   * @param ctx - Router request context
+   * @param properties - User data extracted from the provider
+   * @param opts - Optional utilities for session management
+   * @returns Response that completes the OAuth flow
+   *
+   * @example
+   * ```ts
+   * const userData = { userId: "123", email: "user@example.com" }
+   * return await ctx.success(c, userData)
+   * ```
+   */
+  success: (ctx: RouterContext, properties: Properties, opts?: {
+    /** Function to invalidate existing user sessions */
+    readonly invalidate?: (subject: string) => Promise<void>;
+  }) => Promise<Response>;
+  /**
+   * Forwards a response through the provider context.
+   * Used for redirects and custom responses within the OAuth flow.
+   *
+   * @param ctx - Router request context
+   * @param response - Response to forward
+   * @returns Forwarded response
+   */
+  forward: (ctx: RouterContext, response: Response) => Response;
+  /**
+   * Stores a temporary value with expiration for the current session.
+   * Useful for storing OAuth state, PKCE verifiers, and other temporary data.
+   *
+   * @param ctx - Router request context
+   * @param key - Storage key identifier
+   * @param maxAge - TTL in seconds
+   * @param value - Value to store
+   *
+   * @example
+   * ```ts
+   * // Store OAuth state for 10 minutes
+   * await ctx.set(c, "oauth_state", 600, { state, redirectUri })
+   * ```
+   */
+  set: <T>(ctx: RouterContext, key: string, maxAge: number, value: T) => Promise<void>;
+  /**
+   * Retrieves a previously stored temporary value.
+   *
+   * @param ctx - Router request context
+   * @param key - Storage key identifier
+   * @returns Promise resolving to the stored value or undefined if not found/expired
+   *
+   * @example
+   * ```ts
+   * const oauthState = await ctx.get<OAuthState>(c, "oauth_state")
+   * if (!oauthState) {
+   *   throw new Error("OAuth state expired")
+   * }
+   * ```
+   */
+  get: <T>(ctx: RouterContext, key: string) => Promise<T | undefined>;
+  /**
+   * Removes a stored temporary value.
+   *
+   * @param ctx - Router request context
+   * @param key - Storage key identifier
+   *
+   * @example
+   * ```ts
+   * // Clean up OAuth state after use
+   * await ctx.unset(c, "oauth_state")
+   * ```
+   */
+  unset: (ctx: RouterContext, key: string) => Promise<void>;
+  /**
+   * Invalidates all sessions for a given subject (user).
+   * Forces logout across all devices and applications.
+   *
+   * @param subject - Subject identifier to invalidate
+   *
+   * @example
+   * ```ts
+   * // Force logout on password change
+   * await ctx.invalidate(userId)
+   * ```
+   */
+  invalidate: (subject: string) => Promise<void>;
+  /**
+   * Storage adapter for persistent data operations.
+   * Provides access to the configured storage backend.
+   */
+  readonly storage: StorageAdapter;
+}
+/**
+ * Base error class for provider-related errors.
+ * Extend this class to create specific provider error types.
+ *
+ * @example
+ * ```ts
+ * export class GitHubApiError extends ProviderError {
+ *   constructor(message: string, public readonly statusCode: number) {
+ *     super(message)
+ *   }
+ * }
+ * ```
+ */
+declare class ProviderError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a provider encounters an unknown or unexpected error.
+ * Used as a fallback for unhandled error conditions.
+ *
+ * @example
+ * ```ts
+ * catch (error) {
+ *   if (error instanceof SomeSpecificError) {
+ *     // Handle specific error
+ *   } else {
+ *     throw new ProviderUnknownError(`Unexpected error: ${error}`)
+ *   }
+ * }
+ * ```
+ */
+declare class ProviderUnknownError extends ProviderError {
+  constructor(message?: string);
+}
+//#endregion
 export { Provider, ProviderError, ProviderOptions, ProviderRoute, ProviderUnknownError };

package/dist/random.js

@@ -1,3 +1,87 @@
-import { generateSecureToken, generateUnbiasedDigits, timingSafeCompare } from "./random-SXMYlaVr.js";
+import { timingSafeEqual } from "node:crypto";
 
+//#region src/random.ts
+/**
+* Cryptographic utilities for secure random generation and comparison operations.
+* These functions are designed to prevent timing attacks and provide unbiased randomness.
+*/
+/**
+* Generates a cryptographically secure token with enhanced entropy.
+* Uses Web Crypto API and provides 256 bits of entropy
+*
+* @param length - Length of random data in bytes (default: 32 for 256-bit security)
+* @returns Base64url-encoded secure token
+*
+* @example
+* ```ts
+* const authCode = generateSecureToken()
+* // Returns: "7B8kJ9mN3pQ2rS5tU8vW0xY1zA3bC6dE9fG2hI5jK8lM" (example)
+*
+* const refreshToken = generateSecureToken(24) // 192-bit token
+* // Returns: "4A7bC9dF2gH5iJ8kL1mN4pQ7rS0tU" (example)
+* ```
+*/
+const generateSecureToken = (length = 32) => {
+	if (length <= 0 || !Number.isInteger(length)) throw new RangeError("Token length must be a positive integer");
+	const randomBytes$1 = new Uint8Array(length);
+	crypto.getRandomValues(randomBytes$1);
+	const base64 = btoa(String.fromCharCode.apply(null, Array.from(randomBytes$1)));
+	return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+};
+/**
+* Generates a cryptographically secure string of random digits without modulo bias.
+* Uses rejection sampling to ensure each digit (0-9) has an equal probability of being selected.
+*
+* @param length - Number of digits to generate (must be positive)
+* @returns String containing exactly the specified number of random digits
+*
+* @example
+* ```ts
+* const pinCode = generateUnbiasedDigits(6)
+* // Returns: "492847" (example - actual result is random)
+*
+* const shortCode = generateUnbiasedDigits(4)
+* // Returns: "7291" (example - actual result is random)
+* ```
+*
+* @throws {RangeError} If length is not a positive number
+*/
+const generateUnbiasedDigits = (length) => {
+	if (length <= 0 || !Number.isInteger(length)) throw new RangeError("Length must be a positive integer");
+	const result = [];
+	while (result.length < length) {
+		const buffer = crypto.getRandomValues(new Uint8Array(length * 2));
+		for (const byte of buffer) if (byte < 250 && result.length < length) result.push(byte % 10);
+	}
+	return result.join("");
+};
+/**
+* Performs a timing-safe comparison of two strings to prevent timing attacks.
+* Always takes the same amount of time regardless of where the strings differ,
+* making it safe for comparing sensitive values like tokens or passwords.
+*
+* @param a - First string to compare
+* @param b - Second string to compare
+* @returns True if strings are identical, false otherwise
+*
+* @example
+* ```ts
+* // Safe for comparing sensitive values
+* const isValidToken = timingSafeCompare(userToken, expectedToken)
+*
+* // Safe for password verification
+* const isValidPassword = timingSafeCompare(hashedInput, storedHash)
+*
+* // Returns false for different types or lengths
+* timingSafeCompare("abc", 123 as any) // false
+* timingSafeCompare("abc", "abcd") // false
+* ```
+*/
+const timingSafeCompare = (a, b) => {
+	if (typeof a !== "string" || typeof b !== "string") return false;
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+};
+
+//#endregion
 export { generateSecureToken, generateUnbiasedDigits, timingSafeCompare };

package/dist/storage/memory.d.ts

@@ -1,4 +1,4 @@
-import { StorageAdapter } from "../storage-CxKerLlc.js";
+import { StorageAdapter } from "./storage.js";
 
 //#region src/storage/memory.d.ts
 

package/dist/storage/memory.js

@@ -1,4 +1,4 @@
-import { joinKey, splitKey } from "../storage-BEaqEPNQ.js";
+import { joinKey, splitKey } from "./storage.js";
 import { existsSync, readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 

package/dist/storage/storage.d.ts

@@ -1,2 +1,162 @@
-import { Storage, StorageAdapter, joinKey, splitKey } from "../storage-CxKerLlc.js";
+//#region src/storage/storage.d.ts
+/**
+ * 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.
+ */
+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.
+ *
+ * @param key - Array of key segments to join
+ * @returns Single string representing the full key path
+ *
+ * @example
+ * ```ts
+ * joinKey(['user', 'session', '123'])
+ * // Returns: "user\x1fsession\x1f123"
+ * ```
+ */
+declare const joinKey: (key: string[]) => string;
+/**
+ * Splits a joined key string back into its component segments.
+ *
+ * @param key - Joined key string to split
+ * @returns Array of individual key segments
+ *
+ * @example
+ * ```ts
+ * splitKey("user\x1fsession\x1f123")
+ * // Returns: ['user', 'session', '123']
+ * ```
+ */
+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 conversion and key sanitization.
+ */
+declare const Storage: {
+  /**
+   * Encodes key segments by removing any separator characters to prevent conflicts.
+   * Ensures storage keys don't contain characters that could break key parsing.
+   *
+   * @param key - Array of key segments to encode
+   * @returns Array of sanitized key segments
+   *
+   * @example
+   * ```ts
+   * Storage.encode(['user', 'data\x1fwith\x1fseparators'])
+   * // Returns: ['user', 'datawithseparators']
+   * ```
+   */
+  readonly encode: (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.
+   *
+   * @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
+   *
+   * @example
+   * ```ts
+   * // Store with 1 hour TTL
+   * await Storage.set(adapter, ['sessions', sessionId], sessionData, 3600)
+   *
+   * // Store permanently
+   * 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]>;
+};
+//#endregion
 export { Storage, StorageAdapter, joinKey, splitKey };

package/dist/storage/storage.js

@@ -1,3 +1,62 @@
-import { Storage, joinKey, splitKey } from "../storage-BEaqEPNQ.js";
+//#region src/storage/storage.ts
+/**
+* ASCII unit separator character used to join key segments.
+* Using a control character ensures it won't conflict with user data.
+*/
+const SEPARATOR = String.fromCharCode(31);
+/**
+* Joins an array of key segments into a single string using the separator.
+*
+* @param key - Array of key segments to join
+* @returns Single string representing the full key path
+*
+* @example
+* ```ts
+* joinKey(['user', 'session', '123'])
+* // Returns: "user\x1fsession\x1f123"
+* ```
+*/
+const joinKey = (key) => {
+	return key.join(SEPARATOR);
+};
+/**
+* Splits a joined key string back into its component segments.
+*
+* @param key - Joined key string to split
+* @returns Array of individual key segments
+*
+* @example
+* ```ts
+* splitKey("user\x1fsession\x1f123")
+* // Returns: ['user', 'session', '123']
+* ```
+*/
+const splitKey = (key) => {
+	return key.split(SEPARATOR);
+};
+/**
+* High-level storage operations with key encoding and type safety.
+* Provides a convenient interface over storage adapters with additional features
+* like TTL conversion and key sanitization.
+*/
+const Storage = {
+	encode: (key) => {
+		return key.map((segment) => segment.replaceAll(SEPARATOR, ""));
+	},
+	get: (adapter, key) => {
+		return adapter.get(Storage.encode(key));
+	},
+	set: (adapter, key, value, ttlSeconds) => {
+		const expiry = ttlSeconds ? new Date(Date.now() + ttlSeconds * 1e3) : void 0;
+		return adapter.set(Storage.encode(key), value, expiry);
+	},
+	remove: (adapter, key) => {
+		return adapter.remove(Storage.encode(key));
+	},
+	scan: (adapter, prefix) => {
+		return adapter.scan(Storage.encode(prefix));
+	}
+};
 
+//#endregion
 export { Storage, joinKey, splitKey };

package/dist/storage/turso.d.ts

@@ -1,4 +1,4 @@
-import { StorageAdapter } from "../storage-CxKerLlc.js";
+import { StorageAdapter } from "./storage.js";
 import { Client } from "@libsql/client";
 
 //#region src/storage/turso.d.ts

package/dist/storage/turso.js

@@ -1,4 +1,4 @@
-import { joinKey, splitKey } from "../storage-BEaqEPNQ.js";
+import { joinKey, splitKey } from "./storage.js";
 
 //#region src/storage/turso.ts
 /**

package/dist/storage/unstorage.d.ts

@@ -1,4 +1,4 @@
-import { StorageAdapter } from "../storage-CxKerLlc.js";
+import { StorageAdapter } from "./storage.js";
 import { Driver } from "unstorage";
 
 //#region src/storage/unstorage.d.ts

package/dist/storage/unstorage.js

@@ -1,4 +1,4 @@
-import { joinKey, splitKey } from "../storage-BEaqEPNQ.js";
+import { joinKey, splitKey } from "./storage.js";
 import { createStorage } from "unstorage";
 
 //#region src/storage/unstorage.ts

package/dist/subject.d.ts

@@ -1,3 +1,62 @@
-import "./util-DbSKG1Xm.js";
-import { SubjectPayload, SubjectSchema, createSubjects } from "./subject-DMIMVtaT.js";
+import { Prettify } from "./util.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/subject.d.ts
+
+/**
+ * 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() })
+ * }
+ * ```
+ */
+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
+ */
+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()
+ *   })
+ * })
+ * ```
+ */
+declare const createSubjects: <Schema extends SubjectSchema>(types: Schema) => Schema;
+//#endregion
 export { SubjectPayload, SubjectSchema, createSubjects };