@afora/core 0.0.7 → 0.0.9

package/dist/core/entity/types/entity.interface.d.ts

@@ -1,11 +1,14 @@
+import type { TString } from "typebox";
 import type { BlueprintField, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection, JoinedProperties } from "../../blueprint/types/blueprint.interface.js";
 import type { ParseResult } from "../../parse/types/parse.interface.js";
+import type { PropertyClass } from "../../property/property.js";
 import type { AnyRecordPlugin, IRecordPluginCatalog, PluginMembers, PluginSensitiveKey, PluginUniqueKey, WithPluginProperties } from "../../record/types/plugin.interface.js";
 import type { MarkedUniqueKey, RecordChanges, RecordKey, RecordOptions, RecordSettings } from "../../record/types/record.interface.js";
 import type { StandardSchemaV1 } from "../../standard/standard-schema.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { AbstractEntity, EntityUniqueKeys } from "../abstract-entity.js";
 import type { EntityClassBrand, EntityEvents } from "../event.js";
+import type { EntityVersion } from "../version.js";
 /** The keys every entity has, which its blueprint cannot declare. */
 export type EntityIdentityKey = "id" | "createdAt" | "updatedAt" | "deletedAt";
 /**
@@ -15,6 +18,12 @@ export type EntityIdentityKey = "id" | "createdAt" | "updatedAt" | "deletedAt";
 export type IEntityIdentity = {
     readonly [Key in EntityIdentityKey]: BlueprintField;
 };
+/** The identity key a versioned entity adds: `version`, a positive integer. */
+export type IEntityVersion = {
+    readonly version: typeof EntityVersion;
+};
+/** `Identity`, with `version` when `Versioned` is `true`. */
+export type VersionedIdentity<Identity extends IEntityIdentity, Versioned extends boolean> = Versioned extends true ? Identity & IEntityVersion : Identity;
 /** What an entity builder needs: the identity fields, and how to make an id and a timestamp. */
 export interface EntityBuilderSettings<Identity extends IEntityIdentity, Catalogs extends readonly IRecordPluginCatalog[] = []> {
     /** The blueprint of `id`, `createdAt`, `updatedAt` and `deletedAt`. */
@@ -23,6 +32,11 @@ export interface EntityBuilderSettings<Identity extends IEntityIdentity, Catalog
     readonly generateId: () => string;
     /** The current date and time, as the timestamps accept it. */
     readonly now: () => string;
+    /**
+     * The field of `expiresAt`, a date and time, which entities declared with
+     * `expires: { after }` get; without it such a declaration throws.
+     */
+    readonly expiresAt?: ExpiresAtField;
     /**
      * Catalogs of plugins, made by `recordPluginCatalogOf`, that
      * `options.plugins` picks from, as `(ctx) => [ctx.publishable]`.
@@ -45,7 +59,85 @@ export type EntityProperties<Identity extends IEntityIdentity, Properties extend
  */
 export type EntityInput<Identity extends IEntityIdentity, Properties extends IBlueprintCollection> = BlueprintInput<Properties> & Partial<BlueprintInput<Identity>>;
 /** What `entityOf` takes, after the blueprint, to describe its keys. */
-export type EntityOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown, Sensitive extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[]> = RecordOptions<Properties, Change, Unique, Plugins, Context, Sensitive> & EntityEvents;
+export type EntityOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown, Sensitive extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Expires extends EntityExpires<RecordKey<Properties>> | undefined = EntityExpires<RecordKey<Properties>> | undefined> = RecordOptions<Properties, Change, Unique, Plugins, Context, Sensitive> & EntityEvents & EntityStorageOptions<RecordKey<Properties>, Expires>;
+/** How an entity is stored: optimistic concurrency and expiry. */
+export interface EntityStorageOptions<Key extends string = string, Expires extends EntityExpires<Key> | undefined = EntityExpires<Key> | undefined> {
+    /**
+     * Adds a `version` identity key (1 when created) that the `update` of its
+     * repository checks and increments, throwing `RepositoryConcurrencyConflict`
+     * when the stored one differs: optimistic concurrency.
+     */
+    readonly versioned?: boolean;
+    /**
+     * When records of the entity expire, which reads then leave out:
+     * `{ after: { days: 400 } }` from `createdAt`, kept in an `expiresAt`
+     * identity key, or `{ at: "until" }`, the date held by a key of the
+     * blueprint. A record with no date never expires.
+     */
+    readonly expires?: Expires;
+    /**
+     * The version of the stored shape of the entity, 1 when absent. When set,
+     * every write stores it in each row under `SCHEMA_VERSION_KEY`, and reads
+     * bring older rows up to it with `upgrade` before parsing them.
+     */
+    readonly schemaVersion?: number;
+    /**
+     * The steps that bring a stored row from the version before each key up
+     * to that key: `{ 2: (data) => ({ ...data, slug: data.path }) }`. Each
+     * gets the raw stored data, without the version key.
+     */
+    readonly upgrade?: EntityUpgrades;
+    /**
+     * The names the entity had before (its `name` option), so a backfill
+     * (`app.migrate`) moves their rows to the current name, and `start()`
+     * accepts the rename.
+     */
+    readonly previousNames?: readonly string[];
+}
+/** A step of `upgrade`: the stored data of a version, as the next one. */
+export type EntityUpgrade = (data: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+/** The `upgrade` steps of an entity, keyed by the version each one reaches. */
+export interface EntityUpgrades {
+    readonly [version: number]: EntityUpgrade;
+}
+/** A duration, e.g. `{ days: 400 }`. */
+export interface EntityDuration {
+    readonly days?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+}
+/**
+ * `after` a duration from `createdAt` (stored as `expiresAt`), or `at` the
+ * date held by a key of the blueprint, `Key`.
+ */
+export type EntityExpires<Key extends string = string> = {
+    readonly after: EntityDuration;
+} | {
+    readonly at: Key;
+};
+/**
+ * The field `expiresAt` of the entities that expire `after` a duration: a
+ * required date and time, as `createdAt`.
+ */
+export type ExpiresAtField = PropertyClass<TString, string>;
+/** `Identity`, with `expiresAt` when `Expires` is `{ after }`. */
+export type ExpiringIdentity<Identity extends IEntityIdentity, Expires> = Expires extends {
+    readonly after: EntityDuration;
+} ? Identity & {
+    readonly expiresAt: ExpiresAtField;
+} : Identity;
+/** What `entityOf` stores under `EntitySettings`. */
+export interface EntityStorageSettings {
+    readonly versioned: boolean;
+    readonly expires?: EntityExpires;
+    /** Whether `schemaVersion` was declared, so rows carry the version key. */
+    readonly schemaVersioned: boolean;
+    /** `schemaVersion`, 1 when absent. */
+    readonly schemaVersion: number;
+    readonly upgrade: EntityUpgrades;
+    readonly previousNames: readonly string[];
+}
 /**
  * The unique keys of an entity: `id`, those listed in `options.unique`, and
  * those holding a property declared `unique`, as `Slug`.
@@ -86,4 +178,6 @@ export type EntityConstructor<Identity extends IEntityIdentity, Properties exten
  * What `entityBuilderOf` returns: `entityOf`, declaring entities with the
  * identity it was given, whose `options.plugins` picks from `Context`.
  */
-export type EntityBuilder<Identity extends IEntityIdentity, Context = Record<never, never>> = <Properties extends IBlueprintCollection & Partial<Record<EntityIdentityKey, never>>, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = [], const Sensitive extends readonly RecordKey<Properties>[] = []>(blueprint: IBlueprint<Properties, boolean>, options?: EntityOptions<NoInfer<Properties>, Change, Unique, Plugins, Context, Sensitive>) => EntityConstructor<Identity, WithPluginProperties<Properties, Plugins>, Change, readonly (Unique[number] | PluginUniqueKey<Plugins>)[], PluginMembers<Plugins>, Sensitive[number] | PluginSensitiveKey<Plugins>>;
+export type EntityBuilder<Identity extends IEntityIdentity, Context = Record<never, never>> = <Properties extends IBlueprintCollection & Partial<Record<EntityIdentityKey, never>>, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = [], const Sensitive extends readonly RecordKey<Properties>[] = [], const Versioned extends boolean = false, const Expires extends EntityExpires<RecordKey<Properties>> | undefined = undefined>(blueprint: IBlueprint<Properties, boolean>, options?: EntityOptions<NoInfer<Properties>, Change, Unique, Plugins, Context, Sensitive, Expires> & {
+    readonly versioned?: Versioned;
+}) => EntityConstructor<VersionedIdentity<ExpiringIdentity<Identity, Expires>, Versioned>, WithPluginProperties<Properties, Plugins>, Change, readonly (Unique[number] | PluginUniqueKey<Plugins>)[], PluginMembers<Plugins>, Sensitive[number] | PluginSensitiveKey<Plugins>>;

package/dist/core/entity/version.d.ts

@@ -0,0 +1,13 @@
+import { Type } from "typebox";
+declare const EntityVersion_base: import("../../index.js").PropertyClass<Type.TInteger, number>;
+/**
+ * The `version` of a versioned entity: a positive integer, 1 when created,
+ * which each `update` of its repository checks and increments.
+ */
+export declare class EntityVersion extends EntityVersion_base {
+}
+/** The identity key a versioned entity adds after the others. */
+export declare const VersionIdentity: import("../../index.js").IBlueprint<import("../property/types/property-options.interface.js").StoredFields<{
+    version: typeof EntityVersion;
+}>, false>;
+export {};

package/dist/core/event-policy/event-policy.d.ts

@@ -0,0 +1,25 @@
+import type { EventPolicyDescription, EventPolicyFactory, EventPolicyOptions, EventPolicySettings, IEventPolicyCatalog } from "./types/event-policy.interface.js";
+/**
+ * A factory of event policies for the `events` setting of `commandOf`:
+ * `events: publishEvents({ publisher: "realtime", topic: "posts/{id}" })`.
+ * Its options are JSON, checked by `validate` when the policy is made (an
+ * `InvalidEventPolicy` otherwise), so the policy can be written in an
+ * `afora.json` and an application describes it by name and options instead
+ * of `{ kind: "opaque" }`. `handle` gets the events of a call that succeeded,
+ * what a handler policy gets, and the options.
+ */
+export declare function eventPolicyOf<Options extends object = EventPolicyOptions>(settings: EventPolicySettings<Options>): EventPolicyFactory<Options>;
+/**
+ * The name and options of a policy made by `eventPolicyOf`; `undefined` for
+ * any other value, such as a handler written by hand.
+ */
+export declare function eventPolicyDescriptionOf(handler: unknown): EventPolicyDescription | undefined;
+/** The keys of the application `publishers` a policy uses; none for a handler written by hand. @internal */
+export declare function eventPolicyPublishersOf(handler: unknown): readonly string[];
+/**
+ * A catalog of event policy factories, by name: what resolves
+ * `{ "policy": name, "options": {...} }` back to a policy. Throws
+ * `InvalidEventPolicy` for a function that is not a factory made by
+ * `eventPolicyOf` or for two with the same name.
+ */
+export declare function eventPolicyCatalogOf(...policies: readonly EventPolicyFactory<never>[]): IEventPolicyCatalog;

package/dist/core/event-policy/exceptions.d.ts

@@ -0,0 +1,11 @@
+/** `eventPolicyOf`, a policy's options or a catalog got something it cannot use; `details.reason` says what. */
+export declare const InvalidEventPolicy: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/**
+ * An event policy asked for a publisher that neither the application that
+ * bound the command nor the started application declares.
+ */
+export declare const PublisherNotBound: import("../../index.js").DeclaredExceptionClass<{
+    readonly publisher: string;
+}>;

package/dist/core/event-policy/publish.d.ts

@@ -0,0 +1,17 @@
+import type { PublishEventsOptions } from "./types/event-policy.interface.js";
+/**
+ * An event policy that publishes the events of a call to a publisher of the
+ * application, once the call succeeded (and committed):
+ * `events: publishEvents({ publisher: "realtime", topic: "posts/{id}" })`.
+ *
+ * For each event, in order, it runs the event's own handler first (unless
+ * `handle: false`), then publishes `{ name, command, operation, entity }`
+ * to the topic, the entity as JSON with sensitive values masked; the context
+ * and the variables are never published. `events` limits it to some names.
+ * A handler that fails stops the call with `CommandEventFailed`, as with
+ * `"after-commit"`. A publish that fails is logged and skipped
+ * (`onPublishError: "log"`, the default) or fails the call (`"throw"`). A
+ * publisher the application does not declare fails the call, caused by
+ * `PublisherNotBound`.
+ */
+export declare const publishEvents: import("./types/event-policy.interface.js").EventPolicyFactory<PublishEventsOptions>;

package/dist/core/event-policy/publishers.d.ts

@@ -0,0 +1,18 @@
+import type { IEventPublisher } from "./types/event-policy.interface.js";
+/** The publishers of an application, by key. */
+export type Publishers = Readonly<Record<string, IEventPublisher>>;
+/**
+ * Carries the publishers of an application, when it declares any: on the
+ * application itself. @internal
+ */
+export declare const ApplicationPublishersKey: unique symbol;
+/** Gives `command` the publishers of the application that bound it. @internal */
+export declare function bindPublishers(command: object, publishers: Publishers): void;
+/** Whether `value` can publish: an object with a `publish` function. @internal */
+export declare function isEventPublisher(value: unknown): value is IEventPublisher;
+/**
+ * The publisher `name` for a call of `command`: one of the application that
+ * bound the command, else one of the started application. Throws
+ * `PublisherNotBound` when neither declares it. @internal
+ */
+export declare function resolvePublisher(command: object, name: string, source: string): IEventPublisher;

package/dist/core/event-policy/types/event-policy.interface.d.ts

@@ -0,0 +1,72 @@
+import type { CommandEventHandler, CommandEventInfo } from "../../command/types/command.interface.js";
+import type { JsonValue } from "../../json.js";
+import type { Kind } from "../../symbols/kind.js";
+/** The options of an event policy: JSON, so it can live in an `afora.json`. */
+export type EventPolicyOptions = {
+    readonly [key: string]: JsonValue;
+};
+/** What `eventPolicyOf` takes. */
+export interface EventPolicySettings<Options extends object = EventPolicyOptions> {
+    /** The name the policy is known by in a catalog and in `afora.json`. */
+    readonly name: string;
+    /** Why `options` cannot be used, or `undefined` when they can. */
+    readonly validate?: (options: Options) => string | undefined;
+    /** The handler a command awaits with the events of a call that succeeded. */
+    readonly handle: (events: Parameters<CommandEventHandler>[0], info: CommandEventInfo, options: Options) => void | Promise<void>;
+    /** The keys of the application `publishers` the policy uses, so an application checks them when declared. */
+    readonly publishers?: (options: Options) => readonly string[];
+}
+/**
+ * Makes an event policy for the `events` setting of `commandOf`: a
+ * `CommandEventHandler` that remembers its name and options.
+ */
+export type EventPolicyFactory<Options extends object = EventPolicyOptions> = (options?: Options) => CommandEventHandler;
+/** How an event policy made by a factory is described: by name and options. */
+export interface EventPolicyDescription {
+    readonly kind: "policy";
+    readonly name: string;
+    readonly options: EventPolicyOptions;
+}
+/** Event policy factories by name: what resolves `{ "policy": name, "options": {...} }` of an `afora.json`. */
+export interface IEventPolicyCatalog {
+    readonly [Kind]: "event-policy-catalog";
+    readonly policies: Readonly<Record<string, EventPolicyFactory<never>>>;
+    /** Makes the policy `name` with `options`; throws `InvalidEventPolicy` for an unknown name or invalid options. */
+    resolve(name: string, options?: EventPolicyOptions): CommandEventHandler;
+}
+/** An event as a publisher receives it: JSON, the entity masked by its `toJSON`. */
+export interface PublishedEvent {
+    /** The name given to `eventOf`. */
+    readonly name: string;
+    readonly command: string;
+    readonly operation: string;
+    /** The entity as JSON: sensitive values are masked. */
+    readonly entity: JsonValue;
+}
+/**
+ * Where published events go: a WebSocket hub, a queue, a broker. Declared
+ * under a key in `applicationOf({ publishers })`.
+ */
+export interface IEventPublisher {
+    publish(topic: string, event: PublishedEvent): void | Promise<void>;
+}
+/** The options of the `publishEvents` policy. */
+export interface PublishEventsOptions {
+    /** The key of the publisher in `applicationOf({ publishers })`. */
+    readonly publisher: string;
+    /**
+     * The topic of each event. `{event}`, `{command}`, `{operation}` and
+     * `{id}` (the id of the entity) are replaced: `"posts/{id}"`.
+     */
+    readonly topic: string;
+    /** The names of the events to publish; all of them by default. */
+    readonly events?: readonly string[];
+    /** Whether each event runs its own handler first, as `"after-commit"` does. `true` by default. */
+    readonly handle?: boolean;
+    /**
+     * What a failed publish does: `"log"` (default) writes an error to the
+     * logger and goes on, since the call already committed; `"throw"` makes
+     * the call fail with `CommandEventFailed`.
+     */
+    readonly onPublishError?: "log" | "throw";
+}

package/dist/core/output/access.d.ts

@@ -0,0 +1,16 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+import type { AccessDeclaration } from "../use-case/types/access.interface.js";
+import type { OperationCallOptions } from "./types/output.interface.js";
+/** What `command.run` takes: the call options without the caller. */
+type RunOptions = {
+    readonly context?: unknown;
+} | undefined;
+/**
+ * The check of `access` for the operation `id`, made once: given the input
+ * and the options of a call, it throws `Unauthenticated` or `Forbidden`, or
+ * gives the options to run the command with (the context filled from the
+ * caller). Throws `InvalidOutputStage` when `access.context` names a key the
+ * `context` of the operation does not have.
+ */
+export declare function accessGuardOf(id: string, access: AccessDeclaration, context: AnyBlueprint | undefined): (input: unknown, options: OperationCallOptions | undefined) => RunOptions;
+export {};

package/dist/core/output/coerce.d.ts

@@ -0,0 +1,9 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+/**
+ * Text values (a query string, headers, the values of a session) as the
+ * scalar fields of `blueprint` take them: a number or a boolean where the
+ * field is one rather than a string, else as is, so the blueprint rejects
+ * invalid text with its own issue. `undefined` values are left out. For
+ * sinks, which read text from their transport.
+ */
+export declare function coerceTextValues(blueprint: AnyBlueprint, texts: Readonly<Record<string, string | undefined>>): Record<string, unknown>;

package/dist/core/output/exceptions.d.ts

@@ -6,3 +6,19 @@ export declare const InvalidOutputStage: import("../../index.js").DeclaredExcept
 export declare const DuplicateOperation: import("../../index.js").DeclaredExceptionClass<{
     readonly id: string;
 }>;
+/**
+ * An operation that declares its `access` was called without an
+ * authenticated caller: no credentials, or ones that were not accepted. A
+ * 401.
+ */
+export declare const Unauthenticated: import("../../index.js").DeclaredExceptionClass<undefined>;
+/**
+ * The caller is authenticated but may not call the operation: it lacks a
+ * scope the `access` of the operation asks for (`details.reason` is
+ * `"scope"`, with the missing `scopes`), or is not the owner (`"owner"`). A
+ * 403.
+ */
+export declare const Forbidden: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: "scope" | "owner";
+    readonly scopes?: readonly string[];
+}>;

package/dist/core/output/http.d.ts

@@ -0,0 +1,36 @@
+import type { CompileRoutesSettings, HttpOptions, RouteTable } from "./types/http.interface.js";
+import type { OperationDescriptor, StageContext } from "./types/output.interface.js";
+/** The option names of {@link HttpOptions}, for sinks that list their options. */
+export declare const HTTP_OPTION_KEYS: readonly ["basePath", "route", "responses", "requestId", "security", "docs", "debug", "context", "auth"];
+/**
+ * Why the {@link HttpOptions} are not valid, naming them `where.<option>`;
+ * `undefined` when they are. Other keys of `options` are not looked at.
+ */
+export declare function httpOptionsIssue(options: HttpOptions, where: string): string | undefined;
+/**
+ * The routes of `operations`, compiled once, for a sink that serves HTTP on
+ * any server: the sink routes each `method` and `path` to `handle` and sends
+ * the result as is. Everything a request needs is decided here, so a call
+ * only reads, coerces and runs:
+ *
+ * - The input is the JSON body of a `post`, `put` or `patch` and the query
+ *   of a `get` or `delete`, with the keys the route reads elsewhere over it:
+ *   `{name}` segments of the path, and the query keys, headers and cookies
+ *   the use case route declares. Text is coerced to the numbers and booleans
+ *   the input takes; the operation validates it (a 400 problem with `issues`).
+ * - The context comes from `context.headers` (coerced) and
+ *   `context.variables` (as is); a missing one leaves the key out.
+ * - An operation with an `access` other than `public` asks
+ *   `settings.authenticator` who calls; without one, or without credentials,
+ *   it is a 401.
+ * - Success is the route status with the response as JSON (sensitive values
+ *   masked by `toJSON`), or no body for `204`, plus the `responses` headers.
+ *   Errors are `application/problem+json`, with the status of `statusOf`
+ *   (the output `statuses` first). `requestId` puts the request id on every
+ *   result, `notFound` and `failure` included.
+ * - `docs.path` serves the `openapi` document of the same operations.
+ *
+ * Throws `InvalidOutputStage` (source `settings.source`) as `operationRoutes`
+ * does, and when `docs.path` is taken by a `get` route.
+ */
+export declare function compileRoutes(operations: readonly OperationDescriptor[], options: HttpOptions, context: StageContext, settings: CompileRoutesSettings): RouteTable;

package/dist/core/output/openapi-sink.d.ts

@@ -1,10 +1,96 @@
 import type { OpenAPISchema } from "../openapi/types/openapi.interface.js";
+import type { RouteCookie } from "../use-case/types/route.interface.js";
 import type { OperationDescriptor } from "./types/output.interface.js";
 declare const METHODS: readonly ["get", "post", "put", "patch", "delete"];
 /** An HTTP method an operation can be routed to. */
 export type OpenAPIMethod = (typeof METHODS)[number];
+/** The status of a successful call of a route; `204` has no body. */
+export type RouteStatus = 200 | 201 | 202 | 204;
+/**
+ * A security scheme of the document (`components.securitySchemes`), as
+ * OpenAPI 3.1 writes it.
+ */
+export type OpenAPISecurityScheme = {
+    readonly type: "http";
+    /** `"bearer"`, `"basic"`... */
+    readonly scheme: string;
+    readonly bearerFormat?: string;
+    readonly description?: string;
+} | {
+    readonly type: "apiKey";
+    readonly name: string;
+    readonly in: "header" | "query" | "cookie";
+    readonly description?: string;
+} | {
+    readonly type: "oauth2";
+    readonly flows: {
+        readonly [flow: string]: unknown;
+    };
+    readonly description?: string;
+} | {
+    readonly type: "openIdConnect";
+    readonly openIdConnectUrl: string;
+    readonly description?: string;
+} | {
+    readonly type: "mutualTLS";
+    readonly description?: string;
+};
+/** The scheme an operation needs, and its scopes (none by default). */
+export interface SecurityRequirement {
+    readonly scheme: string;
+    readonly scopes?: readonly string[];
+}
+/**
+ * The options that route operations: shared by the `openapi` sink and the
+ * sinks that serve HTTP, so the served routes and the document agree.
+ */
+export interface RouteOptions {
+    /** Prefix of every path, e.g. `"/api"`. Empty by default. */
+    readonly basePath?: string;
+    /**
+     * Method, path and success status by operation id, e.g.
+     * `{ "Entries.get": { method: "get", path: "/entries/{slug}" } }`. A
+     * `{name}` segment of the path fills the scalar input key `name`.
+     */
+    readonly route?: {
+        readonly [operationId: string]: {
+            readonly method?: OpenAPIMethod;
+            readonly path?: string;
+            /** `200` by default. */
+            readonly status?: RouteStatus;
+        };
+    };
+    /** Static headers of the successful responses, by operation id. */
+    readonly responses?: {
+        readonly [operationId: string]: {
+            readonly headers?: {
+                readonly [name: string]: string;
+            };
+        };
+    };
+    /**
+     * Every response carries a request id: the one the request sent in this
+     * header, else a new UUID. `true` is `"x-request-id"`.
+     */
+    readonly requestId?: true | string;
+    /**
+     * Security schemes and the one each operation needs, for the document
+     * (`components.securitySchemes` and `security`). `default` applies to
+     * every operation not in `operations`; `false` there marks one public.
+     * Sinks that serve HTTP do not enforce it.
+     */
+    readonly security?: {
+        readonly schemes: {
+            readonly [name: string]: OpenAPISecurityScheme;
+        };
+        readonly operations?: {
+            readonly [operationId: string]: SecurityRequirement | false;
+        };
+        readonly default?: SecurityRequirement;
+    };
+}
 /** The options of the `openapi` sink. */
-export interface OpenAPISinkOptions {
+export interface OpenAPISinkOptions extends RouteOptions {
     readonly info: {
         readonly title: string;
         readonly version: string;
@@ -14,21 +100,15 @@ export interface OpenAPISinkOptions {
         readonly url: string;
         readonly description?: string;
     }[];
-    /** Prefix of every path, e.g. `"/api"`. Empty by default. */
-    readonly basePath?: string;
-    /** Method and path by operation id, e.g. `{ "Users.login": { path: "/session" } }`. */
-    readonly route?: {
-        readonly [operationId: string]: {
-            readonly method?: OpenAPIMethod;
-            readonly path?: string;
-        };
-    };
 }
 /** An OpenAPI 3.1 document. */
 export interface OpenAPIDocument {
     readonly openapi: "3.1.0";
     readonly info: OpenAPISinkOptions["info"];
     readonly servers?: OpenAPISinkOptions["servers"];
+    readonly security?: readonly {
+        readonly [scheme: string]: string[];
+    }[];
     readonly paths: {
         readonly [path: string]: Record<string, unknown>;
     };
@@ -36,30 +116,65 @@ export interface OpenAPIDocument {
         readonly schemas: {
             readonly [name: string]: OpenAPISchema;
         };
+        readonly securitySchemes?: {
+            readonly [name: string]: OpenAPISecurityScheme;
+        };
     };
 }
-/** The options that route operations: shared by the sinks that serve HTTP. */
-export interface RouteOptions {
-    readonly basePath?: string;
-    readonly route?: OpenAPISinkOptions["route"];
-}
-/** Where an operation is served. */
+/** The option names of {@link RouteOptions}, for sinks that list their options. */
+export declare const ROUTE_OPTION_KEYS: readonly ["basePath", "route", "responses", "requestId", "security"];
+/**
+ * Why the {@link RouteOptions} (`basePath`, `route`, `responses`,
+ * `requestId`, `security`) are not valid, naming them `where.<option>`;
+ * `undefined` when they are. Other keys of `options` are not looked at.
+ */
+export declare function routeOptionsIssue(options: RouteOptions, where: string): string | undefined;
+/**
+ * The header that carries the request id with these options (`"x-request-id"`
+ * for `requestId: true`), or `undefined` without `requestId`.
+ */
+export declare function requestIdHeaderOf(options: RouteOptions): string | undefined;
+/** Where an operation is served, and how it answers. */
 export interface OperationRoute {
     readonly method: OpenAPIMethod;
-    /** `basePath` included. */
+    /** `basePath` included, parameters as `{name}`. */
     readonly path: string;
+    /** The input keys the `{name}` segments of `path` fill, in order. */
+    readonly parameters: readonly string[];
+    /** The status of a success: `200` unless `route` says otherwise. */
+    readonly status: RouteStatus;
+    /** The static headers of a success, from `responses`. */
+    readonly headers: {
+        readonly [name: string]: string;
+    };
+    /**
+     * Whether the input keys with no other place are a JSON body (`post`,
+     * `put`, `patch`); otherwise they are read from the query.
+     */
+    readonly body: boolean;
+    /** The input keys the use case route reads from the query, whatever the method. */
+    readonly query: readonly string[];
+    /** The input keys read from request headers, with the header of each (lower case). */
+    readonly requestHeaders: {
+        readonly [inputKey: string]: string;
+    };
+    /** The input keys read from cookies, with the cookie of each. */
+    readonly cookies: {
+        readonly [inputKey: string]: string;
+    };
+    /** The response keys sent as cookies instead of in the body, with the cookie of each. */
+    readonly setCookies: {
+        readonly [responseKey: string]: RouteCookie;
+    };
 }
 /**
- * Why `basePath` and `route` are not valid routing options, naming them
- * `where.basePath` and `where.route`; `undefined` when they are.
- */
-export declare function routeOptionsIssue(options: RouteOptions, where: string): string | undefined;
-/**
- * The route of every operation, by id: `POST {basePath}/{kebab(command)}/{kebab(operation)}`,
- * changed per operation id with `route`. Throws `InvalidOutputStage` (with
- * `source`) when `route` names an unknown operation or two operations share a
- * method and path. The routing of the `openapi` sink and of the sinks that
- * serve HTTP.
+ * The route of every operation, by id: `POST {basePath}/{kebab(command)}/{kebab(operation)}`
+ * with `200`, changed by the route the use case declares (`operation.route`)
+ * and, over it, per operation id with `route` and `responses`. Throws
+ * `InvalidOutputStage` (with `source`) when `route`, `responses` or
+ * `security.operations` name an unknown operation, a path parameter is not a
+ * scalar key of the input, or two operations share a method and path. The
+ * routing of the `openapi` sink and of the sinks that serve HTTP.
  */
 export declare function operationRoutes(operations: readonly OperationDescriptor[], options: RouteOptions, source?: string): ReadonlyMap<string, OperationRoute>;
 /**
@@ -67,17 +182,23 @@ export declare function operationRoutes(operations: readonly OperationDescriptor
  *
  * Routes: `POST {basePath}/{kebab(command)}/{kebab(operation)}`, changed per
  * operation id with `route`; two operations on one method and path throw
- * `InvalidOutputStage`. The `operationId` is the id with its dot as an
- * underscore (`Users.register` -> `Users_register`), unique or the build
- * throws. `get` and `delete` send the input as query parameters, which needs
- * every input field to be a scalar property. Responses: `200` with the
- * response schema, `400` and `500` always, and the status of each declared
- * error (`statusOf`: `statuses` of the output, else 422). Operations carry no
- * repository dependencies, so `404` and `409` appear only when an error that
- * maps to them is declared. Records and entities reachable from inputs and
- * responses are named by class name in `components.schemas`, beside `Problem`
- * (RFC 9457). The `context` of an operation is transport-specific and not
- * part of the document; sinks that serve HTTP map it (headers, middleware).
+ * `InvalidOutputStage`. A `{name}` segment of a path is a required path
+ * parameter, the input key `name` (a scalar), left out of the body or query.
+ * The `operationId` is the id with its dot as an underscore (`Users.register`
+ * -> `Users_register`), unique or the build throws. `get` and `delete` send
+ * the input as query parameters, which needs every input field to be a
+ * scalar property. Responses: the `route` status (`200` by default; `204`
+ * without content) with the response schema and the `responses` headers,
+ * `400` and `500` always, and the status of each declared error (`statusOf`:
+ * `statuses` of the output, else 422); `requestId` adds its header to all of
+ * them. Operations carry no repository dependencies, so `404` and `409`
+ * appear only when an error that maps to them is declared. Records and
+ * entities reachable from inputs and responses are named by class name in
+ * `components.schemas`, beside `Problem` (RFC 9457). `security` gives
+ * `components.securitySchemes`, the document `security` (`default`) and the
+ * `security` of each operation. The `context` of an operation is
+ * transport-specific and not part of the document; sinks that serve HTTP map
+ * it (headers, middleware).
  */
-export declare const openapi: import("./types/output.interface.js").SinkFactory<OpenAPIDocument, OpenAPISinkOptions>;
+export declare const openapi: import("./types/output.interface.js").SinkFactory<OpenAPIDocument, OpenAPISinkOptions, never>;
 export {};