@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.2

package/types/src/implement/challenge.d.ts

@@ -0,0 +1,75 @@
+import type { AltchaChallenge, ChallengeProvider } from '@fabrika/auth-core';
+export declare const TURNSTILE_VERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+export declare const CHALLENGE_LIMITS: {
+    /** The provider's answer, the body read included. */
+    readonly timeoutMs: 5000;
+    readonly maxAnswerBytes: number;
+    /** Turnstile's tokens are at most 2048 characters. */
+    readonly maxTokenLength: 2048;
+    /** A token is valid for 300 s after the widget issued it; a recorded one is kept as long, plus the skew. */
+    readonly maxAgeMs: 300000;
+    readonly maxSkewMs: 60000;
+};
+/**
+ * How the siteverify request reaches the provider. `check` is what a passing answer confirms (the host and the form),
+ * for a stand-in that answers as the provider would; the provider itself reads only the request.
+ */
+export type ChallengeFetch = (request: Request, check: ChallengeCheck) => Promise<Response>;
+/** `failed` is the visitor's (400); `unavailable` and `misconfigured` are the platform's or the operator's (503). */
+export type ChallengeOutcome = 'passed' | 'failed' | 'unavailable' | 'misconfigured';
+export interface ChallengeCheck {
+    readonly token: string;
+    /** The host the form was submitted to: the page the widget ran on must be on it. */
+    readonly hostname: string;
+    /** The form's name, which its widget renders as `action`. */
+    readonly action: string;
+}
+/**
+ * A verification's answer. A passed one names what the dispatcher records it by: the token itself, or, for ALTCHA, the
+ * signature of the challenge it solved, since one solution can be encoded as many tokens. Its record lasts at least
+ * as long as this token could pass again, even if the issuer's configured lifetime has since changed.
+ */
+export type ChallengeVerdict = {
+    readonly outcome: 'passed';
+    readonly replayKey: string;
+    readonly recordMs: number;
+} | {
+    readonly outcome: Exclude<ChallengeOutcome, 'passed'>;
+};
+export interface ChallengeVerifier {
+    readonly provider: ChallengeProvider;
+    verify(check: ChallengeCheck): Promise<ChallengeVerdict>;
+}
+/** Turnstile's siteverify under one deadline and a byte budget; `now` is the clock a token's age is read with. */
+export declare function turnstileVerifier(secret: string, fetch: ChallengeFetch, now?: () => number): ChallengeVerifier;
+/**
+ * How hard an ALTCHA challenge is to solve: PBKDF2 attempts of `cost` iterations, up to a count drawn between
+ * `minCounter` and `maxCounter`. The contract's by default; a test kit and `fabrika app dev` make it cheap.
+ */
+export interface ChallengeWork {
+    readonly cost: number;
+    readonly minCounter: number;
+    readonly maxCounter: number;
+}
+/** The cheapest work: the test kit's and `fabrika app dev`'s, so a test solves a challenge in milliseconds. */
+export declare const MINIMAL_CHALLENGE_WORK: ChallengeWork;
+/** What the issuing endpoint answers: the signed parameters, which the widget solves and sends back with its solution. */
+export interface IssuedChallenge {
+    readonly parameters: Readonly<Record<string, unknown>>;
+    readonly signature?: string;
+}
+export interface ChallengeIssuer {
+    /** A fresh challenge for this host and the procedure's action. */
+    issue(hostname: string): Promise<IssuedChallenge>;
+}
+/**
+ * The issuer and the verifier of one public procedure's ALTCHA challenge, with the HMAC key its application variable
+ * holds. A challenge carries the action and the host it was issued for and expires `maxAgeMs` after it was issued; the
+ * server picks the attempt that solves it and signs that attempt's key, so verifying is two HMACs and no proof of work.
+ * Nothing leaves the process. `now` is the clock a challenge's expiry is set with; altcha-lib reads it on the real clock,
+ * and so does the verifier, so the two never disagree.
+ */
+export declare function altchaChallenge(secret: string, rules: Pick<AltchaChallenge, 'action' | 'cost' | 'maxAgeMs'>, work?: ChallengeWork | null, now?: () => number): {
+    readonly issuer: ChallengeIssuer;
+    readonly verifier: ChallengeVerifier;
+};

