@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

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

@@ -0,0 +1,131 @@
+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>>;
+/**
+ * Table → column → value: one row of each application table the handler reads for the caller's own scope, seeded
+ * before a leak or an own case asks and removed once it is over, with every row that refers to it, so no other case
+ * finds it. Both scopes may see it, so its values are never counted as the other scope's.
+ */
+export type AppRows = Readonly<Record<string, Seed>>;
+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`). `appRows` are seeded first, as
+     * for `own`.
+     */
+    leaked(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed, appRows?: AppRows): 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. `appRows` are the rows of application tables its handler reads (the guide a link
+     * holder downloads), each seeded first.
+     */
+    own(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed, appRows?: AppRows): 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 interface EndpointAccessOptions {
+    /**
+     * The file every case of an endpoint sends in a file field instead of the kit's sample, by endpoint id and input
+     * field: a file of the application's repository that a handler inspecting the content accepts (a valid package). Its
+     * type is the first of the field's kind that its bytes are; a file of none of them throws. `files` of the fixtures.
+     */
+    readonly files?: Readonly<Record<string, Readonly<Record<string, URL>>>>;
+    /**
+     * The error types of the refusals (400) an endpoint's handler answers its own object with when the case's input meets
+     * no domain rule the kit can satisfy, by endpoint id: such a 400 is the handler's own answer, so the request passed
+     * the access form, and the endpoint's own case gets it as `{ status: 400 }` instead of failing; so does the other
+     * scope's request a leak case makes first. The own scope's answer of a leak case, and a global or capability case,
+     * still throw on it (an answer that holds nothing proves no isolation), so does any other 400, and an input the schema
+     * refuses (`validation`) always does. `refusals` of the fixtures.
+     */
+    readonly refusals?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Known values for text columns of the row the endpoint addresses (the row of the table that owns its dimension), by
+     * endpoint id: the value in the own scope's row, and `<value>-other` in the other scope's, which counts among the
+     * other scope's values a leak shows. For a handler whose rule ties a column to the input or a file fixture (a package
+     * that names the skill's slug). `pins` of the fixtures.
+     */
+    readonly pins?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+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, options?: EndpointAccessOptions): 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 EndpointAccessOptions, 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';

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

@@ -0,0 +1,187 @@
+import { type ContractArtifact, type IamMembershipRpc, type IamTerminalRpc } from '@fabrika/auth-core';
+import type { Database } from '@fabrika/db';
+import { MemoryEmailSender } from '@fabrika/email/memory';
+import type { FileObjectStore } from '@fabrika/platform';
+import { type IamGateway } from '@fabrika/proxy-core';
+import type { z } from 'zod/v4';
+import type { RpcFetch } from '../client/transport';
+import type { AnyContract, DimensionOf } from '../contract/define';
+import type { TokenPurpose } from '../contract/token';
+import type { FILE_SWEEP_JOB } from '../files/kinds';
+import type { FILE_SCAN_JOB, FileScanner } from '../files/scan';
+import { type BootOptions } from '../implement/boot';
+import { type ChallengeFetch } from '../implement/challenge';
+import { type ConnectFetch } from '../implement/connect';
+import type { SpaAssets } from '../implement/dispatch';
+import type { ApplicationEnvironment, ContractImplementation } from '../implement/implement';
+import type { MailKeyScope } from '../jobs/mail';
+import type { HandlerErrorSink } from '../jobs/runner';
+import type { JobRunOptions, JobRunResult } from '../jobs/runner';
+import { type LabelledTestCaller, type LinkTestCaller, type PersonTestCaller, type TestCaller, type TestCallerOptions, type TestGrant, type TestScope } from './caller';
+import { type KitMembership } from './membership';
+export declare const TEST_ISSUER = "https://iam.test";
+export declare const TEST_ENVIRONMENT = "test";
+export interface TestKitOptions {
+    /** The application's own variables, as `deps` receives them. */
+    readonly env?: ApplicationEnvironment;
+    /**
+     * The address the kit's proxy reports for every request, as the platform's proxy reports the visitor's
+     * (`X-Fabrika-Client-Ip`): what `ctx.client.ip` reads and a per-client bucket counts. `192.0.2.1` by default.
+     */
+    readonly clientIp?: string;
+    /**
+     * The application root an SPA mount's `dir` is relative to; the working directory when omitted. A mount whose built
+     * directory exists there is served from it as the deploy serves it: a file by its path, every other path by the
+     * directory's `index.html`. A mount not built is an empty HTML document.
+     */
+    readonly root?: string;
+    /** Serves the SPA mounts in place of their built directories under `root`. */
+    readonly assets?: SpaAssets;
+    /** The connection a `scoped(tables)` database is bound to, as the runtime adapter supplies it to `boot`. */
+    readonly database?: Database;
+    /** The object storage of the stored files, as the runtime adapter supplies it to `boot`. */
+    readonly files?: FileObjectStore;
+    /** The scanner of the scan job of `scan: true` file kinds; without it, the job leaves every such file quarantined. */
+    readonly scanner?: FileScanner;
+    /**
+     * IAM's membership operations in place of the kit's own stand-in: `boot` asks it as the adapter's transport, and the
+     * kit's proxy obtains each delegation grant from it. Without it the kit's IAM answers them under IAM's rules.
+     */
+    readonly membership?: IamMembershipRpc;
+    /**
+     * IAM's identifications at a terminal (ADR-0067), for a contract that declares one. Without it the kit's IAM knows no
+     * open identification: `inspect` answers null and `assert` `not_found`.
+     */
+    readonly terminals?: IamTerminalRpc;
+    /**
+     * Each import's owner, by the import's name: its origin and edge key, which the platform writes as the import's
+     * framework variables, and how a request reaches it — usually the owner kit's `fetch`.
+     */
+    readonly connect?: Readonly<Record<string, TestConnection>>;
+    /** What answers a public procedure's challenge verification in place of the provider: a stand-in for its siteverify. */
+    readonly challengeFetch?: ChallengeFetch;
+    /** What a job's handler threw, shown on the developer's own machine: `fabrika app dev` sets it, a test need not. */
+    readonly revealHandlerErrors?: HandlerErrorSink;
+    /**
+     * The stand-in for every job's mail transport; a new `MemoryEmailSender` by default. Pass one with other capabilities
+     * to model another provider: `new MemoryEmailSender({ capabilities: { idempotent: false, confirmation: 'queued' } })`.
+     * `'none'` models an installation without a transport: `ctx.mail.available` is false, and every send fails
+     * `mail_not_configured`.
+     */
+    readonly mail?: MemoryEmailSender | 'none';
+    /**
+     * The origins the environment lists for the contract's endpoints that admit `origins: 'listed'`, as an operator sets them in
+     * Control; a page on one of them may call such an endpoint with a key. None when omitted.
+     */
+    readonly crossOrigins?: readonly string[];
+}
+export interface TestConnection {
+    readonly origin: string;
+    readonly key: string;
+    readonly fetch: ConnectFetch;
+}
+export interface TestKit<C extends AnyContract> {
+    /** The origin requests are resolved against, `https://<app>.test`. */
+    readonly origin: string;
+    /** The token audience, `<app>@test`. */
+    readonly appId: string;
+    /** The contract as compiled for `boot`. */
+    readonly artifact: ContractArtifact;
+    /** A new principal of the test IAM holding `grants`, with a fresh credential; only a link holder has no label. */
+    testCaller(grants: readonly TestGrant<C>[], options: TestCallerOptions & {
+        readonly kind: 'link';
+    }): LinkTestCaller;
+    testCaller(grants: readonly TestGrant<C>[], options?: TestCallerOptions & {
+        readonly kind?: 'human';
+    }): PersonTestCaller;
+    testCaller(grants: readonly TestGrant<C>[], options?: TestCallerOptions & {
+        readonly kind?: LabelledTestCaller['kind'];
+    }): LabelledTestCaller;
+    testCaller(grants: readonly TestGrant<C>[], options?: TestCallerOptions): TestCaller;
+    /**
+     * One value of the contract's dimension `dimension`, for a grant's `scope`. Stored in a variable it keeps its
+     * dimension, where an object literal's `type` widens to `string`: `const acme = kit.scope('org', 'acme')`.
+     */
+    scope<D extends DimensionOf<C>>(dimension: D, value: string): TestScope<D>;
+    /** A request as it reaches the proxy, credentials as written: a script, a `px_` key, or another site. */
+    readonly fetch: RpcFetch;
+    /** `fetch` from a page of the application: same-origin, with the session cookie of `caller` when given. */
+    browser(caller?: TestCaller): RpcFetch;
+    /** The test IAM as the proxy calls it: it mints for the credentials `testCaller` issued and serves their key set. */
+    readonly iam: IamGateway;
+    /**
+     * The addressee of an invitation the kit's IAM holds open accepts it, as IAM's onboarding does: `person` holds the
+     * invited role in its scope from now on, or, without one, a new person labelled by the invited address does. Answers
+     * that person. Throws, leaving the invitation open, as IAM refuses: an external `person` and a role not declared
+     * external (`not_eligible`), an inviter that can no longer give the role (`not_allowed`). Throws for an invitation
+     * that is not open, and in a kit given its own `membership`.
+     */
+    acceptInvitation(invitationId: string, person?: LabelledTestCaller): LabelledTestCaller;
+    /**
+     * Runs the cron job `name` once, as `fabrika job run <name>` does: under its lease, with the actions IAM signs for
+     * its key, its writes fenced. It first waits for the runs a site's `ctx.kick` sent, so it never races them.
+     * `FILE_SCAN_JOB` runs the scan of `scan: true` file kinds with the kit's `scanner`, `FILE_SWEEP_JOB` the sweep of
+     * unreferenced files. Needs the application's data layer on Postgres.
+     */
+    runJob(name: JobName<C> | typeof FILE_SCAN_JOB | typeof FILE_SWEEP_JOB, options?: JobRunOptions): Promise<JobRunResult>;
+    /** Waits for the work requests left running: the runs a site's `ctx.kick` sent, a failure's report. */
+    drain(): Promise<void>;
+    /**
+     * The stand-in for every job's transport: what reached it (`accepted`, `handoffs`) and its faults (`refuse`,
+     * `unavailable`, `unreachable`, `loseAnswers`, `during`, `heal`). Each message carries the transport key,
+     * `transportMailKey(kit.mailKeyScope, key)`. Under `mail: 'none'` nothing reaches it.
+     */
+    readonly mail: MemoryEmailSender;
+    /** Whose keys this kit's prefix separates: `mailKeyPrefix(kit.mailKeyScope)` is what a job's key gets in front. */
+    readonly mailKeyScope: MailKeyScope;
+    /**
+     * A token of `purpose`, signed with the key the kit handed the application, as a site's `ctx.tokens.sign` signs it:
+     * what a test sends where an input carries `signedToken('<purpose>')`.
+     */
+    signToken<const P extends TokenPurposeName<C>>(purpose: P, claims: TokenClaimsInput<C, P>, options: {
+        readonly days: number;
+    }): string;
+    /**
+     * A solved ALTCHA challenge of `procedure`, a procedure of a client over this kit whose challenge is
+     * `provider: 'altcha'`: what the page sends as `challengeToken`. Each one passes once. The kit issues the cheapest
+     * challenge whatever the contract's `cost`, so solving one takes milliseconds.
+     */
+    solveChallenge(procedure: object): Promise<string>;
+}
+/** The names of the contract's cron jobs. */
+export type JobName<C> = C extends {
+    readonly surface: {
+        readonly jobs: infer J;
+    };
+} ? keyof J & string : never;
+type TokensOf<C> = C extends {
+    readonly surface: {
+        readonly tokens: infer T;
+    };
+} ? T : Record<never, never>;
+/** The token purposes of the contract's kit. */
+export type TokenPurposeName<C> = keyof TokensOf<C> & string;
+/** What a token of purpose `P` carries, as a site passes it to `sign`. */
+export type TokenClaimsInput<C, P extends string> = TokensOf<C> extends {
+    readonly [K in P]: TokenPurpose<infer Claims>;
+} ? z.input<Claims> : never;
+/** Boots `app` the way its generated entrypoint would, behind the test proxy and IAM. Throws `BootError` like `boot`. */
+export declare function testKit<C extends AnyContract>(app: ContractImplementation<C>, options?: TestKitOptions): TestKit<C>;
+/** The kit of the generated tests, and its stand-in IAM, which seeds the invitations and links a case names. */
+export interface StandInIamKit<C extends AnyContract> {
+    readonly kit: TestKit<C>;
+    readonly standIn: KitMembership;
+}
+/** The kit of the generated tests, with a handle on its stand-in IAM to seed what a case names. */
+export declare function standInIamKit<C extends AnyContract>(app: ContractImplementation<C>, options?: Omit<TestKitOptions, 'membership'>): StandInIamKit<C>;
+/** A booted kit, and its stand-in IAM unless it was given a membership transport. */
+export interface BootedTestKit<C extends AnyContract> {
+    readonly kit: TestKit<C>;
+    readonly standIn: KitMembership | null;
+    /** The caller `value` is when `testCaller` or `acceptInvitation` of this kit made it; `undefined` for any other value. */
+    callerOf(value: unknown): TestCaller | undefined;
+}
+/** What only `fabrika app dev`'s kit boots with, never a test's. */
+export type DevBootOptions = Pick<BootOptions, 'repeatableChallengeToken'>;
+export declare function bootTestKit<C extends AnyContract>(app: ContractImplementation<C>, options: TestKitOptions, dev?: DevBootOptions): BootedTestKit<C>;
+export {};

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

