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

package/src/service.ts

@@ -35,9 +35,11 @@ import {
 } from '@fabrika/auth-core'
 import { uuidv7 } from '@fabrika/platform'
 import { Authorizer, type AuthorizerOptions, type Decision, type DenyReason, type ForwardedRequest, type ResolvedApp } from './authorize'
+import type { InstallationBrand } from './brand'
 import type { TokenCache } from './cache'
 import {
 	APP_QUERY_PARAM,
+	AUTH_SIGNOUT_PATH,
 	DEFAULT_HEALTH_PATH,
 	DEFAULT_VERIFY_PATH,
 	FORWARD_AUTHORIZATION_HEADER,
@@ -66,6 +68,7 @@ import type { DelegationIssuer, IamGateway } from './iam'
 import { type LogFields, type ProxyLogger, redactPath, silentLogger } from './log'
 import { formatOAuthBearerChallenge, isApplicationEntry, type ManifestEndpointRow, type ProxyApp, type ProxyManifest } from './manifest'
 import { findOAuthMetadata, OAUTH_METADATA_VERIFY_PATH, oauthMetadataResponse } from './oauth'
+import { errorAnswer, isPageNavigation, type PageContent, pageResponse, renderPage } from './pages'
 
 export interface VerifyServiceConfig {
 	manifest: ProxyManifest
@@ -99,6 +102,8 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 	const byId = new Map<string, ResolvedApp>()
 	const byHost = new Map<string, ResolvedApp>()
 	const policies = new Map<string, HeaderPolicy>()
+	// The client's logo on every page this service answers with (ADR-0066); the fabrika mark without one.
+	const brand = config.manifest.brand ?? null
 	for (const app of config.manifest.apps) {
 		const resolved = resolveApp(app)
 		byId.set(app.id, resolved)
@@ -139,17 +144,19 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 				return withPolicy(textResponse(405, 'method not allowed'), BASE_HEADER_POLICY)
 			}
 
+			// The forwarded request's headers are this request's: `forward_auth` and the Worker copy the original ones.
+			const asPage = isPageNavigation(request.headers)
 			const read = readForwardedRequest(request, requestId)
 			if (!read.ok) {
 				const status = read.reason === 'non_canonical_path' ? 400 : 403
-				return withPolicy(denied(logger, { requestId }, { outcome: 'deny', status, reason: read.reason }), earlyPolicy(request, url))
+				return withPolicy(denied(logger, { requestId }, { outcome: 'deny', status, reason: read.reason }, { asPage, brand }), earlyPolicy(request, url))
 			}
 			const forwarded = read.request
 
 			const resolved = selectApp(url, forwarded.url.host, byId, byHost)
 			if (resolved === null) {
 				const fields = { requestId, host: forwarded.url.host, path: redactPath(forwarded.url.pathname) }
-				return withPolicy(denied(logger, fields, { outcome: 'deny', status: 403, reason: 'no_app' }), BASE_HEADER_POLICY)
+				return withPolicy(denied(logger, fields, { outcome: 'deny', status: 403, reason: 'no_app' }, { asPage, brand }), BASE_HEADER_POLICY)
 			}
 
 			if (url.pathname === OAUTH_METADATA_VERIFY_PATH) {
@@ -162,9 +169,12 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 			// The handoff callback is checked BEFORE the endpoint table: it is how a browser obtains a
 			// session, so it cannot itself be behind an endpoint. Because Caddy returns a non-2xx auth
 			// response verbatim, answering 302 + Set-Cookie here reaches the client and never the app.
+			// The sign-out is answered here for the same reason: a browser whose session is gone must still reach it.
 			const isCallback = forwarded.url.pathname === AUTH_CALLBACK_PATH
 			const decision = isCallback
 				? await authorizer.authorizeCallback(resolved, forwarded)
+				: forwarded.url.pathname === AUTH_SIGNOUT_PATH
+				? authorizer.signOut(resolved, forwarded)
 				: await authorizer.authorize(resolved, forwarded)
 			const fields: LogFields = {
 				requestId,
@@ -202,8 +212,14 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 				applyCrossOriginHeaders(answer.headers, preflightHeaders(decision.allowOrigin, decision.method))
 				return answer
 			}
-			const answer = decision.outcome === 'handoff' ? handoff(logger, fields, decision) : denied(logger, fields, decision, isCallback)
-			const treated = isDownload(resolved, forwarded) ? withFileTreatment(answer, appFileTreatment(resolved.app)) : withPolicy(answer, policy)
+			// A download's every answer is an attachment, so its refusal stays the text: a page would be saved, not shown.
+			const download = isDownload(resolved, forwarded)
+			const answer = decision.outcome === 'handoff'
+				? handoff(logger, fields, decision)
+				: decision.outcome === 'signout'
+				? signedOut(logger, fields, decision)
+				: denied(logger, fields, decision, { isCallback, asPage: asPage && !download, brand })
+			const treated = download ? withFileTreatment(answer, appFileTreatment(resolved.app)) : withPolicy(answer, policy)
 			if (decision.outcome === 'deny' && decision.crossOrigin !== undefined) {
 				applyCrossOriginHeaders(treated.headers, crossOriginHeaders(decision.crossOrigin))
 			}
@@ -212,7 +228,7 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 			// The last line of the fail-closed guarantee. No `err` is inspected or logged: a caught
 			// error can stringify a URL, a header or a body, any of which may carry a credential.
 			logger.error('verify failed', { requestId })
-			return withPolicy(textResponse(403, 'forbidden'), earlyPolicy(request, null))
+			return withPolicy(errorAnswer(403, DENY_TEXT[403], isPageNavigation(request.headers), brand), earlyPolicy(request, null))
 		}
 	}
 
@@ -238,6 +254,17 @@ function handoff(logger: ProxyLogger, fields: LogFields, decision: Extract<Decis
 	return handoffResponse(decision)
 }
 
+/**
+ * Clear the app session with the attributes it was set with, so the browser matches and drops it. The cookie is
+ * cleared whether or not the request carried one: the answer is the same for a browser already signed out.
+ */
+function signedOut(logger: ProxyLogger, fields: LogFields, decision: Extract<Decision, { outcome: 'signout' }>): Response {
+	logger.info('signout', fields)
+	const headers = new Headers({ location: decision.location, 'cache-control': 'no-store' })
+	headers.append('set-cookie', secureCookie(SESSION_COOKIE, '', 0))
+	return new Response(null, { status: 302, headers })
+}
+
 /** An answer the proxy writes reaches the client as-is, so it carries the policy the application's own answers do. */
 function withPolicy(response: Response, policy: HeaderPolicy): Response {
 	applyHeaderPolicy(response.headers, policy)
@@ -262,7 +289,7 @@ function isDownload(resolved: ResolvedApp, forwarded: ForwardedRequest): boolean
  * Render a redeemed handoff: set the app session on THIS host and send the browser where IAM said.
  *
  * This is the ONE place the proxy writes the long-lived app session. It separately writes a
- * short-lived handoff verifier when starting login, then clears that verifier here.
+ * short-lived handoff verifier when starting login, then clears that verifier here. The sign-out clears the session.
  *
  * Every attribute is fixed by `SESSION_COOKIE`'s `__Host-` prefix: `Secure`, `Path=/`, and no
  * `Domain`. The absent `Domain` is the substance — the session belongs to this app's host and no
@@ -284,12 +311,15 @@ function handoffResponse(decision: Extract<Decision, { outcome: 'handoff' }>): R
 	})
 }
 
