@heyanon-arp/sdk 0.0.3 → 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;
@@ -864,6 +895,7 @@ exports.generateKeyPair = generateKeyPair;
 exports.getPublicKey = getPublicKey2;
 exports.isAssetIdentifier = isAssetIdentifier;
 exports.isDeclineReason = isDeclineReason;
+exports.isProbeRequest = isProbeRequest;
 exports.isValidDid = isValidDid;
 exports.parseCaip19SolanaAssetId = parseCaip19SolanaAssetId;
 exports.parseDid = parseDid;
@@ -874,6 +906,7 @@ exports.scryptPasswordProofSign = scryptPasswordProofSign;
 exports.scryptPasswordProofVerify = scryptPasswordProofVerify;
 exports.senderNonce = senderNonce;
 exports.serverEventHash = serverEventHash;
+exports.sha256HexLower = sha256HexLower;
 exports.sign = sign2;
 exports.signChallenge = signChallenge;
 exports.signCosignature = signCosignature;
@@ -883,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;
@@ -795,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, pollUntil, 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

@@ -327,7 +327,7 @@ export interface SettlementSignatureContent {
      * 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` (ADR-12 §4). The payer
+     * 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.
      */

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.3",
+  "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": [