@heyanon-arp/sdk 0.0.2

package/dist/types/envelope.d.ts

@@ -0,0 +1,121 @@
+import type { PurposeValue } from '../purpose';
+/**
+ * Wire-level types per [00-core/protocol.md](../../../00-core/protocol.md)
+ * and [00-core/schemas.md](../../../00-core/schemas.md).
+ *
+ * Body-type-specific shapes (handshake / contract / delegation / receipt
+ * / etc.) live alongside their handlers in the consumer code — keeping
+ * them out of this file avoids the SDK becoming a kitchen-sink of every
+ * message type. A consumer who needs typed bodies can extend `Envelope<T>`
+ * with their own `T extends Body`.
+ */
+/** Hash string in protocol format `sha256:<64-char hex>`. */
+export type Sha256Hex = `sha256:${string}`;
+/** Ed25519 signature in protocol format `ed25519:<base64>`. */
+export type Ed25519Sig = `ed25519:${string}`;
+/** DID format `did:arp:<base58btc>`. */
+export type Did = `did:arp:${string}`;
+/**
+ * Client-signed `protected` block. All fields here are part of the
+ * signing input. Server-assigned chain fields (`relationship_event_index`,
+ * `prev_server_event_hash`) live OUTSIDE this block — clients MUST NOT
+ * sign them.
+ */
+export interface ProtectedBlock {
+    protocol_version: 'arp/0.1';
+    purpose: PurposeValue;
+    message_id: string;
+    sender_did: Did;
+    recipient_did: Did;
+    /** UUID v4; null only on the first handshake. */
+    relationship_id: string | null;
+    sender_sequence: number;
+    sender_nonce: string;
+    timestamp: string;
+    expires_at: string;
+    body_hash: Sha256Hex;
+    attachments_hash: Sha256Hex | null;
+    delivery_id: string | null;
+}
+/** Body shape — `type` discriminator + per-type `content`. */
+export interface Body<TContent = Record<string, unknown>> {
+    type: string;
+    content: TContent;
+}
+/**
+ * Optional attachments. Three top-level fields are SDK-aware:
+ * `co_signature` (semantic intent), `settlement_signatures`
+ * (financial authorisation), and `escrow_lock` (`delegation.offer`
+ * carries a pre-signed `create_lock` Solana tx). Other body-specific
+ * attachments live under their own keys and are passed through
+ * opaquely.
+ */
+export interface Attachments {
+    co_signature?: CoSignature;
+    settlement_signatures?: SettlementSignatures;
+    escrow_lock?: EscrowLockAttachment;
+    [other: string]: unknown;
+}
+/**
+ * Attached by `delegation.offer` envelopes when the payer (the offer
+ * sender) wants to fund the lock as part of the same envelope.
+ *
+ *   - `signed_tx_blob` is the base64-encoded full Solana tx with the
+ *     payer's settlement key already a tx-level signer.
+ *   - `lock_id` is the deterministic-from-delegation_id hex32, used
+ *     for the server's idempotency-key check (server independently
+ *     derives the same id via `deriveLockId`).
+ *   - `amount` is the base-unit amount (decimal-as-string); must
+ *     equal `toBaseUnits(body.content.amount, currency.decimals)`.
+ *   - `asset_id` is the CAIP-19 currency the lock holds; must equal
+ *     `body.content.currency.asset_id` (defence-in-depth).
+ *   - `expiry` is the on-chain unix-seconds expiry; must satisfy the
+ *     contract's MIN/MAX windows AND the spec's
+ *     `deadline + DISPUTE_BUFFER` constraint.
+ *
+ * Server validation in `EnvelopeValidator` decodes the tx blob via
+ * Anchor IDL and cross-checks every field against the envelope body.
+ */
+export interface EscrowLockAttachment {
+    signed_tx_blob: string;
+    lock_id: string;
+    amount: string;
+    asset_id: string;
+    expiry: number;
+}
+export interface CoSignature {
+    agent_did: Did;
+    purpose: PurposeValue;
+    payload_hash: Sha256Hex;
+    sig: Ed25519Sig;
+}
+export interface SettlementSignatures {
+    purpose: PurposeValue;
+    payer: SettlementParty;
+    payee: SettlementParty;
+    expires_at: number;
+}
+export interface SettlementParty {
+    settlement_pubkey: string;
+    sig: Ed25519Sig;
+}
+/** Top-level envelope as it appears on the wire. */
+export interface Envelope<TBody extends Body = Body> {
+    protected: ProtectedBlock;
+    body: TBody;
+    attachments?: Attachments;
+    sender_signature: Ed25519Sig;
+}
+/**
+ * Server-side projection of an accepted event. Adds chain fields
+ * (server-assigned, NOT in signing input). Returned by the ingestion
+ * endpoint and persisted on the events table.
+ */
+export interface PersistedEvent<TBody extends Body = Body> extends Envelope<TBody> {
+    event_id: string;
+    relationship_event_index: number;
+    prev_server_event_hash: string | null;
+    server_event_hash: string;
+    signed_message_hash: string;
+    server_timestamp: string;
+}

package/dist/types/identity.d.ts

