@toon-protocol/core 3.3.0 → 3.5.0

package/dist/wire/index.d.ts

@@ -0,0 +1,638 @@
+/**
+ * Canonical OER length primitives (RFC-0030), ported byte-for-byte from
+ * `connector_domain::oer` so the Rust and TypeScript fleets agree on the wire.
+ *
+ * "Canonical" is the whole point (ADR 0023): every value has exactly ONE
+ * encoding, and a decoder that quietly accepts a second spelling of the same
+ * value is a decoder two implementations can disagree through. So a
+ * determinant is refused unless the bytes it introduces are exactly what
+ * {@link encodeVarUint} would have produced:
+ *
+ * - `0x81 0x03` — a long form for `3`, which `0x03` already encodes — is
+ *   {@link OerErrorKind.NonCanonicalLength}, not `3`.
+ * - `0x80` — a zero-byte long form aliasing `0x00` — is
+ *   {@link OerErrorKind.NonCanonicalLength}, not `0`.
+ * - `0x89 …` — nine length bytes, which cannot fit a `u64` without silently
+ *   discarding the high-order ones — is
+ *   {@link OerErrorKind.LengthDeterminantOverflow}, not a truncated read.
+ *
+ * Values are `bigint` because the wire type is `u64` and `number` cannot hold
+ * one; the caller narrows.
+ *
+ * Pure: no I/O, no keys, no clock.
+ */
+/** The three, and only three, ways a length determinant can be refused. */
+declare enum OerErrorKind {
+    /** The buffer ends before the field it declares does. */
+    BufferUnderflow = "buffer_underflow",
+    /** A determinant that is not the minimal encoding of its own value. */
+    NonCanonicalLength = "non_canonical_length",
+    /** A determinant wider than eight bytes (cannot be a `u64`). */
+    LengthDeterminantOverflow = "length_determinant_overflow"
+}
+/** A refusal from the length primitives, carrying which of the three it is. */
+declare class OerError extends Error {
+    readonly kind: OerErrorKind;
+    constructor(kind: OerErrorKind);
+}
+/** Encode a VarUInt: `0..=127` as one byte, `128+` as a length-prefixed BE value. */
+declare function encodeVarUint(value: bigint): Uint8Array;
+/** A decoded field: its value, and how many bytes it consumed. */
+interface Decoded<T> {
+    value: T;
+    consumed: number;
+}
+/**
+ * Decode a VarUInt at `offset`, refusing any non-canonical spelling.
+ *
+ * @throws {OerError} and nothing else — arbitrary bytes never produce a
+ * `RangeError`, a `TypeError`, or a plausible-but-wrong value.
+ */
+declare function decodeVarUint(buf: Uint8Array, offset: number): Decoded<bigint>;
+/** Encode a VarOctetString: a VarUInt length prefix followed by the bytes. */
+declare function encodeVarOctetString(data: Uint8Array): Uint8Array;
+/**
+ * Decode a VarOctetString at `offset`.
+ *
+ * @throws {OerError} and nothing else.
+ */
+declare function decodeVarOctetString(buf: Uint8Array, offset: number): Decoded<Uint8Array>;
+
+/**
+ * The structured envelope (ADR 0018): what a packet carries between a
+ * connector and the app behind it, encoded with the same OER primitives an ILP
+ * packet already uses rather than as HTTP text.
+ *
+ * A faithful port of `connector_domain::envelope`
+ * (`crates/connector-domain/src/envelope.rs`) — a method, target, ordered
+ * headers and body going in; a two-byte big-endian status, headers and body
+ * coming back. `vectors/wire-vectors.json` is the contract this is checked
+ * against, and `wire-vectors.test.ts` is where that check happens; the prose
+ * here describes the same thing but the bytes decide.
+ *
+ * ─── Why not HTTP text ─────────────────────────────────────────────────────
+ * The hand-rolled HTTP text this replaces — building latin1 HTTP/1.1 request
+ * text, then parsing a status line and scanning for `\r\n\r\n` — is how such
+ * code acquires leniencies nobody chose: a missing header/body separator
+ * yielding an empty body, blank header lines skipped, spaces tolerated inside
+ * the target. A structured encoding has exactly one representation per message
+ * and nothing to smuggle.
+ *
+ * ─── Headers are a list, not a map ─────────────────────────────────────────
+ * A count prefix then `(name, value)` pairs in order. Both header ORDER and
+ * DUPLICATE NAMES are meaningful on this wire and both survive a round trip; a
+ * `Record<string, string>` would silently destroy each.
+ *
+ * Pure: no keys, no I/O, no clock. `@noble/*` is not involved.
+ */
+/**
+ * Every distinguishable way an envelope can fail to decode. These strings are
+ * the vector file's `expected_error` values verbatim — the same names
+ * `EnvelopeError` uses in `connector-domain` — so a replay compares reasons,
+ * not just "it threw".
+ *
+ * There is deliberately no catch-all: a decoder with an `Invalid` bucket is a
+ * decoder that can be lenient without anyone noticing.
+ */
+declare enum EnvelopeErrorKind {
+    /** The buffer ends before the envelope does. */
+    BufferUnderflow = "buffer_underflow",
+    /** A length determinant that is not the minimal encoding of its value. */
+    NonCanonicalLength = "non_canonical_length",
+    /** A length determinant wider than eight bytes. */
+    LengthDeterminantOverflow = "length_determinant_overflow",
+    /** The type byte is not the one the requested direction requires. */
+    InvalidType = "invalid_type",
+    /** A field that must be UTF-8 is not. */
+    InvalidUtf8 = "invalid_utf8",
+    /** Bytes remain after a fully decoded envelope. */
+    TrailingBytes = "trailing_bytes"
+}
+/**
+ * A refusal to decode. `kind` is the machine-readable reason; `field` names
+ * the offending field for {@link EnvelopeErrorKind.InvalidUtf8}, matching
+ * `EnvelopeError::InvalidUtf8(&'static str)` on the Rust side.
+ */
+declare class EnvelopeError extends Error {
+    readonly kind: EnvelopeErrorKind;
+    readonly field?: string | undefined;
+    constructor(kind: EnvelopeErrorKind, field?: string | undefined);
+}
+/** One `(name, value)` header, in wire order. Duplicates are legal. */
+type EnvelopeHeader = readonly [name: string, value: string];
+/** The request a connector is to make of the app behind a terminated route. */
+interface EnvelopeRequest {
+    method: string;
+    target: string;
+    headers: readonly EnvelopeHeader[];
+    body: Uint8Array;
+}
+/** The app's response back to the connector. */
+interface EnvelopeResponse {
+    /** HTTP status, two bytes big-endian on the wire (`0..=65535`). */
+    status: number;
+    headers: readonly EnvelopeHeader[];
+    body: Uint8Array;
+}
+/** Either direction, tagged — the shape the vector file's `decoded` carries. */
+type Envelope = ({
+    direction: 'request';
+} & EnvelopeRequest) | ({
+    direction: 'response';
+} & EnvelopeResponse);
+/** Encode a request envelope. The inverse of {@link decodeEnvelopeRequest}. */
+declare function encodeEnvelopeRequest(request: EnvelopeRequest): Uint8Array;
+/**
+ * Decode a request envelope, consuming the WHOLE buffer.
+ *
+ * @throws {EnvelopeError} and nothing else, for any input whatsoever.
+ */
+declare function decodeEnvelopeRequest(buf: Uint8Array): EnvelopeRequest;
+/** Encode a response envelope. The inverse of {@link decodeEnvelopeResponse}. */
+declare function encodeEnvelopeResponse(response: EnvelopeResponse): Uint8Array;
+/**
+ * Decode a response envelope, consuming the WHOLE buffer.
+ *
+ * @throws {EnvelopeError} and nothing else, for any input whatsoever.
+ */
+declare function decodeEnvelopeResponse(buf: Uint8Array): EnvelopeResponse;
+/** Encode either direction from its tagged form. */
+declare function encodeEnvelope(envelope: Envelope): Uint8Array;
+/**
+ * Decode as the named direction. The direction is an INPUT, never guessed from
+ * the type byte: a caller that asked for a request and got a response has been
+ * handed the wrong bytes, and `invalid_type` is the honest answer.
+ */
+declare function decodeEnvelope(buf: Uint8Array, direction: 'request' | 'response'): Envelope;
+
+/**
+ * The gift wrap (ADR 0018) and the fulfilment a shared secret derives (ADR
+ * 0019): the seal around the {@link ./envelope.js | envelope}, so a packet
+ * payload is readable only by the connector that terminates it and the
+ * preimage that pays for it needs no app participation.
+ *
+ * A faithful port of `connector_signer::giftwrap`
+ * (`crates/connector-signer/src/giftwrap.rs` on toon-protocol/connector `main`)
+ * and of `connector_domain::condition::derive_condition`
+ * (`crates/connector-domain/src/condition.rs:27`). `vectors/wire-vectors.json`'s
+ * `giftwrap` and `fulfilment` sections are the contract, replayed byte-for-byte
+ * in `wire-vectors.test.ts`; the prose here describes the same thing but the
+ * bytes decide.
+ *
+ * ─── The mechanism, as read off the Rust ────────────────────────────────────
+ * Recorded here because it cannot be inferred from the vector file's field
+ * names, and because the acceptance criterion for toon-client#449 asks for it
+ * in writing. Every line below is cited to
+ * `crates/connector-signer/src/giftwrap.rs` unless stated otherwise.
+ *
+ * - **Curve and ECDH.** The receiver's identity key is secp256k1; the value a
+ *   real connector reports from `GET /ilp/identity` is its 65-byte
+ *   uncompressed form (`0x04 ‖ X ‖ Y`). The sender ECDHs a fresh, per-packet
+ *   ephemeral key against it and uses the **raw X-coordinate** of the
+ *   resulting point — `crypto.rs`'s `ecdh_x_coordinate` does
+ *   `tweak_mul_assign` then `serialize_compressed()[1..]`, deliberately *not*
+ *   `libsecp256k1::SharedSecret`'s digest-mixing variant. So: not hashed, and
+ *   not the 33-byte compressed point.
+ * - **Key derivation.** `HKDF-SHA256`, **no salt** (`Hkdf::new(None, ikm)`,
+ *   i.e. HKDF-Extract with an all-zero salt), expanded to 32 bytes under one
+ *   of three fixed ASCII `info` strings — `giftwrap.rs`'s `hkdf_key`:
+ *   - `toon-giftwrap-request` — the request AEAD key, over the ECDH X.
+ *   - `toon-giftwrap-response` — the response AEAD key, over the shared secret.
+ *   - `toon-giftwrap-fulfillment` — the fulfilment, over the shared secret.
+ *     (American spelling on the wire; the vector *section* is `fulfilment`.)
+ *   These three strings are the only domain separation between two AEAD keys
+ *   and a payment preimage all derived from the same input, so one wrong
+ *   character silently yields bytes that decrypt nothing and satisfy no
+ *   condition.
+ * - **AEAD.** ChaCha20-Poly1305 (RFC 8439), 12-byte nonce, **no** additional
+ *   authenticated data.
+ * - **Request framing.** `0x01 ‖ ephemeral_public(65) ‖ nonce(12) ‖
+ *   ciphertext`, where the encrypted plaintext is `shared_secret(32) ‖
+ *   encoded_envelope`. The secret rides *inside* the sealed request, which is
+ *   what lets the response be sealed with no second key exchange.
+ * - **Response framing.** `0x02 ‖ nonce(12) ‖ ciphertext`, the plaintext being
+ *   just the encoded envelope. Sealed directly with the request's shared
+ *   secret.
+ * - **Fulfilment and condition.** `fulfilment = HKDF-SHA256(shared_secret,
+ *   "toon-giftwrap-fulfillment")`; the condition a sender mints is
+ *   `sha256(fulfilment)` — `condition.rs`'s `derive_condition`. A sender knows
+ *   the secret before it seals, so it can mint the condition first; the
+ *   terminating connector recovers the secret by opening the wrap and derives
+ *   the preimage without asking the app anything.
+ * - **Telling a sealed reject from a plaintext one.** The leading type byte,
+ *   and only that (`looks_like_sealed_response`). A reject raised short of the
+ *   termination shares no secret with the sender and carries empty `data`; an
+ *   empty `data` is never sealed, so a sealed reject is positive proof that
+ *   the destination itself said no.
+ *
+ * ─── Two failure modes, two types ───────────────────────────────────────────
+ * A wrap that cannot be OPENED throws {@link GiftWrapError}. A wrap that opens
+ * cleanly but whose recovered plaintext is not a valid envelope throws
+ * `EnvelopeError`, from `envelope.ts` — a different class entirely, raised
+ * above this module rather than by it. The Rust keeps the same separation
+ * (`GiftWrapError` vs `connector_domain::EnvelopeError`) for the same reason:
+ * "I could not read this" and "I read this and it was malformed" are different
+ * facts about a peer, and collapsing them loses the distinction at every call
+ * site.
+ *
+ * ─── Callers ────────────────────────────────────────────────────────────────
+ * In this package, `BootstrapService.announceViaIlp` (toon#143) is the sending
+ * direction: it seals to the connector that TERMINATES the destination and
+ * lets that connector derive the fulfilment (ADR 0019), via
+ * `wire/sealed-exchange.ts`. The receiving direction — a node that is itself
+ * the BTP destination, opening a request addressed to its own
+ * {@link giftWrapPublicKey} and sealing the answer back — is served by
+ * {@link openRequest}/{@link sealResponse} and lives in the consumers of this
+ * subpath rather than here.
+ */
+/** ChaCha20-Poly1305 nonce length. */
+declare const GIFTWRAP_NONCE_LENGTH = 12;
+/** The shared secret carried inside a sealed request, and the fulfilment. */
+declare const GIFTWRAP_SECRET_LENGTH = 32;
+/** The uncompressed secp256k1 public key a sealed request carries. */
+declare const GIFTWRAP_PUBLIC_KEY_LENGTH = 65;
+/** `TYPE_GIFTWRAP_REQUEST` — the leading byte of a sealed request. */
+declare const GIFTWRAP_TYPE_REQUEST = 1;
+/** `TYPE_GIFTWRAP_RESPONSE` — the leading byte of a sealed response. */
+declare const GIFTWRAP_TYPE_RESPONSE = 2;
+/**
+ * Every distinguishable way a wrap can fail to open — the four variants of
+ * `GiftWrapError` in `giftwrap.rs:57-71`, named the same way. There is
+ * deliberately no catch-all: this module must never be able to fail "somehow".
+ *
+ * None of these ever carries decrypted plaintext, matching the Rust's own
+ * guarantee.
+ */
+declare enum GiftWrapErrorKind {
+    /** The leading byte is not the one this direction requires. */
+    InvalidType = "invalid_type",
+    /** The bytes end before the framing does. */
+    Truncated = "truncated",
+    /** An ephemeral or receiver public key that is not a usable curve point. */
+    InvalidKey = "invalid_key",
+    /** The AEAD refused: wrong key, wrong nonce, or a tampered ciphertext. */
+    OpenFailed = "open_failed"
+}
+/**
+ * A refusal to open a wrap. `kind` is the machine-readable reason;
+ * `expectedType` names the type byte that was required, for
+ * {@link GiftWrapErrorKind.InvalidType} — mirroring
+ * `GiftWrapError::InvalidType(u8)`.
+ */
+declare class GiftWrapError extends Error {
+    readonly kind: GiftWrapErrorKind;
+    readonly expectedType?: number | undefined;
+    constructor(kind: GiftWrapErrorKind, expectedType?: number | undefined);
+}
+/**
+ * What sealing a request produces: the bytes to carry as `Prepare.data`, and
+ * the shared secret that both derives this packet's fulfilment and opens the
+ * answer. The sender must keep the secret — it is the only thing that opens
+ * the response, and the only thing that proves the fulfilment it is paid
+ * against was earned rather than guessed.
+ */
+interface SealedRequest {
+    /** `0x01 ‖ ephemeral_public(65) ‖ nonce(12) ‖ ciphertext`. */
+    readonly wrapped: Uint8Array;
+    /** The 32 random bytes sealed inside `wrapped`. */
+    readonly sharedSecret: Uint8Array;
+}
+/** What opening a sealed request recovers. */
+interface OpenedRequest {
+    /** The encoded envelope — feed to `decodeEnvelopeRequest`. */
+    readonly envelopeBytes: Uint8Array;
+    /** The 32-byte secret the sender chose, for the fulfilment and the answer. */
+    readonly sharedSecret: Uint8Array;
+}
+/**
+ * A key agreement that never hands out secret key material — the TypeScript
+ * counterpart of `giftwrap.rs`'s dependency on `Signer::ecdh`, and the reason
+ * {@link openRequest} takes this rather than a raw private key: a remote or
+ * hardware-backed identity can open a wrap without its key leaving its own
+ * boundary.
+ *
+ * Returns the raw 32-byte ECDH X-coordinate, or throws.
+ */
+interface GiftWrapEcdh {
+    ecdh(ephemeralPublicKey: Uint8Array): Uint8Array;
+}
+/**
+ * The ordinary local case of {@link GiftWrapEcdh}: a 32-byte secp256k1 secret
+ * key held in this process. `openRequest` accepts a bare key too and wraps it
+ * in this.
+ */
+declare function localGiftWrapEcdh(secretKey: Uint8Array): GiftWrapEcdh;
+/**
+ * The 65-byte uncompressed secp256k1 public key a `secretKey` opens gift
+ * wraps under — the counterpart {@link openRequest}/{@link localGiftWrapEcdh}
+ * derive their ECDH from, and the same format a real connector reports from
+ * `GET /ilp/identity` (`ConnectorIdentity.publicKey`). A caller publishes
+ * this as a `kind:31990` advertisement's `seal_pubkey` tag (toon-meta#266
+ * §3.1) so a buyer can seal a job's PREPARE `data` to it directly, without a
+ * `GET /identity` this client cannot serve (ADR 0022).
+ */
+declare function giftWrapPublicKey(secretKey: Uint8Array): Uint8Array;
+/**
+ * The deterministic core of {@link sealRequest}, parameterized on every value
+ * a real seal draws at random — the counterpart of the Rust's
+ * `seal_request_with_randomness`, which that crate gates behind a `test-util`
+ * feature for a reason worth repeating: **reusing a (key, nonce) pair under
+ * ChaCha20-Poly1305 is catastrophic**, so caller-supplied randomness is a
+ * footgun, not a convenience. Use {@link sealRequest} unless you are replaying
+ * a fixed vector.
+ *
+ * `receiverPublicKey` may be the 65-byte uncompressed form a connector's
+ * `GET /ilp/identity` reports, or the 33-byte compressed form; the ECDH result
+ * is the same point either way. The ephemeral key is always emitted
+ * uncompressed, because that is what the framing pins.
+ */
+declare function sealRequestWithRandomness(plaintext: Uint8Array, receiverPublicKey: Uint8Array, ephemeralSecretKey: Uint8Array, sharedSecret: Uint8Array, nonce: Uint8Array): Uint8Array;
+/**
+ * Seal `plaintext` (an encoded envelope) to `receiverPublicKey`. A fresh
+ * ephemeral key pair, shared secret and nonce are drawn for this call alone,
+ * so no two sealed requests — even to the same receiver, even with the same
+ * plaintext — share any of the three.
+ *
+ * Returns the wire bytes and the shared secret. Mint the packet's execution
+ * condition as {@link deriveCondition}({@link deriveFulfillment}(secret))
+ * before sending: the terminating connector recovers the same secret by
+ * opening this wrap, so the preimage it is paid against is one it derived, not
+ * one anybody handed it.
+ */
+declare function sealRequest(plaintext: Uint8Array, receiverPublicKey: Uint8Array): SealedRequest;
+/**
+ * Open a sealed request addressed to `identity`, recovering the encoded
+ * envelope and the shared secret carried alongside it.
+ *
+ * `identity` is either a 32-byte secp256k1 secret key or a {@link GiftWrapEcdh}
+ * that never exposes one. A node that is itself the BTP destination is the
+ * party that calls this for real. It also makes the seal testable from both
+ * ends — and the vectors' "opening it with the fixture's secret key must
+ * recover the envelope and the secret exactly" a check this repo can actually
+ * run.
+ */
+declare function openRequest(bytes: Uint8Array, identity: Uint8Array | GiftWrapEcdh): OpenedRequest;
+/**
+ * The deterministic core of {@link sealResponse}, parameterized on the nonce.
+ * Same footgun, same warning as {@link sealRequestWithRandomness}: a nonce
+ * reused under one shared secret destroys the confidentiality of both
+ * responses sealed with it.
+ */
+declare function sealResponseWithRandomness(sharedSecret: Uint8Array, plaintext: Uint8Array, nonce: Uint8Array): Uint8Array;
+/**
+ * Seal `plaintext` — an encoded response envelope, or a reject's diagnostic
+ * bytes — with the request's own `sharedSecret`. No second key exchange: the
+ * secret is bidirectional by construction, which is also why a sealed reject
+ * can only have come from the termination.
+ */
+declare function sealResponse(sharedSecret: Uint8Array, plaintext: Uint8Array): Uint8Array;
+/**
+ * Open a sealed response with the shared secret {@link sealRequest} returned
+ * for the request it answers. No signer, no key exchange, no identity key.
+ */
+declare function openResponse(sharedSecret: Uint8Array, bytes: Uint8Array): Uint8Array;
+/**
+ * Whether `bytes` is shaped like a sealed response — the leading type byte and
+ * nothing else, exactly as `looks_like_sealed_response` does it. This is how a
+ * sender tells a reject raised BY the destination from one raised on the way
+ * to it, without holding the secret to try opening it.
+ *
+ * Empty `data`, which every reject raised short of a termination carries, is
+ * never sealed.
+ */
+declare function looksLikeSealedResponse(bytes: Uint8Array): boolean;
+/**
+ * The fulfilment a request's shared secret derives (ADR 0019):
+ * `HKDF-SHA256(shared_secret, "toon-giftwrap-fulfillment")`, 32 bytes.
+ * Domain-separated by its own `info` string from both AEAD keys the same
+ * secret also derives, so it can never collide with either.
+ */
+declare function deriveFulfillment(sharedSecret: Uint8Array): Uint8Array;
+/**
+ * The condition a `fulfillment` satisfies: `sha256(fulfillment)` —
+ * `connector_domain::condition::derive_condition`. Hashing only ever runs in
+ * this direction; there is deliberately no function here that goes from a
+ * condition back to a fulfilment.
+ *
+ * The hash is the same one `wire/condition.ts` already uses; what ADR 0019
+ * changes is where the preimage comes from. `mintExecutionCondition` there
+ * draws a random preimage the sender must then carry to the FULFILL itself;
+ * here the preimage is DERIVED from the secret sealed inside the packet, so
+ * the terminating connector can produce it without the sender or the app
+ * handing it over. Checking a returned fulfilment against a condition is
+ * unchanged either way — use `fulfillmentMatchesCondition` from
+ * `wire/condition.ts` for that rather than a second copy of it here.
+ */
+declare function deriveCondition(fulfillment: Uint8Array): Uint8Array;
+
+/**
+ * Sender-chosen ILP execution conditions (toon-client#350, rolling-swap
+ * prerequisite — toon-meta#145 §3 R1/R2).
+ *
+ * Contract (normative: connector `docs/local-delivery-fulfillment-contract.md`,
+ * connector#309):
+ *   - An ABSENT or ALL-ZERO (32×0x00) `executionCondition` is the LEGACY
+ *     class: no hashlock, no verification — today's publish/upload writes.
+ *   - Any NON-ZERO condition is SENDER-CHOSEN: the sender mints a fresh
+ *     random 32-byte preimage `P` per packet, sets `C = sha256(P)` on the
+ *     PREPARE, and on FULFILL MUST verify that the returned fulfillment
+ *     hashes back to `C` — a missing/malformed/mismatching fulfillment is a
+ *     hard failure (the packet is counted failed, never silently accepted).
+ *
+ * Isomorphic: @noble/hashes only (no Buffer, no node:crypto).
+ */
+/** Exact byte length of an ILP execution condition / fulfillment preimage. */
+declare const CONDITION_LENGTH = 32;
+/** A freshly minted per-packet hashlock: `condition = sha256(preimage)`. */
+interface ExecutionConditionPair {
+    /** Random 32-byte preimage `P` — reveal is the commit act; never reuse. */
+    preimage: Uint8Array;
+    /** `C = sha256(P)` — goes on the PREPARE's `executionCondition`. */
+    condition: Uint8Array;
+}
+/**
+ * Mint a fresh random 32-byte preimage and its sha256 condition (spec R1).
+ * Mint one PER PACKET: a reused preimage lets any observer of packet *i*
+ * fulfill packet *i+1* without the sender's consent.
+ */
+declare function mintExecutionCondition(): ExecutionConditionPair;
+/**
+ * True when `condition` selects the LEGACY (unverified) class: absent or
+ * all-zero. The OER wire treats absent and 32×0x00 identically.
+ */
+declare function isZeroCondition(condition: Uint8Array | undefined): boolean;
+/**
+ * Validate a caller-supplied execution condition before it goes on the wire.
+ * @throws {Error} When the condition is not exactly 32 bytes — the OER
+ *   serializer would otherwise silently zero-fill it, downgrading a
+ *   sender-chosen packet to the legacy unverified class.
+ */
+declare function assertValidCondition(condition: Uint8Array): void;
+/**
+ * True iff `fulfillment` is exactly 32 bytes and `sha256(fulfillment)`
+ * equals `condition` — the sender-side FULFILL check (spec R6's mirror).
+ * Fail-closed: an undefined/short/long fulfillment never matches.
+ */
+declare function fulfillmentMatchesCondition(fulfillment: Uint8Array | undefined, condition: Uint8Array): boolean;
+
+/**
+ * One sealed request/answer exchange with a terminating connector (ADR 0018,
+ * ADR 0019, ADR 0020) — the whole shape of a packet's payload, from the
+ * envelope going out to the answer coming back, behind two functions.
+ *
+ * A sender's obligations on this wire are not independent of one another, and
+ * getting any of them separately wrong is silent:
+ *
+ * - The `data` is a gift wrap addressed to the connector that TERMINATES the
+ *   route, around an OER envelope — never HTTP text, never a bare payload.
+ * - The execution condition is `sha256` of the fulfilment DERIVED from the
+ *   very secret that wrap carries. A random condition would never be
+ *   fulfilled; an all-zero one is refused outright by the connector
+ *   (`connector-domain`'s `condition_is_present`), which is why the publish
+ *   path could not work against it at all before this module existed.
+ * - The answer is sealed with that same secret, so opening it requires having
+ *   kept it from the seal.
+ *
+ * {@link sealExchange} produces all three from one call so they cannot drift
+ * apart, and {@link readExchangeOutcome} is the only thing that reads the
+ * answer. The secret is the token joining them.
+ *
+ * ─── Why the outcome is a tagged union ─────────────────────────────────────
+ * ADR 0018 gives a sender something it never had: a REJECT sealed with the
+ * request's own secret can ONLY have come from the termination, because only
+ * the termination could recover that secret. A reject raised short of it is
+ * necessarily plaintext — an intermediate hop shares no secret and cannot
+ * seal. So "the destination said no" and "somebody on the path said no" are
+ * now genuinely different facts, and flattening both into one error string
+ * would throw away the distinction the seal was introduced to create.
+ *
+ * ADR 0020 draws the other line this union encodes: an HTTP status inside a
+ * response envelope is envelope CONTENT, not a packet outcome. A 404 arrives
+ * on a FULFILL and value moved. {@link ExchangeOutcome.Answered} therefore
+ * carries any status at all, and it is the caller's business — not this
+ * module's — whether a given status means its own operation succeeded.
+ *
+ * Pure: no I/O, no clock, no network. Randomness only through
+ * {@link sealRequest}.
+ */
+
+/**
+ * A sealed request, ready to become a PREPARE: what goes in `data`, what goes
+ * on `executionCondition`, and the secret needed to read the answer.
+ *
+ * The three are produced together and belong together. Sending `data` under a
+ * condition minted any other way produces a packet no honest connector can
+ * fulfil; opening the answer with any other secret fails.
+ */
+interface SealedExchange {
+    /** The gift wrap to carry as the PREPARE's `data`. */
+    readonly data: Uint8Array;
+    /**
+     * The PREPARE's `executionCondition`: `sha256(deriveFulfillment(secret))`.
+     * Derived, never random and never caller-supplied — the terminating
+     * connector recovers the same secret and derives the same fulfilment
+     * without the app participating (ADR 0019).
+     */
+    readonly condition: Uint8Array;
+    /**
+     * The 32-byte secret sealed inside the wrap. Keep it until the answer is
+     * read; it is the only thing that opens the response. Never send it
+     * anywhere else, and never reuse it for a second packet.
+     */
+    readonly sharedSecret: Uint8Array;
+    /**
+     * The fulfilment the terminating connector will return. Held so a caller
+     * can check the FULFILL preimage it actually got, rather than only that it
+     * hashes to the condition.
+     */
+    readonly fulfillment: Uint8Array;
+}
+/**
+ * How an exchange ended. Three outcomes, deliberately not two: a refusal's
+ * ORIGIN is the fact ADR 0018 makes knowable for the first time.
+ */
+type ExchangeOutcome = 
+/**
+ * The termination answered. `response` is whatever it said, at whatever
+ * status — a non-2xx here is a real answer that was paid for (ADR 0020),
+ * not a failure of the packet.
+ */
+{
+    readonly kind: 'answered';
+    readonly response: EnvelopeResponse;
+}
+/**
+ * The DESTINATION refused, provably: the reject's `data` was sealed with
+ * this exchange's own secret, which only the terminating connector could
+ * hold. `detail` is whatever it sealed alongside (often empty).
+ */
+ | {
+    readonly kind: 'destination-refused';
+    readonly code: string;
+    readonly message: string;
+    readonly detail: Uint8Array;
+}
+/**
+ * Somebody ON THE PATH refused — no route, expiry, a ceiling, a rejected
+ * claim — short of the termination, so nothing was sealed. Unauthenticated
+ * by construction: any hop can produce this, and it should be read as a
+ * hint, not a verdict from the destination.
+ */
+ | {
+    readonly kind: 'path-refused';
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Why an answer that arrived could not be read. Distinct from an
+ * {@link ExchangeOutcome}: these are not the destination's answer at all, but
+ * bytes that failed to be one.
+ */
+type SealedResponseErrorKind = 
+/** A FULFILL whose `data` is absent, or does not begin with the sealed-response type byte. */
+'not-sealed'
+/** The wrap is shaped right but does not open under this exchange's secret. */
+ | 'unopenable'
+/** It opened, and what came out is not a response envelope. */
+ | 'malformed-envelope';
+/** A refusal to read an answer. Never carries recovered plaintext. */
+declare class SealedResponseError extends Error {
+    readonly kind: SealedResponseErrorKind;
+    readonly cause?: Error | undefined;
+    constructor(kind: SealedResponseErrorKind, message: string, cause?: Error | undefined);
+}
+/**
+ * Seal `request` to `connectorPublicKey` — the identity of the connector that
+ * TERMINATES the destination, as read from its own client edge
+ * (`ConnectorEdgeClient`). Sealing to any other key is a confidentiality
+ * failure that presents as an undeliverable packet.
+ *
+ * @param request the envelope to seal.
+ * @param connectorPublicKey the terminating connector's 65-byte uncompressed
+ *   secp256k1 identity key.
+ */
+declare function sealExchange(request: EnvelopeRequest, connectorPublicKey: Uint8Array): SealedExchange;
+/**
+ * Read what came back.
+ *
+ * `accepted` distinguishes a FULFILL from a REJECT; `data` is the packet's
+ * payload bytes, absent when it carried none. Both come straight off the
+ * transport's result, so this stays testable without a socket.
+ *
+ * A FULFILL must be sealed and must decode: value moved, so bytes that are
+ * neither are a broken counterparty, and this throws rather than inventing an
+ * outcome. A REJECT is classified instead of thrown on — an unopenable one is
+ * simply a path reject that happened to carry bytes.
+ *
+ * @throws {SealedResponseError} for a FULFILL that is not a readable sealed
+ *   response envelope.
+ */
+declare function readExchangeOutcome(result: {
+    accepted: boolean;
+    code?: string;
+    message?: string;
+}, data: Uint8Array | undefined, sharedSecret: Uint8Array): ExchangeOutcome;
+/** Read a response header, case-insensitively; the first match wins. */
+declare function envelopeHeader(response: EnvelopeResponse, name: string): string | undefined;
+
+export { CONDITION_LENGTH, type Decoded, type Envelope, EnvelopeError, EnvelopeErrorKind, type EnvelopeHeader, type EnvelopeRequest, type EnvelopeResponse, type ExchangeOutcome, type ExecutionConditionPair, GIFTWRAP_NONCE_LENGTH, GIFTWRAP_PUBLIC_KEY_LENGTH, GIFTWRAP_SECRET_LENGTH, GIFTWRAP_TYPE_REQUEST, GIFTWRAP_TYPE_RESPONSE, type GiftWrapEcdh, GiftWrapError, GiftWrapErrorKind, OerError, OerErrorKind, type OpenedRequest, type SealedExchange, type SealedRequest, SealedResponseError, type SealedResponseErrorKind, assertValidCondition, decodeEnvelope, decodeEnvelopeRequest, decodeEnvelopeResponse, decodeVarOctetString, decodeVarUint, deriveCondition, deriveFulfillment, encodeEnvelope, encodeEnvelopeRequest, encodeEnvelopeResponse, encodeVarOctetString, encodeVarUint, envelopeHeader, fulfillmentMatchesCondition, giftWrapPublicKey, isZeroCondition, localGiftWrapEcdh, looksLikeSealedResponse, mintExecutionCondition, openRequest, openResponse, readExchangeOutcome, sealExchange, sealRequest, sealRequestWithRandomness, sealResponse, sealResponseWithRandomness };