@fresho/router 0.1.0 → 0.3.2

package/README.md

@@ -214,6 +214,30 @@ Built-in middleware: `cors`, `errorHandler`, `logger`, `rateLimit`, `requestId`,
 
 See **[Middleware Documentation](docs/middleware.md)** for detailed usage.
 
+## Authentication Utilities
+
+For standalone auth utilities (JWT signing/verification, Basic auth, OAuth), import from `@fresho/router/auth`:
+
+```typescript
+import { jwtSign, jwtVerify, parseBasicAuth } from "@fresho/router/auth";
+
+// Sign a JWT
+const token = await jwtSign({ uid: "user-123" }, secret, { expiresIn: "1h" });
+
+// Verify a JWT
+const payload = await jwtVerify(token, secret);
+
+// Parse Basic auth header
+const creds = parseBasicAuth(request.headers.get("Authorization"));
+```
+
+Available utilities:
+- **JWT**: `jwtSign`, `jwtVerify`
+- **Basic Auth**: `parseBasicAuth`, `encodeBasicAuth`, `extractBasicAuthToken`
+- **OAuth**: `encodeOAuthState`, `decodeOAuthState`, `exchangeCode`, `refreshAccessToken`, `revokeToken`, `buildAuthorizationUrl`, `OAUTH_PROVIDERS`
+
+See **[Authentication Documentation](docs/authentication.md)** for detailed usage.
+
 ## HTTP Client
 
 Generate a typed client for your API:

package/dist/auth/index.d.mts

