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

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

@@ -0,0 +1,120 @@
+import { type ContractArtifact, type JobMailer } from '@fabrika/auth-core';
+import { type DataAccess, type DataHandles, type FileBinding, type Session, type SqlTag } from '@fabrika/db/framework';
+import type { DataKind, UnscopedMode } from '@fabrika/db/tables';
+import type { SqlMode } from '../contract/context';
+import { type RequestFrame } from './capability';
+/** A site's declared off-road reach, parsed at `boot`: what its handler's `ctx` gets beyond the paved road. */
+export interface SiteDeclaration {
+    readonly sql: SqlMode | null;
+    readonly unscoped: Readonly<Record<string, UnscopedMode>>;
+    readonly connect: readonly string[];
+    readonly issues: string | null;
+    readonly mailer: JobMailer | null;
+    /** The cron jobs `ctx.kick` may name. */
+    readonly kicks: readonly string[];
+    /** The webhook whose bindings `ctx.webhooks` creates and removes. */
+    readonly binds: string | null;
+    /** The token purposes `ctx.tokens.sign` may sign. */
+    readonly signs: readonly string[];
+    /** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
+    readonly egress: readonly string[];
+}
+/** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
+export interface PublicReach {
+    readonly carried: ReadonlySet<string>;
+}
+export type SiteFunction = (args: {
+    readonly input?: unknown;
+    readonly ctx: object;
+}) => unknown;
+/**
+ * A handler tree leaf of a staged-kit site, which `serve` builds from each handled endpoint, job and webhook: the
+ * handler and the site's `declared` object. `boot` builds the site's `ctx.db` (and the declared handles) from it.
+ */
+export interface SiteHandler {
+    readonly handler: SiteFunction;
+    readonly declared: unknown;
+}
+/** The leaf `serve` puts in the handler tree for one site. */
+export declare function siteHandler(handler: SiteFunction, declared: unknown): SiteHandler;
+/** Whether a handler tree node is a site leaf, rather than a group of handlers that happens to have the same fields. */
+export declare function isSiteHandler(node: unknown): node is SiteHandler;
+/**
+ * The site's `declared` object, parsed at the boundary: the kit's types already refused what is wrong in it, and this
+ * refuses it again, because a widened or cast declaration would otherwise reach further than its site shows.
+ */
+export declare function parseDeclaration(where: string, declared: unknown, kind: DataKind, artifact: ContractArtifact, problems: string[]): SiteDeclaration;
+/**
+ * The declaration a site runs with: the one the approved contract holds (`ContractArtifact.declared`, which the
+ * contract's digest covers), by the site's endpoint id or `job:<name>`. A leaf whose own `declared` says otherwise is
+ * refused, so a declaration only the handler tree carries never widens a site past what was approved.
+ */
+export declare function approvedDeclaration(where: string, site: string, leaf: unknown, kind: DataKind, artifact: ContractArtifact, problems: string[]): SiteDeclaration;
+/** What the approved artifact declares for `site` (an endpoint id or `job:<name>`); nothing when it holds none. */
+export declare function approvedReach(site: string, artifact: ContractArtifact): SiteDeclaration;
+/**
+ * Refuses a handle used outside the work it was made for: another request, another `boot`, an ended one. `handle` names
+ * it in the refusal: a `ctx.db` handle, or `ctx.sql`.
+ */
+export declare function boundTo(frame: RequestFrame, ended: () => boolean, handle?: string): () => void;
+/** One invocation's transaction, and the data handles of its site. */
+export declare class Invocation {
+    #private;
+    constructor(frame: RequestFrame, data: DataAccess, readOnly: boolean);
+    /**
+     * The handles of the site, all of them running in this invocation's transaction. A public procedure's (`reach` its
+     * carried texts) insert and read under its actions only, and update or remove only a row a verified token names.
+     */
+    handles(kind: DataKind, declaration: SiteDeclaration, principal: string, reach?: PublicReach | 'declared', files?: FileBinding): DataHandles;
+    /** `ctx.sql` of a site that declares it: its statements run in this invocation's transaction, like every handle's. */
+    sql(mode: SqlMode): SqlTag;
+    /** The check of `ctx.files`: bound to this invocation's transaction, like every handle. */
+    fileCheck(): () => void;
+    /** Where the framework writes for this site (a webhook binding): this invocation's transaction, bound like every handle. */
+    frameworkSite(handle: string): {
+        readonly check: () => void;
+        readonly session: () => Promise<Session>;
+    };
+    /** Commits; a request the caller abandoned meanwhile rolls back instead. */
+    commit(signal: AbortSignal | null): Promise<void>;
+    rollback(): Promise<void>;
+}
+/** What a request's access form handed the handler, by `ctx` name. */
+export interface AccessCapabilities {
+    readonly target?: unknown;
+    readonly within?: unknown;
+    readonly created?: unknown;
+    /** An `app` endpoint's capability, `ctx.app`. */
+    readonly app?: unknown;
+}
+/**
+ * `ctx.db` of an endpoint, by its access form: the API matrix of `docs/reference/application-runtime.md`. An endpoint of
+ * several capabilities binds each, as a job binds what it minted: `ctx.db.on(ref)`, `.in(ref)`, `.over(within)`.
+ */
+export declare function endpointData(handles: DataHandles, form: 'on' | 'in' | 'over' | 'creates' | 'app' | 'member' | 'capabilities', access: AccessCapabilities): object;
+/** `ctx.db` of a job or a webhook: each capability it minted or received binds the same handles an endpoint gets. */
+export declare function siteData(handles: DataHandles, app: (action: string) => object): object;
+/**
+ * `ctx.app` and `ctx.db.app` of a webhook bound to a dimension. The types already refuse them; at run time they exist
+ * only to refuse by name.
+ */
+export declare function boundWebhookApp(webhook: string): (action: string) => never;
+/**
+ * The handles of a job attempt, outside its fenced transaction (`'job'`, each read on its own) or inside it. `tickMs`,
+ * the job's schedule period, is a queue claim's first backoff.
+ */
+export declare function jobHandles(frame: RequestFrame, data: DataAccess, declaration: SiteDeclaration, principal: string, kind: 'job' | 'mutation', session: () => Promise<Session>, ended: () => boolean, tickMs?: number, files?: FileBinding): DataHandles;
+/** `ctx.sql` (or `member`, a job's `tx.sql`) of a site that does not declare `sql`. */
+export declare function undeclaredSql(site: string, kind: DataKind, member?: 'ctx.sql' | 'tx.sql'): SqlTag;
+/** `ctx.sql` of a job that declares `sql`, outside `ctx.transaction`: its statements run only in the attempt's fence. */
+export declare function jobSqlOutsideTransaction(job: string): SqlTag;
+/** `tx.sql` of a job site that declares it: its statements run in the attempt's fenced transaction. */
+export declare function jobSql(frame: RequestFrame, data: DataAccess, mode: SqlMode, session: Session, ended: () => boolean): SqlTag;
+/**
+ * `ctx.kick` of one invocation: it names only a declared job, and records it; the dispatcher sends each recorded job once,
+ * after the commit, and nothing on a rollback.
+ */
+export declare function kickRecorder(site: string, declared: readonly string[]): {
+    readonly kick: (job: string) => void;
+    readonly kicked: () => readonly string[];
+};

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

@@ -0,0 +1,201 @@
+import type { IamMembership, MembershipRequestCaller } from '@fabrika/auth';
+import type { EndpointDirectory, InvitationItem, InvitationOptions, MemberItem, PrincipalAffiliation, Scope } from '@fabrika/auth-core';
+import type { CapabilityAuthority } from '@fabrika/db/capability';
+import { type Ref } from './capability';
+/** Who a membership is about: an address IAM invites, or a principal it already has. */
+export type MemberTarget = {
+    readonly email: string;
+} | {
+    readonly principalId: string;
+};
+export type AssignedMember = {
+    readonly assigned: {
+        readonly principalId: string;
+        readonly role: string;
+    };
+} | {
+    readonly invited: {
+        readonly invitationId: string;
+        readonly role: string;
+        readonly expiresAt: number;
+    };
+};
+export interface MemberList {
+    readonly members: readonly MemberItem[];
+    readonly invitations: readonly InvitationItem[];
+}
+/** `ctx.members` of an endpoint whose action is its dimension's `members.manage`: one write per request. */
+export interface MemberManagement<D extends string, A extends string, R extends string> {
+    /** The members of the value; IAM requires the dimension's `members.list` there. */
+    list(ref: Ref<D, A>): Promise<MemberList>;
+    /**
+     * Gives `role` in the value: an existing principal gets the grant, an address an invitation. Repeating it answers the
+     * same and sends nothing. For an address, `options` names the company (`label`, at most 200 characters on one line)
+     * and a personal `message` (at most 1000 characters of plain text) the e-mail carries, and `resend` gives an open
+     * invitation a new link and a new 7 days and sends it again; the old link stops working.
+     */
+    assign(ref: Ref<D, A>, member: MemberTarget, role: R, options?: InvitationOptions): Promise<AssignedMember>;
+    /** Removes the member's roles there (only `role` when given), or cancels an invitation. Repeating it answers the same. */
+    revoke(ref: Ref<D, A>, member: {
+        readonly principalId: string;
+        readonly role?: R;
+    } | {
+        readonly invitationId: string;
+    }): Promise<void>;
+}
+/** One member of the target, as a member directory lists it. */
+export interface DirectoryMember<L extends string | null = string | null> {
+    readonly principalId: string;
+    /**
+     * The principal's display label (a user's spelling of its address): `string` where the directory's dimension declares
+     * `directory: 'labels'`, since IAM then answers it to every caller; elsewhere null unless the caller manages its members.
+     */
+    readonly label: L;
+    /** Its membership roles in the target. */
+    readonly roles: readonly string[];
+    readonly disabled: boolean;
+    /** `external`: a person from outside the organization (ADR-0051), for a staff UI to show. */
+    readonly affiliation: PrincipalAffiliation;
+}
+/** One member a lookup found: never its email, and its label only where the directory shows labels. */
+export interface Member<L extends string | null = string | null> {
+    readonly principalId: string;
+    /** The principal's display label, as `DirectoryMember.label`. */
+    readonly label: L;
+    readonly disabled: boolean;
+    readonly affiliation: PrincipalAffiliation;
+}
+/**
+ * `ctx.members` of an endpoint on or in a dimension below a member directory (its own dimension's, or the nearest one
+ * containing it): the members of the value its object lies in. IAM checks the endpoint's own action on that value.
+ */
+export interface MemberLookup<L extends string | null = string | null> {
+    /** The principal, when it is a member of the directory's value; null otherwise, an unknown id included. */
+    get(principalId: string): Promise<Member<L> | null>;
+}
+/**
+ * `ctx.members` of an endpoint whose action is the directory's `members.list`: also every member, read from IAM, which
+ * checks that action live on the directory's value. No emails and no invitations: those stay with `members.manage`.
+ */
+export interface MemberDirectory<L extends string | null = string | null> extends MemberLookup<L> {
+    list(): Promise<readonly DirectoryMember<L>[]>;
+}
+/** One role a person holds at the application: globally (`scope: null`), or in one value. */
+export interface ApplicationMemberRole {
+    readonly role: string;
+    readonly scope: Scope | null;
+}
+/** One of the application's own people, as its directory lists them. */
+export interface ApplicationMember {
+    readonly principalId: string;
+    /** The principal's display label; null unless the vocabulary declares `directory: 'labels'` or the caller manages the people. */
+    readonly label: string | null;
+    /** The person's address; null unless the caller holds the application's `members.manage` globally. */
+    readonly email: string | null;
+    /** Unix seconds of the person's last sign-in to the application; null for one who never did, and as `email`. */
+    readonly lastSignInAt: number | null;
+    /** Every role the person holds at the application, a global one first. */
+    readonly roles: readonly ApplicationMemberRole[];
+    readonly disabled: boolean;
+    readonly affiliation: PrincipalAffiliation;
+}
+export interface ApplicationMemberPage {
+    readonly members: readonly ApplicationMember[];
+    /** The `after` of the following page; null on the last one. */
+    readonly next: string | null;
+}
+/**
+ * `ctx.members` of an `app: true` endpoint whose action is the application's `members.list`: every principal holding a
+ * role of the application, globally or in a value, a page of at most 100 at a time. IAM checks the action live.
+ */
+export interface ApplicationDirectory {
+    list(options?: {
+        readonly after?: string | undefined;
+    }): Promise<ApplicationMemberPage>;
+}
+/**
+ * The application's own directory, read from IAM with the caller's token. A runtime without an IAM membership transport
+ * still boots, and only a call fails.
+ */
+export declare function applicationDirectory(iam: IamMembership | null, caller: MembershipRequestCaller, endpoint: string): ApplicationDirectory;
+export interface IssuedLink {
+    readonly id: string;
+    /** `<prefix>/#<key>`: the key travels in the fragment, which never reaches a server or a `Referer`. */
+    readonly url: string;
+    readonly expiresAt: number;
+}
+/** `ctx.links` of a site that declares the link mount it issues. */
+export interface LinkIssuing<D extends string, A extends string, M extends string> {
+    issue(ref: Ref<D, A>, options: {
+        readonly mount: M;
+        readonly days: number;
+    }): Promise<IssuedLink>;
+    /**
+     * Ends the link `id` (`IssuedLink.id`) at IAM: its issuer or a holder of `members.manage` on its chain may; a job only
+     * a link it issued. Repeating it answers the same. A token minted from it still works until it expires, at most 300 s.
+     */
+    revoke(id: string): Promise<void>;
+}
+/** One request's authority at IAM: the caller's token, the proxy's request id and the delegation grant it obtained. */
+export interface MembershipRequest {
+    readonly iam: IamMembership;
+    readonly caller: MembershipRequestCaller;
+    readonly delegation: string | null;
+    /** The endpoint's own access: the dimension a `Ref` passed to IAM must name, and its action. */
+    readonly dimension: string;
+    readonly action: string;
+    /** The runtime's authority, which the `Ref` passed to IAM must resolve with. */
+    readonly capabilities: CapabilityAuthority;
+}
+/** `creates`: IAM generates the value and grants the caller the dimension's creator role, atomically. */
+export declare function createScope(request: MembershipRequest): Promise<string>;
+export declare function memberManagement(request: MembershipRequest): MemberManagement<string, string, string>;
+/** The directory an endpoint reads (`endpointDirectory`), and whether its dimension declares `directory: 'labels'`. */
+export interface ReadDirectory extends EndpointDirectory {
+    readonly labels: boolean;
+}
+/** The directory an endpoint reads, with the endpoint a fault names. */
+export interface DirectoryReach extends ReadDirectory {
+    readonly endpoint: string;
+}
+/**
+ * The member directory of the request's own target, `target`: its dimension's when it declares members, else the
+ * nearest container's, at the value the target's chain holds. A runtime without an IAM membership transport still
+ * boots, and only a call fails.
+ */
+export declare function memberDirectory(request: MembershipRequest | null, target: unknown, reach: DirectoryReach): MemberLookup | MemberDirectory;
+/** A link mount an endpoint may issue for: its dimension and issuing action are the endpoint's. */
+export interface IssuableLink {
+    readonly name: string;
+    readonly prefix: string;
+}
+/**
+ * `ctx.links`: IAM issues an anonymous key bound to the object's whole containment chain, read from the `Ref`, so a
+ * link whose object moves stops working. `containers` is the object's dimension's containers, nearest first.
+ */
+export declare function linkIssuing(request: MembershipRequest, mounts: readonly IssuableLink[], containers: readonly string[]): LinkIssuing<string, string, string>;
+/** The link mount a cron job declares it `issues`, as the artifact states it. */
+export interface JobLinkMount {
+    readonly name: string;
+    readonly prefix: string;
+    readonly dimension: string;
+    readonly issuedBy: string;
+}
+/** A job's authority at IAM: its link mount, and the token IAM signs from its key now. */
+export interface JobLinkRequest {
+    readonly iam: IamMembership;
+    readonly job: string;
+    readonly mount: JobLinkMount;
+    /** The mount dimension's containers, nearest first. */
+    readonly containers: readonly string[];
+    /** The job's current token and this attempt's id; it throws a 503 when IAM signs none. */
+    caller(): Promise<MembershipRequestCaller>;
+    /** Throws once the attempt has ended. It runs synchronously right before each IAM operation, after every await. */
+    assertLive(): void;
+    readonly capabilities: CapabilityAuthority;
+}
+/**
+ * `ctx.links` of a job that declares `issues`. IAM admits the job's token on `issueLink` and `revokeLink` only while the
+ * approved schema says the job issues this mount, so a job holds no more than its declaration; it revokes only its own.
+ */
+export declare function jobLinkIssuing(request: JobLinkRequest): LinkIssuing<string, string, string>;

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

@@ -0,0 +1,36 @@
+/**
+ * A body that is not the `multipart/form-data` a form reads (`malformed`), or one whose stream failed before its end
+ * (`interrupted`: the client closed the connection). Its message names what is wrong, never a byte of it.
+ */
+export declare class MultipartError extends Error {
+    readonly name = "MultipartError";
+    readonly reason: 'malformed' | 'interrupted';
+    constructor(message: string, reason?: 'malformed' | 'interrupted');
+}
+export interface MultipartPart {
+    /** The `name` of its `Content-Disposition`. */
+    readonly name: string;
+    /** Its `filename`, as sent; `null` when the part has none, which is a plain field. */
+    readonly filename: string | null;
+    /** The media type of its `Content-Type`, lower-cased and without parameters; `null` when it has none. */
+    readonly contentType: string | null;
+    /** Its bytes. Read it to the end, or cancel it, before the next part. */
+    readonly body: ReadableStream<Uint8Array>;
+}
+export interface MultipartReader {
+    /** The next part, or `null` after the closing delimiter. Rejects while the previous part's body is unread. */
+    next(): Promise<MultipartPart | null>;
+    /** Stops reading the body. */
+    cancel(): Promise<void>;
+    /** Why the body broke the format, wherever the break was met (a part's body included); `null` while it did not. */
+    failure(): MultipartError | null;
+}
+/** The boundary of a `multipart/form-data` `Content-Type`, or `null` when it is another type or names none. */
+export declare function multipartBoundary(contentType: string | null): string | null;
+/**
+ * Reads `body` as `multipart/form-data` with `boundary`. A part's headers hold at most `maxHeaderBytes`; its body is
+ * as long as the sender makes it, so the caller bounds what it reads of each.
+ */
+export declare function multipartParts(body: ReadableStream<Uint8Array>, boundary: string, options: {
+    readonly maxHeaderBytes: number;
+}): MultipartReader;

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

@@ -0,0 +1,7 @@
+import type { SchemaShape } from '@fabrika/auth-core';
+/** The longest URL a procedure reads its parameters from. */
+export declare const MAX_URL_LENGTH = 8192;
+/** The parameters of `params` as the object `shape`'s fields read them; `shape` is a flat object, or `null` for none. */
+export declare function paramsObject(params: URLSearchParams, shape: SchemaShape | null): Record<string, unknown>;
+/** The URL's parameters of a request, within `MAX_URL_LENGTH`. */
+export declare function urlParams(request: Request): URLSearchParams;

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

@@ -0,0 +1,52 @@
+import { type AccessTokenClaims, type Caller, type PermissionEntry } from '@fabrika/auth-core';
+import type { PageCaller } from '../client/caller';
+/** A person: the IAM session, or a `px_` key bound to a user principal. */
+export interface UserPrincipal {
+    readonly kind: 'user';
+    readonly id: string;
+    /** What IAM shows for the person: the address as it was spelled. Display it; never mail it. */
+    readonly label: string;
+    /** The mailbox IAM recorded for the person, lower-cased: the one to mail, not proof of possession. Only a person has one. */
+    readonly email: string;
+}
+/** A machine: a `px_` key bound to a service principal. */
+export interface ServicePrincipal {
+    readonly kind: 'service';
+    readonly id: string;
+    readonly label: string;
+}
+/** The anonymous holder of a share link; the id is the link's credential, not a person. */
+export interface LinkHolder {
+    readonly kind: 'link';
+    readonly credentialId: string;
+}
+/** Another application, through its connector key. */
+export interface AppPrincipal<Id extends string = string> {
+    readonly kind: 'app';
+    readonly app: Id;
+    readonly id: string;
+}
+export type Principal = UserPrincipal | ServicePrincipal | LinkHolder | AppPrincipal;
+/** Whoever called a public procedure: nobody the platform knows. The handler runs as the endpoint's own workload. */
+export interface PublicPrincipal {
+    readonly kind: 'public';
+    /** The endpoint id, which is the workload's name: `<mount>.<group>.<procedure>`. */
+    readonly endpoint: string;
+}
+export type PrincipalOf<C> = C extends 'human' ? UserPrincipal : C extends 'machine' ? ServicePrincipal : C extends 'link' ? LinkHolder : C extends `app:${infer Id}` ? AppPrincipal<Id> : never;
+export interface Presented {
+    readonly caller: Caller;
+    readonly principal: Principal;
+}
+/**
+ * Why a verified token presents no principal: it is no caller of an application (`no_caller`), or a person's token
+ * from an IAM that does not mint the mailbox (`no_mailbox`), which a handler could not read.
+ */
+export type Unpresented = 'no_caller' | 'no_mailbox';
+/** The caller a verified application token presents, by `callerOf` (the proxy reads the same), and its principal. */
+export declare function presentedBy(claims: AccessTokenClaims): Presented | Unpresented;
+/**
+ * The caller document of an SPA mount: the person and the contract's actions each of the token's entries covers, a
+ * pattern listed as those actions, global entries apart from each scope value's. Built from the token alone.
+ */
+export declare function pageCallerOf(principal: UserPrincipal, perms: readonly PermissionEntry[], actions: readonly string[]): PageCaller;

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

@@ -0,0 +1,11 @@
+import { z } from 'zod/v4';
+/** No branch of a union accepts the value, whatever it is reduced to. */
+export declare class ProjectionRefusedError extends Error {
+    readonly name = "ProjectionRefusedError";
+}
+/**
+ * `value` with every object reduced to the fields `schema` declares, recursively. A union takes the first branch,
+ * in declaration order, whose schema accepts the value reduced to that branch. Anything else is left for
+ * validation.
+ */
+export declare function project(schema: z.core.$ZodType, value: unknown): unknown;

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

@@ -0,0 +1,61 @@
+import { type AdmissionRate, type ContractArtifact } from '@fabrika/auth-core';
+import { type ChallengeFetch, type ChallengeIssuer, type ChallengeVerifier, type ChallengeWork } from './challenge';
+import type { RequestClient } from './types';
+/** The bucket every call of an endpoint takes from; a client's is `client:<digest>`, a caller's `caller:<digest>`. */
+export declare const ENDPOINT_BUCKET = "endpoint";
+/** The longest `User-Agent` a handler reads: enough to tell browsers apart, too short to carry a payload. */
+export declare const MAX_USER_AGENT_LENGTH = 256;
+/** A procedure's admission and time limit, from the approved artifact. */
+export interface ProcedureAdmission {
+    readonly rate: AdmissionRate;
+    /** The challenge's verifier, with the secret its application variable holds; `null` without a challenge. */
+    readonly challenge: AdmittedChallenge | null;
+    /** The one token the challenge does not record, so it passes again: `fabrika app dev`'s test widget's. */
+    readonly repeatableToken: string | null;
+    /** How long the handler may run after the last body byte. */
+    readonly timeoutMs: number;
+}
+/** A challenge's verifier and the widget action the verification expects back; an ALTCHA one's issuer too. */
+export interface AdmittedChallenge {
+    readonly verifier: ChallengeVerifier;
+    readonly action: string;
+    /** What the procedure's issuing endpoint answers with; `null` for a provider that issues its own (Turnstile). */
+    readonly issuer: ChallengeIssuer | null;
+}
+/** A procedure the artifact holds no rules for (a `defineContract` one): no bucket, the request budget. */
+export declare const DEFAULT_ADMISSION: ProcedureAdmission;
+export interface AdmissionOptions {
+    readonly application: Readonly<Record<string, unknown>>;
+    readonly challengeFetch?: ChallengeFetch;
+    readonly repeatableChallengeToken?: string;
+    /** The work of every ALTCHA challenge in place of the contract's: a test kit's and `fabrika app dev`'s. */
+    readonly challengeWork?: ChallengeWork;
+}
+/**
+ * The admission of endpoint `id`, or `null` after a problem: a challenge whose secret's application variable is not set,
+ * or an ALTCHA key too short to resist a guess, keeps the application from booting, as a form's does.
+ */
+export declare function procedureAdmission(id: string, artifact: ContractArtifact, options: AdmissionOptions, problems: string[]): ProcedureAdmission | null;
+/** The buckets a request takes from, in order: its client's or its caller's first, then the endpoint's. */
+export declare function bucketsOf(rate: AdmissionRate, request: Request, caller: string | null): {
+    readonly bucket: string;
+    readonly limit: number;
+}[];
+/**
+ * Who sent the request, as the proxy saw it. The address is `X-Fabrika-Client-Ip`, which only the proxy sets, and only
+ * where the runtime adapter vouches that the proxy saw the visitor (`vouched`); behind a balancer whose range the
+ * platform does not trust it is `null`. Anything that is no IP address is `null` too.
+ */
+export declare function requestClient(request: Request, vouched: boolean): RequestClient;
+/**
+ * At most `limit` requests at once, beyond which the next is refused: the share of the connection pool all public
+ * procedures of an instance hold together, so a flood of anonymous calls leaves signed-in staff the rest.
+ */
+export declare class InFlightShare {
+    #private;
+    constructor(limit: number);
+    /** A release to call once the request is answered, or `null` when the share is full. */
+    enter(): (() => void) | null;
+}
+/** A quarter of the pool, at least one connection. */
+export declare function publicShareOf(connections: number): number;

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

@@ -0,0 +1,25 @@
+import type { EmailSender } from '@fabrika/email';
+import type { AnyContract } from '../contract/define';
+import { type ApplicationEnvironment, type ContractImplementation, type DepsRuntime, type ImplementationDatabase } from './implement';
+/**
+ * The application's dependencies, built at each `boot` from its own environment. A handler imports the module that
+ * defines them and reads `get()` while it runs: it answers what the boot serving that invocation built. At module load
+ * there is nothing to read yet.
+ */
+export interface AppDeps<D> {
+    get(): D;
+}
+/** Declares how each `boot` builds the dependencies; `serve(contract, { deps })` takes the result. */
+export declare function defineDeps<D>(build: (env: ApplicationEnvironment, runtime: DepsRuntime) => D): AppDeps<D>;
+export interface ServeOptions {
+    /** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or `null` for a kit without tables (`defineApp(vocabulary)`). */
+    readonly database: ImplementationDatabase | null;
+    readonly deps?: AppDeps<unknown>;
+    /** The transport of the jobs that declare `mailer: 'own'`, built once at boot from the application's own variables. */
+    readonly mail?: (env: ApplicationEnvironment) => EmailSender | null;
+}
+/**
+ * The contract with the handlers its endpoints carry, ready for `boot`. The default export of `src/app.ts`. Throws
+ * `ContractError` naming every endpoint, job and webhook that took no `.handle(…)`.
+ */
+export declare function serve<const C extends AnyContract>(contract: C, options: ServeOptions): ContractImplementation<C>;

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

@@ -0,0 +1,49 @@
+import { type ContractArtifact, type SchemaShape } from '@fabrika/auth-core';
+import type { Schema } from '../contract/define';
+/** One key of the environment: its id, which each token it signs carries, and its secret. */
+export interface TokenKey {
+    readonly id: string;
+    readonly secret: Uint8Array;
+}
+/** A purpose as the runtime holds it: the claims schema the application declared, and the longest lifetime. */
+export interface RuntimePurpose {
+    readonly claims: Schema;
+    readonly maxDays: number;
+}
+/**
+ * The keys of `FABRIKA_TOKEN_KEYS`: `<kid>:<secret>` entries joined by `,`, the signing key first. Required when the
+ * contract declares a token purpose; refused at boot when malformed. `null` without purposes or after a problem.
+ */
+export declare function readTokenKeys(framework: Readonly<Record<string, string>>, artifact: ContractArtifact, problems: string[]): readonly TokenKey[] | null;
+/** The claims a verified token carried, and every text in them: a redirect target or a row id the request may use. */
+export interface VerifiedTokens {
+    readonly carried: ReadonlySet<string>;
+}
+export declare const NO_VERIFIED_TOKENS: VerifiedTokens;
+/**
+ * The environment's signed tokens. `purposes` are the application's declared claims schemas, by purpose; `keys` are
+ * `null` when the contract declares none, so a sign or a verification refuses.
+ */
+export declare class SignedTokens {
+    #private;
+    constructor(purposes: ReadonlyMap<string, RuntimePurpose>, keys: readonly TokenKey[] | null, now?: () => number);
+    /**
+     * `ctx.tokens` of a site: signs a token of a purpose `signs` names, valid for `days` (at most the purpose's
+     * `maxDays`). The claims are parsed by the purpose's schema first, so a token never carries what a verifier refuses.
+     */
+    context(site: string, signs: readonly string[]): {
+        readonly sign: (purpose: string, claims: unknown, options: unknown) => string;
+    };
+    /**
+     * The claims of `token` when it is a token of `purpose` this environment signed and it has not expired; a 400
+     * otherwise, which says only that it is not valid, so a caller learns nothing about the keys.
+     */
+    verify(purpose: string, token: string): Readonly<Record<string, unknown>>;
+    /**
+     * Each top-level signed token field of `value` (by `shape`, the approved input or query) replaced by its verified
+     * claims, and every text those claims carry.
+     */
+    verifyFields(shape: SchemaShape | null, value: Readonly<Record<string, unknown>>, into: Set<string>): Readonly<Record<string, unknown>>;
+}
+/** The top-level fields of an object shape that carry a signed token, optional or not, with their purposes. */
+export declare function tokenFields(shape: SchemaShape | null): ReadonlyMap<string, string>;