@formancy/data-server 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,733 @@
+import { DatabaseAdapter, DatabaseKind, DiscoveryScope, DriftReport, FormBindings, FormPolicy, GenerationNote, GenerationRequest, LookupAdapter, MetadataSnapshot, PresentationConflict, PresentationOverrides, ReassignedKey, RecordAdapter } from "@formancy/data-core";
+import { FastifyBaseLogger, FastifyInstance, FastifyRequest } from "fastify";
+import { FormSchema } from "@formancy/spec";
+import "jose";
+//#region src/config-store.d.ts
+type PublishOutcome = {
+  ok: true;
+  version: number;
+} |
+/** Somebody published first. `current` is what they published, so the caller can rebase and retry. */
+{
+  ok: false;
+  reason: 'conflict';
+  current: number | null;
+};
+/**
+ * Where published form bundles live: outside every customer's business tables.
+ *
+ * A port because a second implementation is already planned — a shared store
+ * with compare-and-swap for more than one server instance (plan section 5) —
+ * and `config-store.test.ts` is written against this interface so that store
+ * can run the same cases. Today there is one, on a directory.
+ *
+ * Versions are immutable once published, as formancy's are
+ * (formancy.ai 0025): publishing never edits, it adds the next number.
+ */
+interface ConfigurationStore {
+  /** The newest published version, or `null` before the first. */
+  latest(id: string): Promise<number | null>;
+  /** Every published version, ascending; `[]` for an id never published (0030). */
+  versions(id: string): Promise<number[]>;
+  /**
+   * One published version, or `undefined` if it does not exist. A version
+   * that exists and does not parse -- edited by hand, or damaged -- throws
+   * `UnparsableVersionError`, so a caller can tell it from a read that
+   * failed.
+   */
+  read(id: string, version: number): Promise<unknown>;
+  /**
+   * Publish the next version, only if the newest is still `expectedBase`.
+   * Two administrators publishing from the same base: one wins, the other is
+   * told, and nothing is overwritten.
+   */
+  publish(id: string, expectedBase: number | null, value: unknown): Promise<PublishOutcome>;
+  /** Every id with at least one version, in codepoint order. */
+  list(): Promise<string[]>;
+}
+/** What `read` throws for a version that exists and does not parse. Its message names the file. */
+export declare class UnparsableVersionError extends Error {
+  name: string;
+}
+/**
+ * A configuration store on a directory — a persistent volume in a container.
+ *
+ * Layout: `<root>/<id>/<version>.json`, pretty-printed, one file per version,
+ * so an export is a copy of the directory and a review is a diff.
+ *
+ * **Compare-and-swap without a lock.** A version is written to a temporary file,
+ * flushed, and then hard-linked to its final name. `link` fails if the name
+ * exists, atomically, so of two writers that both read version 3 as the newest,
+ * exactly one creates 4.json and the other gets a conflict. Nobody ever sees a
+ * half-written version, because the final name only appears once the bytes are
+ * on disk. A crash leaves a temporary file that nothing reads.
+ *
+ * On a local filesystem — ext4, xfs, NTFS — `link` is atomic. Over NFS it is
+ * atomic on the server but the error a client sees after a retransmission can
+ * be wrong, which is why the plan limits this store to a single-instance pilot.
+ */
+export declare function createFileConfigurationStore(root: string): ConfigurationStore;
+//#endregion
+//#region src/secrets.d.ts
+/**
+ * Where a secret comes from: injected, so a test can supply an environment and
+ * a file system without touching the process's own.
+ */
+interface SecretSource {
+  env: Readonly<Record<string, string | undefined>>;
+  readFile(path: string): Promise<string>;
+}
+/**
+ * The value behind a secret reference.
+ *
+ * Configuration names a secret, never contains one (plan section 3: "a
+ * server-side secret reference"). Two forms: `env:NAME`, read from the
+ * environment, and `file:/absolute/path`, read from a file — which is how
+ * Docker and Kubernetes hand secrets to a container.
+ *
+ * **No error message ever contains the reference's value**, only its form. The
+ * commonest mistake is pasting the secret itself where its reference belongs,
+ * and an error that echoed the input would print the secret into a log.
+ */
+export declare function resolveSecret(reference: string, source?: SecretSource): Promise<string>;
+//#endregion
+//#region src/connections.d.ts
+/**
+ * One database the deployment allows forms to bind to, as the operator wrote
+ * it. The password is a secret reference, never a password (0014): this file is
+ * reviewable configuration, and a secret in it would be a secret in review.
+ */
+interface ConnectionConfig {
+  /** The name forms use. Lower case, as configuration ids are (0013). */
+  id: string;
+  kind: DatabaseKind;
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  /** `env:NAME` or `file:/absolute/path`. */
+  password: string;
+  /** The schemas an administrator approved. Discovery reads nothing outside them. */
+  schemas: string[];
+  /**
+   * TLS. On by default, and certificate checking with it: a deployment that
+   * turns either off says so here, in a file somebody reviews.
+   */
+  tls?: {
+    enabled?: boolean;
+    trustServerCertificate?: boolean;
+  };
+}
+/** What the server holds for one open connection: the three ports. */
+interface OpenConnection {
+  adapter: DatabaseAdapter;
+  lookups: LookupAdapter;
+  records: RecordAdapter;
+}
+/**
+ * Opens a connection of one kind. Supplied by the composition root, which
+ * imports the drivers; nothing here does, so the registry is tested with a
+ * fake and the server's core depends on no driver.
+ */
+type ConnectionFactory = (config: ConnectionConfig, password: string) => Promise<OpenConnection>;
+/**
+ * The allowlist, checked: every problem at once, so an operator fixes the file
+ * in one pass rather than one restart per mistake.
+ */
+export declare function parseConnections(document: unknown): {
+  ok: true;
+  connections: ConnectionConfig[];
+} | {
+  ok: false;
+  problems: string[];
+};
+interface ConnectionRegistry {
+  /** The ids a form may bind to. */
+  ids(): string[];
+  /** The approved scope of one connection, or `undefined` if the deployment does not allow it. */
+  scope(id: string): DiscoveryScope | undefined;
+  /**
+   * The connection's ports, opened on first use and shared after. A connection
+   * that failed to open is tried again on the next call, not cached as broken:
+   * a database restarting is not a reason to restart the server.
+   */
+  open(id: string): Promise<OpenConnection | undefined>;
+  /** Closes every open connection. Safe to call twice. */
+  close(): Promise<void>;
+}
+/**
+ * The allowlisted connections, opened lazily through the composition root's
+ * factories. A form names a connection; this is the only place that name
+ * becomes a database, so a form cannot reach a database the operator did not
+ * list.
+ */
+export declare function createConnectionRegistry(connections: readonly ConnectionConfig[], factories: Readonly<Partial<Record<DatabaseKind, ConnectionFactory>>>, secrets?: SecretSource): ConnectionRegistry;
+//#endregion
+//#region src/identity-keys.d.ts
+/**
+ * The keys a host identity token is verified with (0014, 0059): one shared
+ * secret, one public key, or a JSON Web Key Set read from a file, each of its
+ * keys selected by the kid a token names.
+ *
+ * A `KeySet` is opaque. Its constructor refuses every caller but the
+ * builders below, which check what they are given, so a set the verifier
+ * meets is always one that `readKeySet`, `KeySet.fromSecret` or
+ * `KeySet.fromPem` made: one algorithm, public keys or long secrets, every kid
+ * distinct.
+ *
+ * Nothing a sentence here says comes from the file. JSON.parse's own message
+ * quotes the text around the error, and the text may be a secret, so a file
+ * that does not parse gets one fixed sentence; every other sentence names a
+ * key by its kid, when that is in the alphabet below and could not be a
+ * secret, or by its place in the file, and names a member, never its value.
+ *
+ * The class, its prototype and every set are frozen, and a set is verified
+ * with only through `verifyWithKeySet`, which index.ts does not export: code
+ * that reaches the class can replace none of its methods, and no caller can
+ * verify under a set with looser options than identity.ts passes.
+ */
+declare const KEY_SET_ALGORITHMS: readonly ["RS256", "ES256", "EdDSA", "HS256"];
+type KeySetAlgorithm = (typeof KEY_SET_ALGORITHMS)[number];
+/** The member that left a key out of force. Never its value. */
+type LeftOutBecause = 'kty' | 'crv' | 'use' | 'key_ops' | 'alg';
+/** A key the file holds that cannot verify the pinned algorithm: by its kid, or by its place in the file (`#3`). */
+interface LeftOutKey {
+  readonly key: string;
+  readonly because: LeftOutBecause;
+}
+/** What changed between two sets, by kid; `replaced` is a kid whose key is not the same key. */
+interface KeySetChange {
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+  readonly replaced: readonly string[];
+}
+/** A sentence saying why a set was refused. It holds no text of the file, so it may be logged. */
+export declare class KeySetRefusal extends Error {
+  readonly name = "KeySetRefusal";
+}
+export declare class KeySet {
+  #private;
+  private constructor();
+  /**
+   * A JSON Web Key Set, `{"keys":[…]}`, read for one algorithm. Throws a
+   * `KeySetRefusal` for an algorithm not one of the four, a file that does
+   * not parse, an entry that is not an object, any key holding a private
+   * member, a key in force without a kid in the alphabet, with another's kid
+   * or with one that could be a secret, one that does not import, an RSA key
+   * under 2048 bits or with an exponent under 65537 or even, an Ed25519 point
+   * of small order, a secret under 32 bytes, and a file with no key in force.
+   * A key that cannot verify the algorithm is left out and named.
+   */
+  static read(text: string, algorithm: KeySetAlgorithm): KeySet;
+  /** `FORMANCY_DATA_IDENTITY_SECRET`'s key: HS256 over the secret's UTF-8 bytes, at least 32 of them. */
+  static fromSecret(secret: string): KeySet;
+  /** `FORMANCY_DATA_IDENTITY_PUBLIC_KEY_FILE`'s key: an SPKI PEM, imported by jose as it always was, for RS256, ES256 or EdDSA and never HS256. */
+  static fromPem(pem: string, algorithm: string): Promise<KeySet>;
+  /** Whether `value` is a set the builders made. A brand check, so neither a look-alike nor an object made from the prototype passes. */
+  static is(value: unknown): value is KeySet;
+  get algorithm(): KeySetAlgorithm;
+  /** The kids in force, in file order; none for a one-key setting, which ignores kids. */
+  get kids(): readonly string[];
+  get leftOut(): readonly LeftOutKey[];
+  /** The type of each key in force, `public` or `secret`: what a test can ask of a key without being handed it. */
+  get keyTypes(): readonly string[];
+  /** What `next` adds, removes and replaces of this set's kids. A key is replaced when its kid stays and its key does not. */
+  compare(next: KeySet): KeySetChange;
+  /**
+   * A one-key setting's key as a key set file holding it under `kid`: what
+   * `identity-keys-cli.mjs convert` writes. The secret's key is the base64url
+   * of the bytes this set verifies with, not the secret's text, which is also
+   * valid base64url and another key (M2). Read back before it is returned.
+   * This is key material; nothing logs it.
+   */
+  document(kid: string): Promise<string>;
+}
+/** The one function that checks a key set file's text; see `KeySet.read`. */
+export declare function readKeySet(text: string, algorithm: KeySetAlgorithm): KeySet;
+//#endregion
+//#region src/identity.d.ts
+/**
+ * Who is asking, as the host application vouched for it.
+ *
+ * Built only from a token whose signature verified. Nothing in a request body,
+ * query or header other than that token contributes to it — a tenant named in a
+ * request is a claim by the browser, and the browser is the party policy exists
+ * to constrain.
+ */
+interface HostIdentity {
+  actor: {
+    id: string;
+    roles: string[];
+  };
+  attributes: Record<string, string>;
+}
+type IdentityOutcome = {
+  ok: true;
+  identity: HostIdentity;
+} | {
+  ok: false;
+  reason: string;
+};
+type IdentityVerifier = (token: string) => Promise<IdentityOutcome>;
+/** A setting that names one key: a shared secret, or a public key's PEM. Its tokens' kid is ignored. */
+type OneKey = {
+  kind: 'secret';
+  secret: string;
+} | {
+  kind: 'public-key';
+  pem: string;
+  algorithm: 'RS256' | 'ES256' | 'EdDSA';
+};
+interface IdentityOptions {
+  /**
+   * How tokens are signed. A shared secret (HS256), a public key the host
+   * signs against with its private one, or a key set read from a file and
+   * read again on SIGHUP, whose `keys` is asked on every token. Never a URL,
+   * and never a key or a URL a token names: an outbound request from inside
+   * a customer's network, and a key the token chooses (0014, 0059).
+   */
+  key: OneKey | {
+    kind: 'key-set';
+    keys: () => KeySet;
+  };
+  issuer: string;
+  audience: string;
+  /** Attribute name to claim name, e.g. `{ tenant: 'tid' }`. Only these claims are read. */
+  attributes: Readonly<Record<string, string>>;
+  /** The claim holding the actor's roles. Default `roles`. */
+  rolesClaim?: string;
+  /** Seconds of clock skew tolerated on `exp` and `nbf`. Default 30. */
+  clockToleranceSeconds?: number;
+}
+/**
+ * A verifier for the host application's tokens, built once at startup.
+ *
+ * Fails at construction on a configuration that would accept forgeries — a
+ * short secret, a key that does not parse, a key set no builder checked —
+ * rather than on the first request. The algorithm is pinned per key kind, and
+ * for a whole key set, so a token cannot choose `none` or swap an asymmetric
+ * key for a shared one.
+ *
+ * A key set's `keys` is asked once per token, so a set read again replaces
+ * the one in force between tokens, and a verification that has begun
+ * finishes on the set it began with.
+ */
+export declare function createIdentityVerifier(options: IdentityOptions): Promise<IdentityVerifier>;
+//#endregion
+//#region src/audit.d.ts
+/** What every event says, on either plane. */
+interface AuditEventBase {
+  at: string;
+  /**
+   * The verified host actor, or `null` for a request refused before its token
+   * was read: no token or a token refused, over the rate limit, or a body
+   * Fastify refused (400, 413, 415, a client gone mid-body), whatever token it
+   * carried, since each plane authenticates after the body is read (0033).
+   */
+  actor: string | null;
+  status: number;
+  /** `ok` below 400; otherwise the stable code the response carried, or `http-NNN` when it carried none. */
+  outcome: string;
+}
+type RuntimeOperation = 'form-list' | 'form' | 'read' | 'list' | 'create' | 'update' | 'delete' | 'lookup-query' | 'lookup-resolve';
+type AdminOperation = 'connection-list' | 'connection-test' | 'discovery' | 'proposal' | 'publish' | 'version-list' | 'version-latest' | 'version-read' | 'drift' | 'regeneration' | 'restore' | 'import';
+/**
+ * One operational audit event of the runtime plane: who asked for what,
+ * against which published version, and how it ended (plan section 12, 0023).
+ *
+ * Never a value. Not an answer, not a field, not a record: an audit log that
+ * copied business data would be a second copy of the customer's database with
+ * none of its permissions. The record is named by a keyed hash, or not at all.
+ */
+interface RuntimeAuditEvent extends AuditEventBase {
+  plane: 'runtime';
+  operation: RuntimeOperation;
+  /** The form addressed, when it has a form id's shape (`auditedForm`); otherwise `null`. */
+  form: string | null;
+  /** The published version the request was served from, when it got that far. */
+  formVersion: number | null;
+  /**
+   * A keyed hash of the record token, or `null`. Keyed, because a record token
+   * spells its key and a key is often small — customer 7 — so a plain hash
+   * could be reversed by trying every number. Without an audit key the server
+   * cannot make one that resists that, so it records nothing rather than a
+   * reference that only looks redacted.
+   */
+  record: string | null;
+}
+/**
+ * One operational audit event of the administrator's plane (0033): who
+ * connected, discovered, proposed, published, read, compared, regenerated,
+ * restored or imported, against which connection and which version, and how
+ * it ended.
+ *
+ * Names and numbers only. Never the bundle, the policy or a role it names,
+ * a snapshot, a generation request, a drift report or any message.
+ */
+interface AdminAuditEvent extends AuditEventBase {
+  plane: 'admin';
+  operation: AdminOperation;
+  /** An allowlisted connection's name, never an address (0019): one the allowlist does not know is `null`. */
+  connection: string | null;
+  /** The form addressed, when it has a form id's shape (`auditedForm`); otherwise `null`. */
+  form: string | null;
+  /** The version read, compared, regenerated from, or written. */
+  formVersion: number | null;
+  /** Publish, restore and import: the base the administrator said they edited, or saw newest. */
+  expectedBase: number | null;
+  /** Restore only: the version the new one copies, which nothing on disk records. */
+  restoredFrom: number | null;
+}
+/** Both planes, told apart by `plane`. A typed sink narrows on it before reading a plane's own fields. */
+type AuditEvent = RuntimeAuditEvent | AdminAuditEvent;
+/**
+ * Where events go. A port: the default writes a structured log line; a
+ * deployment that needs a durable trail supplies its own.
+ *
+ * A sink that throws does not fail the request — by the time the event exists,
+ * the write it describes has committed or not, and refusing to answer would
+ * only hide which. The failure is logged instead. That is the limitation 0023
+ * writes down: this is an operational trail, not evidence.
+ */
+type AuditSink = (event: AuditEvent) => void | Promise<void>;
+/** Events as structured log lines, one per request. */
+export declare function logAuditSink(log: FastifyBaseLogger): AuditSink;
+/** The keyed hash a record is named by: the first 32 hex characters of HMAC-SHA-256. */
+export declare function recordReference(key: string | undefined, token: string | undefined): string | null;
+//#endregion
+//#region src/routes/admin.d.ts
+interface AdminOptions {
+  registry: ConnectionRegistry;
+  store: ConfigurationStore;
+  /** Roles in the host's token that may connect, discover, propose and publish. */
+  adminRoles: readonly string[];
+  authenticate: (request: FastifyRequest) => Promise<HostIdentity | undefined>;
+  /**
+   * The operational trail (0023, 0033): one event per request, refusals
+   * included. Required, unlike the runtime's: a plane that publishes and
+   * restores forms does not run without saying who did.
+   */
+  audit: {
+    sink: AuditSink;
+    now?: () => string;
+  };
+}
+//#endregion
+//#region src/bundle.d.ts
+/**
+ * Everything one published version of a form needs at runtime, as one
+ * immutable document in the configuration store (0013).
+ *
+ * The four concerns plan section 9 keeps apart travel together here and stay
+ * separate inside: the portable formancy document, the database bindings, the
+ * access policy, and the snapshot the bindings were generated from — which the
+ * request planner reads column types from and drift review compares against.
+ */
+interface BundleParts {
+  /** The connection the form is bound to, by the name the deployment's allowlist gives it. */
+  connection: string;
+  form: FormSchema;
+  bindings: FormBindings;
+  policy: FormPolicy;
+  snapshot: MetadataSnapshot;
+}
+/** Published before 0030: served as it is; it kept no base, so a regeneration cannot carry its presentation. */
+interface BundleV1 extends BundleParts {
+  format: 1;
+}
+/**
+ * Since 0030. `form` is `applyPresentation(base, presentation, bindings)`;
+ * `base` and `bindings` are `generateForm(snapshot, generation)`'s, which is
+ * checked at publish (`generatedProblems`) and not on read.
+ */
+interface BundleV2 extends BundleParts {
+  format: 2;
+  generation: GenerationRequest;
+  base: FormSchema;
+  presentation: PresentationOverrides;
+}
+type PublishedBundle = BundleV1 | BundleV2;
+type BundleValidation = {
+  ok: true;
+  bundle: PublishedBundle;
+} | {
+  ok: false;
+  problems: string[];
+};
+/**
+ * Whether a document can be served as a published form, with every reason it
+ * cannot.
+ *
+ * Run on publish and again on every read from the store, because the store is
+ * files on a volume and a file can be edited by hand (0013). Each check is one
+ * a hand edit could break silently:
+ *
+ * - the form must be one formancy's own validator accepts, in the spec
+ *   version the generator writes (`servedSchema`, 0042) -- the validator
+ *   alone accepts every version its release speaks;
+ * - the snapshot must still hash to its own fingerprint — an edited column
+ *   type would otherwise reach the planner, which trusts it;
+ * - the bindings must have been generated from that snapshot;
+ * - the bindings must be a version this release reads — one published before
+ *   0027 cannot say which operation a field is written on, and is republished;
+ * - every bound field must exist in the form, and the policy must fit the
+ *   bindings and the snapshot (`policyProblems`), so a rule nobody enforces
+ *   cannot be published;
+ * - in format 2 (0030), the form must be its base with its presentation
+ *   applied, and the generation request the one this server would store and
+ *   the one its base and bindings say they came from (`bundle-format2.ts`).
+ *
+ * Format 1 is still read, so every version published before 0030 is served.
+ *
+ * It never throws. A part of another shape than a check reads -- a hand
+ * edit's `null` where the bindings' fields belong -- is one more reason the
+ * version is not served: thrown, it would reach the server's default 500,
+ * which answers with the exception's message, and the menu of forms (0045)
+ * would have to tell it from a store that cannot be read.
+ */
+export declare function validateBundle(document: unknown): BundleValidation;
+//#endregion
+//#region src/routes/runtime.d.ts
+interface RuntimeOptions {
+  registry: ConnectionRegistry;
+  store: ConfigurationStore;
+  authenticate: (request: FastifyRequest) => Promise<HostIdentity | undefined>;
+  /**
+   * The operational trail (0023): one event per request, outcomes included.
+   * `key` names records by a keyed hash; without it, no record is named.
+   */
+  audit?: {
+    sink: AuditSink;
+    key?: string;
+    now?: () => string;
+  };
+  /**
+   * How long a lookup statement may run before the server stops it, the
+   * membership checks inside a create or an update included (0061).
+   */
+  lookupDeadlineMs: number;
+}
+declare module 'fastify' {
+  interface FastifyRequest {
+    /** `repeated`: answered with an earlier sending's answer, and nothing asked of the database (0031). */
+    auditTrail?: {
+      formVersion: number | null;
+      record?: string;
+      repeated?: boolean;
+    };
+  }
+}
+/**
+ * The audit name of each runtime route, keyed `METHOD url`; a route without
+ * one stops the server, or never answers (0033). `admin-audit.test.ts` sends
+ * every route the router holds and fails on an entry no route has. Exported
+ * from the package: the host page's suite reads the runtime plane's routes
+ * here rather than keeping a list of its own (0047).
+ */
+export declare const ROUTE_OPERATIONS: Readonly<Record<string, RuntimeOperation>>;
+//#endregion
+//#region src/app.d.ts
+interface DataServerOptions {
+  verifyIdentity: IdentityVerifier;
+  /**
+   * Fastify's logger: `true` for standard output, or a stream to write its
+   * lines to. Off by default in tests; the composition root turns it on.
+   */
+  logger?: boolean | {
+    stream: {
+      write: (line: string) => void;
+    };
+  };
+  /**
+   * Requests per client address per window, on every route but `/health`.
+   *
+   * Default 600 a minute (`DEFAULT_RATE_LIMIT`). Generous on purpose: a lookup
+   * is a request per pause in typing. What it is for is the other case:
+   * somebody replaying tokens at the verifier as fast as the network allows.
+   * The runnable server reads `FORMANCY_DATA_RATE_LIMIT` for it (main.ts).
+   * Fastify's `trustProxy` is not offered, so behind a reverse proxy every
+   * client shares the proxy's address and one bucket: the setting raises that
+   * bucket, it does not split it.
+   */
+  rateLimit?: {
+    max: number;
+    timeWindowMs: number;
+  };
+  /**
+   * The administrator's plane: connections, discovery, proposals, publication
+   * and drift. Absent, none of those routes exist — a server without a store
+   * answers 404 for them rather than pretending. Its audit sink is required:
+   * every request that reaches one of its routes is an event (0033).
+   */
+  admin?: {
+    registry: ConnectionRegistry;
+    store: ConfigurationStore;
+    adminRoles: readonly string[];
+    audit: AdminOptions['audit'];
+  };
+  /**
+   * The runtime plane: published forms, their records and their lookups, for
+   * the host application's people. Absent, none of those routes exist.
+   *
+   * `origins`: the origins a page may call these routes from, each exactly
+   * as a browser sends `Origin` -- `https://app.example`, or plain HTTP on
+   * localhost, 127.0.0.1 or [::1] -- checked as `FORMANCY_DATA_CORS_ORIGINS`
+   * is, so a wildcard, a pattern or `null` stops the server here (0060).
+   * Empty or absent, nothing is offered across origins. The administrator's
+   * plane has no such list: it answers no other origin.
+   *
+   * `lookupDeadlineMs`: how long one lookup statement may run, counted from
+   * when the adapter is asked for it -- so a wait for a pooled connection
+   * counts, and reading the form and opening its connection do not -- before
+   * the server stops it: a search is then answered `503 lookup-timeout`, and
+   * a resolve, or a membership check inside a write, `503 unavailable`
+   * (0061). A whole number from 1 to 2147483647, or the server is not built.
+   * Default `DEFAULT_LOOKUP_DEADLINE_MS`, derived from the published
+   * performance figures; the runnable server reads
+   * `FORMANCY_DATA_LOOKUP_DEADLINE_MS` for it (main.ts).
+   */
+  runtime?: {
+    registry: ConnectionRegistry;
+    store: ConfigurationStore;
+    audit?: NonNullable<RuntimeOptions['audit']>;
+    origins?: readonly string[];
+    lookupDeadlineMs?: number;
+  };
+}
+declare module 'fastify' {
+  interface FastifyRequest {
+    identity?: HostIdentity;
+  }
+}
+/**
+ * The HTTP surface, as far as it exists.
+ *
+ * The administrator's plane is registered when the server is given a store,
+ * a connection registry and the roles that administer. The record and lookup
+ * routes arrive with the operations they call: a route that answered before
+ * the adapters behind it could would be a documented-but-inert endpoint, which
+ * is the failure this repository refuses.
+ *
+ * `GET /v1/whoami` is for the person wiring a host application in: it returns
+ * exactly the identity the server derived from the host's token, so a wrong
+ * issuer, audience or claim mapping is visible before any form depends on it.
+ */
+export declare function createDataServer(options: DataServerOptions): Promise<FastifyInstance>;
+//#endregion
+//#region src/identity-file.d.ts
+/**
+ * What one read again of a key set file did, which the log line is built from
+ * (identity-settings.ts). `problem` is readKeySet's sentence, so it holds no
+ * text of the file.
+ */
+type KeySetReadAgain = {
+  read: true;
+  changed: true;
+  kids: readonly string[];
+  added: readonly string[];
+  removed: readonly string[];
+  replaced: readonly string[];
+  leftOut: readonly LeftOutKey[];
+} | {
+  read: true;
+  changed: false;
+  kids: readonly string[];
+  leftOut: readonly LeftOutKey[];
+} | {
+  read: false;
+  kids: readonly string[];
+  problem: string;
+};
+interface KeySetFile {
+  /** The set in force. The verifier asks for it on every token. */
+  readonly current: () => KeySet;
+  /**
+   * Reads the file again. A set readKeySet accepts replaces the one in force
+   * at once; anything else leaves it as it was. Reads run one at a time, in
+   * the order they were asked for, and none ever rejects.
+   */
+  readonly readAgain: () => Promise<KeySetReadAgain>;
+}
+/**
+ * The key set in `path`, read now -- a refused set throws, which stops the
+ * server at start -- and read again whenever `readAgain` is called: on SIGHUP
+ * in the running server (main.ts), and by an embedder wherever it chooses.
+ *
+ * A read that fails keeps the set in force, a key removed from the file
+ * included, because a typo or a half-written file must not refuse every
+ * token; the outcome says so, and the same file then stops the next start
+ * until it is fixed. `read` is injected for the tests; the server and the
+ * tool read through readKeySetText.
+ */
+export declare function openKeySetFile(path: string, algorithm: KeySetAlgorithm, read?: (path: string) => Promise<string>): Promise<KeySetFile>;
+//#endregion
+//#region src/routes/admin-evolution.d.ts
+/**
+ * What `POST /v1/forms/:id/regenerations` answers: the newest version
+ * regenerated from the database as it is now, with its presentation carried
+ * (0030). Nothing is written; this is a draft to review and publish.
+ */
+interface Regeneration {
+  /** The version regenerated from; publish with it as `expectedBase`. */
+  version: number;
+  /** `diffSnapshots(published snapshot, now, published bindings, published policy)`. */
+  drift: DriftReport;
+  /** The request as used: lookups the database no longer allows are left out. */
+  generation: GenerationRequest;
+  base: FormSchema;
+  bindings: FormBindings;
+  notes: GenerationNote[];
+  snapshot: MetadataSnapshot;
+  /** The published policy, unchanged. */
+  policy: FormPolicy;
+  /** What that policy does not fit in the new bindings and snapshot. */
+  policyProblems: string[];
+  /** The published presentation, carried to the new base. */
+  presentation: PresentationOverrides;
+  /** The new base with it applied. */
+  form: FormSchema;
+  conflicts: PresentationConflict[];
+  /** Lookups the runtime would refuse now, each with the sentence that refuses it. */
+  lookupsDropped: Array<{
+    foreignKey: string;
+    message: string;
+  }>;
+  /**
+   * Keys that now stand for another column or lookup: the grants written for
+   * them need confirming. A publish whose policy grants on one is refused,
+   * 422 `keys-reassigned`, unless its body lists it, as given here, in
+   * `keysConfirmed` (0039).
+   */
+  keysReassigned: ReassignedKey[];
+}
+/** What `POST /v1/forms/:id/restorations` answers: the version written, the one it copies, and the drift that allowed it. */
+interface Restoration {
+  version: number;
+  restoredFrom: number;
+  drift: DriftReport;
+}
+//#endregion
+//#region src/routes/admin-promotion.d.ts
+/**
+ * What `POST /v1/forms/:id/imports` answers (0062): the version written, and
+ * the drift between the snapshot the bundle carries and this deployment's
+ * database that allowed it -- changes to review or note, never one that
+ * blocks.
+ */
+interface Importation {
+  version: number;
+  drift: DriftReport;
+}
+//#endregion
+//#region src/drivers.d.ts
+/**
+ * The drivers, one factory per engine. Each adapter package opens its own
+ * connections (`connectPostgres`, `connectSqlServer`), so a connection and the
+ * code that binds values on it always come from one copy of the driver — the
+ * server imports no driver at all, and the end-to-end suite is what found why
+ * that matters.
+ */
+export declare const DRIVER_FACTORIES: Readonly<Record<DatabaseKind, ConnectionFactory>>;
+//#endregion
+export type { AdminAuditEvent, AuditEvent, AuditSink, BundleV1, BundleV2, BundleValidation, ConfigurationStore, ConnectionConfig, ConnectionFactory, ConnectionRegistry, DataServerOptions, HostIdentity, IdentityOptions, IdentityOutcome, IdentityVerifier, Importation, KeySetAlgorithm, KeySetChange, KeySetFile, KeySetReadAgain, LeftOutKey, OneKey, OpenConnection, PublishOutcome, PublishedBundle, Regeneration, Restoration, RuntimeAuditEvent, RuntimeOperation, SecretSource };
+//# sourceMappingURL=index.d.mts.map