@draftlab/auth 0.15.0 → 0.16.0

package/dist/error.mjs

@@ -1,237 +0,0 @@
-//#region src/error.ts
-/**
-* Base OAuth error class for handling standard OAuth error responses.
-* Contains both the error code and human-readable description.
-*/
-var OauthError = class extends Error {
-	/** The OAuth error code as defined in the specification */
-	error;
-	/** Human-readable description of the error */
-	description;
-	/**
-	* Creates a new OAuth error with the specified error code and description.
-	*
-	* @param error - The OAuth error type
-	* @param description - Human-readable error description
-	*
-	* @example
-	* ```ts
-	* throw new OauthError("invalid_grant", "Authorization code has expired")
-	* ```
-	*/
-	constructor(error, description) {
-		super(`${error} - ${description}`);
-		this.name = "OauthError";
-		this.error = error;
-		this.description = description;
-	}
-	/**
-	* Converts the error to a standard OAuth JSON response format.
-	*
-	* @returns Object with error and error_description fields
-	*
-	* @example
-	* ```ts
-	* const oauthError = new OauthError("invalid_request", "Missing parameter")
-	* return c.json(oauthError.toJSON(), 400)
-	* ```
-	*/
-	toJSON() {
-		return {
-			error: this.error,
-			error_description: this.description
-		};
-	}
-};
-/**
-* Error thrown when a provider parameter is missing from the authorization request.
-* Occurs when multiple providers are configured but no specific provider is selected.
-*/
-var MissingProviderError = class extends OauthError {
-	/**
-	* Creates a missing provider error.
-	* Thrown when the provider query parameter is required but not provided.
-	*/
-	constructor() {
-		super("invalid_request", "Must specify `provider` query parameter if `select` callback on issuer is not specified");
-		this.name = "MissingProviderError";
-	}
-};
-/**
-* Error thrown when a required parameter is missing from a request.
-* Used for validating OAuth request parameters.
-*/
-var MissingParameterError = class extends OauthError {
-	/** The name of the missing parameter */
-	parameter;
-	/**
-	* Creates a missing parameter error.
-	*
-	* @param parameter - The name of the missing parameter
-	*
-	* @example
-	* ```ts
-	* throw new MissingParameterError("client_id")
-	* ```
-	*/
-	constructor(parameter) {
-		super("invalid_request", `Missing parameter: ${parameter}`);
-		this.name = "MissingParameterError";
-		this.parameter = parameter;
-	}
-};
-/**
-* Error thrown when a client is not authorized to use a specific redirect URI.
-* Prevents unauthorized clients from hijacking authorization codes.
-*/
-var UnauthorizedClientError = class extends OauthError {
-	/** The client ID that attempted unauthorized access */
-	clientID;
-	/**
-	* Creates an unauthorized client error.
-	*
-	* @param clientID - The client ID attempting unauthorized access
-	* @param redirectURI - The unauthorized redirect URI
-	*
-	* @example
-	* ```ts
-	* throw new UnauthorizedClientError("malicious-client", "https://evil.com/callback")
-	* ```
-	*/
-	constructor(clientID, redirectURI) {
-		super("unauthorized_client", `Client ${clientID} is not authorized to use this redirect_uri: ${redirectURI}`);
-		this.name = "UnauthorizedClientError";
-		this.clientID = clientID;
-	}
-};
-/**
-* Error thrown when the authentication flow is in an unknown or invalid state.
-*
-* ## Common Causes
-* - Session cookies have expired during the authentication flow
-* - User switched browsers or devices mid-flow
-* - Authentication state was manually tampered with
-* - Server session storage was cleared
-*
-* @example
-* ```ts
-* // In provider callback handling
-* const state = await getAuthState(request)
-* if (!state) {
-*   throw new UnknownStateError()
-* }
-* ```
-*/
-var UnknownStateError = class extends Error {
-	/**
-	* Creates an unknown state error.
-	* Indicates that the authentication flow cannot continue due to missing state.
-	*/
-	constructor() {
-		super("The browser was in an unknown state. This could be because certain cookies expired or the browser was switched in the middle of an authentication flow.");
-		this.name = "UnknownStateError";
-	}
-};
-/**
-* Error thrown when a subject (user identifier) is invalid or malformed.
-* Used during token verification and subject validation.
-*
-* @example
-* ```ts
-* // During token verification
-* const subject = extractSubject(token)
-* if (!isValidSubject(subject)) {
-*   throw new InvalidSubjectError()
-* }
-* ```
-*/
-var InvalidSubjectError = class extends Error {
-	/**
-	* Creates an invalid subject error.
-	*/
-	constructor() {
-		super("Invalid subject");
-		this.name = "InvalidSubjectError";
-	}
-};
-/**
-* Error thrown when a refresh token is invalid, expired, or revoked.
-* Occurs during token refresh operations.
-*
-* @example
-* ```ts
-* // During token refresh
-* try {
-*   const newTokens = await client.refresh(refreshToken)
-* } catch (error) {
-*   if (error instanceof InvalidRefreshTokenError) {
-*     // Redirect user to login again
-*     redirectToLogin()
-*   }
-* }
-* ```
-*/
-var InvalidRefreshTokenError = class extends Error {
-	/**
-	* Creates an invalid refresh token error.
-	*/
-	constructor() {
-		super("Invalid refresh token");
-		this.name = "InvalidRefreshTokenError";
-	}
-};
-/**
-* Error thrown when an access token is invalid, expired, or malformed.
-* Occurs during token verification and API requests.
-*
-* @example
-* ```ts
-* // During API request
-* try {
-*   const user = await api.getUser(accessToken)
-* } catch (error) {
-*   if (error instanceof InvalidAccessTokenError) {
-*     // Try to refresh the token
-*     await refreshAccessToken()
-*   }
-* }
-* ```
-*/
-var InvalidAccessTokenError = class extends Error {
-	/**
-	* Creates an invalid access token error.
-	*/
-	constructor() {
-		super("Invalid access token");
-		this.name = "InvalidAccessTokenError";
-	}
-};
-/**
-* Error thrown when an authorization code is invalid, expired, or already used.
-* Occurs during the token exchange step of the OAuth flow.
-*
-* @example
-* ```ts
-* // During authorization code exchange
-* try {
-*   const tokens = await client.exchange(code, redirectUri)
-* } catch (error) {
-*   if (error instanceof InvalidAuthorizationCodeError) {
-*     // Code may have expired or been used already
-*     redirectToAuthorize()
-*   }
-* }
-* ```
-*/
-var InvalidAuthorizationCodeError = class extends Error {
-	/**
-	* Creates an invalid authorization code error.
-	*/
-	constructor() {
-		super("Invalid authorization code");
-		this.name = "InvalidAuthorizationCodeError";
-	}
-};
-
-//#endregion
-export { InvalidAccessTokenError, InvalidAuthorizationCodeError, InvalidRefreshTokenError, InvalidSubjectError, MissingParameterError, MissingProviderError, OauthError, UnauthorizedClientError, UnknownStateError };

