@authhero/proxy 0.4.5 → 0.5.1

package/dist/proxy.d.ts

@@ -1,4 +1,4 @@
-import { ProxyRoute, ProxyRoutesAdapter, RouteMatch, HandlerConfig } from '@authhero/adapter-interfaces';
+import { ProxyRoute, ProxyRoutesAdapter, CacheAdapter, RouteMatch, HandlerConfig } from '@authhero/adapter-interfaces';
 export { HandlerConfig, ListProxyRoutesParams, ListProxyRoutesResult, ProxyRoute, ProxyRouteInsert, ProxyRouteUpdate, ProxyRoutesAdapter, RouteMatch, handlerConfigSchema, matchSchema, proxyRouteInsertSchema, proxyRouteSchema, proxyRouteUpdateSchema } from '@authhero/adapter-interfaces';
 import { MiddlewareHandler, Hono, Context } from 'hono';
 import { z } from '@hono/zod-openapi';
@@ -57,6 +57,7 @@ interface ProxyAppOptions {
     data: ProxyDataAdapter;
     cacheTtlMs?: number;
     cache?: HostCacheOptions;
+    resolver?: HostResolverCache;
     registry?: HandlerRegistry;
     bindings?: Record<string, unknown>;
 }
@@ -89,10 +90,53 @@ interface CacheApiHostCacheOptions {
  * Invalidation is the caller's responsibility — typically the control plane
  * issues `cache.delete(syntheticKey(...))` on every proxy_route mutation,
  * and each colo's cache expires on its own TTL otherwise.
+ *
+ * @deprecated Prefer `createCacheAdapterHostCache` with `createCloudflareCache`
+ * from `@authhero/cloudflare-adapter`. The adapter-based wrapper supports
+ * stale-while-revalidate and works with any `CacheAdapter` (Cloudflare,
+ * Redis, in-memory, …).
  */
 declare function createCacheApiHostCache(options: CacheApiHostCacheOptions): HostResolverCache;
 declare function buildCacheApiKey(namespace: string, host: string): Request;
 
+interface CacheAdapterHostCacheOptions {
+    upstream: HostResolverCache;
+    cache: CacheAdapter;
+    freshTtlMs: number;
+    staleTtlMs?: number;
+    negativeTtlMs?: number;
+    keyPrefix?: string;
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * Wraps an upstream `HostResolverCache` with a generic `CacheAdapter` layer.
+ * Adds stale-while-revalidate semantics on top of any cache implementation
+ * — Cloudflare Cache API (via `CloudflareCache` from `@authhero/cloudflare-adapter`),
+ * Redis, in-memory, or anything else satisfying the `CacheAdapter` interface.
+ *
+ * Typical use on Cloudflare Workers:
+ *
+ * ```ts
+ * import { createCloudflareCache } from "@authhero/cloudflare-adapter";
+ * import { createCacheAdapterHostCache, createInMemoryHostCache } from "@authhero/proxy";
+ *
+ * const cache = createCloudflareCache({ cacheName: "authhero-proxy-hosts" });
+ * const resolver = createCacheAdapterHostCache({
+ *   upstream: createInMemoryHostCache(data, { freshTtlMs: 60_000 }),
+ *   cache,
+ *   freshTtlMs: 60 * 60_000,           // 1 hour fresh
+ *   staleTtlMs: 23 * 60 * 60_000,      // SWR for 23 more hours (24h total)
+ *   waitUntil: (p) => ctx.waitUntil(p),
+ * });
+ * ```
+ *
+ * Invalidation is the caller's responsibility — when a host's routes change,
+ * call `cache.delete(buildCacheAdapterKey(keyPrefix, host))` from the control
+ * plane. Otherwise entries expire on their own TTL.
+ */
+declare function createCacheAdapterHostCache(options: CacheAdapterHostCacheOptions): HostResolverCache;
+declare function buildCacheAdapterKey(keyPrefix: string, host: string): string;
+
 declare const corsHandler: HandlerDefinition<{
     origins?: string[] | undefined;
     allow_credentials?: boolean | undefined;
@@ -232,6 +276,7 @@ interface HttpProxyAdapterOptions {
     clientId: string;
     clientSecret: string;
     audience?: string;
+    scope?: string;
     resolveHostPath?: string;
     tokenRefreshSkewSeconds?: number;
     timeoutMs?: number;
@@ -249,5 +294,13 @@ interface HttpProxyAdapterOptions {
  */
 declare function createHttpProxyAdapter(options: HttpProxyAdapterOptions): ProxyDataAdapter;
 
-export { HandlerRegistry, basicAuthHandler, buildCacheApiKey, buildMatchFilter, cacheHandler, compileHostApp, corsHandler, createCacheApiHostCache, createHttpProxyAdapter, createInMemoryHostCache, createProxyApp, createProxyDataPlaneHandler, createProxyDataPlaneRouter, createStaticProxyAdapter, defineHandler, dispatchNamespaceHandler, forwardedHeadersHandler, headersHandler, httpHandler, httpRoute, matchesAnyHost, matchesHost, redirectHandler, registerBuiltinHandlers, rewriteCookiesHandler, rewriteLocationHandler, serviceBindingHandler, sortRoutes, staticHandler };
-export type { CacheApiHostCacheOptions, HandlerBuildContext, HandlerDefinition, HostCacheOptions, HostResolverCache, HttpProxyAdapterOptions, ProxyAppOptions, ProxyDataAdapter, ProxyDataPlaneOptions, ResolvedHost, StaticHostConfig, StaticProxyAdapterOptions, StaticRouteInput };
+/**
+ * Scope a control-plane bearer token must carry to call
+ * `GET /api/v2/proxy/control-plane/hosts/:host` or `POST /sync`. The data
+ * plane requests it when minting tokens; the control plane requires it when
+ * verifying them.
+ */
+declare const PROXY_RESOLVE_HOST_SCOPE = "proxy:resolve_host";
+
+export { HandlerRegistry, PROXY_RESOLVE_HOST_SCOPE, basicAuthHandler, buildCacheAdapterKey, buildCacheApiKey, buildMatchFilter, cacheHandler, compileHostApp, corsHandler, createCacheAdapterHostCache, createCacheApiHostCache, createHttpProxyAdapter, createInMemoryHostCache, createProxyApp, createProxyDataPlaneHandler, createProxyDataPlaneRouter, createStaticProxyAdapter, defineHandler, dispatchNamespaceHandler, forwardedHeadersHandler, headersHandler, httpHandler, httpRoute, matchesAnyHost, matchesHost, redirectHandler, registerBuiltinHandlers, rewriteCookiesHandler, rewriteLocationHandler, serviceBindingHandler, sortRoutes, staticHandler };
+export type { CacheAdapterHostCacheOptions, CacheApiHostCacheOptions, HandlerBuildContext, HandlerDefinition, HostCacheOptions, HostResolverCache, HttpProxyAdapterOptions, ProxyAppOptions, ProxyDataAdapter, ProxyDataPlaneOptions, ResolvedHost, StaticHostConfig, StaticProxyAdapterOptions, StaticRouteInput };