package/types/src/implement/client-address.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The client a per-client limit counts: an IPv4 address, or an IPv6 address's /64 (one subscriber's prefix, of which
+ * it may hold every address). Anything else, the header's absence included, is one shared `unknown` client.
+ */
+export declare function clientKey(header: string | null): string;
+/**
+ * The bucket of the client the proxy saw. Only `X-Fabrika-Client-Ip` is read: the proxy deletes it and sets it from
+ * the connection on every request, and the proxy secret proves the request came through it. A forwarding header a
+ * client can write (`X-Forwarded-For`, `CF-Connecting-IP`) is never read. The address is kept as its digest.
+ */
+export declare function clientBucket(request: Request): string;

package/types/src/implement/connect.d.ts

@@ -0,0 +1,67 @@
+import { type ConnectVariables, connectVariables, type ContractArtifact, type ExportDescription } from '@fabrika/auth-core';
+import { type ConnectSnapshot } from '../contract/connect';
+import { type RequestFrame } from './capability';
+export type ConnectFailure = 'denied' | 'invalid_input' | 'unavailable' | 'timeout' | 'contract_violation';
+/** `unavailable` and `timeout` are never reported as `denied`: "we could not ask" is not "no". */
+export type ConnectResult<T> = {
+    readonly outcome: 'ok';
+    readonly value: T;
+} | {
+    readonly outcome: ConnectFailure;
+    readonly message: string;
+};
+/** How a request reaches the owner's proxy: `fetch` over HTTPS, or a service binding to its proxy Worker. */
+export type ConnectFetch = (request: Request) => Promise<Response>;
+/** Every import's variables and binding are named under it (`connectVariables`, `@fabrika/auth-core`). */
+export declare const CONNECT_BINDING_PREFIX = "FABRIKA_CONNECT_";
+export { type ConnectVariables, connectVariables };
+export interface ConnectorOptions {
+    /** The import's name in the contract, for the log line of a contract violation. */
+    readonly name: string;
+    readonly export: string;
+    readonly version: number;
+    readonly origin: string;
+    readonly key: string;
+    readonly fetch: ConnectFetch;
+    readonly timeoutMs: number;
+    /** The imported procedures of the checked description, by path. */
+    readonly description: ExportDescription;
+    readonly procedures: readonly string[];
+}
+/** `application/json`, with or without parameters, is the only media type an export answers in. */
+export declare function isJsonMediaType(header: string | null): boolean;
+/** One import's calls. A message names only what the framework wrote; the edge key is cut out of it regardless. */
+export declare class Connector {
+    #private;
+    constructor(options: ConnectorOptions);
+    call(path: string, input: unknown): Promise<ConnectResult<unknown>>;
+}
+/** `ctx.connect` of one request: each import its endpoint's `usedBy` names, with the procedures the contract imports. */
+export type ConnectContextValue = Readonly<Record<string, Readonly<Record<string, (input?: unknown) => Promise<ConnectResult<unknown>>>>>>;
+/** One import as an endpoint may use it. */
+export interface ImportWire {
+    readonly name: string;
+    readonly connector: Connector;
+    readonly procedures: readonly string[];
+    readonly usedBy: ReadonlySet<string>;
+}
+/**
+ * The `ctx.connect` of one request, bound to its frame. A method kept past its request, called from another request,
+ * from an export's (read-only) request or from an endpoint the import does not name is `denied`, and sends nothing.
+ */
+export declare function connectContext(imports: readonly ImportWire[], frame: RequestFrame): ConnectContextValue;
+export interface ImportWiring {
+    readonly artifact: ContractArtifact;
+    readonly snapshots: Readonly<Record<string, ConnectSnapshot>>;
+    /** The captured `FABRIKA_*` variables, which carry each import's URL and edge key. */
+    readonly framework: Readonly<Record<string, string>>;
+    /** Cloudflare service bindings to owners' proxy Workers, by binding name; any other import uses `fallback`. */
+    readonly bindings: Readonly<Record<string, ConnectFetch>>;
+    readonly fallback: ConnectFetch;
+}
+/**
+ * The imports each endpoint may use. Each import must come with the snapshot its digest names, unedited, and with its
+ * owner's URL and edge key; otherwise `problems` says why. What a connector validates against is compiled here, once,
+ * from the checked description, before the application's `deps` run.
+ */
+export declare function wireImports(wiring: ImportWiring, problems: string[]): ReadonlyMap<string, readonly ImportWire[]>;

package/types/src/implement/crashes.d.ts

