@draftlab/auth 0.0.3 → 0.1.0

package/dist/provider/oauth2.d.ts

@@ -1,4 +1,176 @@
-import "../storage-CxKerLlc.js";
-import "../provider-tndlqCzp.js";
-import { Oauth2Config, Oauth2Provider, Oauth2Token, Oauth2UserData, Oauth2WrappedConfig } from "../oauth2-CXHukHf2.js";
+import { Provider } from "./provider.js";
+
+//#region src/provider/oauth2.d.ts
+
+/**
+ * Configuration options for the OAuth 2.0 provider.
+ */
+interface Oauth2Config {
+  /**
+   * Provider type identifier for internal use.
+   * @internal
+   * @default "oauth2"
+   */
+  readonly type?: string;
+  /**
+   * The client ID registered with the OAuth 2.0 provider.
+   * This public identifier is used in authorization requests.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "github-app-12345"
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * The client secret for authenticating with the OAuth 2.0 provider.
+   * This private credential must be kept secure and not exposed to clients.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.OAUTH_CLIENT_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * OAuth 2.0 endpoint URLs for the authorization and token flows.
+   */
+  readonly endpoint: {
+    /**
+     * The authorization endpoint where users are redirected for authentication.
+     *
+     * @example "https://github.com/login/oauth/authorize"
+     */
+    readonly authorization: string;
+    /**
+     * The token endpoint for exchanging authorization codes for access tokens.
+     *
+     * @example "https://github.com/login/oauth/access_token"
+     */
+    readonly token: string;
+    /**
+     * Optional JWKS endpoint for verifying ID tokens.
+     * Required only if the provider returns ID tokens that need verification.
+     *
+     * @example "https://provider.com/.well-known/jwks.json"
+     */
+    readonly jwks?: string;
+  };
+  /**
+   * OAuth 2.0 scopes to request during authorization.
+   * Scopes define the level of access being requested.
+   *
+   * @example
+   * ```ts
+   * {
+   *   scopes: ["user:email", "read:user", "repo"]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+  /**
+   * Whether to use PKCE (Proof Key for Code Exchange) for enhanced security.
+   * Recommended for public clients and required by some providers.
+   *
+   * @default false
+   *
+   * @example
+   * ```ts
+   * {
+   *   pkce: true // Required for Twitter/X, recommended for mobile apps
+   * }
+   * ```
+   */
+  readonly pkce?: boolean;
+  /**
+   * Additional query parameters to include in the authorization request.
+   * Useful for provider-specific parameters or customizing the auth flow.
+   *
+   * @example
+   * ```ts
+   * {
+   *   query: {
+   *     access_type: "offline",    // Request refresh token
+   *     prompt: "consent",         // Force consent screen
+   *     hd: "mycompany.com"       // Google Workspace domain
+   *   }
+   * }
+   * ```
+   */
+  readonly query?: Record<string, string>;
+}
+/**
+ * OAuth 2.0 configuration without endpoint-specific fields.
+ * Used internally for provider wrapping.
+ * @internal
+ */
+type Oauth2WrappedConfig = Omit<Oauth2Config, "endpoint" | "name">;
+/**
+ * OAuth 2.0 token response containing access tokens and metadata.
+ * Provides a structured interface for token data with lazy property access.
+ * @internal
+ */
+interface Oauth2Token {
+  /** Access token for making authenticated API requests */
+  readonly access: string;
+  /** Refresh token for obtaining new access tokens (if provided) */
+  readonly refresh: string;
+  /** Token expiration time in seconds (if provided) */
+  readonly expiry: number;
+  /** Raw token response from the provider */
+  readonly raw: Record<string, unknown>;
+}
+/**
+ * User data returned by successful OAuth 2.0 authentication.
+ */
+interface Oauth2UserData {
+  /** Token set containing access token, refresh token, and metadata */
+  readonly tokenset: Oauth2Token;
+  /** Client ID used for this authentication */
+  readonly clientID: string;
+}
+/**
+ * Creates an OAuth 2.0 authentication provider.
+ * Implements the Authorization Code Grant flow with optional PKCE support.
+ *
+ * @param config - OAuth 2.0 provider configuration
+ * @returns Provider instance implementing OAuth 2.0 authentication
+ *
+ * @example
+ * ```ts
+ * // GitHub provider with basic configuration
+ * const githubProvider = Oauth2Provider({
+ *   clientID: process.env.GITHUB_CLIENT_ID,
+ *   clientSecret: process.env.GITHUB_CLIENT_SECRET,
+ *   endpoint: {
+ *     authorization: "https://github.com/login/oauth/authorize",
+ *     token: "https://github.com/login/oauth/access_token"
+ *   },
+ *   scopes: ["user:email", "read:user"]
+ * })
+ *
+ * // Provider with PKCE and custom parameters
+ * const customProvider = Oauth2Provider({
+ *   clientID: "my-client-id",
+ *   clientSecret: "my-client-secret",
+ *   endpoint: {
+ *     authorization: "https://provider.com/oauth/authorize",
+ *     token: "https://provider.com/oauth/token",
+ *     jwks: "https://provider.com/.well-known/jwks.json"
+ *   },
+ *   scopes: ["read", "write"],
+ *   pkce: true,
+ *   query: {
+ *     prompt: "consent",
+ *     access_type: "offline"
+ *   }
+ * })
+ * ```
+ */
+declare const Oauth2Provider: (config: Oauth2Config) => Provider<Oauth2UserData>;
+//#endregion
 export { Oauth2Config, Oauth2Provider, Oauth2Token, Oauth2UserData, Oauth2WrappedConfig };

