@formancy/server-core 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,79 +1,88 @@
+import { CHALLENGE_TTL_SECONDS, Challenge, DEFAULT_MAX_NUMBER, Solution, VerifyOutcome, decodeSolution, encodeSolution, hashOf, mintChallenge, solveChallenge, verifySolution } from "@formancy/challenge";
 import { Change, FormSchema } from "@formancy/spec";
 import { SchemaError } from "@formancy/spec/validate";
 import { CapabilitySource } from "@formancy/core";
-//#region src/auth.d.ts
+//#region src/options-membership.d.ts
 /**
- * The management plane's identity and authorization, framework-free.
+ * Checking that a sourced answer is one the deployment's own source offers.
  *
- * Hashing and randomness are injected — this package cannot reach a CSPRNG or
- * argon2 on its own, the composition root hands them in — which keeps every
- * behaviour here testable with deterministic fakes while the real server gets
- * real cryptography.
+ * The engine already refuses a value no *document* option offers
+ * ([0076](../../../docs/decisions/0076-an-answer-is-one-of-the-options.md)), and
+ * it runs on both sides. A `optionsSource` field has no document options, so that
+ * check has nothing to compare against — deliberately, because a list living
+ * outside the document cannot be checked against the document.
+ *
+ * So the server asks the deployment instead, and the deployment answers with a
+ * database query rather than with a request to an address a form author typed.
+ * That is why the port takes a function and this package ships no HTTP client:
+ * `@formancy/server-core` imports no `URL` and no `fetch`, and adding an outbound
+ * request here would add confused-deputy surface to a regulatory set that claims
+ * none.
  */