@@ -0,0 +1,31 @@
+import { type CrashKind, type CrashReporter } from '../jobs/report';
+import type { CapturedEnvironment } from './environment';
+/** How long a crash or a failed boot waits for its report before the process fails as it would have without one. */
+export declare const CRASH_FLUSH_MS = 2000;
+export type ProcessCrashKind = Exclude<CrashKind, 'boot_failed'>;
+export interface CrashEvents {
+    /** Starts listening; the returned function stops, which gives the runtime its own handling back. */
+    listen(listener: (kind: ProcessCrashKind, error: unknown) => void): () => void;
+}
+/** The reporter of `environment`'s DSN, or `null` without a usable one: `boot` reports a DSN that is not one. */
+export declare function environmentCrashReporter(environment: CapturedEnvironment, fetch: ((request: Request) => Promise<Response>) | undefined): CrashReporter | null;
+/** Reports and waits for the delivery, at most `flushMs`. Never rejects. */
+export declare function reportWithin(reporter: CrashReporter, kind: CrashKind, error: unknown, flushMs?: number): Promise<void>;
+export interface FatalCrashOptions {
+    readonly events: CrashEvents;
+    readonly reporter: CrashReporter;
+    /** Fails the process as the runtime would have without a listener: the listeners are stopped by then. */
+    readonly fail: (kind: ProcessCrashKind, error: unknown) => void;
+    readonly flushMs?: number;
+}
+/**
+ * A process that dies of a crash (Bun): the first crash is reported, then the listeners stop and `fail` hands it back
+ * to the runtime, which prints it and exits as before. A second crash during that wait is not reported: the process is
+ * already failing.
+ */
+export declare function reportFatalCrashes(options: FatalCrashOptions): () => void;
+/**
+ * An isolate that survives an unhandled rejection (a Worker): each one is reported, at most
+ * `MAX_FAILURE_REPORTS_PER_MINUTE` per minute, and the runtime keeps its own handling.
+ */
+export declare function reportSurvivedCrashes(events: CrashEvents, reporter: CrashReporter, now?: () => number): () => void;

package/types/src/implement/dispatch.d.ts

