@kavrosai/cli 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kavros OS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# @kavrosai/cli
+
+Language-agnostic developer CLI for Kavros workload egress.
+
+## Requirements
+
+- Node.js 18 or newer
+- A registered Kavros workload
+- Network access to the workload's data-plane endpoint
+
+## Install
+
+```bash
+npm install --global @kavrosai/cli
+```
+
+Or run it without a global install:
+
+```bash
+npx @kavrosai/cli doctor
+```
+
+## Configure
+
+```bash
+export KAVROS_API_URL="https://<data-plane-host>/api/agent/egress"
+export KAVROS_API_KEY="<workload-api-key>"
+export KAVROS_AGENT_ID="<workload-id>"
+```
+
+## Commands
+
+Check connectivity and workload configuration:
+
+```bash
+kavros doctor
+```
+
+Per-command options and examples:
+
+```bash
+kavros help <command>
+```
+
+Send a policy-bound request:
+
+```bash
+kavros request \
+  --action post_data \
+  --target "https://api.example.com/v1/run" \
+  --content '{"input":"hello"}' \
+  --header 'content-type:application/json' \
+  --json
+```
+
+Fetch an approved URL:
+
+```bash
+kavros request --action get --target "https://docs.example.com" --json
+```
+
+The CLI sends credentials as headers and supports the same JSON contract used by
+native clients. It is useful for smoke tests, scripts, jobs, and applications
+that do not yet have a native Kavros SDK.
+
+Forwarded headers are evaluated against the workload policy like any other
+request content; the CLI warns when a header looks like credentials
+(`Authorization`, `Cookie`, or `x-kavros-*`).
+
+### When a request is blocked
+
+A block is a governed outcome, not a malfunction. The CLI prints the policy
+reason plus a plain-language explanation: what happened, whether the content
+reached the outside world (blocked requests never do), and what to do next.
+The same explanation is available standalone:
+
+```bash
+kavros explain 403 --body '{"error":"Blocked by Kavros","reason":"…"}'
+```
+
+### Verify a signed workflow bundle locally
+
+Before importing a workflow bundle exported from another deployment, verify its
+Ed25519 signature against the trusted public key (`CP_POLICY_PUBLIC_KEY` from
+provisioning) — the same check the import route performs, run on your machine,
+often offline:
+
+```bash
+kavros verify-bundle workflow.kavros-bundle.json \
+  --public-key "$CP_POLICY_PUBLIC_KEY"
+```
+
+The key defaults to `KAVROS_POLICY_PUBLIC_KEY`, then `CP_POLICY_PUBLIC_KEY`,
+from the environment. Output names the workflow, revision, origin deployment,
+pinned capabilities, and a fingerprint of the key that verified the signature —
+suitable for pasting into a change record. A tampered or foreign-signed bundle
+exits non-zero with instructions not to import.
+
+## Development
+
+```bash
+npm test
+node bin/kavros.mjs --help
+```
+
+The CLI has no runtime dependencies and supports Node.js 18 and newer. The
+printed version is read from `package.json` at runtime.
+
+## Releasing
+
+Releases use npm Trusted Publishing (GitHub Actions OIDC) — no stored npm
+token, and every published package carries a sigstore provenance attestation.
+
+One-time setup on npmjs.com under the package's **Settings → Trusted
+Publisher**:
+
+- Provider: GitHub Actions
+- Organization or user: `Kavrosai`
+- Repository: `cli`
+- Workflow filename: `publish.yml`
+- Allowed action: npm publish
+
+To release a new version, update `version` in `package.json`, commit, then push
+a matching tag — the workflow rejects a tag that does not match:
+
+```bash
+git tag v0.2.3
+git push origin v0.2.3
+```
+
+Fallback until Trusted Publishing is configured: add an npm granular access
+token with publish permission for `@kavrosai/cli` and **bypass 2FA** enabled
+as the `NPM_TOKEN` Actions secret. The workflow then publishes without
+provenance (`EOTP` failures in Actions mean 2FA bypass was not enabled).
+Provenance requires a public source repository, so Trusted Publishing is the
+long-term path. Remove the `NPM_TOKEN` secret once a tagged release has
+published through OIDC.
+
+npm does not allow re-publishing an existing package version; if a tag was
+already published successfully, bump the version instead of retrying.
+
+## License
+
+[MIT](LICENSE)