-type Role = 'admin' | 'editor' | 'viewer';
-interface Actor {
-  kind: 'user' | 'apiKey';
-  id: string;
-  role: Role;
-}
-interface AuthDeps {
-  storage: Storage;
-  newId(): string;
-  nowIso(): string;
-  /** At least 160 bits of entropy, URL-safe. Injected, never Math.random. */
-  randomToken(): string;
-  hashSecret(secret: string): Promise<string>;
-  verifySecret(secret: string, hash: string): Promise<boolean>;
+/** One named source, as the deployment configured it. */
+interface ServerOptionsSource {
+  /**
+   * Which of these values this source does NOT offer.
+   *
+   * Phrased as the rejects rather than the members so an adapter can answer from a
+   * SQL `IN` clause without materialising a list — a source with two million rows
+   * is exactly the case `optionsSource` exists for.
+   *
+   * Absent means: *this source exists, and I cannot check membership.* That is a
+   * legitimate configuration and it weakens the guarantee, which is why the
+   * guarantee is written down rather than implied.
+   */
+  members?(values: readonly string[]): Promise<readonly string[]>;
 }
-type CreateUserOutcome = {
-  ok: true;
-  id: string;
-} | {
-  ok: false;
-  message: string;
-};
-export declare function createLocalUser(deps: AuthDeps, input: {
-  email: string;
-  password: string;
-  role: Role;
-}): Promise<CreateUserOutcome>;
-type AuthOutcome = {
+type ServerOptionsSources = Readonly<Record<string, ServerOptionsSource>>;
+/**
+ * Every sourced answer in a submission, as `path → { source, value }`.
+ *
+ * Walked from the SCHEMA over the value, never from the value's own shape — the
+ * same way `referencedFileIds` does it. A walk driven by what arrived would let a
+ * client dodge the check by omitting a property, and hidden branches have already
+ * been stripped by the engine before this runs.
+ */
+export declare function sourcedAnswers(schema: FormSchema, value: unknown): ReadonlyArray<{
+  path: string;
+  source: string;
+  value: string;
+}>;
+/** What asking the deployment produced. */
+type MembershipOutcome = {
   ok: true;
-  actor: Actor;
-} | {
+} |
+/** Values the deployment's own source does not offer, by field path. */
+{
   ok: false;
-};
+  kind: 'invalid';
+  errors: Record<string, string[]>;
+} |
 /**
- * A wrong password and an unknown email answer identically, and BOTH run a
- * hash verification — the difference in shape or timing would be a
- * user-enumeration oracle.
+ * A source could not answer.
+ *
+ * Failed CLOSED, always. An accepted bogus value is undetectable afterwards; a
+ * refusal is retryable and the draft still holds the answers. It is the same rule
+ * the engine applies to a validation rule it cannot evaluate.
  */
-export declare function authenticateLocal(deps: AuthDeps, input: {
-  email: string;
-  password: string;
-}): Promise<AuthOutcome>;
-type CreateApiKeyOutcome = {
-  ok: true;
-  id: string;
-  secret: string;
-} | {
+{
   ok: false;
-  message: string;
+  kind: 'source_unavailable';
+  source: string;
 };
-export declare function createApiKey(deps: AuthDeps, input: {
-  name: string;
-  role: Role;
-}): Promise<CreateApiKeyOutcome>;
-export declare function authenticateApiKey(deps: AuthDeps, presented: string): Promise<AuthOutcome>;
 /**
- * The whole authorization model, in one table a reviewer can read top to
- * bottom. Deliberately NOT Postgres RLS in this phase: RLS couples the app to
- * per-request database roles and hides authorization from the test suite.
- * An unknown action is denied — permissions are granted by presence, never by
- * omission.
+ * Ask each source about the values submitted for it.
+ *
+ * One call per source rather than per answer, so a deployment sees `IN (…)` and not
+ * a query per row.
  */
-type Action = 'form.read' | 'form.publish' | 'submission.read' | 'submission.export' | 'draft.write' | 'user.create' | 'apiKey.create';
-export declare function can(actor: Actor, action: Action): boolean;
+export declare function checkMembership(schema: FormSchema, value: unknown, sources: ServerOptionsSources | undefined): Promise<MembershipOutcome>;
+/**
+ * The source names a document uses, for the publish-time vocabulary check.
+ *
+ * Walked over the schema rather than over any data, because publishing has none.
+ */
+export declare function sourceNamesIn(schema: FormSchema): readonly string[];
 //#endregion
 //#region src/ports.d.ts
 /**
@@ -85,6 +94,22 @@ interface FormRecord {
   id: string;
   path: string;
   currentVersionId: string | null;
+  /**
+   * Who may submit. Deliberately NOT part of the form document: a document has
+   * to mean the same thing wherever it is moved, and carrying "anyone may
+   * submit this" across a deployment boundary is how a private form becomes a
+   * public one by accident.
+   *
+   * Defaults to `authenticated`. The safe value is the default because the
+   * unsafe one should require somebody to have said it.
+   */
+  accessSubmit: 'authenticated' | 'public';
+  /**
+   * Origins allowed to submit anonymously. `null` means no allowlist is in
+   * force; an empty array means nothing is allowed, which is not the same
+   * thing and is why this is not just an array.
+   */
+  allowedOrigins: string[] | null;
 }
 interface FormVersionRecord {
   id: string;
@@ -124,16 +149,184 @@ interface DraftRecord {
   data: unknown;
   updatedAt: string;
 }
+/** A webhook registered against a form. */
+interface WebhookRecord {
+  id: string;
+  formId: string;
+  url: string;
+  /** Shared with the receiver; signs every delivery. */
+  secret: string;
+  /**
+   * Failures in a row against this destination. Reset by any success.
+   *
+   * On the record rather than in the worker's memory for two reasons: memory
+   * does not survive a restart, and a self-hoster with no operations team
+   * needs a failing webhook to be visible on a screen rather than in a log
+   * nobody is tailing.
+   */
+  consecutiveFailures: number;
+  /** When the breaker opened, or null while the destination is answering. */
+  openedAt: string | null;
+}
+/**
+ * One queued delivery — the outbox row.
+ *
+ * It exists so that "a submission was accepted" and "its webhooks will be
+ * delivered" are decided by the same COMMIT. The alternative, posting after
+ * the insert returns, produces the two failures a self-hoster cannot debug:
+ * the webhook fired and the submission rolled back, or the submission is
+ * stored and nothing was ever sent.
+ */
+interface DeliveryRecord {
+  id: string;
+  webhookId: string;
+  submissionId: string;
+  /** Stable across every retry, so a receiver can be idempotent. */
+  eventId: string;
+  body: string;
+  attempt: number;
+  /** Not before this instant. Set by the retry schedule. */
+  nextAttemptAt: string;
+  /** `pending`, `delivered`, or `dead` once the attempts run out. */
+  state: 'pending' | 'delivered' | 'dead';
+  lastError: string | null;
+}
+/**
+ * One uploaded file, in three states.
+ *
+ * `offered` means somebody asked where to put a file and the bytes have not
+ * arrived. `stored` means they have. `claimed` means a submission that
+ * references it was accepted, which is the only state that makes a file worth
+ * keeping — everything else is rubbish waiting to be collected.
+ *
+ * The row is written BEFORE the bytes, so a file that dies halfway through
+ * uploading is still something the collector knows to look for. An orphan on
+ * disk with no row is one nothing will ever find.
+ *
+ * `name` is what the reader called it and is shown back to them; it is never
+ * part of `storageKey`, because a key built from a submitted filename is a
+ * path traversal waiting for somebody to try it.
+ */
+interface FileRecord {
+  id: string;
+  formId: string;
+  /** What the reader called it. Display only. */
+  name: string;
+  size: number;
+  contentType: string;
+  /** Where the bytes are, in whatever the host's storage calls a location. */
+  storageKey: string;
+  state: 'offered' | 'stored' | 'claimed';
+  createdAt: string;
+  /** The submission that claimed it, or null. One file, one submission. */
+  submissionId: string | null;
+}
 interface Storage {
   getFormByPath(path: string): Promise<FormRecord | undefined>;
   listForms(): Promise<FormRecord[]>;
   createForm(record: FormRecord): Promise<void>;
+  updateFormAccess(formId: string, access: Pick<FormRecord, 'accessSubmit' | 'allowedOrigins'>): Promise<void>;
   setCurrentVersion(formId: string, versionId: string): Promise<void>;
   insertVersion(record: FormVersionRecord): Promise<void>;
+  /**
+   * A publish, as ONE commit.
+   *
+   * The three steps it replaces — create the form when it is new, insert the
+   * version, point the form at it — used to be three calls, and the middle
+   * failure is the one that hurts: a form row whose `currentVersionId` is
+   * still null resolves to nothing, so the form exists, answers its URL, and
+   * has no schema to render. `GET /f/:path` 404s for a form that is right
+   * there in the list.
+   *
+   * The audit row travels with them for the same reason it travels with a
+   * submission: a publish that rolled back must leave nothing saying it
+   * happened, and a publish that happened must leave something.
+   *
+   * `form` is present only when the form is new. An existing form is not
+   * touched apart from its pointer, because its access settings are not the
+   * publisher's business.
+   */
+  publishVersion(input: {
+    form?: FormRecord;
+    version: FormVersionRecord;
+    audit?: AuditEntry;
+  }): Promise<void>;
   getVersionById(id: string): Promise<FormVersionRecord | undefined>;
   findVersionByHash(formId: string, schemaHash: string): Promise<FormVersionRecord | undefined>;
   latestVersionNumber(formId: string): Promise<number>;
-  insertSubmission(record: SubmissionRecord): Promise<void>;
+  /**
+   * The submission and every delivery it triggers, in ONE transaction.
+   *
+   * One method rather than two calls, because the atomicity is the point and a
+   * port that exposes them separately invites a caller to break it. See
+   * docs/decisions/0024-postgres-over-mongodb.md, where this requirement is
+   * what chose the database.
+   */
+  /**
+   * The submission, the webhooks it triggers and the files it claims, in ONE
+   * call because they belong in one COMMIT. A port that exposed them
+   * separately would invite a caller to break that, and the three failures it
+   * prevents — a webhook fired for a rolled-back submission, a stored
+   * submission nothing was sent about, an accepted submission whose files the
+   * collector deletes — are the ones a self-hoster cannot debug.
+   */
+  insertSubmission(record: SubmissionRecord, deliveries?: readonly DeliveryRecord[], claimFileIds?: readonly string[], audit?: AuditEntry): Promise<void>;
+  /**
+   * Append one audit row.
+   *
+   * Append-only by contract, and the deployment is expected to back that with
+   * a database role holding INSERT and SELECT and nothing else — an audit
+   * log the application can edit is a log that says whatever the person who
+   * broke in wants it to say. There is deliberately no update and no delete
+   * on this port for anything to call.
+   *
+   * For a mutation that HAS a transaction, pass the entry to that call
+   * instead, so the row and the thing it describes commit together. See
+   * `insertSubmission`.
+   */
+  recordAudit(entry: AuditEntry): Promise<void>;
+  /** Newest first. Reading the log is itself a management-plane action. */
+  listAudit(limit: number): Promise<AuditEntry[]>;
+  /**
+   * Spend a solved challenge, once.
+   *
+   * Returns false when it has been spent already. The signature on a challenge
+   * proves this server minted it and the hash proves somebody did the work —
+   * and neither stops the same correct solution being sent a thousand times,
+   * because a correct solution stays correct. Only a record of what has been
+   * used can.
+   *
+   * It must be ATOMIC: two requests arriving with one solution both pass every
+   * stateless check, and the database is the only thing that can decide which
+   * of them spends it. An implementation that reads then writes has a race
+   * exactly where the attacker is looking.
+   */
+  spendChallenge(challenge: string, expiresAtIso: string): Promise<boolean>;
+  /** Drop spent challenges that can no longer be replayed anyway. */
+  forgetExpiredChallenges(beforeIso: string): Promise<number>;
+  insertFile(record: FileRecord): Promise<void>;
+  getFile(id: string): Promise<FileRecord | undefined>;
+  updateFile(record: FileRecord): Promise<void>;
+  /** Every file in a state other than `claimed`, created before `beforeIso`. */
+  abandonedFiles(beforeIso: string): Promise<FileRecord[]>;
+  deleteFiles(ids: readonly string[]): Promise<void>;
+  webhooksForForm(formId: string): Promise<WebhookRecord[]>;
+  insertWebhook(record: WebhookRecord): Promise<void>;
+  /** Health, after an attempt. The record is the breaker's only memory. */
+  updateWebhook(record: WebhookRecord): Promise<void>;
+  listWebhooks(): Promise<WebhookRecord[]>;
+  /**
+   * Deliveries that ran out of attempts.
+   *
+   * Dead, not deleted: the row is the evidence that something was supposed to
+   * be sent and never arrived. Without a way to list them the evidence is in
+   * a table nobody looks at, which is the same as not having it.
+   */
+  deadDeliveries(limit: number): Promise<DeliveryRecord[]>;
+  getDelivery(id: string): Promise<DeliveryRecord | undefined>;
+  /** Oldest first, only those due. */
+  claimDueDeliveries(nowIso: string, limit: number): Promise<DeliveryRecord[]>;
+  updateDelivery(record: DeliveryRecord): Promise<void>;
   listSubmissions(): Promise<SubmissionRecord[]>;
   /** Newest first. */
   listSubmissionsByForm(formId: string): Promise<SubmissionRecord[]>;
@@ -148,6 +341,306 @@ interface Storage {
   revokeApiKey(id: string, atIso: string): Promise<void>;
 }
 //#endregion
+//#region src/auth.d.ts
+/**
+ * The management plane's identity and authorization, framework-free.
+ *
+ * Hashing and randomness are injected — this package cannot reach a CSPRNG or
+ * argon2 on its own, the composition root hands them in — which keeps every
+ * behaviour here testable with deterministic fakes while the real server gets
+ * real cryptography.
+ */
+type Role = 'admin' | 'editor' | 'viewer';
+interface Actor {
+  kind: 'user' | 'apiKey';
+  id: string;
+  role: Role;
+}
+interface AuthDeps {
+  storage: Storage;
+  newId(): string;
+  nowIso(): string;
+  /** At least 160 bits of entropy, URL-safe. Injected, never Math.random. */
+  randomToken(): string;
+  hashSecret(secret: string): Promise<string>;
+  verifySecret(secret: string, hash: string): Promise<boolean>;
+}
+type CreateUserOutcome = {
+  ok: true;
+  id: string;
+} | {
+  ok: false;
+  message: string;
+};
+export declare function createLocalUser(deps: AuthDeps, input: {
+  email: string;
+  password: string;
+  role: Role;
+}): Promise<CreateUserOutcome>;
+type AuthOutcome = {
+  ok: true;
+  actor: Actor;
+} | {
+  ok: false;
+};
+/**
+ * A wrong password and an unknown email answer identically, and BOTH run a
+ * hash verification — the difference in shape or timing would be a
+ * user-enumeration oracle.
+ */
+export declare function authenticateLocal(deps: AuthDeps, input: {
+  email: string;
+  password: string;
+}): Promise<AuthOutcome>;
+type CreateApiKeyOutcome = {
+  ok: true;
+  id: string;
+  secret: string;
+} | {
+  ok: false;
+  message: string;
+};
+export declare function createApiKey(deps: AuthDeps, input: {
+  name: string;
+  role: Role;
+}): Promise<CreateApiKeyOutcome>;
+export declare function authenticateApiKey(deps: AuthDeps, presented: string): Promise<AuthOutcome>;
+/**
+ * The whole authorization model, in one table a reviewer can read top to
+ * bottom. Deliberately NOT Postgres RLS in this phase: RLS couples the app to
+ * per-request database roles and hides authorization from the test suite.
+ * An unknown action is denied — permissions are granted by presence, never by
+ * omission.
+ */
+type Action = 'form.read' | 'form.publish' | 'submission.read' | 'submission.export' | 'draft.write' | 'user.create' | 'apiKey.create';
+export declare function can(actor: Actor, action: Action): boolean;
+//#endregion
+//#region src/audit.d.ts
+/**
+ * Who did what, to which thing, and when.
+ *
+ * **Reads and exports are recorded as well as mutations** — `submission.read` and
+ * `submission.exported` — which is what lets a self-hoster answer who downloaded four
+ * thousand people's answers ([0057](../../../docs/decisions/0057-the-audit-log-records-reads.md)).
+ *
+ * **A row joins the mutation's transaction where there is one.** `insertSubmission` and
+ * `publishVersion` both commit their audit row with the change it describes, so a
+ * rollback leaves no trace saying it happened. A read has nothing to be atomic with, so
+ * its row is appended after the rows are handed over and a failure to write it is logged
+ * loudly rather than swallowed.
+ *
+ * **`detail` carries identifiers and counts, never submission content.** An audit log is
+ * read by more people, kept longer and exported more freely than the data it describes.
+ */
+/**
+ * Every auditable action, as a closed list.
+ *
+ * Closed so a new route cannot invent its own spelling: an audit log where one event is
+ * called two things is one nobody can query.
+ */
+export declare const AUDIT_ACTIONS: readonly ["auth.login", "auth.login.failed", "form.published", "form.access.changed", "submission.created", "submission.read", "submission.exported", "file.downloaded", "user.created", "apiKey.created", "apiKey.revoked", "delivery.replayed"];
+type AuditAction = (typeof AUDIT_ACTIONS)[number];
+interface AuditEntry {
+  readonly id: string;
+  readonly at: string;
+  readonly action: AuditAction;
+  /**
+   * Who. Absent for an anonymous public submission, which is a real answer
+   * rather than a gap: the form was open, and nobody was signed in.
+   */
+  readonly actorKind?: 'user' | 'apiKey';
+  readonly actorId?: string;
+  /**
+   * What it was done to, as a stable identifier: a form's path, a submission
+   * id, a user's id. Absent only where the action has no object, which is
+   * currently nothing.
+   */
+  readonly subject?: string;
+  /**
+   * The request it happened in, so an export and the rows it returned can be
+   * tied together later.
+   */
+  readonly requestId?: string;
+  /** Identifiers and counts. Never a submission's answers. */
+  readonly detail?: Readonly<Record<string, string | number | boolean>>;
+}
+/** What a caller has to supply; the id and the timestamp are minted for it. */
+type AuditDraft = Omit<AuditEntry, 'id' | 'at'>;
+/**
+ * An entry from an actor, with the fields spread the way the record stores
+ * them.
+ *
+ * A helper rather than a convention, because `actorKind` and `actorId` being
+ * set together is exactly the sort of thing eleven call sites get wrong once.
+ */
+export declare function auditedBy(actor: Actor | undefined, draft: Omit<AuditDraft, 'actorKind' | 'actorId'>): AuditDraft;
+//#endregion
+//#region src/outbox.d.ts
+/**
+ * What to do with a delivery once an attempt has finished.
+ *
+ * Pure, and separate from the thing that does the posting, because this is
+ * where the decisions are: whether to retry, when, and when to stop. Tangled
+ * into the network code those decisions are only testable by making requests.
+ */
+interface AttemptOutcome {
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+export declare function afterAttempt(delivery: DeliveryRecord, outcome: AttemptOutcome, now: Date, random: () => number): DeliveryRecord;
+interface OutboxDeps {
+  storage: Storage;
+  /** Posts one delivery. Injected so the loop is testable without a network. */
+  send: (delivery: DeliveryRecord, webhook: WebhookRecord, nowSeconds: number) => Promise<AttemptOutcome>;
+  now: () => Date;
+  random: () => number;
+}
+/**
+ * Drain one batch of due deliveries.
+ *
+ * Returns how many were attempted, so a caller can decide whether to come back
+ * immediately or wait. Deliberately one batch rather than a loop that runs
+ * forever: the thing that decides *when* to run belongs to the host, and a
+ * function that never returns cannot be tested.
+ */
+/**
+ * Returns how many were ATTEMPTED — deliveries skipped because their
+ * destination's breaker is open do not count, so a caller polling until the
+ * queue is quiet does not spin on a dead endpoint.
+ */
+export declare function drainOutbox(deps: OutboxDeps, limit?: number): Promise<number>;
+/**
+ * Put a dead delivery back in the queue.
+ *
+ * Dead is where a delivery goes when the attempts run out, and the row is the
+ * evidence that something was supposed to be sent and never arrived. Replay is
+ * what makes that evidence useful: the receiver was down for a morning, it is
+ * back, and the twelve submissions it missed should go now.
+ *
+ * The attempt count resets. It is a new run against a destination somebody has
+ * looked at and decided is fixed — carrying the old count over would give it
+ * one try before dying again, which is not a replay so much as a formality.
+ *
+ * Refuses anything that is not dead. Replaying a pending delivery would
+ * duplicate it, and replaying a delivered one would send it twice: the event
+ * id is stable across retries so a well-behaved receiver would ignore the
+ * second, but this service does not get to assume the receiver is
+ * well-behaved.
+ */
+type ReplayOutcome = {
+  ok: true;
+  delivery: DeliveryRecord;
+} | {
+  ok: false;
+  kind: 'unknown' | 'not-dead';
+  state?: DeliveryRecord['state'];
+};
+export declare function replayDelivery(deps: {
+  storage: Storage;
+  now: () => Date;
+}, id: string): Promise<ReplayOutcome>;
+//#endregion
+//#region src/breaker.d.ts
+/**
+ * Stopping, when a destination has plainly stopped listening.
+ *
+ * Failure is counted per WEBHOOK as well as per delivery. Enough consecutive failures
+ * and the breaker opens: nothing is attempted for that webhook until a cool-down passes,
+ * then exactly one delivery goes through as a probe. It succeeds and the breaker closes;
+ * it fails and the cool-down starts again.
+ *
+ * `consecutiveFailures` and `openedAt` live on the RECORD rather than in the worker's
+ * memory, so the state survives a restart and can be shown on a screen — a self-hoster
+ * has no operations team watching a dashboard
+ * ([0058](../../../docs/decisions/0058-a-breaker-per-destination.md)).
+ *
+ * Everything here is a pure function of a record and a clock: decisions tangled into
+ * network code can only be tested by making requests.
+ */
+/**
+ * How many consecutive failures open the breaker.
+ *
+ * Three, not one. A single failure is a bad minute — a deploy, a timeout, a
+ * receiver restarting — and opening on it would make every routine blip a
+ * visible outage. Three in a row is a destination that is not coming back on
+ * its own.
+ */
+export declare const BREAKER_THRESHOLD = 3;
+/**
+ * How long the breaker stays shut before one probe is allowed through.
+ *
+ * Five minutes: long enough that a restarting receiver is finished, short
+ * enough that nobody notices the delay once it recovers. The retry schedule
+ * handles patience within a delivery; this handles patience about a
+ * destination.
+ */
+export declare const BREAKER_COOLDOWN_MS: number;
+/** Shut, letting one through, or open. */
+type BreakerState = 'closed' | 'half-open' | 'open';
+export declare function breakerState(webhook: WebhookRecord, now: Date): BreakerState;
+/** Whether a delivery for this webhook may be attempted now. */
+export declare function mayAttempt(webhook: WebhookRecord, now: Date): boolean;
+/**
+ * The webhook's health after one attempt against it.
+ *
+ * A success always closes the breaker completely. Decaying the count instead
+ * would leave a destination that fails twice for every success permanently
+ * one blip from opening, and that destination is working.
+ */
+export declare function afterWebhookAttempt(webhook: WebhookRecord, ok: boolean, now: Date): WebhookRecord;
+/**
+ * What a person is shown about a webhook's health.
+ *
+ * Shaped for a screen rather than for a log: the question being answered is
+ * "is this working, and if not since when", which is what somebody asks when
+ * the CRM has no leads this week.
+ */
+interface WebhookHealth {
+  id: string;
+  url: string;
+  state: BreakerState;
+  consecutiveFailures: number;
+  /** When it stopped working, or null while it is working. */
+  failingSince: string | null;
+}
+export declare function healthOf(webhook: WebhookRecord, now: Date): WebhookHealth;
+//#endregion
+//#region src/redos.d.ts
+/**
+ * Refuse a form whose `pattern` values can be made to backtrack.
+ *
+ * A form author supplies these, and the server runs them against whatever a
+ * submitter typed. That makes a regular expression an author-side denial of
+ * service vector: one bad pattern, published once, and every submission after
+ * it can be turned into unbounded CPU by anyone who can reach the form.
+ *
+ * Checked at PUBLISH time rather than at match time, because there is no way
+ * to time out a JavaScript regular expression once it has started. The only
+ * moment the cost can be refused is before the pattern is stored.
+ *
+ * The check is static — `recheck` analyses the expression rather than running
+ * it — so it costs nothing per submission, and it found a polynomial case in
+ * formancy's own built-in email format before it was ever pointed at a user's.
+ */
+interface UnsafePattern {
+  /** Data path of the field carrying it, e.g. `contacts[].code`. */
+  path: string;
+  pattern: string;
+  /** `exponential` or `polynomial`, with the degree where there is one. */
+  complexity: string;
+}
+/**
+ * The patterns in this schema that an attacker could exploit, or an empty array
+ * when there are none.
+ *
+ * A pattern `recheck` cannot decide about is ACCEPTED. Refusing on `unknown`
+ * would make publishing depend on an analysis timeout, which is a worse failure
+ * than the one being prevented — an author whose legitimate form stops
+ * publishing intermittently has no way to act on that.
+ */
+export declare function unsafePatterns(schema: FormSchema): Promise<UnsafePattern[]>;
+//#endregion
 //#region src/use-cases.d.ts
 /**
  * The backend's use-cases, framework-free.
@@ -162,6 +655,31 @@ interface ServerDeps {
   nowIso(): string;
   /** The clock/randomness the ENGINE sees during replay. */
   capabilities: CapabilitySource;
+  /**
+   * Signs the token that proves somebody started a draft.
+   *
+   * The public plane is anonymous, so a draft has no account behind it — which
+   * is exactly why it needs a secret of its own. The host's own signing key is
+   * reused rather than a second one being configured: a draft token is a
+   * server-signed bearer token, which is what that key is already for, and an
+   * optional secret would mean drafts are unprotected whenever nobody set it.
+   */
+  draftSecret: string;
+  /**
+   * The lists a form document may name with `optionsSource`, and how to check a
+   * value against one.
+   *
+   * A function and never an address: for a real source this is a database query, not
+   * a request to somewhere a form author typed. Shipping an HTTP adapter here would
+   * add outbound-request and confused-deputy surface to a regulatory set that
+   * currently claims neither — for a convenience nobody asked for.
+   *
+   * Absent entirely means this deployment has no vocabulary: publishing cannot be
+   * judged against it, and no submission is checked. Present but without `members`
+   * for a name means *this source exists and I cannot check membership* — a
+   * legitimate configuration, and the reason the guarantee is written down.
+   */
+  optionsSources?: ServerOptionsSources;
 }
 type PublishOutcome = {
   ok: true;
@@ -177,6 +695,16 @@ type PublishOutcome = {
   ok: false;
   kind: 'invalid_logic';
   message: string;
+} | {
+  ok: false;
+  kind: 'unsafe_pattern';
+  patterns: UnsafePattern[];
+} |
+/** The document names a list this deployment has never heard of. */
+{
+  ok: false;
+  kind: 'unknown_options_source';
+  sources: string[];
 };
 /**
  * Publish a schema as a form's next version.
@@ -190,6 +718,7 @@ type PublishOutcome = {
 export declare function publishForm(deps: ServerDeps, input: {
   path: string;
   schema: unknown;
+  actor?: Actor;
 }): Promise<PublishOutcome>;
 interface ResolvedForm {
   formId: string;
@@ -214,6 +743,23 @@ type SubmissionOutcome = {
   ok: false;
   kind: 'invalid';
   errors: Record<string, string[]>;
+} |
+/** The caller may not submit this form: not public, or not from this origin. */
+{
+  ok: false;
+  kind: 'forbidden';
+} |
+/**
+ * A source that should have vouched for an answer could not.
+ *
+ * Failed closed and never accepted unchecked: a bogus value that is stored is
+ * undetectable afterwards, while a refusal is retryable and the draft still holds
+ * the answers.
+ */
+{
+  ok: false;
+  kind: 'source_unavailable';
+  source: string;
 };
 /**
  * Accept one submission: resolve the version the client says it rendered,
@@ -224,10 +770,27 @@ type SubmissionOutcome = {
  * are stripped, so a client cannot smuggle data by lying about what was shown.
  * Client validation is UX; this is truth.
  */
+/**
+ * Change who may submit a form, and from where.
+ *
+ * Separate from publishing on purpose: access is a property of the deployment,
+ * and changing it must not mint a new immutable form version or invalidate the
+ * schema hash every client is holding.
+ */
+export declare function setFormAccess(deps: ServerDeps, input: {
+  path: string;
+  submit: 'authenticated' | 'public';
+  allowedOrigins?: string[];
+}): Promise<{
+  ok: boolean;
+}>;
 export declare function createSubmission(deps: ServerDeps, input: {
   path: string;
   declaredSchemaHash: string;
   data: unknown;
+  /** Defaults to anonymous: the caller must prove otherwise, not the reverse. */
+  actor?: 'anonymous' | 'authenticated';
+  origin?: string;
 }): Promise<SubmissionOutcome>;
 interface ListedSubmission {
   id: string;
@@ -250,14 +813,27 @@ export declare function listSubmissions(deps: ServerDeps, path: string): Promise
  * spreadsheet join a business user will try.
  */
 export declare function exportCsv(deps: ServerDeps, path: string): Promise<string | undefined>;
-/** Save (or re-save) a partial form, bound to the CURRENT version. Undefined
- *  for an unknown form. */
+/**
+ * Start a draft: the server picks the id, and signs it.
+ *
+ * The id is the server's because an id a caller supplies is an id a caller can
+ * enumerate — and enumerating them was enough to read other people's
+ * part-filled answers.
+ */
+export declare function startDraft(deps: ServerDeps, input: {
+  path: string;
+}): Promise<{
+  draftId: string;
+  token: string;
+} | undefined>;
 export declare function saveDraft(deps: ServerDeps, input: {
   path: string;
   draftId: string;
+  token: string;
   data: unknown;
 }): Promise<{
   version: number;
+  saved: boolean;
 } | undefined>;
 interface DraftMigration {
   severity: 'lossy';
@@ -294,6 +870,7 @@ type ResumeOutcome = {
 export declare function resumeDraft(deps: ServerDeps, input: {
   path: string;
   draftId: string;
+  token: string;
 }): Promise<ResumeOutcome | undefined>;
 interface ListedForm {
   path: string;
@@ -320,5 +897,201 @@ export declare function listVersions(deps: ServerDeps, path: string): Promise<Li
  */
 export declare function createMemoryStorage(): Storage;
 //#endregion
-export type { Action, Actor, AuthDeps, AuthOutcome, DraftMigration, DraftRecord, FormRecord, FormVersionRecord, ListedForm, ListedSubmission, ListedVersion, PublishOutcome, ResolvedForm, ResumeOutcome, Role, ServerDeps, Storage, SubmissionOutcome, SubmissionRecord };
+//#region src/address.d.ts
+/**
+ * Deciding whether an address is somewhere this server may fetch from.
+ *
+ * A self-hosted formancy sits inside somebody's private network and webhook
+ * URLs are written by whoever can edit a form, which makes the server a
+ * confused deputy: it can reach the database, the metadata service and every
+ * internal admin panel, and it will fetch whatever it is told to.
+ *
+ * This half is pure — given an address, is it private — so it lives here and is
+ * tested exhaustively. The rest lives in @formancy/server, because it cannot be
+ * pure: parsing a URL needs `URL`, and resolving a hostname then connecting to
+ * the address that was checked, rather than re-resolving, needs Node's DNS and
+ * a custom agent. This package has no @types/node by design, and hand-rolling
+ * a URL parser for a security check is how such a check gets quietly wrong.
+ * All three parts are necessary. Validating a URL and then handing it to fetch is defeated by DNS
+ * rebinding — the name resolves to a public address for the check and a private
+ * one for the request — and that is the difference between a mitigation and
+ * theatre.
+ */
+/**
+ * Whether this address is one the server must not be pointed at.
+ *
+ * Unparseable input counts as private. An address this cannot classify is one
+ * it cannot vouch for, and the safe direction is refusing to fetch.
+ */
+export declare function isPrivateAddress(address: string): boolean;
+/**
+ * Whether this is a literal IP address rather than a hostname.
+ *
+ * The two need different treatment and conflating them breaks the check in
+ * both directions: `isPrivateAddress` fails closed on anything it cannot
+ * parse, which is correct for an address that came back from DNS and wrong for
+ * `example.ch`, where it would refuse every hostname in the world.
+ */
+export declare function isIpLiteral(host: string): boolean;
+//#endregion
+//#region src/webhook.d.ts
+/**
+ * What a webhook delivery looks like on the wire.
+ *
+ * The signature scheme is Stripe's, deliberately: receivers already have code
+ * for it, and a scheme somebody has to implement from scratch is a scheme most
+ * receivers will skip. Adopting a familiar one is the difference between a
+ * verified webhook and a verified-in-principle one.
+ */
+export declare const EVENT_ID_HEADER = "x-formancy-event-id";
+export declare const SIGNATURE_HEADER = "x-formancy-signature";
+interface DeliveryHeaders {
+  [header: string]: string;
+}
+/**
+ * The signed payload is `timestamp.body`, not `body`.
+ *
+ * Without the timestamp inside the signature, a signature captured once stays
+ * valid forever and can be replayed. With it, a receiver can reject anything
+ * older than its tolerance, and the signature covers the timestamp it is
+ * checking — so the timestamp cannot be edited either.
+ */
+export declare function signedPayload(timestampSeconds: number, body: string): string;
+/** Hex HMAC-SHA256 over the signed payload. */
+export declare function signBody(secret: string, timestampSeconds: number, body: string): string;
+/**
+ * The headers for one delivery attempt.
+ *
+ * The event id is stable across retries, which is what makes the receiver able
+ * to be idempotent. Generating a fresh one per attempt would turn our retry
+ * into their duplicate.
+ */
+export declare function deliveryHeaders(input: {
+  eventId: string;
+  secret: string;
+  body: string;
+  timestampSeconds: number;
+  attempt: number;
+}): DeliveryHeaders;
+/**
+ * Verify a delivery the way a receiver would.
+ *
+ * Exported because a scheme nobody can check is a scheme nobody does check —
+ * this is the reference implementation, and the test for our own signing.
+ */
+export declare function verifySignature(input: {
+  secret: string;
+  body: string;
+  header: string;
+  nowSeconds: number;
+  toleranceSeconds?: number;
+}): boolean;
+/**
+ * How long to wait before attempt n, in milliseconds.
+ *
+ * Exponential, capped, with jitter. The jitter is the part that matters at
+ * scale: without it every delivery queued by the same outage retries at the
+ * same instant, and the receiver coming back up is knocked over by the
+ * thundering herd of everyone's retries.
+ */
+export declare function retryDelayMs(attempt: number, random: () => number): number;
+/** Eight attempts reach roughly 24 hours with this schedule. */
+export declare const MAX_ATTEMPTS = 8;
+//#endregion
+//#region src/uploads.d.ts
+/**
+ * The file lifecycle: offered, stored, claimed, collected.
+ *
+ * **Bytes are not the submission's problem.** A submission stores what each
+ * file is and where it went, never the bytes themselves, so a submission read
+ * back years later is small, self-describing, and still says what was attached
+ * even if the object store has since been emptied.
+ *
+ * **The claim happens inside the submission's transaction.** A submission
+ * exists if and only if the files it names are claimed against it. Anything
+ * looser gives one of the two failures nobody can debug: a rolled-back
+ * submission leaving files claimed against nothing, or an accepted submission
+ * referencing files the collector is about to delete.
+ *
+ * **Nothing here touches a disk.** This package has no filesystem and no
+ * object store; it decides what is rubbish and the host deletes it. That is
+ * the same split every other port here makes, and it is why the whole
+ * lifecycle is testable without either.
+ */
+interface OfferDeps {
+  storage: Storage;
+  now: () => Date;
+  newId: () => string;
+}
+interface OfferInput {
+  schema: FormSchema;
+  /** The form, for the access check — the same one a submission passes. */
+  form: FormRecord;
+  actor: 'anonymous' | 'authenticated';
+  origin: string | undefined;
+  /** The field the file is for, as a data path: `evidence`, `people[].passport`. */
+  field: string;
+  name: string;
+  size: number;
+  contentType: string;
+}
+type OfferOutcome = {
+  ok: true;
+  file: FileRecord;
+} | {
+  ok: false;
+  reason: 'not_allowed' | 'unknown_field' | 'not_a_file_field' | 'too_large' | 'not_accepted';
+};
+/**
+ * Agree where a file will go, and refuse it before a byte is sent.
+ *
+ * Checking here rather than after the upload is the difference between
+ * refusing a 2 GB file and receiving one first. The browser's own `accept` and
+ * size limits are a convenience for the person filling the form in; these are
+ * the rule, because somebody posting to the endpoint directly has neither.
+ */
+export declare function offerUpload(deps: OfferDeps, input: OfferInput): Promise<OfferOutcome>;
+type ClaimOutcome = {
+  ok: true;
+  ids: readonly string[];
+} | {
+  ok: false;
+  unknown: readonly string[];
+};
+/**
+ * Which files a submission may claim, checked but not yet claimed.
+ *
+ * The claiming itself is `insertSubmission`'s job, in the same call that
+ * stores the submission, so one COMMIT decides both — the same reasoning
+ * that put the webhook queue there. A submission exists if and only if the
+ * files it names belong to it. Claiming separately gives the two failures
+ * nobody can debug: a rolled-back submission leaving files claimed against
+ * nothing, or an accepted submission referencing bytes the collector is about
+ * to delete.
+ *
+ * Refuses rather than skips. A submission naming a file that does not exist,
+ * belongs to another form, or is already claimed is not a submission to fix up
+ * quietly: the first is a bug or somebody guessing ids; the second is how an
+ * id from a form you may submit to would let you attach a file from one you
+ * may not; the third would make deleting a submission either leak bytes or
+ * break a different one.
+ */
+export declare function filesToClaim(storage: Storage, input: {
+  schema: FormSchema;
+  formId: string;
+  data: unknown;
+}): Promise<ClaimOutcome>;
+/**
+ * Files nobody claimed, old enough that nobody is going to.
+ *
+ * Returns the rows rather than deleting anything: the host removes the bytes
+ * and then the rows, in that order, because a row without bytes is a broken
+ * reference and bytes without a row are invisible rubbish. Of the two, the
+ * second is the one you never find out about.
+ */
+export declare function collectAbandonedFiles(storage: Storage, now: Date, afterHours: number): Promise<FileRecord[]>;
+/** Re-exported so a host can see which paths a schema's file fields live at. */
+export declare function fileFieldPaths(schema: FormSchema): string[];
+//#endregion
+export { type Action, type Actor, type AttemptOutcome, type AuditAction, type AuditDraft, type AuditEntry, type AuthDeps, type AuthOutcome, type BreakerState, CHALLENGE_TTL_SECONDS, type Challenge, type ClaimOutcome, DEFAULT_MAX_NUMBER, type DeliveryHeaders, type DeliveryRecord, type DraftMigration, type DraftRecord, type FileRecord, type FormRecord, type FormVersionRecord, type ListedForm, type ListedSubmission, type ListedVersion, type MembershipOutcome, type OfferDeps, type OfferInput, type OfferOutcome, type OutboxDeps, type PublishOutcome, type ReplayOutcome, type ResolvedForm, type ResumeOutcome, type Role, type ServerDeps, type ServerOptionsSource, type ServerOptionsSources, type Solution, type Storage, type SubmissionOutcome, type SubmissionRecord, type UnsafePattern, type VerifyOutcome, type WebhookHealth, type WebhookRecord, decodeSolution, encodeSolution, hashOf, mintChallenge, solveChallenge, verifySolution };
 //# sourceMappingURL=index.d.mts.map