package/dist/index.d.mts

@@ -1,2 +0,0 @@
-import { issuer } from "./core.mjs";
-export { issuer };

package/dist/index.mjs

@@ -1,3 +0,0 @@
-import { issuer } from "./core.mjs";
-
-export { issuer };

package/dist/keys.mjs

@@ -1,146 +0,0 @@
-import { Mutex } from "./mutex.mjs";
-import { generateSecureToken } from "./random.mjs";
-import { Storage } from "./storage/storage.mjs";
-import { exportJWK, exportPKCS8, exportSPKI, generateKeyPair, importPKCS8, importSPKI } from "jose";
-
-//#region src/keys.ts
-/**
-* Cryptographic key management for JWT signing and encryption operations.
-* Handles automatic key generation, rotation, and storage for OAuth operations.
-*/
-/** Elliptic Curve algorithm used for JWT signing operations */
-const signingAlg = "ES256";
-/** RSA algorithm used for token encryption operations */
-const encryptionAlg = "RSA-OAEP-512";
-/** Mutex to prevent concurrent key generation (race condition with eventually consistent storage) */
-const signingKeyMutex = new Mutex();
-const encryptionKeyMutex = new Mutex();
-/**
-* Loads or generates signing keys for JWT operations.
-* Returns existing valid keys, or generates new ones if none are available.
-* Keys are automatically sorted by creation date (newest first).
-*
-* @param storage - Storage adapter for persistent key storage
-* @returns Promise resolving to array of available signing key pairs
-*
-* @example
-* ```ts
-* const keys = await signingKeys(storage)
-* const currentKey = keys[0] // Most recent key
-*
-* // Use for JWT signing
-* const jwt = await new SignJWT(payload)
-*   .setProtectedHeader({ alg: currentKey.alg, kid: currentKey.id })
-*   .sign(currentKey.private)
-* ```
-*/
-const signingKeys = async (storage) => {
-	return signingKeyMutex.runExclusive(async () => {
-		const results = [];
-		const scanner = Storage.scan(storage, ["signing:key"]);
-		for await (const [, value] of scanner) try {
-			const publicKey = await importSPKI(value.publicKey, value.alg, { extractable: true });
-			const privateKey = await importPKCS8(value.privateKey, value.alg);
-			const jwk$1 = await exportJWK(publicKey);
-			jwk$1.kid = value.id;
-			jwk$1.use = "sig";
-			results.push({
-				id: value.id,
-				alg: signingAlg,
-				created: new Date(value.created),
-				expired: value.expired ? new Date(value.expired) : void 0,
-				public: publicKey,
-				private: privateKey,
-				jwk: jwk$1
-			});
-		} catch {}
-		results.sort((a, b) => b.created.getTime() - a.created.getTime());
-		if (results.filter((item) => !item.expired).length) return results;
-		const key = await generateKeyPair(signingAlg, { extractable: true });
-		const serialized = {
-			id: generateSecureToken(16),
-			publicKey: await exportSPKI(key.publicKey),
-			privateKey: await exportPKCS8(key.privateKey),
-			created: Date.now(),
-			alg: signingAlg
-		};
-		await Storage.set(storage, ["signing:key", serialized.id], serialized);
-		const jwk = await exportJWK(key.publicKey);
-		jwk.kid = serialized.id;
-		jwk.use = "sig";
-		return [{
-			id: serialized.id,
-			alg: signingAlg,
-			created: new Date(serialized.created),
-			expired: serialized.expired ? new Date(serialized.expired) : void 0,
-			public: key.publicKey,
-			private: key.privateKey,
-			jwk
-		}, ...results];
-	});
-};
-/**
-* Loads or generates encryption keys for token encryption operations.
-* Returns existing valid keys, or generates new ones if none are available.
-* Keys are automatically sorted by creation date (newest first).
-*
-* @param storage - Storage adapter for persistent key storage
-* @returns Promise resolving to array of available encryption key pairs
-*
-* @example
-* ```ts
-* const keys = await encryptionKeys(storage)
-* const currentKey = keys[0] // Most recent key
-*
-* // Use for token encryption
-* const encrypted = await new EncryptJWT(payload)
-*   .setProtectedHeader({ alg: 'RSA-OAEP-512', enc: 'A256GCM' })
-*   .encrypt(currentKey.public)
-* ```
-*/
-const encryptionKeys = async (storage) => {
-	return encryptionKeyMutex.runExclusive(async () => {
-		const results = [];
-		const scanner = Storage.scan(storage, ["encryption:key"]);
-		for await (const [, value] of scanner) try {
-			const publicKey = await importSPKI(value.publicKey, value.alg, { extractable: true });
-			const privateKey = await importPKCS8(value.privateKey, value.alg);
-			const jwk$1 = await exportJWK(publicKey);
-			jwk$1.kid = value.id;
-			results.push({
-				id: value.id,
-				alg: encryptionAlg,
-				created: new Date(value.created),
-				expired: value.expired ? new Date(value.expired) : void 0,
-				public: publicKey,
-				private: privateKey,
-				jwk: jwk$1
-			});
-		} catch {}
-		results.sort((a, b) => b.created.getTime() - a.created.getTime());
-		if (results.filter((item) => !item.expired).length) return results;
-		const key = await generateKeyPair(encryptionAlg, { extractable: true });
-		const serialized = {
-			id: generateSecureToken(16),
-			publicKey: await exportSPKI(key.publicKey),
-			privateKey: await exportPKCS8(key.privateKey),
-			created: Date.now(),
-			alg: encryptionAlg
-		};
-		await Storage.set(storage, ["encryption:key", serialized.id], serialized);
-		const jwk = await exportJWK(key.publicKey);
-		jwk.kid = serialized.id;
-		return [{
-			id: serialized.id,
-			alg: encryptionAlg,
-			created: new Date(serialized.created),
-			expired: serialized.expired ? new Date(serialized.expired) : void 0,
-			public: key.publicKey,
-			private: key.privateKey,
-			jwk
-		}, ...results];
-	});
-};
-
-//#endregion
-export { encryptionKeys, signingKeys };

