@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

package/dist/a2a/mission-result-wire.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapMissionResultDataPart = wrapMissionResultDataPart;
+exports.isMissionResultDataPart = isMissionResultDataPart;
+exports.receiveInboundMissionResult = receiveInboundMissionResult;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * THE HARNESS-OWNED RESULT WIRE.
+ *
+ * A mission RESULT is NOT a `FriendsKind` (`FriendsKind` = profile_share |
+ * mission_share | coordination) — `prepareMissionResult`/`importMissionResult` are
+ * transport-agnostic + store-only, and the result does NOT ride `sendShare`/
+ * `receiveShare`. So the HARNESS owns the wire: the result envelope is sealed (reusing
+ * the sign-then-seal crypto) and wrapped in a DataPart carrying a distinct `ouroKind:
+ * "mission_result"` discriminator. The inbound bridge recognizes that tag and routes
+ * it to `importMissionResult` — NEVER to `receiveShare`, which would mis-route a
+ * non-`FriendsKind` envelope. This is "a DataPart variant + an inbound route branch"
+ * (the carrier is the friends `unwrapDataPart` shape + one extra tag field — no
+ * structural change beyond that).
+ *
+ * SECURITY — the wire AUTHENTICATES the sender exactly like the share path
+ * (`receiveShare` in friends' `adapter.ts`). `openSealedEnvelope` does AEAD
+ * decryption ONLY — it does NOT verify the signature (its docstring names the
+ * adapter's `DidVerifier` as "the single authentication gate"). The decrypted
+ * `envelope.fromAgentId` is therefore attacker-controlled plaintext: the recipient's
+ * X25519 pubkey is public (derived from the published DID), so any party can SEAL a
+ * forged result to us. Authentication is the ONLY barrier. Before trusting the
+ * claimed sender we therefore replicate `receiveShare`'s gate:
+ *   1. binding check — `opened.signerDid === opened.fromAgentId` (and non-empty),
+ *   2. resolve + pin the sender DID (TOFU pin + signed-rotation evaluation),
+ *   3. hand `importMissionResult` a REAL `DidVerifier` bound to the pinned key, so
+ *      `verifier.verify(fromAgentId, proof)` runs the Ed25519 signature check against
+ *      the pinned key — NOT the no-op `tofuVerifier` the importer defaults to.
+ * Replay is deduped on the seal nonce (durable `SeenLedger`), matching the share path.
+ */
+const OURO_RESULT_KIND = "mission_result";
+/** Wrap a sealed result envelope into the harness-owned `mission_result` DataPart. */
+function wrapMissionResultDataPart(input) {
+    return {
+        messageId: `result-${Math.random().toString(36).slice(2)}`,
+        role: "agent",
+        parts: [{
+                kind: "data",
+                data: {
+                    v: input.sealedEnvelope.v,
+                    sealed: input.sealedEnvelope.sealed,
+                    recipientDid: input.recipientDid,
+                    ouroKind: OURO_RESULT_KIND,
+                },
+            }],
+    };
+}
+/** Whether an inbound message carries the harness-owned `mission_result` DataPart. */
+function isMissionResultDataPart(message) {
+    if (!Array.isArray(message.parts))
+        return false;
+    return message.parts.some((p) => p && p.kind === "data" && typeof p.data === "object" && p.data !== null
+        && p.data.ouroKind === OURO_RESULT_KIND);
+}
+/** Extract the sealed envelope from a `mission_result` DataPart, or null. */
+function unwrapMissionResultDataPart(message) {
+    if (!Array.isArray(message.parts) || message.parts.length !== 1)
+        return null;
+    const part = message.parts[0];
+    if (!part || part.kind !== "data" || !part.data)
+        return null;
+    const data = part.data;
+    if (data.ouroKind !== OURO_RESULT_KIND)
+        return null;
+    if (typeof data.v !== "number" || typeof data.recipientDid !== "string" || !data.sealed)
+        return null;
+    return { sealed: { v: data.v, sealed: data.sealed }, recipientDid: data.recipientDid };
+}
+/**
+ * Route an inbound `mission_result` DataPart to `importMissionResult`, AUTHENTICATING
+ * the sender exactly like `receiveShare` does for every other inbound kind.
+ *
+ * Ordering (mirrors the share bridge's trust trap + authentication gate):
+ *   1. recognize + unwrap the harness `mission_result` carrier (else `not-a-result`).
+ *   2. replay dedup on the seal nonce (durable `SeenLedger`) — before any state change.
+ *   3. `openSealedEnvelope` → AEAD-decrypt only (unseal/recipient failures → reject).
+ *   4. binding check — reject unless `opened.signerDid === opened.fromAgentId` (and
+ *      non-empty): the advisory `signerDid` (outer, unsigned) must match the claimed
+ *      sender. A divergence is a forged/spoofed bundle (`sender_binding_mismatch`).
+ *   5. `resolveAndPin` the sender DID (TOFU pin / signed-rotation) → the pinned key
+ *      (unresolvable/failed-binding/failed-rotation → `resolve_failed`).
+ *   6. build a `DidVerifier` bound to THIS envelope + the pinned key, mark the nonce
+ *      seen, then call `importMissionResult({ envelope, fromAgentId: <signed DID>,
+ *      trustOfSource }, { verifier })`. The verifier runs the REAL signature check
+ *      against the pinned key — a result signed with a key that is not the pinned key
+ *      for the claimed DID is rejected (`untrusted_source`). Every authorization gate
+ *      (no_mission / no_delegation / assignee_mismatch, fail-closed on a legacy
+ *      assignee-less delegation) is still enforced by the importer.
+ */
+async function receiveInboundMissionResult(message, deps) {
+    const payload = unwrapMissionResultDataPart(message);
+    if (!payload)
+        return { outcome: "not-a-result" };
+    // Replay dedup BEFORE any state change, keyed on the seal nonce (matches receiveShare).
+    if (deps.seen.isSeen(payload.sealed.sealed.n)) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (replayed seal nonce)",
+            meta: { reason: "replayed" },
+        });
+        return { outcome: "rejected", reason: "replayed" };
+    }
+    const recipientIdentity = { x25519Priv: deps.identity.x25519Priv, x25519Pub: deps.identity.x25519Pub };
+    const opened = (0, a2a_client_1.openSealedEnvelope)({
+        sodium: deps.sodium,
+        sealedEnvelope: payload.sealed,
+        recipientDid: deps.identity.did,
+        recipientIdentity,
+    });
+    if (!opened.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (unseal/recipient)",
+            meta: { reason: opened.error },
+        });
+        return { outcome: "rejected", reason: opened.error };
+    }
+    // SECURITY (binding): the trustworthy sender identity is the SIGNED `fromAgentId`.
+    // `openSealedEnvelope` does NOT verify the signature, so `fromAgentId` is untrusted
+    // until the DidVerifier confirms the pinned key signed THIS envelope. The advisory
+    // `signerDid` (from the outer, unsigned sealed plaintext) must match the claimed
+    // sender; a divergence is a forged/spoofed bundle (e.g. an attacker signing with its
+    // OWN key while claiming a victim's DID). Reject before resolving or importing.
+    const senderDid = opened.fromAgentId;
+    if (senderDid.length === 0 || opened.signerDid !== senderDid) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (sender binding mismatch — forged sender)",
+            meta: { reason: "sender_binding_mismatch", claimedDid: senderDid, signerDid: opened.signerDid },
+        });
+        return { outcome: "rejected", reason: "sender_binding_mismatch" };
+    }
+    // Read trust from the friend store BY the verified DID — never defaulted, never from
+    // the envelope. Unknown (or empty) DID ⇒ stranger.
+    const record = await (0, friends_1.findFriendByDid)(deps.store, senderDid);
+    const trust = record?.trustLevel ?? "stranger";
+    // Resolve + pin the SENDER's DID (async — BEFORE the sync verifier/importer).
+    const resolved = await deps.didResolution.resolveAndPin({
+        fromAgentId: senderDid,
+        did: senderDid,
+        pinStore: deps.pinStore,
+        trustOfSource: trust,
+    });
+    if (!resolved) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (sender DID resolve/pin failed)",
+            meta: { reason: "resolve_failed", verifiedDid: senderDid, trust },
+        });
+        return { outcome: "rejected", reason: "resolve_failed" };
+    }
+    // Build the sync verifier bound to THIS envelope + the pinned sender key. This is the
+    // single authentication gate (the importer would otherwise default to the no-op TOFU
+    // verifier). `verify` confirms the agentId===did binding AND the Ed25519 signature
+    // over the envelope against the pinned key.
+    const verifier = new a2a_client_1.DidVerifier({
+        sodium: deps.sodium,
+        pinnedEd25519Pub: resolved.ed25519Pub,
+        pinnedDid: senderDid,
+        envelope: opened.envelope,
+    });
+    // Mark seen now (idempotent imports + the replay guard above keep this safe).
+    deps.seen.markSeen(payload.sealed.sealed.n);
+    const result = await (0, friends_1.importMissionResult)(deps.missionStore, {
+        envelope: opened.envelope,
+        fromAgentId: senderDid,
+        trustOfSource: trust,
+    }, { verifier });
+    if (result.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_imported",
+            message: "imported inbound mission_result (authenticated, quarantined, attributed)",
+            meta: { verifiedDid: senderDid, trust, status: result.status },
+        });
+        return { outcome: "imported", verifiedDid: senderDid };
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_result_rejected",
+        message: "rejected inbound mission_result (import gate)",
+        meta: { reason: result.status, verifiedDid: senderDid, trust },
+    });
+    return { outcome: "rejected", reason: result.status };
+}

