@draftlab/auth 0.7.0 → 0.8.0

package/dist/core.mjs

@@ -187,6 +187,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));
@@ -276,10 +285,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();
@@ -498,13 +518,14 @@ 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,
 			...code_challenge && code_challenge_method && { pkce: {
 				challenge: code_challenge,
 				method: code_challenge_method
@@ -520,6 +541,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 +552,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/package.json

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