@scopebond/hook 0.10.0 → 0.12.0

package/README.md

@@ -200,7 +200,20 @@ portal's **Connect** step (it gives you a one-use enrollment bundle), save it as
 npx @scopebond/hook connect https://<your-workspace> scopebond-enrollment.json
 ```
 
-In Windows PowerShell, use `npx.cmd` instead of `npx` if script execution policy blocks `npx.ps1`; no execution-policy change is needed. Enrollment registers both the gateway attester and the hook's separate agent signing key with proof of possession, so Cloud can verify authenticated receipts.
+In Windows PowerShell, use `npx.cmd` instead of `npx` if script execution policy blocks `npx.ps1`; no execution-policy change is needed. Every command the hook prints for you to run uses `npx.cmd` on Windows.
+
+### Is it delivering?
+
+`status` shows when this computer last delivered records, how many are waiting to send and the
+last problem. Records are never dropped from the queue while they wait: a long outage only makes
+the queue longer. If the workspace refuses this computer's connection (it was revoked, replaced or
+removed), `status` says **NOT DELIVERING** with the time it stopped and the one command that fixes
+it, which is signing in again. `doctor` also checks that the workspace still accepts the connection,
+not only that it is reachable, and fails when it does not.
+
+Signing in puts the hook in your user-level agent settings (`~/.claude/settings.json`, `~/.cursor/hooks.json` or `~/.codex/hooks.json`), so every project on this computer is checked; `--project` connects one project instead. Signing in again never rewrites a settings file that already holds the right hook entry.
+
+Enrollment registers both the gateway attester and the hook's separate agent signing key with proof of possession, so Cloud can verify authenticated receipts.
 
 `connect` does the whole setup in one command: it scaffolds `.scopebond/` if needed,
 enrolls this machine's countersigning key, stores a scoped machine credential in
@@ -216,6 +229,19 @@ locally and retried if the workspace is unreachable. `npx @scopebond/hook flush`
 delivers anything still queued — run it on a session-end hook (and set
 `SCOPEBOND_HOOK_FLUSH_MS=0`) if you want zero per-call latency.
 
+**Reconnecting.** Run `login` again from any folder: unless that folder has its own project
+setup, it repairs the connection the hook actually uses (usually the user-level one) instead
+of creating a second one; pass `--project` to set up the folder you are in. If the workspace
+no longer accepts this computer's countersigning key (the computer was replaced or
+disconnected there), `login` replaces the key and keeps the old one in
+`.scopebond/retired-keys/`.
+
+**Records signed by an earlier key.** The new connection cannot deliver records the earlier
+key signed, so they leave the delivery queue but stay in the local log.
+`npx @scopebond/hook recover` asks the workspace to accept them, waits while an owner or
+admin approves it there, then sends them; the workspace checks each signature against the
+key it kept and labels the records as recovered.
+
 ### Rules set by your workspace
 
 A connected computer keeps its own rules (`.scopebond/rules.json`) until someone who manages

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgqBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmqBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}

package/dist/cli.js

@@ -40,7 +40,8 @@ import { openObservations, describeObservations, observationStatus, stopReasonFr
 import { OBSERVATION_DB, ObservationStore } from "./obs-store.js";
 import { loadOrCreateBindingKey } from "./observation.js";
 import { uploadPending } from "./obs-upload.js";
-import { connectCloud, loadConnection } from "./cloud.js";
+import { connectCloud, ingestUrl, loadConnection } from "./cloud.js";
+import { recoverEarlierReceipts } from "./recover.js";
 import { loadPolicyExport, policyBuilds } from "./policy-load.js";
 import { isManaged, readMeta, MANAGED_DOC_FILE } from "./managed.js";
 import { syncIfDue, syncPolicy } from "./policy-sync.js";
@@ -51,6 +52,8 @@ import { runDispatchCommand } from "./dispatch-cli.js";
 import { describeAction } from "./explain.js";
 import { ensureDurableRuntime, pinnedCliPath, isEphemeralPath } from "./runtime-install.js";
 import { cliCommand, hookCommand, hookVersion } from "./version.js";
+import { recordRulesCredential } from "./delivery-state.js";
+import { describeDelivery } from "./delivery-report.js";
 import { computeManifest, renderManifest } from "./capabilities.js";
 import { runProofFixtures, loadProofs, saveProofs, proofPassed, deliverProofReceipts } from "./proof.js";
 import { fileURLToPath } from "node:url";
@@ -871,11 +874,11 @@ async function runConnect(args) {
     const bundleArg = positional[1];
     const harness = selectedHarness(args);
     if (!url) {
-        console.error(`usage: ${cliCommand("connect <workspace-url> <enrollment> [--claude|--cursor|--codex] [--no-install]")}`);
+        console.error(`usage: ${cliCommand("connect <workspace-url> <enrollment> [--claude|--cursor|--codex] [--no-install] [--project]")}`);
         console.error(enrollmentHelp);
         process.exit(1);
     }
-    const dir = configDir();
+    const dir = connectDir(args);
     // One command sets everything up: scaffold the key, attester and starter policy if
     // they do not exist, then enroll and persist the scoped machine credential. The
     // enrollment can be a file, an inline base64 blob (what the portal hands out) or
@@ -897,6 +900,10 @@ async function finishConnect(dir, url, bundle, harness, args) {
     try {
         const c = await connectCloud(dir, url, bundle);
         console.log(`✓ Connected to ${c.url}`);
+        if (c.rotatedFrom)
+            console.log(`✓ This computer's earlier key (${c.rotatedFrom}) was no longer accepted, so it was replaced; the old key is kept in ${join(dir, "retired-keys")}`);
+        if (c.setAside)
+            console.log(`  ${c.setAside.toLocaleString()} queued record(s) signed by an earlier key cannot go through this connection. To deliver them, run: ${cliCommand("recover")}`);
         // With a user-level install present, the hook ignores a project policy until it is
         // trusted, and would fall back to the user home, which holds no cloud.json: the agent
         // stays governed, but nothing reaches the workspace. Connecting this project is the