package/dist/a2a/onboarding.js

@@ -0,0 +1,133 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onboardA2APeer = onboardA2APeer;
+exports.onboardA2AClientByDid = onboardA2AClientByDid;
+const path = __importStar(require("node:path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const friends_1 = require("@ouro.bot/friends");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const client_1 = require("./client");
+function storeFor(options) {
+    if (options.store)
+        return options.store;
+    /* v8 ignore next -- default bundle root fallback is owned by identity path tests; CLI and onboarding tests inject explicit roots @preserve */
+    return new friends_1.FileFriendStore(path.join(options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${options.agentName}.ouro`, "friends"));
+}
+/** The normalized card URL (legacy URL-keyed identity for did-less cards). */
+function urlAgentId(cardUrl) {
+    const parsed = new URL(cardUrl);
+    parsed.hash = "";
+    return parsed.toString();
+}
+async function onboardA2APeer(options) {
+    // HTTP/URL glue stays harness-side: fetch the agent card, resolve its JSON-RPC
+    // endpoint, and derive the stable agentId. The record-shaping (mint/update the
+    // agent-peer friend) is delegated to @ouro.bot/friends' upsertAgentPeer.
+    const card = await (0, client_1.fetchA2AAgentCard)(options.cardUrl, options.fetchImpl);
+    const store = storeFor(options);
+    /* v8 ignore next -- fetchA2AAgentCard validates a usable endpoint or legacy url before returning a card @preserve */
+    const endpointUrl = (0, client_1.endpointForCard)(card) ?? options.cardUrl;
+    const protocolVersion = card.supportedInterfaces?.find((entry) => entry.url === endpointUrl)?.protocolVersion
+        ?? card.protocolVersion;
+    const name = options.name ?? card.name;
+    // THE FOOTGUN FIX: a DID-bearing card keys the record on its VERIFIED did:key
+    // (so an inbound sealed envelope — keyed on the signed DID — resolves to THIS
+    // record, not a stranger). A did-less (legacy) card keeps the URL-keyed identity
+    // unchanged (backward compatible). For did:key the binding is self-contained
+    // (`card.did === did`, `didDoc: null`); we ALSO require the served did:key to be a
+    // well-formed, parseable Ed25519 key (a malformed did:key could never key/verify
+    // an inbound envelope, so onboarding it would silently break the resolve later). A
+    // card whose DID is unparseable or fails the binding is REFUSED (no record
+    // written) — never TOFU-trust a mis-bound or malformed card.
+    const did = (0, client_1.cardDid)(card);
+    if (did) {
+        const parsed = (0, a2a_client_1.parseDidKey)(did);
+        const bound = parsed !== null && (0, a2a_client_1.verifyCardDidBinding)({ card: { did, url: options.cardUrl }, did, didDoc: null });
+        if (!bound) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "friends",
+                event: "friends.a2a_card_binding_rejected",
+                message: "refused A2A onboarding: card↔DID binding failed",
+                meta: { agentName: options.agentName, cardUrl: options.cardUrl, did, parseable: parsed !== null },
+            });
+            throw new Error(`A2A card↔DID binding failed for ${did}`);
+        }
+    }
+    // DID-keyed when present (externalId === did, a2a.did === did), else URL-keyed.
+    const externalId = did ?? urlAgentId(options.cardUrl);
+    const record = await (0, friends_1.upsertAgentPeer)(store, {
+        name,
+        agentId: externalId,
+        ...(options.trustLevel ? { trustLevel: options.trustLevel } : {}),
+        a2a: {
+            cardUrl: options.cardUrl,
+            endpointUrl,
+            agentId: externalId,
+            protocolVersion,
+            ...(did ? { did } : {}),
+        },
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.a2a_peer_onboarded",
+        message: "onboarded A2A peer into friend model",
+        meta: { agentName: options.agentName, friendId: record.id, peerName: record.name, trustLevel: record.trustLevel, ...(did ? { did } : {}) },
+    });
+    return record;
+}
+/**
+ * Onboard a client that serves no agent card (for example a coding harness with a
+ * file-backed identity) by its did:key alone. The record is keyed on the DID, so its
+ * signed, sealed messages resolve to this friend; the key must parse, or nothing is written.
+ */
+async function onboardA2AClientByDid(options) {
+    if ((0, a2a_client_1.parseDidKey)(options.did) === null)
+        throw new Error(`not a valid did:key: ${options.did}`);
+    const record = await (0, friends_1.upsertAgentPeer)(storeFor(options), {
+        name: options.name,
+        agentId: options.did,
+        ...(options.trustLevel ? { trustLevel: options.trustLevel } : {}),
+        a2a: { did: options.did, agentId: options.did },
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.a2a_client_onboarded",
+        message: "onboarded card-less A2A client into friend model",
+        meta: { agentName: options.agentName, friendId: record.id, peerName: record.name, trustLevel: record.trustLevel, did: options.did },
+    });
+    return record;
+}