@spfn/core 0.2.0-beta.9 → 0.3.0-beta.10

package/dist/nextjs/server.d.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { Router, HttpMethod } from '@spfn/core/route';
+import { HttpMethod } from '@spfn/core/route';
 import { InterceptorRule as InterceptorRule$1 } from '@spfn/core/nextjs/server';
-import { f as SetCookie } from '../types-BOPTApC2.js';
+import { S as SetCookie } from '../types-9oszaJqp.js';
 import '@sinclair/typebox';
 import '@spfn/core/errors';
 
@@ -44,9 +44,11 @@ interface TypedProxyConfig {
      */
     debug?: boolean;
     /**
-     * Request timeout in milliseconds
+     * RPC proxy request timeout in milliseconds
+     * AbortController timeout - cancels proxied request if backend doesn't respond in time
+     * Should be shorter than FETCH_HEADERS_TIMEOUT to ensure meaningful 504 response
      *
-     * @default 30000
+     * @default env.RPC_PROXY_TIMEOUT (120000)
      */
     timeout?: number;
     /**
@@ -115,22 +117,17 @@ interface TypedProxyConfig {
  * Next.js API Route handler that resolves routeName to method/path
  * and forwards requests to SPFN backend.
  *
- * @example Using routeMap (recommended - no server code loaded)
+ * @example
  * ```typescript
  * // app/api/rpc/[routeName]/route.ts
+ * import { createRpcProxy } from '@spfn/core/nextjs/server';
+ * import { authRouteMap } from '@spfn/auth';
+ * import { eventRouteMap } from '@spfn/core/event';
  * import { routeMap } from '@/generated/route-map';
- * import { createRpcProxy } from '@spfn/core/nextjs/proxy';
- *
- * export const { GET, POST } = createRpcProxy({ routeMap });
- * ```
- *
- * @example Using router (legacy - loads full server code)
- * ```typescript
- * // app/api/rpc/[routeName]/route.ts
- * import { appRouter } from '@/server/router';
- * import { createRpcProxy } from '@spfn/core/nextjs/proxy';
  *
- * export const { GET, POST } = createRpcProxy({ router: appRouter });
+ * export const { GET, POST } = createRpcProxy({
+ *     routeMap: { ...routeMap, ...authRouteMap, ...eventRouteMap },
+ * });
  * ```
  */
 
@@ -146,54 +143,37 @@ interface RouteMapEntry {
  */
 type RouteMap = Record<string, RouteMapEntry>;
 /**
- * Base config for RPC proxy
- */
-interface RpcProxyBaseConfig extends Omit<TypedProxyConfig, 'onRequest' | 'onResponse'> {
-}
-/**
- * Config using routeMap (recommended)
- *
- * Uses generated route map file - no server code loaded in Next.js process.
+ * RPC proxy configuration
  */
-interface RpcProxyRouteMapConfig extends RpcProxyBaseConfig {
+interface RpcProxyConfig extends Omit<TypedProxyConfig, 'onRequest' | 'onResponse'> {
     /**
-     * Generated route map containing routeName → {method, path} mappings
+     * Route map containing routeName → {method, path} mappings
+     *
+     * Merge generated route map with package route maps (auth, events, etc.)
      *
      * @example
      * ```typescript
+     * import { authRouteMap } from '@spfn/auth';
+     * import { eventRouteMap } from '@spfn/core/event';
      * import { routeMap } from '@/generated/route-map';
      *
-     * export const { GET, POST } = createRpcProxy({ routeMap });
+     * export const { GET, POST } = createRpcProxy({
+     *     routeMap: { ...routeMap, ...authRouteMap, ...eventRouteMap },
+     * });
      * ```
      */
     routeMap: RouteMap;
-    router?: never;
-}
-/**
- * Config using router (legacy)
- *
- * @deprecated Use routeMap instead to avoid loading server code in Next.js process
- */
-interface RpcProxyRouterConfig<TRouter extends Router<any>> extends RpcProxyBaseConfig {
     /**
-     * The router containing all route definitions
+     * Shared secret for signing proxy→backend requests (HMAC-SHA256).
      *
-     * @deprecated Use routeMap instead - router imports all server code
+     * When set, every forwarded request carries an HMAC signature the backend's
+     * proxy-guard middleware verifies, letting it reject direct-to-backend calls
+     * that bypass this proxy. Set the SAME value here and on the backend.
      *
-     * @example
-     * ```typescript
-     * export const { GET, POST } = createRpcProxy({
-     *     router: appRouter,
-     * });
-     * ```
+     * @default process.env.SPFN_PROXY_SECRET (undefined → signing disabled)
      */
-    router: TRouter;
-    routeMap?: never;
+    proxySecret?: string;
 }
-/**
- * Combined config type
- */
-type RpcProxyConfig<TRouter extends Router<any> = Router<any>> = RpcProxyRouteMapConfig | RpcProxyRouterConfig<TRouter>;
 /**
  * Create RPC proxy handler for Next.js API Route
  *
@@ -201,10 +181,10 @@ type RpcProxyConfig<TRouter extends Router<any> = Router<any>> = RpcProxyRouteMa
  * - GET /api/rpc/{routeName}?input={...}
  * - POST /api/rpc/{routeName} with body
  *
- * Resolves routeName to actual HTTP method and path from the router or routeMap,
+ * Resolves routeName to actual HTTP method and path from routeMap,
  * then forwards to SPFN backend.
  */
-declare function createRpcProxy<TRouter extends Router<any>>(config: RpcProxyConfig<TRouter>): {
+declare function createRpcProxy(config: RpcProxyConfig): {
     GET: (req: NextRequest, context: {
         params: Promise<{
             routeName?: string;
@@ -262,6 +242,28 @@ interface InterceptorRule {
      */
     response?: ResponseInterceptor;
 }
+/**
+ * Response an interceptor refuses a request with
+ */
+interface ProxyAbort {
+    /** HTTP status returned to the caller */
+    status: number;
+    /** JSON body returned to the caller */
+    body: unknown;
+    /**
+     * Cookies to set on the refusal itself
+     *
+     * A refusal skips the backend and every response interceptor, so this is the
+     * only way a refused request can hand the browser anything. The CSRF check in
+     * @spfn/auth uses it to reissue the readable token cookie on the 403 it emits,
+     * which is what makes "retry and it works" true rather than aspirational: the
+     * client that was refused now holds the value the next attempt needs.
+     *
+     * Set nothing an unauthenticated caller could not already have — a refusal is
+     * reachable by whoever sent the request.
+     */
+    setCookies?: SetCookie[];
+}
 /**
  * Request Interceptor Context
  *
@@ -300,6 +302,17 @@ interface RequestInterceptorContext {
      * Metadata for sharing data between interceptors
      */
     metadata: Record<string, any>;
+    /**
+     * Refuse the request without calling the backend
+     *
+     * An interceptor that sets this stops the proxy before the fetch: the status
+     * and body are returned to the caller as-is and no response interceptor runs.
+     * A refusal therefore sets only the cookies the refusing interceptor put on
+     * `abort.setCookies` itself. Used by the CSRF check in @spfn/auth, the only
+     * layer that knows a request was authenticated from the session cookie rather
+     * than from a caller-supplied bearer token.
+     */
+    abort?: ProxyAbort;
 }
 /**
  * Response Interceptor Context
@@ -332,6 +345,10 @@ interface ResponseInterceptorContext {
         headers: Headers;
         body: any;
     };
+    /**
+     * Cookies from original request (read-only)
+     */
+    cookies: Map<string, string>;
     /**
      * Cookies to set in response
      *
@@ -627,4 +644,4 @@ declare const interceptorRegistry: InterceptorRegistry;
  */
 declare function registerInterceptors(packageName: string, interceptors: InterceptorRule[]): void;
 
-export { type InterceptorRule, type ProxyConfig, type RequestInterceptor, type RequestInterceptorContext, type ResponseInterceptor, type ResponseInterceptorContext, type RpcProxyConfig, createRpcProxy, executeRequestInterceptors, executeResponseInterceptors, filterMatchingInterceptors, interceptorRegistry, matchMethod, matchPath, registerInterceptors };
+export { type InterceptorRule, type ProxyAbort, type ProxyConfig, type RequestInterceptor, type RequestInterceptorContext, type ResponseInterceptor, type ResponseInterceptorContext, type RpcProxyConfig, createRpcProxy, executeRequestInterceptors, executeResponseInterceptors, filterMatchingInterceptors, interceptorRegistry, matchMethod, matchPath, registerInterceptors };

package/dist/nextjs/server.js

@@ -1,8 +1,77 @@
 import { NextResponse } from 'next/server';
 import { env } from '@spfn/core/config';
 import { logger } from '@spfn/core/logger';
+import { randomBytes, createHmac, createHash } from 'crypto';
 
 // src/nextjs/proxy/rpc.ts
+var PROXY_SIGNATURE_HEADER = "x-spfn-proxy-signature";
+var PROXY_TIMESTAMP_HEADER = "x-spfn-proxy-timestamp";
+var PROXY_NONCE_HEADER = "x-spfn-proxy-nonce";
+var PROXY_KEY_ID_HEADER = "x-spfn-proxy-key-id";
+var PROXY_CLIENT_IP_HEADER = "x-spfn-proxy-client-ip";
+var DEFAULT_KEY_ID = "default";
+function parseProxyKey(raw) {
+  const idx = raw.indexOf(":");
+  if (idx === -1) {
+    return { keyId: DEFAULT_KEY_ID, secret: raw };
+  }
+  return { keyId: raw.slice(0, idx) || DEFAULT_KEY_ID, secret: raw.slice(idx + 1) };
+}
+function parseProxyKeySet(raws) {
+  const keys = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of raws) {
+    if (!raw) {
+      continue;
+    }
+    for (const part of raw.split(",")) {
+      const trimmed = part.trim();
+      if (!trimmed) {
+        continue;
+      }
+      const key = parseProxyKey(trimmed);
+      if (!key.secret || seen.has(key.keyId)) {
+        continue;
+      }
+      seen.add(key.keyId);
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+function buildCanonicalString(parts) {
+  return [parts.method.toUpperCase(), parts.path, parts.query, parts.timestamp, parts.nonce, parts.bodyHash].join("\n");
+}
+function hashBody(body) {
+  if (!body || body.length === 0) {
+    return "";
+  }
+  return typeof body === "string" ? createHash("sha256").update(body, "utf8").digest("hex") : createHash("sha256").update(body).digest("hex");
+}
+function computeSignature(secret, parts) {
+  return createHmac("sha256", secret).update(buildCanonicalString(parts)).digest("hex");
+}
+function generateNonce() {
+  return randomBytes(16).toString("hex");
+}
+function signProxyRequest(input) {
+  const timestamp = input.timestamp ?? String(Date.now());
+  const nonce = input.nonce ?? generateNonce();
+  const signature = computeSignature(input.key.secret, {
+    method: input.method,
+    path: input.path,
+    query: input.query ?? "",
+    timestamp,
+    nonce,
+    bodyHash: hashBody(input.body)
+  });
+  return {
+    [PROXY_SIGNATURE_HEADER]: signature,
+    [PROXY_TIMESTAMP_HEADER]: timestamp,
+    [PROXY_NONCE_HEADER]: nonce,
+    [PROXY_KEY_ID_HEADER]: input.key.keyId
+  };
+}
 
 // src/nextjs/shared.ts
 function buildUrlWithParams(path, params) {
@@ -188,6 +257,17 @@ function registerInterceptors(packageName, interceptors) {
 }
 
 // src/nextjs/proxy/helpers.ts
+function clientIpFromForwardedChain(xff, trustedHops) {
+  if (!xff) return void 0;
+  const parts = xff.split(",").map((s) => s.trim()).filter(Boolean);
+  if (parts.length === 0) return void 0;
+  const idx = parts.length - Math.max(1, trustedHops);
+  return parts[idx] ?? parts[0];
+}
+function trustedProxyHops() {
+  const raw = Number.parseInt(process.env.TRUSTED_PROXY_HOPS ?? "", 10);
+  return Number.isFinite(raw) && raw > 0 ? raw : 1;
+}
 function buildProxyHeaders(sourceHeaders, defaultHeaders) {
   const headers = new Headers();
   const headersToForward2 = [
@@ -196,7 +276,10 @@ function buildProxyHeaders(sourceHeaders, defaultHeaders) {
     "cookie",
     "user-agent",
     "accept",
-    "accept-language"
+    "accept-language",
+    // Forwarded so the backend proxy-guard can enforce its origin allowlist on
+    // the real browser Origin; without this allowedOrigins would be a no-op.
+    "origin"
   ];
   for (const header of headersToForward2) {
     const value = sourceHeaders instanceof Headers ? sourceHeaders.get(header) : sourceHeaders[header];
@@ -204,6 +287,11 @@ function buildProxyHeaders(sourceHeaders, defaultHeaders) {
       headers.set(header, value);
     }
   }
+  const xff = sourceHeaders instanceof Headers ? sourceHeaders.get("x-forwarded-for") : sourceHeaders["x-forwarded-for"];
+  const clientIp = clientIpFromForwardedChain(xff, trustedProxyHops());
+  if (clientIp) {
+    headers.set(PROXY_CLIENT_IP_HEADER, clientIp);
+  }
   for (const [key, value] of Object.entries(defaultHeaders)) {
     headers.set(key, value);
   }
@@ -305,7 +393,7 @@ function buildRequestContext(path, method, headers, body, searchParams, cookiesM
     metadata: {}
   };
 }
-function buildResponseContext(path, method, requestHeaders, requestBody, response, responseBody, requestMetadata) {
+function buildResponseContext(path, method, requestHeaders, requestBody, response, responseBody, requestMetadata, cookies) {
   return {
     path: `/${path}`,
     method,
@@ -320,6 +408,7 @@ function buildResponseContext(path, method, requestHeaders, requestBody, respons
       headers: response.headers,
       body: responseBody
     },
+    cookies,
     setCookies: [],
     metadata: requestMetadata
   };
@@ -327,71 +416,34 @@ function buildResponseContext(path, method, requestHeaders, requestBody, respons
 
 // src/nextjs/proxy/rpc.ts
 var rpcLogger = logger.child("@spfn/core:rpc-proxy");
-function isRouteDef(value) {
-  return value !== null && typeof value === "object" && "handler" in value && "method" in value && "path" in value;
-}
-function isRouter(value) {
-  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
-}
-function getRouteByPath(router, routePath) {
-  const parts = routePath.split(".");
-  let current = router.routes;
-  for (const part of parts) {
-    if (!current || typeof current !== "object") {
-      return null;
-    }
-    const next = current[part];
-    if (isRouter(next)) {
-      current = next.routes;
-    } else if (isRouteDef(next)) {
-      return next;
-    } else {
-      current = next;
-    }
-  }
-  if (isRouteDef(current)) {
-    return current;
-  }
-  return null;
-}
 function createRpcProxy(config) {
   const {
     apiUrl = env.SPFN_API_URL || "http://localhost:8790",
     debug = env.NODE_ENV === "development",
-    timeout = 3e4,
+    timeout = env.RPC_PROXY_TIMEOUT,
     headers: defaultHeaders = {},
     interceptors,
     autoDiscoverInterceptors = true,
-    disableAutoInterceptors
+    disableAutoInterceptors,
+    proxySecret = env.SPFN_PROXY_SECRET,
+    routeMap
   } = config;
-  const useRouteMap = "routeMap" in config && config.routeMap !== void 0;
-  const routeMap = useRouteMap ? config.routeMap : null;
-  const router = !useRouteMap && "router" in config ? config.router : null;
-  const packageRouters = router?._packageRouters || [];
-  function resolveRoute(routeName) {
-    if (routeMap) {
-      const entry = routeMap[routeName];
-      if (entry) {
-        return { method: entry.method, path: entry.path };
+  const proxyKey = proxySecret ? parseProxyKeySet([proxySecret])[0] ?? null : null;
+  if (proxyKey) {
+    try {
+      const basePath = new URL(apiUrl).pathname;
+      if (basePath !== "/" && basePath !== "") {
+        rpcLogger.warn(
+          `SPFN_API_URL has a base path ("${basePath}"). proxy-guard signs route-relative paths, so the backend must receive paths WITHOUT this prefix (e.g. ingress strip) or strict mode will reject all signed requests with 403.`
+        );
       }
-      return null;
+    } catch {
     }
-    if (router) {
-      let routeDef = getRouteByPath(router, routeName);
-      if (!routeDef && packageRouters.length > 0) {
-        for (const pkgRouter of packageRouters) {
-          routeDef = getRouteByPath(pkgRouter, routeName);
-          if (routeDef) {
-            if (debug) {
-              rpcLogger.debug(`Route "${routeName}" found in package router`);
-            }
-            break;
-          }
-        }
-      }
-      if (routeDef && routeDef.method && routeDef.path) {
-        return { method: routeDef.method, path: routeDef.path };
-      }
+  }
+  function resolveRoute(routeName) {
+    const entry = routeMap[routeName];
+    if (entry) {
+      return { method: entry.method, path: entry.path };
     }
     return null;
   }
@@ -515,7 +567,7 @@ function createRpcProxy(config) {
       const allInterceptors = collectInterceptors(autoDiscoverInterceptors, disableAutoInterceptors, interceptors, interceptorRegistry);
       const matchingInterceptors = filterMatchingInterceptors(allInterceptors, resolvedPath, targetMethod);
       if (debug && matchingInterceptors.length > 0) {
-        rpcLogger.debug(`\u{1F3AF} Found ${matchingInterceptors.length} matching interceptors for ${targetMethod} ${resolvedPath}`);
+        rpcLogger.debug(`Found ${matchingInterceptors.length} matching interceptors for ${targetMethod} ${resolvedPath}`);
       }
       const cookiesMap = parseCookiesFromNextRequest(request);
       const requestCtx = buildRequestContext(
@@ -539,6 +591,33 @@ function createRpcProxy(config) {
           fetchOptions.body = JSON.stringify(requestCtx.body);
         }
       }
+      if (requestCtx.abort) {
+        rpcLogger.warn("Request refused by an interceptor", {
+          routeName,
+          status: requestCtx.abort.status
+        });
+        const abortResponse = NextResponse.json(
+          requestCtx.abort.body,
+          { status: requestCtx.abort.status }
+        );
+        for (const cookie of requestCtx.abort.setCookies ?? []) {
+          abortResponse.headers.append("Set-Cookie", buildSetCookieHeader(cookie));
+        }
+        return abortResponse;
+      }
+      if (proxyKey) {
+        const signedBody = typeof fetchOptions.body === "string" ? fetchOptions.body : void 0;
+        const signatureHeaders = signProxyRequest({
+          key: proxyKey,
+          method: targetMethod,
+          path: resolvedPath,
+          query: queryString,
+          body: signedBody
+        });
+        for (const [headerName, value] of Object.entries(signatureHeaders)) {
+          headers.set(headerName, value);
+        }
+      }
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeout);
       try {
@@ -555,7 +634,8 @@ function createRpcProxy(config) {
           inputBody,
           response,
           body,
-          requestCtx.metadata
+          requestCtx.metadata,
+          requestCtx.cookies
         );
         const responseInterceptorsToRun = matchingInterceptors.map((r) => r.response).filter((i) => !!i);
         if (responseInterceptorsToRun.length > 0) {
@@ -582,7 +662,7 @@ function createRpcProxy(config) {
           const setCookieHeader = buildSetCookieHeader(cookie);
           nextResponse.headers.append("Set-Cookie", setCookieHeader);
           if (debug) {
-            rpcLogger.debug("\u{1F36A} Set-Cookie header added", {
+            rpcLogger.debug("Set-Cookie header added", {
               name: cookie.name
             });
           }