@authhero/proxy 0.2.0 → 0.3.1

package/dist/proxy.d.ts

@@ -0,0 +1,236 @@
+import { ProxyRoute, ProxyRoutesAdapter, 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';
+
+interface ResolvedHost {
+    tenant_id: string;
+    custom_domain_id: string;
+    domain: string;
+    routes: ProxyRoute[];
+}
+/**
+ * Data adapter consumed by the proxy data plane.
+ *
+ * `proxyRoutes` mirrors the tenant-scoped CRUD adapter that AuthHero uses for
+ * its management API. `resolveHost` is the cross-tenant lookup the proxy data
+ * plane needs on every incoming request — it maps a request `Host` header to
+ * the owning tenant, custom domain, and route set.
+ */
+interface ProxyDataAdapter {
+    proxyRoutes: ProxyRoutesAdapter;
+    resolveHost(host: string): Promise<ResolvedHost | null>;
+}
+
+interface HostResolverCache {
+    resolveHost(host: string): Promise<ResolvedHost | null>;
+}
+interface HostCacheOptions {
+    freshTtlMs: number;
+    staleTtlMs?: number;
+    negativeTtlMs?: number;
+    maxEntries?: number;
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+declare function createInMemoryHostCache(data: ProxyDataAdapter, ttlMs: number, maxEntries?: number): HostResolverCache;
+declare function createInMemoryHostCache(data: ProxyDataAdapter, options: HostCacheOptions): HostResolverCache;
+
+interface HandlerBuildContext {
+    bindings: Record<string, unknown>;
+}
+interface HandlerDefinition<TOptions = unknown> {
+    type: string;
+    optionsSchema: z.ZodType<TOptions>;
+    build(options: TOptions, ctx: HandlerBuildContext): MiddlewareHandler;
+}
+declare class HandlerRegistry {
+    private definitions;
+    private bindings;
+    constructor(bindings?: Record<string, unknown>);
+    add<TOptions>(def: HandlerDefinition<TOptions>): this;
+    has(type: string): boolean;
+    build(type: string, rawOptions: unknown): MiddlewareHandler;
+}
+declare function defineHandler<TOptions>(def: HandlerDefinition<TOptions>): HandlerDefinition<TOptions>;
+
+interface ProxyAppOptions {
+    data: ProxyDataAdapter;
+    cacheTtlMs?: number;
+    cache?: HostCacheOptions;
+    registry?: HandlerRegistry;
+    bindings?: Record<string, unknown>;
+}
+declare function createProxyApp(options: ProxyAppOptions): Hono;
+
+interface ProxyDataPlaneOptions {
+    data: ProxyDataAdapter;
+    cacheTtlMs?: number;
+    cache?: HostCacheOptions;
+    resolver?: HostResolverCache;
+    registry?: HandlerRegistry;
+    bindings?: Record<string, unknown>;
+}
+declare function createProxyDataPlaneHandler(options: ProxyDataPlaneOptions): (c: Context) => Promise<Response>;
+declare function createProxyDataPlaneRouter(options: ProxyDataPlaneOptions): Hono;
+
+interface CacheApiHostCacheOptions {
+    upstream: HostResolverCache;
+    cacheTtlSeconds?: number;
+    negativeCacheTtlSeconds?: number;
+    namespace?: string;
+    cache?: Cache;
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * Wraps an upstream `HostResolverCache` with a Cloudflare Cache-API layer.
+ * On cache miss, the upstream is queried and the result written back into
+ * the Cache API for subsequent reads in the same colo.
+ *
+ * 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.
+ */
+declare function createCacheApiHostCache(options: CacheApiHostCacheOptions): HostResolverCache;
+declare function buildCacheApiKey(namespace: string, host: string): Request;
+
+declare const corsHandler: HandlerDefinition<{
+    origins?: string[] | undefined;
+    allow_credentials?: boolean | undefined;
+    allow_headers?: string[] | undefined;
+    allow_methods?: string[] | undefined;
+    expose_headers?: string[] | undefined;
+    max_age?: number | undefined;
+}>;
+
+declare const basicAuthHandler: HandlerDefinition<{
+    username: string;
+    password: string;
+    realm?: string | undefined;
+}>;
+
+declare const headersHandler: HandlerDefinition<{
+    request?: Record<string, string> | undefined;
+    response?: Record<string, string> | undefined;
+    remove_request?: string[] | undefined;
+    remove_response?: string[] | undefined;
+}>;
+
+declare const cacheHandler: HandlerDefinition<{
+    ttl_seconds: number;
+}>;
+
+declare const forwardedHeadersHandler: HandlerDefinition<{
+    client_ip_header: string;
+    set_x_real_ip: boolean;
+    set_x_original_url: boolean;
+}>;
+
+declare const rewriteCookiesHandler: HandlerDefinition<{
+    upstream_host?: string | undefined;
+}>;
+
+declare const rewriteLocationHandler: HandlerDefinition<{
+    upstream_origin?: string | undefined;
+}>;
+
+declare const httpHandler: HandlerDefinition<{
+    upstream_url: string;
+    preserve_host: boolean;
+    timeout_ms?: number | undefined;
+}>;
+
+declare const serviceBindingHandler: HandlerDefinition<{
+    binding: string;
+    preserve_host: boolean;
+    upstream_url?: string | undefined;
+}>;
+
+declare const redirectHandler: HandlerDefinition<{
+    upstream_url: string;
+    status: 301 | 302 | 307 | 308;
+    preserve_path: boolean;
+    preserve_query: boolean;
+}>;
+
+declare const staticHandler: HandlerDefinition<{
+    status: number;
+    headers?: Record<string, string> | undefined;
+    body?: string | undefined;
+    json?: unknown;
+}>;
+
+declare function registerBuiltinHandlers(registry: HandlerRegistry): void;
+
+/**
+ * Build a Hono app whose route table mirrors the configured proxy routes for
+ * a single host. Compiled once per host (and cached alongside the resolved
+ * host) — see `cache.ts`.
+ */
+declare function compileHostApp(routes: ProxyRoute[], registry: HandlerRegistry): Hono;
+
+declare function sortRoutes(routes: ProxyRoute[]): ProxyRoute[];
+/**
+ * Match a configured host pattern against a request's `Host`. Supports
+ * exact match and `*.example.com` wildcard prefix.
+ */
+declare function matchesHost(pattern: string, host: string): boolean;
+declare function matchesAnyHost(patterns: string[] | undefined, host: string): boolean;
+/**
+ * Filter Hono middleware that 404s when the route's `match.headers` /
+ * `match.query` / `match.hosts` predicates don't hold. Path and method
+ * matching is done by Hono itself via `app.on(methods, path, ...)`.
+ */
+declare function buildMatchFilter(match: RouteMatch): (c: Context, next: () => Promise<void>) => Promise<Response | undefined>;
+
+interface StaticRouteInput {
+    id?: string;
+    priority?: number;
+    match: RouteMatch;
+    handlers: HandlerConfig[];
+    created_at?: string;
+    updated_at?: string;
+}
+interface StaticHostConfig {
+    tenant_id?: string;
+    custom_domain_id?: string;
+    routes: StaticRouteInput[];
+}
+interface StaticProxyAdapterOptions {
+    hosts: Record<string, StaticHostConfig | StaticRouteInput[]>;
+    defaultTenantId?: string;
+}
+declare function createStaticProxyAdapter(options: StaticProxyAdapterOptions): ProxyDataAdapter;
+/**
+ * Sugar for building a single HTTP-forwarding route in static configs.
+ * Equivalent to `{ match: { path: "/*" }, handlers: [{ type: "http", options: { upstream_url, preserve_host } }] }`.
+ */
+declare function httpRoute(upstream_url: string, options?: {
+    path?: string;
+    preserve_host?: boolean;
+    priority?: number;
+}): StaticRouteInput;
+
+interface HttpProxyAdapterOptions {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    audience?: string;
+    resolveHostPath?: string;
+    tokenRefreshSkewSeconds?: number;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * Build a `ProxyDataAdapter` that reads from the AuthHero control plane over
+ * HTTP. Intended for a proxy deployment that does not share a database with
+ * the control plane.
+ *
+ * Authentication is a single `client_credentials` grant against the control
+ * plane. The token is cached in-memory and refreshed before expiry. The
+ * privileged `resolveHost` endpoint must be served by the control plane and
+ * requires the `proxy:resolve_host` scope.
+ */
+declare function createHttpProxyAdapter(options: HttpProxyAdapterOptions): ProxyDataAdapter;
+
+export { HandlerRegistry, basicAuthHandler, buildCacheApiKey, buildMatchFilter, cacheHandler, compileHostApp, corsHandler, createCacheApiHostCache, createHttpProxyAdapter, createInMemoryHostCache, createProxyApp, createProxyDataPlaneHandler, createProxyDataPlaneRouter, createStaticProxyAdapter, defineHandler, 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 };