@sackville-mcp/api 0.0.1-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,898 @@
+import { AssertionOp } from "@sackville-mcp/assert";
+import { DnsLookup, Redactor } from "@sackville-mcp/safety";
+import { FormData } from "undici";
+
+//#region src/artifacts.d.ts
+interface Artifact {
+  contentType: string;
+  body: string;
+}
+/**
+ * In-memory store for response bodies, addressed by a `sackville://run/<id>/body`
+ * handle. Agents/CLIs fetch bodies by handle so large payloads are never inlined
+ * into tool results. (A persistent backend can replace this later.)
+ */
+declare class ArtifactStore {
+  private artifacts;
+  put(runId: string, body: string, contentType: string): string;
+  get(handle: string): Artifact | undefined;
+}
+//#endregion
+//#region src/model.d.ts
+type AssertionSource = 'status' | 'statusText' | 'header' | 'body' | 'jsonpath' | 'responseTime' | 'schema';
+/** A declarative assertion (from a `*.sackville.yml` sidecar). */
+interface AssertionSpec {
+  source: AssertionSource;
+  op: AssertionOp;
+  value?: unknown;
+  /** JSONPath expression for source 'jsonpath'. */
+  path?: string;
+  /** Header name for source 'header'. */
+  name?: string;
+}
+/** Capture a value from a response into the runtime variable scope. */
+interface CaptureSpec {
+  var: string;
+  source: 'status' | 'header' | 'body' | 'jsonpath';
+  path?: string;
+  name?: string;
+}
+/** A multipart-form part: a `text` field or a `file` upload (by path). */
+interface MultipartPart {
+  name: string;
+  kind: 'text' | 'file';
+  /** Field value (text parts). */
+  value?: string;
+  /** Source path(s) on disk (file parts; Bruno allows multiple). */
+  filePaths?: string[];
+  /** Explicit per-part content type (file parts), when set. */
+  contentType?: string;
+}
+/** A raw file body — the file's bytes sent as the request body. */
+interface FileBody {
+  filePath: string;
+  contentType?: string;
+}
+/**
+ * A request body. Raw types (`json`/`text`/`xml`/`sparql`) carry `content`;
+ * `form-urlencoded` carries `params`; `graphql` carries a query + variables;
+ * `multipart-form` carries `parts`; `file` carries a single `file`.
+ */
+interface RequestBody {
+  type: string;
+  content?: string;
+  params?: {
+    name: string;
+    value: string;
+  }[];
+  graphql?: {
+    query: string;
+    variables?: string;
+  };
+  parts?: MultipartPart[];
+  file?: FileBody;
+}
+interface ApiRequest {
+  name: string;
+  method: string;
+  url: string;
+  headers: {
+    name: string;
+    value: string;
+  }[];
+  body?: RequestBody;
+}
+interface RequestEntry {
+  request: ApiRequest;
+  assertions: AssertionSpec[];
+  captures: CaptureSpec[];
+  /** Optional pre-request / post-response sandboxed scripts (from the sidecar). */
+  preScript?: string;
+  postScript?: string;
+}
+/** Result of a `test(name, fn)` in a sandboxed script. */
+interface ScriptTest {
+  name: string;
+  pass: boolean;
+  error?: string;
+}
+interface Collection {
+  dir: string;
+  requests: Map<string, RequestEntry>;
+  /** Environment name → its (non-secret) variables. */
+  environments: Map<string, Record<string, string>>;
+}
+interface AssertionResult {
+  source: AssertionSource;
+  op: AssertionOp;
+  path?: string;
+  name?: string;
+  expected?: unknown;
+  actual: unknown;
+  pass: boolean;
+}
+/** Contract-validation finding kinds (OpenAPI + GraphQL drift). */
+type ContractFindingKind = 'missing-operation' | 'undocumented-status' | 'response-schema' | 'graphql-syntax' | 'graphql-validation' | 'graphql-errors' | 'graphql-no-query' | 'request-body-schema' | 'missing-required-body' | 'undocumented-body' | 'unsupported-media-type' | 'missing-required-param' | 'param-schema' | 'undocumented-param' | 'graphql-variable-missing' | 'graphql-variable-invalid' | 'graphql-undocumented-variable';
+/** A single contract discrepancy between a response and its declared shape. */
+interface ContractFinding {
+  kind: ContractFindingKind;
+  message: string;
+  /** JSON Pointer / field path to the offending value, when applicable. */
+  path?: string;
+  severity: 'error' | 'warning';
+}
+/** Result of validating a response against a contract (OpenAPI/GraphQL). */
+interface ContractResult {
+  valid: boolean;
+  findings: ContractFinding[];
+  /** Matched OpenAPI operation (lowercased method + path template), when found. */
+  operation?: {
+    method: string;
+    path: string;
+  };
+}
+/** Resolves named secrets at the transport boundary. */
+interface SecretStore {
+  get(name: string): Promise<string | undefined>;
+}
+/** The request as prepared for the wire — headers/url here are REDACTED for
+ * agent-facing output (secret values never appear). */
+interface PreparedRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  /** Materialized body (redacted), if any. */
+  body?: string;
+}
+interface RunResponse {
+  status: number;
+  latencyMs: number;
+  headers: Record<string, string>;
+  assertions: AssertionResult[];
+  /** Results of `test(...)` calls in the post-response script (if any). */
+  scriptTests: ScriptTest[];
+  captured: Record<string, unknown>;
+  /** Resource handle for the response body — never inlined. */
+  bodyHandle: string;
+  /** Redirect hops followed before the final response (redacted locations).
+   * Empty when no redirect was followed. */
+  redirects?: {
+    status: number;
+    location: string;
+  }[];
+}
+interface RunResult {
+  /** What was (or, for a dry-run, would be) sent — redacted. */
+  request: PreparedRequest;
+  /** Whether the request was actually dispatched. */
+  sent: boolean;
+  /** True when a mutating request was withheld (dry-run). */
+  dryRun: boolean;
+  /** Why it was withheld, when applicable. */
+  reason?: string;
+  /** Present only when `sent`. */
+  response?: RunResponse;
+}
+//#endregion
+//#region src/assert.d.ts
+interface ResponseContext {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  bodyText: string;
+  json: unknown;
+  latencyMs: number;
+}
+/** Evaluate declarative assertions against a response. */
+declare function evaluateAssertions(specs: AssertionSpec[], ctx: ResponseContext): AssertionResult[];
+/** Extract captured variables from a response into a name→value map. */
+declare function extractCaptures(specs: CaptureSpec[], ctx: ResponseContext): Record<string, unknown>;
+//#endregion
+//#region src/collection.d.ts
+/**
+ * Load a Bruno collection directory: each `<name>.bru` request (+ optional
+ * `<name>.sackville.yml` sidecar), plus any `environments/<Env>.bru` files.
+ */
+declare function loadCollection(dir: string): Collection;
+//#endregion
+//#region src/contract.d.ts
+interface OpenApiResponse {
+  content?: Record<string, {
+    schema?: unknown;
+  }>;
+  [key: string]: unknown;
+}
+interface OpenApiOperation {
+  responses?: Record<string, OpenApiResponse>;
+  [key: string]: unknown;
+}
+interface OpenApiDoc {
+  paths?: Record<string, Record<string, OpenApiOperation> | undefined>;
+  components?: {
+    schemas?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+interface ResponseFacts {
+  status: number;
+  headers?: Record<string, string>;
+  body: unknown;
+}
+/**
+ * Validate a response against an OpenAPI 3.1 document. Returns structured
+ * findings; `valid` is true only when no `error`-severity finding is present.
+ */
+interface OpenApiValidateOptions {
+  /** Directory the spec was loaded from — enables external local-file `$ref`
+   * resolution (relative refs resolve against it). Omit to disable. */
+  baseDir?: string;
+}
+/** A resolved OpenAPI operation: the operation object, its path template, and the
+ * raw path-item (its method keys plus any path-level `parameters`). */
+interface ResolvedOperation {
+  operation: OpenApiOperation;
+  template: string;
+  pathItem: Record<string, unknown>;
+}
+/**
+ * Resolve `METHOD path` to its OpenAPI operation via path-template matching (shared
+ * by the response AND request validators — extracted so both resolve operations the
+ * same way). Returns `undefined` when no path template / method matches.
+ */
+declare function resolveOpenApiOperation(spec: OpenApiDoc, method: string, path: string): ResolvedOperation | undefined;
+/**
+ * Normalize an OpenAPI schema for ajv (2020-12) and return a self-contained schema
+ * with component schemas merged into `$defs`. Shared by the response AND request
+ * (body + parameter) validators so every schema gets the same treatment: external
+ * local-file `$ref` inlining (when `baseDir` is set), the OpenAPI 3.0 `nullable`→
+ * type-union shim, and the `#/components/schemas/X`→`#/$defs/X` rewrite. A schema's
+ * own local `$defs` win over component defs on a name clash.
+ */
+declare function normalizeOpenApiSchema(schema: unknown, spec: OpenApiDoc, opts?: OpenApiValidateOptions): Record<string, unknown>;
+declare function validateOpenApiResponse(spec: OpenApiDoc, req: {
+  method: string;
+  path: string;
+}, res: ResponseFacts, opts?: OpenApiValidateOptions): ContractResult;
+//#endregion
+//#region src/graphql.d.ts
+interface GraphqlValidateOptions {
+  /** Response payload to inspect for a top-level `errors` array. */
+  json?: unknown;
+  /** For a multi-operation document, scope the root-type drift check to this
+   * operation (and require it to exist). Without it, every operation is checked. */
+  operationName?: string;
+  /** The runtime variable values to validate against the operation's declared variable
+   * types (ADR 0015). Variable validation runs ONLY when this is provided (so existing
+   * query-vs-SDL-only callers are behavior-preserved). */
+  variables?: unknown;
+  /** Caller KNOWS the variable set is complete (direct surfaces hold the real request).
+   * Default false: an absent required variable is `unverified`, not a finding. */
+  variablesAuthoritative?: boolean;
+  /** Operator-supplied custom-scalar coercers, keyed by scalar name (ADR 0018). A registered
+   * scalar's VARIABLE values become checkable (the coercer throws on definite invalidity);
+   * document literals are NEVER routed through coercers (the `parseLiteral` leak guard, §3).
+   * Built-in scalar names are silently ignored (§8.5). Operator-set — never an agent input;
+   * the MCP surface selects coercers by NAME against an operator-bound registry. */
+  scalarCoercers?: Record<string, ScalarCoercer>;
+}
+/**
+ * A custom-scalar coercer (ADR 0018). Throws (any error) to reject a value as definitely
+ * invalid; the return value is IGNORED — only throw/no-throw is the signal. MUST throw ONLY on
+ * definite invalidity (indeterminate ⇒ do not throw, so an uncertain value never false-fires).
+ * Applies to VARIABLE values only — document literals are never routed through a coercer.
+ */
+type ScalarCoercer = (value: unknown) => unknown;
+interface GraphqlValidationResult extends ContractResult {
+  /** A variable set the validator could not check (custom-scalar-typed variables, a
+   * non-object `variables`, an ambiguous multi-operation target, or an absent required
+   * variable the caller is not authoritative about) — OR a custom-scalar directive-arg
+   * literal (ADR 0018 D2). Additive/optional — the verdict shape is UNCHANGED; the capture
+   * bridge folds this into `noSignal` so it can never become a pass (absence-is-never-a-pass).
+   * Omitted when everything relevant was verifiable. */
+  unverified?: boolean;
+  /** The `unverified` flag was (at least partly) caused by a custom-scalar directive-arg
+   * LITERAL (ADR 0018 D2), as distinct from an unverifiable variable. Additive/optional; lets
+   * the capture bridge bump the distinct `graphql-directive-unverified` summary key (ADR 0018
+   * §8.4) instead of mislabeling it `graphql-variable-unverified`. Omitted otherwise. */
+  directiveUnverified?: boolean;
+}
+/**
+ * Validate a GraphQL `query` against a schema `sdl`; if `opts.json` is supplied,
+ * also check the response payload for returned `errors`. With `opts.operationName`
+ * the root-type drift check is scoped to that operation (which must exist). When
+ * `opts.variables` is supplied, the runtime variable values are validated against the
+ * operation's declared types (ADR 0015). `valid` is true only when no `error`-severity
+ * finding is present.
+ */
+declare function validateGraphqlOperation(sdl: string, query: string, opts?: GraphqlValidateOptions): GraphqlValidationResult;
+//#endregion
+//#region src/har-capture.d.ts
+/** A captured HTTP exchange reduced to the facts the validator needs. */
+interface CaptureEntry {
+  req: {
+    method: string;
+    path: string;
+    origin: string;
+    /**
+     * The parsed JSON request body, when the request carried a JSON `postData`
+     * (attach `_file` first, inline `text` fallback). Needed for GraphQL drift:
+     * the operation `query` lives in the request, not the response (ADR 0013 §5).
+     */
+    body?: unknown;
+    /** Decoded request query params (repeated keys → array). Captured for
+     * request-side contract validation (slice 4a); only set when non-empty. */
+    query?: Record<string, string | string[]>; /** Lower-cased request header names → value (last wins). Only set when present. */
+    headers?: Record<string, string>;
+    /** Decoded TEXT fields of a `form`-style request body (form-urlencoded /
+     * multipart text parts) from HAR `postData.params[]` (repeated keys → array;
+     * urlencoded `text` fallback). The authoritative-source rule still holds: the
+     * capture path drives the validator NON-authoritatively (ADR 0016 addendum 4). */
+    form?: Record<string, string | string[]>;
+    /** NAMES of multipart FILE parts (a `postData.params` entry with `fileName`);
+     * bytes never enter the facts. */
+    formFileFields?: string[];
+  };
+  res: ResponseFacts;
+  /** Lower-cased response content-type (sans parameters), e.g. `application/json`. */
+  mimeType: string;
+  /**
+   * Set when an attached body referenced by `_file` could not be resolved or
+   * JSON-parsed — surfaced as a HARD finding by the driver, never an empty-body
+   * pass (ADR 0013 slice 2).
+   */
+  unresolvedBody?: string;
+}
+/**
+ * Slice 2 — parse a HAR `.zip` and resolve each entry's body. The PRIMARY path
+ * is `content:'attach'` (the only mode the browser pillar emits): a body lives
+ * in a separate archive entry referenced by `response.content._file`. Inline
+ * `response.content.text` (`content:'embed'`) is the fallback. JSON bodies are
+ * parsed; the URL is reduced to its `pathname` (+ origin kept separately).
+ */
+declare function harEntriesToFacts(harZip: Buffer): CaptureEntry[];
+/** Slice 3 — only JSON responses from allowed origins are routed to the validator. */
+interface CaptureFilterOptions {
+  /** When set, only entries whose request origin is in this list are considered. */
+  allowedOrigins?: string[];
+}
+interface OpenApiSpec {
+  servers?: Array<{
+    url?: string;
+  }>;
+  paths?: Record<string, Record<string, unknown> | undefined>;
+  [key: string]: unknown;
+}
+/** The GraphQL half of a capture contract (ADR 0013 §5 discriminated input). */
+interface GraphqlContract {
+  /** The full request pathname that serves GraphQL, e.g. `/graphql`. */
+  endpointPath: string;
+  /** The schema SDL captured operations are validated against (drift detection). */
+  sdl: string;
+}
+/**
+ * The discriminated contract a captured run is validated against. Supply
+ * `openapi` (REST), `graphql` (GraphQL), or both. A captured entry is routed to
+ * exactly one validator; a GraphQL entry never falls through to the OpenAPI
+ * validator (which would flood `missing-operation`), and an entry with no
+ * matching contract half is **no-signal**, never a pass (ADR 0013 §1/§5).
+ */
+interface CaptureContract {
+  openapi?: OpenApiSpec;
+  graphql?: GraphqlContract;
+}
+/** The rolled-up contract sub-verdict over a captured run (ADR 0013 §1/§5). */
+interface CaptureContractVerdict {
+  /** Entries actually routed to the validator (JSON, allowed origin). */
+  entriesValidated: number;
+  /** Per-`ContractFindingKind` finding counts across all entries (+ `unresolved-body`). */
+  findingsByKind: Record<string, number>;
+  /** The first entry that failed validation, for a fast headline. */
+  firstFailing?: {
+    method: string;
+    path: string;
+    kind: string;
+    message: string;
+  };
+  /** `METHOD /template` for every documented op an entry exercised — the inverse-of-drift signal. */
+  exercisedOperations: string[];
+  /** Documented ops NO captured entry hit. */
+  unexercisedOperations: string[];
+  /** Per-entry validator results (finding messages already redacted). */
+  results: ContractResult[];
+  /** Entries whose attached body could not be resolved/parsed (never a pass). */
+  unresolvedBodies: number;
+  /**
+   * Entries we could NOT verify because no matching contract half was supplied —
+   * a GraphQL call with no SDL (`graphql-sdl-not-supplied`), or a REST call with
+   * no OpenAPI spec (`no-contract-for-entry`). Counted, never a pass (ADR 0013 §1).
+   */
+  noSignal: number;
+  /**
+   * `true` only when at least one entry was validated, every result is valid, no
+   * body was unresolved, AND no entry was no-signal. Absence is never a pass
+   * (ADR 0013 §1) — an unverifiable GraphQL/REST call can't make a run clean.
+   */
+  clean: boolean;
+}
+interface ValidateCaptureOptions extends CaptureFilterOptions {
+  /** Redacts finding messages before they leave the bridge (ADR 0013 §3b). */
+  redact?: (value: string) => string;
+  /** Spec dir for external local-file `$ref` resolution (passed to the validator). */
+  baseDir?: string;
+}
+/**
+ * Slice 5 (+ ADR 0013 §5 GraphQL) — drive each captured JSON entry through the
+ * matching shipped validator. A GraphQL entry (matched by the contract's
+ * `endpointPath` or the JSON `{query}` shape) goes to `validateGraphqlOperation`
+ * and NEVER to the OpenAPI validator; a REST entry goes to
+ * `validateOpenApiResponse` and feeds the exercised/unexercised drift walk. An
+ * entry with no matching contract half is no-signal (never a pass). Every finding
+ * message is routed through the operator `Redactor`; our own summary paths use the
+ * matched operation template / operator-supplied endpoint, never a raw captured path.
+ */
+declare function validateCapturedTraffic(harZip: Buffer, contract: CaptureContract, opts?: ValidateCaptureOptions): CaptureContractVerdict;
+//#endregion
+//#region src/har-synth.d.ts
+/** Compact tallies over a parsed HAR; tolerant of a malformed/empty log. */
+interface HarCounts {
+  entryCount: number;
+  byStatus: Record<string, number>;
+  byMethod: Record<string, number>;
+}
+/** Parse the `.har` JSON into compact tallies; tolerant of a malformed/empty log. */
+declare function summarizeHar(harJson: string): HarCounts;
+/**
+ * The blanket-redaction pass over a HAR `.zip` Buffer (PURE — no file I/O). Unzips,
+ * collects the text-like attach `_file` bodies by DECLARED mimeType (so a body stored
+ * under a non-text filename is still scrubbed), redacts every text member — the `.har`
+ * JSON + text-extension bodies + those attach bodies — and re-zips. A genuinely binary
+ * member passes through byte-for-byte. Shared by the browser pillar's `finalizeHar`
+ * (file wrapper) and api synthesis (in-memory), so they share ONE redaction code path.
+ */
+declare function redactHarZip(zip: Buffer, redact: (value: string) => string): Buffer;
+/**
+ * One captured HTTP exchange (a single request OR a single redirect hop) reduced to
+ * what {@link synthesizeRedactedHarZip} needs. The runner's produce channel
+ * (`runRequestForHar`, slice 4) emits one of these per hop — so a redirect chain
+ * becomes one HAR entry per hop, never a collapsed chain (ADR 0013 Addendum 4 gap a).
+ * Bodies are STRING-only: a Buffer/FormData (file/multipart) request body leaves
+ * `reqBody` undefined ⇒ no `postData` is synthesized (lossless — the response still
+ * validates; gap b's GraphQL path needs only string JSON bodies anyway).
+ */
+interface HarHopRecord {
+  method: string;
+  url: string;
+  /** The real numeric HTTP status. A missing status is INCOMPLETE capture and THROWS
+   * (never coerced to 0, which the bridge would read as an undocumented-status finding —
+   * a false fail masking the true inconclusive state). */
+  status: number;
+  resContentType?: string;
+  /** The real (secret-bearing) response body text; redacted by {@link redactHarZip}. */
+  resBody?: string;
+  reqContentType?: string;
+  /** The real (secret-bearing) request body text (GraphQL's `query` lives here). */
+  reqBody?: string;
+}
+/**
+ * Synthesize a HAR `.zip` Buffer from per-hop records and IMMEDIATELY redact it — the
+ * ONLY public surface, so no un-redacted synthesized buffer is ever returned/stored/
+ * validated (ADR 0013 §3b). Builds `{log:{entries}}` with ONLY the six fields the
+ * consume bridge reads, INLINE `text` bodies (we hold the strings — no `_file` attach),
+ * one `.har` member, then runs {@link redactHarZip}. THROWS on a status-less record.
+ */
+declare function synthesizeRedactedHarZip(records: HarHopRecord[], redact: (value: string) => string): Buffer;
+//#endregion
+//#region src/request-contract.d.ts
+/** The request facts a validator reads. `path` is the pathname only (matches
+ * `CaptureEntry.req.path`); `body` is the already-parsed JSON body. */
+interface RequestFacts {
+  method: string;
+  path: string;
+  body?: unknown;
+  query?: Record<string, string | string[]>;
+  /** Lower-cased header names → value. */
+  headers?: Record<string, string>;
+  /** Decoded fields of a `form`-style body (`application/x-www-form-urlencoded` or the
+   * text parts of `multipart/form-data`); repeated keys → array. The AUTHORITATIVE
+   * structured channel for non-JSON body validation (ADR 0016 addendum 4) — populated at
+   * prepare time from the structured parts, NEVER by re-parsing the serialized string.
+   * File-part bytes never enter this map. */
+  form?: Record<string, string | string[]>;
+  /** Field NAMES of `multipart/form-data` FILE parts (bytes never inlined — redaction).
+   * A declared schema property satisfied by a file part is `unverified`-skipped. */
+  formFileFields?: string[];
+}
+interface OpenApiRequestValidateOptions extends OpenApiValidateOptions {
+  /** Caller KNOWS body presence/absence is authoritative (direct surfaces). Default
+   * false: an absent required body is `unverified`, not `missing-required-body`. */
+  bodyPresenceAuthoritative?: boolean;
+  /** Caller KNOWS query/header facts are complete (direct surfaces). Default false:
+   * an absent required query/header param is `unverified`, not a finding. */
+  paramsAuthoritative?: boolean;
+}
+interface RequestValidationResult extends ContractResult {
+  /** A body/param the validator could not verify and the caller is not authoritative
+   * about. The capture bridge folds this into `noSignal` (never a finding, never a
+   * pass). Omitted when everything relevant was verifiable. */
+  unverified?: boolean;
+}
+/** True when a parsed body looks like a GraphQL-over-HTTP envelope (`{query: string,
+ * …}`). A direct surface uses this to refuse running OpenAPI body validation on a
+ * GraphQL request (which has no REST requestBody shape) — H4. */
+declare function isGraphqlEnvelope(body: unknown): boolean;
+declare function validateOpenApiRequest(spec: OpenApiDoc, req: RequestFacts, opts?: OpenApiRequestValidateOptions): RequestValidationResult;
+//#endregion
+//#region src/runner.d.ts
+interface RunOptions {
+  /** Variable scope for `{{var}}` interpolation. */
+  vars?: Record<string, unknown>;
+  /** Name of a collection environment whose vars seed the scope (lowest precedence). */
+  env?: string;
+  /** Secret store for `{{secret:NAME}}` resolution (defaults to env). */
+  secrets?: SecretStore;
+  /** Artifact store for the response body (a fresh one is used if omitted). */
+  artifacts?: ArtifactStore;
+  /** Opt in to actually sending mutating requests. */
+  allowUnsafe?: boolean;
+  /** Hostnames a mutating request may reach. */
+  allowedHosts?: string[];
+  /** Permit loopback/private SSRF targets (default true; see `assertSsrfAllowed`).
+   * Set false to block all private ranges, not just metadata/link-local. */
+  allowPrivate?: boolean;
+  /** Injectable DNS resolver for the SSRF pre-flight (tests). */
+  lookup?: DnsLookup;
+  /** Maximum redirect hops to follow (default 0 = don't follow; return the 3xx).
+   * Every hop is re-checked: SSRF range-block + the mutation host-allowlist. */
+  maxRedirects?: number;
+}
+/**
+ * The PRODUCE-only out-of-band capture channel (ADR 0013 Addendum 4, 5f): the raw
+ * per-hop request/response facts a synthesized HAR is built from, plus the run-resolved
+ * secret pairs the union redactor must learn. NEVER attached to `RunResult` — raw bodies
+ * stay structurally off anything an agent sees; only `runRequestForHar` exposes it, and
+ * its consumer ({@link synthesizeRedactedHarZip} via the verify driver) redacts before
+ * store + validate.
+ */
+interface HarCapture {
+  hops: HarHopRecord[];
+  registeredSecrets: {
+    name: string;
+    value: string;
+  }[];
+  /** The terminal response was still a 3xx (budget exhausted / unparseable / missing
+   * Location): the exchange did not complete to a resource ⇒ the driver throws
+   * (inconclusive), never validates a truncated chain. */
+  redirectTruncated: boolean;
+}
+/**
+ * Execute one request: resolve vars + secrets, apply the mutation safety gate
+ * (mutating methods dry-run unless explicitly unlocked), dispatch via undici if
+ * allowed, evaluate assertions, and return a result whose surfaced strings
+ * (request, response headers, body artifact) are all secret-redacted.
+ */
+declare function runRequest(collection: Collection, name: string, opts?: RunOptions): Promise<RunResult>;
+/**
+ * Drive a request AND retain the raw per-hop facts a synthesized HAR is built from
+ * (ADR 0013 Addendum 4, 5f) — the verify-driven api capture path. `RunResult` is
+ * returned UNCHANGED (still fully redacted); `capture` is the produce-only raw channel
+ * (never on `RunResult`). The caller (verify driver) folds `capture.registeredSecrets`
+ * into a union redactor, then synthesizes + redacts + validates.
+ */
+declare function runRequestForHar(collection: Collection, name: string, opts?: RunOptions): Promise<{
+  result: RunResult;
+  capture: HarCapture;
+}>;
+/**
+ * The out-of-band channel surfacing the UN-redacted {@link RequestFacts} a contract
+ * validator reads (method, pathname, decoded query, lower-cased headers, JSON-parsed
+ * body), plus the run-resolved secret pairs a downstream redactor must learn to scrub
+ * findings. Mirrors {@link HarCapture}: NEVER attached to `RunResult` (which stays fully
+ * redacted), and populated at PREPARE time so it is available even when the request is
+ * withheld (dry-run / gated). Consumed by `api run --openapi`'s request-side validation
+ * (ADR 0014).
+ */
+interface ContractRequestCapture {
+  request: RequestFacts;
+  registeredSecrets: {
+    name: string;
+    value: string;
+  }[];
+}
+/**
+ * Drive a request AND retain the un-redacted request facts a contract validator reads
+ * (ADR 0014). `RunResult` is returned UNCHANGED (still fully redacted); `capture` is the
+ * raw channel (never on `RunResult`). The caller (`api run --openapi`) folds
+ * `capture.registeredSecrets` into a redactor, validates `capture.request` against the
+ * contract, then redacts the findings before surfacing them.
+ */
+declare function runRequestForContract(collection: Collection, name: string, opts?: RunOptions): Promise<{
+  result: RunResult;
+  capture: ContractRequestCapture;
+}>;
+//#endregion
+//#region src/secrets.d.ts
+/** In-memory store (tests / explicit injection). */
+declare class StaticSecretStore implements SecretStore {
+  private readonly values;
+  constructor(values?: Record<string, string>);
+  get(name: string): Promise<string | undefined>;
+}
+/**
+ * Reads `<prefix><NAME>` from the environment — the zero-dependency default
+ * (Linux/CI). The default prefix is `SACKVILLE_SECRET_`; the aggregate server
+ * overrides it to `SACKVILLE_API_SECRET_` so the api pillar's secrets live in its
+ * own namespace and can't be read via a bare, shared name (ADR 0019).
+ */
+declare class EnvSecretStore implements SecretStore {
+  private readonly env;
+  private readonly prefix;
+  constructor(env?: Record<string, string | undefined>, prefix?: string);
+  get(name: string): Promise<string | undefined>;
+}
+/** OS keychain via @napi-rs/keyring (macOS/Windows/Linux-desktop). The native
+ * module is loaded lazily through a non-literal specifier so importing this file
+ * never loads it; Secret Service can throw at runtime in headless containers, so
+ * failures resolve to undefined. */
+declare class KeyringSecretStore implements SecretStore {
+  private readonly service;
+  constructor(service?: string);
+  get(name: string): Promise<string | undefined>;
+}
+/** Try each store in order, first hit wins. */
+declare class ChainedSecretStore implements SecretStore {
+  private readonly stores;
+  constructor(stores: SecretStore[]);
+  get(name: string): Promise<string | undefined>;
+}
+/**
+ * Default store: keyring (opt-in) chained ahead of env, else env only.
+ * `env`/`envPrefix` override the environment source + variable prefix the
+ * `EnvSecretStore` reads (the aggregate server passes `SACKVILLE_API_SECRET_`).
+ */
+declare function resolveSecretStore(opts?: {
+  keyring?: boolean;
+  env?: Record<string, string | undefined>;
+  envPrefix?: string;
+}): SecretStore;
+//#endregion
+//#region src/sequence.d.ts
+interface SequenceOptions extends RunOptions {
+  /** Stop the sequence if a request's assertions fail. */
+  stopOnFailure?: boolean;
+}
+interface SequenceStep {
+  name: string;
+  result: RunResult;
+}
+interface SequenceResult {
+  steps: SequenceStep[];
+  /** Variables captured across the whole sequence (threaded forward). */
+  captured: Record<string, unknown>;
+}
+/**
+ * Run requests in order, threading each response's captured variables into the
+ * scope of the requests that follow (request chaining). Per-run options
+ * (secrets, allowUnsafe, allowlist, artifacts) apply to every request; the
+ * variable scope is the shared, accumulating one.
+ */
+declare function runSequence(collection: Collection, names: string[], opts?: SequenceOptions): Promise<SequenceResult>;
+/**
+ * Like {@link runSequence} but ALSO retains the raw per-hop capture across every step
+ * (ADR 0013 Addendum 4, 5f) — for the verify-driven api capture path. Each step's
+ * `SequenceStep.result` is UNCHANGED (redacted); `capture` aggregates all hops + the
+ * union of run-resolved secret pairs. The transport-completeness guard (every
+ * `step.result.sent`) lives in the driver, which folds a non-sent step to inconclusive.
+ */
+declare function runSequenceForHar(collection: Collection, names: string[], opts?: SequenceOptions): Promise<{
+  result: SequenceResult;
+  capture: HarCapture;
+}>;
+//#endregion
+//#region src/har-produce.d.ts
+/** The minimal artifact store the driver writes the redacted HAR to — satisfied by the
+ * verify-prefix `@sackville-mcp/artifacts` `ArtifactStore` (kept structural so `@sackville-mcp/api`
+ * needn't depend on `@sackville-mcp/artifacts`). */
+interface HarArtifactSink {
+  put(runId: string, kind: string, body: string | Buffer, contentType: string): string;
+}
+/** Compact HAR summary (shape-compatible with `@sackville-mcp/browser` `HarSummary`). */
+interface ProducedHarSummary {
+  handle: string;
+  byteSize: number;
+  entryCount: number;
+  byStatus: Record<string, number>;
+  byMethod: Record<string, number>;
+}
+interface ProducedHar {
+  /** `<store-prefix>://<id>/har` — the redacted, stored HAR archive, by handle. */
+  harHandle: string;
+  summary: ProducedHarSummary;
+  /** The FULL contract verdict (incl. `clean`/`noSignal`/`unresolvedBodies`) so the
+   * downstream fold can hold "absence is never a pass" on the contract dimension. */
+  verdict: CaptureContractVerdict;
+}
+interface HarProduceDeps {
+  store: HarArtifactSink;
+  /** The union redactor (verify ∪ api seed); the driver folds in the run-resolved
+   * secrets and uses it at BOTH chokepoints (synthesize + validate). */
+  redactor: Redactor;
+  contract: CaptureContract;
+  validate?: {
+    baseDir?: string;
+    allowedOrigins?: string[];
+  };
+  idFactory?: () => string;
+  /** Injected so the gate suite needn't fetch. */
+  runForHar?: typeof runRequestForHar;
+  runSequenceForHar?: typeof runSequenceForHar;
+}
+/** Drive ONE request → synthesize + validate its HAR. Throws (⇒ inconclusive) when the
+ * request was not sent (withheld/dry-run/blocked) or its redirect chain was truncated. */
+declare function runRequestToHar(collection: Collection, name: string, opts: RunOptions, deps: HarProduceDeps): Promise<ProducedHar>;
+/** Drive a SEQUENCE → synthesize + validate the aggregated HAR. Throws (⇒ inconclusive)
+ * when ANY step was not sent (per `step.result.sent`) or any hop truncated a redirect. */
+declare function runSequenceToHar(collection: Collection, names: string[], opts: SequenceOptions, deps: HarProduceDeps): Promise<ProducedHar>;
+//#endregion
+//#region src/import.d.ts
+type ImportFormat = 'postman' | 'insomnia' | 'openapi' | 'har';
+/** Normalized request, format-agnostic. */
+interface ImportedRequest {
+  name: string;
+  method: string;
+  url: string;
+  headers: {
+    name: string;
+    value: string;
+  }[];
+  body?: ImportedBody;
+}
+interface ImportedBody {
+  /** Canonical body type: json | text | xml | form-urlencoded | graphql. */
+  type: string;
+  /** Raw content (json/text/xml). */
+  content?: string;
+  /** form-urlencoded params. */
+  params?: {
+    name: string;
+    value: string;
+  }[];
+  /** graphql query + variables. */
+  graphql?: {
+    query: string;
+    variables?: string;
+  };
+}
+interface ImportResult {
+  requests: ImportedRequest[];
+  /** A discovered environment (e.g. OpenAPI `servers[0]`), if any. */
+  environment?: {
+    name: string;
+    variables: Record<string, string>;
+  };
+}
+/** Postman v2.1 collection → requests (folders flattened, depth-first). */
+declare function importPostman(doc: unknown): ImportResult;
+/** Insomnia v4 export → requests. */
+declare function importInsomnia(doc: unknown): ImportResult;
+/** OpenAPI 3.x → one request per operation + an environment for the server URL. */
+declare function importOpenApi(doc: unknown): ImportResult;
+/** HAR → one request per logged entry. */
+declare function importHar(doc: unknown): ImportResult;
+/** Parse a source document (JSON, or YAML for OpenAPI) into normalized requests. */
+declare function parseImport(format: ImportFormat, source: string): ImportResult;
+interface WriteOptions {
+  /** Collection name written to `bruno.json`. */
+  name?: string;
+}
+/**
+ * Write a normalized import to `destDir` as a Bruno collection: `bruno.json`, a
+ * `<name>.bru` per request, and (if present) an `environments/<env>.bru`. Returns
+ * the request count written.
+ */
+declare function writeImported(destDir: string, result: ImportResult, opts?: WriteOptions): number;
+/** One-shot: parse a source document and write the Bruno collection to disk. */
+declare function importToCollection(format: ImportFormat, source: string, destDir: string, opts?: WriteOptions): number;
+//#endregion
+//#region src/prepare.d.ts
+interface PreparedBody {
+  /** Content-Type to set when the request carries none; `undefined` lets undici
+   * set it itself (e.g. multipart, which needs a generated boundary). */
+  contentType?: string;
+  /** The payload handed to undici. */
+  content: string | Buffer | FormData;
+  /** A redaction-safe textual rendering of the body for agent-facing output
+   * (binary/file content is summarized, never inlined). */
+  preview: string;
+  /** For `form`-style bodies (form-urlencoded / multipart): the decoded TEXT fields
+   * (repeated keys → array) — the AUTHORITATIVE structured channel for non-JSON body
+   * contract validation (ADR 0016 addendum 4). Built from the structured parts at
+   * prepare time, NEVER by re-parsing `content`; file bytes never enter it. */
+  formFields?: Record<string, string | string[]>;
+  /** For multipart bodies: the NAMES of FILE parts (bytes are never inlined). */
+  formFileFields?: string[];
+}
+/** A request prepared for the wire — these strings carry REAL secret values. */
+interface Prepared {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: PreparedBody;
+}
+/**
+ * Resolve `{{secret:NAME}}` (from the store, registered with the redactor) and
+ * `{{var}}` (from the scope) across the URL, headers, AND body into the actual
+ * values sent on the wire. Fails closed on an unresolved secret.
+ */
+declare function prepareRequest(request: ApiRequest, scope: Record<string, unknown>, secrets: SecretStore, redactor: Redactor, baseDir?: string): Promise<Prepared>;
+//#endregion
+//#region src/safety.d.ts
+interface SafetyOptions {
+  /** Opt in to actually sending mutating requests. */
+  allowUnsafe?: boolean;
+  /** Hostnames a mutating request is permitted to reach. */
+  allowedHosts?: string[];
+}
+interface SafetyDecision {
+  allowed: boolean;
+  reason: string;
+}
+declare function isMutating(method: string): boolean;
+/**
+ * Decide whether a request may actually be sent. Safe methods always may.
+ * Mutating methods are withheld (dry-run) unless explicitly unlocked
+ * (`allowUnsafe`) AND the target host is on the allowlist — never silently fired.
+ */
+declare function checkGate(method: string, host: string, opts?: SafetyOptions): SafetyDecision;
+//#endregion
+//#region src/schema.d.ts
+/** A single schema violation, located by JSON Pointer into the instance. */
+interface SchemaError {
+  /** JSON Pointer to the offending value ('' = document root). */
+  instancePath: string;
+  message: string;
+}
+interface SchemaValidation {
+  valid: boolean;
+  errors: SchemaError[];
+}
+/** Validate `data` against a JSON Schema. Never throws on data; an invalid
+ * *schema* surfaces as a single error rather than propagating. */
+declare function validateSchema(schema: unknown, data: unknown): SchemaValidation;
+//#endregion
+//#region src/script.d.ts
+interface ScriptResponseView {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+  json: unknown;
+}
+interface ScriptResult {
+  /** The full variable scope after the script ran (incl. `bru.setVar` writes). */
+  vars: Record<string, unknown>;
+  tests: ScriptTest[];
+  logs: string[];
+  /** A top-level (non-`test`) error thrown by the script, if any. */
+  error?: string;
+}
+/**
+ * Run a pre/post-request script in a QuickJS WASM sandbox with the curated
+ * `bru`/`expect`/`test`/`console` API and a wall-clock interrupt. The script
+ * sees `res` (post-response only) and reads/writes variables via `bru`; nothing
+ * from the host process is reachable.
+ */
+declare function runScript(code: string, context: {
+  vars: Record<string, unknown>;
+  res?: ScriptResponseView;
+}): Promise<ScriptResult>;
+//#endregion
+//#region src/vars.d.ts
+/**
+ * Interpolate `{{name}}` placeholders from a variable scope. Unknown names are
+ * left intact (so callers can detect them). Secret resolution is layered on
+ * later, at the transport boundary.
+ */
+declare function interpolate(template: string, scope: Record<string, unknown>): string;
+//#endregion
+export { type ApiRequest, type Artifact, ArtifactStore, type AssertionOp, type AssertionResult, type AssertionSource, type AssertionSpec, type CaptureContract, type CaptureContractVerdict, type CaptureEntry, type CaptureFilterOptions, type CaptureSpec, ChainedSecretStore, type Collection, type ContractFinding, type ContractFindingKind, type ContractRequestCapture, type ContractResult, EnvSecretStore, type GraphqlContract, type GraphqlValidateOptions, type GraphqlValidationResult, type HarArtifactSink, type HarCapture, type HarCounts, type HarHopRecord, type HarProduceDeps, type ImportFormat, type ImportResult, type ImportedRequest, KeyringSecretStore, type OpenApiDoc, type OpenApiRequestValidateOptions, type OpenApiValidateOptions, type Prepared, type PreparedBody, type PreparedRequest, type ProducedHar, type ProducedHarSummary, Redactor, type RequestBody, type RequestEntry, type RequestFacts, type RequestValidationResult, type ResolvedOperation, type ResponseContext, type ResponseFacts, type RunOptions, type RunResponse, type RunResult, type SafetyDecision, type SafetyOptions, type ScalarCoercer, type SchemaError, type SchemaValidation, type ScriptResponseView, type ScriptResult, type ScriptTest, type SecretStore, type SequenceOptions, type SequenceResult, type SequenceStep, StaticSecretStore, type ValidateCaptureOptions, checkGate, evaluateAssertions, extractCaptures, harEntriesToFacts, importHar, importInsomnia, importOpenApi, importPostman, importToCollection, interpolate, isGraphqlEnvelope, isMutating, loadCollection, normalizeOpenApiSchema, parseImport, prepareRequest, redactHarZip, resolveOpenApiOperation, resolveSecretStore, runRequest, runRequestForContract, runRequestForHar, runRequestToHar, runScript, runSequence, runSequenceForHar, runSequenceToHar, summarizeHar, synthesizeRedactedHarZip, validateCapturedTraffic, validateGraphqlOperation, validateOpenApiRequest, validateOpenApiResponse, validateSchema, writeImported };
+//# sourceMappingURL=index.d.mts.map