@fabrika/proxy-core 0.9.0-dev.1 → 0.9.0-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/proxy-core",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.3",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,22 +12,23 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./manifest": {
 			"bun": "./src/manifest.ts",
-			"types": "./src/manifest.ts",
+			"types": "./types/src/manifest.d.ts",
 			"default": "./src/manifest.ts"
 		},
 		"./headers": {
 			"bun": "./src/headers.ts",
-			"types": "./src/headers.ts",
+			"types": "./types/src/headers.d.ts",
 			"default": "./src/headers.ts"
 		}
 	},
@@ -37,9 +38,9 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "0.9.0-dev.1",
-		"@fabrika/jwks": "0.9.0-dev.1",
+		"@fabrika/auth-core": "0.9.0-dev.3",
+		"@fabrika/jwks": "0.9.0-dev.3",
 		"jose": "^5.9.0",
-		"@fabrika/platform": "0.9.0-dev.1"
+		"@fabrika/platform": "0.9.0-dev.3"
 	}
 }

package/types/src/authorize.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The proxy authorization core ([ADR-0022](../../../docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md)).
+ *
+ * Every entry — a contract application or an installation service — is protected by its endpoint table, in one pass
+ * over ONE selected endpoint. A contract application's preflight is decided first, from the endpoint the requested
+ * method selects, and never reaches a credential. Then: `planEndpoint` → a `px_` key whose caller kind the endpoint admits, or else the session
+ * when `human` may call → the requirement (`satisfies`) → admission → the delegation grant. There is no fall-through
+ * to another endpoint. On an installation row that admits `oauth`, a bearer that is not a `px_` key is an OAuth
+ * resource token, verified locally. A key or a session is exchanged with IAM once, cached, and thereafter verified
+ * LOCALLY against the JWKS.
+ *
+ * A human miss becomes a bounce to IAM's `/auth/login`, in whichever shape the caller can act on: a
+ * 302 for a document navigation, a 401 carrying the same URL in a JSON body for everything else (see
+ * `isDocumentNavigation`). Caddy returns a non-2xx auth response — status, headers and body — to the
+ * client verbatim, so both reach the caller and neither reaches the app. A request with no session
+ * cookie needs no IAM call.
+ *
+ * NOTHING here returns an allow on an unexpected condition. Every `catch` maps to a deny.
+ */
+import { type CompiledEndpointTable } from '@fabrika/auth-core';
+import { type TokenCache } from './cache';
+import { type HandoffAttempt } from './handoff';
+import { type DelegationIssuer, type IamGateway } from './iam';
+import { type ManifestEndpointRow, type OAuthBearerChallenge, type ProxyApp } from './manifest';
+/** Every way a request can be refused. Coarse on purpose — these are logged, not returned to clients. */
+export type DenyReason = 
+/** The endpoint admits no person, and no credential was presented. */
+'no_credential'
+/** A bearer was presented and is not a valid `px_` key. */
+ | 'invalid_key'
+/** An `oauth` row's bearer is malformed, unverifiable, or minted for another resource or app. */
+ | 'invalid_token'
+/** An `oauth` row's bearer verified but lacks a required scope. */
+ | 'insufficient_scope' | 'no_session' | 'invalid_session' | 'unknown_principal' | 'disabled'
+/** IAM refused to sign a token above its size bound: the principal holds more than fits in a header. */
+ | 'token_too_large'
+/** The entry's table has no endpoint for the method and path. The fail-closed default; no fall-through. */
+ | 'no_endpoint'
+/**
+ * The credential's caller kind is not one of the endpoint's callers, is no caller kind at all (a job or a webhook
+ * key), or is a connector caller off an export path.
+ */
+ | 'caller_kind'
+/** The token does not satisfy the endpoint's requirement. */
+ | 'insufficient_permission'
+/** A session request that is not a `GET` did not come from the app's own origin. */
+ | 'cross_site'
+/** The request's `Content-Type` is not one the endpoint admits. */
+ | 'content_type'
+/**
+ * A preflight for an endpoint the contract does not open to another origin, or from an origin it does not admit; or a
+ * multipart form's request from such an origin, which a browser sends without a preflight.
+ */
+ | 'cross_origin'
+/** IAM refused the delegation grant a membership or scope-creating endpoint needs. */
+ | 'delegation_refused'
+/** The `Host` maps to no app in the manifest. */
+ | 'no_app'
+/** The forwarded-request headers are missing or malformed — we cannot know what was asked for. */
+ | 'bad_forward'
+/** The forwarded path is not canonical (`isCanonicalPath`); refused before any endpoint is planned. */
+ | 'non_canonical_path'
+/** IAM could not be consulted, or its keys could not be fetched. We do not know; we refuse. */
+ | 'iam_unavailable'
+/** Anything that escaped. Always a deny. */
+ | 'internal_error';
+export type Decision = {
+    outcome: 'allow';
+    /** The verified token to inject upstream. `null` on an anonymous endpoint — no credential, no token. */
+    token: string | null;
+    /** Principal id (or credential id) for the log line. Never a secret. */
+    subject: string | null;
+    /** `<id>@<digest>` of the selected endpoint, for `X-Fabrika-Endpoint`. */
+    endpoint: string;
+    /** The single-use delegation grant for `X-Fabrika-Delegation`, when the endpoint spends one. */
+    delegation: string | null;
+    /** The `Access-Control-Allow-Origin` the answer carries: the request's admitted origin, `*`, or none. */
+    crossOrigin: string | null;
+    /**
+     * Whether the request's own `Authorization` reaches the application: on a webhook row that forwards it, unless it
+     * carries a platform key. Every other anonymous request loses it (ADR-0022 rule 3).
+     */
+    forwardsAuthorization: boolean;
+} | {
+    outcome: 'deny';
+    status: 400 | 401 | 403 | 503;
+    reason: DenyReason;
+    clearHandoffState?: string;
+    /** Set on an `oauth` row's 401/403: rendered as the RFC 6750 `WWW-Authenticate` challenge. */
+    challenge?: OAuthBearerChallenge;
+    /** Set when the request's origin is admitted, so the page can read why it was refused. */
+    crossOrigin?: string;
+}
+/**
+ * A contract application's preflight that the selected endpoint admits (ADR-0022 "Cross-origin endpoints"). The
+ * proxy answers it itself; it never reaches the application. `method` is the endpoint's.
+ */
+ | {
+    outcome: 'preflight';
+    allowOrigin: string;
+    method: string;
+}
+/**
+ * A human reached an endpoint `human` may call without a usable session. `location` is where they must go to sign
+ * in; `status` is only how they are TOLD — 302 for a document navigation, 401 for anything else,
+ * whose body carries the same URL. See `isDocumentNavigation` for why the two differ.
+ */
+ | {
+    outcome: 'login';
+    status: 302 | 401;
+    location: string;
+    reason: DenyReason;
+    handoff: HandoffAttempt;
+}
+/**
+ * A handoff code was redeemed (ADR-0022). The only outcome that writes the long-lived app
+ * session: `session` is host-only on this app's host, and `location` is where IAM said the browser
+ * was going — read from the code server-side, never from the request.
+ */
+ | {
+    outcome: 'handoff';
+    status: 302;
+    location: string;
+    session: string;
+    expiresAt: number;
+    handoffState: string;
+};
+/** The original request, reconstructed from what `forward_auth` forwarded. */
+export interface ForwardedRequest {
+    /** Original method; the endpoint table selects by it. */
+    method: string;
+    /** Original absolute URL; the whole URL is the login return. */
+    url: URL;
+    /** The forwarded path exactly as the upstream receives it, already checked by `isCanonicalPath`. */
+    rawPath: string;
+    /** The original request's headers, forwarded verbatim by Caddy. */
+    headers: Headers;
+    requestId: string;
+}
+/** An entry plus its precompiled endpoint table, built once at startup. */
+export interface ResolvedApp {
+    readonly app: ProxyApp;
+    readonly table: CompiledEndpointTable<ManifestEndpointRow>;
+}
+export interface AuthorizerOptions {
+    iam: IamGateway;
+    /** IAM's origin — verifies the token `iss` and is the base for the `/auth/login` bounce. */
+    issuer: string;
+    /** `null` disables caching entirely. Decisions are identical either way; only the IAM call count changes. */
+    cache?: TokenCache | null;
+    /** Unix seconds. Injectable for tests. */
+    now?: () => number;
+    /**
+     * Issues the single-use grant a membership or scope-creating endpoint spends at IAM. Unset, such a request is
+     * forwarded without one and IAM refuses the membership operation unless the framework obtained a grant itself.
+     */
+    delegations?: DelegationIssuer | null;
+}
+export declare class Authorizer {
+    private readonly options;
+    private readonly verifier;
+    private readonly cache;
+    private readonly now;
+    constructor(options: AuthorizerOptions);
+    /**
+     * Decide one request. NEVER throws and NEVER returns an allow it did not derive from a verified
+     * token — the outer `catch` is the last line of the fail-closed guarantee.
+     */
+    authorize(resolved: ResolvedApp, request: ForwardedRequest): Promise<Decision>;
+    /**
+     * One pass over the endpoint `planEndpoint` selects (ADR-0022 rule 3). An anonymous kind reads no credential and
+     * mints no token. A credentialed one takes a `px_` key when one is presented — terminal, whatever its verdict —
+     * an OAuth resource token on a row that admits `oauth`, and the session only when `human` may call; then the
+     * requirement, then admission.
+     */
+    private decideEndpoint;
+    /**
+     * A preflight is decided from the endpoint the REQUESTED method selects, before any credential: it carries none
+     * (ADR-0022 "Cross-origin endpoints"). Only a contract application's: an installation row of method `*` serves
+     * `OPTIONS` itself.
+     */
+    private decidePreflight;
+    /** The selected row's checks. `crossOrigin` is the admitted origin of a cross-origin request, `*` or none. */
+    private decideRow;
+    /**
+     * A `px_` key wherever the request carries an `Authorization` header, and on a row that admits `oauth` any other
+     * credential there as an OAuth resource token; otherwise the session, if `human` may call.
+     */
+    private endpointCaller;
+    /** A fresh grant for every request, never cached: IAM spends it once, for this request id. */
+    private obtainDelegation;
+    /**
+     * An OAuth resource token for one registered resource of this app, carrying every scope required. Verified
+     * locally — no IAM call, no cache. RFC 6750 §3.1: a request without a bearer (none, or another scheme) gets a
+     * challenge with no error code.
+     */
+    private verifyOAuthBearer;
+    /** Exchange a `px_` key for a verified token, through the cache. A non-`px_` bearer is refused with no IAM call. */
+    private exchangeKey;
+    /**
+     * Resolve a human. Two tiers, cheapest first:
+     *   1. a cached token minted earlier from the SAME session — no IAM call;
+     *   2. exchange the `px_session` SSO cookie via `mintToken`.
+     *
+     * Every tier additionally requires `ptype: 'user'`: a session asserts that a resolved USER principal
+     * exists. Without the check a broken IAM could turn a service token into a human allow.
+     */
+    private authorizeSession;
+    /**
+     * Every IAM call goes through here, so ANY failure — a rejected fetch, a Workers RPC error, a
+     * gateway that does not honour the `IamUnavailableError` contract — becomes the same deny. The
+     * gateway is an injected interface; the fail-closed guarantee must not depend on its manners.
+     */
+    private callIam;
+    /**
+     * Redeem a handoff code (ADR-0022). Called for the reserved callback path only, BEFORE the endpoint
+     * is planned — the callback is how a browser obtains a session, so it cannot be behind an endpoint.
+     *
+     * A failed redemption is an ordinary deny with no cookie. It is deliberately not a fresh bounce to
+     * IAM: a code that will not redeem twice would turn a retry into a loop.
+     */
+    authorizeCallback(resolved: ResolvedApp, request: ForwardedRequest): Promise<Decision>;
+    private redeem;
+    private loginDecision;
+    /**
+     * Where to send the browser to log in, returning to the originally requested URL afterwards.
+     *
+     * The scheme comes from the MANIFEST, not from the forwarded request: behind a TLS-terminating
+     * balancer the proxy is reached over plain HTTP and `X-Forwarded-Proto` says so, which would send
+     * the browser back to an `http://` URL for an origin only served over `https://`.
+     */
+    private loginUrl;
+}

