@klhapp/skillmux 1.11.2 → 1.13.0

package/docs/sdd/runtime-resource-hardening/spec.md

@@ -0,0 +1,43 @@
+<!-- source: docs/sdd/security-hardening-phase/think.md -->
+<!-- plane_project: SMX -->
+<!-- plane_module: runtime-resource-hardening -->
+
+# Spec: Runtime Resource Hardening
+
+Slice 2 of 3 from the security-hardening-phase (see `docs/sdd/security-hardening-phase/think.md`).
+
+## Goal
+
+Close the two remaining "unenforced" gaps from the security-hardening-phase's resource/egress area: (1) the HTTP transport has no positive bound on request body size or concurrent connections, and (2) remote-inference (embedding/reranker) calls ignore the `[egress] allowed_hosts` allowlist that slice 1 (supply-chain-hardening, merged as PR #160) already enforces for install/update git fetches.
+
+## Acceptance Criteria
+
+1. With no `[server]` body/concurrency config set at all, the `--transport http` listener still applies default bounds (1 MiB request body, 100 concurrent in-flight requests) — behavior is never unbounded by omission. Unlike the egress allowlist, these are *positive* defaults, not opt-in.
+2. A request whose body exceeds `server.max_body_bytes` (or the 1 MiB default) is rejected with `413 Payload Too Large` before the full body is buffered into memory.
+3. Once `server.max_concurrent_requests` (or the default of 100) in-flight requests are being handled, an additional concurrent request is rejected with `503 Service Unavailable` rather than queued or accepted.
+4. Both bounds are configurable via `[server] max_body_bytes` / `max_concurrent_requests`.
+5. With `[egress] allowed_hosts` unset, remote embedding/reranker calls are unaffected — unchanged, backward-compatible behavior.
+6. With `allowed_hosts` set, an embedding-endpoint call to a disallowed host is rejected before the network fetch, surfaced as a `RemoteInferenceError` (kind `configuration`) so `resolve_skill` degrades exactly the way it already does for other embedding config failures — not a raw crash.
+7. With `allowed_hosts` set, a reranker-endpoint call to a disallowed host is rejected the same way, before the network fetch.
+8. With `allowed_hosts` set, an embedding/reranker host that *is* listed proceeds unchanged.
+
+## Scope
+
+- `[server] max_body_bytes` / `max_concurrent_requests` config, applied to the main `--transport http` `Bun.serve` listener (`src/server.ts`).
+- Host-check in `src/clients.ts`'s `embed`/`rerank` fetch calls, reusing `assertHostAllowed`/`extractHost` from `src/install.ts` (the function slice 1 already built — not reimplemented).
+
+## Out of Scope
+
+- The `--stats-port` listener (GET-only, no body, lower risk) — no body-size bound needed there; concurrency bound not added this slice either, to keep scope to the primary HTTP transport attack surface.
+- Supply-chain git-fetch egress allowlist enforcement (already shipped, slice 1).
+- Centralized secret redaction, tamper-evident admin audit trail (slice 3: security-observability).
+- Signer verification, SBOM/provenance, posture-visibility command, privacy purge (deferred phase-wide per `think.md`).
+
+## Tasks
+
+1. Config schema: add `max_body_bytes` / `max_concurrent_requests` to `ServerConfig`/`configSchema` (`src/types.ts`, `src/config.ts`), with code-level defaults matching the existing `config.server || {...}` fallback pattern, since `server` itself is optional.
+2. Wire body-size bound into the http-transport `Bun.serve` call (`src/server.ts`).
+3. Wire a concurrency counter (increment/decrement around the `fetch` handler) with a `max_concurrent_requests` cap (`src/server.ts`).
+4. Host-check in `src/clients.ts`: call `assertHostAllowed` on `embedding.endpoint` and `reranker.endpoint` before each fetch, wrapping a thrown allowlist error as `RemoteInferenceError("configuration", ...)`.
+5. Docs: extend `docs/configuration.md`'s `[server]` and `[egress]` sections.
+6. Tests: default bounds apply without config, 413/503 behavior, config overrides, egress unset/blocked/allowed for both embedding and reranker.

package/docs/sdd/security-hardening-phase/think.md