@@ -0,0 +1,218 @@
+import type { IamMembership } from '@fabrika/auth';
+import { type CompiledEndpointTable, type CredentialedEndpoint, type EndpointRow, type ExportDescription, type SchemaShape, type ScopeBinding, type WebhookScheme } from '@fabrika/auth-core';
+import { type CapabilityAuthority } from '@fabrika/db/capability';
+import type { DataAccess, FrameworkTables } from '@fabrika/db/framework';
+import type { DataKind } from '@fabrika/db/tables';
+import type { TokenVerifier } from '@fabrika/jwks';
+import type { Schema } from '../contract/define';
+import type { RequestExecutionContext } from '../fetch';
+import { type StoredFileKinds } from '../files/kinds';
+import type { BrowserConfig } from './browser-config';
+import { type CapabilityMint } from './capability';
+import type { ChallengeIssuer } from './challenge';
+import { type ImportWire } from './connect';
+import type { FailureReports } from './failures';
+import { type HeaderPolicy } from './headers';
+import type { ContractDatabase } from './implement';
+import { type SiteDeclaration } from './invocation';
+import { type IssuableLink, type ReadDirectory } from './membership';
+import { type InFlightShare, type ProcedureAdmission } from './public';
+import type { SignedTokens } from './tokens';
+import type { AppUrl } from './urls';
+import { type BindableWebhook } from './webhook';
+import type { WorkloadCredential } from './workload';
+/** SHA-256 of a proxy secret: 32 bytes whatever the secret's length, as `timingSafeEqual` needs. */
+export declare function proxySecretDigest(secret: string): Uint8Array;
+/** Serves the files of an SPA mount. The runtime adapter supplies it: Workers Assets, or the build output on disk. */
+export interface SpaAssets {
+    serve(mount: {
+        readonly prefix: string;
+        readonly dir: string;
+    }, request: Request): Promise<Response>;
+}
+/** What a procedure's context carries beyond its access form, decided once from the artifact. */
+export interface Facilities {
+    /**
+     * `ctx.members`: management where the action is the dimension's `members.manage`; otherwise the member directory of the
+     * nearest dimension, the endpoint's own or one containing it, that declares members (`endpointDirectory`); for an
+     * `app` endpoint of the application's `members.list`, its own people (`endpointAppDirectory`).
+     */
+    readonly members: 'manage' | ReadDirectory | 'application' | null;
+    /** The link mounts whose dimension and issuing action are the endpoint's. */
+    readonly links: readonly IssuableLink[];
+}
+export declare const NO_FACILITIES: Facilities;
+/** A staged-kit site: its handler reaches data through `ctx.db`, in the invocation's transaction. */
+export interface ServedSite {
+    /** A query and an export read only, in a `READ ONLY` transaction; a mutation also writes. */
+    readonly kind: DataKind;
+    readonly declaration: SiteDeclaration;
+}
+export type ServedEndpoint = {
+    readonly kind: 'procedure';
+    readonly row: CredentialedEndpoint;
+    readonly input: Schema | null;
+    readonly output: Schema;
+    readonly handler: (args: {
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly ctx: object;
+        readonly query?: unknown;
+    }) => unknown;
+    readonly facilities: Facilities;
+    /** An export procedure: its request may only read. */
+    readonly readOnly?: true;
+    /** `ctx.connect`, for an endpoint an import's `usedBy` names. */
+    readonly connect?: readonly ImportWire[];
+    /** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
+    readonly site?: ServedSite;
+    /** The origins a staged-kit site's `fetch` reaches while its handler runs; absent for a handler `implement` bound. */
+    readonly egress?: readonly string[];
+    /** Its buckets and time limit; without them (a generated endpoint) no bucket and the request budget. */
+    readonly admission?: ProcedureAdmission;
+    /** A POST's `query`, parsed from the URL beside the body: its schema and its shape. */
+    readonly query?: ProcedureQuery;
+    /** The webhook whose bindings `ctx.webhooks` creates and removes; absent without `binds`. */
+    readonly binds?: BindableWebhook;
+}
+/** What an export's consumer vendors, behind the export's own callers. */
+ | {
+    readonly kind: 'description';
+    readonly row: CredentialedEndpoint;
+    readonly description: ExportDescription;
+} | {
+    readonly kind: 'spa';
+    readonly row: CredentialedEndpoint;
+    readonly prefix: string;
+    readonly dir: string;
+    readonly config: BrowserConfig;
+}
+/** An SPA mount's bare prefix (`/admin`): the proxy admitted it under the mount's access; it redirects to `/admin/`. */
+ | {
+    readonly kind: 'spa-prefix';
+    readonly row: EndpointRow;
+    readonly prefix: string;
+}
+/** An SPA anyone opens: anonymous, served without a token. */
+ | {
+    readonly kind: 'public-spa';
+    readonly row: EndpointRow;
+    readonly prefix: string;
+    readonly dir: string;
+    readonly config: BrowserConfig;
+} | {
+    readonly kind: 'health';
+    readonly row: EndpointRow;
+}
+/** The shell of a link mount's share SPA: anonymous, and served with the fragment bootstrap. */
+ | {
+    readonly kind: 'link-spa';
+    readonly row: EndpointRow;
+    readonly prefix: string;
+    readonly dir: string;
+} | {
+    /** A procedure anyone calls: its handler runs as the endpoint's own workload, holding `actions` only. */
+    readonly kind: 'public';
+    readonly row: EndpointRow;
+    readonly input: Schema | null;
+    readonly output: Schema;
+    readonly handler: (args: {
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly ctx: object;
+        readonly query?: unknown;
+    }) => unknown;
+    readonly actions: readonly string[];
+    readonly query?: ProcedureQuery;
+    /** The endpoint's key: `ctx.app` mints only what IAM signs for it. */
+    readonly credential: WorkloadCredential;
+    readonly admission: ProcedureAdmission;
+    readonly site: ServedSite;
+}
+/** The framework's own `GET` that issues a public procedure's ALTCHA challenge, behind buckets of its own. */
+ | {
+    readonly kind: 'challenge';
+    readonly row: EndpointRow;
+    readonly issuer: ChallengeIssuer;
+    readonly admission: ProcedureAdmission;
+} | {
+    readonly kind: 'webhook';
+    readonly row: EndpointRow;
+    readonly webhook: string;
+    readonly scheme: WebhookScheme;
+    readonly boundTo: ScopeBinding;
+    /** How long a delivery's handler runs after the last body byte; its claim's lease outlasts it. */
+    readonly timeoutMs: number;
+    readonly actions: readonly string[];
+    readonly input: Schema;
+    readonly handler: (args: {
+        readonly input: unknown;
+        readonly ctx: object;
+    }) => unknown;
+    /** The webhook's key: its refs carry only what IAM signs for it. */
+    readonly credential: WorkloadCredential;
+    /** A staged-kit webhook's declaration: its delivery runs in one transaction, through `ctx.db`. */
+    readonly site?: SiteDeclaration;
+};
+/** A POST procedure's `http.query`: the schema it is parsed with, and its described shape, which reads the parameters. */
+export interface ProcedureQuery {
+    readonly schema: Schema;
+    readonly shape: SchemaShape;
+}
+export interface RuntimeParts {
+    readonly table: CompiledEndpointTable;
+    readonly endpoints: ReadonlyMap<string, ServedEndpoint>;
+    /** Endpoint id → `requirementDigest` of its row: what the proxy's `X-Fabrika-Endpoint` must name. */
+    readonly digests: ReadonlyMap<string, string>;
+    readonly verifier: TokenVerifier;
+    /** The token audience: this application's IAM id in this environment, `<app>@<env>`. */
+    readonly audience: string;
+    /** `proxySecretDigest` of the proxy secret every request must carry; `null` where the hop is a service binding. */
+    readonly proxySecretDigest: Uint8Array | null;
+    readonly policy: HeaderPolicy;
+    readonly database: ContractDatabase | null;
+    /** Dimensions a table owns, so `in` and `on` must find the object. */
+    readonly ownedDimensions: ReadonlySet<string>;
+    /** Each dimension's containers, nearest first; a grant on one reaches every value inside it. */
+    readonly containers: ReadonlyMap<string, readonly string[]>;
+    readonly assets: SpaAssets | null;
+    /** IAM's membership operations; `boot` refuses a contract that needs them when the adapter supplies none. */
+    readonly membership: IamMembership | null;
+    /** The framework's own writes (admission buckets, webhook tables); `boot` refuses a webhook or a bucket without them. */
+    readonly framework: FrameworkTables | null;
+    /** This runtime's capability mint, which `boot` alone holds, and the authority its stores are bound to. */
+    readonly mint: CapabilityMint;
+    readonly capabilities: CapabilityAuthority;
+    /** The mini-ORM of the bound `scoped(tables)` layer; `boot` refuses a site without one. */
+    readonly data: DataAccess | null;
+    /** The contract's file kinds: file fields, file outputs, `ctx.files.put` and `.open`; `null` when it declares none. */
+    readonly fileKinds: StoredFileKinds | null;
+    /** Where a 5xx goes: the server log, and Operations when the application has a DSN. */
+    readonly failures: FailureReports;
+    /** Kicks a contract job under its own key, in the background (`BoundJobs.kick`); it never rejects. */
+    readonly kick: (job: string) => Promise<void>;
+    /** The contract's actions, sorted: what a caller document lists a pattern grant as. */
+    readonly actions: readonly string[];
+    /** The connections all public procedures of this instance hold at once, at most. */
+    readonly publicShare: InFlightShare;
+    /** Whether the proxy's `X-Fabrika-Client-Ip` is the visitor's, so `ctx.client.ip` reads it. */
+    readonly clientVouched: boolean;
+    /** The environment's signed tokens: verified in each input and query, signed by `ctx.tokens`. */
+    readonly tokens: SignedTokens;
+    /** `ctx.url`: absolute links to the application's own procedures. */
+    readonly url: AppUrl;
+    /** The environment's public origin (`FABRIKA_APP_ORIGIN`), which a Twilio signature covers; `null` where it has none. */
+    readonly origin: string | null;
+}
+export declare class ContractRuntime {
+    #private;
+    constructor(parts: RuntimeParts);
+    /**
+     * Every answer of a download endpoint, a denial included, carries the file treatment; every other one the policy.
+     * `exec` keeps a failure's report alive past the response, where the runtime would otherwise end it.
+     */
+    fetch(request: Request, exec?: RequestExecutionContext): Promise<Response>;
+}
+/**
+ * One envelope, `{ error: { type, message, issues? } }`. A client error keeps its own message and issues; every
+ * 5xx and every refused capability answers a fixed message; what made a 5xx reaches only `FailureReports`, as a code.
+ */
+export declare function errorResponse(error: unknown, where: string): Response;