package/dist/provider/oauth2.js

@@ -1,7 +1,155 @@
-import "../util-CSdHUFOo.js";
-import "../error-DgAKK7b2.js";
-import "../pkce-276Za_rZ.js";
-import "../random-SXMYlaVr.js";
-import { Oauth2Provider } from "../oauth2-B7-6Z7Lc.js";
+import { getRelativeUrl } from "../util.js";
+import { OauthError } from "../error.js";
+import { generatePKCE } from "../pkce.js";
+import { generateSecureToken, timingSafeCompare } from "../random.js";
 
+//#region src/provider/oauth2.ts
+/**
+* Creates an OAuth 2.0 authentication provider.
+* Implements the Authorization Code Grant flow with optional PKCE support.
+*
+* @param config - OAuth 2.0 provider configuration
+* @returns Provider instance implementing OAuth 2.0 authentication
+*
+* @example
+* ```ts
+* // GitHub provider with basic configuration
+* const githubProvider = Oauth2Provider({
+*   clientID: process.env.GITHUB_CLIENT_ID,
+*   clientSecret: process.env.GITHUB_CLIENT_SECRET,
+*   endpoint: {
+*     authorization: "https://github.com/login/oauth/authorize",
+*     token: "https://github.com/login/oauth/access_token"
+*   },
+*   scopes: ["user:email", "read:user"]
+* })
+*
+* // Provider with PKCE and custom parameters
+* const customProvider = Oauth2Provider({
+*   clientID: "my-client-id",
+*   clientSecret: "my-client-secret",
+*   endpoint: {
+*     authorization: "https://provider.com/oauth/authorize",
+*     token: "https://provider.com/oauth/token",
+*     jwks: "https://provider.com/.well-known/jwks.json"
+*   },
+*   scopes: ["read", "write"],
+*   pkce: true,
+*   query: {
+*     prompt: "consent",
+*     access_type: "offline"
+*   }
+* })
+* ```
+*/
+const Oauth2Provider = (config) => {
+	const authQuery = config.query || {};
+	/**
+	* Handles the OAuth 2.0 callback logic for both GET and POST requests.
+	* Exchanges the authorization code for tokens and processes the response.
+	*/
+	const handleCallbackLogic = async (c, ctx, provider, code) => {
+		if (!(provider && code)) return c.redirect(getRelativeUrl(c, "./authorize"));
+		const tokenRequestBody = new URLSearchParams({
+			client_id: config.clientID,
+			client_secret: config.clientSecret,
+			code,
+			grant_type: "authorization_code",
+			redirect_uri: provider.redirect,
+			...provider.codeVerifier ? { code_verifier: provider.codeVerifier } : {}
+		});
+		try {
+			const response = await fetch(config.endpoint.token, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/x-www-form-urlencoded",
+					Accept: "application/json"
+				},
+				body: tokenRequestBody.toString()
+			});
+			if (!response.ok) throw new Error(`Token request failed with status ${response.status}`);
+			const tokenData = await response.json();
+			if (tokenData.error) throw new OauthError(tokenData.error, tokenData.error_description || "");
+			return await ctx.success(c, {
+				clientID: config.clientID,
+				tokenset: {
+					get access() {
+						return tokenData.access_token;
+					},
+					get refresh() {
+						return tokenData.refresh_token || "";
+					},
+					get expiry() {
+						return tokenData.expires_in || 0;
+					},
+					get raw() {
+						return tokenData;
+					}
+				}
+			});
+		} catch (error) {
+			if (error instanceof OauthError) throw error;
+			throw new OauthError("server_error", `Token exchange failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+	};
+	return {
+		type: config.type || "oauth2",
+		init(routes, ctx) {
+			/**
+			* Initiates OAuth 2.0 authorization flow.
+			* Redirects user to the provider's authorization endpoint with proper parameters.
+			*/
+			routes.get("/authorize", async (c) => {
+				const state = generateSecureToken();
+				const pkce = config.pkce ? await generatePKCE() : void 0;
+				await ctx.set(c, "provider", 60 * 10, {
+					state,
+					redirect: getRelativeUrl(c, "./callback"),
+					codeVerifier: pkce?.verifier
+				});
+				const authorizationUrl = new URL(config.endpoint.authorization);
+				authorizationUrl.searchParams.set("client_id", config.clientID);
+				authorizationUrl.searchParams.set("redirect_uri", getRelativeUrl(c, "./callback"));
+				authorizationUrl.searchParams.set("response_type", "code");
+				authorizationUrl.searchParams.set("state", state);
+				authorizationUrl.searchParams.set("scope", config.scopes.join(" "));
+				if (pkce) {
+					authorizationUrl.searchParams.set("code_challenge", pkce.challenge);
+					authorizationUrl.searchParams.set("code_challenge_method", pkce.method);
+				}
+				for (const [key, value] of Object.entries(authQuery)) authorizationUrl.searchParams.set(key, value);
+				return c.redirect(authorizationUrl.toString());
+			});
+			/**
+			* Handles OAuth 2.0 callback via query parameters (GET request).
+			* Standard OAuth 2.0 callback method for most providers.
+			*/
+			routes.get("/callback", async (c) => {
+				const provider = await ctx.get(c, "provider");
+				const code = c.query("code");
+				const state = c.query("state");
+				const error = c.query("error");
+				if (error) throw new OauthError(error, c.query("error_description") || "");
+				if (!(provider && code) || provider.state && !timingSafeCompare(state || "", provider.state)) return c.redirect(getRelativeUrl(c, "./authorize"));
+				return await handleCallbackLogic(c, ctx, provider, code);
+			});
+			/**
+			* Handles OAuth 2.0 callback via form data (POST request).
+			* Alternative callback method supported by some providers.
+			*/
+			routes.post("/callback", async (c) => {
+				const provider = await ctx.get(c, "provider");
+				const formData = await c.formData();
+				const code = formData.get("code")?.toString();
+				const state = formData.get("state")?.toString();
+				const error = formData.get("error")?.toString();
+				if (error) throw new OauthError(error, formData.get("error_description")?.toString() || "");
+				if (!(provider && code) || provider.state && !timingSafeCompare(state || "", provider.state)) return c.redirect(getRelativeUrl(c, "./authorize"));
+				return await handleCallbackLogic(c, ctx, provider, code);
+			});
+		}
+	};
+};
+
+//#endregion
 export { Oauth2Provider };