@@ -0,0 +1,129 @@
+# Think: Security-Hardening Phase ("the big one")
+
+**Mode:** Builder — hardening an existing, shipping system (skillmux), not a new product.
+
+## Background
+
+Sequenced 2026-07-21 as the roadmap phase after direction 4 (skill lifecycle
+and distribution) and before the now-cancelled direction 5 (team/governance,
+killed 2026-08-29 for lacking a concrete spec). Reconfirmed 2026-08-29 when
+the user resolved the outstanding Security ASK from the skill-provenance-update
+review and confirmed proceeding.
+
+Original decision (2026-07-21) framed this phase as necessary because
+acquiring and distributing agent instructions from git expands the trust
+boundary, and listed 12 sub-areas: secure non-loopback exposure, fail-closed
+separate MCP/admin authentication, positive resource bounds, filesystem
+containment, source/inference egress policy, quarantine and hash-bound
+approval, optional signer verification, centralized secret redaction,
+privacy reporting/purge, tamper-evident mutation audit, security posture
+visibility, and release SBOM/provenance/adversarial tests. Team accounts,
+RBAC, SSO, and multi-tenancy were explicitly out of scope from the start
+(that became the cancelled direction 5).
+
+No think/spec doc existed for the phase as a whole before this session — a
+meaningful slice shipped ad hoc as individual point-fix PRs first (#146-#158),
+each addressing one concrete bug rather than working from a plan.
+
+## Job-to-be-done
+
+Both network-exposure safety and supply-chain safety are in scope, weighted
+toward what benefits skillmux's OSS users broadly — this is the public repo,
+and most users self-host, so the deliverable is "any user who runs
+`skillmux serve --transport http` or installs from an unfamiliar git source
+can trust the boundary held," not narrowly what benefits this user's own
+Bifrost (stdio-transport) deployment. Bifrost's stdio connection to skillmux
+never touches the network, so full-HTTP-surface hardening doesn't protect it
+directly — the one exception is the `--stats-port` listener (PR #158), which
+does open a narrow HTTP surface even under stdio transport and already
+inherits the non-loopback bind-posture rule from #153.
+
+## Landscape: what already exists (read during this session)
+
+Reconciling the original 12-item scope against current `main` (commit
+`97887fe`):
+
+| # | Sub-area | Status |
+|---|---|---|
+| 1 | Secure non-loopback exposure | **Shipped** — #153 refuses non-loopback bind without auth; `--stats-port` inherits the same rule |
+| 2 | Fail-closed, separate MCP/admin auth | **Shipped, already mature** — `/admin/v1/*` uses a distinct bearer token (`server.admin.token_env`), 403 if disabled, 401 if unauthorized, timing-safe compare (`safeTokenEquals`, #157), ETag-based optimistic concurrency on `PATCH /admin/v1/config`. Documented in `docs/README.md`, `concepts.md`, `cli.md`, `deployment.md`. **This was discovered mid-session — an earlier forcing question in this doc's own design process incorrectly assumed no admin HTTP surface existed. It does, and it's done.** |
+| 3 | Positive resource bounds | **Partial** — `rate-limiter.ts` (LRU-bounded, #155) bounds *request count* per client. No bound on request body size or concurrent connections. |
+| 4 | Filesystem containment | **Mostly shipped** — path-traversal / symlink guards across install (#146, #151), update (#150), sync (#152) |
+| 5 | Source/inference egress policy | **Partial** — scp-like URL and `file://` source rejection shipped (#148, #156); no allowlist for install/update git hosts or remote-inference API hosts |
+| 6 | Quarantine / hash-bound approval | **Shipped, discovered mid-`/sdd-tdd` for the supply-chain-hardening slice** — `src/provenance.ts` (`hashSkillContent`/`content_hash` on `.skillmux-origin`) + `src/commands/update.ts`'s `buildPlan` already bind every update to a local-drift check and an unconditional scan before write, tested in `tests/cli.test.ts`'s `skillmux update CLI` suite. This row originally said "Not started" — that was wrong, the same class of landscape-research miss as item 2 above (grep the source, don't trust the prior scope decision alone). |
+| 7 | Optional signer verification | Not started — **deferred this phase** |
+| 8 | Centralized secret redaction | **Not started** — zero `redact` hits across 99 log call-sites in `server.ts`/`cli.ts` |
+| 9 | Privacy reporting/purge | Not started — **deferred this phase** |
+| 10 | Tamper-evident mutation audit | **Not started, now well-scoped** — `PATCH /admin/v1/config` mutates live config with zero audit trail: no record of who/when/what-changed |
+| 11 | Security posture visibility | Not started — **deferred this phase** |
+| 12 | Release SBOM/provenance + adversarial tests | Not started — **deferred this phase** |
+
+## Decisions made this session
+
+1. **Scope weighting:** both network-exposure and supply-chain safety in
+   scope, weighted toward OSS users (public repo) over this user's own
+   stdio-only Bifrost deployment.
+2. **Done-state:** ship the highest-risk half now (6 items), defer the rest
+   to the same evidence-of-demand bucket the deferred direction-5 items
+   (registry/distribution/versioning, RBAC, dashboards, marketplace,
+   autonomous optimization) already live in.
+3. **Auth split (item 2) removed from the shipping list** — not because it
+   was deferred, but because it turned out to already be fully shipped.
+   Net effect on the plan is the same as the original "defer" answer, but
+   for a different, now-corrected reason.
+4. **Quarantine (item 6) scoped narrowly:** hash-pin the scan verdict, not a
+   full staging/approval workflow. Content-hash the skill directory at scan
+   time, store the hash alongside `.skillmux-origin`; on install/update, a
+   changed hash forces a fresh scan. No new CLI subcommand, no staging
+   directory, `--yes` one-shot install flow is unchanged.
+5. **Egress policy (item 5) scoped broadly:** one `[egress] allowed_hosts`
+   config list, unset by default (backward compatible, matches skillmux's
+   opt-in security posture elsewhere), enforced at both `resolveRepoSource`
+   (install/update git fetches) and remote-inference embedding/reranker
+   calls.
+6. **Resource bounds (item 3) scoped systematically:** beyond the existing
+   per-client request-count limiter, add positive bounds on request body
+   size and concurrent connections on the HTTP transport.
+7. **Tamper-evident mutation audit (item 10) scoped concretely:** log every
+   `PATCH /admin/v1/config` mutation (actor context available from the
+   request, changed keys, old/new values, resulting revision hash) to an
+   audit trail, reusing the existing audit-DB infrastructure from the
+   routing-quality flywheel (`src/db.ts`) rather than inventing a new store.
+
+## Final shipping list (this phase)
+
+1. Systematic resource bounds (request body size + concurrency caps) on the
+   HTTP transport.
+2. Egress allowlist (`[egress] allowed_hosts`) covering install/update git
+   sources and remote-inference calls.
+3. Hash-pinned scan verdicts (quarantine, narrow scope) for install/update.
+4. Centralized secret redaction in logging output.
+5. Tamper-evident audit trail for `PATCH /admin/v1/config` mutations.
+
+## Deferred (evidence-of-demand bucket, alongside the already-deferred
+direction-5 items)
+
+- Fail-closed admin/MCP auth split — **removed, not deferred: already shipped.**
+- Optional signer verification for installed skill content.
+- Release SBOM/provenance + adversarial security tests.
+- `skillmux security-status`-style posture visibility command.
+- Privacy reporting/purge.
+
+## Slicing for /sdd-spec
+
+Three domain-grouped specs, each independently shippable, matching the
+skill-provenance-update precedent (full spec → schema → TDD → review cycle
+per slice):
+
+1. **`supply-chain-hardening`** — egress allowlist for install/update
+   sources + hash-pinned scan verdicts. Both live in `install.ts` /
+   `update.ts` / `scan.ts` / the vault-ingestion path.
+2. **`runtime-resource-hardening`** — positive resource bounds on the HTTP
+   transport + egress allowlist enforcement for remote-inference calls.
+   Both live in `server.ts` / `config.ts`.
+3. **`security-observability`** — centralized secret redaction in logging +
+   tamper-evident audit trail for admin config mutations. Both live in the
+   logging surface and the `/admin/v1/config` handler, and both write to
+   observability-facing output.
+
+Run `/sdd-spec` once per slice, starting with whichever the user picks next.

package/docs/sdd/security-observability/review.md

@@ -0,0 +1,96 @@
+<!-- source: docs/sdd/security-observability/spec.md -->
+
+# Review: Security Observability
+
+Branch `feat/security-observability` vs `main`, 12 commits (a7ec27b through 6cbf8e0).
+Reviewed manually — `goose run --recipe sdd-review` hit the same 24h Bifrost
+token-quota exhaustion seen repeatedly across this phase (`token limit
+exceeded (279006/250000, resets every 24h)`) — this is now the fifth
+occurrence across supply-chain-hardening, runtime-resource-hardening, and
+this slice combined, hitting every SDD pipeline stage at least once. Fell
+back to the skill's documented manual path (sequential focus passes + native
+test/build runs).
+
+## Test Execution
+
+`bun test`: **808 pass, 0 fail, 2053 expect() calls** (61 files) — includes the
+regression test added during this review for the `--verbose` finding below.
+
+## Build Check
+
+`bunx tsc --noEmit`: **clean**, exit 0.
+
+## Compliance
+
+| Criterion | Status | Notes |
+|---|---|---|
+| AC1: centralized `redact(text)` resolves `*_env` secret values | ✅ Done | `buildRedactor(config)` recursively walks the config tree for any `*_env`-suffixed key and resolves it against `process.env`. This also catches `server.auth_token_env` and `server.admin.token_env` (the MCP and admin bearer tokens), not just the inference `api_key_env` fields — verified by inspection, matching AC1's literal enumeration. |
+| AC2: credential-bearing git URL redacted from clone/ls-remote failures | ✅ Done, with a scope note | The real leak (a user-typed `https://user:TOKEN@host/repo.git`, never named by any `*_env` key) can't be caught by AC1's config-driven mechanism alone, so `redact.ts` adds a second, unconditional URL-userinfo regex layered into the same `buildRedactor` closure. AC1's text describes "a single centralized `redact(text)` function" — satisfied at the API level (one function, one call site per consumer) but internally composed of two rules rather than one. Verified end-to-end against a real `git clone` failure against an unresolvable host. |
+| AC3: CLI `handleError` redacts message in human and `--json` modes | ✅ Done (one finding fixed during this review — see Correctness) | Wired via a best-effort redactor built from `getEffectiveConfig()`, falling back to the URL-only layer if config itself fails to load, so a broken config never suppresses the original error report. |
+| AC4: server-side `console.error` sites apply redaction | ✅ Done | 3 of 5 `console.error` call sites in `server.ts` interpolate exception/subprocess text (config reload error, runtime init error, audit prune error) and now route through `redactedErrorLog`. The other 2 sites are fixed diagnostic strings with no exception text, correctly left as-is. |
+| AC5: redaction is a no-op with no `*_env` keys set | ✅ Done | Regression test asserts byte-identical output; passed immediately once AC1 landed (empty secrets list ⇒ identity), kept as a distinct behavioral lock rather than dropped as redundant. |
+| AC6: `redact()` is a pure function, no network/subprocess needed to test | ✅ Done | `redact.ts` has zero I/O imports; test asserts determinism and non-Promise return. |
+| AC7: successful `PATCH /admin/v1/config` appends an `admin_audit` row | ✅ Done | One row per PATCH call (not per changed key), recording ts, an array of `{key, old_value, new_value}`, and `resulting_revision`. Verified via a real HTTP round-trip against a running server, cross-checked against the actual pre/post config values. |
+| AC8: `admin_audit` rows are hash-chained (tamper-evident) | ✅ Done | `row_hash = sha256(JSON({prev_row_hash, ts, changes, resulting_revision}))`, chained per row. No transaction wraps the read-prev/insert pair, but since `insertAdminAuditRow` contains no internal `await`, Bun's single-threaded event loop runs it to completion atomically before any other request handler resumes — checked specifically because two concurrent PATCH requests do have `await` points earlier in the handler (`setDottedKey` is async), but by the time `insertAdminAuditRow` itself runs, no interleaving is possible. |
+| AC9: rejected `PATCH /admin/v1/config` writes no audit row | ✅ Done | Both rejection paths (stale `If-Match` → 409, `SKILLMUX_CONFIG_READONLY` → 409) return before the audit-insert code is reached; verified by asserting zero rows in each case. |
+| AC10: `admin_audit` rows pruned by existing `audit.retention_days` | ✅ Done | `pruneAuditBefore`/`countPrunable` extended to include `admin_audit`; the one pre-existing test asserting the exact `PruneResult` shape was updated for the new field (only such test in the suite). |
+| AC11: `verifyAdminAuditChain()` detects a broken hash chain | ✅ Done | Walks rows in `id` order recomputing each hash; a direct `UPDATE` on a row's `resulting_revision` (simulating out-of-band tampering) is detected and reported with the tampered row's id. |
+
+Schema: no `schema.json` exists for this feature — config/data-shape-only
+change with no new external API surface (the `PATCH /admin/v1/config`
+request/response shape is unchanged; only server-side logging behavior is
+new), consistent with slices 1 and 2 of this phase.
+
+## AC Status
+
+| Criterion | Status | Notes |
+|---|---|---|
+| AC1: centralized redact(text) resolves *_env secret values | ✅ Done | `buildRedactor(config)` recursively resolves every `*_env`-suffixed key against `process.env`. |
+| AC2: credential-bearing git URL redacted from clone/ls-remote failures | ✅ Done | Second, unconditional URL-userinfo regex layered into the same `buildRedactor` closure — see Security section for the scope note. |
+| AC3: CLI handleError redacts message in human and --json modes | ✅ Done | One finding fixed during review: `--verbose` stack trace was leaking the raw message — see Security section. |
+| AC4: server-side console.error sites apply redaction | ✅ Done | 3 of 5 exception-bearing `console.error` sites in `server.ts` route through `redactedErrorLog`; the other 2 are fixed strings with no exception text. |
+| AC5: redaction is a no-op with no *_env keys set | ✅ Done | Regression test asserts byte-identical output. |
+| AC6: redact() is a pure function, no network/subprocess needed to test | ✅ Done | Zero I/O imports in `redact.ts`; determinism asserted directly. |
+| AC7: successful PATCH /admin/v1/config appends an admin_audit row | ✅ Done | One row per PATCH call, verified via a real HTTP round-trip. |
+| AC8: admin_audit rows are hash-chained (tamper-evident) | ✅ Done | `row_hash = sha256(JSON({prev_row_hash, ts, changes, resulting_revision}))`, chained per row; atomicity argument in Security section. |
+| AC9: rejected PATCH /admin/v1/config writes no audit row | ✅ Done | Both rejection paths (stale If-Match, read-only config) verified to write zero rows. |
+| AC10: admin_audit rows pruned by existing audit.retention_days | ✅ Done | `pruneAuditBefore`/`countPrunable` extended to include `admin_audit`. |
+| AC11: verifyAdminAuditChain() detects a broken hash chain | ✅ Done | Direct out-of-band `UPDATE` on a row is detected and reported with the tampered row's id. |
+
+## Security
+
+- **Finding (fixed during this review): `--verbose` stack trace leaked the raw credential.** `handleError` redacted the primary error line via `redact(rawMsg)` but printed `err.stack` verbatim when `--verbose` was set — and `Error.stack`'s first line reproduces the *unredacted* `err.message`, so `skillmux install <credential-url> --verbose` reopened exactly the leak AC2/AC3 were meant to close. Confirmed via a real reproduction (`git clone failed for https://user:supersecret123@...` appearing in full in stderr), fixed by wrapping the stack print in the same `redact()` call, and locked in with a new regression test. This also required a one-line, directly-related fix to `install`'s arg parser, which rejected `--verbose` as an unknown option (it already special-cased `--json` the same way) — without that, the leak path was unreachable through the CLI to write a real test against.
+- The URL-userinfo regex (`/:\/\/[^/\s@]*@/g`) is scoped to `scheme://user:pass@` — it does not touch bare `user@host` strings lacking a scheme, so it won't over-redact plain email addresses or similar text appearing elsewhere in error messages.
+- `collectSecretValues` guards against empty-string secret values (`if (resolved) secrets.push(resolved)`), which matters: an unguarded `"".split("").join(PLACEHOLDER)` would have inserted the placeholder between every character of any string passed to `redact`.
+- `handleError`'s config load is wrapped in try/catch with a fallback to the URL-only redaction layer — a broken config file can never suppress or crash the original error report, only reduce redaction to its unconditional layer.
+- The admin audit trail records `old_value`/`new_value` per changed key, not the raw request/response bodies — it doesn't itself need redaction, since `PATCH /admin/v1/config` never accepts or returns `*_env`-masked keys (`setDottedKey` already throws on `isEnvMasked(key)`, pre-existing behavior unrelated to this diff).
+
+## Correctness
+
+- The one substantive finding (verbose stack-trace leak) is described above and fixed.
+- `redactedErrorLog`'s tuple-spread wiring (`console.error(...redactedErrorLog(...))`) was verified against all three `server.ts` call sites in the diff, not just tested as an isolated helper.
+- `verifyAdminAuditChain` on an empty table returns `{valid: true, broken_at_id: null}` — a sensible vacuous-truth default, not exercised by an explicit test but low-risk (single `if` branch, empty loop).
+- No coverage for a `PATCH` with an empty `changes: {}` object — current behavior is to write no audit row (the `auditChanges.length > 0` guard), which is arguably correct (no real mutation occurred) but untested. Low-severity gap, not blocking.
+
+## Performance
+
+No concerns. `collectSecretValues`'s recursive config walk runs once per `buildRedactor()` call (once per CLI error, once at server startup) against a small config object — not a hot path. The `admin_audit` INSERT/prune additions are O(1)/indexed-scan SQLite operations consistent with the existing `audit`/`fetch` table patterns.
+
+## Test Coverage (static)
+
+Adequate. Every AC has at least one test; AC5/AC6/AC8/AC11 tests were written
+as regression locks even though they passed immediately against the
+preceding cycle's implementation (documented inline in commit messages
+rather than treated as TDD false starts, per this session's established
+practice of keeping a distinct test per spec-named criterion). The one
+gap (empty-changes PATCH) is noted above.
+
+## Reflect
+
+Retained to Hindsight (`infra` bank): the `--verbose` stack-trace redaction
+gap as a pattern worth checking on any future centralized-redaction work
+(a single "redact the message" choke point is not the only place an error's
+raw content can surface — `Error.stack`, `util.inspect` on an Error object
+passed directly to `console.error`, and similar implicit stringification
+paths need the same treatment), and the now-five-times-recurring Bifrost
+24h token-quota exhaustion pattern across every SDD stage in this phase.

package/docs/sdd/security-observability/spec.md

@@ -0,0 +1,55 @@
+<!-- source: docs/sdd/security-hardening-phase/think.md -->
+<!-- plane_project: SMX -->
+<!-- plane_module: security-observability -->
+
+# Spec: Security Observability
+
+Slice 3 of 3 from the security-hardening-phase (see `docs/sdd/security-hardening-phase/think.md`).
+
+## Goal
+
+Close the two remaining unenforced items from the security-hardening-phase's observability area: centralized secret redaction so resolved credential values never reach stdout/stderr/`--json` output or logs unredacted, and a tamper-evident, append-only audit trail for admin config mutations.
+
+## Acceptance Criteria
+
+### Secret redaction
+
+1. A single centralized `redact(text)` function (`src/redact.ts`) knows, from the currently effective config, every env var name referenced by a `*_env` key (`api_key_env`, `token_env`, `auth_token_env`) and scrubs any occurrence of that env var's current value from a string, replacing it with a fixed placeholder.
+2. A git clone/ls-remote/rev-parse failure whose error text embeds a credential-bearing URL is redacted before reaching CLI output — the credential substring never appears in stderr or the `--json` error envelope.
+3. The CLI's top-level error handler (`handleError`) redacts `err.message` before printing to stderr and before including it in the JSON error envelope, in both human and `--json` modes.
+4. The small number of server-side `console.error` calls that include exception or subprocess text apply the same redaction before writing.
+5. With no `*_env` config keys set, redaction is a no-op — output is byte-identical to current behavior.
+6. Redaction is a pure string function, testable in isolation given a config object and env vars, with no network call or subprocess spawn required.
+
+### Tamper-evident admin audit trail
+
+7. Every successful `PATCH /admin/v1/config` mutation appends one row to a new `admin_audit` table in the existing `audit.sqlite3`, recording timestamp, changed keys, old/new value per key, and the resulting config revision hash.
+8. Each `admin_audit` row is tamper-evident: it carries a hash chained to the previous row's hash, so any row deleted or edited out-of-band breaks the chain.
+9. A rejected `PATCH /admin/v1/config` (409 conflict, read-only, validation error) writes no audit row.
+10. `admin_audit` rows are pruned by the existing `audit.retention_days` mechanism (SMX-69–71) — no separate retention config.
+11. A `verifyAdminAuditChain()` utility walks the table and reports whether the hash chain is unbroken.
+
+## Scope
+
+- `src/redact.ts` (new): `buildRedactor(config)` → `(text: string) => string`.
+- Wiring into `cli.ts`'s `handleError` and the ~6 server-side `console.error` sites that include exception/subprocess text.
+- New `admin_audit` table + hash-chain writer in `src/db.ts`/`src/server.ts`, wired into the `PATCH /admin/v1/config` success path.
+- A chain-verification utility (`verifyAdminAuditChain()`).
+
+## Out of Scope
+
+- Any new HTTP/CLI surface for querying admin audit history — overlaps with the phase-wide-deferred "security posture visibility" item.
+- Redacting arbitrary user/skill content — only `*_env`-derived credential values are in scope.
+- Per-admin actor identity — none exists (single shared admin bearer token via `SKILLMUX_ADMIN_TOKEN`/`admin.token_env`).
+- Signer verification, SBOM/provenance, privacy purge (deferred phase-wide per `think.md`).
+
+## Tasks
+
+1. `src/redact.ts`: `buildRedactor(config)` resolving `*_env` config keys to current env values, returning a `redact(text)` closure.
+2. Wire redactor into `cli.ts`'s `handleError` (both human and `--json` paths).
+3. Wire redactor into the server-side `console.error` call sites that include exception/subprocess text (`src/server.ts`).
+4. `admin_audit` table migration in `src/db.ts` (reusing the existing `audit.sqlite3` WAL + incremental auto-vacuum setup).
+5. Hash-chain row builder + insert wired into the `PATCH /admin/v1/config` success path in `src/server.ts`.
+6. `verifyAdminAuditChain()` utility + unit tests.
+7. Docs: extend `docs/configuration.md` (or admin-API docs if present) noting the audit table and redaction behavior.
+8. Tests: one per acceptance criterion above.

package/docs/sdd/skill-provenance-update/review.md

@@ -0,0 +1,152 @@
+# Review: Skill provenance + update
+
+Reviewed diff: `c55e5ec..HEAD` on `main` (no feature branch was cut for this
+work — all 9 commits landed directly on `main`, one per TDD task plus this
+review's fixes).
+
+**Method:** the `sdd-review` goose fan-out was attempted twice. Both runs
+failed — the first with a peg-native format error from the model, the
+second with Bifrost's daily token rate limit exceeded
+(`1723501/1700000, resets every 24h`). Per this skill's "If goose errors
+out" fallback, the five focus passes (security, correctness, performance,
+tests, compliance) were run manually against the diff, plus `tsc --noEmit`
+(build check) and `bun test` (test execution), both run directly rather than
+through `test-runner`/`build-check` workers.
+
+## Findings
+
+### Correctness — FIXED
+**A corrupt `.skillmux-origin` sidecar crashed the whole vault sweep
+instead of being isolated per-skill.** `checkOutdated`'s loop called
+`readSkillOrigin` unguarded; a malformed JSON file (or one failing
+`validateOrigin`) threw past the loop and aborted `outdated`/`update`
+entirely — for every other skill in the vault, not just the broken one.
+AC3 promises no-sidecar skills are "not flagged as errors" and AC4 promises
+a per-skill failure "does not abort the whole command," but both were
+written with only *remote* failures in mind; a local parse failure hit the
+same underlying risk (one skill's problem taking down the whole batch) and
+wasn't covered. Reproduced directly (`bun run src/cli.ts outdated --json`
+against a vault with one skill carrying `{not valid json` as its sidecar →
+exit 2, raw `JSON Parse error`), then fixed: `checkOutdated` now catches
+the exception and reports that skill as `check_failed` with a reason, same
+as an unreachable remote. `update`'s single-skill path (which has no other
+skills to protect) still surfaces the error but with a clearer message.
+Regression test added: `tests/cli.test.ts` — "a malformed .skillmux-origin
+sidecar is reported as check_failed, not a whole-command crash".
+
+### Tests — FIXED
+`update`'s `--fail-on` validation and `<skill-id>` argument-count limit had
+no CLI-level test, unlike the equivalent checks on `install`/`audit prune`.
+Added two tests for parity.
+
+### Security — ASK, later FIXED (commit b2430a8, post-merge)
+`update`'s confirmation prompt lists only skill IDs
+(`update ${toWrite.map(i => i.skillId).join(", ")}?`), never the
+`source_url` each one will be cloned from. Since `source_url` is read back
+from a file written at `install` time — not re-typed by the user at
+`update` time — a user who once installed from an attacker-controlled repo
+and later runs `skillmux update --yes` (batch, non-interactive, e.g. in a
+cron job or CI) re-triggers `git clone`/`git ls-remote` against that same
+URL with no per-run visibility into which URLs are being fetched. This
+isn't a new vulnerability class — `install` already accepts arbitrary git
+URLs from the user directly — but `update` is designed to be re-run
+unattended and batches multiple skills' fetches behind one `--yes`, which
+meaningfully raises the value of showing what's about to be fetched.
+**Proposed fix:** include `source_url` alongside `skill_id` in the
+confirmation prompt and in `--dry-run` output. Left as a decision for the
+human at review time rather than auto-fixed, since it was a UX/trust-surface
+design choice rather than a bug. User approved applying it as the first
+slice of the security-improvement phase; applied in commit `b2430a8` —
+`buildConfirmPrompt` now renders `<skill_id> <- <source_url>` per line, and
+`source_url` was added to the `skills[]` JSON/dry-run output. Covered by a
+new unit test on `buildConfirmPrompt` and an updated AC9 dry-run assertion
+in `tests/cli.test.ts`.
+
+**Security escalation — RUN (commit fc3e083, 6506663, post-merge).** goose's
+recipe-backed `/security-review` failed twice on Bifrost's daily token rate
+limit (same limit hit during the original review); ran the audit manually
+against `install.ts`, `provenance.ts`, `commands/update.ts`, and
+`commands/outdated.ts` per the skill's fallback. Findings:
+
+- **HIGH, fixed (fc3e083):** `readSkillOrigin`/`validateOrigin` accepted any
+  non-empty `source_url`. `update`/`outdated` read `source_url` straight from
+  the on-disk sidecar and pass it directly into `git clone`/`git ls-remote`,
+  bypassing the `isGitUrl` protocol allowlist that gates the `install` CLI
+  entry point. A tampered sidecar (e.g. a malicious edit to a shared,
+  git-backed vault checkout) could route those subprocess calls through
+  git's `ext::` transport or argument injection. Fixed by exporting
+  `isGitUrl` from `install.ts` and enforcing it inside `validateOrigin`, so
+  a non-conforming `source_url` fails closed — isolated per-skill by the
+  existing `checkOutdated`/`resolveCandidateOrigins` error handling.
+- **MEDIUM, informational only (no code change):** `confirmIfNeeded`
+  (`shared.ts:40`) returns `true` immediately when `--yes` is passed, before
+  `buildConfirmPrompt` (the b2430a8 fix) is ever built or shown. That fix
+  only helps the interactive path — it does not cover the review's original
+  highest-risk scenario, unattended `skillmux update --yes` in cron/CI. The
+  HIGH fix above is the actual mitigation for that path.
+- **LOW, fixed (6506663):** `resolveSkillDir` joined an origin-supplied
+  `skill_path` into `cloneDir` with no traversal check; a tampered sidecar's
+  `skill_path` could point content-fetch outside the intended clone dir.
+  Fixed by rejecting `..` segments and absolute paths.
+
+Both fixes are TDD cycles with regression tests
+(`tests/provenance.test.ts`, `tests/install.test.ts`); full suite green
+(700/0) after both.
+
+### Performance — NITPICK (not fixed)
+`buildPlan` clones every candidate skill's source *before* checking local
+drift, even though the drift check (`hashSkillContent(skillDir) !==
+origin.content_hash`) is purely local and needs no network access. A
+drifted skill (which will be skipped) still pays for a full `git clone`.
+Reordering this safely would require making `cloneDir`/`fetchedDir`
+nullable on `UpdatePlanItem` and guarding the cleanup `finally` loop
+accordingly — a real but non-trivial type change, and the actual cost (one
+extra shallow clone in the uncommon drift-skip path, for a manually-invoked
+CLI command) is low. Left as-is; worth revisiting if drift turns out to be
+common in practice.
+
+### Compliance
+All 13 acceptance criteria are met after the correctness fix above (AC3/AC4
+were the ones exposed by the crash bug). See AC Status below.
+
+### Build check
+`bunx tsc --noEmit -p .` — PASS (clean, run directly, four times across the
+session as code changed).
+
+### Test execution
+`bun test` — 697 pass, 0 fail, 1836 `expect()` calls across 55 files (run
+directly; includes this review's two new regression tests).
+
+## AC Status
+
+| Criterion | Status | Notes |
+|---|---|---|
+| AC1: `install` writes a provenance sidecar (source, subpath, commit, timestamp, content hash); `--force` overwrites it | ✅ Done | Tested at unit (provenance.test.ts) and CLI level (cli.test.ts) |
+| AC2: sidecar has its own filename, excluded from scan.ts, `listSupportingFiles`, and sync.ts's managed-entries bookkeeping | ✅ Done | Exclusion lives in `listSupportingFiles`; sync.ts needs no change since its bookkeeping operates one directory level up (target roots, not skill dirs) — confirmed via AC12 test |
+| AC3: `skillmux outdated [--json]` lists sidecar-carrying skills as up-to-date/outdated via `git ls-remote`; no-sidecar skills omitted, not flagged | ✅ Done | Fixed during review: a corrupt sidecar is now `check_failed`, not a crash |
+| AC4: a per-skill remote check failure doesn't abort the rest; drives `checks_failed` and exit code | ✅ Done | Extended during review to cover local parse failures, not just network ones |
+| AC5: `update [skill-id]` supports single-skill and batch (every sidecar-carrying skill `outdated` would report as outdated) | ✅ Done | Tested both modes |
+| AC6: re-fetches from the sidecar's recorded repo URL + subpath, no repo argument needed | ✅ Done | `resolveCandidateOrigins` reads `origin.source_url`/`skill_path` directly |
+| AC7: refuses a locally-drifted skill unless `--force` | ✅ Done | Tested refusal and `--force` override |
+| AC8: runs the install-time scan gate per skill before any write; a scan failure skips that skill without blocking others | ✅ Done | Tested with `--fail-on high` |
+| AC9: `--dry-run` reports old/new SHA and whether content changed, for both single and batch | ✅ Done | Tested both modes |
+| AC10: a real update requires `--yes` non-interactively/`--json`, or an interactive prompt; confirmation covers the post-filter write set; sidecar rewritten on success | ✅ Done | Confirmation set is exactly `plan.filter(kind === "update")`, matching AC10's "after drift and scan filtering" |
+| AC11: `update <skill-id>` with no sidecar fails clearly; bare `update` with nothing outdated succeeds as a no-op | ✅ Done | Tested both |
+| AC12: neither command touches `skillmux.toml`-pinned core/project skills or the `.skillmux`/`SkillmuxMarker` sync machinery | ✅ Done | Explicit regression test against a live sync target |
+| AC13: `docs/cli.md` documents `outdated`/`update`; `docs/schema.json` documents the sidecar shape | ✅ Done (with a documented deviation) | Docs landed in `docs/skill-management.md` instead of `docs/cli.md`, matching where `install`/`scan` are actually documented (cli.md's real scope is global CLI mechanics, not the skill-lifecycle command family). `docs/schema.json` was deliberately left unchanged: its own scope is the MCP wire contract + config.toml — the prior fetch-outcome-flywheel feature set this precedent by never merging its own CLI-only output types (`PruneOutput`, `ReportOutput`, etc.) there either, and this feature adds no MCP tool or config.toml surface |
+
+## Back-edge notes
+
+No back-edge to `/sdd-spec` or `/sdd-schema` was required — the crash bug
+was a robustness gap in an edge case the spec didn't anticipate (a
+*corrupted local file*, distinct from AC3's "no sidecar" and AC4's
+"unreachable remote"), not a case where the spec's stated criteria were
+wrong or the implementation contradicted them. Fixed forward, consistent
+with AC3/AC4's stated intent. Worth a light AC3/AC4 wording touch-up next
+time this spec is revisited, to name "corrupt sidecar" explicitly alongside
+"unreachable remote" — not urgent enough to reopen the spec now.
+
+`docs/schema.json` scope (see AC13 above) is a considered interpretation
+correction, not a back-edge: AC13's literal text assumed the `.skillmux`
+marker and CLI output shapes were already documented there, which a check
+during `/sdd-schema` showed was never true even for the precedent feature.