@fabrika/proxy-core 0.8.1 → 0.9.0-dev.2

package/types/src/oauth-resource.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/** Configuration, not caller-supplied URLs. Resource and metadata stay on the protected app origin. */
+export interface OAuthProtectedResource {
+    resource: string;
+    resourceMetadata: string;
+    authorizationServers: string[];
+    scopesSupported: string[];
+}
+/** RFC 9728 metadata response; metadata publication does not admit requests to the resource. */
+export interface OAuthProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported: string[];
+    bearer_methods_supported: ['header'];
+}
+/** RFC 6750 challenge parameters with RFC 9728 resource metadata discovery. */
+export interface OAuthBearerChallenge {
+    resource_metadata: string;
+    error?: 'invalid_token' | 'insufficient_scope';
+    scope?: string;
+}
+export declare const oauthScopesSchema: z.ZodEffects<z.ZodUnknown, string[], unknown>;
+export declare const oauthProtectedResourceSchema: z.ZodEffects<z.ZodObject<{
+    resource: z.ZodEffects<z.ZodString, string, string>;
+    resourceMetadata: z.ZodEffects<z.ZodString, string, string>;
+    authorizationServers: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+    scopesSupported: z.ZodEffects<z.ZodUnknown, string[], unknown>;
+}, "strip", z.ZodTypeAny, {
+    resource: string;
+    resourceMetadata: string;
+    authorizationServers: string[];
+    scopesSupported: string[];
+}, {
+    resource: string;
+    resourceMetadata: string;
+    authorizationServers: string[];
+    scopesSupported?: unknown;
+}>, {
+    resource: string;
+    resourceMetadata: string;
+    authorizationServers: string[];
+    scopesSupported: string[];
+}, {
+    resource: string;
+    resourceMetadata: string;
+    authorizationServers: string[];
+    scopesSupported?: unknown;
+}>;
+export declare function parseOAuthProtectedResource(value: unknown): OAuthProtectedResource | null;
+export declare function oauthProtectedResourceMetadata(config: OAuthProtectedResource): OAuthProtectedResourceMetadata;
+export declare function parseOAuthBearerChallenge(value: unknown): OAuthBearerChallenge | null;
+export declare function formatOAuthBearerChallenge(value: OAuthBearerChallenge): string;

package/types/src/oauth.d.ts

@@ -0,0 +1,12 @@
+import { type OAuthProtectedResource, type ProxyApp } from './manifest';
+/**
+ * The auth service's RFC 9728 metadata endpoint. Separate from `/verify` because a 2xx from `/verify`
+ * admits the request to the app, while metadata is answered by the proxy itself and never forwarded.
+ */
+export declare const OAUTH_METADATA_VERIFY_PATH = "/oauth-metadata";
+/**
+ * The entry's protected resource whose metadata URL is this request's host and exact raw pathname. Only an
+ * installation entry has one.
+ */
+export declare function findOAuthMetadata(app: ProxyApp, url: URL): OAuthProtectedResource | null;
+export declare function oauthMetadataResponse(resource: OAuthProtectedResource, method: string): Response;

package/types/src/service.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The `forward_auth` endpoint — a fetch-style `Request → Response` service, written the way
+ * `@fabrika/iam` is so the same code runs on Bun, Node and Workers.
+ *
+ * Caddy's contract (verified against `modules/caddyhttp/reverseproxy/forwardauth/caddyfile.go`):
+ *   - the subrequest is rewritten to `GET /verify` with the ORIGINAL headers, plus
+ *     `X-Forwarded-Method` / `X-Forwarded-Uri`, plus reverse_proxy's `X-Forwarded-{For,Proto,Host}`;
+ *   - a **2xx** response lets the request continue, and each `copy_headers` field is copied onto the
+ *     UPSTREAM request — but ONLY when non-empty (Caddy guards each copy with a `not vars ""` matcher);
+ *   - **any other status** is returned to the client verbatim — status, headers AND body, verified
+ *     against caddy 2.10.2 — so both a 302 to `/auth/login` and a 401 carrying a JSON login envelope
+ *     reach the caller and neither reaches the app.
+ *
+ * The two consequences that shape this file:
+ *   1. the request being authorized is described ENTIRELY by the forwarded headers. Never look at
+ *      this request's own method or path — a missing `X-Forwarded-Uri` must deny, not fall back;
+ *   2. because an empty copy header is a no-op rather than a delete, the generated Caddy config
+ *      strips the token header AND the request id from the inbound request BEFORE `forward_auth`
+ *      runs. Otherwise a client could present its own token header on a `public` path and have it
+ *      reach the app, or choose the correlation id that lands in IAM's audit trail. Both are handed
+ *      back on a 2xx, so the edge is the only thing that mints either.
+ */
+import type { TokenCache } from './cache';
+import type { DelegationIssuer, IamGateway } from './iam';
+import { type ProxyLogger } from './log';
+import { type ProxyManifest } from './manifest';
+export interface VerifyServiceConfig {
+    manifest: ProxyManifest;
+    iam: IamGateway;
+    /** IAM's origin — token `iss` and the base of the login bounce. */
+    issuer: string;
+    /** `null`/omitted disables the token cache. Same decisions, more IAM calls. */
+    cache?: TokenCache | null;
+    logger?: ProxyLogger;
+    /** Liveness probe path on the auth service's own port. Default `/healthz`. */
+    healthPath?: string;
+    /** Unix seconds. Injectable for tests. */
+    now?: () => number;
+    /** Issues delegation grants for membership and scope-creating endpoints; see `AuthorizerOptions.delegations`. */
+    delegations?: DelegationIssuer | null;
+}
+export type VerifyService = (request: Request) => Promise<Response>;
+/**
+ * Build the `/verify` service. Endpoint tables are compiled once here, not per request — the planner is
+ * on the hot path of every request to every app.
+ */
+export declare function createVerifyService(config: VerifyServiceConfig): VerifyService;

package/types/src/verifier.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Local token verification — the warm path. Fetch the JWKS once, then verify every token with no
+ * network call on the warm path.
+ *
+ * The verification itself is `@fabrika/jwks`, shared byte-for-byte with the app SDK. What this file
+ * owns is the proxy's construction shape: one long-lived process holding one verifier, so the key set
+ * is cached per instance, and the audience is the app the forwarded request resolved to — per call,
+ * not per verifier.
+ */
+import type { Jwks, TokenAudienceProfile } from '@fabrika/auth-core';
+import { type VerifyResult } from '@fabrika/jwks';
+export type { VerifyResult };
+export declare class TokenVerifier {
+    private readonly inner;
+    constructor(getJwks: () => Promise<Jwks>, issuer: string, now: () => number, ttlSeconds?: number, refetchCooldownSeconds?: number);
+    /**
+     * Verify `token` for `audience` (a bare string is an app id). An unknown `kid` forces one JWKS refetch (a key rotated in), then a
+     * retry — but at most once per cooldown, because otherwise any caller can turn every request into an
+     * IAM round trip just by inventing a `kid`.
+     */
+    verify(token: string, audience: string | TokenAudienceProfile): Promise<VerifyResult>;
+}