@heyanon-arp/sdk 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# `@heyanon-arp/sdk`
+
+TypeScript SDK for the **Agent Relationship Protocol** (ARP) — the
+crypto + canonical-JSON building blocks for autonomous agents that
+exchange signed messages, co-sign receipts, and settle on chain.
+
+If you're building a custom client (a non-Node runtime, a browser
+extension, a Python bridge, an internal agent framework) and you want
+your envelopes / receipts / attestations to be byte-identical to
+what the reference ARP server expects, this is the library to wire in.
+
+If you just want to talk to a running ARP server from the command line,
+use [`@heyanon-arp/cli`](https://www.npmjs.com/package/@heyanon-arp/cli)
+instead — it depends on this SDK internally.
+
+## Install
+
+```bash
+npm install @heyanon-arp/sdk
+# or: pnpm add @heyanon-arp/sdk
+```
+
+Requires **Node ≥ 22** (uses Ed25519 / WebCrypto from `node:crypto`).
+ESM + CJS builds + TypeScript declarations all ship in the same package.
+
+## Quick start
+
+### Generate a DID + keypair
+
+```ts
+import { formatDid, generateKeyPair } from '@heyanon-arp/sdk';
+
+const kp  = generateKeyPair();
+const did = formatDid(kp.publicKey); // "did:arp:7c3GhJ8L…"
+```
+
+### Sign + verify an envelope
+
+```ts
+import {
+  Purpose, expiresAt, formatDid, generateKeyPair, rfc3339,
+  senderNonce, signEnvelope, uuidV4, verifyEnvelope,
+} from '@heyanon-arp/sdk';
+
+const sender    = generateKeyPair();
+const senderDid = formatDid(sender.publicKey);
+
+const envelope = signEnvelope({
+  protected: {
+    protocol_version: 'arp/0.1',
+    purpose:          Purpose.ENVELOPE,
+    message_id:       uuidV4(),
+    sender_did:       senderDid,
+    recipient_did:    'did:arp:9bDfQp2M…',
+    relationship_id:  null,            // first handshake
+    sender_sequence:  1,
+    sender_nonce:     senderNonce(),
+    timestamp:        rfc3339(),
+    expires_at:       expiresAt(3600), // 1 hour from now
+    delivery_id:      null,
+  },
+  body: { type: 'handshake', content: { greeting: 'hello' } },
+  identitySecretKey: sender.secretKey,
+});
+
+// On the receiver:
+const result = verifyEnvelope(envelope, sender.publicKey);
+if (!result.ok) throw new Error(`envelope rejected: ${result.reason}`);
+```
+
+### Co-sign a receipt
+
+```ts
+import { signCosignature, verifyCosignature } from '@heyanon-arp/sdk';
+
+const cs = signCosignature({
+  payload: {
+    purpose:            'ARP-RECEIPT-v1',
+    delegation_id:      'del_…',
+    receipt_event_hash: 'sha256:…',
+    verdict:            'accepted',
+    notes_hash:         null,
+  },
+  signerDid:         senderDid,
+  identitySecretKey: sender.secretKey,
+});
+
+verifyCosignature({ cosignature: cs, payload: cs.payload, signerIdentityPubkey: sender.publicKey });
+```
+
+## What's in the box
+
+| Module          | What it does                                                                  |
+|-----------------|-------------------------------------------------------------------------------|
+| `canonical`     | RFC 8785 JCS canonical JSON, sha256 helpers, signing-input bytes              |
+| `keys`          | Ed25519 generate/sign/verify, base58btc + base64 encoding                     |
+| `did`           | `did:arp:<base58btc>` parse/format, DID document types                        |
+| `envelope`      | `signEnvelope` / `verifyEnvelope` — the wire-level message signing            |
+| `cosignature`   | `ARP-RECEIPT-v1` + `ARP-DISPUTE-RESPONSE-v1` co-signatures                    |
+| `challenge`     | `ARP-CHALLENGE-v1` ownership proof for identity registration                  |
+| `webhook`       | `ARP-WEBHOOK-v1` HMAC for the outbox `X-ARP-Signature` header                 |
+| `attestation`   | `ARP-KEY-LINK-v1` / `ARP-KEY-ROTATION-v1` (scrypt password proof)             |
+| `server-chain`  | `signed_message_hash` + `server_event_hash` builders for chain audit          |
+| `settlement`    | `ARP-SOLANA-RELEASE-v1.5` / `…-PARTIAL-RELEASE-v1.5` / `…-REFUND-v1` digests  |
+| `escrow`        | Solana `create_lock` ix data builder, condition-hash derivation               |
+| `purpose`       | Domain separator constants                                                    |
+| `utils`         | UUID v4, sender_nonce, RFC 3339 timestamp helpers                             |
+| `types`         | Wire-level TypeScript types (envelope, body shapes, attestations)             |
+
+## What's NOT in here
+
+The SDK is deliberately **client-side / shared primitives** only. Server
+concerns live in the backend implementation, not the SDK:
+
+- Replay defence (Redis dedup of `message_id`, `sender_sequence` enforcement)
+- Time-window check (±5 min, `expires_at` future)
+- JSON schema validation
+- Server-side chain assignment (`relationship_event_index`,
+  `prev_server_event_hash`, `server_event_hash` write)
+- Inbox / pricing policy evaluation
+- Rate limits
+
+## Conformance
+
+Any other-language SDK (Python, Go, Rust…) **must** reproduce identical
+canonical bytes for the golden vectors in this package's `test/canonical-vectors.json`
+to claim ARP conformance. Same envelope → same `signed_message_hash` →
+same Ed25519 signature.
+
+## Versioning
+
+Semver:
+- **Major** — protocol version bump (`arp/0.1` → `arp/0.2`), envelope
+  structure change, signature-input shape change, public function
+  return-type change.
+- **Minor** — new exported helpers, new optional fields, new `Purpose`
+  constants.
+- **Patch** — bug fixes that don't change observable behaviour.
+
+## See also
+
+- [`@heyanon-arp/cli`](https://www.npmjs.com/package/@heyanon-arp/cli) —
+  command-line client built on top of this SDK.
+
+## License
+
+MIT

package/dist/assets.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Well-known asset shorthand table + CAIP-19 helpers.
+ *
+ * The protocol carries assets as `AssetIdentifier` ({ asset_id, decimals,
+ * symbol? }) with `asset_id` always a CAIP-19 string. Operators almost
+ * always work with two assets — USDC and native SOL on either mainnet
+ * or devnet — and typing 90-char CAIP-19 strings on every CLI call is
+ * hostile. This module:
+ *
+ *   1. Exports `WELL_KNOWN_ASSETS` — the four mainstream entries
+ *      mapped from shorthand keys to canonical `AssetIdentifier`.
+ *   2. Exports `resolveAsset(input)` — accepts either a shorthand key
+ *      OR a raw CAIP-19 string. Shorthand resolves from the table;
+ *      raw CAIP-19 is returned unchanged with `decimals: null`
+ *      sentinel (caller must supply via separate flag/field).
+ *   3. Exports `CAIP19_REGEX` — the validation regex (server-side and
+ *      client-side both lean on the same source of truth).
+ *
+ * V1 launch ships only the four shorthand entries — extending the
+ * table is a SemVer-minor patch. Adding a Solana cluster (testnet?)
+ * is one entry. Adding a different chain (Ethereum, Polygon) is two
+ * entries (the native + USDC equivalent on that chain).
+ */
+import type { AssetIdentifier } from './types/body';
+/**
+ * Solana cluster genesis-hash prefixes per CAIP-2 (`solana:<cluster_id>`).
+ * The full genesis hash is 32 bytes; CAIP-2 uses the first 32 chars
+ * of the base58 representation (= 24 bytes ≈ 256 bits).
+ *
+ * Sources:
+ *   - mainnet-beta genesis: `5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpgnAv6oW4HXJK`
+ *     → prefix `5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
+ *   - devnet genesis: `EtWTRABZaYq6iMfeYKouRu166VU2xqaq2gP7e2pAjFhX`
+ *     → prefix `EtWTRABZaYq6iMfeYKouRu166VU2xqa1` (note: chainagnostic.org canonical form
+ *       truncates at 32 chars; the actual genesis prefix lookup table is fixed)
+ */
+export declare const SOLANA_CLUSTER_IDS: {
+    readonly 'solana-mainnet': "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    readonly 'solana-devnet': "EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+};
+/**
+ * SLIP-44 coin types — `slip44:<coin_type>` for native chain assets.
+ * Solana = 501 (https://github.com/satoshilabs/slips/blob/master/slip-0044.md).
+ */
+export declare const SLIP44_SOLANA = 501;
+/**
+ * Canonical SPL mints for USDC across the two Solana clusters we
+ * support at V1 launch. Source: Circle's official USDC documentation.
+ */
+export declare const USDC_MINTS: {
+    readonly 'solana-mainnet': "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+    readonly 'solana-devnet': "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+};
+/**
+ * Shorthand → `AssetIdentifier`. Keys follow the pattern
+ * `<TICKER>:<CLUSTER>` so a glance tells you both the asset and the
+ * cluster.
+ */
+export declare const WELL_KNOWN_ASSETS: Readonly<Record<string, AssetIdentifier>>;
+/**
+ * CAIP-19 strict regex. Reused by:
+ *   - Server-side envelope validation (rejects malformed `asset_id`)
+ *   - SDK-side `resolveAsset` (distinguishes raw CAIP-19 from shorthand)
+ *   - CLI flag validation
+ *
+ * Per CAIP-19 spec:
+ *   asset_id        = chain_id "/" asset_namespace ":" asset_reference
+ *   chain_id        = chain_namespace ":" chain_reference
+ *   chain_namespace = [-a-z0-9]{3,8}
+ *   chain_reference = [-_a-zA-Z0-9]{1,32}
+ *   asset_namespace = [-a-z0-9]{3,8}
+ *   asset_reference = [-.%a-zA-Z0-9]{1,128}
+ */
+export declare const CAIP19_REGEX: RegExp;
+/**
+ * Type guard for `AssetIdentifier`. Validates structural shape +
+ * CAIP-19 conformance of `asset_id` + decimals range. Symbol is
+ * optional but if present must be 1-16 chars.
+ */
+export declare function isAssetIdentifier(value: unknown): value is AssetIdentifier;
+/**
+ * Resolve a shorthand key OR raw CAIP-19 string to an `AssetIdentifier`.
+ *
+ * Returns:
+ *   - shorthand match → full `AssetIdentifier` from the table
+ *   - raw CAIP-19 match → `{ asset_id: input, decimals: NaN, symbol: undefined }`
+ *     (caller MUST supply decimals separately — NaN is a loud signal,
+ *     not a useful default)
+ *   - neither → `null`
+ *
+ * The NaN-on-raw-input behaviour exists because decimals can't be
+ * inferred from CAIP-19 alone — `slip44:501` is SOL (9 decimals) but
+ * `slip44:60` is ETH (18 decimals) and we don't ship a coin-type
+ * registry in V1. Callers using raw CAIP-19 are expected to pass
+ * `--rate-decimals <N>` alongside.
+ */
+export declare function resolveAsset(input: string): AssetIdentifier | null;
+/**
+ * Lookup table keys exported for `--help` choices in the CLI.
+ */
+export declare const WELL_KNOWN_ASSET_KEYS: readonly string[];

package/dist/attestation/attestation.d.ts

@@ -0,0 +1,29 @@
+import type { KeyLinkPayload, KeyRotationPayload, ScryptPasswordAttestation } from '../types/identity';
+/**
+ * Build an `ARP-KEY-LINK-v1` attestation record signed via
+ * `scrypt_password_proof` (V1 default). Caller assembles the payload
+ * (DID, both pubkeys, owner_id, nonce, etc.); SDK produces the MAC
+ * and wraps the record in the standard shape.
+ *
+ * Use [signKeyRotationAttestation](#signkeyrotationattestation) for
+ * rotation events — they use a different `purpose` and break the
+ * `agent_did = base58btc(identity_public_key)` invariant.
+ */
+export declare function signKeyLinkAttestation(input: {
+    payload: KeyLinkPayload;
+    scryptKey: Uint8Array;
+    scryptSaltId: string;
+}): ScryptPasswordAttestation<KeyLinkPayload>;
+export declare function verifyKeyLinkAttestation(attestation: ScryptPasswordAttestation<KeyLinkPayload>, scryptKey: Uint8Array): boolean;
+/**
+ * Build an `ARP-KEY-ROTATION-v1` attestation. Same scrypt+HMAC
+ * mechanics as KEY-LINK but with rotation-specific payload fields
+ * (`current_identity_public_key` + `new_identity_public_key` +
+ * `supersedes_attestation_id`). The DID stays frozen.
+ */
+export declare function signKeyRotationAttestation(input: {
+    payload: KeyRotationPayload;
+    scryptKey: Uint8Array;
+    scryptSaltId: string;
+}): ScryptPasswordAttestation<KeyRotationPayload>;
+export declare function verifyKeyRotationAttestation(attestation: ScryptPasswordAttestation<KeyRotationPayload>, scryptKey: Uint8Array): boolean;

package/dist/attestation/index.d.ts

@@ -0,0 +1,2 @@
+export { deriveScryptKey, scryptPasswordProofSign, scryptPasswordProofVerify } from './scrypt-proof';
+export { signKeyLinkAttestation, verifyKeyLinkAttestation, signKeyRotationAttestation, verifyKeyRotationAttestation } from './attestation';

package/dist/attestation/scrypt-proof.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Derive the scrypt key from an owner's password + salt. Uses V1
+ * standard parameters: N=32768, r=8, p=1, dkLen=32. Designed to be
+ * computed once at owner registration time and stored encrypted-at-rest;
+ * subsequent attestation verification recomputes the HMAC, not scrypt.
+ *
+ * Synchronous variant is intentional — the SDK targets V1 deployments
+ * where keys derive at low frequency (once per owner registration);
+ * the worst case is a few hundred ms which is acceptable. Async
+ * variants can be layered on top by the consumer if needed.
+ */
+export declare function deriveScryptKey(password: string, salt: Uint8Array): Uint8Array;
+/**
+ * Compute the scrypt-password-proof signature over the canonical
+ * payload bytes, returning the base64-encoded MAC.
+ *
+ * Steps per [00-core/identity.md](../../../00-core/identity.md):
+ *   1. payload_digest = sha256(canonical_json(payload))
+ *   2. mac            = HMAC-SHA256(scrypt_key, payload_digest)
+ *   3. sig            = base64(mac)
+ */
+export declare function scryptPasswordProofSign(payload: unknown, scryptKey: Uint8Array): string;
+/**
+ * Verify a scrypt-password-proof signature. Constant-time compare on
+ * MAC bytes — never compares strings directly because base64 decoding
+ * normalises some inputs which would mask differences.
+ */
+export declare function scryptPasswordProofVerify(payload: unknown, sigBase64: string, scryptKey: Uint8Array): boolean;

package/dist/canonical/canonicalize.d.ts

@@ -0,0 +1,33 @@
+import type { Sha256Hex } from '../types/envelope';
+/**
+ * RFC 8785 JCS canonical JSON serialization.
+ *
+ * Re-export of the reference `canonicalize` package by Anders Rundgren
+ * (the RFC author). Wrapped here so the rest of the SDK doesn't depend
+ * on the third-party module name directly — if we ever swap the
+ * implementation, only this file changes.
+ *
+ * Properties guaranteed by the spec, relevant to ARP:
+ *   - object keys sorted lexicographically by UTF-16 code units
+ *   - numbers serialized per ECMAScript JSON.stringify (no trailing zeros, no `+E`)
+ *   - strings escape only the mandatory characters (`"`, `\`, control bytes)
+ *   - no whitespace, no trailing commas, no UTF-8 BOM
+ *
+ * The protocol forbids `undefined` and non-finite numbers; this function
+ * inherits the underlying library behaviour: `undefined` values inside
+ * objects are dropped, top-level `undefined` returns `undefined`, and
+ * non-finite numbers throw. ARP-side validators should reject such
+ * inputs before reaching this layer.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * UTF-8 encode the canonical JSON of `value`. The byte form is what
+ * gets fed to hashing / signing.
+ */
+export declare function canonicalBytes(value: unknown): Uint8Array;
+/**
+ * sha256 of `canonical_json(value)`, formatted as the protocol's
+ * `sha256:<hex>` string. Used for `body_hash`, `attachments_hash`,
+ * `payload_hash` in co-signatures, etc.
+ */
+export declare function canonicalSha256Hex(value: unknown): Sha256Hex;

package/dist/canonical/index.d.ts

@@ -0,0 +1 @@
+export { canonicalJson, canonicalBytes, canonicalSha256Hex } from './canonicalize';

package/dist/challenge/challenge.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Produce the Ed25519 signature that proves identity-key ownership
+ * of `challengeBytes`.
+ */
+export declare function signChallenge(challengeBytes: Uint8Array, identitySecretKey: Uint8Array): Uint8Array;
+/**
+ * Verify a challenge signature. Returns boolean; never throws on a
+ * malformed signature so consumers can branch cleanly on `false` and
+ * map to `AUTH_CHALLENGE_NOT_FOUND` / `ENV_INVALID_SIGNATURE`.
+ */
+export declare function verifyChallenge(challengeBytes: Uint8Array, signature: Uint8Array, identityPubkey: Uint8Array): boolean;

package/dist/challenge/index.d.ts

@@ -0,0 +1 @@
+export { signChallenge, verifyChallenge } from './challenge';

package/dist/cosignature/cosign.d.ts

@@ -0,0 +1,35 @@
+import type { CoSignature, CosignPayload, Did } from '../types';
+/**
+ * Build the `attachments.co_signature` block over `payload`.
+ *
+ * The signing input is `sha256(canonical_json(payload))` — same
+ * 32-byte digest the verifier reproduces — and the result is wrapped
+ * in the protocol's `co_signature` shape. `payload.purpose` is the
+ * domain separator; passing a payload whose purpose is not in the
+ * allowed cosignature set throws (defence-in-depth against accidental
+ * cross-purpose reuse).
+ */
+export declare function signCosignature(input: {
+    payload: CosignPayload;
+    signerDid: Did;
+    identitySecretKey: Uint8Array;
+}): CoSignature;
+export type CosignVerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'payload_hash_mismatch' | 'signature_invalid' | 'signature_malformed' | 'purpose_mismatch';
+    detail?: string;
+};
+/**
+ * Verify that `cosignature` was produced by `signerIdentityPubkey`
+ * over `payload`. Three checks:
+ *   1. `cosignature.purpose === payload.purpose` (domain consistency).
+ *   2. recomputed `sha256(canonical_json(payload))` matches `payload_hash`.
+ *   3. Ed25519 verifies signature over the recomputed digest.
+ */
+export declare function verifyCosignature(input: {
+    cosignature: CoSignature;
+    payload: CosignPayload;
+    signerIdentityPubkey: Uint8Array;
+}): CosignVerifyResult;

package/dist/cosignature/index.d.ts

@@ -0,0 +1,2 @@
+export { signCosignature, verifyCosignature } from './cosign';
+export type { CosignVerifyResult } from './cosign';

package/dist/did/document.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DID document shape per [00-core/identity.md](../../../00-core/identity.md).
+ *
+ * Returned by the platform's DID resolver. Verification uses
+ * `identity_pubkey` from the document (not `decoded(did)`) because
+ * `identity_pubkey` may have rotated since registration while the DID
+ * itself stays stable.
+ */
+export interface DidDocument {
+    id: string;
+    verificationMethod: VerificationMethod[];
+    service: ServiceEndpoint[];
+    metadata: {
+        key_mode: KeyMode;
+        owner_attestation_id: string;
+        registered_at: string;
+    };
+}
+export type KeyMode = 'single_key' | 'separated_soft' | 'separated_hard' | 'policy_controlled';
+export interface VerificationMethod {
+    id: string;
+    type: 'Ed25519VerificationKey2020';
+    controller: string;
+    publicKeyMultibase: string;
+}
+export interface ServiceEndpoint {
+    id: string;
+    type: 'ARPEndpoint';
+    serviceEndpoint: string;
+}

package/dist/did/format.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Format an Ed25519 identity public key as a `did:arp:<base58btc>` DID.
+ *
+ * Per [00-core/identity.md](../../../00-core/identity.md), the
+ * method-specific identifier is base58btc(identity_public_key). 32-byte
+ * pubkey → 43-44 character base58btc string → 51-52 character DID.
+ */
+export declare function formatDid(identityPublicKey: Uint8Array): string;
+/**
+ * Decode a `did:arp:<base58btc>` DID back to its identity public key.
+ *
+ * Returns `null` for malformed inputs rather than throwing — DIDs come
+ * over the wire and untrusted callers should not crash the SDK on a
+ * bad string. Server-side validators should reject `null` results
+ * with `ENV_INVALID_DID_FORMAT`.
+ */
+export declare function parseDid(did: string): Uint8Array | null;
+/**
+ * Validate a string as a syntactically well-formed `did:arp:` DID.
+ * Does not check the underlying pubkey is registered or rotated — that
+ * is a server-side concern.
+ */
+export declare function isValidDid(did: string): boolean;

package/dist/did/index.d.ts

@@ -0,0 +1,2 @@
+export { formatDid, parseDid, isValidDid } from './format';
+export type { DidDocument, KeyMode, VerificationMethod, ServiceEndpoint } from './document';

package/dist/envelope/index.d.ts

@@ -0,0 +1,4 @@
+export { signEnvelope } from './sign';
+export type { SignEnvelopeInput, SignableProtected } from './sign';
+export { verifyEnvelope } from './verify';
+export type { VerifyResult, VerifyFailureReason } from './verify';

package/dist/envelope/sign.d.ts

@@ -0,0 +1,28 @@
+import type { Attachments, Body, Envelope, ProtectedBlock } from '../types/envelope';
+/**
+ * Inputs to `signEnvelope` — the caller fills `protected` MINUS the
+ * two hash fields, since those are derived from `body` / `attachments`
+ * and injected by the SDK.
+ */
+export type SignableProtected = Omit<ProtectedBlock, 'body_hash' | 'attachments_hash'>;
+export interface SignEnvelopeInput<TBody extends Body = Body> {
+    protected: SignableProtected;
+    body: TBody;
+    attachments?: Attachments;
+    identitySecretKey: Uint8Array;
+}
+/**
+ * Build a signed envelope.
+ *
+ * Sequence (matches [00-core/protocol.md#signing-rule](../../../00-core/protocol.md)):
+ *   1. Compute `body_hash = sha256(canonical_json(body))`.
+ *   2. Compute `attachments_hash` (or null when absent).
+ *   3. Inject both into `protected` so the wire-protected block is complete.
+ *   4. Compute signing input = `canonical_json({ protected, body, attachments })`.
+ *   5. Sign with Ed25519(identity_priv, signing_input_bytes).
+ *
+ * The protocol forbids the client from setting `body_hash` /
+ * `attachments_hash` to anything other than the recomputed value, so
+ * we deliberately drop them from the typed input.
+ */
+export declare function signEnvelope<TBody extends Body>(input: SignEnvelopeInput<TBody>): Envelope<TBody>;

package/dist/envelope/verify.d.ts

@@ -0,0 +1,37 @@
+import type { Body, Envelope } from '../types/envelope';
+/**
+ * Reasons `verifyEnvelope` may report. Map these to protocol error
+ * codes ([00-core/error-catalog.md](../../../00-core/error-catalog.md))
+ * at the consumer layer:
+ *   - `body_hash_mismatch`     → `ENV_BODY_HASH_MISMATCH`
+ *   - `attachments_hash_mismatch` → `ENV_ATTACHMENTS_HASH_MISMATCH`
+ *   - `signature_invalid`       → `ENV_INVALID_SIGNATURE`
+ *   - `signature_malformed`     → `ENV_INVALID_SIGNATURE` (with details)
+ */
+export type VerifyFailureReason = 'body_hash_mismatch' | 'attachments_hash_mismatch' | 'signature_invalid' | 'signature_malformed';
+export type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: VerifyFailureReason;
+    detail?: string;
+};
+/**
+ * Verify the cryptographic + structural integrity of an envelope.
+ *
+ * Steps 4-6 of the [00-core/protocol.md](../../../00-core/protocol.md)
+ * verification rule:
+ *   - Recompute `body_hash` and compare to `protected.body_hash`.
+ *   - Recompute `attachments_hash` and compare to `protected.attachments_hash`.
+ *   - Recompute canonical signing input and verify Ed25519 signature.
+ *
+ * Replay defence (steps 7), time defence (step 8), purpose / DID
+ * format checks (steps 1-3), and chain assignment (step 11) are
+ * application-layer concerns; this function focuses on the bytes.
+ *
+ * `senderIdentityPubkey` MUST be 32 bytes. Callers resolve it via the
+ * DID document — NOT via `decoded(sender_did)`, because the identity
+ * key may have been rotated since the DID was issued
+ * ([00-core/identity.md](../../../00-core/identity.md)).
+ */
+export declare function verifyEnvelope<TBody extends Body>(envelope: Envelope<TBody>, senderIdentityPubkey: Uint8Array): VerifyResult;

