@draftlab/auth 0.10.4 → 0.12.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftlab/auth",
-  "version": "0.10.4",
+  "version": "0.12.0",
   "type": "module",
   "description": "Core implementation for @draftlab/auth",
   "author": "Matheus Pergoli",
@@ -39,7 +39,7 @@
   "devDependencies": {
     "@types/node": "^25.0.3",
     "@types/qrcode": "^1.5.6",
-    "tsdown": "^0.18.2",
+    "tsdown": "^0.18.3",
     "typescript": "^5.9.3",
     "@draftlab/tsconfig": "0.1.0"
   },
@@ -63,7 +63,7 @@
     "preact": "^10.28.1",
     "preact-render-to-string": "^6.6.4",
     "qrcode": "^1.5.4",
-    "@draftlab/auth-router": "0.4.1"
+    "@draftlab/auth-router": "0.5.0"
   },
   "engines": {
     "node": ">=18"

package/dist/plugin/builder.d.mts

@@ -1,27 +0,0 @@
-import { PluginBuilder } from "./plugin.mjs";
-
-//#region src/plugin/builder.d.ts
-
-/**
- * Create a new plugin builder.
- * Plugins are built using a fluent API that supports routes and lifecycle hooks.
- *
- * @param id - Unique identifier for the plugin
- * @returns Plugin builder with chainable methods
- *
- * @example
- * ```ts
- * const analytics = plugin("analytics")
- *   .onSuccess(async (ctx) => {
- *     await ctx.storage.set(`success:${ctx.clientID}`, ctx.subject)
- *   })
- *   .post("/stats", async (ctx) => {
- *     const stats = await ctx.pluginStorage.get("stats")
- *     return ctx.json(stats)
- *   })
- *   .build()
- * ```
- */
-declare const plugin: (id: string) => PluginBuilder;
-//#endregion
-export { plugin };

package/dist/plugin/builder.mjs

@@ -1,93 +0,0 @@
-//#region src/plugin/builder.ts
-/**
-* Create a new plugin builder.
-* Plugins are built using a fluent API that supports routes and lifecycle hooks.
-*
-* @param id - Unique identifier for the plugin
-* @returns Plugin builder with chainable methods
-*
-* @example
-* ```ts
-* const analytics = plugin("analytics")
-*   .onSuccess(async (ctx) => {
-*     await ctx.storage.set(`success:${ctx.clientID}`, ctx.subject)
-*   })
-*   .post("/stats", async (ctx) => {
-*     const stats = await ctx.pluginStorage.get("stats")
-*     return ctx.json(stats)
-*   })
-*   .build()
-* ```
-*/
-const plugin = (id) => {
-	if (!id || typeof id !== "string") throw new Error("Plugin id must be a non-empty string");
-	const routes = [];
-	const registeredPaths = /* @__PURE__ */ new Set();
-	let initHook;
-	let authorizeHook;
-	let successHook;
-	let errorHook;
-	const validatePath = (path) => {
-		if (!path || typeof path !== "string") throw new Error("Route path must be a non-empty string");
-		if (!path.startsWith("/")) throw new Error("Route path must start with '/'");
-	};
-	return {
-		get(path, handler) {
-			validatePath(path);
-			const routeKey = `GET ${path}`;
-			if (registeredPaths.has(routeKey)) throw new Error(`Route ${routeKey} already registered in plugin '${id}'`);
-			registeredPaths.add(routeKey);
-			routes.push({
-				method: "GET",
-				path,
-				handler
-			});
-			return this;
-		},
-		post(path, handler) {
-			validatePath(path);
-			const routeKey = `POST ${path}`;
-			if (registeredPaths.has(routeKey)) throw new Error(`Route ${routeKey} already registered in plugin '${id}'`);
-			registeredPaths.add(routeKey);
-			routes.push({
-				method: "POST",
-				path,
-				handler
-			});
-			return this;
-		},
-		onInit(handler) {
-			if (initHook) throw new Error(`onInit hook already defined for plugin '${id}'`);
-			initHook = handler;
-			return this;
-		},
-		onAuthorize(handler) {
-			if (authorizeHook) throw new Error(`onAuthorize hook already defined for plugin '${id}'`);
-			authorizeHook = handler;
-			return this;
-		},
-		onSuccess(handler) {
-			if (successHook) throw new Error(`onSuccess hook already defined for plugin '${id}'`);
-			successHook = handler;
-			return this;
-		},
-		onError(handler) {
-			if (errorHook) throw new Error(`onError hook already defined for plugin '${id}'`);
-			errorHook = handler;
-			return this;
-		},
-		build() {
-			return {
-				id,
-				routes: routes.length > 0 ? routes : void 0,
-				onInit: initHook,
-				onAuthorize: authorizeHook,
-				onSuccess: successHook,
-				onError: errorHook
-			};
-		}
-	};
-};
-
-//#endregion
-export { plugin };

package/dist/plugin/manager.d.mts

@@ -1,62 +0,0 @@
-import { StorageAdapter } from "../storage/storage.mjs";
-import { Plugin } from "./types.mjs";
-import { Router } from "@draftlab/auth-router";
-
-//#region src/plugin/manager.d.ts
-
-declare class PluginManager {
-  private readonly plugins;
-  private readonly storage;
-  constructor(storage: StorageAdapter);
-  /**
-   * Register a plugin
-   */
-  register(plugin: Plugin): void;
-  /**
-   * Register multiple plugins at once
-   */
-  registerAll(plugins: Plugin[]): void;
-  /**
-   * Get all registered plugins
-   */
-  getAll(): Plugin[];
-  /**
-   * Get plugin by id
-   */
-  get(id: string): Plugin | undefined;
-  /**
-   * Initialize all plugins.
-   * Called once during issuer setup.
-   * Plugins can set up initial state or validate configuration.
-   *
-   * @throws PluginError if any plugin initialization fails
-   */
-  initialize(): Promise<void>;
-  /**
-   * Execute authorize hooks for all plugins.
-   * Called before processing an authorization request.
-   * Can validate, rate limit, or enhance the request.
-   */
-  executeAuthorizeHooks(clientID: string, provider?: string, scopes?: string[]): Promise<void>;
-  /**
-   * Execute success hooks for all plugins.
-   * Called after successful authentication.
-   * Runs in parallel for better performance.
-   * Plugins cannot modify the response.
-   */
-  executeSuccessHooks(clientID: string, provider: string | undefined, subject: {
-    type: string;
-    properties: Record<string, unknown>;
-  }): Promise<void>;
-  /**
-   * Execute error hooks for all plugins.
-   * Called when an authentication error occurs.
-   */
-  executeErrorHooks(error: Error, clientID?: string, provider?: string): Promise<void>;
-  /**
-   * Setup plugin routes on a router
-   */
-  setupRoutes(router: Router): void;
-}
-//#endregion
-export { PluginManager };