@@ -0,0 +1,62 @@
+import type { KeyMode } from '../did';
+import type { Did } from './envelope';
+/**
+ * Owner attestation methods per [00-core/identity.md](../../../00-core/identity.md).
+ *
+ * V1 ships `scrypt_password_proof` only; the others are reserved
+ * placeholders for forward-compat (V1.5 / V2).
+ */
+export type OwnerSigningMethod = 'scrypt_password_proof' | 'ed25519_owner_key' | 'totp+passphrase';
+/**
+ * `ARP-KEY-LINK-v1` payload — the canonical-JSON-hashed object an owner
+ * signs at registration. Carries the link between identity and settlement
+ * keys plus owner identity / method metadata.
+ */
+export interface KeyLinkPayload {
+    purpose: 'ARP-KEY-LINK-v1';
+    agent_did: Did;
+    identity_public_key: string;
+    settlement_public_key: string;
+    key_mode: KeyMode;
+    owner_id: string;
+    owner_signing_method: OwnerSigningMethod;
+    link_method: 'manual' | 'imported' | 'derived_bip39';
+    created_at: string;
+    nonce: string;
+}
+/**
+ * `ARP-KEY-ROTATION-v1` payload — separate purpose from KEY-LINK
+ * because rotation breaks the `agent_did = base58btc(identity_pubkey)`
+ * invariant. Agent DID stays frozen; identity_public_key changes.
+ */
+export interface KeyRotationPayload {
+    purpose: 'ARP-KEY-ROTATION-v1';
+    agent_did: Did;
+    current_identity_public_key: string;
+    new_identity_public_key: string;
+    settlement_public_key: string;
+    supersedes_attestation_id: string;
+    owner_id: string;
+    owner_signing_method: OwnerSigningMethod;
+    rotation_reason: 'scheduled' | 'compromise' | 'lost_device' | 'other';
+    created_at: string;
+    nonce: string;
+}
+/**
+ * `scrypt_password_proof` — the V1 owner attestation envelope. The
+ * signature is HMAC-SHA256(scrypt(password, salt), sha256(canonical(payload))),
+ * base64-encoded. NOT an Ed25519 signature; verification is
+ * server-side via the stored scrypt-derived key.
+ */
+export interface ScryptPasswordAttestation<TPayload extends KeyLinkPayload | KeyRotationPayload = KeyLinkPayload> {
+    payload: TPayload;
+    sig: string;
+    scrypt_salt_id: string;
+}
+/** Standard scrypt parameters used for owner password proofs (V1). */
+export declare const SCRYPT_PARAMS: {
+    readonly N: 32768;
+    readonly r: 8;
+    readonly p: 1;
+    readonly dkLen: 32;
+};

package/dist/types/index.d.ts

@@ -0,0 +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 { DECLINE_REASONS, isDeclineReason } from './body';
+export type { OwnerSigningMethod, KeyLinkPayload, KeyRotationPayload, ScryptPasswordAttestation } from './identity';
+export { SCRYPT_PARAMS } from './identity';

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { uuidV4 } from './uuid';
+export { senderNonce } from './nonce';
+export { rfc3339, expiresAt } from './timestamp';

package/dist/utils/nonce.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate a 16-byte random nonce, base64url-encoded without padding.
+ *
+ * Used in `protected.sender_nonce` and inside attestation payloads
+ * (`ARP-KEY-LINK-v1`, `ARP-KEY-ROTATION-v1`) to defend against
+ * accidental hash collisions and replay where two semantically
+ * distinct messages would otherwise hash to the same value.
+ */
+export declare function senderNonce(): string;

package/dist/utils/timestamp.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Format a `Date` (or now) as RFC 3339 / ISO 8601 in UTC with second
+ * precision — matches `protected.timestamp` and `protected.expires_at`
+ * format expected by the protocol verifier.
+ *
+ * Intentional choices:
+ *   - second precision (no `.SSS` milliseconds), matching how server
+ *     timestamps render in audit logs / state machines
+ *   - explicit `Z` suffix for UTC, no offset notation
+ */
+export declare function rfc3339(at?: Date): string;
+/**
+ * `expires_at` derived as `now + ttlSeconds`. The protocol caps
+ * envelope validity at 24 hours; callers who pass a longer TTL get
+ * a hard error rather than a silently-truncated value.
+ */
+export declare function expiresAt(ttlSeconds: number, now?: Date): string;

package/dist/utils/uuid.d.ts

@@ -0,0 +1,10 @@
+/**
+ * RFC 4122 UUID v4 generator.
+ *
+ * The protocol uses UUIDv4 for `message_id`, `relationship_id`,
+ * `challenge_id`, etc. Implemented locally rather than via
+ * `crypto.randomUUID()` so the SDK stays portable across environments
+ * that don't expose the global `crypto` (older runtimes, WebWorkers
+ * without crypto polyfills).
+ */
+export declare function uuidV4(): string;

package/dist/webhook/index.d.ts

@@ -0,0 +1,2 @@
+export { buildWebhookSignatureHeader, verifyWebhookSignatureHeader } from './webhook';
+export type { WebhookSignableInput } from './webhook';

package/dist/webhook/webhook.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `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.
+ */
+export interface WebhookSignableInput {
+    delivery_id: string;
+    recipient_did: string;
+    envelope_message_id: string;
+    server_event_hash: string;
+    attempt_n: number;
+    served_at: string;
+}
+/**
+ * Compute `X-ARP-Signature` value: `<purpose>=<base64(HMAC-SHA256(secret, sha256(canonical_json(input))))>`.
+ *
+ * Recipients lookup their per-sender shared secret, recompute the
+ * HMAC over the same canonical input, and compare against the
+ * received header.
+ */
+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.
+ */
+export declare function verifyWebhookSignatureHeader(headerValue: string, input: WebhookSignableInput, sharedSecret: Uint8Array): boolean;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@heyanon-arp/sdk",
+  "version": "0.0.2",
+  "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": [
+    "arp",
+    "agent-relationship-protocol",
+    "did",
+    "ed25519",
+    "jcs",
+    "canonical-json",
+    "envelope",
+    "cosignature",
+    "a2a"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.5.0",
+    "@scure/base": "^1.1.9",
+    "canonicalize": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "tslib": "^2.6.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "start": "tsup --watch",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "lint": "biome check . --write"
+  }
+}