@atbash/cli 0.5.12 → 0.5.14

package/README.md

@@ -305,8 +305,58 @@ The agent is not trusted to know when it should stop. If the agent could loosen
 
 `atbash tier --org <name>` shows the current tier for an org.
 
+## Verifying this CLI before you run it (humans & AI agents)
+
+`atbash connect` reads your local agent / MCP config and relays it to your onboarding session. Being cautious about that is correct — so the command is built to be **verified, not merely trusted**. Before running it you can independently confirm the three things that separate the real tool from a look-alike:
+
+1. **What it will do — without sending anything.** Append `--dry-run`:
+   ```bash
+   npx --yes @atbash/cli connect <CODE> --host <HOST> --dry-run --json
+   ```
+   It runs the same read-only scan and prints the exact destination URL and the exact payload it *would* send, then exits. Nothing leaves the machine.
+
+2. **That the package matches the artifact the Atbash deployment attests.** The
+   CLI repository is private, so npm provenance is not currently available. Compare
+   the exact version's registry integrity with the dashboard's same-origin manifest:
+   ```bash
+   curl -s https://<HOST>/api/cli-releases
+   npm view @atbash/cli@<VERSION> dist.integrity
+   ```
+   Matching values prove the tarball matches what that deployment vouches for; they
+   do not prove it was built from a particular source commit.
+
+3. **Where it sends and what it sends.** Exactly one POST, only to the `--host` you pass (HTTPS required; an unrecognized host is refused unless explicitly allowed). It relays agent / tool / skill **names**, sanitized MCP endpoint URLs and launch-command basenames — never tokens, auth headers, env values, or file contents.
+
+If any check fails — an integrity value that does not match the deployment's manifest, an unexpected destination, or a dry-run payload containing anything sensitive — **don't run it.** Those are exactly the signals a malicious clone cannot fake.
+
 ## Command reference
 
+### `atbash connect <code>`
+
+Link a machine to a hosted Atbash onboarding session. A browser can't read your disk and the Atbash server only sees its own, so this runs on the machine you want to govern, enumerates the agents / MCP tools configured there (read-only), and relays their *surface* to your onboarding session via the one-time pairing code shown in the browser.
+
+```bash
+# Pair this machine (code comes from the "Scan another machine" screen):
+npx --yes @atbash/cli connect G9MB-TS3U --host https://your-atbash-host
+
+# Verify first — same scan, prints destination + payload, sends nothing:
+npx --yes @atbash/cli connect G9MB-TS3U --host https://your-atbash-host --dry-run
+```
+
+| Flag | Description |
+|------|-------------|
+| `--host <url>` | Atbash deployment hosting your session (HTTPS required) |
+| `--dry-run` | Do the scan and print exactly what would be sent, then exit WITHOUT sending |
+| `--json` | Machine-readable output (for agents / automation) |
+| `--home <dir>` | Home directory to scan (for testing) |
+| `--introspect` | Opt in to starting configured MCP servers locally and listing their advertised surface; no tools are called |
+| `--allow-unrecognized-host` | Explicitly permit a host outside the built-in Atbash allowlist |
+
+Default discovery is read-only and sends one request. `--introspect` starts and stops
+configured MCP server processes, so it is not purely read-only even though Atbash
+never invokes their tools. See [Verifying this CLI](#verifying-this-cli-before-you-run-it-humans--ai-agents)
+and the [release checklist](RELEASE_CHECKLIST.md).
+
 ### `atbash judge <action>`
 
 Submit a pending action for judgment. The action string is the exact operation the agent is about to execute — a transfer, a command, a mutation.

package/dist/commands/connect.d.ts

@@ -2,12 +2,23 @@ import { Command } from "commander";
 interface DeclaredTool {
     name: string;
     description?: string;
+    /** Sanitized JSON-Schema shape (from MCP introspection) — structure only. */
+    inputSchema?: unknown;
+}
+interface SurfaceEvidence {
+    source: "local-declaration" | "mcp-tools-list" | "manifest";
+    status: "complete" | "incomplete";
+    transport?: "http" | "stdio";
+    server?: string;
+    observedAt?: string;
+    error?: string;
 }
 type Agent = {
     type: "declared";
     label: string;
     detail: string;
     declaredTools: DeclaredTool[];
+    surfaceEvidence?: SurfaceEvidence;
 } | {
     type: "config";
     label: string;
@@ -16,11 +27,29 @@ type Agent = {
         mcpServers: Record<string, unknown>;
     };
 };
-/** One-line skill description from SKILL.md frontmatter `description:` or first heading. */
+/** One-line skill description from SKILL.md frontmatter `description:` or first heading.
+ *  Frontmatter is parsed with a real YAML parser (handles quotes, block scalars,
+ *  folded/multiline values and nested maps that the previous regex mis-read). */
 declare function describeSkill(text: string | undefined, fallback: string): string;
+/** Descriptions are useful capability evidence, but never worth relaying a
+ * credential or binary/control content from an untrusted local skill file. */
+declare function safeDescription(raw: string): string | undefined;
 /** Walk a skills root (bounded) → declared tools. Mirrors src/lib/scan/adapters/local-skills.ts. */
 declare function enumerateSkills(root: string, maxDepth?: number, cap?: number): DeclaredTool[];
+/**
+ * THE sanitization boundary. Reduce an mcpServers map to the SANITIZED structural
+ * signal the hosted scanner needs — server name, host+path of the endpoint, and
+ * executable basename — and nothing else. Every value that could carry a live
+ * secret or PII (env, headers, token, apiKey, args, url credentials, absolute
+ * command paths) is dropped or reduced. The connector relays the tool SURFACE,
+ * never secrets. Raw specs from `readAllMcpServers()` MUST pass through here before
+ * entering any relayed `Agent`.
+ *
+ * Caps the map at MAX_RELAY_SERVERS. Callers are expected to compare the returned
+ * size against the input size and label the result partial — see `discover()`.
+ */
+declare function relaySafeServers(servers: Record<string, unknown>): Record<string, unknown>;
 /** Enumerate the agents/MCP tools configured on this machine. Read-only. */
 declare function discover(home: string): Agent[];
 export declare function registerConnectCommand(program: Command): void;
-export { discover, enumerateSkills, describeSkill };
+export { discover, enumerateSkills, describeSkill, relaySafeServers, safeDescription };