package/bin/kavros.mjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { readFileSync } from "node:fs";
+import {
+  config,
+  parseArgs,
+  parseContent,
+  parseHeaders,
+  requireConfig,
+  sensitiveHeaders,
+} from "../lib/args.mjs";
+import { verifyBundle } from "../lib/bundle.mjs";
+import { explainFailure } from "../lib/explain.mjs";
+import { readFile } from "node:fs/promises";
+
+const { version: VERSION } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+function usage() {
+  console.log(`Kavros CLI ${VERSION}
+
+Language-agnostic tools for protected workload egress.
+
+Usage:
+  kavros request --action <action> --target <url> [--content <json|string>]
+  kavros doctor
+  kavros verify-bundle <file> [--public-key <base64>]
+  kavros explain <http-status> [--body <json>]
+  kavros help <command>
+  kavros --version
+  kavros --help
+
+Commands:
+  request        Send a policy-bound request through the data plane
+  doctor         Check connectivity and workload configuration
+  verify-bundle  Verify a signed workflow bundle's Ed25519 signature locally
+  explain        Plain-language meaning of a governed-request failure
+
+Environment:
+  KAVROS_API_URL             Data-plane egress URL
+  KAVROS_API_KEY             Workload API key
+  KAVROS_AGENT_ID            Workload ID
+  KAVROS_POLICY_PUBLIC_KEY   Trusted public key for verify-bundle (optional)
+
+Run 'kavros help <command>' for command-specific options and examples.
+
+Examples:
+  kavros doctor
+  kavros request --action post_data --target https://api.example.com/v1/run \\
+    --content '{"input":"hello"}'
+  kavros verify-bundle workflow.kavros-bundle.json
+`);
+}
+
+function commandHelp(command) {
+  const pages = {
+    request: `kavros request — send a policy-bound request through the data plane
+
+The request is evaluated against the workload's signed policy: identity,
+allowlist, DLP, and metering. A block is a governed outcome, not an error —
+use \`kavros explain\` or the failure footer for what to do next.
+
+Required:
+  --action <action>     e.g. get or post_data (per the workload's policy)
+  --target <url>        the approved upstream URL
+
+Options:
+  --content <json|string>   request body
+  --header <name:value>     forward a header (repeatable; credential-like
+                            headers warn)
+  --json                    formatted JSON output
+  --timeout <seconds>       request timeout (default: 120)
+
+Environment: KAVROS_API_URL, KAVROS_API_KEY, KAVROS_AGENT_ID
+
+Examples:
+  kavros request --action get --target https://docs.example.com --json
+  kavros request --action post_data --target https://api.example.com/v1/run \\
+    --content '{"input":"hello"}'
+`,
+    doctor: `kavros doctor — check connectivity and workload configuration
+
+Verifies that the data plane is reachable and the configured workload
+identity is accepted. Requires the same environment as request.
+
+Environment: KAVROS_API_URL, KAVROS_API_KEY, KAVROS_AGENT_ID
+
+Example:
+  kavros doctor
+`,
+    "verify-bundle": `kavros verify-bundle — verify a signed workflow bundle locally
+
+Checks the Ed25519 signature on a bundle exported from a control plane
+against a trusted public key. This is the same verification the import
+route performs, run on your machine — useful before importing a bundle
+and for security review. Works offline; no deployment connection needed.
+
+Usage:
+  kavros verify-bundle <file> [--public-key <base64>]
+
+Options:
+  --public-key <base64>  Trusted public key (SPKI DER or raw32 base64).
+                         Falls back to KAVROS_POLICY_PUBLIC_KEY, then
+                         CP_POLICY_PUBLIC_KEY.
+  --json                 Print the verification result as JSON
+
+The key to trust is the CP_POLICY_PUBLIC_KEY value provisioning shares
+between the exporting and importing deployments.
+
+Examples:
+  kavros verify-bundle workflow.kavros-bundle.json
+  kavros verify-bundle bundle.json --public-key "MCowBQYDK2VwAyEA…"
+`,
+    explain: `kavros explain — plain-language meaning of a governed failure
+
+Turns a data-plane status/body into what happened, whether egress was
+reached, and what to do next. Also prints automatically when a request
+fails (unless --json is set).
+
+Usage:
+  kavros explain <http-status> [--body '<json>']
+
+Examples:
+  kavros explain 403 --body '{"error":"Blocked by Kavros","reason":"DLP rule matched"}'
+  kavros explain 429
+`,
+  };
+  const page = pages[command];
+  if (!page) {
+    console.error(`kavros: no help for "${command}". Commands: request, doctor, verify-bundle, explain.`);
+    process.exitCode = 2;
+    return;
+  }
+  console.log(page);
+}
+
+function fail(message, code = 2) {
+  console.error(`kavros: ${message}`);
+  process.exitCode = code;
+}
+
+async function fetchWithTimeout(url, init, timeoutSeconds) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function readBody(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function printBody(body, formatted) {
+  if (typeof body === "string") console.log(body);
+  else console.log(JSON.stringify(body ?? {}, null, formatted ? 2 : 0));
+}
+
+async function request(options) {
+  const values = requireConfig();
+  if (!options.action) throw new Error("request requires --action");
+  if (!options.target) throw new Error("request requires --target");
+
+  const upstreamHeaders = parseHeaders(options.headers);
+  for (const name of sensitiveHeaders(upstreamHeaders)) {
+    console.error(`kavros: warning: forwarding sensitive header "${name}" to the upstream target; omit it unless the target requires it`);
+  }
+  const headers = {
+    Authorization: `Bearer ${values.apiKey}`,
+    "X-Kavros-Agent-ID": values.agentId,
+    "Content-Type": "application/json",
+  };
+  const payload = {
+    action: options.action,
+    target: options.target,
+    content: parseContent(options.content),
+    headers: upstreamHeaders,
+  };
+  const timeoutSeconds = Number(options.timeout ?? 120);
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) throw new Error("--timeout must be a positive number");
+
+  let response;
+  try {
+    response = await fetchWithTimeout(values.url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+    }, timeoutSeconds);
+  } catch (error) {
+    throw new Error(`data-plane request failed: ${error.name === "AbortError" ? "timed out" : error.message}`);
+  }
+
+  const body = await readBody(response);
+  if (!response.ok) {
+    printBody(body, true);
+    if (!options.json) {
+      const explanation = explainFailure({ status: response.status, body });
+      console.error(`\nWhat happened: ${explanation.headline}`);
+      console.error(`Egress: ${explanation.egress}`);
+      console.error("Next steps:");
+      for (const step of explanation.next) console.error(`  - ${step}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  printBody(body, options.json);
+}
+
+async function verifyBundleCommand(options) {
+  const file = options._[1];
+  if (!file) throw new Error("verify-bundle requires a bundle file path");
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    throw new Error(`cannot read bundle file: ${file}`);
+  }
+  let signed;
+  try {
+    signed = JSON.parse(raw);
+  } catch {
+    throw new Error("the bundle file is not valid JSON");
+  }
+  const publicKeyBase64 = options["public-key"];
+  const result = verifyBundle(signed, { publicKey: publicKeyBase64 });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    const s = result.summary;
+    console.log(`Signature valid (Ed25519, key ${s.signature_key_fingerprint}).`);
+    console.log(`Workflow: ${s.workflow} (revision ${s.revision ?? "?"})`);
+    console.log(`Exported: ${s.exported_at ?? "unknown"}${s.origin_deployment ? ` from deployment ${s.origin_deployment}` : ""}`);
+    if (s.capabilities.length === 0) {
+      console.log("Capabilities: none");
+    } else {
+      console.log("Capabilities:");
+      for (const c of s.capabilities) {
+        const columns = c.approved_columns > 0 ? `, ${c.approved_columns} approved column(s)` : "";
+        console.log(`  - ${c.key} v${c.version ?? "?"}${c.source ? ` (${c.source}${columns})` : ""}`);
+      }
+    }
+    console.log("Safe to import: the bundle matches the deployment key you trust.");
+  } else {
+    console.error(`Signature verification FAILED: ${result.reason}`);
+    console.error("Do not import this bundle. Re-export from the source deployment or confirm the trusted key with the sender.");
+    process.exitCode = 1;
+  }
+}
+
+function explainCommand(options) {
+  const status = Number(options._[1]);
+  if (!Number.isInteger(status) || status < 100) throw new Error("explain requires an HTTP status, e.g. kavros explain 403");
+  let body;
+  if (options.body) {
+    try {
+      body = JSON.parse(options.body);
+    } catch {
+      body = options.body;
+    }
+  }
+  const explanation = explainFailure({ status, body });
+  console.log(`What happened: ${explanation.headline}`);
+  console.log(`Egress: ${explanation.egress}`);
+  console.log("Next steps:");
+  for (const step of explanation.next) console.log(`  - ${step}`);
+}
+
+async function doctor() {
+  const values = config();
+  const missing = [];
+  if (!values.url) missing.push("KAVROS_API_URL");
+  if (!values.apiKey) missing.push("KAVROS_API_KEY");
+  if (!values.agentId) missing.push("KAVROS_AGENT_ID");
+  if (missing.length > 0) {
+    console.error(`Missing environment variables: ${missing.join(", ")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let response;
+  try {
+    const healthUrl = new URL(values.url);
+    healthUrl.pathname = "/health";
+    healthUrl.search = "";
+    response = await fetchWithTimeout(healthUrl, {
+      headers: {
+        Authorization: `Bearer ${values.apiKey}`,
+        "X-Kavros-Agent-ID": values.agentId,
+      },
+    }, 10);
+  } catch (error) {
+    console.error(`Data plane unreachable: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const body = await readBody(response);
+  if (!response.ok) {
+    console.error(`Data plane health check failed (HTTP ${response.status})`);
+    printBody(body, true);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Data plane reachable${body?.build_sha ? ` (build ${body.build_sha})` : ""}.`);
+  console.log(`Workload identity configured: ${values.agentId}`);
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.version) {
+      console.log(VERSION);
+      return;
+    }
+    if (options.help || options._[0] === undefined) {
+      usage();
+      return;
+    }
+    const [command] = options._;
+    if (options.help && command && command !== "help") {
+      commandHelp(command);
+      return;
+    }
+    if (command === "request") await request(options);
+    else if (command === "doctor") await doctor();
+    else if (command === "verify-bundle") await verifyBundleCommand(options);
+    else if (command === "explain") explainCommand(options);
+    else if (command === "help" && options._[1]) commandHelp(options._[1]);
+    else throw new Error(`unknown command ${command ?? ""}; run kavros --help`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+await main();

package/lib/args.mjs

@@ -0,0 +1,84 @@
+// Pure argument and configuration helpers for the Kavros CLI. Kept free of
+// I/O so the test suite can exercise them without network or environment setup.
+
+export function parseArgs(argv) {
+  const options = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("-")) {
+      options._.push(value);
+      continue;
+    }
+    if (value === "--help" || value === "-h") options.help = true;
+    else if (value === "--version" || value === "-v") options.version = true;
+    else if (value === "--json") options.json = true;
+    else if (value === "--action" || value === "--target" || value === "--content" || value === "--header" || value === "--timeout" || value === "--public-key" || value === "--body") {
+      const next = argv[index + 1];
+      if (!next || next.startsWith("-")) throw new Error(`${value} requires a value`);
+      index += 1;
+      if (value === "--header") {
+        options.headers ??= [];
+        options.headers.push(next);
+      } else {
+        options[value.slice(2)] = next;
+      }
+    } else {
+      throw new Error(`unknown option: ${value}`);
+    }
+  }
+  return options;
+}
+
+export function config() {
+  return {
+    url: process.env.KAVROS_API_URL,
+    apiKey: process.env.KAVROS_API_KEY,
+    agentId: process.env.KAVROS_AGENT_ID,
+  };
+}
+
+export function requireConfig(values = config()) {
+  const missing = missingConfig(values);
+  if (missing.length > 0) {
+    throw new Error(`missing ${missing.join(", ")}; configure the workload environment first`);
+  }
+  return values;
+}
+
+/** Environment names that are unset, in config order — for the explain path. */
+export function missingConfig(values = config()) {
+  return Object.entries(values)
+    .filter(([, value]) => !value)
+    .map(([key]) => key === "url" ? "KAVROS_API_URL" : key === "apiKey" ? "KAVROS_API_KEY" : "KAVROS_AGENT_ID");
+}
+
+export function parseHeaders(values = []) {
+  const headers = {};
+  for (const value of values) {
+    const separator = value.indexOf(":");
+    if (separator < 1) throw new Error(`invalid --header value ${JSON.stringify(value)}; use name:value`);
+    headers[value.slice(0, separator).trim()] = value.slice(separator + 1).trim();
+  }
+  return headers;
+}
+
+export function parseContent(value) {
+  if (value === undefined) return "";
+  try {
+    return JSON.stringify(JSON.parse(value));
+  } catch {
+    return value;
+  }
+}
+
+// Headers that should never be blindly forwarded to the upstream target:
+// workload credentials (x-kavros-*), end-user credentials, and the Host
+// header, which the upstream connection must derive itself.
+const SENSITIVE_HEADER_NAMES = new Set(["authorization", "cookie", "host"]);
+
+export function sensitiveHeaders(headers) {
+  return Object.keys(headers).filter((name) => {
+    const lower = name.toLowerCase();
+    return SENSITIVE_HEADER_NAMES.has(lower) || lower.startsWith("x-kavros-");
+  });
+}

package/lib/bundle.mjs

@@ -0,0 +1,142 @@
+// Signed workflow-bundle verification for the Kavros CLI. Pure functions,
+// no dependencies beyond Node's crypto — mirrors the control plane's
+// lib/workflowBundle.ts (canonical JSON + Ed25519 over the canonical bytes)
+// so "trust us" becomes "run kavros verify-bundle" locally, including on
+// machines that never talk to a deployment.
+
+import crypto from "node:crypto";
+
+const BUNDLE_FORMAT = "kavros-workflow-bundle";
+const BUNDLE_FORMAT_VERSION = 2;
+
+/** Deterministic JSON with recursively sorted keys — byte-identical to the
+ * control plane's canonical form, which is what the signature covers. */
+export function canonicalJson(value) {
+  const seen = new WeakSet();
+  const walk = (node) => {
+    if (node === null || typeof node !== "object") return node;
+    if (Array.isArray(node)) return node.map(walk);
+    if (seen.has(node)) throw new Error("Cannot canonicalize a bundle with reference cycles.");
+    seen.add(node);
+    const out = {};
+    for (const key of Object.keys(node).sort()) {
+      out[key] = walk(node[key]);
+    }
+    return out;
+  };
+  return JSON.stringify(walk(value));
+}
+
+/**
+ * Verify a signed bundle against a trusted public key.
+ *
+ * @param {object} signed  Parsed bundle file: { bundle, signature, algorithm? }
+ * @param {object} options
+ * @param {string} [options.publicKey]  Base64 SPKI DER or raw32 Ed25519 key
+ *   (the CP_POLICY_PUBLIC_KEY value provisioning shares between deployments).
+ *   Falls back to KAVROS_POLICY_PUBLIC_KEY / CP_POLICY_PUBLIC_KEY env vars.
+ * @param {string} [options.expectedWorkflow]  When set, fails if the bundle is
+ *   for a different workflow name (guards against swapping files).
+ * @returns {{ ok: boolean, reason?: string, summary?: object }}
+ */
+export function verifyBundle(signed, options = {}) {
+  if (!signed || typeof signed !== "object") {
+    return { ok: false, reason: "Not a signed bundle file — expected a JSON object." };
+  }
+  if (signed.algorithm !== "ed25519") {
+    return {
+      ok: false,
+      reason: `Unsupported signature algorithm: ${signed.algorithm ?? "none"}. Kavros bundles are Ed25519-signed; this file may not be a bundle export.`,
+    };
+  }
+  const publicKeyBase64 = options.publicKey ?? process.env.KAVROS_POLICY_PUBLIC_KEY ?? process.env.CP_POLICY_PUBLIC_KEY;
+  if (!publicKeyBase64) {
+    return {
+      ok: false,
+      reason: "No trusted public key supplied. Pass --public-key <base64> or set KAVROS_POLICY_PUBLIC_KEY (the CP_POLICY_PUBLIC_KEY value from provisioning).",
+    };
+  }
+  const bundle = signed.bundle;
+  if (
+    !bundle ||
+    typeof bundle !== "object" ||
+    bundle.format !== BUNDLE_FORMAT ||
+    bundle.format_version !== BUNDLE_FORMAT_VERSION ||
+    !bundle.workflow ||
+    typeof bundle.workflow.name !== "string"
+  ) {
+    return { ok: false, reason: "Not a valid Kavros workflow bundle (missing format markers or workflow name)." };
+  }
+  if (typeof signed.signature !== "string" || signed.signature.length === 0) {
+    return { ok: false, reason: "The bundle file has no signature." };
+  }
+
+  let publicKey;
+  try {
+    const der = Buffer.from(publicKeyBase64, "base64");
+    try {
+      publicKey = crypto.createPublicKey({ key: der, format: "der", type: "spki" });
+    } catch {
+      if (der.length !== 32) {
+        return { ok: false, reason: `The supplied public key is neither SPKI DER nor raw32 Ed25519 (${der.length} bytes).` };
+      }
+      publicKey = crypto.createPublicKey({
+        key: { kty: "OKP", crv: "Ed25519", x: der.toString("base64url") },
+        format: "jwk",
+      });
+    }
+  } catch {
+    return { ok: false, reason: "The supplied public key could not be parsed." };
+  }
+
+  let canonical;
+  try {
+    canonical = canonicalJson(bundle);
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : "Unserializable bundle." };
+  }
+
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(canonical, "utf8"), publicKey, Buffer.from(signed.signature, "base64"));
+  } catch {
+    ok = false;
+  }
+  if (!ok) {
+    return {
+      ok: false,
+      reason: "Signature verification failed — the bundle was modified after signing or was signed by a different deployment.",
+    };
+  }
+
+  if (options.expectedWorkflow && bundle.workflow.name !== options.expectedWorkflow) {
+    return {
+      ok: false,
+      reason: `Signature is valid, but this bundle is for workflow "${bundle.workflow.name}", not "${options.expectedWorkflow}".`,
+    };
+  }
+
+  const capabilities = Array.isArray(bundle.capabilities) ? bundle.capabilities : [];
+  return {
+    ok: true,
+    summary: {
+      workflow: bundle.workflow.name,
+      revision: bundle.workflow.revision,
+      exported_at: bundle.exported_at,
+      origin_deployment: bundle.origin?.deployment_id ?? null,
+      capabilities: capabilities.map((c) => ({
+        key: c.key,
+        version: c.version,
+        source: c.source,
+        approved_columns: Array.isArray(c.approved_columns) ? c.approved_columns.length : 0,
+      })),
+      signature_key_fingerprint: fingerprint(publicKey),
+    },
+  };
+}
+
+/** Short SHA-256 fingerprint of the verifying public key, for audit notes. */
+export function fingerprint(publicKey) {
+  const der = publicKey.export({ format: "der", type: "spki" });
+  return `sha256:${crypto.createHash("sha256").update(der).digest("hex").slice(0, 16)}`;
+}

