instar 1.2.4 → 1.2.5

package/src/templates/scripts/secret-drop-retrieve.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * secret-drop-retrieve.mjs — fetch a Secret Drop submission and stream the
+ * requested field value to stdout WITHOUT ever printing the response body.
+ * All informational output goes to stderr and is limited to field NAMES,
+ * lengths, and HTTP status — never values.
+ *
+ * Hardened replacement for the ad-hoc `curl + jq` / `curl + python` pattern
+ * that historically leaked credentials in plaintext into the Bash tool
+ * transcript. The lesson: when probing an unknown JSON shape, NEVER fall
+ * back to `console.log(JSON.stringify(body))` — that's how plaintext
+ * credentials end up in shell history, session transcripts, and downstream
+ * LLM context.
+ *
+ * Usage:
+ *   node .instar/scripts/secret-drop-retrieve.mjs <token> <field-name>
+ *     → prints the field value to stdout (single line, no trailing newline)
+ *     → suitable for piping: `... password | gh secret set X`
+ *
+ *   node .instar/scripts/secret-drop-retrieve.mjs <token> --names
+ *     → prints field names + lengths to stderr; nothing to stdout
+ *     → use to discover what fields the submission contains
+ *
+ *   node .instar/scripts/secret-drop-retrieve.mjs <token> <field> --consume
+ *     → opt into one-shot semantics (the submission is removed after read).
+ *     Default is peek (non-destructive) per the 2026-05-20 hardening.
+ *
+ * Config:
+ *   Reads `authToken` and `port` from `.instar/config.json` relative to cwd.
+ *   `INSTAR_PORT` env var overrides the config port.
+ *
+ * Exit codes:
+ *   0 — value or names printed successfully
+ *   1 — HTTP error, missing field, or unexpected response shape
+ *   2 — usage error (missing args, cannot read config)
+ */
+
+import * as fs from 'node:fs';
+
+const args = process.argv.slice(2);
+const token = args[0];
+const mode = args[1];
+const consume = args.includes('--consume');
+
+if (!token || !mode || mode === '--consume') {
+  process.stderr.write('usage: secret-drop-retrieve.mjs <token> <field-name|--names> [--consume]\n');
+  process.exit(2);
+}
+
+let authToken;
+let port;
+try {
+  const config = JSON.parse(fs.readFileSync('.instar/config.json', 'utf-8'));
+  authToken = config.authToken;
+  port = config.port;
+} catch (e) {
+  process.stderr.write('cannot read .instar/config.json: ' + e.message + '\n');
+  process.exit(2);
+}
+
+// Port resolution: env > config. Mirrors the telegram-reply.sh precedence
+// so a single explicit INSTAR_PORT override flows through every agent script.
+const resolvedPort = process.env.INSTAR_PORT || port;
+if (!resolvedPort) {
+  process.stderr.write('cannot resolve port: no INSTAR_PORT env and no port in .instar/config.json\n');
+  process.exit(2);
+}
+
+const url = `http://localhost:${resolvedPort}/secrets/retrieve/${token}${consume ? '?consume=true' : ''}`;
+const res = await fetch(url, {
+  method: 'POST',
+  headers: { 'Authorization': `Bearer ${authToken}` },
+});
+
+if (!res.ok) {
+  // Surface ONLY status + the structured error message field, never the body.
+  let errMsg = '(no error message)';
+  try {
+    const body = await res.json();
+    if (typeof body?.error === 'string') errMsg = body.error;
+  } catch {
+    // Don't fall back to printing raw response body — that's the leak we're
+    // explicitly hardening against. Just report the HTTP status.
+  }
+  process.stderr.write(`HTTP ${res.status}: ${errMsg}\n`);
+  process.exit(1);
+}
+
+const body = await res.json();
+
+// Locate the values bag. The server's known shape is body.values; defend
+// against future shape changes by checking the two most-likely nestings,
+// but NEVER print the body itself.
+const values = body?.values
+  ?? body?.submission?.values
+  ?? body?.fields
+  ?? null;
+
+if (!values || typeof values !== 'object') {
+  process.stderr.write('retrieve: response did not contain a values bag (keys at top: '
+    + Object.keys(body || {}).join(', ') + ')\n');
+  process.exit(1);
+}
+
+if (mode === '--names') {
+  // Field-name listing for debugging — names + lengths only, never values.
+  for (const k of Object.keys(values)) {
+    const v = values[k];
+    const len = typeof v === 'string' ? v.length : -1;
+    process.stderr.write(`  ${k} (length ${len})\n`);
+  }
+  process.exit(0);
+}
+
+const v = values[mode];
+if (typeof v !== 'string') {
+  process.stderr.write(`retrieve: field '${mode}' not found (available: `
+    + Object.keys(values).join(', ') + ')\n');
+  process.exit(1);
+}
+
+// Stream the value to stdout, no trailing newline so it pipes cleanly into
+// `gh secret set` or `bw unlock --raw`. process.stdout.write (not console.log)
+// — no extra newline, no trailing whitespace to confuse downstream consumers.
+process.stdout.write(v);

