@kya-os/cli 1.8.1 → 1.8.3

package/dist/orchestrator/github-credential-anchor-sender.js

@@ -0,0 +1,313 @@
+/**
+ * Anchoring a GitHub credential in the hub (review-loop P16, commit 3).
+ *
+ * Builds a signed `GithubCredentialAnchor` (see `@kya-os/contracts/handshake/
+ * github-credential-anchor.ts`) from a locally stored credential
+ * (`utils/github-credential.ts`) and delivers it to the configured hub over
+ * the SAME observer wire path `hub-observer.ts` speaks: `observe` hello,
+ * challenge, proof-of-possession -- see that file's module doc for why this
+ * package never imports `@kya-os/compute` and instead speaks the shared
+ * wire format directly. Unlike `HubObserver`, this is a ONE-SHOT
+ * connect/authenticate/submit/await-result/close, not a long-lived
+ * reconnecting subscription -- a different lifecycle for a different job,
+ * so it does not extend or wrap that class.
+ *
+ * The anchor is signed and the wire connection authenticated with the SAME
+ * key: the designated agent profile's signing key
+ * (`signingKeyPath(agentSlug)`, the exact file `dco setup`/`dco fix` already
+ * use -- see `ssh-key.ts`'s `parseEd25519SshPrivateKeyPem`). That is what
+ * lets the hub check "the anchor's proof verifies against the DID that
+ * authenticated this very connection" without a second key or a fresh
+ * resolution: the hub already knows this socket proved control of `did`
+ * before a single `credential_anchor` frame arrives.
+ *
+ * No hub configured, or the hub unreachable: the anchor is queued at
+ * `~/.mcpi/github/pending-anchor.json` (fingerprints and proof only -- by
+ * construction, since `GithubCredentialAnchorSchema` holds no secret) for a
+ * later `kya-os init` or P17's wrapper connection to deliver.
+ *
+ * @module cli/orchestrator/github-credential-anchor-sender
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import WebSocket from "ws";
+import { GithubCredentialAnchorMessageSchema, GithubCredentialAnchorResultSchema, GithubCredentialAnchorSchema, ObserverHelloSchema, getGithubCredentialAnchorSigningString, } from "@kya-os/contracts/handshake";
+import { publicJwkFor, respondToObserverChallenge } from "./hub-observer.js";
+import { parseEd25519SshPrivateKeyPem, signWithEd25519Seed } from "../utils/dco/ssh-key.js";
+import { signingKeyPath } from "../utils/dco/paths.js";
+import { ensureSecureDir, writeFileAtomicSafe } from "../utils/cli-kit/index.js";
+import { credentialsDir } from "../utils/github-credential.js";
+/**
+ * Derive the `ObserverIdentity` (did + raw Ed25519 seed) an agent profile
+ * signs and authenticates with, from its converted signing key file
+ * (`signingKeyPath(agentSlug)`, the same file `dco setup`/`dco fix` use).
+ * Shared by {@link buildGithubCredentialAnchor} (a fresh anchor's signer)
+ * and `github-credential-stage.ts` (re-authenticating to deliver a
+ * previously queued anchor, where no new anchor is being built) so both
+ * paths derive the SAME identity for the same profile from one place.
+ */
+export function identityForAgentProfile(agentDid, agentSlug, readSigningKeyPemImpl = (slug) => readFileSync(signingKeyPath(slug), "utf-8")) {
+    const pem = readSigningKeyPemImpl(agentSlug);
+    const { seed } = parseEd25519SshPrivateKeyPem(pem);
+    return { did: agentDid, privateKey: seed.toString("base64") };
+}
+/**
+ * Build and sign a `GithubCredentialAnchor` for `credential`. Signing stays
+ * entirely inside this module -- callers never touch key material, only the
+ * finished anchor and the identity derived alongside it (matching how
+ * `dco fix.ts` keeps its Ed25519 seed scoped to one function, extended here
+ * to the one extra byproduct -- the wire identity -- that a second read of
+ * the same file would otherwise require).
+ */
+export function buildGithubCredentialAnchor(credential, fingerprints, params) {
+    const now = params.now ?? (() => new Date().toISOString());
+    const rest = {
+        githubLogin: credential.githubLogin,
+        tokenFingerprint: fingerprints.tokenFingerprint,
+        webhookSecretFingerprint: fingerprints.webhookSecretFingerprint,
+        scopes: credential.scopes,
+        agentDids: params.agentDids,
+        createdAt: now(),
+        ...(params.supersedes ? { supersedes: params.supersedes } : {}),
+    };
+    const identity = params.readSigningKeyPemImpl
+        ? identityForAgentProfile(params.agentDid, params.agentSlug, params.readSigningKeyPemImpl)
+        : identityForAgentProfile(params.agentDid, params.agentSlug);
+    const seed = Buffer.from(identity.privateKey, "base64");
+    const signingString = getGithubCredentialAnchorSigningString(rest);
+    const signature = signWithEd25519Seed(seed, Buffer.from(signingString, "utf8")).toString("base64url");
+    const anchor = GithubCredentialAnchorSchema.parse({
+        ...rest,
+        proof: { alg: "Ed25519", signature },
+    });
+    return { anchor, identity };
+}
+/**
+ * Connect to the hub as an authenticated observer, submit `anchor` once
+ * admitted, and resolve with whether the hub accepted it. Always settles
+ * (never hangs): a timeout, a socket error, or an early close all resolve
+ * `{ delivered: false, reason }` rather than rejecting -- the caller's
+ * fallback is "queue it locally," not "crash the init stage."
+ */
+export function sendGithubCredentialAnchor(anchor, options) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let sentAnchor = false;
+        const wsFactory = options.wsFactory ?? ((endpoint) => new WebSocket(endpoint));
+        let ws;
+        try {
+            ws = wsFactory(options.endpoint);
+        }
+        catch (err) {
+            resolve({ delivered: false, reason: message(err) });
+            return;
+        }
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closing */
+            }
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ delivered: false, reason: `hub at ${options.endpoint} did not respond in time` });
+        }, options.timeoutMs ?? 10000);
+        ws.on("open", () => {
+            try {
+                const hello = ObserverHelloSchema.parse({
+                    type: "observe",
+                    did: options.identity.did,
+                    publicKey: publicJwkFor(options.identity),
+                });
+                ws.send(JSON.stringify(hello));
+            }
+            catch (err) {
+                finish({ delivered: false, reason: message(err) });
+            }
+        });
+        ws.on("error", (err) => finish({ delivered: false, reason: message(err) }));
+        ws.on("close", (code, reason) => {
+            finish({
+                delivered: false,
+                reason: `hub closed the connection (${code}${reason.length ? `: ${reason.toString()}` : ""})`,
+            });
+        });
+        ws.on("message", (raw) => {
+            void handleFrame(raw.toString());
+        });
+        async function handleFrame(text) {
+            if (settled)
+                return;
+            let msg;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed !== "object" || parsed === null)
+                    return;
+                msg = parsed;
+            }
+            catch {
+                return; // a frame we cannot parse is not a frame we can act on
+            }
+            if (msg["type"] === "challenge") {
+                try {
+                    const frame = await respondToObserverChallenge(options.identity, msg);
+                    if (frame)
+                        ws.send(frame);
+                }
+                catch (err) {
+                    finish({ delivered: false, reason: message(err) });
+                }
+                return;
+            }
+            // "snapshot" is the observer-admission signal (see hub-observer.ts) --
+            // once it lands, this socket is authenticated and may submit.
+            if (msg["type"] === "snapshot" && !sentAnchor) {
+                sentAnchor = true;
+                try {
+                    const anchorMessage = GithubCredentialAnchorMessageSchema.parse({
+                        type: "credential_anchor",
+                        anchor,
+                    });
+                    ws.send(JSON.stringify(anchorMessage));
+                }
+                catch (err) {
+                    finish({ delivered: false, reason: message(err) });
+                }
+                return;
+            }
+            if (msg["type"] === "credential_anchor_result") {
+                const result = GithubCredentialAnchorResultSchema.safeParse(msg);
+                if (!result.success) {
+                    finish({ delivered: false, reason: "malformed credential_anchor_result frame from hub" });
+                    return;
+                }
+                finish(result.data.ok
+                    ? { delivered: true }
+                    : { delivered: false, reason: result.data.error ?? "hub rejected the anchor" });
+            }
+        }
+    });
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ── Pending queue (offline path) ───────────────────────────────────────
+/** ~/.mcpi/github/pending-anchor.json -- fingerprints and proof only; no secrets by construction. */
+export function pendingAnchorPath() {
+    return join(credentialsDir(), "pending-anchor.json");
+}
+/**
+ * Queue `anchor` (signed by `signerDid`) at {@link pendingAnchorPath}.
+ * Never throws: a real filesystem error here (permissions, ENOSPC)
+ * degrades to a reported failure rather than propagating, matching
+ * {@link deliverGithubCredentialAnchor}'s own "never throws" contract -- a
+ * queue write is itself part of that degrade-to-pending path, not a
+ * separate one that could still blow past it.
+ */
+function writePendingAnchor(anchor, signerDid) {
+    try {
+        ensureSecureDir(credentialsDir());
+        const record = { anchor, signerDid };
+        writeFileAtomicSafe(pendingAnchorPath(), JSON.stringify(record, null, 2) + "\n", 0o600);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, reason: message(err) };
+    }
+}
+/** The queued anchor and its signer, or undefined if none is pending (or the file is unreadable/corrupt). */
+export function readPendingAnchor() {
+    const path = pendingAnchorPath();
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        const { anchor, signerDid } = parsed;
+        if (typeof signerDid !== "string" || signerDid.length === 0)
+            return undefined;
+        const result = GithubCredentialAnchorSchema.safeParse(anchor);
+        return result.success ? { anchor: result.data, signerDid } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function clearPendingAnchor() {
+    rmSync(pendingAnchorPath(), { force: true });
+}
+/**
+ * Deliver `anchor` to the hub if one is configured and reachable; otherwise
+ * queue it at {@link pendingAnchorPath} and exit cleanly. Never throws --
+ * every failure mode degrades to "pending," which is exactly the offline
+ * path the init stage needs to complete without a hub.
+ */
+export async function deliverGithubCredentialAnchor(anchor, identity, options = {}) {
+    const onNotice = options.onNotice ?? (() => { });
+    if (!options.hubEndpoint) {
+        const queued = writePendingAnchor(anchor, identity.did);
+        onNotice(queued.ok
+            ? "No hub configured -- the GitHub credential anchor is pending and will be delivered on a later `kya-os init`."
+            : `No hub configured, and the anchor could not even be queued locally (${queued.reason}) -- the credential itself is still saved, but re-run \`kya-os init\` once this is fixed.`);
+        return { status: "pending", reason: "no hub configured" };
+    }
+    const sendImpl = options.sendImpl ?? sendGithubCredentialAnchor;
+    const result = await sendImpl(anchor, { endpoint: options.hubEndpoint, identity });
+    if (result.delivered) {
+        clearPendingAnchor();
+        return { status: "delivered" };
+    }
+    const queued = writePendingAnchor(anchor, identity.did);
+    onNotice(queued.ok
+        ? `Could not deliver the GitHub credential anchor to the hub (${result.reason}) -- it is pending.`
+        : `Could not deliver the GitHub credential anchor to the hub (${result.reason}), and it could not even be queued locally (${queued.reason}) -- the credential itself is still saved, but re-run \`kya-os init\` once this is fixed.`);
+    return { status: "pending", reason: result.reason };
+}
+/**
+ * Attempt delivery of a previously queued anchor (e.g. from a later
+ * `kya-os init`, or P17's wrapper connection). A no-op, reported distinctly,
+ * when nothing is queued.
+ *
+ * `resolveIdentity` maps the queued anchor's recorded `signerDid` to that
+ * profile's CURRENT identity -- never a caller-guessed one. `listProfiles()`
+ * has no defined order (`readdirSync`), so "the first profile on the
+ * machine" today is not reliably the profile that signed a PRIOR anchor;
+ * looking it up by the DID actually recorded at queue time is what makes
+ * this retry succeed instead of failing proof verification against the
+ * wrong key. Never throws, matching every other function in this module's
+ * "degrade to pending" contract: `resolveIdentity` typically ends up
+ * calling {@link identityForAgentProfile}, which reads a signing key file
+ * off disk and throws if it's missing or unreadable -- a real possibility
+ * (deleted, corrupted, permissions) that must fall through to "pending"
+ * exactly like a resolved-but-unusable identity, not crash the caller.
+ */
+export async function deliverPendingGithubCredentialAnchor(resolveIdentity, options = {}) {
+    const pending = readPendingAnchor();
+    if (!pending)
+        return { status: "none" };
+    let identity;
+    let resolveError;
+    try {
+        identity = resolveIdentity(pending.signerDid);
+    }
+    catch (err) {
+        resolveError = message(err);
+    }
+    if (!identity) {
+        const onNotice = options.onNotice ?? (() => { });
+        const reason = resolveError
+            ? `the signing profile (${pending.signerDid}) could not be loaded (${resolveError})`
+            : `the signing profile (${pending.signerDid}) is no longer on this machine`;
+        onNotice(`Cannot retry delivering the queued GitHub credential anchor: ${reason}.`);
+        return { status: "pending", reason: `signer profile ${pending.signerDid} unresolvable: ${reason}` };
+    }
+    return deliverGithubCredentialAnchor(pending.anchor, identity, options);
+}
+//# sourceMappingURL=github-credential-anchor-sender.js.map

package/dist/orchestrator/github-credential-anchor-sender.js.map

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

package/dist/orchestrator/hub-dispatch.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The TUI's one control-plane action (review-loop P18 commit 4): dispatch
+ * a task to a connected agent.
+ *
+ * Trust boundary: this opens a short-lived, authenticated observer
+ * connection -- the SAME wire pattern `hub-observer.ts`'s long-lived
+ * `HubObserver` uses (contracts `./handshake`'s hello/challenge/proof
+ * frames, the #686 precedent), reusing its exported helpers rather than
+ * re-deriving the handshake. It sends exactly one `fleet.dispatch` frame,
+ * waits for exactly one `fleet.dispatch.result`, and closes -- no
+ * reconnect, no history, no long-lived state, because a TUI keystroke is
+ * a single request, not a subscription.
+ *
+ * `fleet.dispatch` here is NOT `@kya-os/compute`'s HTTP `fleet-mcp`
+ * surface (`packages/compute/src/didcomm/fleet-mcp.ts`), which is bearer-
+ * token/org-scoped and has no notion of a per-agent signing key. It is
+ * the wire-level message `packages/compute/src/didcomm/hub.ts` already
+ * handles directly on an admitted OBSERVER socket
+ * (`ws.on("message", ...)` inside `transport.onObserver`): a JSON frame
+ * `{ type: "fleet.dispatch", taskId, toDid, description, context?,
+ * timeoutMs? }`, answered with `{ type: "fleet.dispatch.result", taskId,
+ * status, response?, error?, ... }`. Reusing this existing hub-side
+ * handler is why this file adds nothing to `@kya-os/contracts` or
+ * `@kya-os/compute` -- the wire shape already exists and this PR's
+ * `Package:` line is `@kya-os/cli` alone.
+ *
+ * The hub proposes, the target's on-disk command allowlist (P17, epic
+ * decision 10) disposes: a refusal comes back as an ordinary
+ * `fleet.dispatch.result` with a non-"completed" status, which the caller
+ * renders as a refusal, not an error (see `AgentsView`'s handling of
+ * `status === "refused"`).
+ *
+ * @module cli/orchestrator/hub-dispatch
+ */
+import WebSocket from "ws";
+import { type ObserverIdentity } from "./hub-observer.js";
+import type { AgentProfile } from "../utils/agent-profiles.js";
+export interface DispatchWireResult {
+    taskId: string;
+    status: string;
+    response?: string;
+    error?: string;
+    ok: boolean;
+}
+export interface DispatchTaskConfig {
+    /** e.g. `ws://127.0.0.1:18821` or `wss://did-web-knowthat-ai-hub.fly.dev:4000`. */
+    endpoint: string;
+    /** Omit to connect anonymously, which only a loopback hub will accept. */
+    identity?: ObserverIdentity;
+    /** How long to wait for the observer handshake (hello/challenge/proof + snapshot). */
+    handshakeTimeoutMs?: number;
+    /** How long to wait for the fleet.dispatch.result frame once dispatched. */
+    dispatchTimeoutMs?: number;
+    /** Injectable transport seam for tests; defaults to the real `ws` client. */
+    wsFactory?: (endpoint: string) => WebSocket;
+}
+/**
+ * Opens one observer connection, authenticates if asked to, sends one
+ * `fleet.dispatch` frame for `targetDid`/`command`, and resolves with its
+ * `fleet.dispatch.result` -- or rejects on a connection/handshake/timeout
+ * failure. Always closes the socket before settling, on every path.
+ */
+export declare function dispatchTask(config: DispatchTaskConfig, targetDid: string, command: string): Promise<DispatchWireResult>;
+/**
+ * Is this endpoint loopback-only? Mirrors `isPlaintextNonLoopback`'s host
+ * set but answers a different question: that function asks "is this
+ * unencrypted AND remote" (a warn-but-allow case); this asks "is this
+ * unreachable from anywhere but this machine" (the ONLY case where
+ * connecting with no identity at all -- `--anonymous`-equivalent -- is
+ * appropriate for a write action like dispatch).
+ */
+export declare function isLoopbackEndpoint(endpoint: string): boolean;
+/**
+ * Builds the identity used to authenticate the dispatch connection, from
+ * the profile whose row is focused in the TUI. Every profile's key
+ * lives under `~/.mcpi/keys/<slug>` in the SSH-signing format
+ * `dco setup` writes (see `signing-key-writer.ts`); profiles never
+ * persist a raw seed on disk, so the seed is recovered from that SSH
+ * key via the same parser `dco fix` already uses to sign a fix
+ * attestation from the same file (`parseEd25519SshPrivateKeyPem`) rather
+ * than adding a second place that stores key material.
+ *
+ * Authenticating AS the profile being dispatched to -- rather than some
+ * separate "which of my identities is primary" concept, which does not
+ * exist anywhere else in this codebase -- is a deliberate scope
+ * decision: every profile under `~/.mcpi/keys/` belongs to the one
+ * operator running this TUI, so proving control of the row already in
+ * view is sufficient authorization and needs no new concept.
+ *
+ * Undefined if the key file is missing or not in the format this
+ * codebase writes -- the caller falls back to loopback-only anonymous
+ * dispatch in that case, matching `orchestrator daemon`'s own
+ * `--anonymous` precedent.
+ */
+export declare function resolveProfileIdentity(profile: AgentProfile): ObserverIdentity | undefined;
+export interface DispatchOutcome {
+    ok: boolean;
+    status: string;
+    detail?: string;
+    /**
+     * Set when `hubConfig.endpoint` is plaintext `ws://` to a non-loopback
+     * host: the same condition `orchestrator daemon` (`commands/
+     * orchestrator.ts`) warns about before attaching with a real identity,
+     * via the same `isPlaintextNonLoopback` helper. Surfaced through the
+     * outcome rather than a raw `console.warn` because this call happens
+     * from inside an active Ink render -- an unmediated console write here
+     * would corrupt the TUI's own screen buffer instead of reaching the user.
+     */
+    warning?: string;
+}
+/**
+ * The TUI-facing entry point: resolve the hub and the dispatching
+ * identity, dispatch, and reduce every failure mode (no hub configured,
+ * no usable key on a non-loopback hub, a transport/handshake error) to
+ * the same `DispatchOutcome` shape the agents view renders -- so the UI
+ * never has to distinguish "the wire call threw" from "the wire call
+ * returned an unhappy status".
+ */
+export declare function dispatchToProfile(profile: AgentProfile, command: string, wsFactory?: DispatchTaskConfig["wsFactory"]): Promise<DispatchOutcome>;
+//# sourceMappingURL=hub-dispatch.d.ts.map

package/dist/orchestrator/hub-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-dispatch.d.ts","sourceRoot":"","sources":["../../src/orchestrator/hub-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,SAAS,MAAM,IAAI,CAAC;AAE3B,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,CAAC;CAC7C;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,CAAC,CA+H7B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM5D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,GAAG,SAAS,CAQ1F;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,kBAAkB,CAAC,WAAW,CAAC,GAC1C,OAAO,CAAC,eAAe,CAAC,CAmC1B"}