@fabrika/proxy-core 0.8.2 → 0.9.0-cloudflare.2

package/types/src/constants.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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";
+/**
+ * Reserved on every app host beside the handoff callback, and answered before endpoint selection: it clears the app
+ * session and sends the browser to IAM's release (ADR-0067 §5). It takes the return path in `LOGIN_REDIRECT_PARAM`.
+ */
+export declare const AUTH_SIGNOUT_PATH = "/__fabrika/auth/signout";
+/** IAM's path that revokes the browser's terminal sessions and returns it to the application (ADR-0067 §5). */
+export declare const SIGNOUT_RELEASE_PATH = "/auth/terminals/release";
+/** 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,20 @@
+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>;
+/**
+ * A verifier made for no challenge. IAM consumes a code before it compares the verifier, so redeeming a code with this
+ * one only spends the code.
+ */
+export declare function unmatchedVerifier(): string;
+/** 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,18 @@
+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, AUTH_SIGNOUT_PATH, 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, SIGNOUT_RELEASE_PATH, 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 { errorAnswer, errorPage, FETCH_MODE_HEADER, isPageNavigation, PAGE_CONTENT_TYPE, pageResponse, renderPage } from './pages';
+export type { ErrorPageStatus, PageAction, PageContent } from './pages';
+export { createVerifyService } from './service';
+export type { VerifyService, VerifyServiceConfig } from './service';
+export { TokenVerifier } from './verifier';
+export type { VerifyResult } from './verifier';

package/types/src/log.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Logging, constrained so that secret material cannot reach it.
+ *
+ * The rule is structural rather than aspirational: a log field is a `string | number | boolean |
+ * null`, call sites pass only decision metadata, and the two values that CAN carry a credential —
+ * a request path (share-link tokens ride in the path) and a URL — go through `redactPath` /
+ * `redactUrl` first. Nothing in this package ever passes a header, a cookie, a token or a caught
+ * error object to a logger.
+ */
+export type LogValue = string | number | boolean | null;
+export type LogFields = Record<string, LogValue>;
+export interface ProxyLogger {
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+}
+/** Emits one JSON object per line — what Zerops' log collector expects. */
+export declare const consoleLogger: ProxyLogger;
+/** A logger that discards everything — the default, so a library consumer opts IN to output. */
+export declare const silentLogger: ProxyLogger;
+/**
+ * Make a path safe to log. Two hazards, both real:
+ *   - a query string can carry a declared `query` credential (`?pxt=<token>`) — dropped entirely;
+ *   - a path SEGMENT can be a share-link `px_` credential — replaced with `px_***`.
+ * Anything else is preserved, because an unloggable path is an undebuggable proxy.
+ */
+export declare function redactPath(pathname: string): string;
+/** Origin + redacted path. Never the query string. */
+export declare function redactUrl(url: URL): string;