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

package/types/src/contract/token.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod/v4';
+import type { InputSchema, NotLoose, Schema } from './define';
+declare const SIGNED_TOKEN: unique symbol;
+/** The longest token a field admits: a purpose's claims, a key id, an expiry and a signature, URL-safe. */
+export declare const SIGNED_TOKEN_MAX_LENGTH = 4096;
+/** The most days any purpose may declare: a key stays verifying that long after it stopped signing. */
+export declare const TOKEN_MAX_DAYS = 3650;
+/** One token purpose: the claims a token of it carries and the longest lifetime a site may sign one for. */
+export interface TokenPurpose<C extends Schema = Schema> {
+    readonly '~kind': 'token';
+    readonly claims: C;
+    readonly maxDays: number;
+}
+export type TokenPurposes = {
+    readonly [purpose: string]: TokenPurpose;
+};
+export interface TokenOptions {
+    /** The longest lifetime, in days, of a token of this purpose. */
+    readonly maxDays: number;
+}
+/**
+ * A token purpose: `token(Recipient, { maxDays: 400 })` under `defineApp(vocabulary, tables, { tokens })`. `Claims` is a
+ * strict object; `compileContract` and the checker refuse what a token may not carry.
+ */
+export declare function token<C extends InputSchema>(claims: C & NotLoose<C>, options: TokenOptions): TokenPurpose<C>;
+/** What `signedToken()` adds to its schema: the purpose a token of the field must be signed for. */
+export interface SignedTokenMark {
+    readonly purpose: string;
+}
+type TokenBrand<P extends string> = `fabrika.token:${P}`;
+/** A field that carries a signed token of purpose `P`: a string on the wire, the purpose's claims in the handler. */
+export type SignedTokenSchema<P extends string> = (PropertyKey extends TokenBrand<P> ? z.ZodString : z.core.$ZodBranded<z.ZodString, TokenBrand<P>>) & {
+    readonly [SIGNED_TOKEN]: SignedTokenMark;
+};
+/**
+ * A field of a procedure's input or `http.query` that carries a token of `purpose`, verified as the input is parsed:
+ * `z.strictObject({ t: signedToken('unsubscribe') })`. Only a top-level field; the handler receives the claims.
+ */
+export declare function signedToken<const P extends string>(purpose: P): SignedTokenSchema<P>;
+/** The mark of a `signedToken()` schema, or `null` for any other schema. */
+export declare function signedTokenOf(schema: Schema): SignedTokenMark | null;
+/** The purpose a field's parsed value names when the field is a signed token; `never` for any other field. */
+export type TokenPurposeOf<V> = V extends {
+    readonly [z.core.$brand]: infer B;
+} ? keyof B extends TokenBrand<infer P> ? P : never : never;
+/** One field as the handler holds it: a signed token as the claims of its purpose, any other field as it is. */
+type ClaimsField<V, T> = [TokenPurposeOf<NonNullable<V>>] extends [never] ? V : (TokenPurposeOf<NonNullable<V>> extends keyof T ? T[TokenPurposeOf<NonNullable<V>>] extends TokenPurpose<infer C> ? z.output<C> : never : never) | (undefined extends V ? undefined : never);
+/** An input as its handler receives it: each signed token field replaced by the verified claims of its purpose. */
+export type WithClaims<In, T> = [keyof In] extends [never] ? In : {
+    readonly [F in keyof In]: ClaimsField<In[F], T>;
+};
+/** `ctx.tokens` of a site that declares `signs`: a token of one of those purposes, valid for `days`. */
+export interface TokenSigning<T extends TokenPurposes, S extends string> {
+    sign<const P extends S & keyof T & string>(purpose: P, claims: z.input<T[P]['claims']>, options: {
+        readonly days: number;
+    }): string;
+}
+export {};

package/types/src/contract/vocabulary.d.ts

