@draftlab/auth 0.11.0 → 0.13.0

package/dist/provider/password.d.mts

@@ -174,22 +174,49 @@ interface PasswordConfig {
    * Callback for sending verification codes to users via email.
    * Implement this to integrate with your email service provider.
    *
+   * The context parameter indicates why the code is being sent:
+   * - "register": User is registering for the first time
+   * - "register:resend": User requested to resend registration code
+   * - "reset": User is resetting their password
+   * - "reset:resend": User requested to resend password reset code
+   *
    * @param email - The recipient's email address
    * @param code - The verification code to send
+   * @param context - The context of why the code is being sent
    * @returns Promise that resolves when email is sent
    *
    * @example
    * ```ts
-   * sendCode: async (email, code) => {
+   * sendCode: async (email, code, context) => {
+   *   const templates = {
+   *     "register": {
+   *       subject: "Welcome! Verify your email",
+   *       body: `Welcome! Your verification code is: ${code}`
+   *     },
+   *     "register:resend": {
+   *       subject: "Your verification code (resent)",
+   *       body: `Here's your code again: ${code}`
+   *     },
+   *     "reset": {
+   *       subject: "Reset your password",
+   *       body: `Your password reset code is: ${code}`
+   *     },
+   *     "reset:resend": {
+   *       subject: "Password reset code (resent)",
+   *       body: `Here's your reset code again: ${code}`
+   *     }
+   *   }
+   *
+   *   const template = templates[context]
    *   await emailService.send({
    *     to: email,
-   *     subject: 'Your verification code',
-   *     text: `Your verification code is: ${code}`
+   *     subject: template.subject,
+   *     text: template.body
    *   })
    * }
    * ```
    */
-  sendCode: (email: string, code: string) => Promise<void>;
+  sendCode: (email: string, code: string, context: "register" | "register:resend" | "reset" | "reset:resend") => Promise<void>;
   /**
    * Optional password validation function or schema.
    * Can be either a validation function or a standard-schema validator.

package/dist/provider/password.mjs

@@ -129,7 +129,7 @@ const PasswordProvider = (config) => {
 						"password"
 					])) return transition(provider, { type: "email_taken" });
 					const code = generateCode();
-					await config.sendCode(email, code);
+					await config.sendCode(email, code, "register");
 					return transition({
 						type: "code",
 						code,
@@ -139,7 +139,7 @@ const PasswordProvider = (config) => {
 				}
 				if (action === "register" && provider.type === "code") {
 					const code = generateCode();
-					await config.sendCode(provider.email, code);
+					await config.sendCode(provider.email, code, "register:resend");
 					return transition({
 						type: "code",
 						code,
@@ -170,7 +170,7 @@ const PasswordProvider = (config) => {
 			routes.get("/change", async (c) => {
 				const state = {
 					type: "start",
-					redirect: c.query("redirect_uri") || getRelativeUrl(c, "/authorize")
+					redirect: c.query("redirect_uri") || getRelativeUrl(c, "./authorize")
 				};
 				await ctx.set(c, "provider", 3600 * 24, state);
 				return ctx.forward(c, await config.change(c.request, state));
@@ -194,7 +194,8 @@ const PasswordProvider = (config) => {
 						redirect: provider.redirect
 					}, { type: "invalid_email" });
 					const code = generateCode();
-					await config.sendCode(email, code);
+					const context = provider.type === "code" && provider.email === email ? "reset:resend" : "reset";
+					await config.sendCode(email, code, context);
 					return transition({
 						type: "code",
 						code,

package/dist/toolkit/client.d.mts

@@ -0,0 +1,169 @@
+import { OAuthStrategy } from "./providers/strategy.mjs";
+import { AuthStorage } from "./storage.mjs";
+
+//#region src/toolkit/client.d.ts
+
+/**
+ * Configuration for a single OAuth provider.
+ */
+interface ProviderConfig<TStrategy extends OAuthStrategy> {
+  /** OAuth strategy defining endpoints and defaults */
+  readonly strategy: TStrategy;
+  /** OAuth client ID from provider */
+  readonly clientId: string;
+  /** OAuth client secret from provider */
+  readonly clientSecret: string;
+  /** Redirect URI registered with provider */
+  readonly redirectUri: string;
+  /** Optional default scopes for this provider */
+  readonly scopes?: string[];
+}
+/**
+ * Options for initiating OAuth authorization flow.
+ */
+interface AuthorizeOptions {
+  /** Optional scopes to request (overrides provider defaults) */
+  readonly scopes?: string[];
+  /** Optional additional parameters to include in authorization URL */
+  readonly params?: Record<string, string>;
+  /** Optional nonce for additional security */
+  readonly nonce?: string;
+}
+/**
+ * Result of successful OAuth callback handling.
+ */
+interface CallbackResult {
+  /** OAuth provider that was used */
+  readonly provider: string;
+  /** Access token from provider */
+  readonly accessToken: string;
+  /** Optional refresh token from provider */
+  readonly refreshToken?: string;
+  /** Token expiration time in seconds */
+  readonly expiresIn?: number;
+  /** Token type (usually "Bearer") */
+  readonly tokenType?: string;
+  /** Optional ID token (OpenID Connect) */
+  readonly idToken?: string;
+}
+/**
+ * OAuth 2.0 client configuration.
+ */
+interface OAuthClientConfig<TProviders extends Record<string, ProviderConfig<OAuthStrategy>>> {
+  /** Provider configurations keyed by provider name */
+  readonly providers: TProviders;
+  /** Storage adapter for PKCE state (defaults to sessionStorage in browser) */
+  readonly storage?: AuthStorage;
+}
+/**
+ * OAuth 2.0 client for managing authentication flows.
+ */
+interface OAuthClient<TProviders extends Record<string, ProviderConfig<OAuthStrategy>>> {
+  /**
+   * Initiate OAuth authorization flow.
+   *
+   * @param provider - Provider name (key from providers config)
+   * @param options - Authorization options
+   * @returns Authorization URL to redirect user to
+   *
+   * @example
+   * ```ts
+   * // Basic usage
+   * const { url } = await client.authorize('github')
+   * window.location.href = url
+   *
+   * // With custom scopes
+   * const { url } = await client.authorize('google', {
+   *   scopes: ['openid', 'email', 'profile']
+   * })
+   *
+   * // With additional params
+   * const { url } = await client.authorize('github', {
+   *   params: { prompt: 'consent' }
+   * })
+   * ```
+   */
+  authorize(provider: (string & {}) | keyof TProviders, options?: AuthorizeOptions): Promise<{
+    url: string;
+    state: string;
+  }>;
+  /**
+   * Handle OAuth callback and exchange code for tokens.
+   *
+   * @param callbackUrl - Full callback URL with query parameters
+   * @returns Token exchange result
+   *
+   * @throws {Error} If callback URL is invalid, state mismatch, or token exchange fails
+   *
+   * @example
+   * ```ts
+   * // Client-side
+   * const result = await client.handleCallback(window.location.href)
+   * console.log(result.accessToken, result.provider)
+   *
+   * // Server-side (Next.js)
+   * export async function GET(req: Request) {
+   *   const result = await client.handleCallback(req.url)
+   *   // Store tokens, create session, etc.
+   *   return Response.redirect('/')
+   * }
+   * ```
+   */
+  handleCallback(callbackUrl: string): Promise<CallbackResult>;
+  /**
+   * Get user info from OAuth provider using access token.
+   *
+   * @param provider - Provider name
+   * @param accessToken - Access token from provider
+   * @returns User info from provider
+   *
+   * @example
+   * ```ts
+   * const userInfo = await client.getUserInfo('github', accessToken)
+   * console.log(userInfo.email, userInfo.name)
+   * ```
+   */
+  getUserInfo(provider: (string & {}) | keyof TProviders, accessToken: string): Promise<Record<string, unknown>>;
+}
+/**
+ * Creates an OAuth 2.0 client for managing authentication flows.
+ *
+ * Supports PKCE (Proof Key for Code Exchange) for enhanced security.
+ * Works in both client-side (browser) and server-side (Node.js) environments.
+ *
+ * @param config - OAuth client configuration
+ * @returns OAuth client instance
+ *
+ * @example
+ * ```ts
+ * import { createOAuthClient } from '@draftlab/auth/toolkit/client'
+ * import { GitHubStrategy, GoogleStrategy } from '@draftlab/auth/toolkit/providers'
+ *
+ * const client = createOAuthClient({
+ *   providers: {
+ *     github: {
+ *       strategy: GitHubStrategy,
+ *       clientId: 'YOUR_CLIENT_ID',
+ *       clientSecret: 'YOUR_CLIENT_SECRET',
+ *       redirectUri: 'http://localhost:3000/auth/callback'
+ *     },
+ *     google: {
+ *       strategy: GoogleStrategy,
+ *       clientId: 'YOUR_CLIENT_ID',
+ *       clientSecret: 'YOUR_CLIENT_SECRET',
+ *       redirectUri: 'http://localhost:3000/auth/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * })
+ *
+ * // Initiate login
+ * const { url } = await client.authorize('github')
+ *
+ * // Handle callback
+ * const result = await client.handleCallback(callbackUrl)
+ * ```
+ */
+declare const createOAuthClient: <TProviders extends Record<string, ProviderConfig<OAuthStrategy>>>(config: OAuthClientConfig<TProviders>) => OAuthClient<TProviders>;
+//#endregion
+export { AuthorizeOptions, CallbackResult, OAuthClient, OAuthClientConfig, ProviderConfig, createOAuthClient };

package/dist/toolkit/client.mjs

@@ -0,0 +1,209 @@
+import { generatePKCE } from "../pkce.mjs";
+import { createSessionStorage } from "./storage.mjs";
+import { generateSecureRandom } from "./utils.mjs";
+
+//#region src/toolkit/client.ts
+/**
+* Lightweight OAuth 2.0 client toolkit for DraftAuth.
+*
+* Provides a simple, framework-agnostic way to implement OAuth 2.0 authentication
+* with PKCE support. Works in both client-side (SPA) and server-side (Next.js, Remix) environments.
+*
+* @example
+* ```ts
+* // Client-side SPA (React, Vue, Solid, etc.)
+* import { createOAuthClient } from '@draftlab/auth/toolkit/client'
+* import { GitHubStrategy, GoogleStrategy } from '@draftlab/auth/toolkit/providers'
+* import { createSessionStorage } from '@draftlab/auth/toolkit/storage'
+*
+* const client = createOAuthClient({
+*   providers: {
+*     github: {
+*       strategy: GitHubStrategy,
+*       clientId: 'YOUR_CLIENT_ID',
+*       clientSecret: 'YOUR_CLIENT_SECRET',
+*       redirectUri: 'http://localhost:3000/auth/callback'
+*     },
+*     google: {
+*       strategy: GoogleStrategy,
+*       clientId: 'YOUR_CLIENT_ID',
+*       clientSecret: 'YOUR_CLIENT_SECRET',
+*       redirectUri: 'http://localhost:3000/auth/callback'
+*     }
+*   },
+*   storage: createSessionStorage()
+* })
+*
+* // Initiate login
+* const { url } = await client.authorize('github', { scopes: ['user:email'] })
+* window.location.href = url
+*
+* // Handle callback
+* const result = await client.handleCallback(window.location.href)
+* console.log(result.accessToken, result.provider)
+* ```
+*
+* @example
+* ```ts
+* // Server-side (Next.js App Router)
+* import { createOAuthClient } from '@draftlab/auth/toolkit/client'
+* import { GitHubStrategy } from '@draftlab/auth/toolkit/providers'
+* import { createCookieStorage } from '@draftlab/auth/toolkit/storage'
+* import { cookies } from 'next/headers'
+*
+* export async function GET(req: Request) {
+*   const client = createOAuthClient({
+*     providers: {
+*       github: {
+*         strategy: GitHubStrategy,
+*         clientId: process.env.GITHUB_CLIENT_ID!,
+*         clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+*         redirectUri: 'https://myapp.com/auth/callback'
+*       }
+*     },
+*     storage: createCookieStorage({
+*       getCookie: (name) => cookies().get(name)?.value ?? null,
+*       setCookie: (name, value, opts) => cookies().set(name, value, opts),
+*       deleteCookie: (name) => cookies().delete(name)
+*     })
+*   })
+*
+*   const { url } = await client.authorize('github')
+*   return Response.redirect(url)
+* }
+* ```
+*/
+/**
+* Creates an OAuth 2.0 client for managing authentication flows.
+*
+* Supports PKCE (Proof Key for Code Exchange) for enhanced security.
+* Works in both client-side (browser) and server-side (Node.js) environments.
+*
+* @param config - OAuth client configuration
+* @returns OAuth client instance
+*
+* @example
+* ```ts
+* import { createOAuthClient } from '@draftlab/auth/toolkit/client'
+* import { GitHubStrategy, GoogleStrategy } from '@draftlab/auth/toolkit/providers'
+*
+* const client = createOAuthClient({
+*   providers: {
+*     github: {
+*       strategy: GitHubStrategy,
+*       clientId: 'YOUR_CLIENT_ID',
+*       clientSecret: 'YOUR_CLIENT_SECRET',
+*       redirectUri: 'http://localhost:3000/auth/callback'
+*     },
+*     google: {
+*       strategy: GoogleStrategy,
+*       clientId: 'YOUR_CLIENT_ID',
+*       clientSecret: 'YOUR_CLIENT_SECRET',
+*       redirectUri: 'http://localhost:3000/auth/callback',
+*       scopes: ['openid', 'email', 'profile']
+*     }
+*   }
+* })
+*
+* // Initiate login
+* const { url } = await client.authorize('github')
+*
+* // Handle callback
+* const result = await client.handleCallback(callbackUrl)
+* ```
+*/
+const createOAuthClient = (config) => {
+	const storage = config.storage || (typeof sessionStorage !== "undefined" ? createSessionStorage() : null);
+	if (!storage) throw new Error("No storage adapter provided. Please provide a storage adapter for server-side environments.");
+	return {
+		async authorize(provider, options) {
+			const providerConfig = config.providers[provider];
+			if (!providerConfig) throw new Error(`Provider '${String(provider)}' not configured`);
+			const pkce = await generatePKCE();
+			const state = generateSecureRandom(16);
+			await storage.set({
+				state,
+				verifier: pkce.verifier,
+				provider: String(provider),
+				nonce: options?.nonce
+			});
+			const scopes = options?.scopes || providerConfig.scopes || providerConfig.strategy.scopes;
+			const params = new URLSearchParams({
+				client_id: providerConfig.clientId,
+				redirect_uri: providerConfig.redirectUri,
+				response_type: "code",
+				scope: Array.isArray(scopes) ? scopes.join(" ") : scopes,
+				state,
+				code_challenge: pkce.challenge,
+				code_challenge_method: pkce.method,
+				...options?.params
+			});
+			return {
+				url: `${providerConfig.strategy.authorizationEndpoint}?${params.toString()}`,
+				state
+			};
+		},
+		async handleCallback(callbackUrl) {
+			const url = new URL(callbackUrl);
+			const code = url.searchParams.get("code");
+			const state = url.searchParams.get("state");
+			const error = url.searchParams.get("error");
+			const errorDescription = url.searchParams.get("error_description");
+			if (error) throw new Error(`OAuth error: ${error}${errorDescription ? ` - ${errorDescription}` : ""}`);
+			if (!code || !state) throw new Error("Invalid callback URL: missing code or state parameter");
+			const storedState = await storage.get();
+			await storage.clear();
+			if (!storedState) throw new Error("No stored PKCE state found. OAuth flow may have expired or been tampered with.");
+			if (state !== storedState.state) throw new Error("State mismatch. Possible CSRF attack detected.");
+			const providerConfig = config.providers[storedState.provider];
+			if (!providerConfig) throw new Error(`Provider '${storedState.provider}' from callback not configured`);
+			const tokenParams = new URLSearchParams({
+				grant_type: "authorization_code",
+				code,
+				redirect_uri: providerConfig.redirectUri,
+				client_id: providerConfig.clientId,
+				client_secret: providerConfig.clientSecret,
+				code_verifier: storedState.verifier
+			});
+			const tokenResponse = await fetch(providerConfig.strategy.tokenEndpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/x-www-form-urlencoded",
+					Accept: "application/json"
+				},
+				body: tokenParams
+			});
+			if (!tokenResponse.ok) {
+				const errorText = await tokenResponse.text();
+				throw new Error(`Token exchange failed (${tokenResponse.status}): ${errorText}`);
+			}
+			const tokenData = await tokenResponse.json();
+			if (!tokenData.access_token) throw new Error("No access token in provider response");
+			return {
+				provider: storedState.provider,
+				accessToken: tokenData.access_token,
+				refreshToken: tokenData.refresh_token,
+				expiresIn: tokenData.expires_in,
+				tokenType: tokenData.token_type,
+				idToken: tokenData.id_token
+			};
+		},
+		async getUserInfo(provider, accessToken) {
+			const providerConfig = config.providers[provider];
+			if (!providerConfig) throw new Error(`Provider '${String(provider)}' not configured`);
+			if (!providerConfig.strategy.userInfoEndpoint) throw new Error(`Provider '${String(provider)}' does not support user info endpoint`);
+			const response = await fetch(providerConfig.strategy.userInfoEndpoint, { headers: {
+				Authorization: `Bearer ${accessToken}`,
+				Accept: "application/json"
+			} });
+			if (!response.ok) {
+				const errorText = await response.text();
+				throw new Error(`Failed to fetch user info (${response.status}): ${errorText}`);
+			}
+			return response.json();
+		}
+	};
+};
+
+//#endregion
+export { createOAuthClient };

package/dist/toolkit/index.d.mts

@@ -0,0 +1,9 @@
+import { generatePKCE } from "../pkce.mjs";
+import { OAuth2TokenResponse, OAuthStrategy } from "./providers/strategy.mjs";
+import { AuthStorage, PKCEState, createCookieStorage, createLocalStorage, createMemoryStorage, createSessionStorage } from "./storage.mjs";
+import { AuthorizeOptions, CallbackResult, OAuthClient, OAuthClientConfig, ProviderConfig, createOAuthClient } from "./client.mjs";
+import { FacebookStrategy } from "./providers/facebook.mjs";
+import { GitHubStrategy } from "./providers/github.mjs";
+import { GoogleStrategy } from "./providers/google.mjs";
+import { generateSecureRandom } from "./utils.mjs";
+export { type AuthStorage, type AuthorizeOptions, type CallbackResult, FacebookStrategy, GitHubStrategy, GoogleStrategy, type OAuth2TokenResponse, type OAuthClient, type OAuthClientConfig, type OAuthStrategy, type PKCEState, type ProviderConfig, createCookieStorage, createLocalStorage, createMemoryStorage, createOAuthClient, createSessionStorage, generatePKCE, generateSecureRandom };

package/dist/toolkit/index.mjs

@@ -0,0 +1,9 @@
+import { generatePKCE } from "../pkce.mjs";
+import { createCookieStorage, createLocalStorage, createMemoryStorage, createSessionStorage } from "./storage.mjs";
+import { generateSecureRandom } from "./utils.mjs";
+import { createOAuthClient } from "./client.mjs";
+import { FacebookStrategy } from "./providers/facebook.mjs";
+import { GitHubStrategy } from "./providers/github.mjs";
+import { GoogleStrategy } from "./providers/google.mjs";
+
+export { FacebookStrategy, GitHubStrategy, GoogleStrategy, createCookieStorage, createLocalStorage, createMemoryStorage, createOAuthClient, createSessionStorage, generatePKCE, generateSecureRandom };

package/dist/toolkit/providers/facebook.d.mts

@@ -0,0 +1,12 @@
+import { OAuthStrategy } from "./strategy.mjs";
+
+//#region src/toolkit/providers/facebook.d.ts
+
+/**
+ * Facebook OAuth 2.0 strategy.
+ *
+ * @see https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow
+ */
+declare const FacebookStrategy: OAuthStrategy;
+//#endregion
+export { FacebookStrategy };

package/dist/toolkit/providers/facebook.mjs

@@ -0,0 +1,16 @@
+//#region src/toolkit/providers/facebook.ts
+/**
+* Facebook OAuth 2.0 strategy.
+*
+* @see https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow
+*/
+const FacebookStrategy = {
+	name: "facebook",
+	authorizationEndpoint: "https://www.facebook.com/v23.0/dialog/oauth",
+	tokenEndpoint: "https://graph.facebook.com/v23.0/oauth/access_token",
+	userInfoEndpoint: "https://graph.facebook.com/me?fields=id,name,email",
+	scopes: ["public_profile", "email"]
+};
+
+//#endregion
+export { FacebookStrategy };

package/dist/toolkit/providers/github.d.mts

@@ -0,0 +1,12 @@
+import { OAuthStrategy } from "./strategy.mjs";
+
+//#region src/toolkit/providers/github.d.ts
+
+/**
+ * GitHub OAuth 2.0 strategy.
+ *
+ * @see https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
+ */
+declare const GitHubStrategy: OAuthStrategy;
+//#endregion
+export { GitHubStrategy };

package/dist/toolkit/providers/github.mjs

@@ -0,0 +1,16 @@
+//#region src/toolkit/providers/github.ts
+/**
+* GitHub OAuth 2.0 strategy.
+*
+* @see https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
+*/
+const GitHubStrategy = {
+	name: "github",
+	authorizationEndpoint: "https://github.com/login/oauth/authorize",
+	tokenEndpoint: "https://github.com/login/oauth/access_token",
+	userInfoEndpoint: "https://api.github.com/user",
+	scopes: ["read:user", "user:email"]
+};
+
+//#endregion
+export { GitHubStrategy };

package/dist/toolkit/providers/google.d.mts

@@ -0,0 +1,12 @@
+import { OAuthStrategy } from "./strategy.mjs";
+
+//#region src/toolkit/providers/google.d.ts
+
+/**
+ * Google OAuth 2.0 / OpenID Connect strategy.
+ *
+ * @see https://developers.google.com/identity/protocols/oauth2
+ */
+declare const GoogleStrategy: OAuthStrategy;
+//#endregion
+export { GoogleStrategy };

package/dist/toolkit/providers/google.mjs

@@ -0,0 +1,20 @@
+//#region src/toolkit/providers/google.ts
+/**
+* Google OAuth 2.0 / OpenID Connect strategy.
+*
+* @see https://developers.google.com/identity/protocols/oauth2
+*/
+const GoogleStrategy = {
+	name: "google",
+	authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+	tokenEndpoint: "https://oauth2.googleapis.com/token",
+	userInfoEndpoint: "https://www.googleapis.com/oauth2/v3/userinfo",
+	scopes: [
+		"openid",
+		"email",
+		"profile"
+	]
+};
+
+//#endregion
+export { GoogleStrategy };

package/dist/toolkit/providers/strategy.d.mts

@@ -0,0 +1,40 @@
+//#region src/toolkit/providers/strategy.d.ts
+/**
+ * OAuth 2.0 strategy interface and types for provider configurations.
+ */
+/**
+ * OAuth 2.0 token response from provider's token endpoint.
+ * Based on RFC 6749 Section 5.1.
+ */
+interface OAuth2TokenResponse {
+  /** The access token issued by the authorization server */
+  access_token: string;
+  /** The type of token (usually "Bearer") */
+  token_type?: string;
+  /** The lifetime in seconds of the access token */
+  expires_in?: number;
+  /** The refresh token for obtaining new access tokens */
+  refresh_token?: string;
+  /** The scope of the access token (space-separated list) */
+  scope?: string;
+  /** OpenID Connect ID token (JWT) */
+  id_token?: string;
+}
+/**
+ * OAuth 2.0 provider strategy definition.
+ * Defines the endpoints and default configuration for an OAuth provider.
+ */
+interface OAuthStrategy {
+  /** Provider name (e.g., "github", "google") */
+  readonly name: string;
+  /** OAuth authorization endpoint URL */
+  readonly authorizationEndpoint: string;
+  /** OAuth token exchange endpoint URL */
+  readonly tokenEndpoint: string;
+  /** Optional user info endpoint URL (for OpenID Connect) */
+  readonly userInfoEndpoint?: string;
+  /** Default scopes to request */
+  readonly scopes: string[];
+}
+//#endregion
+export { OAuth2TokenResponse, OAuthStrategy };

package/dist/toolkit/providers/strategy.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/toolkit/storage.d.mts

@@ -0,0 +1,145 @@
+//#region src/toolkit/storage.d.ts
+/**
+ * Storage adapters for PKCE state management across different runtime environments.
+ * Provides implementations for browser (sessionStorage/localStorage), server (cookies),
+ * and custom storage backends.
+ */
+/**
+ * PKCE state data stored during OAuth flow.
+ */
+interface PKCEState {
+  /** Random state parameter for CSRF protection */
+  readonly state: string;
+  /** PKCE code verifier for token exchange */
+  readonly verifier: string;
+  /** OAuth provider identifier */
+  readonly provider: string;
+  /** Optional nonce for additional security */
+  readonly nonce?: string;
+}
+/**
+ * Storage interface for persisting PKCE state during OAuth flow.
+ * Implement this interface to provide custom storage backends.
+ */
+interface AuthStorage {
+  /**
+   * Store PKCE state data.
+   * @param state - PKCE state to persist
+   */
+  set(state: PKCEState): void | Promise<void>;
+  /**
+   * Retrieve stored PKCE state data.
+   * @returns Stored state or null if not found
+   */
+  get(): PKCEState | null | Promise<PKCEState | null>;
+  /**
+   * Clear stored PKCE state data.
+   */
+  clear(): void | Promise<void>;
+}
+/**
+ * Creates a browser sessionStorage adapter for PKCE state.
+ * Suitable for client-side SPAs where state should only persist during the browser session.
+ *
+ * @returns AuthStorage implementation using sessionStorage
+ *
+ * @example
+ * ```ts
+ * const storage = createSessionStorage()
+ *
+ * // Use in toolkit client
+ * const client = createOAuthClient({
+ *   storage,
+ *   providers: { ... }
+ * })
+ * ```
+ */
+declare const createSessionStorage: () => AuthStorage;
+/**
+ * Creates a browser localStorage adapter for PKCE state.
+ * Suitable for client-side SPAs where state should persist across browser sessions.
+ *
+ * ⚠️ Warning: localStorage persists data indefinitely. Consider using sessionStorage
+ * for better security, as it automatically clears on browser close.
+ *
+ * @returns AuthStorage implementation using localStorage
+ *
+ * @example
+ * ```ts
+ * const storage = createLocalStorage()
+ *
+ * // Use in toolkit client
+ * const client = createOAuthClient({
+ *   storage,
+ *   providers: { ... }
+ * })
+ * ```
+ */
+declare const createLocalStorage: () => AuthStorage;
+/**
+ * Creates a memory-based storage adapter for PKCE state.
+ * Suitable for server-side rendering or testing environments.
+ * State is lost when the process terminates or page reloads.
+ *
+ * @returns AuthStorage implementation using in-memory storage
+ *
+ * @example
+ * ```ts
+ * // Server-side or testing
+ * const storage = createMemoryStorage()
+ *
+ * const client = createOAuthClient({
+ *   storage,
+ *   providers: { ... }
+ * })
+ * ```
+ */
+declare const createMemoryStorage: () => AuthStorage;
+/**
+ * Creates a cookie-based storage adapter for PKCE state.
+ * Suitable for server-side OAuth flows (Next.js, Remix, etc.) where you need
+ * to persist state across requests.
+ *
+ * @param options - Cookie configuration options
+ * @returns AuthStorage implementation using cookies
+ *
+ * @example
+ * ```ts
+ * // Next.js App Router
+ * import { cookies } from 'next/headers'
+ *
+ * const storage = createCookieStorage({
+ *   getCookie: (name) => cookies().get(name)?.value ?? null,
+ *   setCookie: (name, value, opts) => {
+ *     cookies().set(name, value, {
+ *       httpOnly: true,
+ *       secure: true,
+ *       sameSite: 'lax',
+ *       maxAge: opts.maxAge
+ *     })
+ *   },
+ *   deleteCookie: (name) => cookies().delete(name)
+ * })
+ *
+ * // TanStack Start
+ * import { getCookie, setCookie, deleteCookie } from '@tanstack/react-start/server'
+ *
+ * const storage = createCookieStorage({
+ *   getCookie,
+ *   setCookie: (name, value, opts) => setCookie(name, value, opts),
+ *   deleteCookie
+ * })
+ * ```
+ */
+declare const createCookieStorage: (options: {
+  getCookie: (name: string) => string | null | Promise<string | null>;
+  setCookie: (name: string, value: string, options: {
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: string;
+  }) => void | Promise<void>;
+  deleteCookie: (name: string) => void | Promise<void>;
+}) => AuthStorage;
+//#endregion
+export { AuthStorage, PKCEState, createCookieStorage, createLocalStorage, createMemoryStorage, createSessionStorage };

package/dist/toolkit/storage.mjs

@@ -0,0 +1,157 @@
+//#region src/toolkit/storage.ts
+const STORAGE_KEY = "draftauth.pkce";
+/**
+* Creates a browser sessionStorage adapter for PKCE state.
+* Suitable for client-side SPAs where state should only persist during the browser session.
+*
+* @returns AuthStorage implementation using sessionStorage
+*
+* @example
+* ```ts
+* const storage = createSessionStorage()
+*
+* // Use in toolkit client
+* const client = createOAuthClient({
+*   storage,
+*   providers: { ... }
+* })
+* ```
+*/
+const createSessionStorage = () => ({
+	set: (data) => {
+		if (typeof sessionStorage === "undefined") throw new Error("sessionStorage is not available in this environment");
+		sessionStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+	},
+	get: () => {
+		if (typeof sessionStorage === "undefined") return null;
+		const data = sessionStorage.getItem(STORAGE_KEY);
+		return data ? JSON.parse(data) : null;
+	},
+	clear: () => {
+		if (typeof sessionStorage === "undefined") return;
+		sessionStorage.removeItem(STORAGE_KEY);
+	}
+});
+/**
+* Creates a browser localStorage adapter for PKCE state.
+* Suitable for client-side SPAs where state should persist across browser sessions.
+*
+* ⚠️ Warning: localStorage persists data indefinitely. Consider using sessionStorage
+* for better security, as it automatically clears on browser close.
+*
+* @returns AuthStorage implementation using localStorage
+*
+* @example
+* ```ts
+* const storage = createLocalStorage()
+*
+* // Use in toolkit client
+* const client = createOAuthClient({
+*   storage,
+*   providers: { ... }
+* })
+* ```
+*/
+const createLocalStorage = () => ({
+	set: (data) => {
+		if (typeof localStorage === "undefined") throw new Error("localStorage is not available in this environment");
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+	},
+	get: () => {
+		if (typeof localStorage === "undefined") return null;
+		const data = localStorage.getItem(STORAGE_KEY);
+		return data ? JSON.parse(data) : null;
+	},
+	clear: () => {
+		if (typeof localStorage === "undefined") return;
+		localStorage.removeItem(STORAGE_KEY);
+	}
+});
+/**
+* Creates a memory-based storage adapter for PKCE state.
+* Suitable for server-side rendering or testing environments.
+* State is lost when the process terminates or page reloads.
+*
+* @returns AuthStorage implementation using in-memory storage
+*
+* @example
+* ```ts
+* // Server-side or testing
+* const storage = createMemoryStorage()
+*
+* const client = createOAuthClient({
+*   storage,
+*   providers: { ... }
+* })
+* ```
+*/
+const createMemoryStorage = () => {
+	let state = null;
+	return {
+		set: (data) => {
+			state = data;
+		},
+		get: () => {
+			return state;
+		},
+		clear: () => {
+			state = null;
+		}
+	};
+};
+/**
+* Creates a cookie-based storage adapter for PKCE state.
+* Suitable for server-side OAuth flows (Next.js, Remix, etc.) where you need
+* to persist state across requests.
+*
+* @param options - Cookie configuration options
+* @returns AuthStorage implementation using cookies
+*
+* @example
+* ```ts
+* // Next.js App Router
+* import { cookies } from 'next/headers'
+*
+* const storage = createCookieStorage({
+*   getCookie: (name) => cookies().get(name)?.value ?? null,
+*   setCookie: (name, value, opts) => {
+*     cookies().set(name, value, {
+*       httpOnly: true,
+*       secure: true,
+*       sameSite: 'lax',
+*       maxAge: opts.maxAge
+*     })
+*   },
+*   deleteCookie: (name) => cookies().delete(name)
+* })
+*
+* // TanStack Start
+* import { getCookie, setCookie, deleteCookie } from '@tanstack/react-start/server'
+*
+* const storage = createCookieStorage({
+*   getCookie,
+*   setCookie: (name, value, opts) => setCookie(name, value, opts),
+*   deleteCookie
+* })
+* ```
+*/
+const createCookieStorage = (options) => ({
+	set: async (data) => {
+		await options.setCookie(STORAGE_KEY, JSON.stringify(data), {
+			maxAge: 600,
+			httpOnly: true,
+			secure: process.env.NODE_ENV === "production",
+			sameSite: "lax"
+		});
+	},
+	get: async () => {
+		const value = await options.getCookie(STORAGE_KEY);
+		return value ? JSON.parse(value) : null;
+	},
+	clear: async () => {
+		await options.deleteCookie(STORAGE_KEY);
+	}
+});
+
+//#endregion
+export { createCookieStorage, createLocalStorage, createMemoryStorage, createSessionStorage };

package/dist/toolkit/utils.d.mts

@@ -0,0 +1,21 @@
+//#region src/toolkit/utils.d.ts
+/**
+ * Universal utilities for the OAuth toolkit.
+ * These functions work in both browser and Node.js environments.
+ */
+/**
+ * Generates a cryptographically secure random string using Web Crypto API.
+ * Works in both browser and Node.js environments (Node 15+).
+ *
+ * @param length - Length of random data in bytes (default: 32 for 256-bit security)
+ * @returns Base64url-encoded secure random string
+ *
+ * @example
+ * ```ts
+ * const state = generateSecureRandom(16) // 128-bit random state
+ * const token = generateSecureRandom(32) // 256-bit random token
+ * ```
+ */
+declare const generateSecureRandom: (length?: number) => string;
+//#endregion
+export { generateSecureRandom };

package/dist/toolkit/utils.mjs

@@ -0,0 +1,30 @@
+//#region src/toolkit/utils.ts
+/**
+* Universal utilities for the OAuth toolkit.
+* These functions work in both browser and Node.js environments.
+*/
+/**
+* Generates a cryptographically secure random string using Web Crypto API.
+* Works in both browser and Node.js environments (Node 15+).
+*
+* @param length - Length of random data in bytes (default: 32 for 256-bit security)
+* @returns Base64url-encoded secure random string
+*
+* @example
+* ```ts
+* const state = generateSecureRandom(16) // 128-bit random state
+* const token = generateSecureRandom(32) // 256-bit random token
+* ```
+*/
+const generateSecureRandom = (length = 32) => {
+	if (length <= 0 || !Number.isInteger(length)) throw new RangeError("Length must be a positive integer");
+	const randomBytes = new Uint8Array(length);
+	crypto.getRandomValues(randomBytes);
+	let base64 = "";
+	if (typeof btoa !== "undefined") base64 = btoa(String.fromCharCode(...randomBytes));
+	else base64 = Buffer.from(randomBytes).toString("base64");
+	return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+};
+
+//#endregion
+export { generateSecureRandom };

package/dist/ui/password.mjs

@@ -159,7 +159,7 @@ const PasswordUI = (options) => {
 					] })
 				})
 			]
-		}) : /* @__PURE__ */ jsxs("form", {
+		}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("form", {
 			"data-component": "form",
 			method: "post",
 			children: [
@@ -188,7 +188,47 @@ const PasswordUI = (options) => {
 					children: copy.button_continue
 				})
 			]
-		}) });
+		}), /* @__PURE__ */ jsxs("form", {
+			method: "post",
+			children: [
+				/* @__PURE__ */ jsx("input", {
+					name: "action",
+					type: "hidden",
+					value: "register"
+				}),
+				/* @__PURE__ */ jsx("input", {
+					name: "email",
+					type: "hidden",
+					value: state.email
+				}),
+				/* @__PURE__ */ jsx("input", {
+					name: "password",
+					type: "hidden",
+					value: ""
+				}),
+				/* @__PURE__ */ jsx("input", {
+					name: "repeat",
+					type: "hidden",
+					value: ""
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					"data-component": "form-footer",
+					children: [/* @__PURE__ */ jsxs("span", { children: [
+						copy.code_return,
+						" ",
+						/* @__PURE__ */ jsx("a", {
+							"data-component": "link",
+							href: "./authorize",
+							children: copy.login
+						})
+					] }), /* @__PURE__ */ jsx("button", {
+						type: "submit",
+						"data-component": "link",
+						children: copy.code_resend
+					})]
+				})
+			]
+		})] }) });
 	};
 	/**
 	* Renders the password change form based on current state

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftlab/auth",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Core implementation for @draftlab/auth",
   "author": "Matheus Pergoli",