package/lib/explain.mjs

@@ -0,0 +1,123 @@
+// Plain-language error explanation for CLI failures — the plan's rule that a
+// failure sentence must say what happened, whether egress was reached, and
+// what to do next. Pure: maps known API/error payloads to human guidance.
+
+/**
+ * Build an operator-readable explanation for a failed governed request.
+ *
+ * @param {object} params
+ * @param {number} [params.status]          HTTP status of the data-plane reply
+ * @param {object|string|null} [params.body] Parsed response body (or text)
+ * @param {string[]} [params.configMissing] Missing env var names, if config failed
+ * @returns {{ headline: string, egress: string, next: string[] }}
+ */
+export function explainFailure({ status, body, configMissing = [] } = {}) {
+  if (configMissing.length > 0) {
+    return {
+      headline: "This shell has no workload credentials configured.",
+      egress: "Nothing was sent — no egress was attempted.",
+      next: [
+        "Export the three variables from your workload's provisioning page:",
+        "  export KAVROS_API_URL=\"https://<data-plane-host>/api/agent/egress\"",
+        "  export KAVROS_API_KEY=\"<workload-api-key>\"",
+        "  export KAVROS_AGENT_ID=\"<workload-id>\"",
+        "Then run `kavros doctor` to confirm connectivity.",
+      ],
+    };
+  }
+
+  const reason =
+    typeof body === "object" && body !== null
+      ? body.reason ?? body.error ?? null
+      : typeof body === "string" && body
+        ? body
+        : null;
+  const blocked = typeof body === "object" && body !== null && body.error === "Blocked by Kavros";
+
+  if (blocked) {
+    return {
+      headline: `Blocked by policy${reason ? ` — ${reason}` : "."}`,
+      egress: "The request was stopped at the data plane. Nothing reached the target, and blocked content is never forwarded or stored.",
+      next: [
+        "Read the reason above: it names the violated rule (DLP match, unapproved target, or identity state).",
+        "If the target is legitimate, ask your admin to add it to the workload's signed policy — do not bypass the data plane.",
+        "Run `kavros doctor` to rule out an identity problem (halted or revoked workloads also block).",
+      ],
+    };
+  }
+
+  if (status === 401 || status === 403) {
+    return {
+      headline: "Your workload identity was rejected.",
+      egress: "The data plane refused the credentials before any policy evaluation — nothing was sent onward.",
+      next: [
+        "Check that KAVROS_API_KEY and KAVROS_AGENT_ID belong to the same registered workload.",
+        "The workload may be halted or revoked — an admin can check its state in the Agent Registry.",
+        "If the key was rotated, fetch the current key from the control plane and re-export it.",
+      ],
+    };
+  }
+
+  if (status === 404) {
+    return {
+      headline: "The data plane does not recognize this workload or route.",
+      egress: "Nothing was forwarded — the request stopped at the data plane.",
+      next: [
+        "Confirm KAVROS_API_URL points at the data-plane egress endpoint (…/api/agent/egress), not the control plane UI.",
+        "Confirm KAVROS_AGENT_ID matches a workload registered on this deployment.",
+      ],
+    };
+  }
+
+  if (status === 429) {
+    return {
+      headline: "Rate or quota limit reached.",
+      egress: "The request was refused at the data plane; nothing was sent onward.",
+      next: [
+        "Wait for the current window to reset, or ask your admin to raise the workload's quota.",
+        "Repeated 429s are visible in Usage — an admin can identify which workload is consuming the budget.",
+      ],
+    };
+  }
+
+  if (status === 502 || status === 504) {
+    return {
+      headline: "The approved upstream target could not be reached.",
+      egress: "Policy checks passed, but the target itself failed or timed out after egress was attempted.",
+      next: [
+        "This is a target-side failure, not a policy denial — retry or check the target service's health.",
+        "If it persists, verify the target URL in the workload's policy matches a healthy endpoint.",
+      ],
+    };
+  }
+
+  if (status === 500 || status === 503) {
+    return {
+      headline: "The data plane reported an internal error.",
+      egress: "The request failed inside the data plane; depending on the stage, egress may not have been attempted.",
+      next: [
+        "Retry once, then check the deployment's health page or contact the operator.",
+        "Include the request timestamp in any report — data-plane logs are audit-linked.",
+      ],
+    };
+  }
+
+  if (status !== undefined) {
+    return {
+      headline: `The data plane returned HTTP ${status}.`,
+      egress: status >= 500 ? "A server-side failure occurred." : "The request was refused before egress.",
+      next: ["Run `kavros doctor` to verify connectivity and identity, then retry."],
+    };
+  }
+
+  return {
+    headline: reason ? `Request failed — ${reason}` : "Request failed.",
+    egress: "The failure occurred before a verdict was reached; treat the target as unreached.",
+    next: ["Run `kavros doctor` to verify connectivity and identity, then retry."],
+  };
+}
+
+/** One-line summary for scripts/CI: headline only, no advice. */
+export function explainOneLine(explanation) {
+  return explanation.headline;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kavrosai/cli",
+  "version": "0.3.0",
+  "description": "Language-agnostic CLI for Kavros workload egress and diagnostics",
+  "type": "module",
+  "bin": {
+    "kavros": "bin/kavros.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "kavros",
+    "ai",
+    "llm",
+    "agents",
+    "security",
+    "egress",
+    "dlp",
+    "policy"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kavrosai/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Kavrosai/cli/issues"
+  },
+  "homepage": "https://kavros.xyz"
+}