@@ -0,0 +1,132 @@
+import { type ContractArtifact, type IamMembershipRpc, type MemberTarget, type PermissionEntry, type RevokeMemberInput, type Scope } from '@fabrika/auth-core';
+import type { TestCaller, TestScope } from './caller';
+/** A role a test caller holds in one scope value, or globally (`null`). */
+export interface TestMembership {
+    readonly role: string;
+    readonly scope: TestScope | null;
+}
+export interface DirectoryCallers {
+    /**
+     * The caller a membership request's credential (its token or `px_` key) belongs to, as IAM verifies it for `app`:
+     * none for a credential of another application or an expired token.
+     */
+    byCredential(app: string, credential: string): TestCaller | undefined;
+    /** The job a link operation's credential (its workload key or token) belongs to, as IAM resolves it for `app`. */
+    jobByCredential(app: string, credential: string): KitJobCaller | undefined;
+    /** Every caller with its role grants. */
+    all(): readonly {
+        readonly caller: TestCaller;
+        readonly memberships: readonly TestMembership[];
+    }[];
+}
+/** A job's principal, as IAM holds it to its declaration: its actions app-wide, and the one link mount it issues. */
+export interface KitJobCaller {
+    readonly id: string;
+    readonly actions: readonly string[];
+    readonly issues: string | null;
+}
+/** A job's workload key (`expiresAt: null`) or a token the kit signed for it. */
+export interface JobCredential {
+    readonly job: KitJobCaller;
+    readonly expiresAt: number | null;
+}
+/** A write `kitMembership` allowed, by the principal that asked; the credential and the delegation grant are left out. */
+export type AskedWrite = {
+    readonly operation: 'createScope';
+    readonly principalId: string;
+    readonly scope: Scope;
+    readonly role: string;
+} | {
+    readonly operation: 'assignMember';
+    readonly principalId: string;
+    readonly scope: Scope;
+    readonly role: string;
+    readonly member: MemberTarget;
+    /** The invitation it answered for an address; `null` for an existing principal. */
+    readonly invitationId: string | null;
+} | {
+    readonly operation: 'revokeMember';
+    readonly principalId: string;
+    readonly scope: Scope;
+    readonly member: RevokeMemberInput['member'];
+} | {
+    readonly operation: 'issueLink';
+    readonly principalId: string;
+    readonly id: string;
+    readonly mount: string;
+    readonly chain: readonly Scope[];
+} | {
+    readonly operation: 'revokeLink';
+    readonly principalId: string;
+    readonly id: string;
+};
+/** An invitation its addressee accepted: the role it gave, in its scope, to the invited address. */
+export interface AcceptedInvitation {
+    readonly scope: Scope;
+    readonly role: string;
+    readonly email: string;
+}
+export interface KitMembership {
+    readonly rpc: IamMembershipRpc;
+    /** Every write it allowed, in order. */
+    readonly asked: readonly AskedWrite[];
+    /** The permissions IAM signs for `caller` now: the test's grants, with the roles this stand-in assigned or revoked. */
+    permsOf(caller: TestCaller): readonly PermissionEntry[];
+    /**
+     * Closes the open invitation `invitationId` as accepted, as IAM's onboarding does, and answers what it gives. With
+     * `recipient`, that person holds the role from now on; without one the kit makes the new person who holds it. As IAM,
+     * it refuses an external recipient of a role not declared external (`not_eligible`) and an invitation whose inviter
+     * could no longer give the role (`not_allowed`), and then leaves the invitation open.
+     */
+    accept(invitationId: string, recipient?: TestCaller): AcceptedInvitation;
+    /** An open invitation of `role` in `scope` to `email`, as an earlier request opened it; answers its id. */
+    seedInvitation(scope: Scope, role: string, email: string): string;
+    /** A share link of `mount` bound to `chain`, as `issuer` issued it in an earlier request; answers its id. */
+    seedLink(issuer: string, mount: string, chain: readonly Scope[]): string;
+    /** The link a key it issued is bound to, as IAM resolves a link key; `undefined` for any other key and a revoked link. */
+    linkOfKey(key: string): IssuedLinkKey | undefined;
+    /** The roles `caller` holds now: the test's grants, with the ones this stand-in assigned or revoked. */
+    membershipsOf(caller: TestCaller): readonly TestMembership[];
+    /** Every invitation it opened, the seeded ones included, in the order they were first opened. */
+    invitations(): readonly SentInvitation[];
+}
+/** A share link the stand-in issued, as its key resolves. */
+export interface IssuedLinkKey {
+    readonly id: string;
+    readonly mount: string;
+    readonly chain: readonly Scope[];
+}
+/** The invitation e-mail IAM would have sent: to whom, for which role in which scope, and where it stands now. */
+export interface SentInvitation {
+    readonly id: string;
+    readonly email: string;
+    readonly role: string;
+    readonly scope: Scope;
+    readonly expiresAt: number;
+    /** When it was last sent, in seconds: when it was opened, or its latest resend. */
+    readonly sentAt: number;
+    readonly status: 'open' | 'accepted' | 'cancelled' | 'expired';
+}
+/**
+ * The addresses the organization names, as IAM's configuration does (its human e-mails, its e-mail domains): IAM never
+ * invites one to an external role (`internal_mailbox`).
+ */
+export interface OrganizationMailboxes {
+    readonly emails: readonly string[];
+    readonly domains: readonly string[];
+}
+/** A token the kit's IAM signed, for the caller it was minted for, until its `exp`. */
+export interface MintedToken {
+    readonly caller: TestCaller;
+    readonly expiresAt: number;
+}
+/**
+ * The kit's callers as IAM resolves a membership request's credential for `app`: a `px_` key the kit issued, or a token
+ * it signed that has not expired; nothing for another application.
+ */
+export declare function credentialCallers(app: string, keys: ReadonlyMap<string, TestCaller>, tokens: ReadonlyMap<string, MintedToken>, memberships: () => ReturnType<DirectoryCallers['all']>, jobs?: ReadonlyMap<string, JobCredential>): DirectoryCallers;
+/**
+ * The directory of the kit's callers, and every write checked against the caller's grants as IAM checks it.
+ * `organization` names the mailboxes IAM's configuration would; by default none.
+ */
+export declare function kitMembership(artifact: ContractArtifact, callers: DirectoryCallers, organization?: OrganizationMailboxes): KitMembership;

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

