@draftlab/auth 0.7.0 → 0.9.0

package/dist/client.mjs

@@ -201,7 +201,10 @@ const createClient = (input) => {
 		},
 		async verify(subjects, token, options) {
 			try {
-				const jwtResult = await jwtVerify(token, await getJWKS(), { issuer });
+				const jwtResult = await jwtVerify(token, await getJWKS(), {
+					issuer: options?.issuer ?? issuer,
+					...options?.audience && { audience: options.audience }
+				});
 				const validated = await subjects[jwtResult.payload.type]?.["~standard"].validate(jwtResult.payload.properties);
 				if (!validated?.issues && jwtResult.payload.mode === "access") return {
 					success: true,

package/dist/core.d.mts

@@ -6,6 +6,7 @@ import { StorageAdapter } from "./storage/storage.mjs";
 import { Plugin } from "./plugin/types.mjs";
 import { Provider } from "./provider/provider.mjs";
 import { Theme } from "./themes/theme.mjs";
+import { AuthorizationState } from "./types.mjs";
 import { Router } from "@draftlab/auth-router";
 
 //#region src/core.d.ts
@@ -27,26 +28,6 @@ interface OnSuccessResponder<T$1 extends {
     subject?: string;
   }): Promise<Response>;
 }
-/**
- * Authorization state for OAuth 2.0 flows.
- */
-interface AuthorizationState {
-  /** OAuth redirect URI */
-  redirect_uri: string;
-  /** OAuth response type */
-  response_type: string;
-  /** OAuth state parameter for CSRF protection */
-  state: string;
-  /** OAuth client identifier */
-  client_id: string;
-  /** OAuth audience parameter */
-  audience: string;
-  /** PKCE challenge data for code verification */
-  pkce?: {
-    challenge: string;
-    method: "S256";
-  };
-}
 /**
  * Main issuer input configuration interface.
  */
@@ -129,4 +110,4 @@ declare const issuer: <Providers extends Record<string, Provider<unknown>>, Subj
   };
 }>;
 //#endregion
-export { AuthorizationState, OnSuccessResponder, issuer };
+export { OnSuccessResponder, issuer };

package/dist/core.mjs