package/dist/mutex.d.mts

@@ -1,44 +0,0 @@
-//#region src/mutex.d.ts
-/**
- * A Mutex (mutual exclusion lock) for async functions.
- * It allows only one async task to access a critical section at a time.
- *
- * @example
- * const mutex = new Mutex();
- *
- * async function criticalSection() {
- *   await mutex.acquire();
- *   try {
- *     // This code section cannot be executed simultaneously
- *   } finally {
- *     mutex.release();
- *   }
- * }
- */
-declare class Mutex {
-  private semaphore;
-  /**
-   * Checks if the mutex is currently locked.
-   * @returns True if the mutex is locked, false otherwise.
-   */
-  get isLocked(): boolean;
-  /**
-   * Acquires the mutex, blocking if necessary until it is available.
-   * @returns A promise that resolves when the mutex is acquired.
-   */
-  acquire(): Promise<void>;
-  /**
-   * Releases the mutex, allowing another waiting task to proceed.
-   */
-  release(): void;
-  /**
-   * Runs a function while holding the mutex lock.
-   * Automatically acquires before and releases after the function execution.
-   *
-   * @param fn - The function to execute while holding the lock
-   * @returns The result of the function
-   */
-  runExclusive<T>(fn: () => Promise<T>): Promise<T>;
-}
-//#endregion
-export { Mutex };