package/dist/escrow/caip19.d.ts

@@ -0,0 +1,41 @@
+/**
+ * CAIP-19 ↔ Solana resolution helpers.
+ *
+ * Pure-SDK pieces:
+ *   - `parseCaip19SolanaAssetId` — pure parse, no cluster cross-check
+ *     (because the SDK has no notion of "deploy cluster" — that's
+ *     server state).
+ *
+ * The server-side cross-check (`mintFromCaip19`) lives in the
+ * arp-server's escrow service because it depends on
+ * `program_state.clusterTag` which is on-chain state.
+ *
+ * `SOLANA_CLUSTER_IDS` is re-exported from `assets.ts` for callers that
+ * already import from `@heyanon-arp/sdk`.
+ */
+/**
+ * Parsed CAIP-19 asset identifier — split into its three structural
+ * fields plus a derived `isNative` flag for the SOL fast-path.
+ */
+export interface ParsedSolanaAssetId {
+    /** CAIP-2 chain reference, e.g. `5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` for mainnet. */
+    cluster: string;
+    /** Asset namespace: `spl` (SPL mint) or `slip44` (chain-native token). */
+    namespace: 'spl' | 'slip44';
+    /** Asset reference: SPL mint pubkey OR slip44 coin index (`501` for SOL). */
+    reference: string;
+    /** Convenience: `true` iff this is native SOL (namespace=slip44, ref=501). */
+    isNative: boolean;
+}
+/**
+ * Parse a CAIP-19 asset id without any cluster cross-check.
+ *
+ * Throws `Error('CAIP-19 asset_id is malformed')` on regex miss.
+ * Throws `Error('Unsupported slip44 coin index')` on non-501 slip44.
+ * Throws `Error('Unsupported CAIP-19 namespace')` on namespace != spl|slip44.
+ *
+ * (The regex already restricts namespace to one of those two, but the
+ * explicit check makes the failure mode surface as a typed error
+ * rather than a regex no-match if the regex is ever loosened.)
+ */
+export declare function parseCaip19SolanaAssetId(assetId: string): ParsedSolanaAssetId;