@7h3/protocol 0.4.0 → 0.5.1

package/README.md

@@ -1,333 +1,16 @@
-<div align="center">
-  <img src="./docs/assets/banner.png" alt="@7h3/protocol — AIP: Sign every message. Reject every replay." width="100%">
+# @7h3/protocol
 
-  <br/><br/>
+7h3 Protocol (wire version `7h3/0.1`):
+deterministic, signed, replay-safe AI-to-AI message envelopes.
 
-  [![npm](https://img.shields.io/npm/v/@7h3/protocol?style=flat-square&color=818cf8&logo=npm&logoColor=white&label=%407h3%2Fprotocol)](https://www.npmjs.com/package/@7h3/protocol)
-  [![npm mcp](https://img.shields.io/npm/v/@7h3/protocol-mcp?style=flat-square&color=6366f1&logo=npm&logoColor=white&label=%407h3%2Fprotocol-mcp)](https://www.npmjs.com/package/@7h3/protocol-mcp)
-  [![PyPI](https://img.shields.io/pypi/v/aip7h3?style=flat-square&color=818cf8&logo=python&logoColor=white)](https://pypi.org/project/aip7h3/)
-  [![Crates.io](https://img.shields.io/crates/v/aip7h3?style=flat-square&color=a5b4fc&logo=rust&logoColor=white)](https://crates.io/crates/aip7h3)
-  [![Tests](https://img.shields.io/badge/tests-131%20passing-4ade80?style=flat-square&logo=vitest&logoColor=white)](https://github.com/IceMasterT/7h3-protocol-aip/tree/main/src)
-  [![Zero deps](https://img.shields.io/badge/runtime%20deps-0-a5b4fc?style=flat-square)](./package.json)
-  [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](./tsconfig.json)
-  [![License](https://img.shields.io/badge/license-MIT-94a3b8?style=flat-square)](./LICENSE)
-  [![Wire](https://img.shields.io/badge/wire-aip%2F0.1-818cf8?style=flat-square)](./docs/VERSIONING_POLICY.md)
-
-  <br/>
-
-  **The signing-and-replay layer your agent protocol forgot.**
-
-  <br/>
-</div>
-
----
-
-## Why it exists
-
-The dominant agent protocols ship messages unsigned:
-
-- **MCP** uses plain JSON-RPC 2.0 — no signatures, no replay protection. Parameters can be altered in transit; valid messages can be replayed indefinitely.
-- **A2A** signs *Agent Cards* for domain identity — but not the per-message task traffic.
-
-AIP fills exactly that gap. It is a hardening envelope you put *around* MCP or A2A traffic — not a competitor to them. Every message gets signed, TTL-bounded, and replay-checked before it reaches your handler.
-
-Use it when agents trigger real side effects (writes, payments, tool calls) and you need tamper-evidence, replay-safety, and auditability.
-
----
-
-## Guarantees
-
-| Property | Mechanism |
-|---|---|
-| **Authentic** | HMAC-SHA256 (HS256) or Ed25519 over a canonical payload — real WebCrypto, no hand-rolled crypto |
-| **Deterministic** | Fixed-key-order canonicalization; signatures match byte-for-byte across TS / Python / Rust |
-| **Replay-resistant** | `(sender, messageId, nonce)` uniqueness window + TTL / clock-skew enforcement |
-| **Polyglot** | Shared conformance fixture set (`conformance/aip_v0_1.json`) proves parity across all three runtimes |
-
----
-
-## Install
+Install:
 
 ```bash
 npm install @7h3/protocol
 ```
 
-Python and Rust SDKs live under `sdk/python` (`from aip7h3 import …`) and `sdk/rust` (`use aip7h3::…`).
-
-### MCP server (for Claude Code / Claude Desktop)
-
-The companion `@7h3/protocol-mcp` package installs five tools into your AI assistant for generating secrets, keypairs, and boilerplate.
-
-```bash
-# Claude Code
-claude mcp add aip -- npx @7h3/protocol-mcp
-```
-
-```json
-// Claude Desktop — claude_desktop_config.json
-{
-  "mcpServers": {
-    "aip": { "command": "npx", "args": ["@7h3/protocol-mcp"] }
-  }
-}
-```
-
-| Tool | What it does |
-|---|---|
-| `aip_generate_secret` | 32-byte HMAC secret → `AIP_SECRET` |
-| `aip_generate_keypair` | Ed25519 keypair → env vars |
-| `aip_wrap_mcp_server` | Ready-to-paste boilerplate for your MCP server |
-| `aip_sign` | Sign a test envelope (debugging / fixture generation) |
-| `aip_verify` | Verify an envelope's signature and shape |
-
----
-
-## Quick start
-
-### HMAC (shared secret — simplest path)
+Import:
 
 ```ts
-import {
-  createEnvelope, signEnvelopeHmac, verifyEnvelopeHmac, validateEnvelope,
-} from '@7h3/protocol'
-
-const secret = 'shared-secret'
-const envelope = await signEnvelopeHmac(
-  createEnvelope({ sender: 'planner', recipient: 'worker', intent: 'TASK', content: 'do-the-thing' }),
-  secret,
-)
-
-const diagnostics = validateEnvelope(envelope)        // shape / TTL / version checks
-const ok = await verifyEnvelopeHmac(envelope, secret) // tamper + auth check
-// → replay-check downstream via your transport's replay cache
+import { createAipAgentAdapter, receiveEnvelope } from '@7h3/protocol'
 ```
-
-### Ed25519 (asymmetric — production recommendation)
-
-> **Why Ed25519?** HMAC is a shared secret — any peer that can verify can also forge. Ed25519 is asymmetric: you sign with a private key, peers verify with your public key only. Compromising a peer does not compromise your signing key.
-
-```ts
-import {
-  generateEd25519KeypairBase64Url, createEnvelope,
-  signEnvelopeEd25519, verifyEnvelopeEd25519,
-} from '@7h3/protocol'
-
-const { privateKey, publicKey } = await generateEd25519KeypairBase64Url()
-const envelope = await signEnvelopeEd25519(
-  createEnvelope({ sender: 'planner', recipient: 'worker', intent: 'TASK', content: 'do-the-thing' }),
-  privateKey, 'k1',
-)
-const ok = await verifyEnvelopeEd25519(envelope, publicKey)
-```
-
----
-
-## MCP hardening wrapper
-
-Wrap any existing MCP server or client — handler signature does not change:
-
-```ts
-import { wrapMcpServer, wrapMcpClient, signEnvelopeEd25519 } from '@7h3/protocol'
-
-// Server side
-const secureServer = wrapMcpServer(myMcpHandler, {
-  selfAgentId: 'my-server',
-  sign: (e) => signEnvelopeEd25519(e, serverPrivateKey, 'k1'),
-})
-
-// Client side
-const { send } = wrapMcpClient({
-  selfAgentId: 'my-client',
-  peerAgentId: 'my-server',
-  sign: (e) => signEnvelopeEd25519(e, clientPrivateKey, 'k1'),
-  receive: { signatureResolver: async ({ keyId }) => ({ alg: 'ED25519', publicKey: serverPublicKey }) },
-})
-const response = await send({ jsonrpc: '2.0', id: 1, method: 'tools/list' }, fetch)
-```
-
-The wrapper enforces four bindings beyond signature verification:
-
-| Binding | Attack defeated |
-|---|---|
-| **Recipient** | Server rejects envelopes not addressed to `selfAgentId` — cross-server relay |
-| **Sender** | Client accepts responses only from `peerAgentId` — response spoofing |
-| **Correlation** | Client enforces `correlationId === request messageId` — response substitution |
-| **Replay** | `InMemoryReplayCache` injected by default — replay of prior requests |
-
-Demo: `npm run aip:mcp:wrap`
-
----
-
-## Wire formats
-
-Three formats — choose by context:
-
-| Format | Use case |
-|---|---|
-| `json` | Human-readable, debug-friendly |
-| `compact` | Minified JSON — smaller over HTTP |
-| `binary` | MessagePack (magic `AIPB`) — highest throughput, lowest parse overhead |
-
-```ts
-import { encodeEnvelope, decodeEnvelope } from '@7h3/protocol'
-
-const wire = encodeEnvelope(envelope, 'binary')   // Uint8Array
-const back = decodeEnvelope(wire)                  // ProtocolEnvelope
-```
-
----
-
-## Distributed replay store (Redis)
-
-Production deployments need a shared replay store across agent instances:
-
-```ts
-import { createRedisReplayStore, DistributedReplayCache } from '@7h3/protocol'
-
-const store = createRedisReplayStore(redisClient, {
-  errorBehavior: 'fallback', // degrade to local store on Redis outage — never silent
-  onDegraded: (err) => telemetry.error('replay-store-degraded', err),
-})
-const replayCache = new DistributedReplayCache(store)
-
-// Pass replayCache into receiveEnvelope or wrapMcpServer/wrapMcpClient
-```
-
-- Atomic `SET NX PX` reserve — no double-processing under concurrent writes
-- `reserveMany` batch pipeline — low overhead for high-volume handlers
-- `errorBehavior: 'fallback' | 'reject' | 'allow'` — operator controls degradation posture
-- See `docs/DISTRIBUTED_REPLAY.md`
-
----
-
-## Fleet-wide key revocation
-
-```ts
-import { createRedisRevocationStore, withRevocationCheck } from '@7h3/protocol'
-
-const revocationStore = createRedisRevocationStore(redisClient) // fail-closed default
-const secureResolver = withRevocationCheck(mySignatureResolver, revocationStore)
-// Revoked key → resolver returns undefined → verification fails
-```
-
-- Cached reads (5 s TTL by default) — low overhead on the verify hot path
-- Fail-closed default: Redis outage → reject, not allow
-- See `docs/KEY_REVOCATION.md`
-
----
-
-## Transport adapters
-
-Zero new runtime dependencies — only Node built-ins and global `fetch`:
-
-```ts
-import { serveMcpOverStdio, createStdioMcpClient } from '@7h3/protocol'
-import { createHttpMcpHandler, createHttpMcpClient } from '@7h3/protocol'
-```
-
-| Adapter | Notes |
-|---|---|
-| `serveMcpOverStdio` + `createStdioMcpClient` | Newline-delimited; in-order sequential chain prevents response interleaving |
-| `createHttpMcpHandler` + `createHttpMcpClient` | `node:http` handler + `fetch` client; supports `binary` wire format |
-
----
-
-## Framework adapters
-
-LangChain, LlamaIndex, and JSON-RPC bridge adapters wrap `AipAgentAdapter` to translate between AIP envelopes and framework-native message types:
-
-```ts
-import { LangChainAipAdapter, LlamaIndexAipAdapter, JsonRpcBridge } from '@7h3/protocol'
-```
-
----
-
-## Policy and telemetry
-
-Runtime policy controls transport behavior, retry, rate limits, and safety invariants — loaded from `AI_RUNTIME_POLICY.yaml` or inline:
-
-```ts
-import { loadRuntimePolicy, validateRuntimePolicy, PolicyEnforcer } from '@7h3/protocol'
-
-const policy = await loadRuntimePolicy({ path: './AI_RUNTIME_POLICY.yaml' })
-const enforcer = new PolicyEnforcer(policy)
-```
-
-See `docs/TELEMETRY.md`, `docs/AI_DECISION_CARD.md`, `docs/OPERATORS.md`.
-
----
-
-## Polyglot parity
-
-All three SDKs are driven by the same conformance fixture set at `conformance/aip_v0_1.json`. Signatures verified against known vectors in all three runtimes:
-
-```bash
-npm test                          # TypeScript (131 tests / 23 files)
-npm run conformance:python        # Python unittest
-npm run conformance:rust          # Rust cargo test (7 tests)
-```
-
----
-
-## Status
-
-**Version: 0.1.2** · Wire protocol: `aip/0.1`
-
-| What | Status |
-|---|---|
-| Core test suite | ✅ 131 tests / 23 files — all green |
-| Cryptography | ✅ Real WebCrypto — HMAC-SHA256 + Ed25519 (no hand-rolled crypto) |
-| Deterministic canonicalization | ✅ Fixed key order; byte-identical across runtimes |
-| TS/Python/Rust parity | ✅ Shared conformance fixtures; all pass |
-| Distributed replay (Redis) | ✅ Atomic `SET NX PX`; batch pipeline; graceful degradation |
-| Fleet-wide revocation (Redis) | ✅ Fail-closed; cached reads; stale-serve during outage |
-| MCP hardening wrapper | ✅ 4 bindings; all independently tested |
-| Property-based fuzz tests | ✅ 8 properties via fast-check (wire decoder, canonicalization, replay) |
-| Live-Redis integration test | ✅ Auto-skips if no server present — no false passes |
-| Formal fuzz campaign | ✅ TypeScript mutation harnesses run clean (50k/20k rounds, 0 crashes); Rust targets built and run (4.9M iterations, no panics in `canonicalize_envelope`/`decode_envelope`) — see [`docs/FUZZ_CAMPAIGN.md`](./docs/FUZZ_CAMPAIGN.md) |
-| Independent security audit | ⚠️ Not yet performed by an external reviewer — internal AI-assisted review completed 2026-06-05, 2 bugs found and fixed (see [`docs/SECURITY_REVIEW_2026-06-05.md`](./docs/SECURITY_REVIEW_2026-06-05.md)); cryptographic primitives are standard WebCrypto; parsing/replay/canonicalization logic remains unaudited by a qualified third party |
-| Python Ed25519 | ✅ Pure-Python fallback — no external packages required; tries `cryptography` → `PyNaCl` → pure Python in order |
-| Rust crates.io publish | ✅ Metadata complete; `cargo publish --dry-run` passes — publish with `cargo publish` when ready |
-| Redis HA | ✅ Sentinel, Cluster, and Upstash adapter patterns documented in [`docs/DISTRIBUTED_REPLAY.md`](./docs/DISTRIBUTED_REPLAY.md) |
-
----
-
-## Docs
-
-| Document | Contents |
-|---|---|
-| [`docs/THREAT_MODEL.md`](./docs/THREAT_MODEL.md) | Full threat coverage matrix |
-| [`docs/MCP_WRAPPER.md`](./docs/MCP_WRAPPER.md) | MCP wrapper usage, transport examples, HMAC vs Ed25519 comparison |
-| [`docs/DISTRIBUTED_REPLAY.md`](./docs/DISTRIBUTED_REPLAY.md) | Redis store setup, `errorBehavior` table, ops guidance |
-| [`docs/KEY_REVOCATION.md`](./docs/KEY_REVOCATION.md) | Revocation store setup, cache TTL tuning |
-| [`docs/KEY_MANAGEMENT_POLICY.md`](./docs/KEY_MANAGEMENT_POLICY.md) | Key lifecycle and rotation policy |
-| [`docs/CLOCK_SKEW_POLICY.md`](./docs/CLOCK_SKEW_POLICY.md) | Clock sync requirements |
-| [`docs/VERSIONING_POLICY.md`](./docs/VERSIONING_POLICY.md) | Wire freeze guarantees, semver policy |
-| [`docs/MIGRATION_GUIDE.md`](./docs/MIGRATION_GUIDE.md) | Breaking-change upgrade paths |
-| [`docs/OPERATORS.md`](./docs/OPERATORS.md) | Deployment and operations reference |
-| [`docs/TELEMETRY.md`](./docs/TELEMETRY.md) | Telemetry hooks and observability |
-| [`docs/SECURITY_REVIEW_2026-06-05.md`](./docs/SECURITY_REVIEW_2026-06-05.md) | AI-assisted internal security review — findings, fixes, positive findings |
-| [`docs/PROJECT_EXAMINATION_2026-05-31.md`](./docs/PROJECT_EXAMINATION_2026-05-31.md) | Independent examination — verified vs asserted |
-| [`CHANGELOG.md`](./CHANGELOG.md) | Full version history |
-
----
-
-## Security
-
-Report vulnerabilities via the coordinated disclosure process in [`SECURITY.md`](./SECURITY.md). **Do not open a public issue for security findings.** 48-hour acknowledgement SLA; 14-day critical patch SLA.
-
-The cryptographic primitives are standard (WebCrypto Ed25519 / HMAC-SHA256). The envelope parsing, canonicalization, and replay-cache logic have not been formally audited. No independent security audit has been performed. Treat accordingly in high-stakes deployments.
-
----
-
-## Contributing
-
-See [`CONTRIBUTING.md`](./CONTRIBUTING.md) — test commands, wire-freeze policy, conformance fixture update requirement, and PR workflow.
-
-## Governance
-
-See [`GOVERNANCE.md`](./GOVERNANCE.md) — single-maintainer stage, decision process, co-maintainership path (LF Minimum Viable Governance style).
-
-## License
-
-MIT

package/agentAdapter.d.ts

@@ -0,0 +1,26 @@
+import { type AgentReceiveResult, type AgentSessionConfig } from './protocolAgent';
+import { type IntentKind, type ProtocolEnvelope } from './protocol';
+import { type WireEnvelope, type WireFormat } from './protocolTransport';
+export interface AipAdapterConfig extends AgentSessionConfig {
+    wireFormat?: WireFormat;
+}
+export declare class AipAgentAdapter {
+    private readonly session;
+    private readonly wireFormat;
+    constructor(config: AipAdapterConfig);
+    toRaw(envelope: ProtocolEnvelope): WireEnvelope;
+    createRawIntent(input: {
+        recipient?: string;
+        intent: IntentKind;
+        content: string;
+        capability?: string;
+        correlationId?: string;
+        ttlMs?: number;
+        messageId?: string;
+        nonce?: string;
+        nowMs?: number;
+    }): Promise<WireEnvelope>;
+    receiveRaw(raw: WireEnvelope, nowMs?: number): Promise<AgentReceiveResult>;
+    handleRaw(raw: WireEnvelope, emitResponseRaw: (rawResponse: WireEnvelope, responseEnvelope: ProtocolEnvelope) => void | Promise<void>, nowMs?: number): Promise<AgentReceiveResult>;
+}
+export declare function createAipAgentAdapter(config: AipAdapterConfig): AipAgentAdapter;

package/auditLog.d.ts

@@ -0,0 +1,54 @@
+export type AuditEventType = 'verify-ok' | 'verify-fail' | 'rate-limited' | 'sender-denied' | 'response-signed';
+export interface AuditEntry {
+    id: string;
+    timestampMs: number;
+    type: AuditEventType;
+    sender?: string;
+    path?: string;
+    method?: string;
+    envelopeId?: string;
+    failReason?: string;
+    upstream?: string;
+    responseStatus?: number;
+    entrySignature: string;
+}
+export interface AuditLogger {
+    log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>;
+    query(opts?: {
+        type?: AuditEventType;
+        sender?: string;
+        since?: number;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    verify(entry: AuditEntry, publicKey: string): Promise<boolean>;
+}
+declare class InMemoryAuditLog implements AuditLogger {
+    private entries;
+    private privateKey;
+    private maxEntries;
+    constructor(privateKey: string, maxEntries?: number);
+    log(event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>;
+    query(opts?: {
+        type?: AuditEventType;
+        sender?: string;
+        since?: number;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    verify(entry: AuditEntry, publicKey: string): Promise<boolean>;
+    size(): number;
+}
+declare class NoopAuditLog implements AuditLogger {
+    log(_event: Omit<AuditEntry, 'id' | 'timestampMs' | 'entrySignature'>): Promise<void>;
+    query(_opts?: {
+        type?: AuditEventType;
+        sender?: string;
+        since?: number;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+    verify(_entry: AuditEntry, _publicKey: string): Promise<boolean>;
+    size(): number;
+}
+export declare function createAuditLog(privateKey: string, opts?: {
+    maxEntries?: number;
+}): InMemoryAuditLog;
+export { InMemoryAuditLog, NoopAuditLog };

package/capability.d.ts

@@ -0,0 +1,67 @@
+import { generateEd25519KeypairBase64Url } from './protocol';
+export { generateEd25519KeypairBase64Url };
+export interface CapabilityScope {
+    pathGlob: string;
+    methods?: string[];
+    maxDelegations?: number;
+}
+export interface CapabilityToken {
+    id: string;
+    version: '7h3-cap/1';
+    issuer: string;
+    subject: string;
+    scopes: CapabilityScope[];
+    issuedAt: number;
+    expiresAt: number;
+    delegationDepth: number;
+    parentTokenId?: string;
+    /** How many more times this token can be re-delegated. undefined = unlimited, 0 = no further delegation. */
+    maxDelegations: number | undefined;
+    signature: string;
+    keyId: string;
+}
+export type CapabilityVerifyResult = {
+    ok: true;
+    token: CapabilityToken;
+    chain: CapabilityToken[];
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const CAP_HEADER = "x-7h3-capability";
+/**
+ * Deterministic canonical form for signing: alphabetically sorted top-level fields,
+ * each scope also sorted. The `signature` field is excluded.
+ */
+export declare function canonicalizeCapabilityToken(token: Omit<CapabilityToken, 'signature'>): string;
+export declare function issueCapabilityToken(opts: {
+    issuerPrivateKey: string;
+    issuerId: string;
+    subject: string;
+    scopes: CapabilityScope[];
+    ttlMs: number;
+    maxDelegations?: number;
+    keyId?: string;
+}): Promise<CapabilityToken>;
+export declare function delegateCapabilityToken(opts: {
+    parentToken: CapabilityToken;
+    delegatorPrivateKey: string;
+    delegatorId: string;
+    newSubject: string;
+    scopes?: CapabilityScope[];
+    ttlMs: number;
+    keyId?: string;
+}): Promise<CapabilityToken>;
+export declare function verifyCapabilityToken(token: CapabilityToken, publicKey: string, opts?: {
+    now?: number;
+}): Promise<boolean>;
+export declare function verifyCapabilityChain(chain: CapabilityToken[], keyRegistry: {
+    getPublicKey(id: string): Promise<string | null>;
+}, opts?: {
+    requiredPathGlob?: string;
+    requiredMethod?: string;
+    now?: number;
+}): Promise<CapabilityVerifyResult>;
+export declare function tokenMatchesScope(token: CapabilityToken, pathGlob: string, method?: string): boolean;
+export declare function serializeCapabilityChain(chain: CapabilityToken[]): string;
+export declare function parseCapabilityChain(serialized: string): CapabilityToken[];

package/cborCodec.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal deterministic CBOR encoder/decoder — zero external dependencies.
+ * Follows RFC 8949 §4.2 deterministic encoding:
+ *   - Shortest-length integers
+ *   - Map keys sorted by lexicographic byte order of encoded key
+ */
+export declare class CborEncoder {
+    private chunks;
+    encode(value: unknown): Uint8Array;
+    private _encode;
+    private _encodeNumber;
+    private _float64Header;
+    private _encodeString;
+    private _encodeByteString;
+    private _encodeArray;
+    private _encodeMapFromAnyEntries;
+    private _encodeMapFromEntries;
+    private _compareBytes;
+    private _concatPair;
+    private _encodeHead;
+    private _encodeHeadBytes;
+    private _concat;
+}
+export declare class CborDecoder {
+    private data;
+    private offset;
+    decode(data: Uint8Array): unknown;
+    private _decode;
+    private _decodeUint;
+    private _readByte;
+    private _readBytes;
+}
+export declare function encodeCbor(value: unknown): Uint8Array;
+export declare function decodeCbor(data: Uint8Array): unknown;

package/conformanceVectors.d.ts

@@ -0,0 +1,20 @@
+import type { ProtocolEnvelope } from './protocol';
+export interface ConformanceVector {
+    id: string;
+    secret: string;
+    keyId: string;
+    envelope: Omit<ProtocolEnvelope, 'signature'>;
+    canonical: string;
+    signature: string;
+}
+export interface Ed25519ConformanceVector {
+    id: string;
+    keyId: string;
+    publicKey: string;
+    privateKey: string;
+    envelope: Omit<ProtocolEnvelope, 'signature'>;
+    canonical: string;
+    signature: string;
+}
+export declare const AIP_V01_CONFORMANCE_VECTORS: ConformanceVector[];
+export declare const AIP_V01_ED25519_CONFORMANCE_VECTORS: Ed25519ConformanceVector[];

package/encryption.d.ts

@@ -0,0 +1,85 @@
+/**
+ * E2E Encryption for 7h3 Protocol
+ *
+ * Uses X25519 Diffie-Hellman key exchange + ChaCha20-Poly1305 AEAD.
+ * All operations via Node.js built-in `node:crypto` — zero new dependencies.
+ *
+ * Architecture:
+ *   EncryptedEnvelope = SignedEnvelope where body.content is a base64url-encoded
+ *   EncryptedPayload, body.intent = 'ENCRYPTED', body.capability = 'x25519-chacha20poly1305'
+ */
+import { type ProtocolBody, type ProtocolEnvelope } from './protocol.js';
+export interface X25519KeyPair {
+    /** Raw 32-byte X25519 public key, base64url-encoded (no padding) */
+    publicKey: string;
+    /** Raw 32-byte X25519 private key, base64url-encoded (no padding) */
+    privateKey: string;
+}
+export interface EncryptedPayload {
+    /** Ephemeral X25519 public key (base64url, raw 32 bytes) */
+    ephemeralPublic: string;
+    /** ChaCha20 nonce / HKDF salt (base64url, 12 bytes) */
+    nonce: string;
+    /** Ciphertext without auth tag (base64url) */
+    ciphertext: string;
+    /** 16-byte Poly1305 auth tag (base64url) */
+    tag: string;
+}
+/**
+ * Generate a fresh X25519 keypair.
+ * Both keys are raw 32-byte values encoded as base64url (no padding).
+ */
+export declare function generateX25519KeyPair(): X25519KeyPair;
+/**
+ * Perform X25519 DH + HKDF-SHA256 to derive a 32-byte ChaCha20-Poly1305 key.
+ *
+ * @param privateKeyBase64Url  - raw 32-byte X25519 private key (base64url)
+ * @param peerPublicKeyBase64Url - raw 32-byte X25519 public key (base64url)
+ * @param nonce - raw 12-byte nonce (base64url); used as HKDF salt
+ * @returns 32-byte Buffer ready for use with createCipheriv/createDecipheriv
+ */
+export declare function deriveEncryptionKey(privateKeyBase64Url: string, peerPublicKeyBase64Url: string, nonce: string): Buffer;
+/**
+ * Encrypt a ProtocolBody with the recipient's X25519 public key.
+ *
+ * @returns encryptedContent (base64url-encoded EncryptedPayload JSON) and ephemeralPublic
+ */
+export declare function encryptBody(body: ProtocolBody, recipientX25519PublicKey: string): {
+    encryptedContent: string;
+    ephemeralPublic: string;
+};
+/**
+ * Decrypt an encrypted ProtocolBody.
+ *
+ * @param encryptedContent - base64url-encoded EncryptedPayload
+ * @param recipientX25519PrivateKey - raw 32-byte X25519 private key (base64url)
+ * @returns decrypted ProtocolBody
+ * @throws if AEAD tag verification fails
+ */
+export declare function decryptBody(encryptedContent: string, recipientX25519PrivateKey: string): ProtocolBody;
+/**
+ * Encrypt and sign an envelope (full pipeline).
+ *
+ * The original body is encrypted; the envelope body is replaced with:
+ *   { intent: 'ENCRYPTED', content: <encrypted-payload>, capability: 'x25519-chacha20poly1305' }
+ * The modified envelope is then signed with Ed25519.
+ */
+export declare function sealEnvelope(envelope: Omit<ProtocolEnvelope, 'signature'>, opts: {
+    recipientX25519PublicKey: string;
+    senderEd25519PrivateKey: string;
+}): Promise<ProtocolEnvelope>;
+/**
+ * Verify signature and decrypt an envelope (full pipeline).
+ *
+ * Signature is verified FIRST; decryption only proceeds if valid.
+ *
+ * @returns The signed envelope (with encrypted body) and the decrypted original body
+ * @throws if Ed25519 signature invalid or AEAD tag fails
+ */
+export declare function openEnvelope(envelope: ProtocolEnvelope, opts: {
+    recipientX25519PrivateKey: string;
+    senderEd25519PublicKey: string;
+}): Promise<{
+    envelope: ProtocolEnvelope;
+    body: ProtocolBody;
+}>;

package/envelopeCbor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Higher-level CBOR codec for ProtocolEnvelope.
+ * Uses numeric field keys for maximum compactness.
+ *
+ * Envelope map structure:
+ *   1 → header map
+ *   2 → body map
+ *   3 → signature map (omitted if no signature)
+ *
+ * Header map:
+ *   1 → version (string)
+ *   2 → messageId (string)
+ *   3 → timestampMs (int)
+ *   4 → ttlMs (int)
+ *   5 → sender (string)
+ *   6 → recipient (string, omit if absent)
+ *   7 → nonce (string)
+ *
+ * Body map:
+ *   1 → intent (string)
+ *   2 → content (string)
+ *   3 → capability (string, omit if absent)
+ *   4 → correlationId (string, omit if absent)
+ *
+ * Signature map:
+ *   1 → alg (string)
+ *   2 → keyId (string)
+ *   3 → value (string — base64url signature)
+ */
+import type { ProtocolEnvelope } from './protocol';
+export declare const CBOR_CONTENT_TYPE = "application/7h3-cbor";
+export declare function encodeEnvelopeCbor(env: ProtocolEnvelope): Uint8Array;
+export declare function decodeEnvelopeCbor(data: Uint8Array): ProtocolEnvelope;