package/dist/mutex.mjs

@@ -1,110 +0,0 @@
-//#region src/mutex.ts
-/**
-* A counting semaphore for async functions that manages available permits.
-* Semaphores are mainly used to limit the number of concurrent async tasks.
-*
-* Each `acquire` operation takes a permit or waits until one is available.
-* Each `release` operation adds a permit, potentially allowing a waiting task to proceed.
-*
-* The semaphore ensures fairness by maintaining a FIFO (First In, First Out) order for acquirers.
-*/
-var Semaphore = class {
-	/**
-	* The maximum number of concurrent operations allowed.
-	*/
-	capacity;
-	/**
-	* The number of available permits.
-	*/
-	available;
-	deferredTasks = [];
-	/**
-	* Creates an instance of Semaphore.
-	* @param capacity - The maximum number of concurrent operations allowed.
-	*/
-	constructor(capacity) {
-		this.capacity = capacity;
-		this.available = capacity;
-	}
-	/**
-	* Acquires a semaphore, blocking if necessary until one is available.
-	* @returns A promise that resolves when the semaphore is acquired.
-	*/
-	async acquire() {
-		if (this.available > 0) {
-			this.available--;
-			return;
-		}
-		return new Promise((resolve) => {
-			this.deferredTasks.push(resolve);
-		});
-	}
-	/**
-	* Releases a semaphore, allowing one more operation to proceed.
-	*/
-	release() {
-		const deferredTask = this.deferredTasks.shift();
-		if (deferredTask != null) {
-			deferredTask();
-			return;
-		}
-		if (this.available < this.capacity) this.available++;
-	}
-};
-/**
-* A Mutex (mutual exclusion lock) for async functions.
-* It allows only one async task to access a critical section at a time.
-*
-* @example
-* const mutex = new Mutex();
-*
-* async function criticalSection() {
-*   await mutex.acquire();
-*   try {
-*     // This code section cannot be executed simultaneously
-*   } finally {
-*     mutex.release();
-*   }
-* }
-*/
-var Mutex = class {
-	semaphore = new Semaphore(1);
-	/**
-	* Checks if the mutex is currently locked.
-	* @returns True if the mutex is locked, false otherwise.
-	*/
-	get isLocked() {
-		return this.semaphore.available === 0;
-	}
-	/**
-	* Acquires the mutex, blocking if necessary until it is available.
-	* @returns A promise that resolves when the mutex is acquired.
-	*/
-	async acquire() {
-		return this.semaphore.acquire();
-	}
-	/**
-	* Releases the mutex, allowing another waiting task to proceed.
-	*/
-	release() {
-		this.semaphore.release();
-	}
-	/**
-	* Runs a function while holding the mutex lock.
-	* Automatically acquires before and releases after the function execution.
-	*
-	* @param fn - The function to execute while holding the lock
-	* @returns The result of the function
-	*/
-	async runExclusive(fn) {
-		await this.acquire();
-		try {
-			return await fn();
-		} finally {
-			this.release();
-		}
-	}
-};
-
-//#endregion
-export { Mutex };