@@ -0,0 +1,30 @@
+import { type AppMembers, type DimensionDef, type Presentation, type RoleDefs, type Vocabulary, type WildcardMessage } from './define';
+/**
+ * The vocabulary as `defineVocabulary` returned it, with its literal names, dimension definitions and the actions of its
+ * people (`M`, `never` when it declares none).
+ */
+export interface AppVocabulary<A extends string, D extends string, R extends string, Dims, M extends AppMembers<A> = never> extends Vocabulary<A, D, R> {
+    readonly dimensions: Dims & {
+        readonly [K in D]: DimensionDef<A, D, R>;
+    };
+    readonly members?: M;
+}
+export type AnyAppVocabulary = AppVocabulary<string, string, string, unknown, AppMembers<string>>;
+/**
+ * Declares the dimensions, actions and roles, and how IAM names the application (`locale`, `displayName`). `src/vocabulary.ts` exports it; `defineTables`, `defineApp` and the
+ * contract take it, so each name is written once.
+ */
+export declare function defineVocabulary<const A extends string, const D extends string, const R extends string, const Dims extends {
+    readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>>;
+}, const M extends AppMembers<NoInfer<A>> = never>(vocabulary: Presentation & {
+    readonly app: string;
+    readonly dimensions: Dims & {
+        readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>>;
+    };
+    readonly actions: {
+        readonly [K in A]: K extends `${string}*${string}` ? WildcardMessage : string;
+    };
+    readonly roles: RoleDefs<NoInfer<A>, NoInfer<D>, R>;
+    readonly members?: M;
+    readonly directory?: 'labels';
+}): AppVocabulary<A, D, R, Dims, M>;

package/types/src/contract/webhook-binding.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod/v4';
+import type { AppCapability, Ref } from '../implement/capability';
+/** The output of a procedure that binds: the binding's id, the URL the provider posts to, and the secret, once. */
+export declare const WebhookSecret: z.ZodObject<{
+    id: z.ZodUUID;
+    url: z.ZodString;
+    secret: z.ZodString;
+}, z.core.$strict>;
+export type WebhookSecret = z.output<typeof WebhookSecret>;
+/**
+ * The bindings of one webhook. A binding reaches the value the capability names: a `Ref` of the webhook's dimension, or
+ * an `AppCapability` for a webhook bound to `'app'`. Both run in the procedure's transaction.
+ */
+export interface WebhookBindings {
+    /** A new binding that accepts deliveries for `account`; the framework generates its secret. */
+    bind(capability: Ref<string, string> | AppCapability<string>, account: string): Promise<WebhookSecret>;
+    /**
+     * Replaces the secret of the binding `id` of that value with one the provider issued (Stripe, Slack, Twilio): the
+     * provider shows it only after the binding's URL is registered. `false` when the value has no binding of that id.
+     */
+    setSecret(capability: Ref<string, string> | AppCapability<string>, id: string, secret: string): Promise<boolean>;
+    /** Removes the binding `id` of that value; `false` when it has none of that id. */
+    unbind(capability: Ref<string, string> | AppCapability<string>, id: string): Promise<boolean>;
+}

package/types/src/contract/webhook-scheme.d.ts

