@draftlab/auth 0.4.1 → 0.6.0

package/dist/provider/{totp.js → totp.mjs}

@@ -1,8 +1,50 @@
-import { generateSecureToken } from "../random.js";
-import { Storage } from "../storage/storage.js";
+import { generateSecureToken } from "../random.mjs";
+import { Storage } from "../storage/storage.mjs";
 import { Secret, TOTP } from "otpauth";
 
 //#region src/provider/totp.ts
+/**
+* Configures a provider that supports TOTP (Time-based One-Time Password) authentication.
+*
+* ```ts
+* import { TOTPProvider } from "@draftlab/auth/provider/totp"
+*
+* export default issuer({
+*   providers: {
+*     totp: TOTPProvider({
+*       issuer: "My Application",
+*       setup: async (req, qrCode, secret, backupCodes) => {
+*         return new Response(renderSetupPage(qrCode, secret, backupCodes))
+*       },
+*       verify: async (req, error) => {
+*         return new Response(renderVerifyPage(error))
+*       },
+*       recovery: async (req, error) => {
+*         return new Response(renderRecoveryPage(error))
+*       }
+*     })
+*   },
+*   // ...
+* })
+* ```
+*
+* TOTPProvider implements Time-based One-Time Password authentication.
+* It provides secure TOTP token generation and verification with backup recovery codes.
+*
+* The provider requires configuration of:
+* - Issuer name for authenticator apps
+* - UI handlers for setup, verification, and recovery flows
+* - Optional TOTP parameters (algorithm, digits, period)
+*
+* It automatically manages:
+* - Secure secret generation
+* - QR code URL generation for authenticator apps
+* - Token validation with timing attack protection
+* - Recovery codes generation and one-time usage
+* - Storage of TOTP configuration and backup codes
+*
+* @packageDocumentation
+*/
 const totpKey = (userId) => [
 	"totp",
 	"user",
@@ -72,16 +114,14 @@ const TOTPProvider = (config) => {
 					const secret = new Secret({ size: 20 });
 					const label = config.generateLabel ? await config.generateLabel(email) : email;
 					const backupCodes = generateBackupCodes(backupCodesCount);
-					const totp$1 = createTOTPInstance(secret.base32, label);
-					const qrCodeUrl$1 = totp$1.toString();
-					const totpData$1 = {
+					const qrCodeUrl$1 = createTOTPInstance(secret.base32, label).toString();
+					await saveTOTPData(email, {
 						secret: secret.base32,
 						enabled: false,
 						backupCodes,
 						createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 						label
-					};
-					await saveTOTPData(email, totpData$1);
+					});
 					return ctx.forward(c, await config.register(c.request, qrCodeUrl$1, secret.base32, backupCodes, void 0, email));
 				}
 				const token = formData.get("token")?.toString();
@@ -89,11 +129,10 @@ const TOTPProvider = (config) => {
 				const totpData = await getTOTPData(email);
 				if (!totpData) return ctx.forward(c, await config.register(c.request, "", "", [], "TOTP setup session not found"));
 				const totp = createTOTPInstance(totpData.secret, totpData.label || email);
-				const delta = totp.validate({
+				if (totp.validate({
 					token,
 					window
-				});
-				if (delta !== null) {
+				}) !== null) {
 					totpData.enabled = true;
 					await saveTOTPData(email, totpData);
 					return ctx.success(c, {
@@ -114,12 +153,10 @@ const TOTPProvider = (config) => {
 				if (!email || !token) return ctx.forward(c, await config.authorize(c.request, "Email and verification code are required"));
 				const totpData = await getTOTPData(email);
 				if (!totpData || !totpData.enabled) return ctx.forward(c, await config.authorize(c.request, "TOTP is not set up for this email"));
-				const totp = createTOTPInstance(totpData.secret, totpData.label || email);
-				const delta = totp.validate({
+				if (createTOTPInstance(totpData.secret, totpData.label || email).validate({
 					token,
 					window
-				});
-				if (delta !== null) return ctx.success(c, {
+				}) !== null) return ctx.success(c, {
 					email,
 					method: "totp"
 				});

package/dist/provider/twitch.d.mts

@@ -0,0 +1,102 @@
+import { Provider } from "./provider.mjs";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
+
+//#region src/provider/twitch.d.ts
+
+/**
+ * Configuration options for Twitch OAuth 2.0 provider.
+ * Extends the base OAuth 2.0 configuration with Twitch-specific documentation.
+ */
+interface TwitchConfig extends Oauth2WrappedConfig {
+  /**
+   * Twitch application client ID.
+   * Get this from your Twitch Console at https://dev.twitch.tv/console
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "abcdef123456"
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * Twitch application client secret.
+   * Keep this secure and never expose it to client-side code.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.TWITCH_CLIENT_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * Twitch OAuth scopes to request access for.
+   * Determines what data and actions your app can access.
+   *
+   * @example
+   * ```ts
+   * {
+   *   scopes: [
+   *     "user:read:email",           // Access user email
+   *     "user:read:subscriptions"    // View subscriptions
+   *   ]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+}
+/**
+ * Creates a Twitch OAuth 2.0 authentication provider.
+ * Allows users to authenticate using their Twitch accounts.
+ *
+ * @param config - Twitch OAuth 2.0 configuration
+ * @returns OAuth 2.0 provider configured for Twitch
+ *
+ * @example
+ * ```ts
+ * // Basic Twitch authentication
+ * const basicTwitch = TwitchProvider({
+ *   clientID: process.env.TWITCH_CLIENT_ID,
+ *   clientSecret: process.env.TWITCH_CLIENT_SECRET
+ * })
+ *
+ * // Twitch with email scope
+ * const twitchWithEmail = TwitchProvider({
+ *   clientID: process.env.TWITCH_CLIENT_ID,
+ *   clientSecret: process.env.TWITCH_CLIENT_SECRET,
+ *   scopes: ["user:read:email"]
+ * })
+ *
+ * // Using the access token to fetch user data
+ * export default issuer({
+ *   providers: { twitch: twitchWithEmail },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "twitch") {
+ *       const token = value.tokenset.access
+ *
+ *       const userRes = await fetch('https://api.twitch.tv/helix/users', {
+ *         headers: {
+ *           'Authorization': `Bearer ${token}`,
+ *           'Client-ID': process.env.TWITCH_CLIENT_ID
+ *         }
+ *       })
+ *       const { data } = await userRes.json()
+ *       const user = data[0]
+ *
+ *       return ctx.subject("user", {
+ *         twitchId: user.id,
+ *         login: user.login,
+ *         email: user.email,
+ *         displayName: user.display_name
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare const TwitchProvider: (config: TwitchConfig) => Provider<Oauth2UserData>;
+//#endregion
+export { TwitchConfig, TwitchProvider };

package/dist/provider/twitch.mjs

@@ -0,0 +1,118 @@
+import { Oauth2Provider } from "./oauth2.mjs";
+
+//#region src/provider/twitch.ts
+/**
+* Twitch authentication provider for Draft Auth.
+* Implements OAuth 2.0 flow for authenticating users with their Twitch accounts.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { TwitchProvider } from "@draftlab/auth/provider/twitch"
+*
+* export default issuer({
+*   providers: {
+*     twitch: TwitchProvider({
+*       clientID: process.env.TWITCH_CLIENT_ID,
+*       clientSecret: process.env.TWITCH_CLIENT_SECRET,
+*       scopes: ["user:read:email"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Common Scopes
+*
+* - `user:read:email` - Access user's email address
+* - `user:read:subscriptions` - View user subscriptions
+* - `user:read:follows` - View user's follows
+* - `channel:read:subscriptions` - View channel subscribers
+* - `analytics:read:games` - View game analytics
+* - `bits:read` - View bits information
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "twitch") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user information
+*     const userResponse = await fetch('https://api.twitch.tv/helix/users', {
+*       headers: {
+*         'Authorization': `Bearer ${accessToken}`,
+*         'Client-ID': process.env.TWITCH_CLIENT_ID
+*       }
+*     })
+*     const { data } = await userResponse.json()
+*     const user = data[0]
+*
+*     // User info available: id, login, display_name, email, profile_image_url
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Creates a Twitch OAuth 2.0 authentication provider.
+* Allows users to authenticate using their Twitch accounts.
+*
+* @param config - Twitch OAuth 2.0 configuration
+* @returns OAuth 2.0 provider configured for Twitch
+*
+* @example
+* ```ts
+* // Basic Twitch authentication
+* const basicTwitch = TwitchProvider({
+*   clientID: process.env.TWITCH_CLIENT_ID,
+*   clientSecret: process.env.TWITCH_CLIENT_SECRET
+* })
+*
+* // Twitch with email scope
+* const twitchWithEmail = TwitchProvider({
+*   clientID: process.env.TWITCH_CLIENT_ID,
+*   clientSecret: process.env.TWITCH_CLIENT_SECRET,
+*   scopes: ["user:read:email"]
+* })
+*
+* // Using the access token to fetch user data
+* export default issuer({
+*   providers: { twitch: twitchWithEmail },
+*   success: async (ctx, value) => {
+*     if (value.provider === "twitch") {
+*       const token = value.tokenset.access
+*
+*       const userRes = await fetch('https://api.twitch.tv/helix/users', {
+*         headers: {
+*           'Authorization': `Bearer ${token}`,
+*           'Client-ID': process.env.TWITCH_CLIENT_ID
+*         }
+*       })
+*       const { data } = await userRes.json()
+*       const user = data[0]
+*
+*       return ctx.subject("user", {
+*         twitchId: user.id,
+*         login: user.login,
+*         email: user.email,
+*         displayName: user.display_name
+*       })
+*     }
+*   }
+* })
+* ```
+*/
+const TwitchProvider = (config) => {
+	return Oauth2Provider({
+		...config,
+		type: "twitch",
+		endpoint: {
+			authorization: "https://id.twitch.tv/oauth2/authorize",
+			token: "https://id.twitch.tv/oauth2/token"
+		}
+	});
+};
+
+//#endregion
+export { TwitchProvider };

package/dist/{random.js → random.mjs}

@@ -25,8 +25,7 @@ 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, "");
+	return btoa(String.fromCharCode.apply(null, Array.from(randomBytes$1))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 };
 /**
 * Generates a cryptographically secure string of random digits without modulo bias.

package/dist/revocation.d.mts

@@ -0,0 +1,55 @@
+import { StorageAdapter } from "./storage/storage.mjs";
+
+//#region src/revocation.d.ts
+
+/**
+ * Data stored for a revoked token.
+ * Tracks when the token was revoked and when it naturally expires.
+ */
+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.
+ */
+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>;
+};
+//#endregion
+export { Revocation, RevocationRecord };

package/dist/revocation.mjs

@@ -0,0 +1,63 @@
+import { Storage } from "./storage/storage.mjs";
+import { createHash } from "node:crypto";
+
+//#region src/revocation.ts
+/**
+* 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
+*/
+/**
+* Hashes a token for storage.
+* Uses SHA-256 to reduce storage size and prevent exposure of full token value.
+*
+* @param token - The token to hash
+* @returns SHA-256 hash of the token
+*
+* @internal
+*/
+const hashToken = (token) => {
+	return createHash("sha256").update(token).digest("hex");
+};
+/**
+* Token revocation manager.
+* Provides methods to revoke tokens and check if a token has been revoked.
+*/
+const Revocation = {
+	revoke: async (storage, token, expiresAt) => {
+		const key = ["revocation:token", hashToken(token)];
+		const record = {
+			revokedAt: Date.now(),
+			expiresAt
+		};
+		const ttlSeconds = Math.ceil((expiresAt - Date.now()) / 1e3);
+		await Storage.set(storage, key, record, Math.max(1, ttlSeconds));
+	},
+	isRevoked: async (storage, token) => {
+		const key = ["revocation:token", hashToken(token)];
+		return !!await Storage.get(storage, key);
+	}
+};
+
+//#endregion
+export { Revocation };

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

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

package/dist/storage/{memory.js → memory.mjs}

@@ -1,4 +1,4 @@
-import { joinKey, splitKey } from "./storage.js";
+import { joinKey, splitKey } from "./storage.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 
@@ -79,8 +79,7 @@ const MemoryStorage = (options) => {
 	};
 	return {
 		async get(key) {
-			const searchKey = joinKey(key);
-			const match = search(searchKey);
+			const match = search(joinKey(key));
 			if (!match.found) return;
 			const storeEntry = store[match.index];
 			if (!storeEntry) return;
@@ -104,8 +103,7 @@ const MemoryStorage = (options) => {
 			await save();
 		},
 		async remove(key) {
-			const searchKey = joinKey(key);
-			const match = search(searchKey);
+			const match = search(joinKey(key));
 			if (match.found) {
 				store.splice(match.index, 1);
 				await save();

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

@@ -42,50 +42,64 @@ interface StorageAdapter {
 }
 /**
  * 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', 'session', '123'])
- * // Returns: "user\x1fsession\x1f123"
+ * joinKey(['user', 'data\x1fwith\x1fseparators'])
+ * // Returns: "user\x1fdata\\x1fwith\\x1fseparators"
  * ```
  */
 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\x1fsession\x1f123")
- * // Returns: ['user', 'session', '123']
+ * splitKey("user\x1fdata\\x1fwith\\x1fseparators")
+ * // Returns: ['user', 'data\x1fwith\x1fseparators']
  * ```
  */
 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.
+ * like TTL validation and secure key encoding to prevent collisions.
  */
 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.
+   * 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 sanitized key segments
+   * @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', 'datawithseparators']
+   * // 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.
    *
@@ -110,6 +124,7 @@ declare const Storage: {
   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
@@ -117,12 +132,14 @@ declare const Storage: {
    * @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
+   * // Store permanently (no expiration)
    * await Storage.set(adapter, ['users', userId], userData)
    * ```
    */

package/dist/storage/storage.mjs

@@ -0,0 +1,104 @@
+//#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);
+/**
+* Escape character used to escape SEPARATOR characters in key segments.
+* Uses backslash as the escape character, which is then itself escaped when appearing.
+*/
+const ESCAPE = "\\";
+/**
+* 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"
+* ```
+*/
+const joinKey = (key) => {
+	return key.join(SEPARATOR);
+};
+/**
+* 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']
+* ```
+*/
+const splitKey = (key) => {
+	return key.split(SEPARATOR);
+};
+/**
+* Encodes a single key segment by escaping special characters.
+* Prevents collisions by properly escaping separator and escape characters.
+*
+* @param segment - The key segment to encode
+* @returns Encoded segment with special characters escaped
+* @throws {Error} If segment is empty or whitespace-only
+*
+* @internal
+*/
+const encodeSegment = (segment) => {
+	if (!segment || !segment.trim()) throw new Error(`Storage key segment cannot be empty or whitespace-only: "${segment}"`);
+	return segment.replaceAll(ESCAPE, ESCAPE + ESCAPE).replaceAll(SEPARATOR, ESCAPE + SEPARATOR);
+};
+/**
+* Decodes a key segment by unescaping special characters.
+* Reverse of encodeSegment operation.
+*
+* @param segment - The encoded segment to decode
+* @returns Decoded segment with special characters restored
+*
+* @internal
+*/
+const decodeSegment = (segment) => {
+	return segment.replaceAll(ESCAPE + SEPARATOR, SEPARATOR).replaceAll(ESCAPE + ESCAPE, ESCAPE);
+};
+/**
+* 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.
+*/
+const Storage = {
+	encode: (key) => {
+		return key.map(encodeSegment);
+	},
+	decode: (key) => {
+		return key.map(decodeSegment);
+	},
+	get: (adapter, key) => {
+		return adapter.get(Storage.encode(key));
+	},
+	set: (adapter, key, value, ttlSeconds) => {
+		if (ttlSeconds !== void 0 && ttlSeconds !== null) {
+			if (!Number.isInteger(ttlSeconds)) throw new RangeError(`Storage TTL must be an integer in seconds, received ${typeof ttlSeconds}`);
+			if (ttlSeconds <= 0) throw new RangeError(`Storage TTL must be positive, received ${ttlSeconds}`);
+			const maxTtlSeconds = 3600 * 24 * 365 * 10;
+			if (ttlSeconds > maxTtlSeconds) throw new RangeError(`Storage TTL exceeds maximum (${maxTtlSeconds}s = 10 years), received ${ttlSeconds}s`);
+		}
+		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 → turso.d.mts}

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