@agirails/sdk 4.4.8 → 4.5.2

package/dist/delivery/envelopeBuilder.d.ts

@@ -0,0 +1,531 @@
+/**
+ * AIP-16 Delivery Surface — Provider Envelope Builder + Verifier + Decryptor (Phase 2b)
+ * =======================================================================================
+ *
+ * Constructs and verifies the provider-signed `DeliveryEnvelopeV1` payload —
+ * the load-bearing artifact of the AIP-16 Rev 5 delivery surface. The
+ * provider posts this signed object to the delivery channel after the
+ * buyer's setup is received (and after the on-chain transaction reaches
+ * `COMMITTED`), carrying:
+ *
+ *  - the EIP-712 binding to a specific kernel, chain, and `txId`,
+ *  - the on-chain identity acting as the provider, plus the EOA that
+ *    signed (smart-wallet two-step auth),
+ *  - the cryptographic scheme used to protect the body (`public-v1` or
+ *    `x25519-aes256gcm-v1`),
+ *  - the provider's ephemeral X25519 pubkey (encrypted scheme) or
+ *    canonical-empty bytes32 (public scheme),
+ *  - the AES-256-GCM nonce + tag (encrypted) or canonical-empty
+ *    bytes12 / bytes16 (public),
+ *  - `payloadHash = keccak256(bodyBytes)` — the on-chain anchor for the
+ *    exact bytes the buyer will receive,
+ *  - the body bytes themselves (alongside the signed projection, in the
+ *    wire envelope).
+ *
+ * ## Body encoding (SCHEME-AWARE — FIX-1, AIP-16 Phase 3.5)
+ *
+ * The wire encoding is scheme-dependent so the SDK and the Platform
+ * verifier (`Platform/agirails.app/web/lib/delivery/auth.ts`) hash the
+ * SAME bytes in BOTH locations:
+ *
+ *  - `public-v1`: `wire.body = JSON.stringify(payload)` — plaintext
+ *    UTF-8 JSON string, NOT hex. `payloadHash = keccak256(utf8Bytes(body))`.
+ *    The Platform verifier computes `keccak256(toUtf8Bytes(body))`
+ *    directly on the wire body. Hex-encoding the plaintext here would
+ *    make the Platform recompute `keccak256(utf8Bytes("0x7b22…"))` —
+ *    a different digest — and every public envelope would 400 with
+ *    `payload_hash_mismatch`.
+ *
+ *  - `x25519-aes256gcm-v1`: `wire.body = "0x" + hex(aesGcmCiphertext)`.
+ *    `payloadHash = keccak256(rawCiphertextBytes)`. The Platform
+ *    verifier hex-decodes `wire.body` and then keccak256s the bytes.
+ *    Ciphertext is a byte string that does NOT round-trip through UTF-8
+ *    (it contains arbitrary 0..255 bytes incl. 0x00 and high bits),
+ *    so hex is the only safe text encoding — base64 would also work but
+ *    AIP-16 standardizes on hex for cross-language SDK consistency.
+ *
+ * Rationale for the asymmetry:
+ *  1. **Public payloads are already text.** JSON serializes to valid
+ *     UTF-8 — no encoding wrapper needed. The plaintext IS the wire.
+ *  2. **Ciphertext is binary.** Cannot travel naked in JSON; hex is the
+ *     chosen text encoding (matches `nonce`, `tag`, `payloadHash`,
+ *     `providerEphemeralPubkey`).
+ *  3. **Spec match.** AIP-16 §6.2 sign-side and the Platform verify-
+ *     side both implement this exact rule.
+ *
+ * ## Builder shape (matches DeliverySetupBuilder)
+ *
+ *  - `constructor(signer?)` — signer required for `build*()`, optional
+ *    for `verify()` / `computeHash()` / `decryptPayload()`. The static
+ *    helpers do not consult builder state.
+ *  - `buildPublic(params)` / `buildEncrypted(params)` are `async`
+ *    because EIP-712 signing on real wallets is async.
+ *  - `verify`, `decryptPayload`, `verifyAndDecrypt`, `computeHash` are
+ *    `static` — mirrors {@link DeliverySetupBuilder} and the existing
+ *    delivery-proof / quote builders.
+ *
+ * ## Smart-wallet two-step auth (DEC-10 / V2 receipts)
+ *
+ * `providerAddress` (on-chain participant — possibly a Smart Wallet)
+ * and `signerAddress` (the EOA that actually signed) are accepted
+ * SEPARATELY. The SDK does NOT derive one from the other; the smart-
+ * wallet equality check
+ *   computeSmartWalletFromSigner(signerAddress) === providerAddress
+ * is the SERVER'S responsibility (cross-vendor factory ABI agnostic).
+ *
+ * What the SDK enforces in `build*()` is the cheaper invariant:
+ *   `signerAddress === await signer.getAddress()`.
+ *
+ * ## payloadHash defends against body-after-sign tamper
+ *
+ * Because `payloadHash = keccak256(bodyBytes)` is part of the SIGNED
+ * EIP-712 projection, any post-signature mutation of `wire.body`
+ * causes `bodyHash(wire.body)` to diverge from `signed.payloadHash`.
+ * The verifier short-circuits with `envelope_payload_hash_mismatch`
+ * before signature recovery, so a malicious relay cannot swap bodies
+ * even within an otherwise valid signed envelope.
+ *
+ * ## Verification order (first failure short-circuits)
+ *
+ *   1. `validateEnvelopeWire(wire)` — structural shape, types, lengths,
+ *      and scheme/canonical-empty consistency in one pass.
+ *   2. `validateSchemeConsistency(signed)` — defense-in-depth re-check
+ *      (already covered by step 1 but called explicitly so future
+ *      refactors of the validator do not silently weaken the contract).
+ *   3. `signed.chainId === expectedChainId` → `envelope_chain_mismatch`.
+ *   4. `signed.kernelAddress` (lc) === `expectedKernelAddress` (lc)
+ *      → `envelope_kernel_mismatch`.
+ *   5. `bodyHash(wire.body) === signed.payloadHash`
+ *      → `envelope_payload_hash_mismatch`.
+ *   6. `recoverEnvelopeSigner(signed, providerSig, expectedKernel)`
+ *      (lc) === `signed.signerAddress` (lc)
+ *      → `envelope_signature_invalid`.
+ *   7. `|now - signed.createdAt| <= ENVELOPE_TIMESTAMP_SKEW_SEC`
+ *      → `envelope_timestamp_skew`.
+ *
+ * Note that timestamp skew is checked LAST — a forged signature is a
+ * more severe error than a stale-but-genuine envelope and we want the
+ * caller to see the more severe failure first.
+ *
+ * @module delivery/envelopeBuilder
+ * @see ./types — signed/wire interfaces and {@link BuildEnvelopeResult}.
+ * @see ./eip712 — domain, types, and {@link recoverEnvelopeSigner}.
+ * @see ./validate — {@link validateEnvelopeWire},
+ *      {@link validateSchemeConsistency}.
+ * @see ./keys — X25519 keygen + ECDH + HKDF.
+ * @see ./crypto — AES-256-GCM seal/open + {@link bodyHash}.
+ * @see ./setupBuilder — sibling builder; same shape conventions.
+ */
+import { type Signer } from 'ethers';
+import { type EphemeralKeyPair } from './keys';
+import { type BuildEnvelopeResult, type DeliveryEnvelopeSignedV1, type DeliveryEnvelopeWireV1 } from './types';
+/**
+ * Maximum tolerated clock-skew, in seconds, between the signed
+ * `createdAt` and the verifier's wall clock. Symmetric (past + future).
+ *
+ * 900s (15 min) matches {@link DeliverySetupBuilder}'s
+ * `SETUP_TIMESTAMP_SKEW_SEC`, the receipts-V2 freshness window, and
+ * the AIP-3 anchor-receipt skew bound.
+ */
+export declare const ENVELOPE_TIMESTAMP_SKEW_SEC = 900;
+/**
+ * Length (in bytes) of the AES-256-GCM AAD used by the encrypted
+ * scheme — `txId_bytes (32) || signerAddress_bytes (20) = 52`.
+ *
+ * H5 binding: GCM authenticates the AAD; a misrouted envelope (correct
+ * ciphertext + nonce + tag + sessionKey, but delivered as if for a
+ * different `txId` or `signerAddress`) fails the tag check on decrypt.
+ * The hash-input `payloadHash` in the EIP-712 signature already binds
+ * the body to a specific `txId` at the signature layer; this AAD adds
+ * the same binding INSIDE the GCM authentication, defense-in-depth.
+ *
+ * Bytes layout (network byte order, no padding):
+ *  - [0..32):  `txId` raw 32 bytes (from the 0x + 64 hex chars).
+ *  - [32..52): `signerAddress` raw 20 bytes (from the 0x + 40 hex chars).
+ */
+export declare const ENVELOPE_AAD_LENGTH: 52;
+/**
+ * Construct the AES-256-GCM AAD for the `x25519-aes256gcm-v1` scheme.
+ *
+ * Format: `txId (32 bytes) || signerAddress (20 bytes) = 52 bytes`.
+ *
+ * Both the build side (in {@link DeliveryEnvelopeBuilder.buildEncrypted})
+ * and the decrypt side (in {@link DeliveryEnvelopeBuilder.decryptPayload})
+ * call this helper with the SAME txId/signerAddress so the GCM tag
+ * commits to identical AAD bytes. Address case is normalized via
+ * `bytesFromHex` (which is case-insensitive on the hex characters), so
+ * checksum vs lowercase inputs round-trip to the same 20 raw bytes.
+ *
+ * @param txId - On-chain transaction id, `0x` + 64 hex chars.
+ * @param signerAddress - EOA address, `0x` + 40 hex chars.
+ * @returns 52-byte AAD buffer (`txId_bytes || signerAddress_bytes`).
+ * @throws {DeliveryCryptoError} `crypto_decrypt_failed` if either
+ *   parameter has the wrong byte length (decoded via `bytesFromHex`
+ *   from `./crypto`); the underlying helper raises this code.
+ *
+ * @internal Used by the envelope builder; exposed for cross-SDK
+ * fixtures and the H5 test suite.
+ */
+export declare function buildEnvelopeAad(txId: `0x${string}`, signerAddress: `0x${string}`): Uint8Array;
+/**
+ * Replace the wall-clock implementation used inside this module.
+ *
+ * **TEST-ONLY.** Production code MUST NOT call this. Pass `null` (or
+ * call {@link resetSecondsNowForTests}) to restore the real-clock
+ * implementation.
+ *
+ * @param impl - Replacement function returning Unix seconds, or `null`
+ *   to restore the default real-clock implementation.
+ */
+export declare function setSecondsNowForTests(impl: (() => number) | null): void;
+/**
+ * Restore {@link secondsNow} to its default real-clock implementation.
+ *
+ * **TEST-ONLY.** Safe to call when no override is active.
+ */
+export declare function resetSecondsNowForTests(): void;
+/**
+ * Parameters accepted by {@link DeliveryEnvelopeBuilder.buildPublic}.
+ *
+ * Every address is passed explicitly — no implicit derivation of one
+ * address from another. `providerAddress` and `signerAddress` are
+ * separate so the SDK is agnostic to which Smart Wallet factory the
+ * caller is using.
+ */
+export interface BuildPublicEnvelopeParams {
+    /**
+     * On-chain transaction id this envelope is bound to.
+     * 32-byte hex (`0x` + 64 hex chars). MUST equal the corresponding
+     * setup's `txId`.
+     */
+    txId: `0x${string}`;
+    /**
+     * EVM chain id (e.g. `8453` for Base mainnet, `84532` for Base Sepolia).
+     * Encoded into BOTH the EIP-712 domain and the signed payload.
+     */
+    chainId: number;
+    /**
+     * Address of the ACTP kernel contract on `chainId`. Becomes the
+     * EIP-712 `verifyingContract`.
+     */
+    kernelAddress: `0x${string}`;
+    /**
+     * On-chain identity acting as the provider. Smart-wallet flows pass
+     * the Smart Wallet address here; non-smart-wallet flows pass the EOA.
+     * The SDK does NOT derive this from `signer`.
+     */
+    providerAddress: `0x${string}`;
+    /**
+     * EOA address that will produce the signature. MUST equal
+     * `await signer.getAddress()` — `buildPublic()` enforces this and
+     * throws on mismatch.
+     */
+    signerAddress: `0x${string}`;
+    /**
+     * The actual deliverable payload. Any JSON-serializable value.
+     * `buildPublic` will `JSON.stringify(payload)` and treat the UTF-8
+     * bytes of the resulting string as the body bytes.
+     */
+    payload: unknown;
+    /**
+     * Override the `createdAt` timestamp. Defaults to {@link secondsNow}.
+     * Tests SHOULD pass an explicit value here for determinism rather
+     * than relying on {@link setSecondsNowForTests}.
+     */
+    createdAt?: number;
+    /**
+     * CoinbaseSmartWallet factory nonce used to derive `providerAddress`
+     * from `signerAddress`. Defaults to `0` (the first wallet per owner).
+     *
+     * H4 fix (AIP-16 Phase 3 HIGH): providers whose Smart Wallet was
+     * deployed at a non-zero factory nonce MUST pass that nonce here so
+     * the server's smart-wallet derivation lands on the correct address.
+     *
+     * Must be a non-negative integer; `buildPublic()` rejects negatives
+     * with `BUILDER_INVALID_SMART_WALLET_NONCE`.
+     */
+    smartWalletNonce?: number;
+}
+/**
+ * Parameters accepted by {@link DeliveryEnvelopeBuilder.buildEncrypted}.
+ *
+ * Extends {@link BuildPublicEnvelopeParams} with the buyer's ephemeral
+ * pubkey (from the corresponding setup) and an optional override for
+ * the provider's own ephemeral keypair (tests use this for determinism;
+ * production callers SHOULD omit it).
+ */
+export interface BuildEncryptedEnvelopeParams {
+    /** See {@link BuildPublicEnvelopeParams.txId}. */
+    txId: `0x${string}`;
+    /** See {@link BuildPublicEnvelopeParams.chainId}. */
+    chainId: number;
+    /** See {@link BuildPublicEnvelopeParams.kernelAddress}. */
+    kernelAddress: `0x${string}`;
+    /** See {@link BuildPublicEnvelopeParams.providerAddress}. */
+    providerAddress: `0x${string}`;
+    /** See {@link BuildPublicEnvelopeParams.signerAddress}. */
+    signerAddress: `0x${string}`;
+    /**
+     * The actual deliverable payload. Any JSON-serializable value.
+     * `buildEncrypted` will `JSON.stringify(payload)`, UTF-8 encode, then
+     * AES-256-GCM seal under the X25519+HKDF-derived session key.
+     */
+    payload: unknown;
+    /**
+     * The buyer's ephemeral X25519 public key (32 bytes, hex), copied
+     * from the corresponding `DeliverySetupSignedV1.buyerEphemeralPubkey`.
+     * `buildEncrypted` runs ECDH with this and the provider's own
+     * ephemeral private key to derive the shared secret.
+     *
+     * MUST NOT be {@link CANONICAL_EMPTY_BYTES32} — the canonical-empty
+     * value is reserved for the public scheme.
+     */
+    buyerEphemeralPubkey: `0x${string}`;
+    /**
+     * Override for the provider's ephemeral X25519 keypair. When omitted
+     * (the production path), a fresh keypair is generated via
+     * {@link generateEphemeralKeyPair}.
+     *
+     * **TEST-ONLY in practice.** Production callers SHOULD let the
+     * builder generate the keypair so the private key never crosses a
+     * call boundary; passing one in increases the risk of accidental
+     * persistence.
+     */
+    providerEphemeralKeyPair?: EphemeralKeyPair;
+    /**
+     * Override the `createdAt` timestamp. Defaults to {@link secondsNow}.
+     */
+    createdAt?: number;
+    /**
+     * CoinbaseSmartWallet factory nonce used to derive `providerAddress`
+     * from `signerAddress`. Defaults to `0` (the first wallet per owner).
+     *
+     * H4 fix (AIP-16 Phase 3 HIGH): symmetric to
+     * {@link BuildPublicEnvelopeParams.smartWalletNonce}. Allows providers
+     * with non-zero-nonce Smart Wallets to authenticate.
+     */
+    smartWalletNonce?: number;
+}
+/**
+ * Builder + verifier + decryptor for AIP-16 delivery envelopes.
+ *
+ * Instances are cheap to construct and have no I/O side effects.
+ * `verify()`, `decryptPayload()`, `verifyAndDecrypt()`, and
+ * `computeHash()` are static — call them without constructing an
+ * instance.
+ *
+ * @example Provider build (public)
+ * ```typescript
+ * const builder = new DeliveryEnvelopeBuilder(wallet);
+ * const { wire } = await builder.buildPublic({
+ *   txId, chainId: 84532, kernelAddress: KERNEL,
+ *   providerAddress: SMART_WALLET, signerAddress: EOA,
+ *   payload: { result: 'ok' },
+ * });
+ * await postToRelay(wire);
+ * ```
+ *
+ * @example Provider build (encrypted)
+ * ```typescript
+ * const { wire, blobKey } = await builder.buildEncrypted({
+ *   txId, chainId: 84532, kernelAddress: KERNEL,
+ *   providerAddress: SMART_WALLET, signerAddress: EOA,
+ *   payload: { secret: 'data' },
+ *   buyerEphemeralPubkey: setupSigned.buyerEphemeralPubkey,
+ * });
+ * ```
+ *
+ * @example Buyer decrypt
+ * ```typescript
+ * const result = await DeliveryEnvelopeBuilder.verifyAndDecrypt(
+ *   wire,
+ *   buyerEphemeralPrivKey,
+ *   { expectedKernelAddress: KERNEL, expectedChainId: 84532 },
+ * );
+ * if (!result.ok) throw new Error(result.code);
+ * const payload = result.payload;
+ * ```
+ */
+export declare class DeliveryEnvelopeBuilder {
+    private readonly signer?;
+    /**
+     * Construct a new builder.
+     *
+     * @param signer - EOA signer required for {@link buildPublic} and
+     *   {@link buildEncrypted}. Pass `undefined` for a verify-/decrypt-only
+     *   instance; all verification / decryption helpers are static and
+     *   do not consult builder state.
+     */
+    constructor(signer?: Signer);
+    /**
+     * Construct, sign, and return a {@link DeliveryEnvelopeWireV1} using
+     * the `public-v1` scheme.
+     *
+     * Encoding (FIX-1, AIP-16 Phase 3.5):
+     *  - `bodyString = JSON.stringify(params.payload)`.
+     *  - `wire.body = bodyString` (plaintext UTF-8 JSON, NOT hex).
+     *  - `payloadHash = keccak256(utf8Bytes(bodyString))`.
+     *  - The Platform verifier recomputes `keccak256(toUtf8Bytes(body))`
+     *    on the wire body directly, so the SDK and verifier hash the
+     *    same bytes byte-for-byte.
+     *
+     * Canonical-empty enforcement:
+     *  - `providerEphemeralPubkey = CANONICAL_EMPTY_BYTES32`.
+     *  - `nonce = CANONICAL_EMPTY_BYTES12`.
+     *  - `tag = CANONICAL_EMPTY_BYTES16`.
+     *
+     * Pre-checks:
+     *  - signer MUST be present.
+     *  - `signerAddress` MUST equal `await signer.getAddress()`.
+     *
+     * @param params - {@link BuildPublicEnvelopeParams}.
+     * @returns A {@link BuildEnvelopeResult} carrying the signed wire
+     *   envelope and the raw plaintext bytes (`bodyBytes`) that the
+     *   `payloadHash` was computed over. `blobKey` is `undefined` for
+     *   the public scheme.
+     * @throws {DeliveryEip712Error} on signer absence or signer/address
+     *   mismatch.
+     */
+    buildPublic(params: BuildPublicEnvelopeParams): Promise<BuildEnvelopeResult>;
+    /**
+     * Construct, sign, and return a {@link DeliveryEnvelopeWireV1} using
+     * the `x25519-aes256gcm-v1` scheme.
+     *
+     * Crypto flow:
+     *  1. Generate (or accept) a provider ephemeral X25519 keypair.
+     *  2. `shared = X25519(providerPriv, buyerPub)`.
+     *  3. `sessionKey = HKDF-SHA256(ikm=shared, salt=txId, info="agirails-delivery-v1", L=32)`.
+     *  4. `plaintextBytes = utf8Bytes(JSON.stringify(payload))`.
+     *  5. `{ciphertext, nonce, tag} = AES-256-GCM(plaintextBytes, sessionKey)`.
+     *  6. `wire.body = bytesToHex(ciphertext)`.
+     *  7. `payloadHash = keccak256(ciphertext)`.
+     *  8. Sign the EIP-712 projection containing `scheme = "x25519-aes256gcm-v1"`,
+     *     the provider's ephemeral pubkey, the AES-GCM nonce + tag, and
+     *     `payloadHash`.
+     *
+     * The provider's ephemeral PRIVATE key is dropped after step 5;
+     * forward secrecy w.r.t. provider long-term keys is provided by the
+     * fresh keypair per delivery.
+     *
+     * Pre-checks:
+     *  - signer MUST be present.
+     *  - `signerAddress` MUST equal `await signer.getAddress()`.
+     *  - `buyerEphemeralPubkey` MUST NOT be {@link CANONICAL_EMPTY_BYTES32}.
+     *
+     * @param params - {@link BuildEncryptedEnvelopeParams}.
+     * @returns A {@link BuildEnvelopeResult} carrying the signed wire
+     *   envelope, the ciphertext bytes (`bodyBytes`) the `payloadHash`
+     *   was computed over, and the symmetric session `blobKey` (for
+     *   provider-side observability / future reference-mode flows; the
+     *   buyer derives the key independently).
+     * @throws {DeliveryEip712Error} on signer absence, signer/address
+     *   mismatch, or canonical-empty buyer pubkey.
+     */
+    buildEncrypted(params: BuildEncryptedEnvelopeParams): Promise<BuildEnvelopeResult>;
+    /**
+     * Verify a {@link DeliveryEnvelopeWireV1} received from the relay.
+     *
+     * See the module-level header for the full check ordering and rationale.
+     *
+     * @param wire - The wire envelope received from the relay.
+     * @param opts.expectedKernelAddress - Trusted kernel address for the
+     *   target chain (from the verifier's allowlist).
+     * @param opts.expectedChainId - Trusted chainId for the target chain.
+     * @param opts.now - Override for the verifier's wall clock (Unix
+     *   seconds). Tests use this for deterministic timestamp-skew paths;
+     *   production callers SHOULD omit.
+     * @returns `{ ok: true, signed }` on success, `{ ok: false, code, error }`
+     *   on failure.
+     */
+    static verify(wire: DeliveryEnvelopeWireV1, opts: {
+        expectedKernelAddress: string;
+        expectedChainId: number;
+        now?: number;
+    }): {
+        ok: true;
+        signed: DeliveryEnvelopeSignedV1;
+    } | {
+        ok: false;
+        code: string;
+        error: string;
+    };
+    /**
+     * Decrypt the payload of an `x25519-aes256gcm-v1` envelope using the
+     * buyer's ephemeral private key.
+     *
+     * Does NOT verify the EIP-712 signature, the chainId / kernel binding,
+     * or the payloadHash. Callers that have not already run {@link verify}
+     * SHOULD use {@link verifyAndDecrypt} instead.
+     *
+     * Throws on:
+     *  - non-encrypted scheme (`public-v1` envelopes are not decrypted),
+     *  - malformed buyerEphemeralPrivKey length,
+     *  - ECDH failure (low-order peer pubkey, etc.),
+     *  - HKDF failure,
+     *  - AES-GCM authentication failure (tag mismatch).
+     *
+     * @param wire - The envelope to decrypt.
+     * @param buyerEphemeralPrivKey - The buyer's 32-byte X25519 private
+     *   key (the one whose pubkey was embedded in the setup).
+     * @returns The JSON-parsed payload (`unknown`).
+     * @throws {DeliveryCryptoError} via the underlying crypto helpers.
+     * @throws {DeliveryEip712Error} `BUILDER_PUBLIC_DECRYPT_NOT_APPLICABLE`
+     *   when called on a `public-v1` envelope.
+     */
+    static decryptPayload(wire: DeliveryEnvelopeWireV1, buyerEphemeralPrivKey: Uint8Array): Promise<unknown>;
+    /**
+     * Combined {@link verify} + payload extraction.
+     *
+     * For `public-v1`: after a successful `verify`, the wire body (hex)
+     * is decoded to bytes, UTF-8 → string, JSON-parsed, and returned.
+     *
+     * For `x25519-aes256gcm-v1`: after a successful `verify`,
+     * {@link decryptPayload} is invoked with `buyerEphemeralPrivKey`.
+     *
+     * Verification failures are returned as `{ ok: false, code, error }`
+     * — the structured shape matches `verify`. Decryption failures are
+     * also returned as `{ ok: false, code: "envelope_decrypt_failed", ...}`
+     * (catching the underlying `DeliveryCryptoError`).
+     *
+     * @param wire - The envelope to verify + decrypt.
+     * @param buyerEphemeralPrivKey - 32-byte X25519 private key. Ignored
+     *   for `public-v1` envelopes (pass `new Uint8Array(32)` if you do
+     *   not have one — the value is never read in that branch).
+     * @param opts - Same as {@link verify}.
+     * @returns `{ ok: true, payload }` on success, `{ ok: false, code, error }`
+     *   on any failure.
+     */
+    static verifyAndDecrypt(wire: DeliveryEnvelopeWireV1, buyerEphemeralPrivKey: Uint8Array, opts: {
+        expectedKernelAddress: string;
+        expectedChainId: number;
+        now?: number;
+    }): Promise<{
+        ok: true;
+        payload: unknown;
+    } | {
+        ok: false;
+        code: string;
+        error: string;
+    }>;
+    /**
+     * Compute a stable, cross-SDK identifier for an envelope wire object.
+     *
+     * The hash is `keccak256(utf8Bytes(canonicalJsonStringify(wire.signed)))`:
+     *
+     *  - canonical JSON (sorted keys, no whitespace) guarantees byte-for-
+     *    byte identical input across SDK languages,
+     *  - `keccak256` matches the on-chain hashing convention,
+     *  - hashing the SIGNED projection (not the full wire) excludes the
+     *    signature, body, and any `serverMeta` so the hash is stable
+     *    across relay-side decoration and signature malleability.
+     *
+     * This is NOT the EIP-712 signing hash; it is a content-addressing
+     * helper for logs, dedup sets, and cross-SDK fixtures.
+     *
+     * @param wire - The wire envelope to hash.
+     * @returns 32-byte hex-encoded keccak256 hash (`0x` + 64 hex chars).
+     */
+    static computeHash(wire: DeliveryEnvelopeWireV1): string;
+}
+export type { BuildEnvelopeResult } from './types';
+//# sourceMappingURL=envelopeBuilder.d.ts.map

package/dist/delivery/envelopeBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopeBuilder.d.ts","sourceRoot":"","sources":["../../src/delivery/envelopeBuilder.ts"],"names":[],"mappings":"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"}