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

package/types/src/files/kinds.d.ts

@@ -0,0 +1,105 @@
+import type { ContractArtifact, FileKindArtifact } from '@fabrika/auth-core';
+import { type FileBinding, type FileColumnRef, type StoredFiles } from '@fabrika/db/framework';
+import { type FileObjectStore } from '@fabrika/platform';
+import type { FileRef } from '../contract/file';
+import type { ImplementationDatabase } from '../implement/implement';
+import type { OperationsReporter } from '../jobs/report';
+import type { OpenedFile } from './handle';
+import { type FileScanner } from './scan';
+import { FileDownload } from './treatment';
+/**
+ * The framework's sweep job: hourly, it deletes the files no declared column references and the pending ones past the
+ * grace, so none waits for the next request. A reserved name with `-`, which no `c.cron` name can take;
+ * `@fabrika/provider-zerops` writes it into the crontab on this schedule (`ZEROPS_FILE_SWEEP_JOB`).
+ */
+export declare const FILE_SWEEP_JOB = "fabrika-file-sweep";
+export declare const FILE_SWEEP_SCHEDULE = "41 * * * *";
+export declare const FILE_SWEEP_TIMEOUT_MS: number;
+/** How long a staged file waits for its first reference before the sweep may delete it. */
+export declare const FILE_PENDING_GRACE_MS: number;
+/** One file part of a multipart body, as the multipart reader hands it over. */
+export interface FilePart {
+    readonly filename: string | null;
+    /** The media type the part declares; the bytes must be of it. */
+    readonly contentType: string | null;
+    readonly body: ReadableStream<Uint8Array>;
+}
+/** What `ctx.files.put` takes: the bytes, and the type they must be of. */
+export interface PutOptions {
+    readonly type: string;
+    readonly name?: string;
+}
+/** The bytes `ctx.files.put` writes: in memory, or a stream a large file comes from. */
+export type PutBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
+/**
+ * One request's or job attempt's files: the holder its file references belong to, the id a pending file it stages
+ * carries, and what it staged, so a known rollback deletes what nothing claimed.
+ */
+export declare class FileWork {
+    #private;
+    readonly holder: object;
+    readonly request: string;
+    constructor(holder: object, request: string);
+    staged(id: string): void;
+    get stagedIds(): readonly string[];
+}
+interface Kind {
+    readonly name: string;
+    readonly artifact: FileKindArtifact;
+}
+export declare class StoredFileKinds {
+    #private;
+    constructor(kinds: readonly Kind[], store: FileObjectStore, files: StoredFiles, columns: readonly FileColumnRef[]);
+    /** Whether the contract declares kind `name`. */
+    has(name: string): boolean;
+    /** Whether any kind scans, so the scan job runs. */
+    get scans(): boolean;
+    /** What the data layer claims and checks a site's file references with. */
+    binding(work: FileWork): FileBinding;
+    /**
+     * One incoming file of a request's file field, staged for `work`: its declared type must be one the kind admits and
+     * its first bytes that type. `null` for an empty part without a file name: a file input the visitor left empty.
+     */
+    receive(work: FileWork, kind: string, part: FilePart): Promise<FileRef | null>;
+    /** `ctx.files.put`: a file of `kind` this work creates, staged like an incoming one; its reference is the work's. */
+    put(work: FileWork, kind: unknown, body: PutBody, options: PutOptions): Promise<FileRef>;
+    /**
+     * After a known rollback: every file the work staged and nothing claimed goes now. After an uncertain outcome (a lost
+     * commit answer, a crash) nothing is deleted here; the sweep decides from the database.
+     */
+    release(work: FileWork): Promise<void>;
+    /** `ctx.files.open(ref)`: the bytes of a live file, read whole, at most `maxBytes` (the kind's by default). */
+    open(work: FileWork, reference: unknown, options?: {
+        readonly maxBytes?: number;
+    }): Promise<OpenedFile>;
+    /** The answer of a procedure whose output is a file: the file the handler returned, streamed. */
+    download(work: FileWork, endpoint: string, kind: string, reference: unknown): Promise<FileDownload>;
+    /**
+     * The sweep: it finishes deletions a crash interrupted, adopts the migrated files a declared column references, then
+     * deletes, batch by batch, every file past the grace that no declared column references: its row and the record of
+     * its object in one transaction (the foreign key keeps a referenced one), then the object, then the record.
+     */
+    sweep(signal: AbortSignal): Promise<void>;
+    /** One scan pass over the quarantined files of every scanning kind: the scan job's part for kinds. */
+    scanPass(scanner: FileScanner | null, reporter: OperationsReporter, signal: AbortSignal): Promise<void>;
+}
+/** Where `ctx.files.put` and `.open` run: the site's name, its liveness check, and whether it may create a file. */
+export interface StoredFileSite {
+    readonly where: string;
+    readonly check: () => void;
+    /** A query reads only, so it puts no file. */
+    readonly writes: boolean;
+}
+/** `ctx.files.put` and `.open` of one site, bound to its work. */
+export declare function storedFilesHandle(kinds: StoredFileKinds | null, work: FileWork, site: StoredFileSite): {
+    readonly put: (kind: unknown, body: PutBody, options: PutOptions) => Promise<FileRef>;
+    readonly open: (file: unknown, options?: {
+        readonly maxBytes?: number;
+    }) => Promise<OpenedFile>;
+};
+/**
+ * The file kinds of `artifact`, or `null` when it declares none. Every reason a kind cannot be served goes into
+ * `problems`, so `boot` refuses to start rather than take a file it cannot check.
+ */
+export declare function storedFileKinds(artifact: ContractArtifact, database: ImplementationDatabase | null, store: FileObjectStore | undefined, problems: string[]): StoredFileKinds | null;
+export {};