package/dist/pkce.mjs

@@ -1,157 +0,0 @@
-import { base64url } from "jose";
-
-//#region src/pkce.ts
-/**
-* Performs a timing-safe comparison of two strings to prevent timing attacks.
-* This implementation is platform-agnostic, uses a constant-time algorithm,
-* and correctly handles all Unicode characters by operating on their UTF-8 byte representation.
-* It always takes a time proportional to the length of the expected string,
-* regardless of where the strings differ, making it safe for comparing sensitive values.
-*
-* @param a - The first string to compare (often the expected, secret value).
-* @param b - The second string to compare (often the user-provided value).
-* @returns True if the strings are identical, false otherwise.
-*
-* @example
-* ```ts
-* // Safe for comparing sensitive values like PKCE verifiers or tokens
-* const isValid = await timingSafeCompare(receivedVerifier, expectedChallenge);
-*
-* // Safe for password hash verification
-* const isValidPassword = timingSafeCompare(hashedInput, storedHash);
-*
-* // Returns false for different types or lengths without leaking timing info
-* timingSafeCompare("abc", 123 as any); // false
-* timingSafeCompare("abc", "abcd"); // false
-* ```
-*/
-const timingSafeCompare = (a, b) => {
-	if (typeof a !== "string" || typeof b !== "string") return false;
-	const encoder = new TextEncoder();
-	const aBytes = encoder.encode(a);
-	const bBytes = encoder.encode(b);
-	let diff = aBytes.length ^ bBytes.length;
-	for (const [i, aByte] of aBytes.entries()) diff |= aByte ^ (bBytes[i] ?? 0);
-	return diff === 0;
-};
-/**
-* Generates a cryptographically secure code verifier for PKCE.
-* The verifier is a URL-safe base64-encoded string of random bytes.
-*
-* @param length - Length of the random buffer in bytes
-* @returns Base64url-encoded verifier string
-*/
-const generateVerifier = (length) => {
-	const buffer = new Uint8Array(length);
-	crypto.getRandomValues(buffer);
-	return base64url.encode(buffer);
-};
-/**
-* Generates a code challenge from a verifier using the specified method.
-* For 'S256', applies SHA-256 hash then base64url encoding.
-* For 'plain', returns the verifier unchanged (not recommended for production).
-*
-* @param verifier - The code verifier string
-* @param method - Challenge generation method
-* @returns Promise resolving to the code challenge string
-*/
-const generateChallenge = async (verifier, method) => {
-	if (method === "plain") return verifier;
-	const data = new TextEncoder().encode(verifier);
-	const hash = await crypto.subtle.digest("SHA-256", data);
-	return base64url.encode(new Uint8Array(hash));
-};
-/**
-* Generates a complete PKCE challenge for OAuth authorization requests.
-* Creates a cryptographically secure verifier and corresponding S256 challenge.
-* Validates that the generated verifier meets standard requirements (43-128 characters).
-*
-* @param length - Length of the random buffer in bytes (32-96 range to generate 43-128 character verifier)
-* @returns Promise resolving to PKCE challenge data
-*
-* @example
-* ```ts
-* const pkce = await generatePKCE()
-*
-* // Use challenge in authorization URL
-* authUrl.searchParams.set('code_challenge', pkce.challenge)
-* authUrl.searchParams.set('code_challenge_method', pkce.method)
-*
-* // Store verifier for token exchange
-* sessionStorage.setItem('code_verifier', pkce.verifier)
-* ```
-*
-* @throws {RangeError} If length is outside valid range or generated verifier doesn't meet requirements
-*/
-const generatePKCE = async (length = 48) => {
-	if (!Number.isInteger(length) || length < 32 || length > 96) throw new RangeError("Random buffer length must be between 32 and 96 bytes (generates 43-128 character verifier)");
-	const verifier = generateVerifier(length);
-	if (verifier.length < 43 || verifier.length > 128) throw new Error("Generated verifier does not meet requirements");
-	if (!/^[A-Za-z0-9_-]+$/.test(verifier)) throw new Error("Generated verifier is not valid base64url format");
-	return {
-		verifier,
-		challenge: await generateChallenge(verifier, "S256"),
-		method: "S256"
-	};
-};
-/**
-* Validates a PKCE code verifier against a previously generated challenge.
-* Uses timing-safe comparison and timing normalization to prevent timing attacks.
-* All validation paths take the same computational time regardless of input validity,
-* making it resistant to timing-based side-channel attacks.
-*
-* @param verifier - The code verifier received from the client
-* @param challenge - The code challenge stored during authorization
-* @param method - The challenge method used during generation
-* @returns Promise resolving to true if verifier matches challenge
-*
-* @example
-* ```ts
-* // During token exchange
-* const isValid = await validatePKCE(
-*   receivedVerifier,
-*   storedChallenge,
-*   'S256'
-* )
-*
-* if (!isValid) {
-*   throw new Error('Invalid PKCE verifier')
-* }
-* ```
-*/
-const validatePKCE = async (verifier, challenge, method = "S256") => {
-	const MIN_PROCESSING_TIME = 50;
-	const RANDOM_JITTER_MAX = 20;
-	const startTime = performance.now();
-	let isValid = false;
-	let hasEarlyFailure = false;
-	const normalizedVerifier = String(verifier || "");
-	const normalizedChallenge = String(challenge || "");
-	hasEarlyFailure = ![
-		typeof verifier === "string" && typeof challenge === "string" && verifier && challenge,
-		normalizedVerifier.length >= 43 && normalizedVerifier.length <= 128,
-		normalizedChallenge.length >= 43 && normalizedChallenge.length <= 128,
-		/^[A-Za-z0-9_-]+$/.test(normalizedVerifier),
-		/^[A-Za-z0-9_-]+$/.test(normalizedChallenge)
-	].every(Boolean);
-	const verifierToUse = hasEarlyFailure ? "dummyverifier_".repeat(6) : normalizedVerifier;
-	try {
-		const comparisonResult = timingSafeCompare(await generateChallenge(verifierToUse, method), hasEarlyFailure ? "dummychallenge_".repeat(6) : normalizedChallenge);
-		isValid = !hasEarlyFailure && comparisonResult;
-	} catch {
-		isValid = false;
-	}
-	const elapsed = performance.now() - startTime;
-	const remainingTime = Math.max(0, MIN_PROCESSING_TIME - elapsed);
-	if (remainingTime > 0 || elapsed < MIN_PROCESSING_TIME) {
-		const jitterArray = new Uint32Array(1);
-		crypto.getRandomValues(jitterArray);
-		const jitter = (jitterArray[0] ?? 0) / 4294967295 * RANDOM_JITTER_MAX;
-		const totalDelay = Math.max(remainingTime, MIN_PROCESSING_TIME - elapsed) + jitter;
-		await new Promise((resolve) => setTimeout(resolve, totalDelay));
-	}
-	return isValid;
-};
-
-//#endregion
-export { generatePKCE, validatePKCE };