package/types/src/implement/egress.d.ts

@@ -0,0 +1,14 @@
+/** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
+export declare function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T>;
+/**
+ * `facility` with each of its methods run outside any site's scope: a framework facility a handler calls, whose own
+ * requests are the platform's, not the site's.
+ */
+export declare function platformFacility<T extends object>(facility: T): T;
+/** `work`, outside any site's scope: a framework call that happens to run inside a handler. */
+export declare function platformCall<T>(work: () => T): T;
+/**
+ * Wraps the global `fetch` in the guard, once: a `fetch` that is already a guard stays. A test that replaces `fetch`
+ * after boot replaces the guard with it.
+ */
+export declare function installEgressGuard(): void;

package/types/src/implement/environment.d.ts

@@ -0,0 +1,14 @@
+import type { ApplicationEnvironment } from './implement';
+/** Every variable under this prefix is the framework's; no application code sees one. */
+export declare const FRAMEWORK_PREFIX = "FABRIKA_";
+export interface CapturedEnvironment {
+    /** The `FABRIKA_*` variables, for `boot` only. */
+    readonly framework: Readonly<Record<string, string>>;
+    /** Every other variable or binding, for the application's `deps`. */
+    readonly application: ApplicationEnvironment;
+}
+/**
+ * Splits `source` into the framework's variables and the application's, then scrubs the process environment.
+ * The generated entrypoint calls it through its runtime adapter before it imports `src/app.ts`.
+ */
+export declare function captureEnvironment(source: Readonly<Record<string, unknown>>): CapturedEnvironment;