@@ -915,7 +922,14 @@ async function finishConnect(dir, url, bundle, harness, args) {
             console.log(`✓ ${harnessName(harness)} already configured in ${existing}`);
         }
         else if (!args.includes("--no-install")) {
-            const { file } = placeHook(harness, process.cwd(), undefined);
+            // A connection for this computer (the user home, the default) covers every project,
+            // so the hook goes into the user-level agent settings. Placing it in the current
+            // folder's project settings — what this did before — left every other project
+            // unchecked, and a sign-in run from a scratch folder governed only that folder.
+            // `--project` (a per-project connection) keeps the project placement.
+            const file = dir === userHome()
+                ? writeHarnessConfig(userHarnessFile(harness), harness, durableHookCommand(harness))
+                : placeHook(harness, process.cwd(), undefined).file;
             console.log(`✓ ${harnessName(harness)} configured in ${file}`);
             if (harness === "codex")
                 console.log(`\nOne last step: ${codexTrustStep}`);
@@ -959,6 +973,43 @@ const enrollmentHelp = [
     "Each enrollment is single-use and expires soon after it is created; if this one was",
     "used or has expired, create a new one there.",
 ].join("\n");
+/** Where `connect` and `login` write. A project someone set up here with `init` (it has a
+ *  policy) is connected, as before. Otherwise the configuration the hook itself uses from
+ *  here — usually the user-level install — so reconnecting from any folder repairs the
+ *  connection that is actually failing instead of creating a second, project-level one
+ *  beside it. `--project` asks for a new per-project setup explicitly. */
+function connectDir(args) {
+    const project = configDir();
+    return args.includes("--project") || existsSync(join(project, "policy.json")) ? project : resolveConfigDir(process.cwd());
+}
+/** `recover [--no-wait]`: deliver receipts that an earlier, since-revoked key of this computer
+ *  signed and the workspace never received, after an owner or admin approves it there. */
+async function runRecover(args) {
+    const dir = resolveConfigDir(process.cwd());
+    const connection = loadConnection(dir);
+    if (!connection) {
+        console.error(`not connected to a workspace; run \`${cliCommand("login <workspace-url>")}\` first`);
+        process.exit(1);
+    }
+    console.log(`Recovering from ${dir}`);
+    const result = await recoverEarlierReceipts(dir, connection, {
+        log: (line) => console.log(line),
+        fetch,
+        now: Date.now,
+        sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    }, { wait: !args.includes("--no-wait"), waitMs: 15 * 60_000, pollMs: 5_000 });
+    if (result.groups) {
+        const parts = [
+            `recovered ${result.accepted.toLocaleString()}`,
+            `already present ${result.duplicates.toLocaleString()}`,
+            `refused ${result.rejected.toLocaleString()}`,
+            ...(result.pending ? [`waiting for approval ${result.pending.toLocaleString()}`] : []),
+            ...(result.skipped ? [`skipped ${result.skipped.toLocaleString()}`] : []),
+        ];
+        console.log(`\nDone: ${parts.join(", ")}.`);
+    }
+    process.exitCode = result.failed || result.pending ? 1 : 0;
+}
 async function runFlush() {
     const dir = resolveConfigDir(process.cwd());
     if (!loadConnection(dir)) {
@@ -1180,7 +1231,7 @@ async function runObservations(args) {
     const emitter = opened.emitter;
     try {
         if (sub === "flush") {
-            const outcome = await uploadPending(emitter.store, { url: emitter.connection.url, credential: emitter.connection.credential, timeoutMs: 10_000 });
+            const outcome = await uploadPending(emitter.store, { url: ingestUrl(emitter.connection), credential: emitter.connection.credential, timeoutMs: 10_000 });
             const left = emitter.store.pendingSummary().count;
             console.log(`${outcome.result}: ${outcome.acknowledged} acknowledged, ${outcome.deferred} deferred, ${outcome.rejected} refused; ${left} still pending${outcome.detail ? ` (${outcome.detail})` : ""}`);
             process.exitCode = left > 0 ? 1 : 0;
@@ -1237,16 +1288,17 @@ function cliPath() {
 /** `install` — the once-per-machine, user-level install (SB112). Scaffolds the
  *  user home and registers the hook by absolute path in the user-level agent config,
  *  so every project a developer opens is governed without a per-repo `init`. */
+/** The command a user-level agent setting runs. Run through `npx`, this CLI lives in npm's
+ *  throwaway cache; registering that path would leave a hook that stops starting whenever
+ *  npm clears it — and a hook that cannot start lets every action through. Pin the durable
+ *  copy, as `init` does, and fall back to the portable `npx` command when none can be made. */
+function durableHookCommand(h) {
+    const pin = ensureDurableRuntime(cliPath(), hookVersion());
+    return pin.cli ? absoluteHookCommand(pin.cli, h) : hookCommand(h);
+}
 function runInstall(args) {
     const dir = userHome();
-    // Run through `npx`, this CLI lives in npm's throwaway cache; registering that path
-    // would leave a hook that stops starting whenever npm clears it — and a hook that
-    // cannot start lets every action through. Pin the durable copy, as `init` does, and
-    // fall back to the portable `npx` command when none can be made.
-    const commandFor = (h) => {
-        const pin = ensureDurableRuntime(cliPath(), hookVersion());
-        return pin.cli ? absoluteHookCommand(pin.cli, h) : hookCommand(h);
-    };
+    const commandFor = durableHookCommand;
     const harnessesFor = () => args.includes("--codex") ? ["codex"]
         : args.includes("--cursor") ? ["cursor"]
             : args.includes("--claude") ? ["claude"]
@@ -1351,6 +1403,13 @@ function runStatus() {
     console.log(`  Cursor           ${harnessScopeLabel(cursor) || (cursorDetected() ? "detected, not configured" : "not detected")}`);
     console.log(`  Codex            ${codex.project || codex.user ? `${harnessScopeLabel(codex)} — approve once with /hooks` : codexDetected() ? "detected, not configured" : "not detected"}`);
     console.log(`  cloud workspace  ${connected ? "connected" : "not connected (local only)"}`);
+    {
+        const activeDir = resolveConfigDir(process.cwd());
+        const connection = loadConnection(activeDir);
+        if (connection)
+            for (const line of describeDelivery(activeDir, connection).lines)
+                console.log(`                   ${line}`);
+    }
     {
         const activeDir = resolveConfigDir(process.cwd());
         const meta = readMeta(activeDir);
@@ -1515,6 +1574,33 @@ async function runDoctor() {
             reachable = `unreachable (${error.message})`;
         }
         console.log(`  cloud            ${connection.url} — ${reachable}`);
+        // SB273: an authenticated check. Reaching the workspace says nothing about whether it
+        // still accepts this computer; the rules endpoint answers 401 when it does not.
+        let accepted = "unknown";
+        try {
+            const res = await fetch(new URL("/v1/policy", connection.url).toString(), {
+                headers: { authorization: `Bearer ${connection.credential}`, "x-scopebond-hook-version": hookVersion() },
+                redirect: "error", signal: AbortSignal.timeout(10_000),
+            });
+            if (res.status === 401) {
+                accepted = "REFUSED (401)";
+                recordRulesCredential(active, false, Date.now());
+            }
+            else if (res.ok || res.status === 204 || res.status === 304) {
+                accepted = "accepted";
+                recordRulesCredential(active, true, Date.now());
+            }
+            else
+                accepted = `unknown (HTTP ${res.status})`;
+        }
+        catch (error) {
+            accepted = `not checked (${error.message})`;
+        }
+        console.log(`  connection       ${accepted}`);
+        const delivery = describeDelivery(active, connection);
+        for (const line of delivery.lines)
+            console.log(`                   ${line}`);
+        problems.push(...delivery.problems);
     }
     console.log(problems.length ? `\n${problems.length} problem(s): ${problems.join("; ")}` : `\nAll good.`);
     process.exitCode = problems.length ? 1 : 0;
@@ -1577,7 +1663,7 @@ async function runLogin(args) {
         origin = parsed.origin;
     }
     catch {
-        console.error(`usage: ${cliCommand("login <workspace-url> [--claude|--cursor|--codex] [--no-install]")}`);
+        console.error(`usage: ${cliCommand("login <workspace-url> [--claude|--cursor|--codex] [--no-install] [--project]")}`);
         console.error("The workspace URL is the address of your Scopebond workspace, for example https://cloud.scopebond.com.");
         process.exit(1);
     }
@@ -1588,6 +1674,12 @@ async function runLogin(args) {
         });
         return { status: response.status, json: await response.json().catch(() => ({})) };
     };
+    // SB276: run from inside an agent session (its own terminal or tool call), a sign-in can
+    // land in the agent's working folder rather than this person's, and the person may never
+    // see the code to approve. Say so plainly; the hook settings are left alone either way.
+    if (process.env.CLAUDECODE || process.env.CODEX_SANDBOX || process.env.CURSOR_AGENT) {
+        console.error("Note: this looks like a coding agent's own terminal. Signing in works best from your own terminal window, outside the agent.");
+    }
     let start;
     try {
         start = await post("/v1/device/code", { client_name: hostname(), harness });
@@ -1607,7 +1699,7 @@ async function runLogin(args) {
     const deadline = Date.now() + Math.max(60, Number(start.json.expires_in ?? 600)) * 1000;
     console.log(`To connect this computer, open:\n\n  ${verify}\n\nand check that it shows the code  ${userCode}\n`);
     console.log("Waiting for approval (the code expires in 10 minutes; Ctrl+C to stop)…");
-    const dir = configDir();
+    const dir = connectDir(args);
     scaffold(dir, {});
     while (Date.now() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, intervalMs));
@@ -1750,6 +1842,12 @@ const COMMANDS = [
     { name: "connect", args: "<workspace-url> <enrollment> [--claude|--cursor|--codex]",
         summary: "send receipts to a Scopebond Cloud workspace as well as keeping them locally" },
     { name: "flush", summary: "deliver any receipts still queued for the workspace now" },
+    { name: "recover", args: "[--no-wait]", summary: "deliver records an earlier, revoked key signed, once the workspace approves",
+        detail: [
+            "When this computer was replaced or disconnected while records were still queued, the",
+            "workspace refuses them from the new connection. This asks the workspace to accept them,",
+            "waits while an owner or admin approves it on Activity, then sends them, labelled Recovered.",
+        ] },
     { name: "trust", args: "[--yes]", summary: "let this project's .scopebond policy govern here (pinned by hash)" },
     { name: "uninstall", args: "[--purge] [--yes]", summary: "remove the hook from your agent config; --purge also deletes the home" },
     { name: "claude", summary: "(internal) decide one Claude Code PreToolUse call, JSON on stdin" },
@@ -1840,6 +1938,9 @@ else if (cmd === "test") {
 else if (cmd === "flush") {
     await runFlush();
 }
+else if (cmd === "recover") {
+    await runRecover(rest);
+}
 else if (cmd === "status") {
     runStatus();
 }