package/upgrades/1.2.5.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- minor = new agent-facing capability without breaking changes -->
+
+## What Changed
+
+**feat(secret-drop): ship the hardened retrieve helper as a template — and rewrite every line of agent guidance that previously taught the unsafe pattern.**
+
+The 2026-05-20 incident exposed a credential-leak class: when an agent retrieved a Secret Drop submission via a raw `curl /secrets/retrieve/TOKEN`, the response body — including the secret value — landed in the Bash tool transcript. The fix existed as a one-off `secret-drop-retrieve.mjs` on a single agent's machine, but no other agent had it, and every line of agent-facing guidance (CLAUDE.md template, the spawned-session system message, the stuck-consumer retry message) still recommended the unsafe `curl` pattern.
+
+This release closes the gap on six interlocking surfaces:
+
+1. **Ship the hardened helper as a template.** `src/templates/scripts/secret-drop-retrieve.mjs` streams the requested field value to stdout, prints field NAMES + lengths to stderr, and structurally refuses to print the response body. New agents get it via `installSecretDropRetrieve` (called from three `init.ts` paths next to `installSerendipityCapture`).
+
+2. **Migrate existing agents.** `PostUpdateMigrator.migrateScripts` always-overwrites `.instar/scripts/secret-drop-retrieve.mjs` on every update (same pattern as `convergence-check.sh`). Idempotent — running the migrator twice produces identical content.
+
+3. **Rewrite the spawn message.** `src/server/routes.ts` no longer instructs the agent to `curl ... /secrets/retrieve/TOKEN` when a Secret Drop arrives. The new message points at `node .instar/scripts/secret-drop-retrieve.mjs TOKEN <field-name>` with an explicit warning against the raw curl pattern.
+
+4. **Rewrite the stuck-consumer retry message.** Same hardened command form, same explicit warning.
+
+5. **Rewrite the CLAUDE.md template.** `src/scaffold/templates.ts` documents the hardened command as the required retrieval pattern, with a one-line explanation of the leak class.
+
+6. **Rewrite existing CLAUDE.md files.** `PostUpdateMigrator.migrateClaudeMd` detects the legacy `curl /secrets/retrieve/TOKEN` line (port-tolerant — matches any local port literal) and replaces it with the hardened guidance. Idempotent: a CLAUDE.md that already documents `secret-drop-retrieve.mjs` is left alone.
+
+7. **Update the /capabilities `secrets.retrievalHint`.** The hint now gives the actual command form so an agent reading `/capabilities` learns the safe pattern directly from the discovery surface.
+
+## What to Tell Your User
+
+No user-visible behavior change. Agents will start using the hardened retrieve helper automatically — the next time they receive a Secret Drop submission, the spawned session reads the hardened command form from the system message, not the unsafe curl. Existing agents pick up the helper script and the CLAUDE.md rewrite on the next instar update run.
+
+If you were ever shown the unsafe curl-against-secrets-retrieve pattern in chat, that guidance has been retired across every surface; the hardened helper is the only documented path now.
+
+## Summary of New Capabilities
+
+For the agent:
+
+- `.instar/scripts/secret-drop-retrieve.mjs TOKEN field-name` — streams the value to stdout, never prints the body.
+- `.instar/scripts/secret-drop-retrieve.mjs TOKEN --names` — discover field names + lengths.
+- `.instar/scripts/secret-drop-retrieve.mjs TOKEN field-name --consume` — opt into one-shot semantics.
+
+## Evidence
+
+The leak class was reproduced before the fix: running `curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:4042/secrets/retrieve/<token>` against a known submission prints the full JSON `{"values":{"password":"actual-secret-here"}, ...}` to stdout, which lands in the Bash tool transcript.
+
+After the fix, the hardened helper isolates the value path: `node .instar/scripts/secret-drop-retrieve.mjs <token> password` streams only `actual-secret-here` to stdout (no newline, pipeable), and prints nothing else. The `--names` mode prints only `password (length 16)` to stderr; stdout stays empty.
+
+New tests:
+- `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` — 8 cases covering script install (presence, executable bit, content invariants, idempotency) + CLAUDE.md rewrite (legacy → hardened, idempotent, port-tolerant).
+- The existing `tests/unit/capabilities-discoverability.test.ts` continues to pass with the updated `secrets.retrievalHint` string.
+
+Spec: `docs/specs/secret-drop-hardened-retrieve-template.md`
+ELI16: `docs/specs/secret-drop-hardened-retrieve-template.eli16.md`
+Side-effects: `upgrades/side-effects/secret-drop-hardened-retrieve-template.md`
+
+Origin: 2026-05-20 leak incident (topic 9984) + 2026-05-21 case-study audit (topic 11141, follow-up #1).

package/upgrades/side-effects/secret-drop-hardened-retrieve-template.md

@@ -0,0 +1,123 @@
+# Side-Effects Review — Secret Drop Hardened Retrieve Template
+
+**Version / slug:** `secret-drop-hardened-retrieve-template`
+**Date:** `2026-05-21`
+**Author:** `Echo (instar-developing agent)`
+**Second-pass reviewer:** `not required` (template install + documentation rewrite; no new gate/block authority)
+
+## Summary of the change
+
+Ships the hardened `secret-drop-retrieve.mjs` as an `src/templates/scripts/` template; wires it into `init.ts` (for new agents) and `PostUpdateMigrator.migrateScripts` (for existing agents); rewrites the `[secret-drop-received]` spawn message, the `[secret-drop-stuck]` retry message, the CLAUDE.md template, and the `/capabilities.secrets.retrievalHint` to instruct the hardened command form. Adds a `migrateClaudeMd` block that detects the legacy `curl /secrets/retrieve/TOKEN` line and rewrites it in place; idempotent and port-tolerant.
+
+Files touched:
+
+- `src/templates/scripts/secret-drop-retrieve.mjs` — new template.
+- `src/commands/init.ts` — `installSecretDropRetrieve` + three call sites.
+- `src/core/PostUpdateMigrator.ts` — `migrateScripts` block (always-overwrite); `migrateClaudeMd` block (port-tolerant rewrite).
+- `src/server/routes.ts` — spawn message + stuck-consumer retry message + `/capabilities.secrets.retrievalHint`.
+- `src/scaffold/templates.ts` — CLAUDE.md Secret Drop documentation block.
+- `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` — new tests (8 cases).
+- `upgrades/NEXT.md` — release notes (minor bump).
+- `docs/specs/secret-drop-hardened-retrieve-template.{md,eli16.md}` — spec + ELI16.
+
+## Decision-point inventory
+
+- `[secret-drop-received]` spawn message — **modify** — guidance the agent reads to learn how to retrieve. Unsafe → hardened.
+- `[secret-drop-stuck]` retry message — **modify** — same retrieval path on the retry branch.
+- CLAUDE.md Secret Drop block (template + migrator) — **modify** — agent's static retrieval guidance.
+- `/capabilities.secrets.retrievalHint` — **modify** — discovery-surface guidance.
+
+No new gate/block surface introduced. The `/secrets/retrieve` endpoint behavior is unchanged.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The migrator's CLAUDE.md rewrite is the closest thing to a block: it refuses to touch a CLAUDE.md that already documents `secret-drop-retrieve.mjs` (idempotent skip). That's the desired behavior — over-block would require the migrator to refuse legitimate rewrites, which it does not.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The migrator's regex matches the exact legacy-line pattern. A CLAUDE.md that someone manually customized to use a different unsafe pattern (e.g., `wget` instead of `curl`, or a piped one-liner) would slip past the rewrite. Acceptable: the rewrite is the structural fix for the documented unsafe pattern; bespoke unsafe variants are out of scope and would be visible to anyone reading their own CLAUDE.md.
+
+The hardened helper itself still reads `.instar/config.json` for the authToken. If the config file is missing, the script exits 2 with a clear stderr message; if the file is present but `authToken` is empty, the script does a request with an empty bearer and the server returns 401 — the script prints the 401 status (no body). Both paths are safe.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+The change lives at the agent-facing instruction layer, which is the correct level. Three reasons:
+
+1. The leak is caused by the agent running a documented command verbatim. The fix is to make the documented command safe.
+2. Adding a server-side gate (e.g., refuse `/secrets/retrieve` without a hardened-client header) would create a brittle detector with block authority — violating the signal-vs-authority principle. The server stays permissive; the agent layer is hardened by making safe the only documented path.
+3. The hardened helper itself is a thin wrapper around `fetch`. It doesn't introduce new architecture; it constrains how the value flows out of the response.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface at runtime.
+
+The migrator's CLAUDE.md rewrite has commit-time block authority via the precommit hook, but only by virtue of being a code change; the migrator itself does not refuse anything at runtime. The hardened helper has no gate logic — it just streams a value or exits with an error code.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** the `[secret-drop-received]` spawn message replaces the existing one verbatim (no append, no shadow). The existing 5-minute cleanup timer and the stuck-consumer event from PR #288 are unchanged — both rely on server-side state, not on the system-message content.
+- **Double-fire:** the migrator runs each of `migrateScripts` and `migrateClaudeMd` once per `instar update` invocation. Neither path is recursive.
+- **Races:** the migrator runs single-threaded against an agent that is not yet started; no concurrent writers to the files it touches.
+- **Feedback loops:** none. The agent reading the new guidance produces no input back into the migrator.
+
+The `PostUpdateMigrator.loadRelayTemplate` helper is reused (not duplicated) for loading the new template. Symmetric with `getTelegramReplyScript`.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Agents on the same machine:** yes — every existing agent picks up `.instar/scripts/secret-drop-retrieve.mjs` on the next update, and any agent whose CLAUDE.md still has the legacy retrieve line gets it rewritten in place. The behavioral change is that the agent learns a safer command form. The unsafe `/secrets/retrieve` endpoint continues to work unchanged for any caller (including custom integrations); only the guidance is updated.
+- **Other agents on the install base:** same — Codex / Gemini agents that read CLAUDE.md / AGENTS.md / GEMINI.md get the rewrite via `migrateFrameworkShadowCapabilities` (existing migrator path that mirrors CLAUDE.md changes to non-Claude shadows).
+- **External systems:** no external surface touched.
+- **Persistent state:** none beyond the file install (which is by design).
+- **Timing / runtime conditions:** the new helper makes one `fetch` call per invocation; same latency profile as the curl it replaces.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code change. Revert the migrator + init + templates + spec/artifact files. The script previously installed by the migrator stays on disk for existing agents (the rollback doesn't delete). The CLAUDE.md rewrites previously applied to existing agents also stay — which is fine because the hardened guidance points at a script that still exists (the install path doesn't go away during a code-only rollback).
+
+Realistic rollback: revert + patch release. Under 5 minutes. The only concern would be a downstream agent that started depending on a quirk of the hardened helper (e.g., expecting an exact stderr format). The script's output contract is documented in the file header; downstream tooling using it should pin against that, not against ephemeral implementation details.
+
+---
+
+## Conclusion
+
+This is a low-risk hardening change focused on agent-facing guidance. It closes the structural side of the 2026-05-20 leak class: every documented path now teaches the safe pattern. The runtime change is a script install + a sequence of string rewrites; no new decision points introduced; signal-vs-authority preserved. No second-pass review required.
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/secret-drop-hardened-retrieve-template.md`
+- ELI16: `docs/specs/secret-drop-hardened-retrieve-template.eli16.md`
+- Tests: `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` (8 cases, all green).
+- Existing coverage that continues to pass with the updated guidance strings: `tests/unit/capabilities-discoverability.test.ts`, `tests/unit/secret-drop-hardening.test.ts`.
+- Origin: 2026-05-20 leak incident (topic 9984); 2026-05-21 case-study audit (topic 11141, follow-up #1).