@@ -0,0 +1,327 @@
+import { a as VerifyJwtOptions, i as SignJwtOptions, n as JwtPayload, o as jwtSign, r as JwtSecret, s as jwtVerify, t as JwtAlgorithm } from "../jwt-DHM_nSwL.mjs";
+
+//#region src/auth/basic.d.ts
+
+/**
+ * @fileoverview Basic HTTP authentication utilities.
+ *
+ * Provides functions for parsing and encoding Basic authentication credentials.
+ *
+ * @example
+ * ```typescript
+ * import { parseBasicAuth, encodeBasicAuth } from '@fresho/router/auth';
+ *
+ * // Parse credentials from Authorization header
+ * const credentials = parseBasicAuth('Basic dXNlcm5hbWU6cGFzc3dvcmQ=');
+ * if (credentials) {
+ *   console.log(credentials.username); // 'username'
+ *   console.log(credentials.password); // 'password'
+ * }
+ *
+ * // Create an Authorization header value
+ * const header = encodeBasicAuth('username', 'password');
+ * // 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
+ * ```
+ */
+/** Parsed Basic authentication credentials. */
+interface BasicCredentials {
+  /** The username from the credentials. */
+  username: string;
+  /** The password from the credentials. */
+  password: string;
+}
+/**
+ * Parses Basic authentication credentials from an Authorization header value.
+ *
+ * @param authHeader - The full Authorization header value (e.g., 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=')
+ * @returns The parsed credentials, or null if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const header = request.headers.get('Authorization');
+ * const credentials = parseBasicAuth(header);
+ * if (credentials) {
+ *   // Verify credentials
+ *   const isValid = await verifyPassword(credentials.username, credentials.password);
+ * }
+ * ```
+ */
+declare function parseBasicAuth(authHeader: string | null): BasicCredentials | null;
+/**
+ * Encodes credentials into a Basic authentication header value.
+ *
+ * @param username - The username
+ * @param password - The password
+ * @returns The Authorization header value (e.g., 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=')
+ *
+ * @example
+ * ```typescript
+ * const authHeader = encodeBasicAuth('admin', 'secret');
+ * fetch('/api/endpoint', {
+ *   headers: { Authorization: authHeader }
+ * });
+ * ```
+ */
+declare function encodeBasicAuth(username: string, password: string): string;
+/**
+ * Extracts the raw base64-encoded credentials from an Authorization header.
+ *
+ * @param authHeader - The full Authorization header value
+ * @returns The base64 string, or null if not a Basic auth header
+ */
+declare function extractBasicAuthToken(authHeader: string | null): string | null;
+//#endregion
+//#region src/auth/oauth.d.ts
+/**
+ * @fileoverview OAuth 2.0 utilities for @fresho/router.
+ *
+ * Provides reusable primitives for implementing OAuth 2.0 Authorization Code flows.
+ * This implementation is designed as a confidential client suitable for server-side
+ * applications that can securely store client secrets.
+ *
+ * ## Design Decisions
+ *
+ * ### Why Not PKCE?
+ *
+ * PKCE (Proof Key for Code Exchange, RFC 7636) is a security extension designed to
+ * protect against authorization code interception attacks. However:
+ *
+ * - PKCE is **required** only for public clients (mobile apps, SPAs without backend)
+ * - PKCE is **optional** for confidential clients that can securely store secrets
+ * - These utilities assume a confidential client with a `client_secret`
+ * - The `client_secret` provides equivalent protection during token exchange
+ *
+ * ### HMAC-Signed State Parameter
+ *
+ * Instead of PKCE, we provide HMAC-signed state utilities that:
+ *
+ * 1. **Prevent CSRF attacks** - The signature is verified on callback
+ * 2. **Carry custom data** - Embed arbitrary data (e.g., user ID) in the state
+ * 3. **Include a nonce** - Random bytes prevent replay attacks
+ * 4. **Use Web Crypto API** - Works in Cloudflare Workers, Deno, and browsers
+ *
+ * ## Provider Compatibility
+ *
+ * This implementation pattern works with ~60-70% of OAuth 2.0 providers:
+ *
+ * | Provider   | PKCE     | Auth Method | Compatible |
+ * |------------|----------|-------------|------------|
+ * | Google     | Optional | Body        | ✅ Yes     |
+ * | GitHub     | None     | Basic Auth  | ✅ Minor tweak |
+ * | Slack      | None     | Body        | ✅ Yes     |
+ * | LinkedIn   | None     | Body        | ✅ Yes     |
+ * | Spotify    | Optional | Basic Auth  | ✅ Yes     |
+ * | Discord    | Optional | Body        | ✅ Yes     |
+ * | Dropbox    | None     | Basic Auth  | ✅ Minor tweak |
+ * | Twitter    | Required | -           | ❌ Needs PKCE |
+ * | TikTok     | Required | -           | ❌ Needs PKCE |
+ *
+ * @see https://tools.ietf.org/html/rfc6749 - OAuth 2.0 Authorization Framework
+ * @see https://tools.ietf.org/html/rfc7636 - PKCE Extension
+ *
+ * @example
+ * ```typescript
+ * import { encodeOAuthState, decodeOAuthState, exchangeCode } from '@fresho/router/middleware';
+ *
+ * // In your authorize route:
+ * const state = await encodeOAuthState({ uid: 'user-123' }, SECRET);
+ * const authUrl = `https://provider.com/oauth/authorize?state=${state}&...`;
+ *
+ * // In your callback route:
+ * const data = await decodeOAuthState(state, SECRET);
+ * if (data) {
+ *   const tokens = await exchangeCode(code, { ... });
+ * }
+ * ```
+ */
+/** OAuth 2.0 token response as per RFC 6749. */
+interface OAuthTokenResponse {
+  /** The access token issued by the authorization server. */
+  access_token: string;
+  /** The refresh token (optional, returned with offline access). */
+  refresh_token?: string;
+  /** The type of token (typically "Bearer"). */
+  token_type: string;
+  /** The lifetime in seconds of the access token. */
+  expires_in: number;
+  /** The scopes granted by the authorization server. */
+  scope?: string;
+  /** OpenID Connect ID token (if openid scope was requested). */
+  id_token?: string;
+}
+/** OAuth 2.0 provider configuration. */
+interface OAuthProvider {
+  /** Authorization endpoint URL. */
+  authorizationUrl: string;
+  /** Token endpoint URL. */
+  tokenUrl: string;
+  /** Token revocation endpoint URL (optional). */
+  revokeUrl?: string;
+  /** User info endpoint URL (optional). */
+  userInfoUrl?: string;
+}
+/** Common OAuth 2.0 providers with their endpoints. */
+declare const OAUTH_PROVIDERS: Record<string, OAuthProvider>;
+/** Token endpoint authentication method. */
+type TokenAuthMethod = 'body' | 'basic';
+/** Configuration for token exchange. */
+interface ExchangeCodeOptions {
+  /** Token endpoint URL. */
+  tokenUrl: string;
+  /** OAuth client ID. */
+  clientId: string;
+  /** OAuth client secret. */
+  clientSecret: string;
+  /** Redirect URI used in authorization request. */
+  redirectUri: string;
+  /** Authentication method (default: 'body'). */
+  authMethod?: TokenAuthMethod;
+}
+/** Configuration for token revocation. */
+interface RevokeTokenOptions {
+  /** Revocation endpoint URL. */
+  revokeUrl: string;
+  /** Token to revoke. */
+  token: string;
+  /** Token type hint (optional, e.g., 'refresh_token' or 'access_token'). */
+  tokenTypeHint?: string;
+  /** OAuth client ID (for providers that require it). */
+  clientId?: string;
+  /** OAuth client secret (for providers that require it). */
+  clientSecret?: string;
+  /** Authentication method (default: 'body'). */
+  authMethod?: TokenAuthMethod;
+}
+/**
+ * Encodes arbitrary data into an HMAC-signed state parameter.
+ *
+ * The state is base64url-encoded and includes:
+ * - The JSON-serialized payload
+ * - A random nonce (12 bytes) for replay protection
+ * - An HMAC-SHA256 signature (truncated to 16 hex chars)
+ *
+ * @param data - Arbitrary data to encode in the state
+ * @param secret - Secret key for HMAC signing
+ * @returns Base64url-encoded state string
+ *
+ * @example
+ * ```typescript
+ * const state = await encodeOAuthState({ uid: 'user-123', returnTo: '/dashboard' }, SECRET);
+ * // Use in OAuth authorization URL
+ * ```
+ */
+declare function encodeOAuthState(data: Record<string, unknown>, secret: string): Promise<string>;
+/**
+ * Decodes and verifies an HMAC-signed state parameter.
+ *
+ * @param state - Base64url-encoded state string
+ * @param secret - Secret key for HMAC verification
+ * @returns The decoded data, or null if verification fails
+ *
+ * @example
+ * ```typescript
+ * const data = await decodeOAuthState(state, SECRET);
+ * if (data) {
+ *   console.log(data.uid); // 'user-123'
+ * }
+ * ```
+ */
+declare function decodeOAuthState<T extends Record<string, unknown> = Record<string, unknown>>(state: string, secret: string): Promise<T | null>;
+/**
+ * Exchanges an authorization code for tokens.
+ *
+ * @param code - Authorization code from OAuth callback
+ * @param options - Token exchange configuration
+ * @returns Token response from the OAuth provider
+ * @throws Error if token exchange fails
+ *
+ * @example
+ * ```typescript
+ * const tokens = await exchangeCode(code, {
+ *   tokenUrl: OAUTH_PROVIDERS.google.tokenUrl,
+ *   clientId: env.CLIENT_ID,
+ *   clientSecret: env.CLIENT_SECRET,
+ *   redirectUri: 'https://example.com/callback',
+ * });
+ * ```
+ */
+declare function exchangeCode(code: string, options: ExchangeCodeOptions): Promise<OAuthTokenResponse>;
+/**
+ * Refreshes an access token using a refresh token.
+ *
+ * @param refreshToken - The refresh token
+ * @param options - Token exchange configuration (same as exchangeCode)
+ * @returns New token response from the OAuth provider
+ * @throws Error if token refresh fails
+ *
+ * @example
+ * ```typescript
+ * const tokens = await refreshAccessToken(refreshToken, {
+ *   tokenUrl: OAUTH_PROVIDERS.google.tokenUrl,
+ *   clientId: env.CLIENT_ID,
+ *   clientSecret: env.CLIENT_SECRET,
+ *   redirectUri: 'https://example.com/callback',
+ * });
+ * ```
+ */
+declare function refreshAccessToken(refreshToken: string, options: Omit<ExchangeCodeOptions, 'redirectUri'>): Promise<OAuthTokenResponse>;
+/**
+ * Revokes an OAuth token.
+ *
+ * @param options - Token revocation configuration
+ * @returns True if revocation succeeded
+ * @throws Error if revocation fails
+ *
+ * @example
+ * ```typescript
+ * await revokeToken({
+ *   revokeUrl: OAUTH_PROVIDERS.google.revokeUrl!,
+ *   token: refreshToken,
+ *   tokenTypeHint: 'refresh_token',
+ * });
+ * ```
+ */
+declare function revokeToken(options: RevokeTokenOptions): Promise<boolean>;
+/** Options for building an authorization URL. */
+interface AuthorizationUrlOptions {
+  /** Authorization endpoint URL. */
+  authorizationUrl: string;
+  /** OAuth client ID. */
+  clientId: string;
+  /** Redirect URI for OAuth callback. */
+  redirectUri: string;
+  /** Requested scopes. */
+  scopes: string[];
+  /** State parameter (use encodeOAuthState to generate). */
+  state: string;
+  /** Response type (default: 'code'). */
+  responseType?: string;
+  /** Additional provider-specific parameters. */
+  extraParams?: Record<string, string>;
+}
+/**
+ * Builds an OAuth authorization URL.
+ *
+ * @param options - Authorization URL configuration
+ * @returns The complete authorization URL
+ *
+ * @example
+ * ```typescript
+ * const state = await encodeOAuthState({ uid: 'user-123' }, SECRET);
+ * const authUrl = buildAuthorizationUrl({
+ *   authorizationUrl: OAUTH_PROVIDERS.google.authorizationUrl,
+ *   clientId: env.CLIENT_ID,
+ *   redirectUri: 'https://example.com/callback',
+ *   scopes: ['openid', 'email', 'profile'],
+ *   state,
+ *   extraParams: {
+ *     access_type: 'offline',
+ *     prompt: 'consent',
+ *   },
+ * });
+ * ```
+ */
+declare function buildAuthorizationUrl(options: AuthorizationUrlOptions): string;
+//#endregion
+export { type AuthorizationUrlOptions, type BasicCredentials, type ExchangeCodeOptions, type JwtAlgorithm, type JwtPayload, type JwtSecret, OAUTH_PROVIDERS, type OAuthProvider, type OAuthTokenResponse, type RevokeTokenOptions, type SignJwtOptions, type TokenAuthMethod, type VerifyJwtOptions, buildAuthorizationUrl, decodeOAuthState, encodeBasicAuth, encodeOAuthState, exchangeCode, extractBasicAuthToken, jwtSign, jwtVerify, parseBasicAuth, refreshAccessToken, revokeToken };
+//# sourceMappingURL=index.d.mts.map

