@authhero/proxy 0.4.4 → 0.5.0

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 };

package/dist/proxy.mjs

@@ -3009,6 +3009,7 @@ function Tr(e) {
 		data: e.data,
 		cacheTtlMs: e.cacheTtlMs,
 		cache: e.cache,
+		resolver: e.resolver,
 		registry: e.registry,
 		bindings: e.bindings
 	})), n;
@@ -3041,11 +3042,53 @@ function Or(e, t) {
 	return Q(e, t);
 }
 //#endregion
+//#region src/data-plane/cache-adapter-cache.ts
+function kr(e) {
+	let { upstream: t, cache: n, freshTtlMs: r, staleTtlMs: i = 0, negativeTtlMs: a = r, keyPrefix: o = "authhero-proxy-host", waitUntil: s } = e, c = /* @__PURE__ */ new Map();
+	function l(e) {
+		return `${o}:${e.toLowerCase()}`;
+	}
+	async function u(e) {
+		let o = c.get(e);
+		if (o) return o;
+		let s = (async () => {
+			try {
+				let o = await t.resolveHost(e), s = Date.now(), c = o === null ? a : r, u = o === null ? 0 : i, d = {
+					value: o,
+					freshUntilMs: s + c,
+					staleUntilMs: s + c + u
+				}, f = Math.max(1, Math.ceil((c + u) / 1e3));
+				return await n.set(l(e), d, f), o;
+			} finally {
+				c.delete(e);
+			}
+		})();
+		return c.set(e, s), s;
+	}
+	return { async resolveHost(e) {
+		let t = l(e), r = await n.get(t), i = Date.now();
+		if (r && typeof r.freshUntilMs == "number") {
+			if (r.freshUntilMs > i) return r.value;
+			if (r.staleUntilMs > i) {
+				if (!c.has(e)) {
+					let t = u(e).catch(() => void 0);
+					s && s(t);
+				}
+				return r.value;
+			}
+		}
+		return u(e);
+	} };
+}
+function Ar(e, t) {
+	return `${e}:${t.toLowerCase()}`;
+}
+//#endregion
 //#region src/static/index.ts
 function $() {
 	throw Error("Static proxy adapter is read-only; configure routes at init time");
 }