@@ -0,0 +1,113 @@
+import { type Tables } from '@fabrika/db';
+import { type TestDatabase } from '@fabrika/db/testing';
+import { type AnyContract } from '../contract/define';
+/** Which of the two seeded rows a request names: the caller's own, or the one in the scope it holds nothing in. */
+export type IsolationRow = 'own' | 'other';
+/** A child row addressed through the caller's own parent with the other row's key: a key from another scope. */
+export type ChildIsolationRow = IsolationRow | 'crossed';
+export interface IsolationOutcome {
+    /** 200 when the operation ran, otherwise the status the caller got. */
+    readonly status: number;
+}
+export interface ReadOutcome extends IsolationOutcome {
+    /** The columns the row came back with. */
+    readonly columns: readonly string[];
+}
+export interface ListOutcome extends IsolationOutcome {
+    /** Which seeded rows the list reached. */
+    readonly rows: readonly IsolationRow[];
+}
+export interface CountOutcome extends IsolationOutcome {
+    readonly count: string;
+}
+export interface AppCountOutcome extends IsolationOutcome {
+    /** How many more rows the count answered after the seed than before it. */
+    readonly counted: number;
+}
+export interface MisuseOutcome extends IsolationOutcome {
+    /** Whether the data layer refused the read capability (`CapabilityError`). */
+    readonly refused: boolean;
+}
+export interface PolicyIsolationKit {
+    readonly table: string;
+    /** The dimension the caller's grants are scoped by. */
+    readonly dimension: string;
+    get(row: ChildIsolationRow): Promise<ReadOutcome>;
+    /** Lists through a `Within` of the caller's scope. */
+    list(): Promise<ListOutcome>;
+    /** A child table listed through the parent's `Ref`; the dimension table has no parent. */
+    listByParent(row: IsolationRow): Promise<ListOutcome>;
+    count(): Promise<CountOutcome>;
+    insert(into: IsolationRow): Promise<IsolationOutcome>;
+    update(row: ChildIsolationRow): Promise<IsolationOutcome>;
+    remove(row: ChildIsolationRow): Promise<IsolationOutcome>;
+    /** A `Ref` for the read action handed to update: the data layer must refuse it. */
+    updateWithRead(): Promise<MisuseOutcome>;
+    /** A `Ref` for the read action handed to remove. */
+    removeWithRead(): Promise<MisuseOutcome>;
+    /** Lists from an `app` endpoint of `action`, one of the table's `appRead`, for a global holder: every row. */
+    appList(action: string): Promise<ListOutcome>;
+    /**
+     * Counts from an `app` endpoint of `action`, one of the table's `appCount`, for a global holder, before and after
+     * two rows of two scopes are seeded: `counted` is 2 when the count reaches every row.
+     */
+    appCount(action: string): Promise<AppCountOutcome>;
+    /** Lists from an `app` endpoint of `action`, one of the table's `appCount`: the data layer must refuse it. */
+    appListWithCount(action: string): Promise<MisuseOutcome>;
+    /**
+     * Lists from an `app` endpoint of `action`, one of the table's `appRead`: `leaked` names each answered column that
+     * declares another read action, `missing` each column that declares exactly `action` and was not answered.
+     */
+    appColumns(action: string): Promise<AppColumnsOutcome>;
+    /**
+     * Groups by the key and every column from an `app` endpoint of `action`, one of the table's `appCount`: a group is a
+     * row's values, so the data layer must refuse it.
+     */
+    appGroupWithCount(action: string): Promise<MisuseOutcome>;
+}
+export interface AppColumnsOutcome extends IsolationOutcome {
+    readonly leaked: readonly string[];
+    readonly missing: readonly string[];
+}
+/**
+ * An application table's isolation kit: the rows belong to no scope, so the boundary is the grant. `global` holds the
+ * table's actions as global grants; `scoped` holds the same actions in one value of a dimension only, which the proxy
+ * refuses on an `app` endpoint. Each attempt seeds one fresh row.
+ */
+export interface AppIsolationKit {
+    readonly table: string;
+    get(caller: AppCaller): Promise<ReadOutcome>;
+    /** Lists through the `app` capability; `rows` is `['own']` when the list holds the seeded row. */
+    list(caller: AppCaller): Promise<ListOutcome>;
+    insert(caller: AppCaller): Promise<IsolationOutcome>;
+    update(caller: AppCaller): Promise<IsolationOutcome>;
+    remove(caller: AppCaller): Promise<IsolationOutcome>;
+    /** The capability of the read action handed to update: the data layer must refuse it. */
+    updateWithRead(): Promise<MisuseOutcome>;
+    /** The capability of the read action handed to remove. */
+    removeWithRead(): Promise<MisuseOutcome>;
+    /**
+     * Lists from an `over` endpoint of the table's read action, for a caller who holds it in one scope only: a scoped
+     * site reads every row of an application table by its read action.
+     */
+    scopedList(): Promise<ListOutcome>;
+    /** The same list from an `over` endpoint of another action the table names: the data layer must refuse it. */
+    scopedListWithOther(): Promise<MisuseOutcome>;
+}
+export type AppCaller = 'global' | 'scoped';
+/**
+ * The isolation kit of `table`, an application table of `tables`, over `postgres`, through a probe contract of `app`
+ * endpoints. `contract` gives only the vocabulary. The kit binds a data layer of its own.
+ */
+export declare function appPolicyIsolationKit<C extends AnyContract, DB, P>(contract: C, tables: Tables<DB, P>, table: string, postgres: TestDatabase): AppIsolationKit;
+/**
+ * The policy isolation kit of `table`, a dimension or child table of `tables`, over `postgres`. `contract` gives only the
+ * vocabulary: its actions, dimensions and roles. The kit binds a data layer of its own, so it does not touch the
+ * application's.
+ */
+export declare function policyIsolationKit<C extends AnyContract, DB, P>(contract: C, tables: Tables<DB, P>, table: string, postgres: TestDatabase): PolicyIsolationKit;
+/**
+ * The scope type a `scoped` caller's grants name: the vocabulary's first dimension, or, in a vocabulary without one, a
+ * name IAM never grants in. Either way the grant is not global, which is all the app form looks at.
+ */
+export declare function scopeTypeOf(dimensions: object): string;

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

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

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

