Add onProtectedRequest hook (x402-foundation#1010)

* add new onRequest hook

* add unit tests

Author: phdargen

typescript/packages/core/src/http/index.ts

@@ -99,6 +99,7 @@ export {
   ProcessSettleFailureResponse,
   RouteValidationError,
   RouteConfigurationError,
+  ProtectedRequestHook,
 } from "./x402HTTPResourceServer";
 export {
   HTTPFacilitatorClient,

typescript/packages/core/src/http/x402HTTPResourceServer.ts

@@ -155,6 +155,20 @@ export interface RouteConfig {
  */
 export type RoutesConfig = Record<string, RouteConfig> | RouteConfig;
 
+/**
+ * Hook that runs on every request to a protected route, before payment processing.
+ * Can grant access without payment, deny the request, or continue to payment flow.
+ *
+ * @returns
+ * - `void` - Continue to payment processing (default behavior)
+ * - `{ grantAccess: true }` - Grant access without requiring payment
+ * - `{ abort: true; reason: string }` - Deny the request (returns 403)
+ */
+export type ProtectedRequestHook = (
+  context: HTTPRequestContext,
+  routeConfig: RouteConfig,
+) => Promise<void | { grantAccess: true } | { abort: true; reason: string }>;
+
 /**
  * Compiled route for efficient matching
  */
@@ -260,6 +274,7 @@ export class x402HTTPResourceServer {
   private compiledRoutes: CompiledRoute[] = [];
   private routesConfig: RoutesConfig;
   private paywallProvider?: PaywallProvider;
+  private protectedRequestHooks: ProtectedRequestHook[] = [];
 
   /**
    * Creates a new x402HTTPResourceServer instance.
@@ -287,6 +302,24 @@ export class x402HTTPResourceServer {
     }
   }
 
+  /**
+   * Get the underlying x402ResourceServer instance.
+   *
+   * @returns The underlying x402ResourceServer instance
+   */
+  get server(): x402ResourceServer {
+    return this.ResourceServer;
+  }
+
+  /**
+   * Get the routes configuration.
+   *
+   * @returns The routes configuration
+   */
+  get routes(): RoutesConfig {
+    return this.routesConfig;
+  }
+
   /**
    * Initialize the HTTP resource server.
    *
@@ -325,6 +358,18 @@ export class x402HTTPResourceServer {
     return this;
   }
 
+  /**
+   * Register a hook that runs on every request to a protected route, before payment processing.
+   * Hooks are executed in order of registration. The first hook to return a non-void result wins.
+   *
+   * @param hook - The request hook function
+   * @returns The x402HTTPResourceServer instance for chaining
+   */
+  onProtectedRequest(hook: ProtectedRequestHook): this {
+    this.protectedRequestHooks.push(hook);
+    return this;
+  }
+
   /**
    * Process HTTP request and return response instructions
    * This is the main entry point for framework middleware
@@ -345,6 +390,24 @@ export class x402HTTPResourceServer {
       return { type: "no-payment-required" }; // No payment required for this route
     }
 
+    // Execute request hooks before any payment processing
+    for (const hook of this.protectedRequestHooks) {
+      const result = await hook(context, routeConfig);
+      if (result && "grantAccess" in result) {
+        return { type: "no-payment-required" };
+      }
+      if (result && "abort" in result) {
+        return {
+          type: "payment-error",
+          response: {
+            status: 403,
+            headers: { "Content-Type": "application/json" },
+            body: { error: result.reason },
+          },
+        };
+      }
+    }
+
     // Normalize accepts field to array of payment options
     const paymentOptions = this.normalizePaymentOptions(routeConfig);
 

typescript/packages/core/src/server/index.ts

@@ -1,5 +1,5 @@
 export { x402ResourceServer } from "./x402ResourceServer";
-export type { ResourceConfig, ResourceInfo } from "./x402ResourceServer";
+export type { ResourceConfig, ResourceInfo, SettleResultContext } from "./x402ResourceServer";
 
 export { HTTPFacilitatorClient } from "../http/httpFacilitatorClient";
 export type { FacilitatorClient, FacilitatorConfig } from "../http/httpFacilitatorClient";