-function kr(e, t, n, r, i, a) {
+function jr(e, t, n, r, i, a) {
 	return {
 		id: e.id ?? `${n}:${t}`,
 		tenant_id: r,
@@ -3060,10 +3103,10 @@ function kr(e, t, n, r, i, a) {
 		updated_at: e.updated_at ?? a
 	};
 }
-function Ar(e) {
+function Mr(e) {
 	let t = (/* @__PURE__ */ new Date()).toISOString(), n = e.defaultTenantId ?? "static", r = /* @__PURE__ */ new Map();
 	for (let [i, a] of Object.entries(e.hosts)) {
-		let e = i.toLowerCase(), o = Array.isArray(a) ? { routes: a } : a, s = o.tenant_id ?? n, c = o.custom_domain_id ?? e, l = o.routes.map((n, r) => kr(n, r, e, s, c, t)).sort((e, t) => e.priority - t.priority);
+		let e = i.toLowerCase(), o = Array.isArray(a) ? { routes: a } : a, s = o.tenant_id ?? n, c = o.custom_domain_id ?? e, l = o.routes.map((n, r) => jr(n, r, e, s, c, t)).sort((e, t) => e.priority - t.priority);
 		r.set(e, {
 			tenant_id: s,
 			custom_domain_id: c,
@@ -3107,7 +3150,7 @@ function Ar(e) {
 		}
 	};
 }
-function jr(e, t = {}) {
+function Nr(e, t = {}) {
 	return {
 		priority: t.priority,
 		match: { path: t.path ?? "/*" },
@@ -3121,8 +3164,11 @@ function jr(e, t = {}) {
 	};
 }
 //#endregion
+//#region src/constants.ts
+var Pr = "proxy:resolve_host";
+//#endregion
 //#region src/http-adapter/index.ts
-function Mr() {
+function Fr() {
 	let e = () => {
 		throw Error("HTTP proxy adapter does not expose write access to proxy_routes; mutate via the control-plane management API");
 	};
@@ -3144,41 +3190,42 @@ function Mr() {
 		}
 	};
 }
-function Nr(e) {
-	let t = e.fetch ?? fetch, n = e.baseUrl.replace(/\/+$/, ""), r = e.resolveHostPath ?? "/api/v2/proxy/control-plane/hosts/", i = e.audience ?? `${n}/api/v2/`, a = e.tokenRefreshSkewSeconds ?? 60, o = e.timeoutMs ?? 5e3;
-	function s(e) {
-		let t = new AbortController(), n = setTimeout(() => t.abort(), o);
+function Ir(e) {
+	let t = e.fetch ?? fetch, n = e.baseUrl.replace(/\/+$/, ""), r = e.resolveHostPath ?? "/api/v2/proxy/control-plane/hosts/", i = e.audience ?? `${n}/api/v2/`, a = e.scope ?? "proxy:resolve_host", o = e.tokenRefreshSkewSeconds ?? 60, s = e.timeoutMs ?? 5e3;
+	function c(e) {
+		let t = new AbortController(), n = setTimeout(() => t.abort(), s);
 		return e(t.signal).finally(() => clearTimeout(n));
 	}
-	let c = null, l = null;
-	async function u() {
-		let r = await s((r) => t(`${n}/oauth/token`, {
+	let l = null, u = null;
+	async function d() {
+		let r = await c((r) => t(`${n}/oauth/token`, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify({
 				grant_type: "client_credentials",
 				client_id: e.clientId,
 				client_secret: e.clientSecret,
-				audience: i
+				audience: i,
+				scope: a
 			}),
 			signal: r
 		}));
 		if (!r.ok) throw Error(`Proxy adapter token request failed: ${r.status} ${await r.text().catch(() => "")}`);
-		let o = await r.json(), l = o.expires_in ?? 3600;
-		return c = {
-			value: o.access_token,
-			expires_at: Date.now() + (l - a) * 1e3
-		}, o.access_token;
+		let s = await r.json(), u = s.expires_in ?? 3600;
+		return l = {
+			value: s.access_token,
+			expires_at: Date.now() + (u - o) * 1e3
+		}, s.access_token;
 	}
-	async function d() {
-		return c && c.expires_at > Date.now() ? c.value : l || (l = u().finally(() => {
-			l = null;
-		}), l);
+	async function f() {
+		return l && l.expires_at > Date.now() ? l.value : u || (u = d().finally(() => {
+			u = null;
+		}), u);
 	}
 	return {
-		proxyRoutes: Mr(),
+		proxyRoutes: Fr(),
 		async resolveHost(e) {
-			let i = await d(), a = `${n}${r}${encodeURIComponent(e.toLowerCase())}`, o = await s((e) => t(a, {
+			let i = await f(), a = `${n}${r}${encodeURIComponent(e.toLowerCase())}`, o = await c((e) => t(a, {
 				headers: { authorization: `Bearer ${i}` },
 				signal: e
 			}));
@@ -3189,4 +3236,4 @@ function Nr(e) {
 	};
 }
 //#endregion
-export { z as HandlerRegistry, Wn as basicAuthHandler, Or as buildCacheApiKey, yr as buildMatchFilter, Kn as cacheHandler, xr as compileHostApp, Vn as corsHandler, Dr as createCacheApiHostCache, Nr as createHttpProxyAdapter, R as createInMemoryHostCache, Tr as createProxyApp, Z as createProxyDataPlaneHandler, wr as createProxyDataPlaneRouter, Ar as createStaticProxyAdapter, B as defineHandler, fr as dispatchNamespaceHandler, qn as forwardedHeadersHandler, P as handlerConfigSchema, Gn as headersHandler, ar as httpHandler, jr as httpRoute, N as matchSchema, vr as matchesAnyHost, _r as matchesHost, F as proxyRouteInsertSchema, mn as proxyRouteSchema, hn as proxyRouteUpdateSchema, pr as redirectHandler, hr as registerBuiltinHandlers, Zn as rewriteCookiesHandler, Qn as rewriteLocationHandler, cr as serviceBindingHandler, gr as sortRoutes, mr as staticHandler };
+export { z as HandlerRegistry, Pr as PROXY_RESOLVE_HOST_SCOPE, Wn as basicAuthHandler, Ar as buildCacheAdapterKey, Or as buildCacheApiKey, yr as buildMatchFilter, Kn as cacheHandler, xr as compileHostApp, Vn as corsHandler, kr as createCacheAdapterHostCache, Dr as createCacheApiHostCache, Ir as createHttpProxyAdapter, R as createInMemoryHostCache, Tr as createProxyApp, Z as createProxyDataPlaneHandler, wr as createProxyDataPlaneRouter, Mr as createStaticProxyAdapter, B as defineHandler, fr as dispatchNamespaceHandler, qn as forwardedHeadersHandler, P as handlerConfigSchema, Gn as headersHandler, ar as httpHandler, Nr as httpRoute, N as matchSchema, vr as matchesAnyHost, _r as matchesHost, F as proxyRouteInsertSchema, mn as proxyRouteSchema, hn as proxyRouteUpdateSchema, pr as redirectHandler, hr as registerBuiltinHandlers, Zn as rewriteCookiesHandler, Qn as rewriteLocationHandler, cr as serviceBindingHandler, gr as sortRoutes, mr as staticHandler };