@agirails/sdk 4.4.8 → 4.5.2

package/dist/delivery/channel.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * AIP-16 Delivery Surface — Channel Abstraction (Phase 2b)
+ * =========================================================
+ *
+ * Transport-agnostic interface for posting and observing delivery
+ * setup + envelope wire objects between requester and provider.
+ *
+ * The delivery channel is the wire-level boundary between the two
+ * participants of an AIP-16 delivery exchange. It does NOT participate
+ * in any cryptographic verification — its only job is to transport
+ * already-signed {@link DeliverySetupWireV1} and {@link DeliveryEnvelopeWireV1}
+ * objects between participants.
+ *
+ * ## Concrete implementations
+ *
+ *  - **MockDeliveryChannel** — in-process loopback used by tests and
+ *    MockRuntime flows. Implements dedup-after-verify on the read side
+ *    (see {@link MockChannel} in `src/negotiation/` for the reference
+ *    pattern). Useful for end-to-end tests without network setup.
+ *  - **RelayDeliveryChannel** — HTTP client against the AGIRAILS relay
+ *    (or any compatible relay implementing the same REST surface). Uses
+ *    cursor pagination, polling at `POLL_INTERVAL_MS = 1000`, and an
+ *    SSRF guard on the relay URL (see {@link RelayChannel} in
+ *    `src/negotiation/` for the reference pattern).
+ *
+ * ## Security invariants (binding on ALL implementations)
+ *
+ * 1. **Dedup AFTER verify.** Implementations that deduplicate
+ *    incoming setups/envelopes MUST verify signatures BEFORE adding any
+ *    identifier (txId, sig hash, etc.) to a dedup set. Otherwise an
+ *    attacker can post malformed signatures to permanently suppress
+ *    the legitimate signed object that arrives later.
+ *
+ * 2. **Subscriber error isolation.** Subscriber callbacks may throw
+ *    arbitrary errors (consumer code is not the channel's problem).
+ *    Implementations MUST catch and silently swallow callback errors —
+ *    NEVER propagate them into the channel's read loop, since one bad
+ *    subscriber would otherwise halt delivery for all other subscribers
+ *    sharing the same channel.
+ *
+ * 3. **No verification at the channel layer.** Channels do NOT call
+ *    `recoverSetupSigner` / `recoverEnvelopeSigner` or any other
+ *    cryptographic check. Verification is the consumer's responsibility
+ *    (typically via {@link DeliverySetupBuilder.verify} /
+ *    {@link DeliveryEnvelopeBuilder.verify}). The channel is a dumb pipe.
+ *
+ * 4. **Address comparison case-insensitivity.** Where addresses appear
+ *    in dedup keys (e.g. `signerAddress`), implementations MUST normalize
+ *    to lowercase on both sides of any comparison.
+ *
+ * ## Subscription semantics
+ *
+ *  - `subscribeSetups` / `subscribeEnvelopes` are scoped to a single
+ *    `txId`. A subscription begins emitting from "now" — that is, from
+ *    objects that are NOT already known to the channel at subscribe time
+ *    are guaranteed to be delivered; objects that ARE already known MAY
+ *    or MAY NOT be re-delivered depending on the implementation. Code
+ *    that needs the full historical set should call the optional
+ *    `getSetups` / `getEnvelopes` methods.
+ *
+ *  - Returning a {@link DeliverySubscription} whose `close()` is invoked
+ *    MUST stop further callbacks from firing on that subscription. It
+ *    SHOULD also free any underlying transport (polling timer, HTTP
+ *    connection, etc.).
+ *
+ *  - Multiple subscribers on the same `txId` MUST each receive all
+ *    matching objects (fan-out, not steal). One subscriber's `close()`
+ *    MUST NOT affect other subscribers.
+ *
+ * @module delivery/channel
+ * @see {@link DeliverySetupWireV1}
+ * @see {@link DeliveryEnvelopeWireV1}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=channel.js.map

package/dist/delivery/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../src/delivery/channel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG"}

package/dist/delivery/channelLog.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AIP-16 Delivery Surface — Pluggable Channel Logger (Phase 2b)
+ * ==============================================================
+ *
+ * Minimal logger contract used by delivery channel implementations
+ * (`MockDeliveryChannel`, `RelayDeliveryChannel`) to surface
+ * operational events — transport errors, dedup hits, subscriber-callback
+ * errors that were swallowed per security invariant #2 — without
+ * coupling those implementations to any specific logging framework.
+ *
+ * ## Design intent
+ *
+ * Channels are dumb pipes: they verify nothing, decrypt nothing, and
+ * make no business decisions. They DO, however, encounter transport
+ * failures, malformed payloads, and (per the subscriber-error-isolation
+ * invariant) consumer callbacks that throw. Operators need visibility
+ * into these events; tests need to be able to assert on or silence
+ * them. A pluggable {@link LogFn} satisfies both needs without
+ * pulling pino/winston/console into the SDK runtime.
+ *
+ * The shape is intentionally minimal — three levels, a message string,
+ * and an optional structured `details` bag. Implementers can adapt
+ * this to any backend (console, pino, OpenTelemetry, in-memory buffer
+ * for tests, etc.).
+ *
+ * ## Levels
+ *
+ *  - `"info"`  — Normal lifecycle events (subscription opened/closed,
+ *    publish accepted). Quiet by default in production.
+ *  - `"warn"`  — Recoverable anomalies (dedup hit on poisoned signature,
+ *    subscriber callback threw and was swallowed, optional `getSetups`
+ *    not supported by the underlying transport). Worth surfacing in
+ *    dashboards but not pageable.
+ *  - `"error"` — Transport failures (relay returned 5xx, network
+ *    unreachable, malformed wire object rejected before publish).
+ *    May trigger retries upstream.
+ *
+ * ## Default
+ *
+ * The exported {@link noopLog} is a silent default suitable for
+ * library consumers who do not want any logging output. Tests can
+ * provide a capturing logger; production deployments can adapt the
+ * SDK's events to their preferred observability stack.
+ *
+ * @example Console logger
+ * ```typescript
+ * import type { LogFn } from '@agirails/sdk/delivery';
+ *
+ * const consoleLog: LogFn = (level, msg, details) => {
+ *   // eslint-disable-next-line no-console
+ *   console[level](`[delivery] ${msg}`, details ?? {});
+ * };
+ * ```
+ *
+ * @example Capturing logger for tests
+ * ```typescript
+ * const events: Array<{ level: string; msg: string; details?: unknown }> = [];
+ * const captureLog: LogFn = (level, msg, details) => {
+ *   events.push({ level, msg, details });
+ * };
+ * // …run channel under test, then assert on `events`.
+ * ```
+ *
+ * @module delivery/channelLog
+ */
+/**
+ * Pluggable logger function used by delivery channel implementations.
+ *
+ * Implementations of this signature receive a level, a human-readable
+ * message string, and an optional structured `details` bag. They MAY
+ * route the event to any backend (console, pino, OTel, in-memory
+ * capture, /dev/null) — the channel does not care.
+ *
+ * The function MUST be synchronous from the channel's point of view
+ * (the channel never `await`s it). Implementations that need to batch
+ * or ship logs asynchronously SHOULD do so via internal queues, NOT
+ * by returning a Promise.
+ *
+ * Implementations MUST NOT throw. If an underlying logging backend
+ * fails (e.g. write to disk failed), implementations SHOULD catch
+ * and discard — a channel cannot let a logging failure interrupt
+ * delivery transport.
+ *
+ * @param level The severity of the event. See module JSDoc for level
+ *   semantics.
+ * @param msg A human-readable description of the event. Stable enough
+ *   to be greppable across log volumes, but not promised as a
+ *   machine-actionable identifier — use `details.code` (when present)
+ *   for that.
+ * @param details Optional structured context (txId, signer address,
+ *   HTTP status, error code, etc.). Implementations SHOULD attach
+ *   any details bag to the underlying log record verbatim; loggers
+ *   that flatten structured data SHOULD preserve key/value pairs.
+ */
+export type LogFn = (level: 'info' | 'warn' | 'error', msg: string, details?: Record<string, unknown>) => void;
+/**
+ * Silent default {@link LogFn}: discards every event.
+ *
+ * Suitable as the default `log` parameter on channel constructors so
+ * that consumers who do not opt into logging see no output. Tests and
+ * production deployments that want visibility SHOULD pass their own
+ * {@link LogFn} implementation.
+ *
+ * @example
+ * ```typescript
+ * import { noopLog } from '@agirails/sdk/delivery';
+ *
+ * const channel = new RelayDeliveryChannel({
+ *   baseUrl: 'https://relay.agirails.io',
+ *   log: noopLog, // explicit silence; same as omitting the param
+ * });
+ * ```
+ */
+export declare const noopLog: LogFn;
+//# sourceMappingURL=channelLog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channelLog.d.ts","sourceRoot":"","sources":["../../src/delivery/channelLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,KAAK,GAAG,CAClB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAChC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,IAAI,CAAC;AAMV;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,OAAO,EAAE,KAErB,CAAC"}

package/dist/delivery/channelLog.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * AIP-16 Delivery Surface — Pluggable Channel Logger (Phase 2b)
+ * ==============================================================
+ *
+ * Minimal logger contract used by delivery channel implementations
+ * (`MockDeliveryChannel`, `RelayDeliveryChannel`) to surface
+ * operational events — transport errors, dedup hits, subscriber-callback
+ * errors that were swallowed per security invariant #2 — without
+ * coupling those implementations to any specific logging framework.
+ *
+ * ## Design intent
+ *
+ * Channels are dumb pipes: they verify nothing, decrypt nothing, and
+ * make no business decisions. They DO, however, encounter transport
+ * failures, malformed payloads, and (per the subscriber-error-isolation
+ * invariant) consumer callbacks that throw. Operators need visibility
+ * into these events; tests need to be able to assert on or silence
+ * them. A pluggable {@link LogFn} satisfies both needs without
+ * pulling pino/winston/console into the SDK runtime.
+ *
+ * The shape is intentionally minimal — three levels, a message string,
+ * and an optional structured `details` bag. Implementers can adapt
+ * this to any backend (console, pino, OpenTelemetry, in-memory buffer
+ * for tests, etc.).
+ *
+ * ## Levels
+ *
+ *  - `"info"`  — Normal lifecycle events (subscription opened/closed,
+ *    publish accepted). Quiet by default in production.
+ *  - `"warn"`  — Recoverable anomalies (dedup hit on poisoned signature,
+ *    subscriber callback threw and was swallowed, optional `getSetups`
+ *    not supported by the underlying transport). Worth surfacing in
+ *    dashboards but not pageable.
+ *  - `"error"` — Transport failures (relay returned 5xx, network
+ *    unreachable, malformed wire object rejected before publish).
+ *    May trigger retries upstream.
+ *
+ * ## Default
+ *
+ * The exported {@link noopLog} is a silent default suitable for
+ * library consumers who do not want any logging output. Tests can
+ * provide a capturing logger; production deployments can adapt the
+ * SDK's events to their preferred observability stack.
+ *
+ * @example Console logger
+ * ```typescript
+ * import type { LogFn } from '@agirails/sdk/delivery';
+ *
+ * const consoleLog: LogFn = (level, msg, details) => {
+ *   // eslint-disable-next-line no-console
+ *   console[level](`[delivery] ${msg}`, details ?? {});
+ * };
+ * ```
+ *
+ * @example Capturing logger for tests
+ * ```typescript
+ * const events: Array<{ level: string; msg: string; details?: unknown }> = [];
+ * const captureLog: LogFn = (level, msg, details) => {
+ *   events.push({ level, msg, details });
+ * };
+ * // …run channel under test, then assert on `events`.
+ * ```
+ *
+ * @module delivery/channelLog
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopLog = void 0;
+// ============================================================================
+// Default silent logger
+// ============================================================================
+/**
+ * Silent default {@link LogFn}: discards every event.
+ *
+ * Suitable as the default `log` parameter on channel constructors so
+ * that consumers who do not opt into logging see no output. Tests and
+ * production deployments that want visibility SHOULD pass their own
+ * {@link LogFn} implementation.
+ *
+ * @example
+ * ```typescript
+ * import { noopLog } from '@agirails/sdk/delivery';
+ *
+ * const channel = new RelayDeliveryChannel({
+ *   baseUrl: 'https://relay.agirails.io',
+ *   log: noopLog, // explicit silence; same as omitting the param
+ * });
+ * ```
+ */
+const noopLog = () => {
+    // Intentional no-op. See JSDoc for rationale.
+};
+exports.noopLog = noopLog;
+//# sourceMappingURL=channelLog.js.map

package/dist/delivery/channelLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channelLog.js","sourceRoot":"","sources":["../../src/delivery/channelLog.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;;;AAyCH,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACI,MAAM,OAAO,GAAU,GAAG,EAAE;IACjC,8CAA8C;AAChD,CAAC,CAAC;AAFW,QAAA,OAAO,WAElB"}

package/dist/delivery/crypto.d.ts

@@ -0,0 +1,312 @@
+/**
+ * AIP-16 Delivery Surface — AES-256-GCM AEAD + Body Hashing (Phase 2a Foundation)
+ * ==============================================================================
+ *
+ * Authenticated encryption primitives for the `x25519-aes256gcm-v1`
+ * delivery scheme of AIP-16 Rev 5.
+ *
+ * This module sits one layer above `./keys.ts` (which produces the
+ * 32-byte session key via X25519 ECDH + HKDF-SHA256) and one layer
+ * below the envelope builders (`./envelopeBuilder.ts`, later phase),
+ * which assemble the ciphertext + nonce + tag + signature into the
+ * wire envelope.
+ *
+ * ## Scope of this file
+ *
+ * - {@link encryptBody}: seal a UTF-8 string or raw byte body with
+ *   AES-256-GCM, returning ciphertext + 12-byte nonce + 16-byte tag.
+ * - {@link decryptBody}: inverse — verify the GCM tag and return the
+ *   plaintext.
+ * - {@link bodyHash}: keccak256 of the UTF-8 / raw bytes, in the exact
+ *   form used for the `payloadHash` field of the signed EIP-712
+ *   projection.
+ * - Hex format helpers ({@link bytesToHex}, {@link bytesFromHex}) for
+ *   ciphertext / nonce / tag serialization at the wire boundary.
+ *
+ * ## Library choice: `node:crypto`
+ *
+ * We use Node's built-in AES-GCM (`createCipheriv('aes-256-gcm', …)`)
+ * rather than `@noble/ciphers`. Reasons:
+ *
+ *  1. AES-256-GCM is a *standard* AEAD; the implementation surface is
+ *     small and audited as part of OpenSSL (the engine behind
+ *     `node:crypto`).
+ *  2. Zero new dependencies — matches the design constraint in the
+ *     Phase 2a task brief.
+ *  3. The `setAuthTag` / `getAuthTag` pattern is mechanical and easy
+ *     to audit for "did we actually verify the tag before returning
+ *     plaintext?" (`decipher.final()` throws on tag mismatch).
+ *
+ * ## AAD (Additional Authenticated Data) — H5 defense-in-depth
+ *
+ * Both {@link encryptBody} and {@link decryptBody} accept an OPTIONAL
+ * `aad` byte buffer. When supplied, the bytes are fed into GCM via
+ * `cipher.setAAD(aad)` / `decipher.setAAD(aad)` — they are *not*
+ * encrypted, but the GCM authentication tag commits to them, so a
+ * decryption with the wrong AAD fails closed with a tag mismatch.
+ *
+ * For the `x25519-aes256gcm-v1` scheme the envelope builder constructs
+ *
+ *   aad = txId_bytes (32) || signerAddress_bytes (20)   // 52 bytes
+ *
+ * and passes it to both encrypt and decrypt. This binds the GCM
+ * authentication to the on-chain transaction id and the EOA that
+ * signed the envelope, so a misrouted envelope (correct ciphertext +
+ * nonce + tag + sessionKey, but delivered to a different `txId` or
+ * `signerAddress`) cannot be opened — defense-in-depth on top of the
+ * EIP-712 signature over `txId` and `payloadHash`.
+ *
+ * Because the channel is gated behind the Phase 2f feature flag and
+ * no in-flight `x25519-aes256gcm-v1` envelopes exist in production, we
+ * change the AAD inline within the existing scheme tag rather than
+ * minting a `-v2` suffix; the scheme name stays `x25519-aes256gcm-v1`.
+ *
+ * AAD is OPTIONAL at the primitive level. Callers that omit it get
+ * the legacy "AAD = empty" behavior (still interoperable with prior
+ * versions of the function). The envelope builder always supplies AAD.
+ *
+ * ## Memory hygiene
+ *
+ * `sessionKey` and plaintext are held in plain `Uint8Array`s. Like
+ * `./keys.ts`, this module does not attempt to zero memory — V8 makes
+ * no such guarantees, and the SDK target environments (Node + Bun)
+ * inherit that limitation. Callers SHOULD let secrets go out of scope
+ * promptly after use.
+ *
+ * @module delivery/crypto
+ * @see ./keys — produces the 32-byte session key consumed here
+ * @see ./eip712 — signs the `payloadHash` produced by {@link bodyHash}
+ * @see {@link https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf NIST SP 800-38D — GCM mode}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc5116 RFC 5116 — AEAD interface}
+ */
+/**
+ * Length (in bytes) of the AES-256-GCM nonce / IV.
+ *
+ * Twelve bytes is the GCM-standard length (NIST SP 800-38D §5.2.1.1).
+ * Any other length is technically permitted by the spec but triggers
+ * an additional GHASH step and is interoperable only by convention;
+ * AIP-16 v1 mandates 12 bytes to keep the wire format unambiguous.
+ *
+ * We sample the nonce from `randomBytes(12)` per-encryption. The
+ * 2^96 nonce space is more than adequate for the AIP-16 use case
+ * (one nonce per delivery envelope per session key, with session keys
+ * themselves bound to a single transaction via HKDF).
+ */
+export declare const AES_GCM_NONCE_LENGTH: 12;
+/**
+ * Length (in bytes) of the AES-256-GCM authentication tag.
+ *
+ * Sixteen bytes is the maximum (full-strength) tag length permitted
+ * by GCM; NIST SP 800-38D recommends this size when the application
+ * cannot tolerate any forgery probability. The wire format reserves
+ * a fixed 16-byte slot for the tag.
+ */
+export declare const AES_GCM_TAG_LENGTH: 16;
+/**
+ * Length (in bytes) of an AES-256 key. Equal to
+ * {@link DELIVERY_SESSION_KEY_LENGTH} (re-exported from `./keys`) so
+ * callers do not have to import both files just for the length check.
+ */
+export declare const AES_KEY_LENGTH: 32;
+/**
+ * Result of {@link encryptBody}.
+ *
+ * All three fields are raw bytes (not hex). The envelope builder will
+ * apply {@link bytesToHex} just before serializing to the wire
+ * envelope's `bodyCiphertextHex`, `nonceHex`, and `tagHex` fields.
+ *
+ * The separation of `ciphertext` and `tag` matches the `node:crypto`
+ * GCM API surface (`getAuthTag` is a distinct call from the cipher's
+ * `update` / `final` output). It also makes the wire format
+ * unambiguous: there is no need to peel the last 16 bytes off the
+ * ciphertext, which is a common parsing bug.
+ */
+export interface EncryptResult {
+    /**
+     * The AES-256-GCM ciphertext. Length is exactly equal to the
+     * plaintext length (GCM is a stream-cipher mode, no padding).
+     */
+    ciphertext: Uint8Array;
+    /**
+     * The 12-byte random nonce / IV used for this encryption. Embedded
+     * verbatim in the wire envelope so the recipient can pass it to
+     * {@link decryptBody}.
+     */
+    nonce: Uint8Array;
+    /**
+     * The 16-byte GCM authentication tag. The recipient MUST present
+     * this tag to AES-GCM during decryption; `decipher.final()` will
+     * throw if it does not match, which {@link decryptBody} catches
+     * and re-raises as `DeliveryCryptoError('crypto_decrypt_failed')`.
+     */
+    tag: Uint8Array;
+}
+/**
+ * Encrypt a delivery envelope body with AES-256-GCM using the supplied
+ * session key.
+ *
+ * The session key MUST have been produced by
+ * {@link import('./keys').deriveSessionKey} (32 bytes, HKDF-SHA256
+ * output bound to the on-chain `txId`).
+ *
+ * A fresh 12-byte nonce is sampled from `randomBytes` per call.
+ * Re-using a (key, nonce) pair is *catastrophic* for GCM — it leaks
+ * the GHASH key, allowing both decryption of past messages and
+ * forgery of future ones. With session keys scoped to one transaction
+ * and nonces randomized per envelope, the probability of collision
+ * over realistic envelope counts is negligible.
+ *
+ * AAD is OPTIONAL. When supplied, the bytes are committed by the GCM
+ * tag (defense-in-depth — see the H5 section of the module-level docs).
+ * Decryption with a different AAD (or with no AAD at all when the
+ * encrypt side used one) will fail with `crypto_decrypt_failed`.
+ *
+ * @param plaintext - Body bytes to encrypt. A `string` is interpreted
+ *   as UTF-8; pre-encoded `Uint8Array` is passed through verbatim.
+ * @param sessionKey - 32-byte AES-256-GCM key from `deriveSessionKey`.
+ * @param aad - Optional Additional Authenticated Data. When omitted,
+ *   no AAD is fed into GCM (legacy behavior). When supplied, MUST be a
+ *   `Uint8Array`; mismatched AAD at decrypt time fails tag verification.
+ * @returns {@link EncryptResult} carrying ciphertext, nonce, and tag.
+ * @throws {DeliveryCryptoError} `crypto_encrypt_failed` if
+ *   `sessionKey` is malformed (not a `Uint8Array` of length 32), if
+ *   `plaintext` is the wrong type, if `aad` is supplied as a non-bytes
+ *   value, or if `node:crypto` raises.
+ *
+ * @example
+ * ```typescript
+ * const key = deriveSessionKey(shared, txId);
+ * // AAD = txId_bytes || signerAddress_bytes (H5 binding)
+ * const aad = new Uint8Array(52);
+ * aad.set(bytesFromHex(txId), 0);
+ * aad.set(bytesFromHex(signerAddress), 32);
+ * const { ciphertext, nonce, tag } = encryptBody('{"result":"ok"}', key, aad);
+ * ```
+ */
+export declare function encryptBody(plaintext: Uint8Array | string, sessionKey: Uint8Array, aad?: Uint8Array): EncryptResult;
+/**
+ * Decrypt and authenticate an AES-256-GCM ciphertext produced by
+ * {@link encryptBody} (or an interoperable peer).
+ *
+ * The GCM authentication tag is verified inside `decipher.final()` —
+ * if the tag does not match, `node:crypto` throws and we re-raise as
+ * `DeliveryCryptoError('crypto_decrypt_failed')`. This is the *only*
+ * integrity check on the envelope body bytes; pair it with EIP-712
+ * signature verification one layer up to also bind the body to a
+ * specific signer.
+ *
+ * AAD is OPTIONAL but MUST match what the encrypt side used. The GCM
+ * tag commits to the AAD bytes; supplying the wrong AAD (or omitting
+ * AAD when the encrypt side supplied one, or vice versa) produces a
+ * tag-mismatch error, surfaced here as `crypto_decrypt_failed`. This
+ * is the H5 misrouting defense — see the module-level AAD section.
+ *
+ * @param ciphertext - GCM ciphertext as raw bytes.
+ * @param sessionKey - 32-byte AES-256-GCM key (same as encrypt side).
+ * @param nonce - 12-byte nonce that was used at encrypt time.
+ * @param tag - 16-byte GCM authentication tag.
+ * @param aad - Optional Additional Authenticated Data. MUST exactly
+ *   match the AAD passed to {@link encryptBody}; mismatch (including
+ *   AAD/no-AAD asymmetry) fails the tag check and throws
+ *   `crypto_decrypt_failed`.
+ * @returns The decrypted plaintext as raw bytes. If the original
+ *   plaintext was a UTF-8 string, the caller can recover it via
+ *   `Buffer.from(plaintext).toString('utf8')`.
+ * @throws {DeliveryCryptoError} `crypto_decrypt_failed` on any of:
+ *   malformed lengths, wrong session key, tampered ciphertext / tag /
+ *   nonce, AAD mismatch, malformed AAD type, or underlying
+ *   `node:crypto` failure.
+ *
+ * @example
+ * ```typescript
+ * const aad = new Uint8Array(52);
+ * aad.set(bytesFromHex(txId), 0);
+ * aad.set(bytesFromHex(signerAddress), 32);
+ * const plaintextBytes = decryptBody(ciphertext, key, nonce, tag, aad);
+ * const json = Buffer.from(plaintextBytes).toString('utf8');
+ * ```
+ */
+export declare function decryptBody(ciphertext: Uint8Array, sessionKey: Uint8Array, nonce: Uint8Array, tag: Uint8Array, aad?: Uint8Array): Uint8Array;
+/**
+ * Compute the keccak256 hash of an envelope body, in the exact form
+ * embedded into the `payloadHash` field of the signed EIP-712
+ * projection.
+ *
+ * Per AIP-16 Rev 5 §6.2, `payloadHash = keccak256(bodyBytes)` where
+ * `bodyBytes` is:
+ *  - For `scheme: "public-v1"`: the UTF-8 bytes of the plaintext body
+ *    string (or the raw `Uint8Array` if the caller pre-encoded).
+ *  - For `scheme: "x25519-aes256gcm-v1"`: the *ciphertext* bytes (the
+ *    output of {@link encryptBody}.ciphertext), not the plaintext.
+ *    This commits the signer to the exact bytes that travel on the
+ *    wire, preventing a malicious relay from substituting alternative
+ *    ciphertext with the same plaintext (which GCM nonces would
+ *    actually preclude, but the EIP-712 commitment is independent of
+ *    that).
+ *
+ * The output is a 0x-prefixed lowercase 66-char hex string (32-byte
+ * keccak256 digest), exactly matching the `bytes32` field shape in
+ * the EIP-712 types.
+ *
+ * @param body - The bytes to hash. A `string` is interpreted as UTF-8.
+ * @returns The keccak256 digest as `0x` + 64 lowercase hex chars.
+ *
+ * @example
+ * ```typescript
+ * // Public scheme:
+ * const h1 = bodyHash('{"result":"ok"}');
+ *
+ * // Encrypted scheme — hash the CIPHERTEXT, not the plaintext:
+ * const { ciphertext } = encryptBody(plaintext, key);
+ * const h2 = bodyHash(ciphertext);
+ * ```
+ */
+export declare function bodyHash(body: string | Uint8Array): `0x${string}`;
+/**
+ * Encode raw bytes to a lowercase 0x-prefixed hex string.
+ *
+ * Intentionally byte-for-byte equivalent to the equivalent helper in
+ * `./keys.ts` (which is `internal` there). Exposed here at the
+ * module surface so envelope-builder callers can serialize their
+ * ciphertext / nonce / tag without reaching into `./keys.ts` internals.
+ *
+ * Hand-rolled rather than `Buffer.from(b).toString('hex')` so the
+ * implementation is portable to non-Node runtimes (Bun, web) without
+ * polyfills, and to avoid Buffer-vs-Uint8Array subclass confusion.
+ *
+ * @param b - Raw bytes to encode.
+ * @returns A `0x`-prefixed lowercase hex string of length
+ *   `2 + 2 * b.length`.
+ *
+ * @example
+ * ```typescript
+ * bytesToHex(new Uint8Array([0xab, 0xcd])); // "0xabcd"
+ * ```
+ */
+export declare function bytesToHex(b: Uint8Array): `0x${string}`;
+/**
+ * Decode a 0x-prefixed hex string to raw bytes.
+ *
+ * Strict on shape: the string MUST start with `0x` (case-insensitive
+ * prefix), MUST contain only hex digits after the prefix, and MUST
+ * have an even number of hex digits. Returns a fresh `Uint8Array`.
+ *
+ * Used at the wire boundary to decode `bodyCiphertextHex`, `nonceHex`,
+ * `tagHex`, and any other hex-serialized byte field into the byte
+ * forms expected by {@link decryptBody}.
+ *
+ * @param hex - 0x-prefixed hex string, even number of hex digits.
+ * @returns A fresh `Uint8Array` of length `(hex.length - 2) / 2`.
+ * @throws {DeliveryCryptoError} `crypto_decrypt_failed` if `hex` is
+ *   missing the `0x` prefix, has odd length, or contains non-hex
+ *   characters. (`crypto_decrypt_failed` is the most likely site of
+ *   failure for this helper; encrypt-side callers will instead get
+ *   the structural validation in {@link encryptBody}.)
+ *
+ * @example
+ * ```typescript
+ * bytesFromHex('0xabcd'); // Uint8Array(2) [0xab, 0xcd]
+ * ```
+ */
+export declare function bytesFromHex(hex: string): Uint8Array;
+//# sourceMappingURL=crypto.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/delivery/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAYH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,IAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,IAAc,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,cAAc,IAA8B,CAAC;AAM1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,UAAU,EAAE,UAAU,CAAC;IAEvB;;;;OAIG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB;;;;;OAKG;IACH,GAAG,EAAE,UAAU,CAAC;CACjB;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,UAAU,EAAE,UAAU,EACtB,GAAG,CAAC,EAAE,UAAU,GACf,aAAa,CA2Gf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,UAAU,EACf,GAAG,CAAC,EAAE,UAAU,GACf,UAAU,CAsFZ;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,MAAM,EAAE,CAOjE;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,KAAK,MAAM,EAAE,CAevD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAyCpD"}