-/** Emit the log line for a refusal and render its response. The reason is logged, never returned. */
+/**
+ * Emit the log line for a refusal and render its response. The reason is logged, never returned. `asPage` is a
+ * navigation that is not a download (`./pages`), which reads the status's page in place of its text.
+ */
 function denied(
 	logger: ProxyLogger,
 	fields: LogFields,
 	decision: Extract<Decision, { outcome: 'deny' | 'login' }>,
-	isCallback = false,
+	{ isCallback = false, asPage, brand }: { isCallback?: boolean; asPage: boolean; brand: InstallationBrand | null },
 ): Response {
 	const reason: DenyReason = decision.reason
 	if (decision.outcome === 'login') {
@@ -299,7 +329,7 @@ function denied(
 			: loginRequired(decision.location, decision.handoff)
 	}
 	logger.warn('deny', { ...fields, reason, status: decision.status })
-	const response = isCallback ? callbackFailure(decision.status) : textResponse(decision.status, DENY_TEXT[decision.status])
+	const response = isCallback ? callbackFailure(decision.status, brand) : errorAnswer(decision.status, DENY_TEXT[decision.status], asPage, brand)
 	if (decision.clearHandoffState !== undefined) {
 		response.headers.append('set-cookie', clearHandoffCookie(decision.clearHandoffState))
 	}
@@ -310,9 +340,8 @@ function denied(
 }
 
 /**
- * The callback refusal is the one denial a person reads. Every other one answers a program — an XHR,
- * an app request, Caddy itself — but this path is only ever reached by a browser following IAM's
- * redirect, and a viewport containing `forbidden` describes nothing the reader can act on.
+ * The callback refusal is always a page, also without `Sec-Fetch-Mode`: this path is only ever reached by
+ * a browser following IAM's redirect, and its text says what the sign-in did rather than the status's.
  *
  * It deliberately does NOT bounce back into login. A browser that dropped the handoff cookie on this
  * host while keeping IAM's session would be sent straight back here, and the automatic retry becomes
@@ -322,42 +351,14 @@ function denied(
  * out here anyway: `invalid_session` covers an expired verifier and a code IAM refused alike. Coarse
  * deny reasons stay in the log (`../proxy/CLAUDE.md`).
  */
-function callbackFailure(status: number): Response {
-	const [title, detail] = status === 503
-		? ['Sign-in is unavailable', 'The sign-in service could not be reached. Please try again in a moment.']
-		: ['Sign-in did not complete', 'The sign-in link has expired or has already been used. Signing in again will issue a new one.']
-	// No script and no external reference: this page is served on the application's own origin, and a
-	// deployment may sit behind a strict CSP that would blank anything else.
-	const body = `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${title}</title>
-<style>
-body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: #f4f4f5; color: #18181b;
-	font: 16px/1.6 system-ui, -apple-system, "Segoe UI", sans-serif; }
-main { max-width: 27rem; padding: 2rem; }
-h1 { margin: 0 0 .5rem; font-size: 1.25rem; }
-p { margin: 0 0 1.5rem; color: #52525b; }
-a { display: inline-block; padding: .55rem 1.1rem; border-radius: .375rem; background: #18181b; color: #fafafa; text-decoration: none; }
-@media (prefers-color-scheme: dark) {
-	body { background: #18181b; color: #fafafa; }
-	p { color: #a1a1aa; }
-	a { background: #fafafa; color: #18181b; }
-}
-</style>
-</head>
-<body>
-<main>
-<h1>${title}</h1>
-<p>${detail}</p>
-<a href="/">Start again</a>
-</main>
-</body>
-</html>
-`
-	return new Response(body, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } })
+function callbackFailure(status: number, brand: InstallationBrand | null): Response {
+	const content: Omit<PageContent, 'action'> = status === 503
+		? { title: 'Sign-in is unavailable', detail: 'The sign-in service could not be reached. Please try again in a moment.' }
+		: {
+			title: 'Sign-in did not complete',
+			detail: 'The sign-in link has expired or has already been used. Signing in again will issue a new one.',
+		}
+	return pageResponse(status, renderPage({ ...content, action: { href: '/', label: 'Start again' } }, String(status), brand))
 }
 
 /** The bounce a document navigation gets: the browser follows it and comes back signed in. */

package/types/src/authorize.d.ts

@@ -0,0 +1,253 @@
+/**
+ * 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`, or a sign-out, did not come from the app's own origin. */
+ | 'cross_site'
+/** A sign-out's return is absent or not a path on the app's own origin. */
+ | 'bad_redirect'
+/** 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 the ops row, and 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;
+}
+/**
+ * A same-origin sign-out (ADR-0067 §5): the app session cookie is cleared and the browser goes to IAM's release,
+ * which returns it to `location`'s own redirect on this app's origin.
+ */
+ | {
+    outcome: 'signout';
+    status: 302;
+    location: 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;
+    /**
+     * Sign the browser out of this host (ADR-0067 §5). Called for the reserved sign-out path only, BEFORE the endpoint
+     * is planned, for any entry and any session. It drops this session's cached token, so the next request re-mints
+     * from IAM, which has revoked the session by then or still holds it; the cookie itself is cleared by the response.
+     *
+     * Admission is `Sec-Fetch-Site: same-origin`, absent included: the request changes state, and another page must not
+     * sign a person out, as for a session request that is not a `GET` (ADR-0022 rule 3, step 6).
+     */
+    signOut(resolved: ResolvedApp, request: ForwardedRequest): Decision;
+    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/brand.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The client's brand on fabrika's own pages (ADR-0066). An installation serves one client, so its logo is one setting
+ * of the installation: IAM keeps it, the console's Settings writes it, and the proxy manifest carries it to the pages the
+ * proxy answers with on every application host. A page shows it where it would otherwise draw the fabrika mark.
+ *
+ * A logo is an image a page embeds as a `data:` URI in an `<img>`, never markup: an SVG in an image runs no script, and
+ * a page that carries it loads nothing. Every consumer checks it here, the IAM write, the manifest parser and the
+ * console's own pre-check, so a logo that one of them admits passes the others. This module imports zod and nothing
+ * else, so the browser can use it.
+ */
+import { z } from 'zod';
+export declare const BRAND_IMAGE_TYPES: readonly ["image/png", "image/webp", "image/svg+xml"];
+export type BrandImageType = (typeof BRAND_IMAGE_TYPES)[number];
+/** The most one image may weigh, decoded. A page carries it in every copy Caddy serves, so it stays a logo's size. */
+export declare const MAX_BRAND_IMAGE_BYTES: number;
+/** One image of the brand: its type and its bytes as canonical base64. */
+export interface BrandImage {
+    readonly type: BrandImageType;
+    readonly base64: string;
+}
+/** The logo for a light page, and the one for a dark page when the light one would not read there. */
+export interface InstallationBrand {
+    readonly light: BrandImage;
+    readonly dark?: BrandImage;
+}
+export type BrandImageProblem = 'type' | 'encoding' | 'size' | 'content';
+/** Why an image cannot be the brand, or null. The type must be one of three and must be what the bytes are. */
+export declare function brandImageProblem(image: {
+    readonly type: string;
+    readonly base64: string;
+}): BrandImageProblem | null;
+export declare function isBrandImageType(value: string): value is BrandImageType;
+export declare const brandImageSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodEnum<["image/png", "image/webp", "image/svg+xml"]>;
+    base64: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    base64: string;
+    type: "image/png" | "image/webp" | "image/svg+xml";
+}, {
+    base64: string;
+    type: "image/png" | "image/webp" | "image/svg+xml";
+}>, {
+    base64: string;
+    type: "image/png" | "image/webp" | "image/svg+xml";
+}, {
+    base64: string;
+    type: "image/png" | "image/webp" | "image/svg+xml";
+}>;
+export declare const installationBrandSchema: z.ZodObject<{
+    light: z.ZodEffects<z.ZodObject<{
+        type: z.ZodEnum<["image/png", "image/webp", "image/svg+xml"]>;
+        base64: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }>, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }>;
+    dark: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        type: z.ZodEnum<["image/png", "image/webp", "image/svg+xml"]>;
+        base64: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }>, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }, {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    light: {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    };
+    dark?: {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    } | undefined;
+}, {
+    light: {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    };
+    dark?: {
+        base64: string;
+        type: "image/png" | "image/webp" | "image/svg+xml";
+    } | undefined;
+}>;
+/** The image as the `src` of an `<img>`. Base64 holds no `{`, so a Caddy `static_response` body keeps it as it is. */
+export declare function brandImageDataUri(image: BrandImage): string;
+/** Canonical base64 of `bytes`, the spelling the check requires. Chunked, so a large file stays within `fromCharCode`'s arguments. */
+export declare function brandImageBase64(bytes: Uint8Array): string;

package/types/src/cache.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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` and to
+ * `maxBytes` of keys and tokens together, so a flood of distinct credentials cannot grow it without bound. The byte
+ * budget is what holds on Cloudflare: 10,000 application tokens of 24 KiB would pass a Worker isolate's 128 MB.
+ *
+ * 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 maxBytes;
+    private readonly entries;
+    private bytes;
+    constructor(maxEntries?: number, maxBytes?: 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;