@heyanon-arp/sdk 0.0.2 → 0.0.4

package/dist/index.js

@@ -273,8 +273,39 @@ function buildWebhookSignatureHeader(input, sharedSecret) {
   return `${Purpose.WEBHOOK}=${base.base64.encode(mac)}`;
 }
 function verifyWebhookSignatureHeader(headerValue, input, sharedSecret) {
-  const expected = buildWebhookSignatureHeader(input, sharedSecret);
-  return constantTimeEqual(expected, headerValue);
+  const secrets = Array.isArray(sharedSecret) ? sharedSecret : [sharedSecret];
+  if (secrets.length === 0) return false;
+  let matched = false;
+  for (const secret of secrets) {
+    const expected = buildWebhookSignatureHeader(input, secret);
+    matched = constantTimeEqual(expected, headerValue) || matched;
+  }
+  return matched;
+}
+function verifyAndCheckPayload(args) {
+  const tolerance = args.servedAtToleranceMs === void 0 ? 5 * 6e4 : args.servedAtToleranceMs;
+  if (tolerance !== null) {
+    const servedAtMs = Date.parse(args.input.served_at);
+    const nowMs = (args.now ?? /* @__PURE__ */ new Date()).getTime();
+    if (Number.isNaN(servedAtMs) || Math.abs(nowMs - servedAtMs) > tolerance) return "stale_attempt";
+  }
+  const fullInput = { ...args.input, payload_sha256: sha256HexLower(args.rawBody) };
+  if (!verifyWebhookSignatureHeader(args.headerValue, fullInput, args.secrets)) return "invalid_signature";
+  return "ok";
+}
+function isProbeRequest(headers) {
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== "x-arp-probe") continue;
+    const v = Array.isArray(value) ? value[0] : value;
+    if (v === "1" || v === "true") return true;
+  }
+  return false;
+}
+function sha256HexLower(bytes) {
+  const digest = sha2.sha256(bytes);
+  let hex = "";
+  for (const b of digest) hex += b.toString(16).padStart(2, "0");
+  return hex;
 }
 function constantTimeEqual(a, b) {
   if (a.length !== b.length) return false;
@@ -645,6 +676,43 @@ function expiresAt(ttlSeconds, now = /* @__PURE__ */ new Date()) {
   return rfc3339(new Date(now.getTime() + ttlSeconds * 1e3));
 }
 
+// src/utils/poll.ts
+async function pollUntil(opts) {
+  const intervalMs = Math.max(100, opts.intervalMs ?? 3e3);
+  const timeoutMs = Math.max(intervalMs, opts.timeoutMs ?? 3e5);
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  if (opts.abortSignal?.aborted) return { kind: "aborted", last: void 0 };
+  for (; ; ) {
+    try {
+      last = await opts.fetch();
+      if (opts.predicate(last)) return { kind: "matched", value: last };
+    } catch (err) {
+      if (!opts.swallowFetchErrors) throw err;
+      opts.onFetchError?.(err);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return { kind: "timeout", last };
+    const sleepMs = Math.min(intervalMs, remaining);
+    await sleepWithAbort(sleepMs, opts.abortSignal);
+    if (opts.abortSignal?.aborted) return { kind: "aborted", last };
+  }
+}
+function sleepWithAbort(ms, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/types/body.ts
 var DECLINE_REASONS = ["missing_brief", "rate_too_low", "out_of_scope", "policy", "expired_proposal", "capacity", "unspecified", "other"];
 function isDeclineReason(v) {
@@ -827,15 +895,18 @@ exports.generateKeyPair = generateKeyPair;
 exports.getPublicKey = getPublicKey2;
 exports.isAssetIdentifier = isAssetIdentifier;
 exports.isDeclineReason = isDeclineReason;
+exports.isProbeRequest = isProbeRequest;
 exports.isValidDid = isValidDid;
 exports.parseCaip19SolanaAssetId = parseCaip19SolanaAssetId;
 exports.parseDid = parseDid;
+exports.pollUntil = pollUntil;
 exports.resolveAsset = resolveAsset;
 exports.rfc3339 = rfc3339;
 exports.scryptPasswordProofSign = scryptPasswordProofSign;
 exports.scryptPasswordProofVerify = scryptPasswordProofVerify;
 exports.senderNonce = senderNonce;
 exports.serverEventHash = serverEventHash;
+exports.sha256HexLower = sha256HexLower;
 exports.sign = sign2;
 exports.signChallenge = signChallenge;
 exports.signCosignature = signCosignature;
@@ -845,6 +916,7 @@ exports.signKeyRotationAttestation = signKeyRotationAttestation;
 exports.signedMessageHash = signedMessageHash;
 exports.uuidV4 = uuidV4;
 exports.verify = verify2;
+exports.verifyAndCheckPayload = verifyAndCheckPayload;
 exports.verifyChallenge = verifyChallenge;
 exports.verifyCosignature = verifyCosignature;
 exports.verifyEnvelope = verifyEnvelope;

package/dist/index.mjs

@@ -248,8 +248,39 @@ function buildWebhookSignatureHeader(input, sharedSecret) {
   return `${Purpose.WEBHOOK}=${base64.encode(mac)}`;
 }
 function verifyWebhookSignatureHeader(headerValue, input, sharedSecret) {
-  const expected = buildWebhookSignatureHeader(input, sharedSecret);
-  return constantTimeEqual(expected, headerValue);
+  const secrets = Array.isArray(sharedSecret) ? sharedSecret : [sharedSecret];
+  if (secrets.length === 0) return false;
+  let matched = false;
+  for (const secret of secrets) {
+    const expected = buildWebhookSignatureHeader(input, secret);
+    matched = constantTimeEqual(expected, headerValue) || matched;
+  }
+  return matched;
+}
+function verifyAndCheckPayload(args) {
+  const tolerance = args.servedAtToleranceMs === void 0 ? 5 * 6e4 : args.servedAtToleranceMs;
+  if (tolerance !== null) {
+    const servedAtMs = Date.parse(args.input.served_at);
+    const nowMs = (args.now ?? /* @__PURE__ */ new Date()).getTime();
+    if (Number.isNaN(servedAtMs) || Math.abs(nowMs - servedAtMs) > tolerance) return "stale_attempt";
+  }
+  const fullInput = { ...args.input, payload_sha256: sha256HexLower(args.rawBody) };
+  if (!verifyWebhookSignatureHeader(args.headerValue, fullInput, args.secrets)) return "invalid_signature";
+  return "ok";
+}
+function isProbeRequest(headers) {
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== "x-arp-probe") continue;
+    const v = Array.isArray(value) ? value[0] : value;
+    if (v === "1" || v === "true") return true;
+  }
+  return false;
+}
+function sha256HexLower(bytes) {
+  const digest = sha256(bytes);
+  let hex = "";
+  for (const b of digest) hex += b.toString(16).padStart(2, "0");
+  return hex;
 }
 function constantTimeEqual(a, b) {
   if (a.length !== b.length) return false;
@@ -620,6 +651,43 @@ function expiresAt(ttlSeconds, now = /* @__PURE__ */ new Date()) {
   return rfc3339(new Date(now.getTime() + ttlSeconds * 1e3));
 }
 
+// src/utils/poll.ts
+async function pollUntil(opts) {
+  const intervalMs = Math.max(100, opts.intervalMs ?? 3e3);
+  const timeoutMs = Math.max(intervalMs, opts.timeoutMs ?? 3e5);
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  if (opts.abortSignal?.aborted) return { kind: "aborted", last: void 0 };
+  for (; ; ) {
+    try {
+      last = await opts.fetch();
+      if (opts.predicate(last)) return { kind: "matched", value: last };
+    } catch (err) {
+      if (!opts.swallowFetchErrors) throw err;
+      opts.onFetchError?.(err);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return { kind: "timeout", last };
+    const sleepMs = Math.min(intervalMs, remaining);
+    await sleepWithAbort(sleepMs, opts.abortSignal);
+    if (opts.abortSignal?.aborted) return { kind: "aborted", last };
+  }
+}
+function sleepWithAbort(ms, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/types/body.ts
 var DECLINE_REASONS = ["missing_brief", "rate_too_low", "out_of_scope", "policy", "expired_proposal", "capacity", "unspecified", "other"];
 function isDeclineReason(v) {
@@ -758,4 +826,4 @@ function computeCreateLockDiscriminator() {
   return h.slice(0, 8);
 }
 
-export { CAIP19_REGEX, COSIGNATURE_PURPOSES, CREATE_LOCK_DISCRIMINATOR, DECLINE_REASONS, PROTECTED_PURPOSES, PURPOSE_PARTIAL_RELEASE_STRING, PURPOSE_REFUND_STRING, PURPOSE_RELEASE_STRING, Purpose, REFUND_REASON_BYTES, SCRYPT_PARAMS, SETTLEMENT_PURPOSES, SLIP44_SOLANA, SOLANA_CLUSTER_IDS, SPL_TOKEN_PROGRAM_ID_BASE58, TOKEN_2022_PROGRAM_ID_BASE58, USDC_MINTS, WELL_KNOWN_ASSETS, WELL_KNOWN_ASSET_KEYS, base58btcDecode, base58btcEncode, buildCreateLockIxData, buildPartialReleaseDigest, buildRefundDigest, buildReleaseDigest, buildWebhookSignatureHeader, bytes16ToDelegationId, canonicalBytes, canonicalJson, canonicalSha256Hex, computeCreateLockDiscriminator, delegationIdToBytes16, deriveConditionHash, deriveLockId, deriveScryptKey, detectTokenProgramFromOwner, detectTokenProgramFromOwnerBytes, expiresAt, findFirstChainDivergence, formatDid, generateKeyPair, getPublicKey2 as getPublicKey, isAssetIdentifier, isDeclineReason, isValidDid, parseCaip19SolanaAssetId, parseDid, resolveAsset, rfc3339, scryptPasswordProofSign, scryptPasswordProofVerify, senderNonce, serverEventHash, sign2 as sign, signChallenge, signCosignature, signEnvelope, signKeyLinkAttestation, signKeyRotationAttestation, signedMessageHash, uuidV4, verify2 as verify, verifyChallenge, verifyCosignature, verifyEnvelope, verifyKeyLinkAttestation, verifyKeyRotationAttestation, verifyWebhookSignatureHeader };
+export { CAIP19_REGEX, COSIGNATURE_PURPOSES, CREATE_LOCK_DISCRIMINATOR, DECLINE_REASONS, PROTECTED_PURPOSES, PURPOSE_PARTIAL_RELEASE_STRING, PURPOSE_REFUND_STRING, PURPOSE_RELEASE_STRING, Purpose, REFUND_REASON_BYTES, SCRYPT_PARAMS, SETTLEMENT_PURPOSES, SLIP44_SOLANA, SOLANA_CLUSTER_IDS, SPL_TOKEN_PROGRAM_ID_BASE58, TOKEN_2022_PROGRAM_ID_BASE58, USDC_MINTS, WELL_KNOWN_ASSETS, WELL_KNOWN_ASSET_KEYS, base58btcDecode, base58btcEncode, buildCreateLockIxData, buildPartialReleaseDigest, buildRefundDigest, buildReleaseDigest, buildWebhookSignatureHeader, bytes16ToDelegationId, canonicalBytes, canonicalJson, canonicalSha256Hex, computeCreateLockDiscriminator, delegationIdToBytes16, deriveConditionHash, deriveLockId, deriveScryptKey, detectTokenProgramFromOwner, detectTokenProgramFromOwnerBytes, expiresAt, findFirstChainDivergence, formatDid, generateKeyPair, getPublicKey2 as getPublicKey, isAssetIdentifier, isDeclineReason, isProbeRequest, isValidDid, parseCaip19SolanaAssetId, parseDid, pollUntil, resolveAsset, rfc3339, scryptPasswordProofSign, scryptPasswordProofVerify, senderNonce, serverEventHash, sha256HexLower, sign2 as sign, signChallenge, signCosignature, signEnvelope, signKeyLinkAttestation, signKeyRotationAttestation, signedMessageHash, uuidV4, verify2 as verify, verifyAndCheckPayload, verifyChallenge, verifyCosignature, verifyEnvelope, verifyKeyLinkAttestation, verifyKeyRotationAttestation, verifyWebhookSignatureHeader };

package/dist/purpose.d.ts

@@ -7,8 +7,8 @@
  * "this byte string was signed" assertion is not enough; the bytes
  * themselves carry the role).
  *
- * Adding a new purpose = add an entry here AND amend
- * [00-core/protocol.md](../../00-core/protocol.md) in the same PR.
+ * Adding a new purpose means adding an entry here and keeping
+ * [00-core/protocol.md](../../00-core/protocol.md) in sync.
  */
 export declare const Purpose: {
     /** Default for `protected.purpose` on body messages. */

package/dist/types/body.d.ts

@@ -238,11 +238,117 @@ export interface DisputeContent {
     evidence_refs?: string[];
     response_text?: string;
 }
+/**
+ * `settlement_signature` — payee's settlement-key signature on a
+ * release-digest, sent as a STAND-ALONE envelope AFTER the matching
+ * receipt-propose envelope is committed.
+ *
+ * Why a separate envelope (and not an attachment on receipt-propose)?
+ * The release digest (`buildReleaseDigest` / `buildPartialReleaseDigest`
+ * in `packages/sdk/src/settlement/settlement.ts`) takes `receiptEventHash`
+ * as one of its inputs. `receipt_event_hash` is the SERVER-ASSIGNED
+ * hash of the receipt envelope — it is computed only AFTER server-side
+ * validation completes (it includes server-assigned `prev_server_event_hash`
+ * + `server_timestamp` in its canonical input). The payee CANNOT
+ * compute the digest at receipt-propose time because the digest input
+ * does not yet exist. So the wire flow is necessarily two envelopes:
+ *
+ *   1. Payee sends `receipt` (propose) — server commits + returns
+ *      `IngestResultDto.serverEventHash`.
+ *   2. Payee reads `serverEventHash`, computes the release digest,
+ *      signs it, and sends THIS `settlement_signature` envelope.
+ *   3. Buyer reads the `settlement_signature` envelope from inbox SSE
+ *      (sender-recipient routing is standard), then assembles the
+ *      `attachments.settlement_signatures` block on the cosign envelope.
+ *
+ * This body type carries ONLY the payee side. The payer's settlement
+ * sig still lands on the cosign envelope's `attachments` block — that
+ * stays unchanged. The server's handler for `settlement_signature`
+ * also performs Ed25519 verification of the payee sig against the
+ * reconstructed digest as defence-in-depth: a bad sig fails loudly on
+ * the worker side instead of stranding the buyer's cosign later.
+ *
+ * Refund flow is NOT served by this body type — `buildRefundDigest`
+ * does NOT bind to `receipt_event_hash` (it binds to lock-derived
+ * fields only), so refund signatures can be computed independent of
+ * any envelope timing and ride their own dedicated paths. The
+ * `purpose` field below is intentionally narrowed to RELEASE +
+ * PARTIAL_RELEASE for the same reason — REFUND-v1 sigs do not belong
+ * on this envelope.
+ */
+export interface SettlementSignatureBody extends Body<SettlementSignatureContent> {
+    type: 'settlement_signature';
+}
+export interface SettlementSignatureContent {
+    /** The delegation whose receipt is being settlement-signed. */
+    delegation_id: string;
+    /**
+     * Server-assigned hash of the receipt-propose envelope this signature
+     * settles. Must match `Receipt.receiptEventHash` server-side; that is
+     * the value the server's cosign-validator feeds into the digest
+     * reconstruction as `receiptEventHash`.
+     */
+    receipt_event_hash: Sha256Hex;
+    /**
+     * Which digest the `sig` was computed over. Narrowed to RELEASE +
+     * PARTIAL_RELEASE: REFUND-v1 sigs ride other paths because the
+     * refund digest is independent of `receipt_event_hash` and never
+     * needs this envelope as a transport.
+     */
+    purpose: 'ARP-SOLANA-RELEASE-v1.5' | 'ARP-SOLANA-PARTIAL-RELEASE-v1.5';
+    /**
+     * Payee's settlement-key public key (base58, 32 bytes raw). The
+     * server cross-checks this against the registered settlement key on
+     * the payee's DID document before re-verifying the sig — a sig
+     * signed by an unregistered key is rejected even if it
+     * mathematically verifies.
+     */
+    payee_settlement_pubkey: string;
+    /**
+     * Ed25519 sig over the reconstructed release/partial-release digest,
+     * **raw base64 — NO `ed25519:` prefix.** Wire format intentionally
+     * mismatches the SDK's prefixed `Ed25519Sig` type because the buyer
+     * forwards this exact string verbatim into
+     * `attachments.settlement_signatures.payee.sig` at cosign time, and
+     * the server's `ReceiptCosignValidatorService.parseBase64Sig`
+     * (`apps/arp-server/src/escrow/services/receipt-cosign-validator.service.ts:557-565`)
+     * `Buffer.from(input, 'base64')` directly — no prefix stripping.
+     * Aligns with the CLI's `--payer-settlement-sig <base64>` /
+     * `--payee-settlement-sig <base64>` flags that consumers already
+     * wire to (see `packages/cli/src/commands/receipt.ts:670-673`).
+     *
+     * Server re-builds the same digest from lock + receipt + envelope
+     * content and verifies this sig as defence-in-depth at handler time
+     * — a malformed or wrong-digest sig is rejected pre-projection so
+     * the bad receipt sig never reaches the buyer's cosign attempt.
+     */
+    sig: string;
+    /**
+     * Unix seconds — the `expires_at` value the payee bound into the
+     * digest. Server re-uses it when reconstructing the digest and
+     * cross-checks against `expires_at > now` + `expires_at <=
+     * lock.expiry - DISPUTE_BUFFER_SECONDS`. The payer
+     * echoes the SAME value on the cosign envelope's settlement_signatures
+     * block so both sides sign the same bytes.
+     */
+    expires_at: number;
+    /**
+     * Base-unit decimal-integer string — required when `purpose ===
+     * 'ARP-SOLANA-PARTIAL-RELEASE-v1.5'`, omitted (or undefined) for
+     * full RELEASE. The server cross-checks it against
+     * `receipt.usage.computed_amount` for usage_based contracts before
+     * verifying the digest (same invariant
+     * `ESC_USAGE_COMPUTED_AMOUNT_MISMATCH` already guards on the
+     * propose-time receipt body).
+     */
+    payee_amount?: string;
+    [extra: string]: unknown;
+}
 /**
  * Union over every standard body type. Consumers can narrow on
  * `body.type` via discriminated dispatch.
  */
-export type AnyBody = HandshakeBody | HandshakeResponseBody | ContractBody | DelegationBody | WorkRequestBody | WorkResponseBody | ReceiptBody | MemoryDeltaBody | DisputeBody;
+export type AnyBody = HandshakeBody | HandshakeResponseBody | ContractBody | DelegationBody | WorkRequestBody | WorkResponseBody | ReceiptBody | MemoryDeltaBody | DisputeBody | SettlementSignatureBody;
 /** Receipt co-signature payload — what gets `payload_hash`'d in `attachments.co_signature`. */
 export interface ReceiptCosignPayload {
     purpose: 'ARP-RECEIPT-v1';

package/dist/types/envelope.d.ts

@@ -97,7 +97,22 @@ export interface SettlementSignatures {
 }
 export interface SettlementParty {
     settlement_pubkey: string;
-    sig: Ed25519Sig;
+    /**
+     * Ed25519 signature, **raw base64 — NO `ed25519:` prefix.** Wire
+     * format intentionally mismatches the prefixed `Ed25519Sig` type
+     * because this block is consumed by the Solana Ed25519Program at
+     * release-tx-builder time, where prefixed strings would break. The
+     * server's `ReceiptCosignValidatorService.parseBase64Sig`
+     * (`apps/arp-server/src/escrow/services/receipt-cosign-validator.service.ts:557-565`)
+     * decodes 64 bytes directly via `Buffer.from(input, 'base64')`
+     * without any prefix stripping. The CLI's
+     * `heyarp wallet sign-settlement-release` already emits raw base64
+     * (`packages/cli/src/commands/wallet.ts:1718-1722`). Matches the
+     * raw-base64 shape of `SettlementSignatureContent.sig` — divergent
+     * types here would leave buyers unable to copy the value verbatim
+     * into the cosign attachment.
+     */
+    sig: string;
 }
 /** Top-level envelope as it appears on the wire. */
 export interface Envelope<TBody extends Body = Body> {

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export type { Sha256Hex, Ed25519Sig, Did, ProtectedBlock, Body, Attachments, CoSignature, SettlementSignatures, SettlementParty, EscrowLockAttachment, Envelope, PersistedEvent, } from './envelope';
-export type { HandshakeBody, HandshakeContent, HandshakeResponseBody, HandshakeResponseContent, ContractBody, ContractContent, DelegationBody, DelegationContent, WorkRequestBody, WorkRequestContent, WorkResponseBody, WorkResponseContent, ReceiptBody, ReceiptContent, MemoryDeltaBody, MemoryDeltaContent, DisputeBody, DisputeContent, AnyBody, ReceiptCosignPayload, DisputeResponseCosignPayload, CosignPayload, DeclineReason, AssetIdentifier, } from './body';
+export type { HandshakeBody, HandshakeContent, HandshakeResponseBody, HandshakeResponseContent, ContractBody, ContractContent, DelegationBody, DelegationContent, WorkRequestBody, WorkRequestContent, WorkResponseBody, WorkResponseContent, ReceiptBody, ReceiptContent, MemoryDeltaBody, MemoryDeltaContent, DisputeBody, DisputeContent, SettlementSignatureBody, SettlementSignatureContent, AnyBody, ReceiptCosignPayload, DisputeResponseCosignPayload, CosignPayload, DeclineReason, AssetIdentifier, } from './body';
 export { DECLINE_REASONS, isDeclineReason } from './body';
 export type { OwnerSigningMethod, KeyLinkPayload, KeyRotationPayload, ScryptPasswordAttestation } from './identity';
 export { SCRYPT_PARAMS } from './identity';

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export { uuidV4 } from './uuid';
 export { senderNonce } from './nonce';
 export { rfc3339, expiresAt } from './timestamp';
+export { pollUntil, type PollUntilOptions, type PollUntilResult } from './poll';

package/dist/utils/poll.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Generic polling helper for SDK consumers that need to block until
+ * an FSM transition lands.
+ *
+ * The SDK is wire-format-only — it has no HTTP client and no
+ * awareness of the relationship/delegation/receipt state-machine
+ * strings. Callers bring their own `fetch` function (axios, native
+ * fetch, custom transport) and their own predicate; this helper
+ * supplies the polling discipline (interval, timeout, cancellable
+ * AbortSignal, exponential backoff on transient errors).
+ *
+ * Why this is useful enough to ship even without a state-machine
+ * type in the SDK: third-party bot authors today write the loop
+ * themselves and routinely get the discipline wrong — they tight-loop
+ * the RPC, ignore timeouts, swallow errors that should propagate, or
+ * miss state transitions that landed between polls. A 40-LOC
+ * primitive with documented behaviour is worth more than the
+ * duplicated `setTimeout` chains it replaces.
+ *
+ * Pairs with the CLI's `--wait-until <phase>` flag on FSM-advancing
+ * commands: same polling shape, same exit-on-predicate semantics,
+ * ported to the API-client layer for callers who don't shell out to
+ * `heyarp`. Either path can be skipped — `heyarp status <rel-id>
+ * --wait --until <phase>` remains the documented escape hatch.
+ */
+/**
+ * Outcome of a `pollUntil` call.
+ *
+ * - `{ kind: 'matched', value }` — predicate returned true; `value`
+ *   is the matched fetcher return.
+ * - `{ kind: 'timeout', last }` — wall-clock exceeded `timeoutMs`;
+ *   `last` is the most recent fetcher return (which DID NOT match the
+ *   predicate) for the caller's diagnostic / retry decision.
+ * - `{ kind: 'aborted', last }` — `abortSignal.aborted` became true;
+ *   `last` is the most recent fetcher return, or `undefined` if the
+ *   abort fired before the first fetch landed.
+ *
+ * Discriminated union (`kind` literal) so consumers can `switch`
+ * exhaustively. No exceptions are thrown for the timeout/abort
+ * outcomes — they're modelled as values so the caller's branching
+ * stays explicit. Fetcher errors are a different story: they bubble
+ * unless `swallowFetchErrors` is true.
+ */
+export type PollUntilResult<T> = {
+    kind: 'matched';
+    value: T;
+} | {
+    kind: 'timeout';
+    last: T | undefined;
+} | {
+    kind: 'aborted';
+    last: T | undefined;
+};
+export interface PollUntilOptions<T> {
+    /**
+     * Async fetcher invoked once per poll tick. Should return the
+     * domain object the predicate evaluates against. Implementations
+     * typically read the same row the CLI's `composeStatus` reads —
+     * a single signed-GET against the relationship's entities is
+     * common.
+     */
+    fetch: () => Promise<T>;
+    /**
+     * Returns `true` when `value` satisfies the wait condition. The
+     * helper exits with `{ kind: 'matched', value }` on the first
+     * `true`. Predicate exceptions bubble (treat as a fail-fast
+     * programmer error — the predicate shouldn't be side-effectful or
+     * I/O-bound).
+     */
+    predicate: (value: T) => boolean;
+    /** Milliseconds between fetches. Defaults to 3000 (matches CLI WAIT_DEFAULT_INTERVAL_SEC). Lower bound is 100ms to avoid tight-loop accidents. */
+    intervalMs?: number;
+    /** Wall-clock budget in milliseconds. Defaults to 300000 (5 min). On exceed, returns `{ kind: 'timeout', last }`. */
+    timeoutMs?: number;
+    /**
+     * If true, fetch errors are caught and logged via `onFetchError`
+     * (or silently swallowed when that's absent); the loop continues
+     * to the next tick. If false (default), the first fetch error
+     * rejects the returned promise — appropriate for "fail loud on
+     * the first network blip" scripts.
+     */
+    swallowFetchErrors?: boolean;
+    /**
+     * Called once per fetch error when `swallowFetchErrors` is true.
+     * Gets the raw error so the caller can log / sample / surface to
+     * an observability sink without coupling the polling primitive to
+     * any particular logger.
+     */
+    onFetchError?: (err: unknown) => void;
+    /**
+     * Cancellation signal — when its `aborted` flag flips, the
+     * helper resolves with `{ kind: 'aborted', last }` after the
+     * current sleep completes (or immediately if currently mid-sleep
+     * and the signal supports listener-driven abort). The fetcher
+     * itself is not abort-aware here; if it needs to be, the caller
+     * should pass the same signal into its own implementation.
+     */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Poll `fetch` until `predicate` returns true, the timeout fires, or
+ * the optional `abortSignal` aborts. Returns a discriminated outcome
+ * (no exceptions for the expected paths).
+ *
+ * Behaviour notes:
+ *   - The first fetch happens immediately (no leading sleep). If the
+ *     predicate matches on the first call, returns without any sleep
+ *     — useful when the caller already knows the state may have
+ *     transitioned in the background.
+ *   - Sleeps are clamped to the remaining budget; the final sleep
+ *     will be shorter than `intervalMs` when timeout is near.
+ *   - Lower-bound `intervalMs` to 100ms. Higher-frequency polling is
+ *     an accident; if you really need it, build your own loop with
+ *     direct `setTimeout` calls.
+ */
+export declare function pollUntil<T>(opts: PollUntilOptions<T>): Promise<PollUntilResult<T>>;

package/dist/webhook/index.d.ts

@@ -1,2 +1,3 @@
-export { buildWebhookSignatureHeader, verifyWebhookSignatureHeader } from './webhook';
-export type { WebhookSignableInput } from './webhook';
+export { buildWebhookSignatureHeader, isProbeRequest, sha256HexLower, verifyAndCheckPayload, verifyWebhookSignatureHeader } from './webhook';
+export type { WebhookSignableInput, WebhookSignableSource } from './webhook';
+export type { ChainEventRecoveryRow, ChainEventRecoveryRowCommon, ChainPayloadCommon, ChainWebhookPayload, DisputeResolvedWebhookPayload, EnvelopeWebhookPayload, LockCreatedWebhookPayload, LockPartiallyReleasedWebhookPayload, LockRefundedWebhookPayload, LockReleasedWebhookPayload, WebhookPayload, } from './payload-types';

package/dist/webhook/payload-types.d.ts

@@ -0,0 +1,198 @@
+/**
+ * SDK consumer types for the on-the-wire body the OutboxDeliveryWorker
+ * POSTs to a recipient's `webhookUrl`. Mirrors the JSON shape the
+ * server's `OutboxDeliveryWorkerService.deliver` builds.
+ *
+ * The body is a discriminated union on `event_type`:
+ *
+ *   - `envelope.<type>` → `payload` is the envelope `EventPublic`
+ *     shape (eventId, messageId, sender/recipient DIDs, protected
+ *     block, body, attachments, server-derived hashes).
+ *   - `escrow.<event>` → `payload` is the per-event-type chain shape
+ *     (delegation/lock IDs, amounts, verdict, etc.).
+ *
+ * Recipient TypeScript consumers `switch (payload.event_type)` to
+ * branch exhaustively without `default` — drift on either side
+ * surfaces as a missing-case compile error.
+ */
+/**
+ * What the server-side `events` collection row looks like on the wire
+ * after `buildEnvelopeDeliveryPayload` formatting. Recipients see the
+ * full canonical envelope so they can re-verify the signature locally
+ * with the SDK (same call they'd make on `/inbox?since=` rows).
+ *
+ * Body shape varies by `type` — keep `body` open (the SDK's
+ * type-narrowing for each `BodyType` lives in
+ * `packages/sdk/src/envelope/*` and is consumed when the recipient
+ * branches on body.type).
+ */
+export interface EnvelopeWebhookPayload {
+    event_type: `envelope.${string}`;
+    delivery_id: string;
+    attempt_n: number;
+    served_at: string;
+    payload: {
+        eventId: string;
+        messageId: string;
+        senderDid: string;
+        recipientDid: string;
+        relationshipId: string;
+        senderSequence: number;
+        protocolVersion: string;
+        purpose: string;
+        type: string;
+        protectedBlock: Record<string, unknown>;
+        body: Record<string, unknown>;
+        attachments?: Record<string, unknown>;
+        senderSignature: string;
+        relationshipEventIndex: number;
+        prevServerEventHash: string | null;
+        serverTimestamp: string;
+        signedMessageHash: string;
+        serverEventHash: string;
+    };
+}
+/**
+ * Fields every chain-source payload carries. `chain_event_id` +
+ * `instruction_idx` let the recipient reconstruct
+ * `WebhookSignableInput.source` for HMAC verification from the body
+ * alone — no reverse-parse of `delivery_id` required.
+ */
+export interface ChainPayloadCommon {
+    chain_event_id: string;
+    instruction_idx: number;
+    delegation_id: string;
+    relationship_id: string;
+    payer_did: string;
+    payee_did: string;
+    tx_signature: string;
+    slot: number;
+    block_time_iso?: string;
+    lock_id: string;
+}
+export interface LockCreatedWebhookPayload {
+    event_type: 'escrow.lock_created';
+    delivery_id: string;
+    attempt_n: number;
+    served_at: string;
+    payload: ChainPayloadCommon & {
+        amount: string;
+        asset_id?: string;
+        expiry_unix?: number;
+        fee_bps?: number;
+        fee_recipient?: string;
+    };
+}
+export interface LockReleasedWebhookPayload {
+    event_type: 'escrow.lock_released';
+    delivery_id: string;
+    attempt_n: number;
+    served_at: string;
+    payload: ChainPayloadCommon & {
+        released_amount: string;
+    };
+}
+export interface LockPartiallyReleasedWebhookPayload {
+    event_type: 'escrow.lock_partially_released';
+    delivery_id: string;
+    attempt_n: number;
+    served_at: string;
+    payload: ChainPayloadCommon & {
+        released_amount: string;
+        refunded_amount: string;
+    };
+}
+export interface LockRefundedWebhookPayload {
+    event_type: 'escrow.lock_refunded';
+    delivery_id: string;
+    attempt_n: number;
+    served_at: string;
+    payload: ChainPayloadCommon & {
+        refunded_amount: string;
+        reason?: string;
+    };
+}
+export interface DisputeResolvedWebhookPayload {
+    event_type: 'escrow.dispute_resolved';
+    delivery_id: string;
+    attempt_n: number;
+    served_at: string;
+    payload: ChainPayloadCommon & {
+        verdict: string;
+    };
+}
+/**
+ * Discriminated union of every webhook delivery the recipient might
+ * receive. Use exhaustive `switch` on `event_type`:
+ *
+ * ```ts
+ * function handle(p: WebhookPayload) {
+ *   switch (p.event_type) {
+ *     case 'escrow.lock_created': return onLockCreated(p);
+ *     case 'escrow.lock_released': return onLockReleased(p);
+ *     case 'escrow.lock_partially_released': return onPartial(p);
+ *     case 'escrow.lock_refunded': return onRefund(p);
+ *     case 'escrow.dispute_resolved': return onDispute(p);
+ *     default:
+ *       // p.event_type is `envelope.${string}` here
+ *       return onEnvelope(p);
+ *   }
+ * }
+ * ```
+ *
+ * The chain branches narrow exhaustively because each is a string-
+ * literal type; the envelope branch carries the catch-all
+ * `envelope.${string}` template-literal type so recipients can
+ * still narrow on `payload.type` if they care about specific body
+ * types.
+ */
+export type ChainWebhookPayload = LockCreatedWebhookPayload | LockReleasedWebhookPayload | LockPartiallyReleasedWebhookPayload | LockRefundedWebhookPayload | DisputeResolvedWebhookPayload;
+export type WebhookPayload = EnvelopeWebhookPayload | ChainWebhookPayload;
+/**
+ * Fields every recovery row carries irrespective of event type — the
+ * envelope around the per-event-type `payload`.
+ */
+export interface ChainEventRecoveryRowCommon {
+    chain_event_id: string;
+    delegation_id: string;
+    relationship_id: string;
+    lock_id: string;
+    tx_signature: string;
+    slot: number;
+    block_time_iso?: string;
+    created_at: string;
+}
+/**
+ * Recovery channel for chain events. Returned by the
+ * `GET /v1/agents/me/chain-events?since=…` endpoint. Recipients call
+ * this on handler restart / reconnection to catch any chain events
+ * they missed while their handler was down.
+ *
+ * **Discriminated union**: both `event_type` and `payload` come from
+ * the SAME tagged union — `switch (row.event_type)` narrows
+ * `row.payload` to the right per-event-type shape so the advertised
+ * "share a single handler between push and pull" actually type-checks.
+ *
+ *   switch (row.event_type) {
+ *     case 'escrow.lock_released':
+ *       // row.payload is LockReleasedWebhookPayload['payload'] here
+ *       break;
+ *     ...
+ *   }
+ */
+export type ChainEventRecoveryRow = ChainEventRecoveryRowCommon & ({
+    event_type: 'escrow.lock_created';
+    payload: LockCreatedWebhookPayload['payload'];
+} | {
+    event_type: 'escrow.lock_released';
+    payload: LockReleasedWebhookPayload['payload'];
+} | {
+    event_type: 'escrow.lock_partially_released';
+    payload: LockPartiallyReleasedWebhookPayload['payload'];
+} | {
+    event_type: 'escrow.lock_refunded';
+    payload: LockRefundedWebhookPayload['payload'];
+} | {
+    event_type: 'escrow.dispute_resolved';
+    payload: DisputeResolvedWebhookPayload['payload'];
+});

package/dist/webhook/webhook.d.ts

@@ -2,37 +2,157 @@
  * `ARP-WEBHOOK-v1` HMAC over the canonical webhook envelope. Used by
  * the OutboxDeliveryWorker for the `X-ARP-Signature` header.
  *
- * Inputs (per backend's outbox spec):
- *   - delivery_id              — outbox row id
- *   - recipient_did
- *   - envelope_message_id      — envelope being delivered
- *   - server_event_hash        — chain head at delivery time
- *   - attempt_n                — 1-based retry counter
- *   - served_at                — RFC3339, when this attempt was generated
- *
- * Each retry produces a different MAC because `attempt_n` and
- * `served_at` participate in canonical input — replays of an old
- * header on a fresh attempt fail HMAC verification.
+ * The signable input is a discriminated `source` union covering BOTH
+ * envelope deliveries (`source.kind === 'envelope'`) AND chain
+ * settlement events (`source.kind === 'chain'`). The single
+ * canonical-JSON output binds the HMAC to the source variant so a
+ * recipient receiving a chain webhook can't accidentally verify
+ * against an envelope-shaped signable, and vice versa.
+ *
+ * The body-tampering defence (`payload_sha256`) is mandatory on the
+ * new shape — recipients SHOULD verify the hash matches their
+ * received raw body BEFORE the HMAC check (cheap, and surfaces
+ * "wrong body" as a separate diagnostic from "wrong HMAC").
  */
+export type WebhookSignableSource = {
+    kind: 'envelope';
+    envelope_message_id: string;
+    server_event_hash: string;
+} | {
+    kind: 'chain';
+    chain_event_id: string;
+    tx_signature: string;
+    instruction_idx: number;
+};
 export interface WebhookSignableInput {
+    /** Outbox row id (deterministic per delivery attempt). */
     delivery_id: string;
     recipient_did: string;
-    envelope_message_id: string;
-    server_event_hash: string;
+    /** Public event-type discriminator (`envelope.<type>` or `escrow.<event>`). */
+    event_type: string;
+    /** Source-variant discriminated union. Binds the HMAC to the kind. */
+    source: WebhookSignableSource;
+    /** SHA-256 (lowercase hex, no `sha256:` prefix) of the canonical raw body bytes the recipient receives. */
+    payload_sha256: string;
+    /** 1-based retry counter — participates in canonical input so replays of an old header on a fresh attempt fail. */
     attempt_n: number;
+    /** RFC 3339 wall-clock time the server generated this attempt. Recipient policy MAY reject outside a tolerance window. */
     served_at: string;
 }
 /**
- * Compute `X-ARP-Signature` value: `<purpose>=<base64(HMAC-SHA256(secret, sha256(canonical_json(input))))>`.
+ * Compute `X-ARP-Signature` value:
+ *   `<purpose>=<base64(HMAC-SHA256(secret, sha256(canonical_json(input))))>`.
  *
- * Recipients lookup their per-sender shared secret, recompute the
+ * Recipients lookup their per-sender shared secret(s), recompute the
  * HMAC over the same canonical input, and compare against the
- * received header.
+ * received header. See `verifyWebhookSignatureHeader` for the
+ * standard recipient flow with rotation grace.
  */
 export declare function buildWebhookSignatureHeader(input: WebhookSignableInput, sharedSecret: Uint8Array): string;
 /**
- * Constant-time compare an inbound `X-ARP-Signature` header against
- * the expected one. Returns `false` on shape mismatch, missing
- * purpose label, or HMAC mismatch — never throws.
+ * Verify an inbound `X-ARP-Signature` header against the reconstructed
+ * signable input. The 3-argument form is the convenience for
+ * single-secret consumers (most use); the array form is the rotation-
+ * grace path (two-phase rotate: recipient verifies against
+ * `[current, pending, previous]` during the 1h grace window).
+ *
+ * Returns `false` on shape mismatch, missing purpose label, OR HMAC
+ * mismatch under EVERY supplied secret. Never throws.
+ *
+ * **Timing-uniform across rotation slots** — the array form runs ALL
+ * HMAC computations + constant-time compares before returning, so the
+ * total time is proportional to N (number of secrets) regardless of
+ * which slot matched. A short-circuiting implementation would leak
+ * the position of the matching key via total time. Practical impact
+ * is small (attacker would only learn "current vs pending vs previous
+ * matched", not key material), but timing-uniform is the right
+ * default for a verification primitive.
+ *
+ * Recipient flow:
+ *   1. Receive POST with `X-ARP-Signature` header + raw body bytes.
+ *   2. Compute `payload_sha256 = sha256-hex(rawBodyBytes)`.
+ *   3. Reconstruct `WebhookSignableInput` from headers + payload sha256.
+ *   4. Call `verifyWebhookSignatureHeader(header, input, [current, pending, previous].filter(Boolean))`.
+ *   5. On `true`, accept. On `false`, 401 the request.
+ *
+ * Helper `verifyAndCheckPayload` (below) bundles steps 2-4 into one
+ * call for the common path.
+ */
+export declare function verifyWebhookSignatureHeader(headerValue: string, input: WebhookSignableInput, sharedSecret: Uint8Array | Uint8Array[]): boolean;
+/**
+ * Recipient convenience: combine body-hash binding + HMAC verify +
+ * optional `served_at` clock-skew tolerance into one call.
+ *
+ *   1. Compute `payload_sha256 = sha256-hex(rawBody)` and OVERLAY it
+ *      onto `input.payload_sha256` (caller's value, if any, is
+ *      replaced).
+ *   2. Verify `served_at` is within `toleranceMs` of `now()` (default
+ *      ±5 minutes; pass `null` to skip).
+ *   3. Verify HMAC against each secret in `secrets`.
+ *
+ * Returns a tagged outcome the caller can branch on:
+ *   - `'ok'` — accept the delivery
+ *   - `'stale_attempt'` — served_at outside the tolerance window
+ *   - `'invalid_signature'` — HMAC didn't verify under any secret
+ *
+ * **Why no `body_mismatch` outcome** — `payload_sha256` is a derived
+ * field bound to the raw body. The HMAC signs the input INCLUDING
+ * `payload_sha256`, so a tampered body causes the recipient's
+ * recomputed hash to differ from the server-signed one, which fails
+ * the HMAC check as `'invalid_signature'`. Body tampering is
+ * detected via the HMAC failure; if you need a dedicated diagnostic,
+ * compute `sha256HexLower(rawBody)` yourself and compare to an
+ * out-of-band trusted source (e.g. a signed mirror of the body).
+ */
+export declare function verifyAndCheckPayload(args: {
+    headerValue: string;
+    /** Reconstructed signable input MINUS `payload_sha256` — helper computes that field from `rawBody`. */
+    input: Omit<WebhookSignableInput, 'payload_sha256'>;
+    rawBody: Uint8Array;
+    secrets: Uint8Array | Uint8Array[];
+    servedAtToleranceMs?: number | null;
+    now?: Date;
+}): 'ok' | 'stale_attempt' | 'invalid_signature';
+/**
+ * Probe-skip helper for recipient handlers. The `POST /v1/agents/me/webhook-config`
+ * flow fires an UNSIGNED probe POST with the `X-ARP-Probe: 1` header.
+ * Recipient handlers MUST 2xx without HMAC verification on probe
+ * requests — otherwise the operator can't set their webhook URL
+ * (the probe gets rejected as unsigned, the URL persist step fails).
+ *
+ * Use this at the top of your handler:
+ *
+ * ```ts
+ * if (isProbeRequest(req.headers)) {
+ *   res.statusCode = 200;
+ *   res.end();
+ *   return;
+ * }
+ * // Otherwise: verify signature normally.
+ * ```
+ *
+ * Header values are inspected case-insensitively per Node's
+ * IncomingMessage convention.
+ *
+ * **SECURITY (spoofability)** — the helper is a pure header check;
+ * it cannot itself defend against an attacker setting
+ * `X-ARP-Probe: 1` to bypass HMAC verification. The probe branch
+ * in your handler MUST be side-effect-free:
+ *
+ *   - Respond 2xx with an empty body — no DB write, no downstream
+ *     fan-out, no metric increment that an attacker could amplify.
+ *   - Consider rate-limiting probe-skipped requests per source IP if
+ *     the surrounding stack doesn't already.
+ *   - Do NOT log full request bodies on the probe branch (an
+ *     attacker can pump log noise).
+ *   - If your handler genuinely has zero side-effects on a 200
+ *     response, this is automatic; otherwise treat the probe branch
+ *     as you would an unauthenticated health-check endpoint.
+ */
+export declare function isProbeRequest(headers: Record<string, string | string[] | undefined>): boolean;
+/**
+ * SHA-256 hex digest of the input bytes, lowercase. Exported for unit
+ * tests + the rare consumer that needs to compute payload_sha256
+ * outside `verifyAndCheckPayload`.
  */
-export declare function verifyWebhookSignatureHeader(headerValue: string, input: WebhookSignableInput, sharedSecret: Uint8Array): boolean;
+export declare function sha256HexLower(bytes: Uint8Array): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyanon-arp/sdk",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "TypeScript SDK for the Agent Relationship Protocol — canonical JSON, Ed25519 envelope sign/verify, did:arp identity, receipt co-signatures, scrypt key attestation, chain-audit helpers.",
   "license": "MIT",
   "keywords": [