@aroha-sdk/core 1.0.0 → 1.2.0

package/dist/identity/web-did.js

@@ -0,0 +1,338 @@
+/**
+ * Aroha Web-Native Identity — did:aroha-web:
+ *
+ * A DNS-anchored DID method that requires NO central Aroha registry.
+ * Identity is verified by TWO independent channels simultaneously:
+ *
+ *   1. HTTPS — DID Document served at:
+ *      https://{domain}/.well-known/aroha/agents/{path}/did.json
+ *
+ *   2. DNS TXT — Key-commitment record at:
+ *      _aroha.{domain} IN TXT "v=aroha1; path={path}; keyhash={sha256 of pubkey}"
+ *
+ * Both channels must agree. Domain hijacking via HTTPS alone is insufficient —
+ * the attacker would also need to control DNS to forge the key-commitment.
+ * This is a meaningful security upgrade over single-channel HTTPS identity
+ * (did:wba, did:web).
+ *
+ * Key rotation:
+ *   Rotations are cryptographically chained — the new key is signed by the old
+ *   key and a 24-hour cool-down window is enforced before the new key is trusted.
+ *   The rotation record is embedded in the DID Document under `keyHistory`.
+ *
+ * DID format:
+ *   did:aroha-web:{domain}[:{path}]
+ *   e.g. did:aroha-web:stripe.com:payments-agent
+ *        did:aroha-web:internal.example.corp:invoicing
+ *
+ * Resolution produces the same DIDDocument format as did:aroha: — full
+ * interoperability with the rest of the Aroha stack.
+ */
+import * as ed from "@noble/ed25519";
+import { sha256 } from "@noble/hashes/sha256";
+import { sha512 } from "@noble/hashes/sha512";
+import { bytesToHex } from "@noble/hashes/utils";
+import { toMultibase, fromMultibase, } from "./did.js";
+ed.etc.sha512Sync = (...m) => sha512(...m);
+// ─── DID parsing ──────────────────────────────────────────────────────────────
+/** Parse `did:aroha-web:domain[:path]` into its components. */
+export function parseWebDID(did) {
+    const prefix = "did:aroha-web:";
+    if (!did.startsWith(prefix)) {
+        throw new Error(`Not a did:aroha-web: identifier: ${did}`);
+    }
+    const rest = did.slice(prefix.length);
+    const colonIdx = rest.indexOf(":");
+    if (colonIdx === -1) {
+        return { domain: rest, path: "agent" };
+    }
+    return {
+        domain: rest.slice(0, colonIdx),
+        path: rest.slice(colonIdx + 1).replace(/:/g, "/"),
+    };
+}
+export function buildWebDID(domain, path) {
+    const normalised = path.replace(/\//g, ":");
+    return `did:aroha-web:${domain}:${normalised}`;
+}
+export function isWebDID(did) {
+    return did.startsWith("did:aroha-web:");
+}
+// ─── Well-known path ──────────────────────────────────────────────────────────
+/**
+ * The HTTP path at which the DID Document should be served.
+ * e.g. `did:aroha-web:stripe.com:payments` → `/.well-known/aroha/agents/payments/did.json`
+ */
+export function wellKnownPath(did) {
+    const { path } = parseWebDID(did);
+    return `/.well-known/aroha/agents/${path}/did.json`;
+}
+/**
+ * The full HTTPS URL for a given did:aroha-web: identifier.
+ */
+export function wellKnownUrl(did) {
+    const { domain, path } = parseWebDID(did);
+    return `https://${domain}/.well-known/aroha/agents/${path}/did.json`;
+}
+// ─── DNS TXT record ───────────────────────────────────────────────────────────
+/**
+ * Returns the DNS TXT record VALUE (not the full DNS record) for the
+ * key-commitment. Publish at: `_aroha.{domain} IN TXT "{this value}"`
+ *
+ * Format: `v=aroha1; path={path}; keyhash={sha256hex}`
+ */
+export function dnsTXTValue(did, publicKey) {
+    const { path } = parseWebDID(did);
+    const keyhash = bytesToHex(sha256(publicKey));
+    return `v=aroha1; path=${path}; keyhash=${keyhash}`;
+}
+/** Parse a DNS TXT value back to its fields. Returns null if invalid. */
+export function parseDNSTXT(txt) {
+    if (!txt.includes("v=aroha1"))
+        return null;
+    const fields = {};
+    for (const part of txt.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        fields[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+    }
+    if (!fields.path || !fields.keyhash)
+        return null;
+    return { path: fields.path, keyhash: fields.keyhash };
+}
+// ─── Key commitment hash ──────────────────────────────────────────────────────
+export function keyCommitmentHash(publicKey) {
+    return bytesToHex(sha256(publicKey));
+}
+// ─── Generate ─────────────────────────────────────────────────────────────────
+/**
+ * Generate a new did:aroha-web: identity.
+ *
+ * Returns the key pair, the DID Document to serve at the well-known path,
+ * the DNS TXT value to publish, and the well-known URL.
+ *
+ * @param domain    The company domain (e.g. "stripe.com")
+ * @param path      Agent identifier within the domain (e.g. "payments-agent")
+ * @param endpoint  The Aroha HTTP endpoint URL (e.g. "https://agents.stripe.com/aroha/v1")
+ */
+export async function generateWebAgent(domain, path, endpoint) {
+    const privateKey = ed.utils.randomPrivateKey();
+    const publicKey = await ed.getPublicKeyAsync(privateKey);
+    const did = buildWebDID(domain, path);
+    const keyId = `${did}#key-1`;
+    const now = new Date().toISOString();
+    const agentEndpoint = endpoint ?? `https://${domain}/aroha/v1`;
+    const webDoc = {
+        "@context": [
+            "https://www.w3.org/ns/did/v1",
+            "https://w3id.org/security/suites/ed25519-2020/v1",
+            "https://aroha-labs.com/contexts/aroha-web/v1",
+        ],
+        id: did,
+        verificationMethod: [
+            {
+                id: keyId,
+                type: "Ed25519VerificationKey2020",
+                controller: did,
+                publicKeyMultibase: toMultibase(publicKey),
+            },
+        ],
+        authentication: [keyId],
+        assertionMethod: [keyId],
+        keyAgreement: [keyId],
+        service: [
+            {
+                id: `${did}#aroha`,
+                type: "ArohaEndpoint",
+                serviceEndpoint: agentEndpoint,
+            },
+        ],
+        created: now,
+        updated: now,
+        arohaWeb: {
+            domain,
+            path,
+            keyCommitmentHash: keyCommitmentHash(publicKey),
+            keyHistory: [],
+        },
+    };
+    const txt = dnsTXTValue(did, publicKey);
+    const url = wellKnownUrl(did);
+    return {
+        did,
+        privateKey,
+        publicKey,
+        document: webDoc,
+        webDocument: webDoc,
+        dnsTXTRecord: txt,
+        wellKnownUrl: url,
+    };
+}
+// ─── Key rotation ──────────────────────────────────────────────────────────────
+/**
+ * Rotate to a new key pair. The old key signs a rotation record that is
+ * embedded in the new DID Document. The new key is not trusted until
+ * `coolDownHours` (default 24h) after the rotation is announced.
+ *
+ * Publish the returned `webDocument` at the well-known URL and update the
+ * DNS TXT record with `dnsTXTRecord` to complete the rotation.
+ */
+export async function rotateKey(current, coolDownHours = 24) {
+    const newPrivateKey = ed.utils.randomPrivateKey();
+    const newPublicKey = await ed.getPublicKeyAsync(newPrivateKey);
+    const oldPubKeyMultibase = toMultibase(current.publicKey);
+    const now = new Date();
+    const trustAfter = new Date(now.getTime() + coolDownHours * 3_600_000);
+    // Rotation payload: predecessorKey ∥ newKeyHash ∥ rotatedAt
+    const newKeyHash = keyCommitmentHash(newPublicKey);
+    const payload = new TextEncoder().encode(oldPubKeyMultibase + newKeyHash + now.toISOString());
+    const sig = await ed.signAsync(payload, current.privateKey);
+    const rotation = {
+        rotatedAt: now.toISOString(),
+        trustAfter: trustAfter.toISOString(),
+        predecessorKey: oldPubKeyMultibase,
+        newKeyHash,
+        predecessorSignature: Buffer.from(sig).toString("base64url"),
+    };
+    const { domain, path } = current.webDocument.arohaWeb;
+    const did = buildWebDID(domain, path);
+    const keyId = `${did}#key-1`;
+    const ts = now.toISOString();
+    const newDoc = {
+        ...current.webDocument,
+        verificationMethod: [
+            {
+                id: keyId,
+                type: "Ed25519VerificationKey2020",
+                controller: did,
+                publicKeyMultibase: toMultibase(newPublicKey),
+            },
+        ],
+        updated: ts,
+        arohaWeb: {
+            ...current.webDocument.arohaWeb,
+            keyCommitmentHash: keyCommitmentHash(newPublicKey),
+            keyHistory: [rotation, ...current.webDocument.arohaWeb.keyHistory],
+        },
+    };
+    return {
+        did,
+        privateKey: newPrivateKey,
+        publicKey: newPublicKey,
+        document: newDoc,
+        webDocument: newDoc,
+        dnsTXTRecord: dnsTXTValue(did, newPublicKey),
+        wellKnownUrl: wellKnownUrl(did),
+    };
+}
+// ─── Resolve ──────────────────────────────────────────────────────────────────
+/**
+ * Resolve a did:aroha-web: identifier.
+ *
+ * Fetches the DID Document over HTTPS and, if `verifyDNS` is true,
+ * also verifies the DNS TXT key-commitment. Both must match for full
+ * two-factor verification.
+ *
+ * In Node.js server environments, pass a custom `dnsResolver` to perform
+ * the DNS TXT lookup. In browser or edge environments, set `verifyDNS: false`
+ * (single-channel HTTPS-only, same security as did:wba).
+ *
+ * @param did          The did:aroha-web: identifier to resolve
+ * @param verifyDNS    Whether to check the DNS TXT record (default: true)
+ * @param dnsResolver  Optional custom DNS TXT resolver
+ */
+export async function resolveWebDID(did, verifyDNS = true, dnsResolver, fetchTimeoutMs = 10_000) {
+    const url = wellKnownUrl(did);
+    // ── Step 1: Fetch DID Document over HTTPS ─────────────────────────────────
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), fetchTimeoutMs);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: { Accept: "application/json" },
+            signal: ctrl.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        throw new Error(`Failed to resolve ${did}: HTTP ${res.status} from ${url}`);
+    }
+    const doc = await res.json();
+    if (doc.id !== did) {
+        throw new Error(`DID mismatch: document claims ${doc.id}, expected ${did}`);
+    }
+    const activeKey = fromMultibase(doc.verificationMethod[0].publicKeyMultibase);
+    // ── Step 2: Verify all rotation records in keyHistory ────────────────────
+    if (doc.arohaWeb?.keyHistory?.length > 0) {
+        for (const rotation of doc.arohaWeb.keyHistory) {
+            const rotationValid = await verifyKeyRotation(rotation);
+            if (!rotationValid) {
+                throw new Error(`DID ${did}: key rotation record (rotatedAt ${rotation.rotatedAt}) has invalid predecessor signature`);
+            }
+        }
+    }
+    // ── Step 4: Check key rotation cool-down ─────────────────────────────────
+    let keyTrusted = true;
+    let trustReason;
+    if (doc.arohaWeb?.keyHistory?.length > 0) {
+        const latestRotation = doc.arohaWeb.keyHistory[0];
+        const trustAfter = new Date(latestRotation.trustAfter);
+        if (new Date() < trustAfter) {
+            keyTrusted = false;
+            trustReason = `Key rotation cool-down active until ${latestRotation.trustAfter}`;
+        }
+    }
+    // ── Step 5: DNS TXT key-commitment verification ────────────────────────────
+    let dnsVerified = false;
+    if (verifyDNS) {
+        const { domain, path } = parseWebDID(did);
+        let txtRecords = [];
+        if (dnsResolver) {
+            txtRecords = await dnsResolver(domain).catch(() => []);
+        }
+        else if (typeof globalThis["Deno"] !== "undefined") {
+            // Deno DNS API
+            try {
+                const denoGlobal = globalThis.Deno;
+                const records = await denoGlobal
+                    .resolveDns(`_aroha.${domain}`, "TXT");
+                txtRecords = records.flat();
+            }
+            catch { /* DNS unavailable — fall back to HTTPS-only */ }
+        }
+        // Node.js: caller must pass dnsResolver (avoids bundling dns module in core)
+        for (const txt of txtRecords) {
+            const parsed = parseDNSTXT(txt);
+            if (!parsed)
+                continue;
+            if (parsed.path !== path)
+                continue;
+            const expectedHash = keyCommitmentHash(activeKey);
+            if (parsed.keyhash === expectedHash) {
+                dnsVerified = true;
+                break;
+            }
+        }
+    }
+    return { document: doc, dnsVerified, keyTrusted, trustReason };
+}
+/**
+ * Verify a key rotation record — confirms the predecessor key signed the
+ * rotation event voluntarily (prevents unauthorized key replacement).
+ */
+export async function verifyKeyRotation(rotation) {
+    try {
+        const predKey = fromMultibase(rotation.predecessorKey);
+        const newHash = rotation.newKeyHash;
+        const payload = new TextEncoder().encode(rotation.predecessorKey + newHash + rotation.rotatedAt);
+        const sig = Buffer.from(rotation.predecessorSignature, "base64url");
+        return await ed.verifyAsync(sig, payload, predKey);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=web-did.js.map

package/dist/identity/web-did.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-did.js","sourceRoot":"","sources":["../../src/identity/web-did.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @aroha-sdk/core — Aroha Protocol Layers 0–3
+ *
+ * Layer 0: Transport  → ArohaServer, ArohaClient
+ * Layer 1: Identity   → generateDID, DIDDocument, issueCredential, verifyCredential
+ *          Auth       → issueCredential, verifyCredential, ArohaRole, RbacPolicy, checkPermission
+ * Layer 3: Messaging  → buildEnvelope, validateEnvelope, ArohaEnvelope, all message types
+ * Crypto:             → signMessage, verifyMessageSignature, encryptBody, decryptBody
+ */
+export * from "./identity/index.js";
+export * from "./crypto/index.js";
+export * from "./messages/index.js";
+export * from "./transport/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @aroha-sdk/core — Aroha Protocol Layers 0–3
+ *
+ * Layer 0: Transport  → ArohaServer, ArohaClient
+ * Layer 1: Identity   → generateDID, DIDDocument, issueCredential, verifyCredential
+ *          Auth       → issueCredential, verifyCredential, ArohaRole, RbacPolicy, checkPermission
+ * Layer 3: Messaging  → buildEnvelope, validateEnvelope, ArohaEnvelope, all message types
+ * Crypto:             → signMessage, verifyMessageSignature, encryptBody, decryptBody
+ */
+export * from "./identity/index.js";
+export * from "./crypto/index.js";
+export * from "./messages/index.js";
+export * from "./transport/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/dist/messages/envelope.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Aroha Protocol — Layer 3 Message Envelope
+ *
+ * Implements the spec's message envelope format.
+ * Every Aroha message, regardless of type, uses this envelope.
+ *
+ * Responsibilities:
+ *   - Build outbound envelopes (build + sign)
+ *   - Validate inbound envelopes (schema + signature + nonce + expiry + recipient)
+ *
+ * This module is pure protocol. It does not route messages or apply
+ * business logic — that belongs to the application tier.
+ */
+import { type MessageProof } from "../crypto/signing.js";
+import { NonceRegistry } from "./nonce.js";
+import { type ArohaMessageType, type ArohaBodyByType } from "./types.js";
+export interface ArohaEnvelope<T extends ArohaMessageType = ArohaMessageType> {
+    "@context": string[];
+    id: string;
+    type: T;
+    from: string;
+    to: string;
+    created: string;
+    expires: string;
+    nonce: string;
+    correlationId: string;
+    body: T extends keyof ArohaBodyByType ? ArohaBodyByType[T] : Record<string, unknown>;
+    proof?: MessageProof;
+    /** W3C Trace Context traceparent header — injected by @aroha-sdk/telemetry for distributed tracing. */
+    traceparent?: string;
+    /**
+     * Model routing hint — set by @aroha-sdk/orchestrator ModelRouter.
+     * Informational only: tells the receiving agent which model tier to use
+     * for processing this request. Never enforced by the transport layer.
+     */
+    routingHint?: {
+        complexity: "trivial" | "standard" | "complex";
+        suggestedModel?: string;
+    };
+}
+/**
+ * Build and sign an outbound Aroha message envelope.
+ *
+ * @param type             One of the 15 Aroha message types
+ * @param from             Sender DID (did:aroha:<id>)
+ * @param to               Recipient DID (did:aroha:<id>)
+ * @param body             Message body — typed per message type
+ * @param correlationId    Saga or session ID linking related messages
+ * @param privateKey       Sender's Ed25519 private key
+ * @param ttlSeconds       How long the message is valid (default: 300s / 5min)
+ */
+export interface BuildEnvelopeOptions {
+    ttlSeconds?: number;
+    /** W3C Trace Context traceparent — propagated by @aroha-sdk/telemetry. */
+    traceparent?: string;
+    /** Model routing hint — set by @aroha-sdk/orchestrator ModelRouter. */
+    routingHint?: ArohaEnvelope["routingHint"];
+}
+export declare function buildEnvelope<T extends ArohaMessageType>(type: T, from: string, to: string, body: T extends keyof ArohaBodyByType ? ArohaBodyByType[T] : Record<string, unknown>, correlationId: string, privateKey: Uint8Array, ttlSecondsOrOptions?: number | BuildEnvelopeOptions): Promise<ArohaEnvelope<T>>;
+/**
+ * Build an unsigned Aroha envelope for use within a trusted network mesh
+ * (VPC, mTLS service mesh). The receiving server must be configured with
+ * bypassSignatureFor to accept envelopes from this sender DID.
+ */
+export declare function buildUnsignedEnvelope<T extends ArohaMessageType>(type: T, from: string, to: string, body: T extends keyof ArohaBodyByType ? ArohaBodyByType[T] : Record<string, unknown>, correlationId: string, opts?: BuildEnvelopeOptions): Promise<ArohaEnvelope<T>>;
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Validate an inbound Aroha message envelope.
+ *
+ * Checks (per spec):
+ *   1. Signature verification (against provided public key)
+ *   2. Message expiry (expires field)
+ *   3. Nonce freshness (replay attack prevention)
+ *   4. Recipient match (to field must equal this agent's DID)
+ *
+ * @param envelope      The received message envelope
+ * @param senderPubKey  Ed25519 public key of the claimed sender (looked up from registry)
+ * @param myDID         This agent's DID (to verify the "to" field)
+ * @param nonceRegistry Shared nonce registry for this agent
+ */
+export interface ValidateEnvelopeOptions {
+    /** Skip Ed25519 signature check — use only within trusted mesh / VPC environments. */
+    skipSignature?: boolean;
+    /**
+     * Clock skew tolerance in milliseconds applied to the expires check.
+     * Accepts messages that expired up to this many ms ago.
+     * Recommended: 5000 (5s) for cross-region deployments.
+     * Default: 0 (strict).
+     */
+    clockToleranceMs?: number;
+}
+export declare function validateEnvelope(envelope: ArohaEnvelope, senderPubKey: Uint8Array, myDID: string, nonceRegistry: NonceRegistry, options?: ValidateEnvelopeOptions): Promise<ValidationResult>;
+/** Create a new correlationId for a new saga or session. */
+export declare function newCorrelationId(): string;
+/** Extract the sender's DID from an envelope. */
+export declare function senderDID(envelope: ArohaEnvelope): string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/messages/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/messages/envelope.ts"],"names":[],"mappings":"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"}

package/dist/messages/envelope.js

@@ -0,0 +1,106 @@
+/**
+ * Aroha Protocol — Layer 3 Message Envelope
+ *
+ * Implements the spec's message envelope format.
+ * Every Aroha message, regardless of type, uses this envelope.
+ *
+ * Responsibilities:
+ *   - Build outbound envelopes (build + sign)
+ *   - Validate inbound envelopes (schema + signature + nonce + expiry + recipient)
+ *
+ * This module is pure protocol. It does not route messages or apply
+ * business logic — that belongs to the application tier.
+ */
+import { randomBytes } from "@noble/hashes/utils";
+import { v4 as uuidv4 } from "uuid";
+import { signMessage, verifyMessageSignature } from "../crypto/signing.js";
+// ─── Build ────────────────────────────────────────────────────────────────────
+const Aroha_CONTEXT = [
+    "https://aroha-labs.com/contexts/v1",
+    "https://w3id.org/security/suites/ed25519-2020/v1",
+];
+export async function buildEnvelope(type, from, to, body, correlationId, privateKey, ttlSecondsOrOptions = 300) {
+    const opts = typeof ttlSecondsOrOptions === "number"
+        ? { ttlSeconds: ttlSecondsOrOptions }
+        : ttlSecondsOrOptions;
+    const ttlSeconds = opts.ttlSeconds ?? 300;
+    const now = new Date();
+    const expires = new Date(now.getTime() + ttlSeconds * 1000);
+    const envelope = {
+        "@context": Aroha_CONTEXT,
+        id: `urn:uuid:${uuidv4()}`,
+        type,
+        from,
+        to,
+        created: now.toISOString(),
+        expires: expires.toISOString(),
+        nonce: Buffer.from(randomBytes(32)).toString("hex"),
+        correlationId,
+        body,
+        ...(opts.traceparent ? { traceparent: opts.traceparent } : {}),
+        ...(opts.routingHint ? { routingHint: opts.routingHint } : {}),
+    };
+    const keyId = `${from}#key-1`;
+    const proof = await signMessage(envelope, privateKey, keyId);
+    return { ...envelope, proof };
+}
+/**
+ * Build an unsigned Aroha envelope for use within a trusted network mesh
+ * (VPC, mTLS service mesh). The receiving server must be configured with
+ * bypassSignatureFor to accept envelopes from this sender DID.
+ */
+export async function buildUnsignedEnvelope(type, from, to, body, correlationId, opts = {}) {
+    const ttlSeconds = opts.ttlSeconds ?? 300;
+    const now = new Date();
+    const expires = new Date(now.getTime() + ttlSeconds * 1000);
+    return {
+        "@context": Aroha_CONTEXT,
+        id: `urn:uuid:${uuidv4()}`,
+        type,
+        from,
+        to,
+        created: now.toISOString(),
+        expires: expires.toISOString(),
+        nonce: Buffer.from(randomBytes(32)).toString("hex"),
+        correlationId,
+        body,
+        ...(opts.traceparent ? { traceparent: opts.traceparent } : {}),
+    };
+}
+export async function validateEnvelope(envelope, senderPubKey, myDID, nonceRegistry, options) {
+    // 1. Recipient check — must be addressed to us
+    if (envelope.to !== myDID) {
+        return { valid: false, reason: `Message addressed to ${envelope.to}, not ${myDID}` };
+    }
+    // 2. Expiry check
+    const tolerance = options?.clockToleranceMs ?? 0;
+    if (tolerance < 0) {
+        return { valid: false, reason: "Invalid clockToleranceMs: must be non-negative" };
+    }
+    if (new Date(envelope.expires).getTime() + tolerance < Date.now()) {
+        return { valid: false, reason: `Message expired at ${envelope.expires} (outside tolerance window)` };
+    }
+    // 3. Nonce check (replay prevention)
+    const nonceFresh = await nonceRegistry.checkAsync(envelope.nonce, envelope.expires);
+    if (!nonceFresh) {
+        return { valid: false, reason: "Nonce replay detected" };
+    }
+    // 4. Signature verification (skip in trusted mesh mode)
+    if (!options?.skipSignature) {
+        const isValid = await verifyMessageSignature(envelope, senderPubKey);
+        if (!isValid) {
+            return { valid: false, reason: "Signature verification failed" };
+        }
+    }
+    return { valid: true };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Create a new correlationId for a new saga or session. */
+export function newCorrelationId() {
+    return `saga-${uuidv4()}`;
+}
+/** Extract the sender's DID from an envelope. */
+export function senderDID(envelope) {
+    return envelope.from;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/messages/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/messages/envelope.ts"],"names":[],"mappings":"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"}