package/types/src/implement/failures.d.ts

@@ -0,0 +1,34 @@
+import type { OperationsReporter } from '../jobs/report';
+export type RequestFailureCode = 'framework_fault' | 'unavailable' | 'capability_refused' | 'query_refused' | 'handler_status' | 'handler_failed';
+/** At most this many request failures per process and minute become Operations events; every one is logged. */
+export declare const MAX_FAILURE_REPORTS_PER_MINUTE = 30;
+/** Chosen by `instanceof` against the framework's own classes, never by `name`, which any thrown value can set. */
+export declare function failureCode(error: unknown): RequestFailureCode;
+/** What a log may say of a framework failure: the reason its catalog keys it by, and that reason's fixed text. */
+export interface FailureReason {
+    readonly reason: string;
+    readonly text: string;
+}
+/** A framework failure's reason and the fixed text its catalog gives it; `null` for any other thrown value. */
+export declare function failureReason(error: unknown): FailureReason | null;
+export interface RequestFailure {
+    /** The endpoint id the request selected, or `request` before one was selected. */
+    readonly endpoint: string;
+    /** The proxy's `X-Request-Id`. */
+    readonly requestId: string | null;
+    readonly status: number;
+    readonly error: unknown;
+}
+/** At most `limit` admissions per minute of `now`; the next minute starts again. */
+export declare class MinuteBudget {
+    #private;
+    constructor(limit: number, now?: () => number);
+    admit(): boolean;
+}
+export declare class FailureReports {
+    #private;
+    /** `reporter` is `null` without an Operations DSN: the log line is then the only record. */
+    constructor(reporter: OperationsReporter | null, now?: () => number);
+    /** Never rejects. The returned delivery may outlive the response; a runtime with `waitUntil` keeps it alive. */
+    record(failure: RequestFailure): Promise<void>;
+}

package/types/src/implement/faults.d.ts

@@ -0,0 +1,44 @@
+/** Why the framework failed a request, as a closed catalog with the fixed text a log may print. */
+export declare const SERVER_FAULTS: {
+    readonly iam_unavailable: "IAM could not be reached or could not complete the operation";
+    readonly delegation_missing: "a membership endpoint was reached without the proxy's delegation grant";
+    readonly iam_answer_mismatch: "IAM answered for another scope or principal than the request asked for";
+    readonly iam_answer_unlabelled: "IAM answered a member without a label where the member directory's dimension shows labels";
+    readonly link_mount: "the endpoint asked for a link of a mount it does not issue";
+    readonly directory_unlocated: "no table locates the value of the member directory's dimension that the endpoint's object lies in";
+    readonly facility_unbound: "a facility the endpoint needs (assets, data layer, framework tables or IAM transport) was not bound at boot";
+    readonly endpoint_decision_missing: "the request did not carry the proxy's endpoint decision";
+    readonly endpoint_decision_mismatch: "the proxy applied other rules than this version serves the endpoint with";
+    readonly key_set_unavailable: "the IAM key set could not be fetched; nothing was checked";
+    readonly output_refused: "the handler returned a value its output schema refuses";
+    readonly contract_inconsistent: "the compiled endpoint misses what its kind needs (a path parameter, a body limit or a capability kind)";
+    readonly webhook_binding_mismatch: "a webhook binding reaches another dimension than the webhook's";
+    readonly webhook_unverifiable: "a webhook verifies a signature over its public URL (Twilio), and the environment has no FABRIKA_APP_ORIGIN";
+    readonly webhook_claim_lost: "a delivery's claim expired and another copy of the delivery took it over before this one committed; nothing it wrote is kept";
+    readonly workload_unauthorized: "the workload's key or token does not carry the authority its declaration needs";
+    readonly request_cancelled: "the request was cancelled or outlived its budget before its transaction committed; nothing it wrote is kept";
+    readonly file_object_missing: "a file's object is missing from storage";
+    readonly file_object_mismatch: "a file's object has another size than its row records";
+    readonly file_key_taken: "a new file's object key already held an object this upload did not write";
+    readonly file_kind_unknown: "ctx.files.put or a file field named a file kind the contract does not declare";
+    readonly file_put: "ctx.files.put was called without the options it takes ({ type, name? })";
+    readonly file_output_kind: "the handler answered a file of another kind than its output declares";
+    readonly file_sweep_failed: "the sweep could not delete a removed or orphaned file's object or row; the next run retries it";
+    readonly challenge_unavailable: "a form's challenge provider could not be reached in time or did not answer as it documents";
+    readonly challenge_misconfigured: "a form's challenge provider refused the application's secret";
+    readonly attachment_rows: "the handler returned more rows than its attachment declares (maxRows)";
+    readonly attachment_cell: "a cell of the attachment is longer than one cell may hold";
+    readonly attachment_size: "the encoded attachment is larger than it declares (maxBytes); no body was sent";
+    readonly redirect_refused: "the handler redirected to a target that is neither its own origin's path, an origin its redirect() lists, nor a URL a verified token of the request carries";
+    readonly token_claims_refused: "the claims a site signed are not what the token purpose's claims schema admits";
+    readonly token_keys_missing: "a site signed a token, and the environment holds no token key";
+    readonly url_unbuildable: "ctx.url named no procedure of the contract, passed a parameter its HTTP shape does not read, or the environment has no public origin";
+};
+export type ServerFaultReason = keyof typeof SERVER_FAULTS;
+/** A failure the framework itself describes. Its message is for the author's own run, never the response or a log. */
+export declare class ServerFault extends Error {
+    readonly name = "ServerFault";
+    readonly reason: ServerFaultReason;
+    readonly status: number;
+    constructor(reason: ServerFaultReason, message: string, status?: number);
+}