@@ -0,0 +1,40 @@
+import { type ContractArtifact } from '@fabrika/auth-core';
+import { type DelegationIssuer, type IamGateway, type TokenCache } from '@fabrika/proxy-core';
+/** What the proxy did with a request: answered it itself, or forwarded it with what only the proxy may set. */
+export type ProxyOutcome = {
+    readonly outcome: 'forward';
+    /**
+     * Every header only the proxy may assert, with the value the decision gave it. A credentialed request that carried
+     * `Authorization` has it replaced by the minted token, so the caller's `px_` key never reaches the application.
+     */
+    readonly asserted: ReadonlyMap<string, string>;
+    /** Whether the request's own `Authorization` reaches the application: only on a webhook row the decision marked to pass it on. */
+    readonly keepsAuthorization: boolean;
+    /** What the application's answer is given for an admitted cross-origin request, over its own headers. */
+    readonly decorate: (headers: Headers) => void;
+} | {
+    readonly outcome: 'answer';
+    readonly response: Response;
+};
+/** What the proxy reads of a request; its headers have already lost every one a client may not assert. */
+export interface ProxiedRequest {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Headers;
+}
+export type TestProxy = (request: ProxiedRequest) => Promise<ProxyOutcome>;
+export interface EndpointProxyOptions {
+    readonly artifact: ContractArtifact;
+    readonly appId: string;
+    readonly host: string;
+    readonly iam: IamGateway;
+    readonly issuer: string;
+    /** Issues the delegation grants of membership and scope-creating endpoints, as IAM does for the proxy. */
+    readonly delegations: DelegationIssuer | null;
+    /** The proxy's token cache, as production keeps one; omitted, every request mints. */
+    readonly cache?: TokenCache;
+    /** The origins the environment lists for the contract's cross-origin endpoints; none when omitted. */
+    readonly crossOrigins?: readonly string[];
+}
+/** The production proxy: the verify service over the contract's endpoint table, asked the way an enforcement point asks it. */
+export declare function endpointProxy(options: EndpointProxyOptions): TestProxy;

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

@@ -0,0 +1,8 @@
+import * as bunTest from 'bun:test';
+/** Captures Bun's test functions process-wide, once; the platform's preload calls it before the application loads. */
+export declare function installTestRunner(): void;
+export declare function describe(name: string, body: () => void): void;
+/** Registers a case that fails unless its body ran at least one `expect`. */
+export declare function test(name: string, body: () => Promise<void>): void;
+export declare function expect<T>(value: T): ReturnType<typeof bunTest.expect<T>>;
+export declare function afterAll(body: () => Promise<void>): void;

package/types/src/testing/sample-file.d.ts

@@ -0,0 +1,5 @@
+/** A file of the first of `types` the kit can write; `name` (a collection or a kind) names it in the error when none is. */
+export declare function sampleFile(name: string, types: readonly string[]): {
+    readonly type: string;
+    readonly bytes: Uint8Array<ArrayBuffer>;
+};

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

@@ -0,0 +1,4 @@
+/** The status the application refused a call with; a failure that is not its answer (no status) is rethrown. */
+export declare function refusalStatus(error: unknown): number;
+/** A call's status: 200 when it resolves, the status the application refused it with otherwise. */
+export declare function statusOf(call: Promise<unknown>): Promise<number>;