package/types/src/files/scan.d.ts

@@ -0,0 +1,80 @@
+import type { QuarantinedStoredFile } from '@fabrika/db/framework';
+import type { FileObjectStore } from '@fabrika/platform';
+import type { OperationsReporter } from '../jobs/report';
+/** The reserved name of the scan job: a `c.cron` job name cannot contain `-`, so no application job takes it. */
+export declare const FILE_SCAN_JOB = "fabrika-file-scan";
+export declare const FILE_SCAN_SCHEDULE = "* * * * *";
+export declare const SCAN_LIMITS: {
+    /** One pass scans at most this many files, and at most `batchBytes` of them; the next pass takes the rest. */
+    readonly batchFiles: 20;
+    readonly batchBytes: number;
+    /** The scanner's whole run — reading the objects, the scan, the cleanup — is stopped by then. */
+    readonly scanTimeoutMs: number;
+    /** The attempt's deadline; it outlasts the scanner's, so the verdicts are written before it. */
+    readonly jobTimeoutMs: number;
+    /** A file that got no verdict this many times is rejected. */
+    readonly maxAttempts: 5;
+    /** The wait before the next try of a file without a verdict: doubled per try, at most `retryMaxMs`. */
+    readonly retryBaseMs: 60000;
+    readonly retryMaxMs: number;
+};
+/** What the scanner decided about one file. Only `clean` promotes; `infected` rejects; anything else is retried. */
+export type ScanVerdict = {
+    readonly kind: 'clean';
+} | {
+    readonly kind: 'infected';
+    readonly signature: string;
+} | {
+    readonly kind: 'unscanned';
+};
+/** Why a whole batch got no verdict. Fixed codes only: a scanner's own output is never reported. */
+export type ScanFailure = 'scanner_missing' | 'signatures_missing' | 'signatures_stale' | 'scanner_failed' | 'timeout' | 'output_overflow';
+export type ScanBatchResult = {
+    readonly ok: true;
+    readonly verdicts: ReadonlyMap<string, ScanVerdict>;
+} | {
+    readonly ok: false;
+    readonly failure: ScanFailure;
+};
+export interface ScanObject {
+    /** The file's id: a UUID. */
+    readonly id: string;
+    /**
+     * The object's bytes. It throws when they are missing, differ from the upload's, are an archive the scanner cannot
+     * read in full, or `signal` aborts.
+     */
+    open(signal: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+}
+export interface FileScanner {
+    /**
+     * A verdict per file id, or why the batch got none. A file whose `open` threw has no verdict. Stops once `signal`
+     * aborts. Never throws.
+     */
+    scan(objects: readonly ScanObject[], signal: AbortSignal): Promise<ScanBatchResult>;
+}
+/** What one scanning file kind lets the scan pass do: take its due files, and write each verdict. */
+export interface ScanningKind {
+    readonly name: string;
+    readonly table: {
+        quarantined(limit: number, now: Date): Promise<readonly QuarantinedStoredFile[]>;
+        promote(id: string, sha256: string, version: string): Promise<boolean>;
+        deferScan(id: string, attempts: number, after: Date): Promise<boolean>;
+        reject(id: string): Promise<boolean>;
+    };
+}
+/** The next try of a file that has had `attempts` tries: one minute, doubled per try, at most an hour. */
+export declare function retryDelayMs(attempts: number): number;
+export interface ScanPassInput {
+    readonly collections: readonly ScanningKind[];
+    readonly store: FileObjectStore;
+    /** `null` when the runtime adapter supplies none: every quarantined file stays quarantined. */
+    readonly scanner: FileScanner | null;
+    readonly reporter: OperationsReporter;
+    readonly signal: AbortSignal;
+    readonly now?: () => Date;
+}
+/**
+ * One pass. A verdict write that fails (the lease lost, the database gone) throws, so the runner reports the run as
+ * failed; everything the scanner decides is reported here and never throws.
+ */
+export declare function runScanPass(input: ScanPassInput): Promise<void>;

package/types/src/files/sniff.d.ts

@@ -0,0 +1,7 @@
+/** How many leading bytes an upload is judged by. */
+export declare const SNIFF_BYTES = 512;
+/** The ZIP-based types: a ZIP archive, and an Office Open XML document, which is one. */
+export declare const ZIP_TYPES: readonly string[];
+export declare const SNIFFABLE_TYPES: readonly string[];
+/** Whether the first bytes of an upload are of `type`; always false for a type the framework cannot verify. */
+export declare function bytesAreOfType(type: string, head: Uint8Array): boolean;

package/types/src/files/streams.d.ts

@@ -0,0 +1,17 @@
+/** The client's file name, metadata only: at most 255 code points, never half a character, no control characters. */
+export declare function cleanName(raw: string): string | null;
+/** The first `size` bytes of `body`, and a stream that yields the whole body again. */
+export declare function readHead(body: ReadableStream<Uint8Array>, size: number): Promise<{
+    readonly head: Uint8Array;
+    readonly stream: ReadableStream<Uint8Array>;
+}>;
+/** The body as it is stored: hashed on the way, and failed once `timeoutMs` (`null`: no timer) passes before it ends. */
+export declare function digesting(body: ReadableStream<Uint8Array>, timeoutMs: number | null): {
+    readonly stream: ReadableStream<Uint8Array>;
+    digest(): string;
+    timedOut(): boolean;
+    stop(): void;
+};
+/** The whole body when it holds exactly `size` bytes; `null` as soon as it proves longer, or once it ends shorter. */
+export declare function readExactly(body: ReadableStream<Uint8Array>, size: number): Promise<Uint8Array | null>;
+export declare function isNamed(error: unknown, name: string): boolean;

package/types/src/files/treatment.d.ts

@@ -0,0 +1,18 @@
+/** A file the download endpoint answers. `ContractRuntime` turns it into the response, with the file treatment. */
+export declare class FileDownload {
+    readonly body: ReadableStream<Uint8Array>;
+    readonly size: number;
+    /** The type recorded at upload, which its bytes were checked against; never a type a request sent. */
+    readonly contentType: string;
+    readonly name: string | null;
+    constructor(file: {
+        readonly body: ReadableStream<Uint8Array>;
+        readonly size: number;
+        readonly contentType: string;
+        readonly name: string | null;
+    });
+}
+export declare function contentDisposition(contentType: string, name: string | null): string;
+export declare function fileResponse(file: FileDownload): Response;
+/** An error of a download endpoint, with the file treatment in place of the header policy. */
+export declare function withFileTreatment(response: Response): Response;

package/types/src/from-row.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod/v4';
+/** `companyId` → `company_id`: the column a field is read from. */
+export type Snake<S extends string> = S extends `${infer Head}${infer Tail}` ? `${Head extends Lowercase<Head> ? Head : `_${Lowercase<Head>}`}${Snake<Tail>}` : S;
+/** A row value a field accepts: text for a literal string (the schema checks it), a `Date` for ISO text. */
+type Widened<V> = V extends string ? string | Date : V;
+/** The row `fromRow` takes for `S`: one column per declared field; any other column is allowed and dropped. */
+export type RowInput<S extends z.ZodObject> = {
+    readonly [K in keyof z.input<S> as Snake<K & string>]: Widened<z.input<S>[K]>;
+};
+/** The row as `schema`'s output; a row the schema refuses throws, as a handler's bug. */
+export declare function fromRow<const S extends z.ZodObject>(schema: S, row: RowInput<S>): z.output<S>;
+/** A list's page as a page output: each row through `fromRow`, and `next` as the list answered it. */
+export declare function fromPage<const S extends z.ZodObject>(schema: S, page: {
+    readonly items: readonly RowInput<S>[];
+    readonly next: string | null;
+}): {
+    items: z.output<S>[];
+    next: string | null;
+};
+export {};

package/types/src/honeypot.d.ts

@@ -0,0 +1,2 @@
+/** Whether the hidden field was filled: `if (honeypot(input.website)) return {}`. */
+export declare function honeypot(value: string | null | undefined): boolean;

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

@@ -0,0 +1,26 @@
+import { HttpError } from '../errors';
+/** The slowest body a procedure waits for, in bytes per second: its deadline is `maxBytes` at this rate, 30 s at least. */
+export declare const BODY_RATE_FLOOR: number;
+/** How long a body of at most `maxBytes` may take to arrive. */
+export declare function bodyDeadlineMs(maxBytes: number): number;
+/**
+ * The body as bytes, read until `maxBytes`; a longer one stops the read and is a 413. A body whose stream fails before
+ * its end (the client closed the connection) is the sender's 400 `aborted`, never a failure of the application.
+ */
+export declare function readBoundedBody(request: Request, maxBytes: number, deadline?: AbortSignal): Promise<Uint8Array<ArrayBuffer>>;
+/** What a request answers whose body did not arrive whole: nobody reads it, and no failure is reported. */
+export declare function abortedBody(): HttpError;
+/**
+ * Runs before any other script of the share SPA: it takes the key out of the fragment, removes the fragment from the
+ * address with `history.replaceState`, and keeps the key in a closure. Telemetry that reads `location` later finds
+ * no key; the SPA reads it through `shareKey()` of `@fabrika/app/client`.
+ */
+export declare const LINK_BOOTSTRAP_SCRIPT = "(function () {\n\tvar fragment = window.location.hash.slice(1)\n\tvar key = /^px_[A-Za-z0-9_-]+$/.test(fragment) ? fragment : null\n\tif (window.location.hash !== '') {\n\t\twindow.history.replaceState(window.history.state, '', window.location.pathname + window.location.search)\n\t}\n\tObject.defineProperty(window, '__fabrikaShareKey', {\n\t\tvalue: function () {\n\t\t\treturn key\n\t\t},\n\t\twritable: false,\n\t\tconfigurable: false,\n\t\tenumerable: false,\n\t})\n})()\n";
+/** The share SPA's bootstrap path under the link prefix. */
+export declare function bootstrapPath(prefix: string): string;
+export declare function bootstrapResponse(): Response;
+/**
+ * The share SPA's document with the bootstrap as its first script: right after `<head>`, so it runs before every
+ * module script and every script the document loads. A response that is not HTML passes unchanged.
+ */
+export declare function withBootstrap(response: Response, prefix: string): Promise<Response>;

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

@@ -0,0 +1,14 @@
+import type { AttachmentShape } from '@fabrika/auth-core';
+import type { Schema } from '../contract/define';
+/**
+ * The response an attachment answers. `rows` is what the handler returned: each row is projected and validated with
+ * the row schema of `output` only when its turn to be encoded comes.
+ */
+export declare function attachmentResponse(endpoint: string, shape: AttachmentShape, output: Schema, rows: unknown): Response;
+/**
+ * The header line of the column names, then one line per row, each row read through `rowOf` only when its turn
+ * comes. The row count is checked before any row is read. Each field is encoded on its own, with its separator, and
+ * counted against `maxBytes` before the next one is read, so neither a long result nor a wide row is built past the
+ * limit; only then is the whole file joined.
+ */
+export declare function encodeCsv(endpoint: string, shape: AttachmentShape, rows: unknown, rowOf: (row: unknown) => unknown): Uint8Array<ArrayBuffer>;

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

@@ -0,0 +1,109 @@
+import { type IamMembershipRpc, type Jwks } from '@fabrika/auth-core';
+import type { Database } from '@fabrika/db';
+import type { EmailProviderRegistry } from '@fabrika/email';
+import type { FileObjectStore } from '@fabrika/platform';
+import type { RequestExecutionContext } from '../fetch';
+import { type FileScanner } from '../files/scan';
+import { type MailStandIn } from '../jobs/mail';
+import { type ContractJobs, type HandlerErrorSink } from '../jobs/runner';
+import type { ChallengeFetch, ChallengeWork } from './challenge';
+import { type ConnectFetch } from './connect';
+import { type SpaAssets } from './dispatch';
+import type { CapturedEnvironment } from './environment';
+import type { ContractImplementation } from './implement';
+import { type WorkloadTokenSource } from './workload';
+/** Where the token verifier gets IAM's public keys: the IAM binding on Cloudflare, the issuer's JWKS elsewhere. */
+export interface IamKeySource {
+    getJwks(): Promise<Jwks>;
+}
+export interface BootOptions {
+    /** The variables `captureEnvironment` took before the application's modules loaded. */
+    readonly environment: CapturedEnvironment;
+    readonly iam: IamKeySource;
+    /** Serves the SPA mounts. Without it, a contract that declares one does not boot. */
+    readonly assets?: SpaAssets;
+    /** The application's Postgres connection, which the Bun adapter opens. Without it, an application on `@fabrika/db` does not boot. */
+    readonly database?: Database;
+    /**
+     * The proxy authenticates itself with `FABRIKA_PROXY_SECRET`, and the application does not boot without it. The Bun
+     * adapter sets it: on Zerops a namespace is one private network. On Cloudflare the service binding is the
+     * authenticated hop (ADR-0022 rule 1). A secret that is set is checked either way.
+     */
+    readonly requireProxySecret?: boolean;
+    /** The object storage of the stored files, which the Bun adapter opens. Without it, a contract with file kinds does not boot. */
+    readonly files?: FileObjectStore;
+    /**
+     * The malware scanner of the scan job of `scan: true` file kinds, which the Bun adapter supplies to a job run
+     * (`clamscanScanner`). Without it the scan job leaves every quarantined file quarantined and reports.
+     */
+    readonly scanner?: FileScanner;
+    /**
+     * IAM's membership operations: the IAM binding on Cloudflare, `HttpIamRpc` elsewhere. Without it, a contract that
+     * creates scopes, manages members or issues share links does not boot.
+     */
+    readonly membership?: IamMembershipRpc;
+    /**
+     * Cloudflare service bindings to the owners' proxy Workers, by binding name (`FABRIKA_CONNECT_<IMPORT>`). An import
+     * without one calls its owner with `fetch`.
+     */
+    readonly connectBindings?: Readonly<Record<string, ConnectFetch>>;
+    /**
+     * Where a job or a webhook exchanges its key for a token: IAM's public token exchange on Bun. Without it, a contract
+     * with a job or a webhook does not boot.
+     */
+    readonly workloadTokens?: WorkloadTokenSource;
+    /** What posts a report to Operations' ingest; `fetch` by default. */
+    readonly operationsFetch?: (request: Request) => Promise<Response>;
+    /** What asks a public procedure's challenge provider to verify a token; `fetch` by default. */
+    readonly challengeFetch?: ChallengeFetch;
+    /**
+     * The developer's own machine only (`fabrika app dev`): the token a challenge admits more than once, which
+     * Turnstile's always-passing test widget hands out for every call. Every other token stays single use.
+     */
+    readonly repeatableChallengeToken?: string;
+    /**
+     * The work of every ALTCHA challenge in place of the contract's `cost`: the test kit's and `fabrika app dev`'s
+     * (`MINIMAL_CHALLENGE_WORK`), so a test solves one in milliseconds. A deployed application never sets it.
+     */
+    readonly challengeWork?: ChallengeWork;
+    /**
+     * The developer's own machine only (`fabrika app dev`): what a job's handler threw, which every log of a deployed
+     * application withholds because it may carry a credential.
+     */
+    readonly revealHandlerErrors?: HandlerErrorSink;
+    /** The providers `FABRIKA_EMAIL_PROVIDER` may name for the jobs that declare `mailer: 'installation'`; the built-in ones by default. */
+    readonly emailProviders?: EmailProviderRegistry;
+    /**
+     * Providers added to `emailProviders` only in a local composition (a loopback `FABRIKA_IAM_ISSUER`); anywhere else
+     * `FABRIKA_EMAIL_PROVIDER` naming one is refused like any unknown provider. On a name both hold, `emailProviders` wins.
+     */
+    readonly localEmailProviders?: EmailProviderRegistry;
+    /**
+     * The test kit's stand-in for every mailer job, or `'none'` for an installation without mail; boot then reads neither
+     * `FABRIKA_EMAIL_*` nor `serve`'s `mail`.
+     */
+    readonly mailStandIn?: MailStandIn;
+    /** The connections the application's pool holds: a quarter of them, at least one, is the public procedures' share. */
+    readonly connections?: number;
+    /**
+     * `'vouched'` where the proxy's `X-Fabrika-Client-Ip` is the visitor's own address, so `ctx.client.ip` reads it. A
+     * runtime behind a balancer whose range the platform does not trust (Zerops, until it does) leaves it unset: the ip is
+     * then `null`.
+     */
+    readonly clientAddress?: 'vouched';
+}
+export interface ContractApp {
+    /** `exec` keeps a failure's report to Operations alive past the response (a Worker's `waitUntil`). */
+    fetch(request: Request, exec?: RequestExecutionContext): Promise<Response>;
+    /** The contract's `c.cron` jobs; `fabrika job run <name>` runs one. */
+    readonly jobs: ContractJobs;
+    /** Aborts every kicked run in flight; a later kick starts none; the schedule recovers their work. */
+    stopKicks(): void;
+}
+/** Everything that stops a contract application from starting, with where it is and what to do. */
+export declare class BootError extends Error {
+    readonly name = "BootError";
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+export declare function boot(app: ContractImplementation, options: BootOptions): ContractApp;

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

@@ -0,0 +1,22 @@
+/**
+ * How long a request handler runs before its `ctx.signal` aborts and its transaction cannot commit. It equals
+ * `Bun.serve`'s default `idleTimeout`, which already closes a connection the server sends nothing on for that long, so
+ * both runtimes stop a handler at the same point.
+ */
+export declare const REQUEST_BUDGET_MS = 10000;
+/** A handler's `ctx.signal`: aborted when the client leaves (`request.signal`) or once `budgetMs` passed. */
+export declare function handlerSignal(request: Request, budgetMs?: number): AbortSignal;
+export interface BoundedRead {
+    readonly maxBytes: number;
+    /** `Content-Length`, when the sender declared one: a larger value is refused before anything is read. */
+    readonly declaredLength?: string | null;
+    /** Aborting it cancels the stream; the read then rejects. */
+    readonly signal?: AbortSignal;
+}
+/** The body's bytes, or `null` when it is larger than `maxBytes`. Rejects when `signal` aborts the read. */
+export declare function readBoundedBytes(stream: ReadableStream<Uint8Array> | null, options: BoundedRead): Promise<Uint8Array<ArrayBuffer> | null>;
+/** `body` passed on as it streams, failed once more than `maxBytes` went through; `exceeded` tells that failure apart. */
+export declare function boundedStream(body: ReadableStream<Uint8Array>, maxBytes: number): {
+    readonly stream: ReadableStream<Uint8Array>;
+    exceeded(): boolean;
+};

package/types/src/implement/browser-config.d.ts

@@ -0,0 +1,19 @@
+import type { ContractArtifact } from '@fabrika/auth-core';
+import type { CapturedEnvironment } from './environment';
+export interface BrowserConfig {
+    /** The Operations ingest DSN (a public key), or `null` without one. */
+    readonly dsn: string | null;
+    readonly release: string | null;
+    /** `FABRIKA_ENVIRONMENT`, which the page's error reports carry, or `null` when unset. */
+    readonly environment: string | null;
+    /**
+     * Every public procedure challenge's site key, and the variables the mount lists in `public`, by variable name. Absent when
+     * there is none, so the file of an application without them holds the three Operations values only.
+     */
+    readonly public?: Readonly<Record<string, string>>;
+}
+/**
+ * The browser config of each SPA mount, by mount name: the Operations settings, and the public variables the contract
+ * names. A named variable that is not set is a boot problem.
+ */
+export declare function browserConfigs(artifact: ContractArtifact, environment: CapturedEnvironment, operations: Pick<BrowserConfig, 'dsn' | 'release'>, problems: string[]): ReadonlyMap<string, BrowserConfig>;

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

@@ -0,0 +1,140 @@
+import { type AppCapability as AppCapabilityType, type CapabilityAuthority, type ContainerGrant, type LeaseFence, type Ref as RefCapability, type RowGrant, type RowRef as RowRefCapability, type Within as WithinCapability } from '@fabrika/db/capability';
+/** Why a capability or a handle was refused, as a closed catalog with the fixed text a log may print. */
+export declare const CAPABILITY_REFUSALS: {
+    readonly not_minted: "a value the framework did not mint was used as a capability; pass the ctx.target or ctx.within of this request";
+    readonly ended: "a capability or handle was used after its request, invocation or attempt ended";
+    readonly foreign_work: "a capability or handle was used from other work than the request it belongs to";
+    readonly wrong_target: "an IAM request was not passed this request's ctx.target";
+    readonly undeclared_action: "the job's declaration or its token does not carry the action";
+    readonly undeclared_dimension: "the job named a dimension the contract does not declare";
+    readonly undeclared_kick: "the site kicked a job it does not declare in kicks";
+    readonly undeclared_binding: "the site named a webhook it does not declare in binds";
+    readonly undeclared_signs: "the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows";
+    readonly undeclared_egress: "the site called an origin it does not declare in egress";
+    readonly wrong_binding: "a webhook binding was handed a capability of another kind or dimension than the webhook is bound to";
+    readonly missing_id: "the job named an object without an id";
+    readonly wrong_capability: "an operation was handed a capability of another dimension or action than it needs";
+};
+export type CapabilityRefusal = keyof typeof CAPABILITY_REFUSALS;
+/** A capability that is forged, from a request that has ended, or from another request than the current one. */
+export declare class CapabilityRefusedError extends Error {
+    readonly name = "CapabilityRefusedError";
+    /** What a log may say; the message is for the author's own run. */
+    readonly reason: CapabilityRefusal;
+    constructor(reason: CapabilityRefusal, message: string);
+}
+/** A `Within` that would carry more scope values than one statement may bind; the caller is refused, not truncated. */
+export declare class CapabilityLimitError extends Error {
+    readonly name = "CapabilityLimitError";
+}
+/**
+ * One request's lifetime, or one job attempt's. A capability minted in it is usable only while it runs, and only
+ * inside it; a job attempt's writes also need its lease (`fence`).
+ */
+export declare class RequestFrame {
+    #private;
+    readonly id: string;
+    readonly fence: LeaseFence | null;
+    /** An export's request: the data layer runs its every statement `READ ONLY` and refuses every write. */
+    readonly readOnly: boolean;
+    /** The endpoint the request is served by; `ctx.connect` checks it against each import's `usedBy`. */
+    readonly endpoint: string | null;
+    constructor(id: string, options?: {
+        readonly fence?: LeaseFence | null;
+        readonly readOnly?: boolean;
+        readonly endpoint?: string | null;
+    });
+    get ended(): boolean;
+    end(): void;
+}
+/** Run `work` as the request `frame`: every capability check inside it compares against this frame. */
+export declare function runInRequest<T>(frame: RequestFrame, work: () => Promise<T>): Promise<T>;
+/** Whether `frame` is the request running now. */
+export declare function isActiveRequest(frame: RequestFrame): boolean;
+/** Whether the request running now may only read; `@fabrika/db` asks it before every statement. */
+export declare function requestIsReadOnly(): boolean;
+/** The module-private token that makes a `Ref` or a `Within` constructible by the framework only. */
+declare const MINT: unique symbol;
+/** One authorized object for one action, in one request. `chain` holds the containers the object lies in. */
+export declare class Ref<D extends string, A extends string> implements RefCapability<D, A> {
+    #private;
+    readonly '~capability': {
+        readonly kind: 'ref';
+        readonly dimension: D;
+        readonly action: A;
+    };
+    constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>);
+    get dimension(): D;
+    get action(): A;
+    /** The object's id: the value of its dimension. */
+    get value(): string;
+    /** The containers of the object, by dimension (`workspace → w1` for a note); a copy. */
+    get chain(): ReadonlyMap<string, string>;
+}
+/**
+ * The values of one dimension in which the caller holds one action, in one request; `all` for a global grant. The
+ * containers whose grants also authorise it stay separate, so the data layer matches them against each row's chain.
+ */
+export declare class Within<D extends string, A extends string> implements WithinCapability<D, A> {
+    #private;
+    readonly '~capability': {
+        readonly kind: 'within';
+        readonly dimension: D;
+        readonly action: A;
+    };
+    constructor(token: typeof MINT, issuer: object, frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers: readonly ContainerGrant[]);
+    get dimension(): D;
+    get action(): A;
+    /** The values of this dimension itself. */
+    get values(): readonly string[] | 'all';
+    /** The containers in which the caller also holds the action: `organization → [o1]` for a workspace list. */
+    get containers(): readonly ContainerGrant[];
+}
+/**
+ * One action held as a global grant, in one request: what an `app` endpoint's `ctx.db.app` is built from. The proxy
+ * admitted the request only for a caller who holds the action without a scope.
+ */
+export declare class AppCapability<A extends string> implements AppCapabilityType<A> {
+    #private;
+    readonly '~capability': {
+        readonly kind: 'app';
+        readonly action: A;
+    };
+    constructor(token: typeof MINT, issuer: object, frame: RequestFrame, action: A, principal: string);
+    get action(): A;
+}
+/**
+ * One row a claim leased, for one action, in one job attempt: `row.ref`, which `tx.db.on(row.ref)` finishes the row
+ * through. `chain` holds the row's containment columns as it was claimed.
+ */
+export declare class RowRef<T extends string, A extends string> implements RowRefCapability<T, A> {
+    #private;
+    readonly '~capability': {
+        readonly kind: 'row';
+        readonly table: T;
+        readonly action: A;
+    };
+    constructor(token: typeof MINT, issuer: object, frame: RequestFrame, grant: Omit<RowGrant, 'kind'>);
+    get table(): string;
+    get action(): string;
+    /** The row's key. */
+    get value(): string;
+}
+/** Makes the capabilities one authority accepts; a runtime's is held by the `boot` call that made it alone. */
+export interface CapabilityMint {
+    ref<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, id: string, chain: ReadonlyMap<string, string>): Ref<D, A>;
+    within<D extends string, A extends string>(frame: RequestFrame, dimension: D, action: A, principal: string, values: readonly string[] | 'all', containers?: readonly ContainerGrant[]): Within<D, A>;
+    app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>;
+}
+/** A mint and the one authority that accepts what it mints. */
+export interface CapabilityIssuer {
+    readonly mint: CapabilityMint;
+    readonly authority: CapabilityAuthority;
+}
+/**
+ * A new issuer: its authority refuses every capability another issuer minted. Every `boot` makes one and binds its
+ * data layer and its deps to the authority; a test that needs a capability no access check gave makes another, whose
+ * capabilities reach only stores bound to that issuer's authority.
+ */
+export declare function createCapabilityIssuer(): CapabilityIssuer;
+export {};