package/types/src/implement/headers.d.ts

@@ -0,0 +1,7 @@
+import type { CspExtensions } from '@fabrika/auth-core';
+import { type HeaderPolicy } from '@fabrika/proxy-core/headers';
+export type { HeaderPolicy };
+/** The policy of an application: its contract's named origins and the Operations ingest origin the browser reports to. */
+export declare function applicationPolicy(csp: CspExtensions, operationsOrigin: string | null): HeaderPolicy;
+/** A copy of `response` carrying the policy; whatever the handler or an asset server set for these names is replaced. */
+export declare function withHeaderPolicy(response: Response, policy: HeaderPolicy): Response;

package/types/src/implement/implement.d.ts

@@ -0,0 +1,58 @@
+import type { TablePolicyArtifact } from '@fabrika/auth-core';
+import type { DataLayer } from '@fabrika/db';
+import type { CapabilityAuthority } from '@fabrika/db/capability';
+import type { Session } from '@fabrika/db/framework';
+import type { EmailSender } from '@fabrika/email';
+import type { ConnectSnapshot } from '../contract/connect';
+import type { AnyContract } from '../contract/define';
+import type { ConnectSnapshots, ExactHandlers, HandlersOf } from './types';
+/**
+ * What the framework reads from the application's tables before a handler runs. The table policies are what
+ * `compileContract` takes; `locate` resolves an object's containment chain for `on` and checks that an `in` scope
+ * exists. For `@fabrika/db`'s `scoped(tables)`, `boot` builds one from the locator only it receives when it binds.
+ */
+export interface ContractDatabase {
+    readonly tables: Readonly<Record<string, TablePolicyArtifact>>;
+    /**
+     * The containers an object lies in, by dimension, or `null` when the table that owns `dimension` has no such row.
+     * `using` is a job's transaction, which also sees the object it wrote; a layer of the application's own ignores it.
+     */
+    locate(dimension: string, id: string, using?: Session): Promise<ReadonlyMap<string, string> | null>;
+}
+/** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or a `ContractDatabase` of the application's own. */
+export type ImplementationDatabase = DataLayer | ContractDatabase;
+/**
+ * The application's own variables: everything the platform and the operator set except the framework's. Values are
+ * unchecked, so `deps` parses what it reads.
+ */
+export type ApplicationEnvironment = Readonly<Record<string, unknown>>;
+/** What the framework hands `deps`: the authority `@fabrika/db` asks whether a capability belongs to this request. */
+export interface DepsRuntime {
+    readonly capabilities: CapabilityAuthority;
+}
+/** A contract with its handlers, ready for `boot`. Only `implement` and `serve` make one. */
+export interface ContractImplementation<C extends AnyContract = AnyContract> {
+    readonly contract: C;
+    readonly database: ImplementationDatabase | null;
+    /** The vendored snapshot of each import, by the import's name; `boot` checks each against the contract's digest. */
+    readonly connect?: Readonly<Record<string, ConnectSnapshot>>;
+    /** Runs `deps`, then `handlers` over its result. The tree is checked by the types of `implement`, and again by `boot`. */
+    readonly handlers: (env: ApplicationEnvironment, runtime: DepsRuntime) => unknown;
+    /** The application's own transport, built once at boot from its own variables; `null` when they configure none. */
+    readonly mail?: (env: ApplicationEnvironment) => EmailSender | null;
+}
+/**
+ * Binds one handler to every procedure of the contract. `deps` runs once, at `boot`; `handlers` receives what it
+ * returned and builds the handler tree, so a handler reaches its dependencies through that closure.
+ */
+export declare function implement<const C extends AnyContract, Deps, H extends HandlersOf<C, Snap>, Snap extends ConnectSnapshots<C> = ConnectSnapshots<C>>(contract: C, implementation: {
+    readonly database: ImplementationDatabase | null;
+    /** The vendored snapshot of each import (`fabrika/connect/*.ts`), by the import's name. */
+    readonly connect?: Snap;
+    readonly deps: (env: ApplicationEnvironment, runtime: DepsRuntime) => Deps;
+    readonly handlers: (deps: Deps) => H & ExactHandlers<H, C>;
+}): ContractImplementation<C>;
+/** The one way a `ContractImplementation` is made, by `implement` and `serve`: frozen, and known to `isContractImplementation`. */
+export declare function contractImplementation<C extends AnyContract>(made: ContractImplementation<C>): ContractImplementation<C>;
+/** Whether `value` is what `implement` or `serve` returned: how a loader checks a module it imported by path. */
+export declare function isContractImplementation(value: unknown): value is ContractImplementation;