package/dist/auth/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/auth/basic.ts","../../src/auth/oauth.ts"],"sourcesContent":[],"mappings":";;;;;;;AA2BA;AA2BA;AAsCA;AAUA;;;;AClCA;AAgBA;AAYA;AA8CA;AAGA;AAcA;AAqCA;AAmDA;;;;;AAGU,UD/NO,gBAAA,CC+NP;EA6DY;EAEX,QAAA,EAAA,MAAA;EACA;EAAR,QAAA,EAAA,MAAA;;AAqDH;;;;;;AAqDA;AAkCA;AAuCA;;;;;;;;iBDvbgB,cAAA,6BAA2C;;;;;;;;;;;;;;;;iBAsC3C,eAAA;;;;;;;iBAUA,qBAAA;;;;;;AA3EhB;AA2BA;AAsCA;AAUA;;;;AClCA;AAgBA;AAYA;AA8CA;AAGA;AAcA;AAqCA;AAmDA;;;;;;AAgEA;;;;;AAwDA;;;;;;AAqDA;AAkCA;AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;UAzaiB,kBAAA;;;;;;;;;;;;;;;UAgBA,aAAA;;;;;;;;;;;cAYJ,iBAAiB,eAAe;;KA8CjC,eAAA;;UAGK,mBAAA;;;;;;;;;;eAUF;;;UAIE,kBAAA;;;;;;;;;;;;eAYF;;;;;;;;;;;;;;;;;;;;iBAyBO,gBAAA,OACd,0CAEL;;;;;;;;;;;;;;;;iBAgDmB,2BAA2B,0BAA0B,yDAGxE,QAAQ;;;;;;;;;;;;;;;;;;;iBA6DW,YAAA,wBAEX,sBACR,QAAQ;;;;;;;;;;;;;;;;;;;iBAqDW,kBAAA,gCAEX,KAAK,sCACb,QAAQ;;;;;;;;;;;;;;;;;iBAkDW,WAAA,UAAqB,qBAAqB;;UAkC/C,uBAAA;;;;;;;;;;;;;;gBAcD;;;;;;;;;;;;;;;;;;;;;;;;iBAyBA,qBAAA,UAA+B"}

