@metamynd/agentsafe-signer 0.13.0

package/README.md

@@ -0,0 +1,382 @@
+# AgentSafe Signer — the local key-custody daemon
+
+Reference implementation of [`docs/design/agent-key-custody-local-signer-daemon-plan.md`](../../docs/design/agent-key-custody-local-signer-daemon-plan.md).
+A separate OS process holds an agent's or a service's Ed25519 signing key — `agentsafe-guard`/
+`agentsafe-mcp-guard` never hold it themselves — and exposes a small, closed set of signing
+operations over a local socket. The key never enters the calling guard's own process, encrypted
+or otherwise, under any code path.
+
+**This is a first implementation pass, not the finished design.** It exists to make the protocol,
+key storage, and socket layer real and tested, not to claim every property the design doc
+describes is fully delivered yet. See "Status" below for exactly what that means.
+
+## Try it
+
+```bash
+npm test   # daemon-protocol + daemon-key-exfiltration + kek-backends + service-installer + daemon-log-integrity, offline, no network
+```
+
+```bash
+node cli.mjs start --state-dir ./.signer --role agent --admin
+```
+
+Resolves the KEK from a real OS-keychain backend automatically (see "OS-keychain KEK backends"
+below) — no passphrase needed unless none is available on the host, in which case it says so and
+tells you what to set. Opens the signing socket (always on) and the admin socket (closes after one
+`generate-key` call or 60s, whichever comes first — see the design doc's "The admin interface").
+
+## Status
+
+**Implemented and tested:**
+- The full eight-operation signing-socket protocol (`sign-authorize`, `sign-envelope`,
+  `sign-handshake-nonce`, `sign-key-control-challenge`, `sign-log-checkpoint`,
+  `sign-local-decision`, `get-identity`, `ping`) and the two-operation admin socket
+  (`generate-key`, `status`), matching the design doc's closed operation set exactly — no generic
+  "sign this string" primitive.
+- Canonical message construction via the *real*, backend-generated `buildAuthMessage`/
+  `envelopeHashFor` (`npm run build:signer-core` from `backend/`, the same generation mechanism
+  `agentsafe-guard`/`agentsafe-mcp-guard` already use for their own copies) — not a daemon-local
+  reimplementation that could drift.
+- Per-request validation: identity binding (`DAEMON_IDENTITY_MISMATCH`), amount
+  finite/non-negative, no `|` in `action`, `issuedAt` freshness bound at *sign* time (closes the
+  pre-signed-stockpile gap, not just the verifier's own freshness check), role-based operation
+  allow-listing (`DAEMON_OPERATION_NOT_PERMITTED`), a closed `DAEMON_*` error-code set, fail-closed
+  on every rejection.
+- Per-operation rate limiting (sliding window), shadow mode by default per the design doc's own
+  "ship in shadow, promote from real data" guidance — `shadowMode: false` to enforce.
+- Local, append-only logging of every request (operation/timestamp/`requestId`/outcome), verified
+  to never contain key material — both by fuzzing every response and by statically checking the
+  logging call sites' own source.
+- **OS-keychain-backed KEK storage** (`kek-backends.mjs`) — see its own section below for exactly
+  what's verified vs. implemented-but-untested per platform. The passphrase+scrypt path from the
+  first implementation pass is now the last-resort fallback, not the only option.
+- **Wired into both `agentsafe-guard` (0.9.0) and `agentsafe-mcp-guard` (0.5.0)** via the
+  `keyProvider` seam — `keyProvider: 'daemon'` talks to a running instance of this daemon over its
+  socket on either side; the key never enters either guard's own process. Proven end to end by
+  `agentsafe-guard/daemon-keyprovider.smoke.mjs` and `agentsafe-mcp-guard/daemon-keyprovider.smoke.mjs`
+  (a real signer daemon signing for a real guard, both roles).
+- **OS service unit generation** (`service-installer.mjs`) — see its own section below for exactly
+  what "generation" does and, deliberately, does not do.
+- `daemon-protocol.smoke.mjs`, `daemon-key-exfiltration.smoke.mjs`, `kek-backends.smoke.mjs`,
+  `service-installer.smoke.mjs`, `daemon-envelope-parity.smoke.mjs`,
+  `daemon-admin-socket.smoke.mjs`, `daemon-socket-permissions.smoke.mjs`,
+  `daemon-hardening.smoke.mjs` and `daemon-hardening-tier2.smoke.mjs` from the design doc's
+  smoke-test suite, all real and passing, not just named — **all nine now exist as their own
+  files**, which was an open gap in the previous pass.
+- **Socket permissions (T4)** — `daemon-socket-permissions.smoke.mjs` asserts the signing AND admin
+  sockets are mode exactly `0600`, owned by the invoking uid, inside a `0700` directory, read back
+  from the filesystem after a real `listen()`. It carries its own negative control (a deliberately
+  `0666` file must be rejected by the same comparison), and it documents a real window it found:
+  `net.Server.listen()` creates the socket node at `0777 & ~umask` — observed `0755` — and
+  `daemon.mjs` chmods it to `0600` a syscall later. That window is **not** a T4 hole, because
+  traversing to the socket also needs `+x` on its parent, and the parent is created `0700` *before*
+  the bind; the test asserts that directory mode is what closes it, rather than leaving the window
+  undocumented. What it does **not** prove: an actual connect attempt from a second OS user —
+  creating one needs root, so T4 rests here on the permission bits the kernel enforces, not on an
+  observed `EACCES` from a foreign uid. The last two closed with zero bugs found in `daemon.mjs` itself — the underlying
+  behavior (canonical-message parity, the admin socket's own-timeout/one-op-then-close lifecycle)
+  was already correct; these two just prove it rather than leave it merely documented.
+- **A real, ACL-restricted named pipe on Windows** (`windows-secure-pipe.mjs`) — an earlier pass
+  of this README claimed this needed a native addon (see git history); that was wrong. The same
+  shell-to-PowerShell technique already used for DPAPI works here too: .NET's
+  `System.IO.Pipes.NamedPipeServerStream` accepts a real `PipeSecurity` restricting the pipe to
+  the current Windows user (verified: `GetAccessRules().Count === 1`), and a small relay process
+  bridges it to Node's own `net` socket API over the relay's stdio. `toPlatformSocketPath` and
+  `daemon.mjs`'s `startServer` route through it automatically on `win32`; `daemon-protocol.smoke.mjs`
+  and `daemon-admin-socket.smoke.mjs` both exercise the real transport (not a mock) on every run.
+  Two genuine Windows-specific bugs were found and fixed getting here, verified empirically rather
+  than assumed: additional multi-instance pipes need `PipeAccessRights.FullControl`, not
+  `ReadWrite`, or every instance past the first fails with "Access to the path is denied"; and the
+  pipe must be opened with `PipeOptions.Asynchronous`, not `None` — a synchronous handle can't
+  safely run the relay's two concurrent `CopyToAsync` directions at once, and without it a
+  response written back to a connected client was silently lost. A third, subtler bug surfaced
+  only under real concurrent load (several relay processes constructing a
+  `NamedPipeServerStream` with a custom `PipeSecurity` at nearly the same instant, even for
+  DIFFERENT pipe names): one occasionally hangs indefinitely inside the .NET constructor call
+  itself, never reporting readiness and never exiting on its own — with no bound on this, the
+  hang was unrecoverable and propagated all the way up to `daemon.startSigningServer`/
+  `startAdminServer`'s own callers. Fixed with a per-attempt construction timeout
+  (`SPAWN_TIMEOUT_MS`) that kills a stuck attempt and retries (bounded, `MAX_SPAWN_ATTEMPTS`, for
+  the one-shot admin socket; unbounded, matching its own "always on" design, for the signing
+  socket's pool) — self-healing rather than assuming the first attempt always succeeds.
+- **Local, tamper-evident log hash-chaining** (`log-checkpoint.mjs`, T11 — "the covered half"):
+  the daemon periodically (`DEFAULT_CHECKPOINT_INTERVAL_MS`, 15 minutes) batches whatever new lines
+  have accumulated in `signer.log` since the last checkpoint, hashes each line's exact stored
+  bytes, builds a Merkle root over the batch (`merkle.mjs`, the same algorithm
+  `backend/src/features/magp/merkle.ts` already uses — ported rather than imported, since this
+  package has no dependency on the backend or any sibling package, by design), and chains that
+  root to the previous checkpoint's own hash. `agentsafe-signer verify-log --state-dir <dir>`
+  recomputes the whole chain directly from the log's own bytes and reports the exact checkpoint
+  where tampering was introduced, if any — proven by `daemon-log-integrity.smoke.mjs` actually
+  flipping a byte inside an already-checkpointed line and confirming both the direct API and the
+  real CLI subcommand detect it, not just that an untouched chain verifies. This closes the
+  "covered half" of T11 named in the design doc's own threat model; it does **not**, on its own,
+  stop an attacker who controls both the log and the checkpoints file from rewriting both
+  consistently — that needs a checkpoint's hash anchored somewhere outside this host, which is a
+  separate, still-outstanding piece (see below).
+
+**Also implemented and tested, since this section was last written accurately:**
+- **Externally anchoring a checkpoint hash (the rest of T11).** `log-anchor.mjs` asks the daemon to
+  sign each pending checkpoint (`sign-log-checkpoint`) and submits it to the backend's
+  `POST /evidence/signer-checkpoint` (DID-signature-authenticated, not session-based — a headless
+  daemon has no user session to present), which anchors it via HCS. Idempotent, capped at
+  96 anchors/agent/day. `agentsafe-signer log-anchor` CLI subcommand; `log-anchor.smoke.mjs`.
+- **A real migration/fresh-provisioning CLI.** `agentsafe-signer migrate` drives
+  `rotateNetworkIdentity` end to end (generate-key → rotate → sign-key-control-challenge →
+  verify-key — the proof-of-possession trio that didn't exist for BYOK network identities until
+  this was built); `create-metamynd-agent --byok --daemon-socket` drives fresh provisioning the
+  same way. Both routed through the daemon; the private key never enters either CLI's process.
+- **Real `mlock()`/`VirtualLock()` protection for the decrypted key.** `secure-memory.mjs`, backed
+  by `sodium-native` (this package's only dependency, added deliberately — this specific property
+  cannot be reached via a shell-out the way every other gap here was closed, since it must run
+  inside the process that owns the memory). `secure-memory.smoke.mjs`.
+- **Core-dump-disable and Linux `ptrace`-denial**, closed declaratively rather than in the daemon's
+  own runtime code: the generated systemd units now prefix `ExecStart=` with
+  `setpriv --dumpable 0 --` (a real binary, no shell needed — ptrace-deny, pairs with the
+  already-present `LimitCORE=0`), and the generated launchd plist routes through `/bin/sh -c
+  'ulimit -c 0; exec "$@"'` (launchd has no `LimitCORE`-equivalent key, and `ulimit` is a shell
+  builtin) — both a true `exec()` chain, never a forked supervisor process. **Disclosed, not
+  closed**: macOS has no `ptrace`-deny reachable this way at all — `PT_DENY_ATTACH` must be called
+  *by* the target process itself via a syscall, the same architectural limitation `secure-memory.mjs`
+  discloses for `mlock()`.
+- **`sign-local-decision`, closing the gap left when local-decision audit reporting first
+  shipped.** A daemon-custody agent can now sign its own local-first block/escalate/non-value-allow
+  verdict for `POST /policy/decisions/local` the same way the static-key provider always could —
+  `agentsafe-guard`'s `createDaemonKeyProvider` gained the matching client method. Agent-role only,
+  same as `sign-authorize`/`sign-envelope` (a service-role daemon never evaluates a mandate
+  locally). `daemon-protocol.smoke.mjs`, `daemon-envelope-parity.smoke.mjs`.
+
+**Deliberately not yet implemented — real gaps, not oversights:**
+- **The generated systemd unit has never started a daemon.** Running it for real on Ubuntu 24.04
+  LTS / systemd 255 (the first time this was tried on any Linux host) found five defects in a
+  single `ExecStart` line, four of them fatal before any daemon code ran. Three are fixed here;
+  two remain and are listed under "OS service unit generation" below. Until those two are closed,
+  `cli.mjs install`'s output is a template to adapt, not something that runs as generated.
+- `daemon-hardening.smoke.mjs` **currently fails** — on the two real defects above, not on a test
+  bug. That is deliberate: it is the assertion that would have caught them, and greening it by
+  weakening it would restore the exact blind spot that let a never-runnable unit ship.
+- All the smoke tests the design doc names now exist as their own files:
+  `daemon-socket-permissions.smoke.mjs` (T4), `daemon-hardening.smoke.mjs` (Tier 1) and
+  `daemon-hardening-tier2.smoke.mjs` (Tier 2, verified against a real system unit — see above). **Log integrity** is its own real file
+  (`daemon-log-integrity.smoke.mjs`, above) — though it covers only the local hash-chain half of
+  T11, not the external-anchoring half, which remains open per the bullet above.
+
+## Hardening tiers — what a real host actually confirms (T3, T5)
+
+`daemon-hardening.smoke.mjs` checks the tier directives **from outside** the process, against the
+kernel's own view, never by trusting the unit file's text (`service-installer.smoke.mjs` already
+covers the text; these are different questions, and the `setpriv` defect above is exactly what
+happens when only the text is checked). It reports three outcomes, not two — `ok`, `FAIL`, and
+**INCONCLUSIVE** — because on this axis a green check that would stay green with the hardening
+removed is worse than no check.
+
+Confirmed on Ubuntu 24.04.4 / systemd 255:
+
+- **`LimitCORE=0` works.** A live service process reported `Max core file size 0 0` in
+  `/proc/<pid>/limits`, soft *and* hard, with a negative control proving an unconstrained process
+  on the same host reports `unlimited` — so the check is reading the directive, not the host
+  default.
+- **`SocketMode=0600`/`DirectoryMode=0700` work** on the real `%t/agentsafe/` path (see above).
+
+Reported INCONCLUSIVE rather than passed, at Tier 1:
+
+- **`ptrace` denial (T3).** This host runs `kernel.yama.ptrace_scope=1`, which already denies a
+  same-UID sibling's `PTRACE_ATTACH` for *every* process, hardened or not. An `EPERM` here is the
+  ambient LSM policy, not evidence the unit hardened anything, so the test says so instead of
+  banking the pass. Distinguishing the two needs `ptrace_scope=0`, a root-only host change.
+
+### Tier 2 is now verified against a real system unit
+
+`daemon-hardening-tier2.smoke.mjs` is the second file the design doc names, and it decides what the
+Tier 1 file structurally cannot: `DynamicUser=` is a **system**-manager feature, so a
+`systemctl --user` service always runs as the invoking user and can never demonstrate it. Run
+against a Tier 2 unit installed at `/etc/systemd/system/` on Ubuntu 24.04.4 / systemd 255, audited
+from an ordinary unprivileged shell:
+
+| Claim | Result |
+|---|---|
+| The daemon runs under a genuinely separate UID | **Verified** — uid `64750`, user `agentsafe-signer`, against an invoking uid of `1000` |
+| A same-user `PTRACE_ATTACH` is refused (T3) | **Verified** — `EPERM`, from a real `PTRACE_ATTACH` probe, not from the unit's declared text |
+| The daemon's `/proc` entries are unreadable to the agent's own account | **Verified** — `/proc/<pid>/environ` returns `EACCES` |
+| `RemoveIPC=true` and `DynamicUser=true` are live on the loaded unit | **Verified** — `systemctl show` reports `yes` for both |
+| Its state directory is out of reach of the invoking user | **Verified indirectly** — `/var/lib/private` is `0700 root`, so uid 1000 cannot even traverse to it |
+
+**This is also what closes the Tier 1 namespacing caveat below.** The Tier 2 unit sets
+`PrivateTmp=true` and `PrivateDevices=true` — the two directives that, at Tier 1, flipped a
+same-UID `PTRACE_ATTACH` from `EPERM` to success. With both live and `yama.ptrace_scope=1`, the
+cross-UID attach was still refused, because that refusal is the ordinary permission check and owes
+nothing to Yama. Tier 2 does not inherit the Tier 1 hole; it closes it. The test asserts this
+contrast directly rather than leaving it as prose here.
+
+Still INCONCLUSIVE even with root, and reported as such:
+
+- **`RemoveIPC`'s functional reap.** The directive is confirmed *live* on the loaded unit, which is
+  what the unit is responsible for. Observing the reap itself means creating IPC objects as the
+  dynamic user and then stopping the unit — privileged and destructive, and systemd's behavior
+  rather than this package's, so the read-only audit does not do it.
+- **Direct `stat` of the state directory.** `/var/lib/private/<name>` is root-only traversable, so
+  the ownership check cannot read through it unprivileged. That is consistent with the isolation
+  being real, and is reported as unproven rather than inferred.
+
+Two things the installation surfaced that are worth repeating, because neither is obvious from the
+unit file:
+
+- **Tier 2 cannot use a home-directory interpreter.** `nodePath` defaults to `process.execPath`,
+  which is correct at Tier 1 (the unit runs as the invoking user) and **wrong** at Tier 2: a
+  `DynamicUser` account is a different UID and cannot traverse a `0750` home, which is the Ubuntu
+  default. On the test host the dynamic user could reach neither the nvm `node` binary nor the
+  package under `~`. `cli.mjs install` now takes `--node-path` and **warns** when a Tier 2
+  `ExecStart` resolves under `/home`; the package itself needs a system path too
+  (`/usr/local/share/agentsafe/signer/`, as the design doc already specifies).
+- **The privileged step stayed a human step.** The design doc requires it ("must always be a
+  printed instruction the operator runs themselves, never something the installer executes on their
+  behalf"), and `service-installer.smoke.mjs` asserts by source inspection that this package never
+  shells out to `systemctl`. The verification above was done by handing the operator a script to
+  run, not by the test installing anything.
+
+**A counterintuitive result worth re-measuring on your own target host.** While establishing the
+Yama baseline, bisecting one directive at a time and reproducing across rounds: a plain
+`systemd-run --user` node process correctly refused `PTRACE_ATTACH` (`EPERM`), but adding **either**
+`PrivateTmp=true` **or** `PrivateDevices=true` — both of which the generated unit sets — flipped the
+identical process to `ATTACH_SUCCEEDED`. On such a host the "hardened" unit is *more* ptrace-exposed
+than an unhardened one. This was measured, not derived from documentation, and the underlying kernel
+mechanism was not chased down; it is recorded here as a caveat, and the test emits it as a standing
+INCONCLUSIVE whenever the unit contains those directives and Yama is active. It does not change the
+guidance — Tier 2's dedicated UID was already the mitigation the threat model relies on for T3, and
+Tier 1 was always documented as "partial" there — but it does mean Tier 1 should not be assumed to
+inherit host Yama protection.
+
+One methodological note, since it produced a misleading result before it was caught: a `ptrace`
+probe that calls `PTRACE_ATTACH` and then `PTRACE_DETACH` without an intervening `waitpid()` races,
+and can leave the target in `T (stopped)` with `TracerPid: 0` — i.e. it silently stops the service
+it was auditing. That is what happened here, and the daemon had to be `SIGCONT`ed back. Any probe
+used for this check needs to wait for the stop before detaching.
+
+## OS service unit generation
+
+`service-installer.mjs` generates the real systemd/launchd/Windows unit content from the design
+doc's own templates — parameterized by identity and tier — and `cli.mjs install` writes them to a
+local `--out-dir` you choose. **It never writes to a real system service location
+(`~/.config/systemd/user`, `/etc/systemd/system`, `~/Library/LaunchAgents`, the Windows service
+registry) and never runs `systemctl`/`launchctl`/`sc.exe` itself** — verified by
+`service-installer.smoke.mjs`'s own static check of the module's source, not just asserted in
+this paragraph. It prints the exact command to actually install the result; running that command
+is always a separate, deliberate, human step — registering a real system service is a genuine
+system modification, deliberately out of scope for what this module does on its own.
+
+```bash
+node cli.mjs install --identity <did> --daemon-path /opt/agentsafe/signer/daemon.mjs \
+  --platform linux --tier 2 --out-dir ./service-units
+```
+
+Tested: the Tier 1/Tier 2 content differences match the design doc exactly (the `%h`-vs-absolute
+`ExecStart` path and the `RemoveIPC=true` placement — both real bugs the code-review pass on the
+design doc itself caught before any of this was written) for systemd; the launchd plist's
+`SockPathMode`/`RunAtLoad`/`KeepAlive` values; and the Windows `sc.exe` argv shape (Virtual Service
+Account, no password to manage).
+
+**Now also tested, for the first time, by actually installing and starting it** (Ubuntu 24.04.4
+LTS, systemd 255, `systemctl --user`). The socket unit works: systemd created
+`%t/agentsafe/signer-%i.sock` at mode `0600` in a `0700` directory, owned by the invoking user —
+`SocketMode=`/`DirectoryMode=` take effect exactly as written, which is T4 confirmed on the real
+deployment path rather than only in a temp dir. `LimitCORE=0` also verifiably takes effect:
+`/proc/<pid>/limits` on the live process reported `Max core file size 0 0`, read from outside the
+process.
+
+The **service** unit did not start. Five defects in one `ExecStart` line, each found only by
+running it:
+
+| # | Defect | Symptom | Status |
+|---|---|---|---|
+| 1 | `setpriv --dumpable 0 --` wrapper | util-linux's `setpriv` **has no `--dumpable` option** (checked on util-linux 2.39.3; the string is absent from the binary). Unit died at exec: `setpriv: unrecognized option '--dumpable'`, `status=1/FAILURE` | **Fixed** — wrapper removed |
+| 2 | `%h/` prefixed onto an **absolute** `--daemon-path` | `ExecStart` resolved to `/home/u/home/u/...`; the CLI's own documented example passes an absolute path, so this was the common case | **Fixed** — `%h` now applied only to a relative path |
+| 3 | `nodePath` defaulting to `/usr/bin/node` | Absent on any nvm/asdf/volta host (this one had node only under `~/.nvm`); systemd reports a bare `203/EXEC` with no hint which binary was missing | **Fixed** — defaults to `process.execPath` |
+| 4 | `MemoryDenyWriteExecute=true` | V8 is a JIT; its `mprotect` fails with `ENOMEM` inside `v8::base::OS::SetPermissions` during Isolate init and node dies with `SIGTRAP` (`Check failed: 12 == errno`) before running any daemon code. **No Node service can set this directive** | **Fixed** — removed from both tiers |
+| 5 | `ExecStart` points at `daemon.mjs` | `daemon.mjs` is a library module with no argv handling — `node daemon.mjs` returns 0 immediately and serves nothing | **Fixed** — `ExecStart` now runs `cli.mjs start --state-dir %S/agentsafe/%i --role <role> --identity %i` |
+| 6 | `Type=notify` | Nothing in the package sends `sd_notify READY=1`, so systemd fails the unit with `Result: protocol` even though node is healthy and listening | **Fixed** — `Type=exec`, which still waits for a successful `execve()` without requiring the notify protocol |
+
+**With all six fixed, the generated unit now starts and serves.** Verified by installing the
+generator's own output unmodified (plus a drop-in supplying `AGENTSAFE_SIGNER_PASSPHRASE`, since
+no OS-keychain backend works on that host — see below): `systemctl --user start` reached
+`active (running)`, the daemon unlocked, and a real `ping` over its socket returned
+`{"ok":true,"result":{"status":"ok","unlocked":true}}`. `LimitCORE=0` was confirmed on that live
+process from outside it (`/proc/<pid>/limits`: `Max core file size 0 0`).
+
+### Still open: socket activation is declared but not implemented
+
+The generated `.socket` unit is real and works on its own — systemd creates and listens on
+`%t/agentsafe/signer-%i.sock` at `0600` — but **the daemon never accepts that socket**. Nothing in
+`daemon.mjs` or `cli.mjs` reads `LISTEN_FDS`/`LISTEN_PID`, so `cli.mjs start` binds its own socket
+at `<state-dir>/signer.sock` instead. Measured on the running unit, the two paths are simply
+different:
+
+```
+socket unit listens on : /run/user/1000/agentsafe/signer-1c741375.sock   (%t/…)
+daemon listens on      : ~/.local/state/agentsafe/1c741375/signer.sock   (%S/…)
+```
+
+So a client that connects to the systemd socket triggers the service and then talks to nobody;
+`Requires=…​.socket` currently buys the ordering relationship and nothing else. Consumers should
+point at the daemon's own `<state-dir>/signer.sock` until this is closed.
+
+Closing it properly means implementing the sd_notify/`LISTEN_FDS` protocol in the daemon — a real
+feature, not a generator tweak, and deliberately out of scope for this verification pass in the
+same way the macOS ptrace-deny gap above is: disclosed as a first-implementation-pass limit rather
+than quietly left for someone to discover in production. Also still untested: launchd and Windows
+installation, unchanged from the previous pass.
+
+## OS-keychain KEK backends
+
+`kek-backends.mjs` tries a real platform backend first, in order, and only falls back to
+passphrase+scrypt if none is available — always printing which one was actually used, so an
+operator can see what's protecting their key rather than assume.
+
+**A backend "being available" and "actually working" are checked separately.** `available()` only
+proves the tool exists and runs (e.g. `systemd-creds --version` exits 0) — it can't cheaply prove
+the backend can actually encrypt/decrypt in this environment. Caught for real, not hypothesized:
+wiring `agentsafe-signer`'s tests into CI (`ubuntu-latest`) found that `systemd-creds` is present
+and passes its own `--version` check there, but `systemd-creds encrypt` fails with "Failed to
+determine local credential host secret: Permission denied" — the runner has no host/TPM secret
+for it to use. `resolveKek()` now catches a failure from the selected backend and falls through to
+the next one (down to `passphrase` as the last resort) instead of crashing the daemon — a backend
+that is present but unusable is not meaningfully different from one that is absent.
+
+| Platform | Backend | Mechanism | Verified in this pass? |
+|---|---|---|---|
+| Windows | `dpapi` | `ProtectedData.Protect`/`Unprotect` (`CurrentUser` scope), via a PowerShell one-liner — no native addon | **Yes** — real protect/unprotect round-trip, including a simulated daemon restart (`kek-backends.smoke.mjs`), run on the actual development machine for this pass |
+| macOS | `macos-keychain` | `security add-generic-password`/`find-generic-password` | No — implemented per `man security`'s documented behavior, never run against a real macOS host |
+| Linux | `systemd-creds` | `systemd-creds encrypt`/`decrypt` (TPM- or machine-ID-backed) — tried first, fits the Tier 2 systemd-service deployment model this daemon targets | **Still no.** Retried on a real Ubuntu 24.04 / systemd 255 host and it failed there too, with the *same* error as CI: `Failed to determine local credential host secret: Permission denied`. Root cause now pinned rather than guessed (see below) |
+| Linux (no systemd-creds) | `secret-tool` | Secret Service (GNOME Keyring/KWallet) via `secret-tool store`/`lookup` | **Still no, and not testable on that host.** `secret-tool` is not installed, no keyring daemon is running, and `org.freedesktop.secrets` is neither on the session bus nor D-Bus-activatable — so there was no Secret Service to exercise. Installing a keyring purely to make the test pass would prove nothing about a real desktop host, so it was not done |
+| Any (no backend available, or every available one failed) | `passphrase` | `AGENTSAFE_SIGNER_PASSPHRASE` + scrypt (unchanged from the first pass) | Yes (carried over), but explicitly the weakest tier — the daemon says so out loud when it's the one in use |
+
+**Why `systemd-creds` fails on a normal Linux host, precisely.** It needs one of two secrets, and
+a non-root user can obtain neither:
+
+- **Host secret** — `/var/lib/systemd/credential.secret`, created by `systemd-creds setup`. The
+  file does not exist by default and `/var/lib/systemd` is `root:root 0755`, so creating it needs
+  root. This is the `Permission denied` above, on a real host and on CI alike; CI was not the
+  anomaly.
+- **TPM2** — `systemd-creds encrypt --with-key=tpm2` returns `Failed to create TPM2 context:
+  Operation not supported`; the host has no `/dev/tpm*` at all.
+
+There is no user-scoped alternative: `systemd-creds` has no `--user` flag (systemd 255). So on any
+host where the operator cannot run `systemd-creds setup` as root, and which has no TPM, this
+backend can only ever be *present-but-unusable* — which `resolveKek` already handles by falling
+through. Verified end-to-end on that path: with `AGENTSAFE_SIGNER_PASSPHRASE` set,
+`kek-backends.smoke.mjs` passes with `backend actually used on this host: passphrase`, having
+logged the `systemd-creds` failure and moved on. With no passphrase either, `resolveKek` throws
+and the test exits non-zero — correct fail-closed behavior, but worth knowing before running the
+suite on a bare Linux box.
+
+**Before trusting the macOS/Linux backends in production**, run `kek-backends.smoke.mjs` on the
+real target OS — it's written to exercise whichever backend `resolveKek` actually selects, so the
+same test file is the real verification step for those platforms too, not new tooling to build.
+
+## Regenerating the bundled canonical-message logic
+
+```bash
+cd ../../backend && npm run build:signer-core
+```
+
+Regenerates `policy-core.mjs` and `governance-envelope.mjs` from their real TypeScript sources —
+never hand-edit those two files.

package/cli.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// cli.mjs — starts the signer daemon. Resolves the KEK from a real OS-keychain backend when one
+// is available (kek-backends.mjs), falling back to a passphrase only when none is — see that
+// module's own header and README.md "Status" for exactly which backends are verified vs.
+// implemented-but-untested-on-a-real-host in this pass.
+import fs from 'node:fs';
+import path from 'node:path';
+import { SignerDaemon } from './daemon.mjs';
+import { deriveKek, loadOrCreateSalt } from './keystore.mjs';
+import { resolveKek } from './kek-backends.mjs';
+import { generateSystemdUnits, generateLaunchdPlist, generateWindowsService } from './service-installer.mjs';
+import { verifyLogCheckpoints, listCheckpoints } from './log-checkpoint.mjs';
+import { runLogAnchor } from './log-anchor.mjs';
+import { runMigrate } from './migrate.mjs';
+import { parseArgs } from './daemon-client.mjs';
+
+/**
+ * Writes generated unit files to `--out-dir` (a local directory, NEVER a real system service
+ * location) and prints the exact command an operator runs to actually install them. Never invokes
+ * systemctl/launchctl/sc.exe itself — see service-installer.mjs's own header for why.
+ */
+function runInstall(args) {
+  const platform = args.platform ?? process.platform;
+  const tier = args.tier === '2' || args.tier === 2 ? 2 : 1;
+  const identity = args.identity;
+  const daemonPath = args['daemon-path'] ?? path.join(process.cwd(), 'daemon.mjs');
+  const outDir = args['out-dir'] ?? path.join(process.cwd(), 'service-units');
+  // --node-path matters most at Tier 2. The generator defaults to process.execPath, which is
+  // correct at Tier 1 (the unit runs AS the invoking user, so their nvm/asdf node is reachable)
+  // but wrong at Tier 2: a DynamicUser account is a different UID and cannot traverse a home
+  // directory that is mode 0750, which is the Ubuntu default. Verified on a real host — the
+  // dynamic user could reach neither the nvm node binary nor the package under ~. Tier 2 needs an
+  // interpreter on a system path, and this is how the operator names it.
+  const nodePath = args['node-path'];
+  const role = args.role === 'service' ? 'service' : 'agent';
+  if (!identity) {
+    console.error('agentsafe-signer install requires --identity <agentDid or serviceDid>');
+    process.exit(1);
+  }
+  fs.mkdirSync(outDir, { recursive: true });
+
+  if (platform === 'linux') {
+    const { socketUnit, serviceUnit, id, enableCommand } = generateSystemdUnits({ identity, tier, daemonPath, role, ...(nodePath ? { nodePath } : {}) });
+    fs.writeFileSync(path.join(outDir, `agentsafe-signer@${id}.socket`), socketUnit);
+    fs.writeFileSync(path.join(outDir, `agentsafe-signer@${id}.service`), serviceUnit);
+    console.log(`Wrote systemd unit files to ${outDir}`);
+    console.log(`Tier ${tier} — copy them into place, then run:\n  ${enableCommand}`);
+    if (tier === 2 && /^\/home\/|^\/Users\//.test(serviceUnit.match(/^ExecStart=(\S+)/m)?.[1] ?? '')) {
+      console.warn(
+        '\n[warning] Tier 2 runs under DynamicUser=true — a separate UID that usually CANNOT read a\n' +
+        '          home directory (0750 by default). The ExecStart interpreter above is under /home,\n' +
+        '          so this unit will fail to start. Pass --node-path /usr/local/bin/node (or another\n' +
+        '          system path) and install the package somewhere system-wide, e.g.\n' +
+        '          /usr/local/share/agentsafe/signer/.');
+    }
+  } else if (platform === 'darwin') {
+    const { plist, plistFileName, enableCommand } = generateLaunchdPlist({ identity, tier, daemonPath, socketDir: outDir });
+    fs.writeFileSync(path.join(outDir, plistFileName), plist);
+    console.log(`Wrote launchd plist to ${outDir}`);
+    console.log(`Copy it into ~/Library/LaunchAgents/, then run:\n  ${enableCommand}`);
+  } else if (platform === 'win32') {
+    const { serviceName, enableCommand } = generateWindowsService({ identity, daemonPath });
+    fs.writeFileSync(path.join(outDir, `${serviceName}.install.txt`), enableCommand + '\n');
+    console.log(`Wrote the sc.exe install command to ${path.join(outDir, `${serviceName}.install.txt`)}`);
+    console.log(`Run it yourself, from an elevated prompt:\n  ${enableCommand}`);
+  } else {
+    console.error(`Unsupported --platform "${platform}" — use linux, darwin, or win32.`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Recomputes every local log checkpoint (T11) directly from signer.log's own bytes and reports
+ * whether the chain is intact — the operator-facing proof that the daemon's own request log
+ * hasn't been tampered with since it was last checkpointed. Read-only: never touches the log or
+ * checkpoints file, and never touches the network (see log-anchor.mjs for the separate, optional,
+ * live step that anchors a checkpointHash externally).
+ */
+function runVerifyLog(args) {
+  const stateDir = args['state-dir'] ?? path.join(process.cwd(), '.agentsafe-signer');
+  const checkpoints = listCheckpoints(stateDir);
+  if (checkpoints.length === 0) {
+    console.log(`[agentsafe-signer] no checkpoints yet in ${stateDir} — nothing to verify.`);
+    return;
+  }
+  const result = verifyLogCheckpoints(stateDir);
+  const anchoredCount = checkpoints.filter((cp) => cp.anchoredAt).length;
+  console.log(`[agentsafe-signer] ${checkpoints.length} checkpoint(s), ${anchoredCount} anchored, ${checkpoints.length - anchoredCount} pending.`);
+  if (result.ok) {
+    console.log(`[agentsafe-signer] OK — the log hash-chain verifies clean across all ${result.checkedCount} checkpoint(s).`);
+    return;
+  }
+  console.error(`[agentsafe-signer] TAMPER DETECTED at checkpoint index ${result.failedIndex}: ${result.reason}`);
+  process.exit(1);
+}
+
+/**
+ * Anchors every pending local checkpoint (T11) via the backend's /evidence/signer-checkpoint
+ * endpoint — the separate, optional, LIVE-NETWORK step; requires an already-running daemon at
+ * `--socket-path` to sign each anchor request, since only the daemon holds the key. See
+ * log-anchor.mjs's own header for why this is a separate script rather than a daemon feature.
+ */
+async function runLogAnchorCommand(args) {
+  const stateDir = args['state-dir'] ?? path.join(process.cwd(), '.agentsafe-signer');
+  const socketPath = args['socket-path'] ?? path.join(stateDir, 'signer.sock');
+  const apiUrl = args['api-url'] ?? process.env.AGENTSAFE_SIGNER_API_URL;
+  if (!apiUrl) {
+    console.error('agentsafe-signer log-anchor requires --api-url <backend base url> (or AGENTSAFE_SIGNER_API_URL)');
+    process.exit(1);
+  }
+  const failed = await runLogAnchor({ stateDir, socketPath, apiUrl });
+  if (failed > 0) process.exit(1);
+}
+
+/**
+ * Rotates an existing agent's network identity onto a fresh, daemon-generated key
+ * (rotateNetworkIdentity's real BYOK + proof-of-possession flow — see migrate.mjs's own header
+ * for exactly why this exists and what it requires). Requires the daemon's admin socket to be
+ * open right now (`agentsafe-signer start --admin`).
+ */
+async function runMigrateCommand(args) {
+  const stateDir = args['state-dir'] ?? path.join(process.cwd(), '.agentsafe-signer');
+  const socketPath = args['socket-path'] ?? path.join(stateDir, 'signer.sock');
+  const adminSocketPath = args['admin-socket-path'] ?? path.join(stateDir, 'signer-admin.sock');
+  const apiUrl = args['api-url'] ?? process.env.AGENTSAFE_SIGNER_API_URL;
+  const authToken = args['auth-token'] ?? process.env.AGENTSAFE_SIGNER_AUTH_TOKEN;
+  const ref = args.ref;
+  const networkIdentityId = args['network-identity-id'];
+
+  const missing = [];
+  if (!apiUrl) missing.push('--api-url (or AGENTSAFE_SIGNER_API_URL)');
+  if (!authToken) missing.push('--auth-token (or AGENTSAFE_SIGNER_AUTH_TOKEN)');
+  if (!ref) missing.push('--ref <agentIdentityId or DID>');
+  if (!networkIdentityId) missing.push('--network-identity-id <id>');
+  if (missing.length > 0) {
+    console.error(`agentsafe-signer migrate requires: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log('[migrate] asking the daemon to generate a fresh key (requires --admin to be open right now)...');
+  const result = await runMigrate({ stateDir, socketPath, adminSocketPath, apiUrl, authToken, ref, networkIdentityId });
+  console.log(`[migrate] rotated to ${result.did} and verified proof of possession.`);
+  console.log('[migrate] restart the daemon bound to the new identity:');
+  console.log(`  ${result.restartCommand}`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+  if (command === 'install') return runInstall(args);
+  if (command === 'verify-log') return runVerifyLog(args);
+  if (command === 'log-anchor') return runLogAnchorCommand(args);
+  if (command === 'migrate') return runMigrateCommand(args);
+  if (command !== 'start') {
+    console.error('Usage: agentsafe-signer start --state-dir <dir> --role agent|service [--identity <did>] [--admin] [--allow-rekey]');
+    console.error('   or: agentsafe-signer install --identity <did> --daemon-path <path> [--platform linux|darwin|win32] [--tier 1|2] [--role agent|service] [--node-path <path>] [--out-dir <dir>]');
+    console.error('   or: agentsafe-signer verify-log --state-dir <dir>');
+    console.error('   or: agentsafe-signer log-anchor --state-dir <dir> --api-url <backend base url>');
+    console.error('   or: agentsafe-signer migrate --state-dir <dir> --api-url <backend base url> --auth-token <token> --ref <agentIdentityId-or-did> --network-identity-id <id>');
+    process.exit(1);
+  }
+
+  const stateDir = args['state-dir'] ?? path.join(process.cwd(), '.agentsafe-signer');
+  const role = args.role;
+  if (role !== 'agent' && role !== 'service') {
+    console.error("--role must be 'agent' or 'service'");
+    process.exit(1);
+  }
+
+  let kek, kekBackend;
+  if (args['kek-backend'] === 'passphrase') {
+    // Explicit opt-out of OS-keychain detection, e.g. for local dev/testing.
+    const passphrase = process.env.AGENTSAFE_SIGNER_PASSPHRASE;
+    if (!passphrase) {
+      console.error('--kek-backend passphrase requires AGENTSAFE_SIGNER_PASSPHRASE to be set.');
+      process.exit(1);
+    }
+    kek = deriveKek(passphrase, loadOrCreateSalt(stateDir));
+    kekBackend = 'passphrase (forced)';
+  } else {
+    try {
+      ({ kek, backend: kekBackend } = resolveKek(stateDir));
+    } catch (err) {
+      console.error(`[agentsafe-signer] ${err.message}`);
+      process.exit(1);
+    }
+  }
+  console.log(`[agentsafe-signer] KEK backend: ${kekBackend}${kekBackend.startsWith('passphrase') ? ' — weaker than an OS-keychain backend, see README.md "Status"' : ''}`);
+
+  const daemon = new SignerDaemon({
+    stateDir,
+    role,
+    agentDid: typeof args.identity === 'string' ? args.identity : null,
+    kek,
+    shadowMode: args.enforce !== true,
+  });
+  await daemon.waitUntilUnlocked();
+
+  await daemon.startSigningServer(path.join(stateDir, 'signer.sock'));
+  console.log(`[agentsafe-signer] signing socket listening: ${path.join(stateDir, 'signer.sock')}`);
+
+  if (args.admin) {
+    const timeoutMs = typeof args['admin-timeout'] === 'string' ? Number(args['admin-timeout']) : 60_000;
+    console.log(`[agentsafe-signer] admin socket open for ${timeoutMs}ms or one operation, whichever comes first`);
+    await daemon.startAdminServer(path.join(stateDir, 'signer-admin.sock'), { timeoutMs });
+    console.log('[agentsafe-signer] admin socket closed');
+  }
+}
+
+main().catch((err) => {
+  console.error('[agentsafe-signer] fatal:', err);
+  process.exit(1);
+});