package/types/src/implement/index.d.ts

@@ -0,0 +1,24 @@
+export { EmailDeliveryError, type EmailDeliveryErrorCode, type EmailDeliveryOutcome, type EmailDeliveryResult, type EmailSender, type EmailSenderCapabilities, mayRetryDelivery, } from '@fabrika/email';
+export type { FileCollectionHandle, FileCollectionReader, FileListing, ListedFile, OpenedFile } from '../files/handle';
+export { FILE_SWEEP_JOB } from '../files/kinds';
+export { FILE_SCAN_JOB, type FileScanner, SCAN_LIMITS, type ScanBatchResult, type ScanFailure, type ScanObject, type ScanVerdict, } from '../files/scan';
+export { crashEnvelope, type OperationsReport, type OperationsReporter, reportEnvelope } from '../jobs/report';
+export { type ContractJobs, type JobClock, JobError, type JobFailureCode, type JobRunOptions, type JobRunResult } from '../jobs/runner';
+export { secretScrubber } from '../jobs/scrub';
+export type { AppMail, AppMailMessage, JobContext, JobHandler, JobHandlersOf, JobPrincipal } from '../jobs/types';
+export { LINK_BOOTSTRAP_SCRIPT } from './anonymous';
+export { boot, BootError, type BootOptions, type ContractApp, type IamKeySource } from './boot';
+export { readBoundedBytes, REQUEST_BUDGET_MS } from './bounded';
+export { AppCapability, CapabilityRefusedError, Ref, Within } from './capability';
+export { CHALLENGE_LIMITS, type ChallengeFetch, TURNSTILE_VERIFY_URL } from './challenge';
+export { type ConnectFailure, type ConnectFetch, type ConnectResult, type ConnectVariables, connectVariables, isJsonMediaType } from './connect';
+export type { SpaAssets } from './dispatch';
+export { type CapturedEnvironment, captureEnvironment } from './environment';
+export type { ApplicationEnvironment, ContractDatabase, ContractImplementation, DepsRuntime, ImplementationDatabase } from './implement';
+export { isContractImplementation } from './implement';
+export type { ApplicationDirectory, ApplicationMember, ApplicationMemberPage, ApplicationMemberRole, AssignedMember, DirectoryMember, IssuedLink, LinkIssuing, Member, MemberDirectory, MemberList, MemberLookup, MemberManagement, MemberTarget, } from './membership';
+export type { AppPrincipal, LinkHolder, Principal, PrincipalOf, PublicPrincipal, ServicePrincipal, UserPrincipal } from './principal';
+export { type AppDeps, defineDeps, serve, type ServeOptions } from './serve';
+export type { AccessContext, ConnectCall, ConnectContext, ConnectSnapshots, ContractContext, ExactHandlers, Handler, HandlerInput, HandlersOf, RequestClient, RequestContext, WebhookHandler, } from './types';
+export type { WebhookDelivery, WebhookPrincipal } from './webhook';
+export { issuerWorkloadTokens, type WorkloadTokenSource } from './workload';