@@ -0,0 +1,23 @@
+import { type WebhookScheme } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+export declare const hmacSchemeSchema: z.ZodObject<{
+    header: z.ZodString;
+    algorithm: z.ZodEnum<{
+        sha1: "sha1";
+        sha256: "sha256";
+        sha512: "sha512";
+    }>;
+    encoding: z.ZodEnum<{
+        base64: "base64";
+        hex: "hex";
+    }>;
+    prefix: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodString>;
+    signed: z.ZodEnum<{
+        body: "body";
+        "timestamp.body": "timestamp.body";
+    }>;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const webhookSchemeSchema: z.ZodType<WebhookScheme>;
+export declare const WEBHOOK_SCHEME_ALLOWED = "scheme: 'github-sha256' | 'slack' | 'standard-webhooks' | 'stripe' | 'twilio' | { hmac: { header, algorithm: 'sha1' | 'sha256' | 'sha512', encoding: 'hex' | 'base64', prefix?, timestamp?, signed: 'body' | 'timestamp.body', id? } } | { basic: true } | { bearer: true }";

package/types/src/dev/changes.d.ts

@@ -0,0 +1,7 @@
+/** The application's migrations, as `fabrika db migrate` reads them. */
+export declare const MIGRATIONS_DIRECTORY = "db/migrations/";
+/** Why the change needs a bootstrap run, in one line, or null when the launcher may apply it. */
+export declare function bootstrapReason(paths: readonly string[]): string | null;
+export declare const migrationsChanged: (paths: readonly string[]) => boolean;
+/** A change outside the server code and the database may reach the SPA, so its build runs again. */
+export declare const webSourceChanged: (paths: readonly string[]) => boolean;

package/types/src/dev/contract-digest.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js';
+export { type DevLauncher, type DevLauncherOptions, type DevSourceTransport, readDevLauncherConfig, runDevLauncher, startDevLauncher, } from './launcher.js';

package/types/src/dev/launcher.d.ts

@@ -0,0 +1,32 @@
+import { type DevLauncherConfig } from '@fabrika/auth-core';
+import { type OutputSink } from './output.js';
+/** The launcher's configuration, which the build generated; a missing or malformed file stops the launch. */
+export declare function readDevLauncherConfig(root: string): Promise<DevLauncherConfig>;
+export interface DevSourceTransport {
+    readonly url: string;
+    readonly key: string;
+}
+export interface DevLauncherOptions {
+    readonly root: string;
+    readonly config: DevLauncherConfig;
+    /** The launcher's own environment: the application's, with the provisioning credential and the `source` key. */
+    readonly environment: Readonly<Record<string, string>>;
+    readonly source: DevSourceTransport;
+    readonly fetch?: (request: Request) => Promise<Response>;
+    readonly output?: OutputSink;
+    /** How long a boot tries to reach Control before it serves the files it holds. */
+    readonly bootReconcileMs?: number;
+}
+export interface DevLauncher {
+    /** Settles once the first boot served, or failed and reported it. */
+    readonly ready: Promise<void>;
+    /** Stop the long poll and the application. */
+    stop(): Promise<void>;
+}
+/** Start the launcher: reconcile to the recorded head, serve, then follow Control's long poll. */
+export declare function startDevLauncher(options: DevLauncherOptions): DevLauncher;
+/**
+ * The generated dev entrypoint's only call. It reads the build's configuration and the `source` transport, makes
+ * itself non-dumpable (it holds the provisioning credential and the key), and runs until a signal stops it.
+ */
+export declare function runDevLauncher(env: Readonly<Record<string, string | undefined>>): Promise<void>;

package/types/src/dev/output.d.ts

@@ -0,0 +1,22 @@
+import { type DevLogLine } from './wire.js';
+export type OutputStream = DevLogLine['stream'];
+export interface OutputSink {
+    write(stream: OutputStream, line: string): void;
+}
+/** The launcher process's own stdout and stderr. */
+export declare const processOutput: OutputSink;
+/** The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. */
+export declare class OutputRing {
+    private readonly capacity;
+    private readonly secrets;
+    private readonly sink;
+    private readonly lines;
+    private next;
+    constructor(capacity: number, secrets: readonly string[], sink: OutputSink);
+    push(stream: OutputStream, text: string): void;
+    /** The newest `count` lines, oldest first. */
+    tail(count: number): DevLogLine[];
+    private redact;
+}
+/** Feed `stream` to `onLine` one line at a time; a last line without a newline is fed when the stream ends. */
+export declare function readLines(stream: ReadableStream<Uint8Array>, onLine: (line: string) => void): Promise<void>;

package/types/src/dev/wire.d.ts

@@ -0,0 +1,126 @@
+import { z } from 'zod/v4';
+/** The long poll under the receiver's URL (`FABRIKA_PLATFORM_SOURCE_URL`). */
+export declare const DEV_SOURCE_WAIT_PATH = "/platform/source/wait";
+/** Where the launcher reports what it serves. */
+export declare const DEV_SOURCE_REPORT_PATH = "/platform/source/report";
+/** How long Control holds a wait before it answers `idle`: below every proxy's idle timeout on the way. */
+export declare const DEV_SOURCE_WAIT_MS = 25000;
+/** The most log lines one report carries, and the longest line. */
+export declare const DEV_REPORT_MAX_LINES = 200;
+export declare const DEV_REPORT_MAX_LINE_CHARACTERS = 2000;
+export declare const DEV_REPORT_MAX_MESSAGE_CHARACTERS = 500;
+/**
+ * Repository-relative with forward slashes: no leading slash, no backslash, no empty, `.` or `..` segment, no control
+ * character. The launcher writes these paths under its root, so nothing it receives may name a path outside it.
+ */
+export declare function isSourcePath(path: string): boolean;
+export declare const devWaitRequestSchema: z.ZodObject<{
+    bootstrap: z.ZodString;
+    head: z.ZodString;
+    reset: z.ZodNullable<z.ZodNumber>;
+    checks: z.ZodNullable<z.ZodNumber>;
+    hold: z.ZodBoolean;
+}, z.core.$strict>;
+export type DevWaitRequest = z.infer<typeof devWaitRequestSchema>;
+/** One changed file at the target commit; `content` null deletes it. */
+export declare const devSourceFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type DevSourceFile = z.infer<typeof devSourceFileSchema>;
+/** The files that bring the container from `from` to `to`. */
+export declare const devSyncSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type DevSync = z.infer<typeof devSyncSchema>;
+/**
+ * What to do. `sync` is null when the container holds the recorded head (or a head it refused). `reset` and `checks` are
+ * the environment's current generations: one past what the container applied asks it to reset its schema, or to run
+ * the check chain.
+ */
+export declare const devWaitAnswerSchema: z.ZodObject<{
+    sync: z.ZodNullable<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            content: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    reset: z.ZodNumber;
+    checks: z.ZodNumber;
+}, z.core.$strict>;
+export type DevWaitAnswer = z.infer<typeof devWaitAnswerSchema>;
+export declare const DEV_STATUSES: readonly ["syncing", "serving", "failed", "needs_bootstrap", "resetting", "checking"];
+export type DevStatus = (typeof DEV_STATUSES)[number];
+export declare const devLogLineSchema: z.ZodObject<{
+    n: z.ZodNumber;
+    stream: z.ZodEnum<{
+        stdout: "stdout";
+        stderr: "stderr";
+    }>;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type DevLogLine = z.infer<typeof devLogLineSchema>;
+export declare const devCheckResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    ok: z.ZodBoolean;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNumber;
+    output: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type DevCheckResult = z.infer<typeof devCheckResultSchema>;
+export declare const devReportSchema: z.ZodObject<{
+    bootstrap: z.ZodString;
+    head: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        syncing: "syncing";
+        serving: "serving";
+        needs_bootstrap: "needs_bootstrap";
+        resetting: "resetting";
+        checking: "checking";
+    }>;
+    target: z.ZodNullable<z.ZodString>;
+    message: z.ZodNullable<z.ZodString>;
+    log: z.ZodArray<z.ZodObject<{
+        n: z.ZodNumber;
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    reset: z.ZodNullable<z.ZodNumber>;
+    checks: z.ZodNullable<z.ZodObject<{
+        request: z.ZodNumber;
+        head: z.ZodString;
+        results: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            ok: z.ZodBoolean;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+            durationMs: z.ZodNumber;
+            output: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type DevReport = z.infer<typeof devReportSchema>;
+/** The body of a wait as JSON text. */
+export declare function encodeDevWaitRequest(request: DevWaitRequest): string;
+/** The body of a report as JSON text. */
+export declare function encodeDevReport(report: DevReport): string;
+export type DevParse<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+};
+/** The one parser of a wait request; a field this release does not know is refused, never dropped. */
+export declare const parseDevWaitRequest: (json: unknown) => DevParse<DevWaitRequest>;
+export declare const parseDevWaitAnswer: (json: unknown) => DevParse<DevWaitAnswer>;
+export declare const parseDevReport: (json: unknown) => DevParse<DevReport>;

package/types/src/disk-assets.d.ts

@@ -0,0 +1,3 @@
+import type { SpaAssets } from './implement/dispatch.js';
+/** Serves each SPA mount from its build directory under `root`; a path that names no file gets the SPA's `index.html`. */
+export declare function diskAssets(root: string): SpaAssets;

package/types/src/errors.d.ts

@@ -0,0 +1,46 @@
+interface ErrorOptions {
+    readonly issues?: unknown;
+    readonly loginUrl?: string;
+}
+export declare class HttpError extends Error {
+    readonly httpStatus: number;
+    readonly type: string;
+    readonly issues?: unknown;
+    readonly loginUrl?: string;
+    constructor(httpStatus: number, type: string, message: string, options?: ErrorOptions);
+}
+export declare class BadRequestError extends HttpError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class UnauthorizedError extends HttpError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class ForbiddenError extends HttpError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class NotFoundError extends HttpError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class ConflictError extends HttpError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export interface StructuralError {
+    readonly httpStatus: number;
+    readonly type: string;
+    readonly message: string;
+    readonly issues?: unknown;
+    readonly loginUrl?: string;
+}
+/** True when a thrown value carries its own HTTP status and type, i.e. it is meant to reach the caller as-is. */
+export declare function isStructuralError(err: unknown): err is StructuralError;
+/**
+ * Read the structural HTTP-error fields off ANY thrown value. Defaults:
+ * `httpStatus → 500`, `type → 'internal'`, `message → the Error message or 'Internal error'`.
+ */
+export declare function readStructuralError(err: unknown): StructuralError;
+export declare function jsonResponse(body: unknown, status: number): Response;
+/** Map any thrown value to a JSON `Response` per the structural error contract. */
+export declare function toErrorResponse(err: unknown): Response;
+/** The default `onError` handler — a thin wrapper around {@link toErrorResponse}. */
+export declare function defaultOnError(err: unknown, _request?: Request): Response;
+export {};

package/types/src/fetch.d.ts

@@ -0,0 +1,7 @@
+/** Runtime-neutral background-work capability available while handling a request. */
+export interface RequestExecutionContext {
+    waitUntil(promise: Promise<unknown>): void;
+}
+export interface FetchService<Env> {
+    fetch(request: Request, env: Env, exec: RequestExecutionContext): Promise<Response>;
+}

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

@@ -0,0 +1,26 @@
+export declare const ARCHIVE_LIMITS: {
+    /** Entries of one archive, nested ones counted with their parent's. */
+    readonly maxEntries: 1000;
+    /** Uncompressed bytes of one archive and everything nested in it. */
+    readonly maxUnpackedBytes: number;
+    /** The outer archive is depth 0; an archive inside it is 1; one inside that is refused. */
+    readonly maxDepth: 1;
+};
+/** Why an archive is refused. Each is a reject, never a retry: the bytes will not change. */
+export type ArchiveRefusal = 'encrypted' | 'unsupported_method' | 'zip64' | 'malformed' | 'too_many_entries' | 'too_large_unpacked' | 'nested_too_deep' | 'unsupported_archive'
+/** A ZIP signature inside a file that is no ZIP, or before a ZIP's first entry. */
+ | 'embedded_archive'
+/** More than one end record a scanner could pick, or one whose comment does not end the file. */
+ | 'ambiguous_directory';
+export type ArchiveCheck = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly refusal: ArchiveRefusal;
+};
+/**
+ * Whether the scanner can vouch for these bytes. A file of a ZIP-based type (`zipBased`: ZIP and Office Open XML) must
+ * be a ZIP from its first byte whose every entry, nested ZIPs included, ClamAV reads in full. Any other file passes
+ * only when it holds no archive: no other archive format, and no ZIP signature at any offset.
+ */
+export declare function checkArchive(bytes: Uint8Array, zipBased: boolean): ArchiveCheck;

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

@@ -0,0 +1,32 @@
+import { type FileScanner, type ScanBatchResult } from './scan';
+export declare const CLAMSCAN_LIMITS: {
+    /** The scanner refuses signatures older than this; the provider refreshes them at start and daily. */
+    readonly maxSignatureAgeDays: 3;
+    /** One file's scan time, after which ClamAV alerts instead of passing it. */
+    readonly maxScanTimeMs: 120000;
+    readonly maxRecursion: 10;
+    readonly maxFilesPerContainer: 1000;
+    /** What clamscan may print; past it the run is stopped and the batch gets no verdict. */
+    readonly maxOutputBytes: number;
+};
+export interface ClamscanOptions {
+    /** The `clamscan` binary; by default the one on `PATH`. */
+    readonly binary?: string;
+    /** The signature directory; by default ClamAV's configured one. */
+    readonly database?: string;
+    /** Where the batch's directory is made; by default the system's temporary directory. */
+    readonly directory?: string;
+    readonly timeoutMs?: number;
+    /** The largest file ClamAV reads in full; a larger one alerts. By default `FILE_LIMITS.maxScannedBytes`. */
+    readonly maxFileBytes?: number;
+}
+/** The arguments of one run; every limit alerts, so a file ClamAV could not read in full is never reported OK. */
+export declare function clamscanArguments(database: string | undefined, size?: number): readonly string[];
+/**
+ * The verdicts of one finished run. Exit 0 (nothing found) and 1 (something found) carry per-file lines; any other exit
+ * is a failed batch, classified from stderr. A file without exactly one `<path>: OK` or `<path>: <name> FOUND` line,
+ * a conflicting second line included, gets no clean verdict.
+ */
+export declare function clamscanVerdicts(paths: ReadonlyMap<string, string>, exitCode: number, stdout: string, stderr: string): ScanBatchResult;
+/** ClamAV's `clamscan` as the scan pass's scanner. Fails closed: see `ScanFailure` for what makes a batch fail. */
+export declare function clamscanScanner(options?: ClamscanOptions): FileScanner;

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

@@ -0,0 +1,106 @@
+import type { Unavailable } from '@fabrika/db/tables';
+import type { FileRef } from '../contract/file';
+import type { Ref } from '../implement/capability';
+/** A held file's state: served when `live`, `409` while `quarantined`, gone when `rejected`. */
+export type HeldFileStatus = 'live' | 'quarantined' | 'rejected';
+/** One file of an owner, as `list` answers it. */
+export interface ListedFile {
+    readonly id: string;
+    /** The name the uploader gave it, metadata only. */
+    readonly name: string | null;
+    /** The sniffed media type its bytes were checked against. */
+    readonly type: string;
+    readonly size: number;
+    readonly status: HeldFileStatus;
+    readonly createdAt: Date;
+}
+/** A page of an owner's files, oldest first; `next` is the `after` of the following page, `null` after the last. */
+export interface FileListing {
+    readonly items: readonly ListedFile[];
+    readonly next: string | null;
+}
+export interface FileListPage {
+    /** The id of the last file of the previous page. */
+    readonly after?: string;
+    /** 1–100, 50 by default. */
+    readonly limit?: number;
+}
+/** A live file read whole: what an e-mail attaches. */
+export interface OpenedFile {
+    readonly id: string;
+    readonly name: string | null;
+    readonly type: string;
+    readonly size: number;
+    readonly bytes: Uint8Array;
+}
+export interface OpenOptions {
+    /** The most bytes the caller holds in memory; a larger file is refused (413 `too_large`) before it is read. */
+    readonly maxBytes: number;
+}
+/** What every site reaches of one collection: its owner's files. */
+export interface FileCollectionReader {
+    /**
+     * The owner's held files, oldest first; `owner` is a `Ref` of the collection's owner for its `read` action. A
+     * handler that must see the uploads holds that action.
+     */
+    list(owner: Ref<string, string>, page?: FileListPage): Promise<FileListing>;
+    /**
+     * The live file `id` of the owner, read whole; `owner` is a `Ref` for the collection's `read` action. A file of
+     * another owner, a rejected or a removed one is 404, a quarantined one 409 `quarantined`, one over `maxBytes` 413.
+     */
+    open(owner: Ref<string, string>, id: string, options: OpenOptions): Promise<OpenedFile>;
+}
+/** A site that writes also removes: a mutation, and a job inside `ctx.transaction`. */
+export interface FileCollectionWriter extends FileCollectionReader {
+    /**
+     * Marks every file of the owner removed, in this site's transaction, and answers how many; `owner` is a `Ref` for the
+     * collection's `delete` action. The framework's sweep deletes their objects after the commit.
+     */
+    removeAll(owner: Ref<string, string>): Promise<number>;
+}
+/** A mutation's handle: it writes, and attaches nothing, since only the job that drains a form's inbox does. */
+export type FileCollectionHandle = FileCollectionWriter & {
+    readonly attach: Unavailable<"only a job attaches a form's file, inside ctx.transaction((tx) => …), as tx.files">;
+};
+/** A job's transaction also attaches the files a form received: the job that drains the form's inbox. */
+export interface FileCollectionJobHandle extends FileCollectionWriter {
+    /**
+     * Attaches the file a form received under `id` (the id its inbox column holds) to `owner`, a `Ref` for the
+     * collection's `write` action, in this site's transaction: the one that wrote the owner, located with `tx.ref`. A
+     * scanning collection holds it `quarantined` until the scan job's verdict. `false` when no file of this collection
+     * waits under the id (none was sent, or its hold of 7 days ended); `true` again for one this owner attached before.
+     */
+    attach(owner: Ref<string, string>, id: string): Promise<boolean>;
+}
+/** A site that only reads: a query, and a job outside `ctx.transaction`. */
+export type FileCollectionReadHandle<Why extends string> = FileCollectionReader & {
+    readonly removeAll: Unavailable<Why>;
+    readonly attach: Unavailable<Why>;
+};
+/** `ctx.files(<collection>)`: the handle of one collection of the contract, by its name in `files`. */
+export type FileCollections<H> = (collection: string) => H;
+/** What `ctx.files.put` writes: bytes in memory, a `Blob`, or a stream a large file comes from. */
+export type StoredFileBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
+/**
+ * `ctx.files.put` and `ctx.files.open`: the stored files of a site (`c.files` kinds). A put stages a file this request
+ * holds; writing its reference into a file column is what keeps it. `open` reads a live file whose reference this
+ * request holds and may read: an input file, a put, or a file column read under its table's read action.
+ */
+export interface StoredFilesHandle {
+    /** A file of `kind` with these bytes, which must be of `type`; it is pending until a column references it. */
+    put(kind: string, body: StoredFileBody, options: {
+        readonly type: string;
+        readonly name?: string;
+    }): Promise<FileRef>;
+    /** The bytes of a live file, read whole, at most `maxBytes` (the kind's by default); 409 until it is live. */
+    open(file: FileRef, options?: {
+        readonly maxBytes?: number;
+    }): Promise<OpenedFile>;
+}
+/** A site that only reads (a query): it opens a file and creates none. */
+export interface StoredFilesReadHandle {
+    readonly put: Unavailable<'a query creates no file; put it in a mutation, a job or a webhook'>;
+    open(file: FileRef, options?: {
+        readonly maxBytes?: number;
+    }): Promise<OpenedFile>;
+}