package/types/src/cache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The minted-token cache — the thing that makes the warm path free.
+ *
+ * It matters MORE here than it did in the SDK. In-process, a human's freshly minted `px_token` went
+ * back to the browser as a `Set-Cookie`, so the browser carried the warm credential itself. Behind
+ * `forward_auth` there is no such channel: Caddy copies only the named headers of a 2xx auth response
+ * onto the UPSTREAM request and discards the rest, so the proxy cannot hand the browser a cookie on
+ * an allowed request. The server-side cache is what replaces it.
+ *
+ * It is nonetheless BEST-EFFORT. Every entry is re-verified against the JWKS before it is trusted,
+ * and `null` (no cache at all) is a supported configuration that changes only how many times IAM is
+ * called — never which requests are allowed.
+ *
+ * The cache is per-process and in-memory ON PURPOSE: ADR-0022 requires the proxy to stay stateless so
+ * any instance can serve any request. A shared/persistent cache would be state, and would put minted
+ * tokens somewhere they outlive the process.
+ */
+export interface CachedToken {
+    token: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+export interface TokenCache {
+    get(key: string): CachedToken | undefined;
+    set(key: string, value: CachedToken): void;
+    delete(key: string): void;
+}
+/**
+ * A bounded in-memory cache. Insertion-ordered eviction (Map iteration order) keeps it to
+ * `maxEntries`, so a flood of distinct credentials cannot grow it without bound.
+ *
+ * The key is derived from a raw credential (see `cacheKey`). It is never logged, never serialized
+ * and never leaves the process.
+ */
+export declare class MemoryTokenCache implements TokenCache {
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(maxEntries?: number);
+    get(key: string): CachedToken | undefined;
+    set(key: string, value: CachedToken): void;
+    delete(key: string): void;
+    /** Test/introspection helper — the number of live entries. Never exposes keys or tokens. */
+    get size(): number;
+}
+/**
+ * Namespace a cache key by app and credential kind. Without the app id a proxy fronting two apps
+ * could serve app A's token for app B — the `aud` check would still reject it (so it is a correctness
+ * non-issue), but it would turn a warm hit into a needless deny.
+ */
+export declare function cacheKey(app: string, kind: 'session' | 'key', credential: string): string;

package/types/src/constants.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The wire names the proxy and its Caddy config agree on. Both sides are generated from this file
+ * (`caddy.ts` reads the same constants the service does), so a rename cannot desynchronise them.
+ */
+export { CLIENT_ADDRESS_HEADER, DELEGATION_HEADER, ENDPOINT_HEADER, PROXY_TOKEN_HEADER, UNTRUSTED_FORWARD_HEADERS } from '@fabrika/auth-core';
+export declare const FORWARDED_METHOD_HEADER = "X-Forwarded-Method";
+export declare const FORWARDED_URI_HEADER = "X-Forwarded-Uri";
+export declare const FORWARDED_HOST_HEADER = "X-Forwarded-Host";
+export declare const FORWARDED_PROTO_HEADER = "X-Forwarded-Proto";
+/** Correlation id, when the edge supplies one; otherwise the proxy generates a UUIDv7. */
+export declare const REQUEST_ID_HEADER = "X-Request-Id";
+/** The auth service's decision endpoint (Caddy's `uri` subdirective). */
+export declare const DEFAULT_VERIFY_PATH = "/verify";
+/**
+ * Set on the auth service's 2xx to a preflight it admitted (ADR-0022 "Cross-origin endpoints"). The answer is the
+ * preflight's whole answer: the composition returns it to the browser, without the marker, and never dials the app.
+ */
+export declare const PREFLIGHT_HEADER = "X-Fabrika-Preflight";
+/**
+ * Set on the auth service's 2xx when the request's own `Authorization` goes on to the application: an anonymous webhook
+ * row that forwards it. Every composition deletes `Authorization` from an anonymous request without it, and passes the
+ * marker on to no one.
+ */
+export declare const FORWARD_AUTHORIZATION_HEADER = "X-Fabrika-Forward-Authorization";
+/** Liveness endpoint on the auth service itself — never routed publicly. */
+export declare const DEFAULT_HEALTH_PATH = "/healthz";
+/**
+ * Query parameter the generated Caddy route pins the app id with. Explicit beats host-sniffing: the
+ * route already knows which app it fronts, so the auth service never has to infer it.
+ */
+export declare const APP_QUERY_PARAM = "app";
+/**
+ * Query parameter IAM's `/auth/login` takes the return URL in (ADR-0022). The proxy writes it on the
+ * login bounce and redacts it out of the access log, where it would re-emit — percent-encoded — a
+ * credential that was just stripped from the logged URI.
+ */
+export declare const LOGIN_REDIRECT_PARAM = "redirect";
+/** The JWKS cache TTL and the unknown-`kid` refetch cooldown, owned by the verifier both planes share. */
+export { JWKS_REFETCH_COOLDOWN_SECONDS, JWKS_TTL_SECONDS } from '@fabrika/jwks';
+/** Default IAM request timeout. A hung IAM must deny, not hang every request behind it. */
+export declare const DEFAULT_IAM_TIMEOUT_MS = 5000;

package/types/src/credentials.d.ts

@@ -0,0 +1,10 @@
+/** Read the token out of an `Authorization: Bearer <token>` header. Null when absent/non-bearer. */
+export declare function readBearer(header: string | null): string | null;
+/**
+ * Whether an `Authorization` value carries a platform key anywhere: the header itself, or the user or password of Basic
+ * credentials. Such a value is never forwarded to an application, whatever its row says: a key sent to a webhook URL
+ * by mistake must not reach application code.
+ */
+export declare function carriesPlatformKey(header: string, keyPrefix: string): boolean;
+/** Read a single cookie value out of a raw `Cookie` header. Null when absent or malformed. */
+export declare function readCookie(header: string | null, name: string): string | null;

package/types/src/handoff.d.ts

@@ -0,0 +1,15 @@
+export interface HandoffAttempt {
+    state: string;
+    verifier: string;
+    challenge: string;
+}
+/** Create the browser-held verifier and the public values IAM carries through the login. */
+export declare function createHandoffAttempt(): Promise<HandoffAttempt>;
+/** S256, matching PKCE: the verifier never rides in a URL or reaches IAM through the browser. */
+export declare function handoffChallenge(verifier: string): Promise<string>;
+/** Return the dynamic `__Host-` cookie name for a validated public state. */
+export declare function handoffCookieName(state: string | null): string | null;
+/** Add the public handoff coordinates to IAM's login URL. */
+export declare function setHandoffParams(url: URL, attempt: HandoffAttempt): void;
+/** Keep application cookies, but never expose a Fabrika bearer credential to the upstream app. */
+export declare function stripFabrikaCookies(headers: Headers): void;

package/types/src/headers.d.ts

@@ -0,0 +1,112 @@
+import type { CspExtensions, EndpointCache } from '@fabrika/auth-core';
+/** Every powerful feature off. ADR-0022 lists the same names; change both together. */
+export declare const PERMISSIONS_POLICY_FEATURES: readonly string[];
+export type HeaderPolicy = readonly (readonly [name: string, value: string])[];
+/** The named origins a contract adds to seven CSP directives: exact `https://` origins, never patterns. */
+export interface CspOrigins {
+    readonly connectSrc: readonly string[];
+    readonly imgSrc: readonly string[];
+    readonly frameAncestors: readonly string[];
+    readonly scriptSrc: readonly string[];
+    /** `frame-src 'self' <origins>` is emitted only when it names an origin; without it frames fall back to `default-src 'self'`. */
+    readonly frameSrc: readonly string[];
+    readonly styleSrc: readonly string[];
+    readonly fontSrc: readonly string[];
+    /**
+     * `worker-src 'self' blob:` is emitted only when it holds `blob:`, its one source (a challenge widget that starts its
+     * workers from `Blob` URLs); without it workers fall back to `script-src`. Absent from every manifest without it, so a
+     * proxy that does not know the directive still parses those.
+     */
+    readonly workerSrc?: readonly string[];
+}
+/** The one source a contract's `workerSrc` holds: a worker the page's own script built from a `Blob`. */
+export declare const WORKER_BLOB_SOURCE = "blob:";
+/**
+ * An exact origin with a literal hostname: no path, no credentials and no wildcard (`new URL` accepts `*` in a
+ * hostname), so it means one site and is safe inside a header value. CSP origins are `https:` only.
+ */
+export declare function isPolicyOrigin(value: string, protocols?: readonly string[]): boolean;
+/** The most named origins one directive may carry: the contract build and the manifest parser refuse more. */
+export declare const MAX_CSP_ORIGINS = 16;
+export declare const NO_CSP_ORIGINS: CspOrigins;
+export declare function cspOrigins(csp: CspExtensions): CspOrigins;
+/**
+ * The policy for one application: the fixed CSP, extended by the contract's named origins and by the Operations
+ * ingest origin the browser reports errors to.
+ */
+export declare function headerPolicy(origins: CspOrigins, operationsOrigin: string | null): HeaderPolicy;
+/** The browser-facing scheme of a manifest entry's hosts; behind a TLS-terminating balancer no header can supply it. */
+export type PublicScheme = 'http' | 'https';
+/** One year. No `includeSubDomains` and no `preload`: applications share parent domains. */
+export declare const STRICT_TRANSPORT_SECURITY = "max-age=31536000";
+/**
+ * What every answer of an application host carries for its transport: HSTS on an `https` host, nothing on `http` (the
+ * local stack). Only the proxy knows the scheme, from the manifest, so the framework's in-process policy has none.
+ */
+export declare function transportPolicy(scheme: PublicScheme): HeaderPolicy;
+/**
+ * The transport headers the policy owns: an `https` entry's policy sets them, and every other answer loses the
+ * application's own, so an `http` host never pins a browser to a scheme it does not serve.
+ */
+export declare const TRANSPORT_HEADERS: readonly string[];
+/** The policy of a contract application's manifest entry, its transport header included. */
+export declare function appHeaderPolicy(app: {
+    readonly csp: CspOrigins;
+    readonly operationsOrigin?: string;
+    readonly scheme: PublicScheme;
+}): HeaderPolicy;
+/** The policy of an answer that belongs to no contract application: no named origin, no ingest. */
+export declare const BASE_HEADER_POLICY: HeaderPolicy;
+/** Raster formats a browser only ever renders as an image; every other download, SVG and HTML included, is an attachment. */
+export declare const INLINE_FILE_TYPES: readonly string[];
+/** What every answer of a download endpoint carries in place of the policy, its errors included. */
+export declare const FILE_TREATMENT: HeaderPolicy;
+/** The file treatment of a manifest entry's downloads, its transport header included. */
+export declare function appFileTreatment(app: {
+    readonly scheme: PublicScheme;
+}): HeaderPolicy;
+/**
+ * Headers an application may not send at all: each names a reporting endpoint the policy never approved, and a
+ * report-only CSP reports there whatever the enforced one says (`document-uri`, `blocked-uri`).
+ */
+export declare const REMOVED_RESPONSE_HEADERS: readonly string[];
+/** The most origins one environment may list for its cross-origin endpoints: Control and the manifest parser refuse more. */
+export declare const MAX_CROSS_ORIGINS = 16;
+/**
+ * An origin an environment may list for its cross-origin endpoints: exact, a literal host, `https:` (or `http:`, which
+ * only a local host is served over). `null`, an opaque origin, never matches.
+ */
+export declare function isCrossOrigin(value: string): boolean;
+/** What a cross-origin page may send beside the safelisted headers: the key, and the JSON body's type. */
+export declare const CROSS_ORIGIN_REQUEST_HEADERS = "Authorization, Content-Type";
+/** How long a browser may reuse an answered preflight, in seconds. */
+export declare const CROSS_ORIGIN_MAX_AGE = "600";
+/**
+ * The headers an answer to an admitted cross-origin request carries: the admitted origin, and `Vary: Origin` unless every
+ * origin is admitted. Never `Access-Control-Allow-Credentials`: a session does not cross origins.
+ */
+export declare function crossOriginHeaders(allowOrigin: string): HeaderPolicy;
+/** A preflight's answer on top of `crossOriginHeaders`: the endpoint's one method, the two headers, the cache lifetime. */
+export declare function preflightHeaders(allowOrigin: string, method: string): HeaderPolicy;
+/** `crossOriginHeaders` over headers that already carry the answer's own policy; `Vary` is added to, never replaced. */
+export declare function applyCrossOriginHeaders(headers: Headers, policy: HeaderPolicy): void;
+/** `null` and anything but one allowlisted value is an attachment; `Headers` joins repeated fields with `, `, so two never match. */
+export declare function fileDisposition(contentType: string | null): 'inline' | 'attachment';
+/** Whatever the handler or an asset server set for these names is replaced; the removed and transport headers are dropped first. */
+export declare function applyHeaderPolicy(headers: Headers, policy: HeaderPolicy): void;
+/**
+ * The file treatment over headers a download already carries: the disposition type follows the `Content-Type`
+ * exactly, and the parameters after it (the file name) are kept. The proxy passes `appFileTreatment` of its entry.
+ */
+export declare function applyFileTreatment(headers: Headers, treatment?: HeaderPolicy): void;
+/**
+ * A cacheable row's successful answer (`http.cache`): its `Cache-Control` replaces the `no-store` of the policy or the
+ * file treatment. Every other answer, an error or a redirect included, keeps `no-store`.
+ */
+export declare function applyAnswerCache(headers: Headers, row: {
+    readonly cache?: EndpointCache;
+}, status: number): void;
+/** The `Cache-Control` of a cacheable row's successful answer: `immutable` is reused for a year. */
+export declare function cacheControlOf(cache: EndpointCache): string;
+/** A copy of `response` whose headers `apply` rewrote; status and body are unchanged. */
+export declare function withResponseHeaders(response: Response, apply: (headers: Headers) => void): Response;

package/types/src/iam.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The proxy's view of the IAM service: the three cold-path calls it needs, and nothing else.
+ *
+ * `IamGateway` is a STRUCTURAL SUBSET of `IamRpc`, so on Cloudflare the thin Worker passes its
+ * `env.IAM` service binding straight in with no adapter. On Zerops there is no binding, so
+ * `HttpIamGateway` speaks HTTP to the global IAM service — the public hop ADR-0022 calls cold-path
+ * only: everything after the first exchange is a local JWKS verification against the cached token.
+ *
+ * FAIL-CLOSED CONTRACT: an unreachable, slow or incoherent IAM raises `IamUnavailableError`. A
+ * *decided* negative (`{ ok: false, reason }`) is returned normally. The caller must map the former
+ * to a deny too — the distinction only chooses the status, never the outcome.
+ */
+import type { ExchangeAuthCodeInput, ExchangeAuthCodeResult, Jwks, MintFromKeyInput, MintFromKeyResult, MintTokenInput, MintTokenResult } from '@fabrika/auth-core';
+/**
+ * What the proxy needs of IAM. IAM's entrypoints satisfy it structurally — the CF binding drops
+ * straight in with no adapter. Three of the four calls are `IamRpc`; `exchangeAuthCode` is
+ * deliberately NOT (`IamHandoffRpc`, ADR-0022), because only the proxy may turn a handoff code into
+ * a session and `IamRpc` is held by every SDK consumer.
+ */
+export interface IamGateway {
+    mintToken(input: MintTokenInput): Promise<MintTokenResult>;
+    mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult>;
+    exchangeAuthCode(input: ExchangeAuthCodeInput): Promise<ExchangeAuthCodeResult>;
+    getJwks(): Promise<Jwks>;
+}
+/**
+ * Issues the single-use delegation grant a membership or scope-creating endpoint spends (ADR-0022 rule 6). A
+ * structural subset of IAM's membership RPC, so its binding drops in like `IamGateway`'s does. `credential` is the
+ * token the proxy just minted for this request; the grant is bound to `endpoint` and `requestId`.
+ */
+export interface DelegationIssuer {
+    requestDelegation(input: DelegationRequest): Promise<{
+        ok: true;
+        grant: string;
+        expiresAt: number;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+}
+export interface DelegationRequest {
+    app: string;
+    credential: string;
+    requestId: string;
+    endpoint: string;
+}
+/**
+ * IAM could not be consulted — network failure, timeout, non-200, or a body we cannot read. Distinct
+ * from a decided denial: we do not know the answer, so the request is denied with 503 rather than
+ * being told it is unauthorized.
+ *
+ * Carries NO cause and no response body: an error object from `fetch` can carry a URL, and a body
+ * can carry a token.
+ */
+export declare class IamUnavailableError extends Error {
+    readonly operation: string;
+    constructor(operation: string);
+}
+export interface HttpIamGatewayOptions {
+    /** The IAM service origin, e.g. `https://iam.example.com` (trailing slash tolerated). */
+    origin: string;
+    /** Per-call timeout. A hung IAM must deny, not hang every request behind the proxy. */
+    timeoutMs?: number;
+    /** Optional `Authorization: Bearer` the proxy authenticates ITSELF to IAM with. */
+    key?: string;
+    /** Injectable for tests; defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * Just the call shape the gateway uses. Narrower than `typeof fetch` on purpose: the global carries
+ * runtime-specific extras (Bun's `preconnect`) that a test double has no business implementing.
+ */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/**
+ * HTTP transport for `IamGateway` — the Zerops path, where there is no service binding.
+ *
+ * This file and `packages/iam/src/rpc-http.ts` are two halves of one contract; neither may move
+ * without the other in the SAME commit. A mismatch fails closed (any non-200 becomes
+ * `IamUnavailableError` → a 503 deny) but is very hard to read from the outside.
+ *
+ *   POST {origin}/auth/mint/session   {app, session, requestId} -> MintTokenResult
+ *   POST {origin}/auth/mint/key       {app, key, requestId}     -> MintFromKeyResult
+ *   POST {origin}/auth/mint/exchange  {app, code, requestId}    -> ExchangeAuthCodeResult   (ADR-0022)
+ *   POST {origin}/auth/mint/delegation {app, credential, requestId, endpoint} -> a grant or a denial (rule 6)
+ *   GET  {origin}/.well-known/jwks.json                         -> Jwks                     (public)
+ *
+ * The four POST endpoints are the `/auth/mint/*` PROXY surface, authenticated by IAM's `proxyKey` — the
+ * least-privilege split ADR-0022 requires, kept apart from the management `/rpc/*` surface. They
+ * answer **200 on any decided outcome, including a denial**: `{ ok: false, reason }` is "IAM answered:
+ * no", a non-200 is "IAM could not be consulted". Both deny; only the second is an incident.
+ *
+ * Credentials always ride in the POST body, never in a URL — a URL ends up in access logs and error
+ * strings; a body does not.
+ */
+export declare class HttpIamGateway implements IamGateway, DelegationIssuer {
+    private readonly origin;
+    private readonly timeoutMs;
+    private readonly key;
+    private readonly fetchImpl;
+    constructor(options: HttpIamGatewayOptions);
+    mintToken(input: MintTokenInput): Promise<MintTokenResult>;
+    mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult>;
+    exchangeAuthCode(input: ExchangeAuthCodeInput): Promise<ExchangeAuthCodeResult>;
+    requestDelegation(input: DelegationRequest): Promise<{
+        ok: true;
+        grant: string;
+        expiresAt: number;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    getJwks(): Promise<Jwks>;
+    private post;
+    private send;
+}

package/types/src/index.d.ts

@@ -0,0 +1,16 @@
+export { Authorizer } from './authorize';
+export type { AuthorizerOptions, Decision, DenyReason, ForwardedRequest, ResolvedApp } from './authorize';
+export { cacheKey, MemoryTokenCache } from './cache';
+export type { CachedToken, TokenCache } from './cache';
+export { APP_QUERY_PARAM, CLIENT_ADDRESS_HEADER, DEFAULT_HEALTH_PATH, DEFAULT_IAM_TIMEOUT_MS, DEFAULT_VERIFY_PATH, DELEGATION_HEADER, ENDPOINT_HEADER, FORWARD_AUTHORIZATION_HEADER, FORWARDED_HOST_HEADER, FORWARDED_METHOD_HEADER, FORWARDED_PROTO_HEADER, FORWARDED_URI_HEADER, JWKS_TTL_SECONDS, LOGIN_REDIRECT_PARAM, PREFLIGHT_HEADER, PROXY_TOKEN_HEADER, REQUEST_ID_HEADER, UNTRUSTED_FORWARD_HEADERS, } from './constants';
+export { carriesPlatformKey, readBearer, readCookie } from './credentials';
+export { stripFabrikaCookies } from './handoff';
+export { HttpIamGateway, IamUnavailableError } from './iam';
+export type { DelegationIssuer, DelegationRequest, HttpIamGatewayOptions, IamGateway } from './iam';
+export { consoleLogger, redactPath, redactUrl, silentLogger } from './log';
+export type { LogFields, LogValue, ProxyLogger } from './log';
+export { findOAuthMetadata, OAUTH_METADATA_VERIFY_PATH, oauthMetadataResponse } from './oauth';
+export { createVerifyService } from './service';
+export type { VerifyService, VerifyServiceConfig } from './service';
+export { TokenVerifier } from './verifier';
+export type { VerifyResult } from './verifier';