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

package/types/src/rpc/builder.d.ts

@@ -0,0 +1,52 @@
+import type { AuthContext, Scope } from '@fabrika/auth';
+import type { StandardSchemaV1 } from '../standard-schema.js';
+import type { AuthRequirement, Procedure, Router, RouterDef } from './types.js';
+type Handler<TContext, TInput, TOutput> = (args: {
+    ctx: TContext;
+    input: TInput;
+}) => TOutput | Promise<TOutput>;
+/** Builder before an output schema is set — the terminal infers the output type from the handler. */
+export declare class ProcedureBuilder<TContext, TInput> {
+    private readonly _input;
+    private readonly _requirements;
+    constructor(_input: StandardSchemaV1<unknown, TInput>, _requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>);
+    /** Set the input schema — ANY Standard Schema validator (zod, valibot, arktype, …). Resets requirements. */
+    input<TNewInput>(schema: StandardSchemaV1<unknown, TNewInput>): ProcedureBuilder<TContext, TNewInput>;
+    /** Set an output schema → switch to the output builder (handler result validated against it). */
+    output<TOutput>(schema: StandardSchemaV1<unknown, TOutput>): OutputProcedureBuilder<TContext, TInput, TOutput>;
+    /**
+     * Record an authz requirement, checked BEFORE the handler runs (all must pass).
+     * Only available when the context carries `auth: AuthContext`.
+     */
+    require<TThis extends {
+        auth: AuthContext;
+    }>(this: ProcedureBuilder<TThis, TInput>, action: string, scopeResolver?: (input: TInput, ctx: TThis) => Scope | undefined): ProcedureBuilder<TThis, TInput>;
+    /** Terminal: a neutral handler (tagged `query`). Output type inferred from the return. */
+    handler<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `query`-tagged handler. Output type inferred from the return. */
+    query<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `mutation`-tagged handler. Output type inferred from the return. */
+    mutation<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+}
+/** Builder after `.output(schema)` — the terminal fixes the output to the schema type + validates it. */
+export declare class OutputProcedureBuilder<TContext, TInput, TOutput> {
+    private readonly _input;
+    private readonly _output;
+    private readonly _requirements;
+    constructor(_input: StandardSchemaV1<unknown, TInput>, _output: StandardSchemaV1<unknown, TOutput>, _requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>);
+    /** Record an authz requirement, checked BEFORE the handler runs (all must pass). */
+    require<TThis extends {
+        auth: AuthContext;
+    }>(this: OutputProcedureBuilder<TThis, TInput, TOutput>, action: string, scopeResolver?: (input: TInput, ctx: TThis) => Scope | undefined): OutputProcedureBuilder<TThis, TInput, TOutput>;
+    /** Terminal: a neutral handler (tagged `query`); result validated against the output schema. */
+    handler(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `query`-tagged handler; result validated against the output schema. */
+    query(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+    /** Terminal: a `mutation`-tagged handler; result validated against the output schema. */
+    mutation(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput>;
+}
+export declare function initRpc<TContext>(): {
+    procedure: ProcedureBuilder<TContext, void>;
+    router<TDef extends RouterDef>(def: TDef): Router<TDef>;
+};
+export {};

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

@@ -0,0 +1,23 @@
+import type { InferRouterClient, Procedure, Router, RouterDef } from './types.js';
+/** A type-only RPC procedure declaration for a portable API contract. */
+export interface RpcProcedureContract<TInput, TOutput> {
+    readonly '~rpc': {
+        readonly input: TInput;
+        readonly output: TOutput;
+    };
+}
+/** Client-facing view of a portable contract. */
+export type InferRpcContractClient<TContract> = TContract extends RpcProcedureContract<infer TInput, infer TOutput> ? (input: TInput) => Promise<TOutput> : TContract extends object ? {
+    [K in keyof TContract]: InferRpcContractClient<TContract[K]>;
+} : never;
+/** Client-facing view of either a server router or a portable contract. */
+export type InferRpcClient<TApi> = TApi extends {
+    readonly _tag: 'router';
+    readonly _def: RouterDef;
+} ? InferRouterClient<TApi> : InferRpcContractClient<TApi>;
+type RpcRouterDefinition<TContext, TContract> = {
+    readonly [K in keyof TContract]: TContract[K] extends RpcProcedureContract<infer TInput, infer TOutput> ? Procedure<TContext, TInput, TOutput> : TContract[K] extends object ? RpcRouterFor<TContext, TContract[K]> : never;
+};
+/** Server router shape required to implement a portable contract. */
+export type RpcRouterFor<TContext, TContract> = Router<RpcRouterDefinition<TContext, TContract>>;
+export {};

package/types/src/rpc/dispatcher.d.ts

@@ -0,0 +1,11 @@
+import type { AnyRouter } from './types.js';
+/**
+ * Dispatch an RPC POST. The `ctx` is already built (with its `ctx.auth`, for example)
+ * by the server before this is called. One request is one call,
+ * `{ method, input }`.
+ */
+export declare function dispatchRpcRequest(args: {
+    router: AnyRouter;
+    ctx: unknown;
+    request: Request;
+}): Promise<Response>;

package/types/src/rpc/types.d.ts

@@ -0,0 +1,62 @@
+import type { AuthContext, Scope } from '@fabrika/auth';
+import type { StandardSchemaV1 } from '../standard-schema.js';
+/** `query` and `mutation` are metadata today — the dispatcher treats them identically. */
+export type ProcedureKind = 'query' | 'mutation';
+/**
+ * A recorded authorization requirement. `scopeResolver` is declared as a METHOD
+ * (bivariant params) on purpose, so a concrete `Procedure<C, I, O>` stays
+ * assignable to `AnyProcedure`.
+ */
+export interface AuthRequirement<TContext, TInput> {
+    readonly action: string;
+    scopeResolver?(input: TInput, ctx: TContext): Scope | undefined;
+}
+export interface Procedure<TContext, TInput, TOutput> {
+    readonly _tag: 'procedure';
+    readonly kind: ProcedureKind;
+    readonly input: StandardSchemaV1<unknown, TInput>;
+    readonly output: StandardSchemaV1<unknown, TOutput> | null;
+    readonly requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>;
+    handler(args: {
+        ctx: TContext;
+        input: TInput;
+    }): Promise<TOutput> | TOutput;
+}
+export interface AnyProcedure {
+    readonly _tag: 'procedure';
+    readonly kind: ProcedureKind;
+    readonly input: StandardSchemaV1;
+    readonly output: StandardSchemaV1 | null;
+    readonly requirements: ReadonlyArray<AuthRequirement<unknown, unknown>>;
+    handler(args: {
+        ctx: unknown;
+        input: unknown;
+    }): Promise<unknown> | unknown;
+}
+export type RouterDef = {
+    readonly [key: string]: AnyProcedure | AnyRouter;
+};
+export interface Router<TDef extends RouterDef> {
+    readonly _tag: 'router';
+    readonly _def: TDef;
+}
+export type AnyRouter = Router<RouterDef>;
+/** Re-export the auth contract used by procedure requirements. */
+export type { AuthContext, Scope };
+/** Server-facing view of a router: each procedure as its handler signature. */
+export type InferRouter<TRouter> = TRouter extends {
+    _tag: 'router';
+    _def: infer TDef;
+} ? TDef extends RouterDef ? {
+    [K in keyof TDef]: TDef[K] extends Procedure<infer C, infer I, infer O> ? (args: {
+        ctx: C;
+        input: I;
+    }) => Promise<O> | O : TDef[K] extends Router<RouterDef> ? InferRouter<TDef[K]> : never;
+} : never : never;
+/** Client-facing view of a router: each procedure as `(input) => Promise<output>`. */
+export type InferRouterClient<TRouter> = TRouter extends {
+    _tag: 'router';
+    _def: infer TDef;
+} ? TDef extends RouterDef ? {
+    [K in keyof TDef]: TDef[K] extends Procedure<unknown, infer I, infer O> ? (input: I) => Promise<O> : TDef[K] extends Router<RouterDef> ? InferRouterClient<TDef[K]> : never;
+} : never : never;

package/types/src/service/define.d.ts

@@ -0,0 +1,42 @@
+import { type BodyAdmission, type InstallationCaller, type InstallationEndpointMethod, type InstallationEndpointRow, type InstallationEndpointTable } from '@fabrika/auth-core';
+/** A row as the builder writes it; the record key of `endpoints` becomes its id. */
+export type ServiceEndpointSpec = InstallationEndpointRow extends infer Row ? Row extends InstallationEndpointRow ? Omit<Row, 'id'> : never : never;
+/** One installation service's table, with the row ids as a type so its handlers can be checked against them. */
+export interface ServiceArtifact<Id extends string = string> extends InstallationEndpointTable {
+    /** The service's IAM app id; never `<app>@<env>`. */
+    readonly id: string;
+    readonly endpoints: readonly (InstallationEndpointRow & {
+        readonly id: Id;
+    })[];
+}
+export interface ServiceEndpointOptions {
+    readonly callers: readonly [InstallationCaller, ...InstallationCaller[]];
+    /** The request body the row admits; omitted admits none. */
+    readonly admission?: BodyAdmission;
+    /** The scopes an OAuth resource token must carry; required exactly when `callers` holds `oauth`. */
+    readonly scopes?: readonly string[];
+}
+export interface ServiceContractBuilder {
+    /** A liveness endpoint: anonymous, and served without `X-Fabrika-Endpoint`. */
+    health(method: InstallationEndpointMethod, path: string): ServiceEndpointSpec;
+    /** An endpoint the service authenticates itself; the proxy reads no credential and keeps `Authorization`. */
+    protocol(method: InstallationEndpointMethod, path: string): ServiceEndpointSpec;
+    /** A credentialed endpoint: a listed caller kind, and no permission (`authenticated`). */
+    service(method: InstallationEndpointMethod, path: string, options: ServiceEndpointOptions): ServiceEndpointSpec;
+}
+export interface ServiceContractDeclaration<Id extends string> {
+    /** `null` is a row this composition does not serve: the table has no row there, and its handler is never called. */
+    readonly endpoints: Readonly<Record<Id, ServiceEndpointSpec | null>>;
+    /** Literal prefixes a path under which reaches only a row declared under it. */
+    readonly reservedPrefixes: readonly string[];
+}
+export declare class ServiceContractError extends Error {
+    readonly name = "ServiceContractError";
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/**
+ * Declare one installation service's endpoint table. Validated here, once: an id that is an application environment,
+ * an `oauth` caller without its scopes (or scopes without it), and every table the matcher would refuse.
+ */
+export declare function defineServiceContract<const Id extends string>(id: string, declare: (s: ServiceContractBuilder) => ServiceContractDeclaration<Id>): ServiceArtifact<Id>;

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

@@ -0,0 +1,3 @@
+export { dispatchRpcRequest } from '../rpc/dispatcher.js';
+export { defineServiceContract, type ServiceArtifact, type ServiceContractBuilder, type ServiceContractDeclaration, ServiceContractError, type ServiceEndpointOptions, type ServiceEndpointSpec, } from './define.js';
+export { serveService, type ServeServiceOptions, type ServiceHandler, type ServiceHandlers, ServiceHandlersError, type ServiceRequest, } from './serve.js';

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

@@ -0,0 +1,28 @@
+import type { FetchService, RequestExecutionContext } from '../fetch.js';
+import type { ServiceArtifact } from './define.js';
+export interface ServiceRequest<Env> {
+    readonly request: Request;
+    /** The `:name` segments of the selected path, percent-decoded. */
+    readonly params: Readonly<Record<string, string>>;
+    readonly env: Env;
+    readonly exec: RequestExecutionContext;
+}
+export type ServiceHandler<Env> = (input: ServiceRequest<Env>) => Response | Promise<Response>;
+/** One handler per declared row id, also for a row this composition left out; that one is never called. */
+export type ServiceHandlers<Id extends string, Env> = {
+    readonly [K in Id]: ServiceHandler<Env>;
+};
+export interface ServeServiceOptions<Env> {
+    /** Map a value a handler threw to a response. Defaults to the structural error mapping. */
+    readonly onError?: (error: unknown, request: Request, env: Env) => Response;
+}
+export declare class ServiceHandlersError extends Error {
+    readonly name = "ServiceHandlersError";
+}
+/**
+ * Serve a service contract. Per request: a non-canonical path is a 400, a request no row selects a 404, a `service`
+ * row reached without the proxy's `X-Fabrika-Endpoint` for that row and its digest a 503; then the row's handler. A
+ * `protocol` or `health` row ignores the header, because the service authenticates it itself and it also arrives
+ * unfronted (ADR-0022 rule 5).
+ */
+export declare function serveService<Id extends string, Env>(service: ServiceArtifact<Id>, handlers: ServiceHandlers<Id, Env>, options?: ServeServiceOptions<Env>): FetchService<Env>;

package/types/src/standard-schema.d.ts

@@ -0,0 +1,55 @@
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}

package/types/src/testing/caller.d.ts

@@ -0,0 +1,95 @@
+import type { PermissionEntry, PrincipalAffiliation } from '@fabrika/auth-core';
+import type { ActionOf, AnyContract, DimensionOf, RoleOf } from '../contract/define';
+/** `app` is the connector of another application: its key reaches only the exports that application consumes. */
+export type TestCallerKind = 'human' | 'machine' | 'link' | 'app';
+export interface TestScope<D extends string = string> {
+    readonly type: D;
+    readonly value: string;
+}
+/** An action, or a role whose actions IAM grants together; without a scope it is global. */
+export type TestGrant<C> = {
+    readonly action: ActionOf<C>;
+    readonly scope?: TestScope<DimensionOf<C>>;
+} | {
+    readonly role: RoleOf<C>;
+    readonly scope?: TestScope<DimensionOf<C>>;
+};
+export interface TestCallerOptions {
+    /** Defaults to `human`. */
+    readonly kind?: TestCallerKind;
+    /** How a human signs in: the IAM session (default) or a `px_` key bound to the person. Other kinds use a key. */
+    readonly via?: 'session' | 'key';
+    readonly id?: string;
+    readonly label?: string;
+    /** A human's address (`ctx.principal.email`), normalized as IAM stores it. Only a human has one. */
+    readonly email?: string;
+    /**
+     * Defaults to `internal`. An `external` human holds only roles the contract declares `external`, as IAM resolves it
+     * (ADR-0051); the kit refuses any other grant for one.
+     */
+    readonly affiliation?: PrincipalAffiliation;
+    /**
+     * An operator disabled the principal in IAM: a member directory lists and finds it with `disabled: true`, and the kit's
+     * IAM signs no token for its session or key, so its requests are refused as IAM refuses a disabled principal's.
+     */
+    readonly disabled?: boolean;
+    /**
+     * When the person last signed in to the application (unix seconds), as IAM records it at the handoff; absent, never.
+     * A member directory answers it to a holder of `members.manage` only. Only a human signs in.
+     */
+    readonly lastSignInAt?: number;
+    /** The consuming application's id, for an `app` caller. */
+    readonly app?: string;
+    /**
+     * What a `link` caller's key is bound to: the link mount, and the object first, then each value containing it. A link
+     * caller without one holds a key bound to nothing, which no procedure admits.
+     */
+    readonly link?: TestLink;
+}
+export interface TestLink {
+    readonly mount: string;
+    readonly chain: readonly TestScope[];
+}
+interface TestCallerCredential {
+    /** The principal id, or the share key's credential id for a link. */
+    readonly id: string;
+    /** `internal` for every caller but an `external` human. */
+    readonly affiliation: PrincipalAffiliation;
+    /** `true` for a principal an operator disabled; `false` for every other caller, a link holder included. */
+    readonly disabled: boolean;
+    /** A human's last sign-in to the application (`TestCallerOptions.lastSignInAt`); `null` for one that never did and every other caller. */
+    readonly lastSignInAt: number | null;
+    readonly perms: readonly PermissionEntry[];
+    /** The `px_` key a key caller presents as a bearer; `null` for a session. */
+    readonly key: string | null;
+    /** The `Cookie` header a signed-in browser sends; `null` for a key caller. */
+    readonly cookie: string | null;
+}
+/** A person, a script or another application's connector: a principal with a label. */
+export interface LabelledTestCaller extends TestCallerCredential {
+    readonly kind: Exclude<TestCallerKind, 'link'>;
+    /** The consuming application of an `app` caller, `null` for every other kind. */
+    readonly app: string | null;
+    readonly link: null;
+    readonly label: string;
+    /** A human's normalized address, which its token carries; `null` for a script and a connector. */
+    readonly email: string | null;
+}
+/** A person, whose token carries its address: `ctx.principal.email` of its requests. */
+export interface PersonTestCaller extends LabelledTestCaller {
+    readonly kind: 'human';
+    readonly email: string;
+}
+/** The holder of a share link: an anonymous key, which carries no label. */
+export interface LinkTestCaller extends TestCallerCredential {
+    readonly kind: 'link';
+    readonly app: null;
+    /** The link mount and chain the key is bound to; `null` for a key bound to nothing. */
+    readonly link: TestLink | null;
+    readonly label: null;
+    readonly email: null;
+}
+export type TestCaller = LabelledTestCaller | LinkTestCaller;
+/** The permissions `grants` resolve to: a role becomes each of its actions in the role's scope. */
+export declare function resolveGrants<C extends AnyContract>(contract: C, grants: readonly TestGrant<C>[]): PermissionEntry[];
+export {};

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

@@ -0,0 +1,11 @@
+import type { RpcFetch } from '../client/transport';
+import type { ChallengeFetch } from '../implement/challenge';
+/** The token Turnstile's always-passing test widget (site key `1x00000000000000000000AA`) hands out every time. */
+export declare const TURNSTILE_TEST_TOKEN = "XXXX.DUMMY.TOKEN.XXXX";
+/** Turnstile's siteverify that passes every token: a fresh answer for the host and the form the check expects. */
+export declare const passingChallenge: ChallengeFetch;
+/**
+ * Fetches a challenge from `url` through `fetch` and solves it as the widget does, answering the payload the page puts
+ * into `challengeToken`. The kit issues the cheapest challenge, so this takes milliseconds.
+ */
+export declare function solveChallengeAt(fetch: RpcFetch, url: string): Promise<string>;

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

@@ -0,0 +1,97 @@
+import { type EmailDeliveryErrorCode, type EmailDeliveryOutcome } from '@fabrika/email';
+import type { AnyContract, DimensionOf } from '../contract/define';
+import type { ContractImplementation } from '../implement/implement';
+import type { PersonTestCaller, TestCaller } from './caller';
+import { type TestKit, type TestKitOptions } from './kit';
+import type { SentInvitation, TestMembership } from './membership';
+/** Someone the author clicks through the application as: a person the seed made with `dev.testCaller`. */
+export interface DevPersona {
+    /** Shown on the picker's card and in the toolbar, unique among the personas: `Petra`. */
+    readonly name: string;
+    /** One short line of who this is: `Staff of the design workspace`. */
+    readonly description?: string;
+    readonly caller: PersonTestCaller;
+}
+/** A page a link holder opens: a link the seed issued through the application's own endpoint. */
+export interface DevLink {
+    readonly title: string;
+    readonly description?: string;
+    /** The URL the application answered, a path of its origin: `/s/#px_…`. */
+    readonly url: string;
+}
+/** A scope value the seed made, with the name a person knows it by: `{ value: 'w1', label: 'Design team' }`. */
+export interface DevScopeValue {
+    readonly value: string;
+    readonly label: string;
+}
+/** What a seed answers; every part is optional. */
+export interface DevSeedResult<C extends AnyContract> {
+    readonly personas?: readonly DevPersona[];
+    readonly links?: readonly DevLink[];
+    /** The values of each dimension the seed made, which the picker offers for a membership role. */
+    readonly scopes?: {
+        readonly [D in DimensionOf<C>]?: readonly DevScopeValue[];
+    };
+}
+/** The origin `fabrika app dev` captures every request to: an outside provider's stand-in, named by its path. */
+export declare const DEV_OUTBOX_ORIGIN = "https://outbox.invalid";
+/** A request the application sent to `DEV_OUTBOX_ORIGIN` under `fabrika app dev`: its body, never its headers. */
+export interface DevOutboxMessage {
+    readonly id: number;
+    readonly method: string;
+    /** The path it was sent to: `/mail`. */
+    readonly path: string;
+    readonly contentType: string | null;
+    readonly body: string;
+}
+/** A message a job handed to the kit's mail stand-in, as `fabrika app dev` shows it. */
+export interface DevMail {
+    /** Its position among the handoffs, from 1. */
+    readonly id: number;
+    /** When it was handed off, ISO 8601. */
+    readonly at: string;
+    readonly to: string;
+    readonly subject: string;
+    readonly text: string;
+    readonly html: string | null;
+    readonly replyTo: string | null;
+    readonly fromName: string | null;
+    /** The idempotency key as the job passed it. */
+    readonly key: string;
+    /** The key the transport got: `key` behind the application environment's prefix. */
+    readonly transportKey: string;
+    readonly answer: 'accepted' | EmailDeliveryErrorCode;
+    readonly outcome: 'accepted' | EmailDeliveryOutcome;
+    /** Whether this handoff put the message in the inbox; a repeat under its key does not. */
+    readonly delivered: boolean;
+}
+/** What `fabrika app dev` stands in for outside the application, for the seed to read. */
+export interface DevOutside {
+    /** Every request sent to `DEV_OUTBOX_ORIGIN` so far, oldest first. */
+    outbox(): readonly DevOutboxMessage[];
+    /** Every message a job handed to the mail stand-in so far, oldest first. */
+    mails(): readonly DevMail[];
+}
+/**
+ * The default export of `dev/seed.ts`: it receives the application's test kit, the API its tests use, writes through the
+ * endpoints, and answers who and what the picker offers. `outside` reads what the application sent to the dev outbox
+ * and every message a job handed to the mail stand-in, oldest first.
+ */
+export type DevSeed<C extends AnyContract> = (dev: TestKit<C>, outside: DevOutside) => Promise<DevSeedResult<C>> | DevSeedResult<C>;
+export interface DevKit<C extends AnyContract> {
+    readonly kit: TestKit<C>;
+    /** The person `value` is when this kit made it; `undefined` for any other value. */
+    personOf(value: unknown): PersonTestCaller | undefined;
+    /** The roles a caller of this kit holds now: its grants, with what the application assigned and revoked through IAM. */
+    membershipsOf(caller: TestCaller): readonly TestMembership[];
+    /** The invitation e-mails the stand-in IAM sent, in the order it first sent them. */
+    invitations(): readonly SentInvitation[];
+    /** Every message the application's jobs handed to the mail stand-in, oldest first; one refused before the handoff is absent. */
+    mails(): readonly DevMail[];
+}
+/**
+ * The test kit of `app` with its stand-in IAM, and what `fabrika app dev` shows of it. A challenge passes
+ * (`passingChallenge`) unless `options.challengeFetch` answers it, and admits the test widget's token
+ * (`TURNSTILE_TEST_TOKEN`) at every call; any other token is single use, as deployed.
+ */
+export declare function devKit<C extends AnyContract>(app: ContractImplementation<C>, options?: Omit<TestKitOptions, 'membership'>): DevKit<C>;

package/types/src/testing/endpoint-access.d.ts

@@ -0,0 +1,99 @@
+import { type ContractArtifact, type Scope } from '@fabrika/auth-core';
+import type { Tables } from '@fabrika/db';
+import { type SampleValue, type TestDatabase } from '@fabrika/db/testing';
+import type { AnyContract } from '../contract/define';
+import type { ContractImplementation } from '../implement/implement';
+export interface DeniedOutcome {
+    readonly status: number;
+}
+/**
+ * `answered` when every answer to the own scope is one the application gave: a 2xx, or a 4xx other than 401, 403 and
+ * 404 (a precondition's 409 included). Otherwise `status` is the first other answer. `leaked` are the values of the
+ * other scope's rows that the answers held: keys, parents, scope values and text markers.
+ */
+export type LeakOutcome = {
+    readonly answered: true;
+    readonly leaked: readonly string[];
+} | {
+    readonly answered: false;
+    readonly status: number;
+    readonly leaked: readonly string[];
+};
+/** `answered` unless the caller got a 401, a 403 or a 5xx; otherwise that status. */
+export type ReachOutcome = {
+    readonly answered: true;
+} | {
+    readonly answered: false;
+    readonly status: number;
+};
+/** Column → value of the row of the table that owns the endpoint's dimension, in both scopes: the author's seed. */
+export type Seed = Readonly<Record<string, SampleValue>>;
+export interface EndpointAccessKit {
+    /**
+     * A caller holding the endpoint's action in one scope names an object (`on`) or a scope value (`in`) of another;
+     * `input` is the rest of a valid input, and its `from` field is replaced.
+     */
+    denied(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>;
+    /**
+     * A caller of the other scope asks first, then a caller of one scope asks for its own object (`on`), its list
+     * (`over`) or, for every table that lies in the dimension, its scope value (`in`).
+     */
+    leaked(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<LeakOutcome>;
+    /**
+     * A caller that holds only the endpoint's action asks for its own object: a person or a script in its scope, or, on
+     * a link mount, the holder of a link bound to the object. A write action reads its own target. Where IAM requires more
+     * of the caller, it holds that too: a member manager an assigning role and the assigned role's actions, a link's
+     * issuer the actions the link grants.
+     */
+    own(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>;
+    /**
+     * An `app` or a `creates` endpoint asked by a caller who holds its action in one value of a dimension only, never
+     * globally: refused (403), by the proxy for `app` and by IAM for `creates`, since both need a global grant.
+     */
+    scoped(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<DeniedOutcome>;
+    /**
+     * An `app` or a `creates` endpoint asked by a caller who holds its action as a global grant, and nothing else:
+     * `answered` unless the answer is a 401, a 403 or a 5xx.
+     */
+    global(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>;
+    /**
+     * One capability of an endpoint of several, refused while every other one passes: the caller holds each other one's
+     * action in a scope of its own and addresses its object or value there (or, for `over`, holds the action globally).
+     * For an `on` or `in` capability it also holds the named one's action in its own scope and addresses the other's
+     * object (404) or value (403); for `over` it holds the named action nowhere (403). `seed` is the named one's.
+     */
+    capability(endpoint: string, capability: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>;
+    /**
+     * A public procedure asked by anyone, with no credential, from a page of its own origin: `answered` unless the answer
+     * is a 401, a 403, a 5xx or a failed challenge. A procedure with a challenge is a 400 `challenge_failed`: the kit's
+     * challenge never passes.
+     */
+    anyone(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>;
+}
+export type Grant = {
+    readonly action: string;
+    readonly scope: {
+        readonly type: string;
+        readonly value: string;
+    };
+} | {
+    readonly role: string;
+    readonly scope: {
+        readonly type: string;
+        readonly value: string;
+    };
+};
+/**
+ * The least a member manager holds in `scope` for IAM to let it give or remove the roles a case may ask for: the
+ * endpoint's action, one assigning role of each (`assignableBy`) that adds the fewest actions beyond those, and the
+ * actions of each as plain grants. The roles a case asks for are the membership roles its input names; an input that
+ * names none may ask for any, so the caller then covers every membership role of the dimension. Where one role assigns
+ * them all, it is the only role held. Every role is held in `scope`, an application-wide assigner too: IAM counts any
+ * assigning role held there, and a grant in `scope` reaches no other value.
+ */
+export declare const managerGrants: (artifact: Pick<ContractArtifact, "roles">, action: string, input: Readonly<Record<string, unknown>>, scope: Scope) => Grant[];
+/**
+ * The endpoint access kit of `app`, whose data layer is `scoped(tables)`, over `postgres`. It boots `app` once, so the
+ * application's layer is bound here and nowhere else in the process.
+ */
+export declare function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract>, tables: Tables<DB, P>, postgres: TestDatabase): EndpointAccessKit;

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

@@ -0,0 +1,12 @@
+export type { IamMembershipRpc } from '@fabrika/auth-core';
+export { type MemoryEmail, MemoryEmailSender, type MemoryHandoff } from '@fabrika/email/memory';
+export type { FileScanner } from '../files/scan';
+export type { ChallengeFetch } from '../implement/challenge';
+export { mailKeyPrefix, type MailKeyScope, transportMailKey } from '../jobs/mail';
+export type { HandlerErrorSink } from '../jobs/runner';
+export type { LabelledTestCaller, LinkTestCaller, PersonTestCaller, TestCaller, TestCallerKind, TestCallerOptions, TestGrant, TestLink, TestScope, } from './caller';
+export { passingChallenge } from './challenge';
+export { DEV_OUTBOX_ORIGIN, type DevKit, devKit, type DevLink, type DevMail, type DevOutboxMessage, type DevOutside, type DevPersona, type DevScopeValue, type DevSeed, type DevSeedResult, } from './dev';
+export { type JobName, TEST_ENVIRONMENT, TEST_ISSUER, type TestConnection, type TestKit, testKit, type TestKitOptions } from './kit';
+export type { SentInvitation, TestMembership } from './membership';
+export { statusOf } from './status';

package/types/src/testing/isolation.d.ts

@@ -0,0 +1,3 @@
+export { type DeniedOutcome, type EndpointAccessKit, endpointAccessKit, type LeakOutcome, type ReachOutcome } from './endpoint-access';
+export { type AppCaller, type AppCountOutcome, type AppIsolationKit, appPolicyIsolationKit, type ChildIsolationRow, type CountOutcome, type IsolationOutcome, type IsolationRow, type ListOutcome, type MisuseOutcome, type PolicyIsolationKit, policyIsolationKit, type ReadOutcome, } from './policy-isolation';
+export { afterAll, describe, expect, test } from './runner';