package/dist/auth/index.mjs

@@ -0,0 +1,279 @@
+import { a as parseBasicAuth, i as extractBasicAuthToken, n as jwtVerify, r as encodeBasicAuth, t as jwtSign } from "../jwt-Dab9kOC2.mjs";
+
+//#region src/auth/oauth.ts
+/** Common OAuth 2.0 providers with their endpoints. */
+const OAUTH_PROVIDERS = {
+	google: {
+		authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+		tokenUrl: "https://oauth2.googleapis.com/token",
+		revokeUrl: "https://oauth2.googleapis.com/revoke",
+		userInfoUrl: "https://www.googleapis.com/oauth2/v3/userinfo"
+	},
+	github: {
+		authorizationUrl: "https://github.com/login/oauth/authorize",
+		tokenUrl: "https://github.com/login/oauth/access_token",
+		revokeUrl: void 0,
+		userInfoUrl: "https://api.github.com/user"
+	},
+	discord: {
+		authorizationUrl: "https://discord.com/oauth2/authorize",
+		tokenUrl: "https://discord.com/api/oauth2/token",
+		revokeUrl: "https://discord.com/api/oauth2/token/revoke",
+		userInfoUrl: "https://discord.com/api/users/@me"
+	},
+	slack: {
+		authorizationUrl: "https://slack.com/openid/connect/authorize",
+		tokenUrl: "https://slack.com/api/openid.connect.token",
+		revokeUrl: void 0,
+		userInfoUrl: void 0
+	},
+	linkedin: {
+		authorizationUrl: "https://www.linkedin.com/oauth/v2/authorization",
+		tokenUrl: "https://www.linkedin.com/oauth/v2/accessToken",
+		revokeUrl: void 0,
+		userInfoUrl: "https://api.linkedin.com/v2/userinfo"
+	},
+	spotify: {
+		authorizationUrl: "https://accounts.spotify.com/authorize",
+		tokenUrl: "https://accounts.spotify.com/api/token",
+		revokeUrl: void 0,
+		userInfoUrl: "https://api.spotify.com/v1/me"
+	},
+	dropbox: {
+		authorizationUrl: "https://www.dropbox.com/oauth2/authorize",
+		tokenUrl: "https://api.dropboxapi.com/oauth2/token",
+		revokeUrl: "https://api.dropboxapi.com/2/auth/token/revoke",
+		userInfoUrl: void 0
+	}
+};
+/**
+* Encodes arbitrary data into an HMAC-signed state parameter.
+*
+* The state is base64url-encoded and includes:
+* - The JSON-serialized payload
+* - A random nonce (12 bytes) for replay protection
+* - An HMAC-SHA256 signature (truncated to 16 hex chars)
+*
+* @param data - Arbitrary data to encode in the state
+* @param secret - Secret key for HMAC signing
+* @returns Base64url-encoded state string
+*
+* @example
+* ```typescript
+* const state = await encodeOAuthState({ uid: 'user-123', returnTo: '/dashboard' }, SECRET);
+* // Use in OAuth authorization URL
+* ```
+*/
+async function encodeOAuthState(data, secret) {
+	const nonceBytes = new Uint8Array(12);
+	crypto.getRandomValues(nonceBytes);
+	const nonce = btoa(String.fromCharCode(...nonceBytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+	const payload = JSON.stringify({
+		...data,
+		_nonce: nonce
+	});
+	const encoder = new TextEncoder();
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+	const signatureHex = Array.from(new Uint8Array(signature)).map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 16);
+	const stateData = JSON.stringify({
+		payload,
+		sig: signatureHex
+	});
+	return btoa(stateData).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+/**
+* Decodes and verifies an HMAC-signed state parameter.
+*
+* @param state - Base64url-encoded state string
+* @param secret - Secret key for HMAC verification
+* @returns The decoded data, or null if verification fails
+*
+* @example
+* ```typescript
+* const data = await decodeOAuthState(state, SECRET);
+* if (data) {
+*   console.log(data.uid); // 'user-123'
+* }
+* ```
+*/
+async function decodeOAuthState(state, secret) {
+	try {
+		const base64 = state.replace(/-/g, "+").replace(/_/g, "/");
+		const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, "=");
+		const { payload, sig } = JSON.parse(atob(padded));
+		const encoder = new TextEncoder();
+		const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["sign"]);
+		const expectedSignature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+		if (sig !== Array.from(new Uint8Array(expectedSignature)).map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 16)) return null;
+		const payloadData = JSON.parse(payload);
+		delete payloadData._nonce;
+		return payloadData;
+	} catch {
+		return null;
+	}
+}
+/**
+* Exchanges an authorization code for tokens.
+*
+* @param code - Authorization code from OAuth callback
+* @param options - Token exchange configuration
+* @returns Token response from the OAuth provider
+* @throws Error if token exchange fails
+*
+* @example
+* ```typescript
+* const tokens = await exchangeCode(code, {
+*   tokenUrl: OAUTH_PROVIDERS.google.tokenUrl,
+*   clientId: env.CLIENT_ID,
+*   clientSecret: env.CLIENT_SECRET,
+*   redirectUri: 'https://example.com/callback',
+* });
+* ```
+*/
+async function exchangeCode(code, options) {
+	const { tokenUrl, clientId, clientSecret, redirectUri, authMethod = "body" } = options;
+	const body = new URLSearchParams({
+		grant_type: "authorization_code",
+		code,
+		redirect_uri: redirectUri
+	});
+	const headers = {
+		"Content-Type": "application/x-www-form-urlencoded",
+		Accept: "application/json"
+	};
+	if (authMethod === "basic") headers.Authorization = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
+	else {
+		body.set("client_id", clientId);
+		body.set("client_secret", clientSecret);
+	}
+	const response = await fetch(tokenUrl, {
+		method: "POST",
+		headers,
+		body: body.toString()
+	});
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Token exchange failed: ${response.status} ${errorText}`);
+	}
+	return response.json();
+}
+/**
+* Refreshes an access token using a refresh token.
+*
+* @param refreshToken - The refresh token
+* @param options - Token exchange configuration (same as exchangeCode)
+* @returns New token response from the OAuth provider
+* @throws Error if token refresh fails
+*
+* @example
+* ```typescript
+* const tokens = await refreshAccessToken(refreshToken, {
+*   tokenUrl: OAUTH_PROVIDERS.google.tokenUrl,
+*   clientId: env.CLIENT_ID,
+*   clientSecret: env.CLIENT_SECRET,
+*   redirectUri: 'https://example.com/callback',
+* });
+* ```
+*/
+async function refreshAccessToken(refreshToken, options) {
+	const { tokenUrl, clientId, clientSecret, authMethod = "body" } = options;
+	const body = new URLSearchParams({
+		grant_type: "refresh_token",
+		refresh_token: refreshToken
+	});
+	const headers = {
+		"Content-Type": "application/x-www-form-urlencoded",
+		Accept: "application/json"
+	};
+	if (authMethod === "basic") headers.Authorization = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
+	else {
+		body.set("client_id", clientId);
+		body.set("client_secret", clientSecret);
+	}
+	const response = await fetch(tokenUrl, {
+		method: "POST",
+		headers,
+		body: body.toString()
+	});
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Token refresh failed: ${response.status} ${errorText}`);
+	}
+	return response.json();
+}
+/**
+* Revokes an OAuth token.
+*
+* @param options - Token revocation configuration
+* @returns True if revocation succeeded
+* @throws Error if revocation fails
+*
+* @example
+* ```typescript
+* await revokeToken({
+*   revokeUrl: OAUTH_PROVIDERS.google.revokeUrl!,
+*   token: refreshToken,
+*   tokenTypeHint: 'refresh_token',
+* });
+* ```
+*/
+async function revokeToken(options) {
+	const { revokeUrl, token, tokenTypeHint, clientId, clientSecret, authMethod = "body" } = options;
+	const body = new URLSearchParams({ token });
+	if (tokenTypeHint) body.set("token_type_hint", tokenTypeHint);
+	const headers = { "Content-Type": "application/x-www-form-urlencoded" };
+	if (authMethod === "basic" && clientId && clientSecret) headers.Authorization = `Basic ${btoa(`${clientId}:${clientSecret}`)}`;
+	else if (clientId && clientSecret) {
+		body.set("client_id", clientId);
+		body.set("client_secret", clientSecret);
+	}
+	return (await fetch(revokeUrl, {
+		method: "POST",
+		headers,
+		body: body.toString()
+	})).ok;
+}
+/**
+* Builds an OAuth authorization URL.
+*
+* @param options - Authorization URL configuration
+* @returns The complete authorization URL
+*
+* @example
+* ```typescript
+* const state = await encodeOAuthState({ uid: 'user-123' }, SECRET);
+* const authUrl = buildAuthorizationUrl({
+*   authorizationUrl: OAUTH_PROVIDERS.google.authorizationUrl,
+*   clientId: env.CLIENT_ID,
+*   redirectUri: 'https://example.com/callback',
+*   scopes: ['openid', 'email', 'profile'],
+*   state,
+*   extraParams: {
+*     access_type: 'offline',
+*     prompt: 'consent',
+*   },
+* });
+* ```
+*/
+function buildAuthorizationUrl(options) {
+	const { authorizationUrl, clientId, redirectUri, scopes, state, responseType = "code", extraParams = {} } = options;
+	return `${authorizationUrl}?${new URLSearchParams({
+		response_type: responseType,
+		client_id: clientId,
+		redirect_uri: redirectUri,
+		scope: scopes.join(" "),
+		state,
+		...extraParams
+	}).toString()}`;
+}
+
+//#endregion
+export { OAUTH_PROVIDERS, buildAuthorizationUrl, decodeOAuthState, encodeBasicAuth, encodeOAuthState, exchangeCode, extractBasicAuthToken, jwtSign, jwtVerify, parseBasicAuth, refreshAccessToken, revokeToken };
+//# sourceMappingURL=index.mjs.map