@@ -139,7 +139,8 @@ const issuer = (input) => {
 				clientID: value.clientID,
 				subject: value.subject,
 				ttl: value.ttl,
-				nextToken: generateSecureToken()
+				nextToken: generateSecureToken(),
+				timeUsed: value.timeUsed
 			};
 			const refreshKey = [
 				"oauth:refresh",
@@ -187,6 +188,15 @@ const issuer = (input) => {
 			const authorization = await getAuthorization(ctx);
 			const currentProvider = ctx.get("provider") || "unknown";
 			if (!authorization.client_id) throw new Error("client_id is required");
+			if (manager) try {
+				const subjectProperties = properties && typeof properties === "object" ? properties : {};
+				await manager.executeSuccessHooks(authorization.client_id, currentProvider, {
+					type: currentProvider,
+					properties: subjectProperties
+				});
+			} catch (error$1) {
+				console.error("Plugin success hook failed:", error$1);
+			}
 			return await input.success({ async subject(type, properties$1, subjectOpts) {
 				const subject = subjectOpts?.subject ?? await resolveSubject(type, properties$1);
 				await successOpts?.invalidate?.(await resolveSubject(type, properties$1));
@@ -222,6 +232,7 @@ const issuer = (input) => {
 					subject,
 					redirectURI: authorization.redirect_uri,
 					clientID: authorization.client_id,
+					scopes: authorization.scopes,
 					pkce: authorization.pkce,
 					ttl: {
 						access: subjectOpts?.ttl?.access ?? ttlAccess,
@@ -276,10 +287,21 @@ const issuer = (input) => {
 		storage
 	};
 	const app = new Router({ basePath: input.basePath });
-	if (input.plugins && input.plugins.length > 0) {
-		const manager = new PluginManager(input.storage);
+	const manager = input.plugins && input.plugins.length > 0 ? new PluginManager(input.storage) : null;
+	let pluginsInitialized = false;
+	if (manager && input.plugins) {
 		manager.registerAll(input.plugins);
 		manager.setupRoutes(app);
+		app.use(async (c, next) => {
+			if (!pluginsInitialized) try {
+				await manager.initialize();
+				pluginsInitialized = true;
+			} catch (error$1) {
+				console.error("Plugin initialization failed:", error$1);
+				return c.newResponse("Plugin initialization failed", { status: 500 });
+			}
+			return await next();
+		});
 	}
 	for (const [name, value] of Object.entries(input.providers)) {
 		const route = new Router();
@@ -472,13 +494,51 @@ const issuer = (input) => {
 			credentials: false
 		})],
 		handler: async (c) => {
-			const token = (await c.formData()).get("token")?.toString();
+			const form = await c.formData();
+			const token = form.get("token")?.toString();
+			const tokenTypeHint = form.get("token_type_hint")?.toString();
 			if (!token) {
 				const error$1 = new OauthError("invalid_request", "Missing token parameter");
 				return c.json(error$1.toJSON(), { status: 400 });
 			}
 			try {
-				const expiresAt = Date.now() + ttlRefresh * 1e3;
+				if (tokenTypeHint === "refresh_token") {
+					const splits$1 = token.split(":");
+					const tokenPart$1 = splits$1.pop();
+					if (tokenPart$1 && splits$1.length > 0) {
+						const key = [
+							"oauth:refresh",
+							splits$1.join(":"),
+							tokenPart$1
+						];
+						if (await Storage.get(storage, key)) {
+							await Storage.remove(storage, key);
+							const expiresAt$1 = Date.now() + ttlRefreshRetention * 1e3;
+							await Revocation.revoke(storage, token, expiresAt$1);
+							return c.json({});
+						}
+					}
+				} else if (tokenTypeHint === "access_token") {
+					const expiresAt$1 = Date.now() + ttlAccess * 1e3;
+					await Revocation.revoke(storage, token, expiresAt$1);
+					return c.json({});
+				}
+				const splits = token.split(":");
+				const tokenPart = splits.pop();
+				if (tokenPart && splits.length > 0) {
+					const key = [
+						"oauth:refresh",
+						splits.join(":"),
+						tokenPart
+					];
+					if (await Storage.get(storage, key)) {
+						await Storage.remove(storage, key);
+						const expiresAt$1 = Date.now() + ttlRefreshRetention * 1e3;
+						await Revocation.revoke(storage, token, expiresAt$1);
+						return c.json({});
+					}
+				}
+				const expiresAt = Date.now() + ttlAccess * 1e3;
 				await Revocation.revoke(storage, token, expiresAt);
 				return c.json({});
 			} catch (_err) {
@@ -498,13 +558,15 @@ const issuer = (input) => {
 		const audience = c.query("audience");
 		const code_challenge = c.query("code_challenge");
 		const code_challenge_method = c.query("code_challenge_method");
+		const scope = c.query("scope");
 		const authorization = {
 			response_type,
 			redirect_uri,
 			state,
 			client_id,
 			audience,
-			scope: c.query("scope"),
+			scope,
+			scopes: scope ? scope.split(" ").filter(Boolean) : void 0,
 			...code_challenge && code_challenge_method && { pkce: {
 				challenge: code_challenge,
 				method: code_challenge_method
@@ -520,6 +582,10 @@ const issuer = (input) => {
 			redirectURI: redirect_uri,
 			audience
 		}, c.request)) throw new UnauthorizedClientError(client_id, redirect_uri);
+		if (manager) {
+			const scopes = scope ? scope.split(" ") : void 0;
+			await manager.executeAuthorizeHooks(client_id, provider, scopes);
+		}
 		await auth.set(c, "authorization", 900, authorization);
 		if (provider) return c.redirect(`${provider}/authorize`);
 		const availableProviders = Object.keys(input.providers);
@@ -527,6 +593,12 @@ const issuer = (input) => {
 		return auth.forward(c, await select()(Object.fromEntries(Object.entries(input.providers).map(([key, value]) => [key, value.type])), c.request));
 	});
 	app.onError(async (err, c) => {
+		if (manager) try {
+			const errorObj = err instanceof Error ? err : new Error(String(err));
+			await manager.executeErrorHooks(errorObj);
+		} catch (hookError) {
+			console.error("Plugin error hook failed:", hookError);
+		}
 		if (err instanceof UnknownStateError) return auth.forward(c, await error(err, c.request));
 		try {
 			const authorization = await getAuthorization(c);

package/dist/plugin/builder.d.mts

@@ -3,7 +3,24 @@ import { PluginBuilder } from "./plugin.mjs";
 //#region src/plugin/builder.d.ts
 
 /**
- * Create a new plugin
+ * 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

package/dist/plugin/builder.mjs

@@ -1,11 +1,32 @@
 //#region src/plugin/builder.ts
 /**
-* Create a new plugin
+* 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 '/'");
@@ -35,11 +56,34 @@ const plugin = (id) => {
 			});
 			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() {
-			if (routes.length === 0) throw new Error(`Plugin '${id}' has no routes defined`);
 			return {
 				id,
-				routes
+				routes: routes.length > 0 ? routes : void 0,
+				onInit: initHook,
+				onAuthorize: authorizeHook,
+				onSuccess: successHook,
+				onError: errorHook
 			};
 		}
 	};

package/dist/plugin/manager.d.mts

@@ -24,6 +24,35 @@ declare class PluginManager {
    * 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
    */

package/dist/plugin/manager.mjs

@@ -33,6 +33,99 @@ var PluginManager = class {
 		return this.plugins.get(id);
 	}
 	/**
+	* Initialize all plugins.
+	* Called once during issuer setup.
+	* Plugins can set up initial state or validate configuration.
+	*
+	* @throws PluginError if any plugin initialization fails
+	*/
+	async initialize() {
+		for (const plugin of this.plugins.values()) {
+			if (!plugin.onInit) continue;
+			try {
+				const context = {
+					pluginId: plugin.id,
+					request: new Request("http://internal/init"),
+					now: /* @__PURE__ */ new Date(),
+					storage: this.storage
+				};
+				await plugin.onInit(context);
+			} catch (error) {
+				throw new PluginError(`Initialization failed: ${error instanceof Error ? error.message : String(error)}`, plugin.id);
+			}
+		}
+	}
+	/**
+	* Execute authorize hooks for all plugins.
+	* Called before processing an authorization request.
+	* Can validate, rate limit, or enhance the request.
+	*/
+	async executeAuthorizeHooks(clientID, provider, scopes) {
+		for (const plugin of this.plugins.values()) {
+			if (!plugin.onAuthorize) continue;
+			try {
+				const context = {
+					pluginId: plugin.id,
+					request: new Request("http://internal/authorize"),
+					now: /* @__PURE__ */ new Date(),
+					storage: this.storage,
+					clientID,
+					provider,
+					scopes
+				};
+				await plugin.onAuthorize(context);
+			} catch (error) {
+				throw new PluginError(`Authorization hook failed: ${error instanceof Error ? error.message : String(error)}`, plugin.id);
+			}
+		}
+	}
+	/**
+	* Execute success hooks for all plugins.
+	* Called after successful authentication.
+	* Runs in parallel for better performance.
+	* Plugins cannot modify the response.
+	*/
+	async executeSuccessHooks(clientID, provider, subject) {
+		const hooks = Array.from(this.plugins.values()).filter((p) => p.onSuccess).map(async (plugin) => {
+			const context = {
+				pluginId: plugin.id,
+				request: new Request("http://internal/success"),
+				now: /* @__PURE__ */ new Date(),
+				storage: this.storage,
+				clientID,
+				provider,
+				subject
+			};
+			return plugin.onSuccess?.(context).catch((error) => {
+				console.error(`[Plugin: ${plugin.id}] Success hook failed:`, error instanceof Error ? error.message : String(error));
+			});
+		});
+		await Promise.all(hooks);
+	}
+	/**
+	* Execute error hooks for all plugins.
+	* Called when an authentication error occurs.
+	*/
+	async executeErrorHooks(error, clientID, provider) {
+		for (const plugin of this.plugins.values()) {
+			if (!plugin.onError) continue;
+			try {
+				const context = {
+					pluginId: plugin.id,
+					request: new Request("http://internal/error"),
+					now: /* @__PURE__ */ new Date(),
+					storage: this.storage,
+					error,
+					clientID,
+					provider
+				};
+				await plugin.onError(context);
+			} catch (hookError) {
+				console.error(`[Plugin: ${plugin.id}] Error hook failed:`, hookError instanceof Error ? hookError.message : String(hookError));
+			}
+		}
+	}
+	/**
 	* Setup plugin routes on a router
 	*/
 	setupRoutes(router) {
@@ -40,7 +133,7 @@ var PluginManager = class {
 		for (const plugin of this.plugins.values()) {
 			if (!plugin.routes) continue;
 			for (const route of plugin.routes) {
-				const fullPath = `/${plugin.id}${route.path}`;
+				const fullPath = `/plugin/${plugin.id}${route.path}`;
 				if (registeredPaths.has(fullPath)) throw new PluginError(`Route conflict: ${fullPath} already registered`, plugin.id);
 				registeredPaths.add(fullPath);
 				const handler = async (ctx) => {

package/dist/plugin/plugin.d.mts

@@ -1,16 +1,41 @@
-import { Plugin, PluginRouteHandler } from "./types.mjs";
+import { Plugin, PluginAuthorizeHook, PluginErrorHook, PluginInitHook, PluginRouteHandler, PluginSuccessHook } from "./types.mjs";
 
 //#region src/plugin/plugin.d.ts
 
 /**
- * Plugin builder interface
+ * Plugin builder interface for creating plugins with a fluent API.
+ *
+ * The builder pattern allows for elegant plugin definition:
+ * - Chain route definitions with lifecycle hooks
+ * - Each method returns this for chaining
+ * - Build finalizes the plugin definition
+ *
+ * @example
+ * ```ts
+ * const myPlugin = plugin("my-plugin")
+ *   .onInit(async (ctx) => {
+ *     console.log("Plugin initialized")
+ *   })
+ *   .post("/action", async (ctx) => {
+ *     return ctx.json({ success: true })
+ *   })
+ *   .build()
+ * ```
  */
 interface PluginBuilder {
-  /** Add GET route */
+  /** Register a GET route */
   get(path: string, handler: PluginRouteHandler): PluginBuilder;
-  /** Add POST route */
+  /** Register a POST route */
   post(path: string, handler: PluginRouteHandler): PluginBuilder;
-  /** Build the plugin */
+  /** Register initialization hook (called once during issuer setup) */
+  onInit(handler: PluginInitHook): PluginBuilder;
+  /** Register authorization hook (called before authorization request) */
+  onAuthorize(handler: PluginAuthorizeHook): PluginBuilder;
+  /** Register success hook (called after successful authentication) */
+  onSuccess(handler: PluginSuccessHook): PluginBuilder;
+  /** Register error hook (called when authentication fails) */
+  onError(handler: PluginErrorHook): PluginBuilder;
+  /** Build the final plugin */
   build(): Plugin;
 }
 //#endregion

package/dist/plugin/types.d.mts

@@ -22,13 +22,72 @@ interface PluginRoute {
   readonly handler: PluginRouteHandler;
 }
 /**
- * Main plugin interface
+ * Lifecycle hook context provided to plugin hooks.
+ * Contains information about the current operation and access to isolated storage.
+ */
+interface PluginHookContext {
+  /** Unique identifier for the plugin */
+  pluginId: string;
+  /** Raw request object */
+  request: Request;
+  /** Current time for consistency across hook execution */
+  now: Date;
+  /** Storage adapter for data persistence */
+  storage: StorageAdapter;
+}
+/**
+ * Hook called when the issuer is being initialized.
+ * Useful for plugins that need to set up initial state or validate configuration.
+ * Should complete quickly - takes place during server startup.
+ */
+type PluginInitHook = (context: PluginHookContext) => Promise<void>;
+/**
+ * Hook called before an authorization request is processed.
+ * Use for validation, rate limiting, or request enhancement.
+ */
+type PluginAuthorizeHook = (context: PluginHookContext & {
+  clientID: string;
+  provider?: string;
+  scopes?: string[];
+}) => Promise<void>;
+/**
+ * Hook called after successful authentication.
+ * Use for logging, analytics, webhooks, or side effects.
+ * Cannot modify the response - hooks run in parallel.
+ */
+type PluginSuccessHook = (context: PluginHookContext & {
+  clientID: string;
+  provider?: string;
+  subject: {
+    type: string;
+    properties: Record<string, unknown>;
+  };
+}) => Promise<void>;
+/**
+ * Hook called when an authentication error occurs.
+ * Use for error logging, custom error pages, or error transformation.
+ */
+type PluginErrorHook = (context: PluginHookContext & {
+  error: Error;
+  clientID?: string;
+  provider?: string;
+}) => Promise<void>;
+/**
+ * Main plugin interface with lifecycle hooks and storage isolation
  */
 interface Plugin {
   /** Unique plugin identifier */
   readonly id: string;
   /** Custom routes added by this plugin */
   readonly routes?: readonly PluginRoute[];
+  /** Called once when the issuer initializes */
+  readonly onInit?: PluginInitHook;
+  /** Called before authorization request is processed */
+  readonly onAuthorize?: PluginAuthorizeHook;
+  /** Called after successful authentication */
+  readonly onSuccess?: PluginSuccessHook;
+  /** Called when an error occurs during authentication */
+  readonly onError?: PluginErrorHook;
 }
 /**
  * Plugin error types
@@ -37,4 +96,4 @@ declare class PluginError extends Error {
   constructor(message: string, pluginId: string);
 }
 //#endregion
-export { Plugin, PluginContext, PluginError, PluginRoute, PluginRouteHandler };
+export { Plugin, PluginAuthorizeHook, PluginContext, PluginError, PluginErrorHook, PluginHookContext, PluginInitHook, PluginRoute, PluginRouteHandler, PluginSuccessHook };

package/dist/provider/oauth2.mjs

@@ -2,6 +2,7 @@ import { getRelativeUrl } from "../util.mjs";
 import { OauthError } from "../error.mjs";
 import { generatePKCE } from "../pkce.mjs";
 import { generateSecureToken, timingSafeCompare } from "../random.mjs";
+import { createRemoteJWKSet, jwtVerify } from "jose";
 
 //#region src/provider/oauth2.ts
 /**
@@ -70,6 +71,12 @@ const Oauth2Provider = (config) => {
 			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 || "");
+			if (tokenData.id_token && config.endpoint.jwks) try {
+				const jwks = createRemoteJWKSet(new URL(config.endpoint.jwks));
+				await jwtVerify(tokenData.id_token, jwks, { issuer: config.endpoint.authorization.split("/").slice(0, 3).join("/") });
+			} catch (error) {
+				throw new OauthError("invalid_request", `ID token validation failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
 			return await ctx.success(c, {
 				clientID: config.clientID,
 				tokenset: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftlab/auth",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Core implementation for @draftlab/auth",
   "author": "Matheus Pergoli",
@@ -39,7 +39,7 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/qrcode": "^1.5.6",
-    "tsdown": "^0.16.6",
+    "tsdown": "^0.16.7",
     "typescript": "^5.9.3",
     "@draftlab/tsconfig": "0.1.0"
   },
@@ -63,7 +63,7 @@
     "preact": "^10.27.2",
     "preact-render-to-string": "^6.6.3",
     "qrcode": "^1.5.4",
-    "@draftlab/auth-router": "0.1.0"
+    "@draftlab/auth-router": "0.2.0"
   },
   "engines": {
     "node": ">=18"