[DealAppSeo]

Update — offline verification works out of the box (and the CI regression that took, and its fix)

Finding #1 below is fixed. keccak256 for the receipt hash now comes from @noble/hashes (a real dependency), not the optional ethers peer, so a plain npm install @hyperdag/trustshell verifies receipts offline — integrity reads VERIFIED out of the box. The demo's step 8 shows Integrity VERIFIED and the fresh-install smoke test asserts it. ethers stays an OPTIONAL peer, needed only for on-chain reads and x402 signing (erc8004, verify-signer, x402-prepare). Argument hashing and kernelDecide no longer need ethers either.

Two commits, and I'm being open about the first one's mistake because catching it is the point:

• dca4a1f4 moved keccak to @noble/hashes — but imported it at the top of kernel-client.ts. index.ts imports that module at startup, so the whole CLI then needed @noble merely to load. Two test suites (learn-hook, and egress via scripts/check-egress.cjs) compile the CLI to a bare temp dir with no reachable node_modules and run it there — so in CI every subcommand, even non-hashing ones like guard/inspect, crashed at startup with MODULE_NOT_FOUND. That turned the CI check job red on tests/egress.test.ts and tests/learn-hook.test.ts. It passed on my local machine only because the temp dir happens to resolve @noble up-tree — a difference I should not have trusted, and the CI rerun (identical failure both times) is what proved it was mine, not flake.
• 9f7e0939 resolves @noble lazily, on first hash, instead of at module load (the hash functions are already async). Loading the CLI no longer requires it; a real npm install always has it, so the OOTB guarantee is unchanged. dist/lib/kernel-client.js now has no top-level require("@noble…") — only a deferred one inside keccak256Utf8.

Finding #2 (two evidence planes) is unchanged — still open, still disclosed.

---

What

A guided trustshell demo: the five-minute, no-account, no-keys, no-network first run the product was missing. It drives the real commands — it spawns this CLI as subprocesses in a throwaway TRUSTSHELL_HOME, so what it shows is exactly what the tool does, nothing re-implemented:

1. guard init → an owner policy, fail-closed (every limit 0, local commands only)
2. guard allow / limit / sign → configure it, pin one task script by sha256, owner-sign it
3. ALLOWED run → the pinned task starts and writes an observable file
4. DENIED run (capability) → an unlisted command refused before it starts — nothing runs
5. DENIED run (spend cap) → an allowed tool, but an over-cap amount refused — nothing runs
6. guard show → the decision ledger, chain INTACT
7. tamper one byte → chain BROKEN (the negative control), then restored
8. verify-receipt → a signed engine receipt verified OFFLINE (integrity VERIFIED, out of the box)

It teaches the four verdict words kept apart — VERIFIED / NOT_CHECKED / FAILED / NOT_APPLICABLE — and exits non-zero if any step stops doing what it says.

Two honest findings it surfaced (named, not hidden)

1. Offline verification needed the optional ethers peer (P1 for the "independently verify" north star). → FIXED (see Update above).
verify-receipt recomputed the receipt hash with keccak256 from the optional ethers peer, so on a bare install integrity read NOT_CHECKED — fail-closed, never a false pass, but offline verification did not actually work out of the box. Now sourced from @noble/hashes (a real dependency, imported lazily); integrity reads VERIFIED on a bare install.

2. Local enforcement and engine receipts are two different evidence planes (P2). (still open, disclosed)
Steps 1–7 are the local plane: a hash-chained guard-receipts.jsonl, checked by guard show. Step 8 verifies an engine kernel-receipt/2 (six-claim plane), checked by verify-receipt. A local run does not yet emit an engine-signed six-claim receipt a stranger can verify offline. The demo shows both planes and names the gap rather than pretending they are one.

Minor, also noted in code: the default owner policy allows the offline inspect but not the equally-offline, egress-free verify-receipt, so a relying party verifies in a policy-free home.

Tests

Verified locally on the fixed tip (9f7e0939):

• tsc --project tsconfig.sdk.json builds clean (exit 0, no errors); dist/lib/kernel-client.js has no top-level @noble require.
• tests/egress.test.ts, tests/learn-hook.test.ts, tests/kernel-client-no-ethers.test.ts — 13/13 pass (hashing bit-exact against the golden with ethers absent).
• npm run test:demo — demo against built dist: exit 0, the four verdicts, the seam disclosed, ALLOW + two DENY, ledger INTACT→BROKEN, integrity VERIFIED.
• npm run e2e:demo — fresh-install smoke test (packs, installs the tarball, runs the demo from the installed package): 0 gaps, "offline verify reads integrity VERIFIED out of the box (no ethers)".

CI honesty. This PR also fixes two pre-existing CI reds on the clean demo tip (e2e-stranger, docs — the demo command is now documented and excluded from the in-process stranger harness with a rationale). The check job was then red on dca4a1f4 for the startup-require regression described above; 9f7e0939 fixes the cause and a fresh CI run is confirming it. Note: the full jest suite has a handful of environment-specific failures unrelated to this change (e.g. measure-home-samples, publish-trusted-publishing, scrub-battery, the repid-engine schema sha256 byte-match in kernel-client.test.ts) — these are not touched here and differ by OS/runner.

Scope / weight

Additive and inert: a new offline CLI command, a shipped sample receipt, one real audited dependency (@noble/hashes, lazily imported), and a keccak-source swap in kernel-client (bit-exact, ethers relocated to on-chain/signing only). No live surface, no network, no secrets, no schema change. Draft for review — merge is yours.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
trustshell-landing	Ready	Preview	Nov 7, 2026 11:00pm UTC

[strix-security]

Strix Security Review

To fix before merging (1)

• 🔵 MEDIUM trustshell run decides on a bare executable name and lets the spawn re-resolve it on the caller's PATH, so a shadowing node satisfies the pin without opening the pinned script — src/cli/guard.ts:230-243

PR summary: Adds a guided, fully offline `trustshell demo` command that drives the real CLI subcommands in a throwaway policy home, plus a shipped sample signed receipt, and switches receipt/argument keccak256 hashing from the optional `ethers` peer to a lazily imported `@​noble/hashes` dependency so offline verification works on a bare install.

Review summary

Reviewed the new offline trustshell demo command, the executableIdentity change in run, the keccak256 swap from the optional ethers peer to @noble/hashes, and the shipped sample receipt. The demo itself holds up: it is gated as tool:demo (no longer in NEVER_GUARDED), takes no argv, spawns a fixed argv with no shell in a freshly created 0700 temp home, and its self-check can only pass under a root pinned out of band. The hashing change is bit-exact and fail-closed, and no secret ships in the sample receipt. Still open is trustshell run deciding on a bare executable name and handing that name back to the OS: the PR's executableIdentity closes the path-qualified variant, but a shadowing node earlier on PATH is still ALLOWED and satisfies the tool:node script pin while a different binary runs — trustshell run decides on a bare executable name and lets the spawn re-resolve it on the caller's PATH, so a shadowing node satisfies the pin without opening the pinned script — which also makes the demo's narrated guarantee and the ledger's executable: "node" attestation untrue in that case.

2 resolved findings

• trustshell demo is exempt from the owner-policy gate, so an enforced deny-all policy still spawns interpreters with no audit record — resolved in 2bf4baf
• trustshell demo pins verify-receipt to the key it reads out of the receipt being verified — resolved in 2bf4baf

Ruled out (4)

• Does swapping keccak256 from ethers to a lazily imported @​noble/hashes weaken receipt integrity or let a tampered receipt read VERIFIED?
  The new keccak is bit-exact against the golden receipt_hash, the signature is still verified over the hash-bearing body against a caller-pinned root, tampering any hashed field yields FAILED, and a missing @​noble leaves the verifier at NOT_CHECKED rather than VERIFIED.
• Can `trustshell demo` bypass the owner-policy gate or inject commands/paths through the environment it inherits?
  `demo` is gated as `tool:demo` before `run()` is reachable (refused under deny-all and TRUSTSHELL_REQUIRE_POLICY), it parses no argv, it spawns a fixed argv array with no shell in a fresh 0700 mkdtemp home it overwrites TRUSTSHELL_HOME and DEMO_ARTIFACT for, and its verify steps pin the sealing roo…
• Does the PR's changed guard code newly expose the sandbox receipt verifier that trusts keys carried inside the receipt?
  src/sandbox/receipt.ts is unmodified and the changed guard.ts lines do not reach it; the no-pin call sites verify only in-memory receipts the process just signed, and the shipped verify path pins by fingerprint.
• Do the other lint-flagged printing/argv paths in the changed CLI files become exploitable through the new code?
  The flagged formatQuarantine/formatVerify/ground and guard usage-echo code is untouched by this PR and is not reached by the demo, which only prints output from its own throwaway-home commands and its shipped sample.

Review history (5)

• Review 5 · 17daeb6 · Nov 7 23:04 UTC · Nothing new
• Review 4 · 2bf4baf · Nov 7 08:35 UTC · Fixed 2
• Review 3 · 9f7e093 · Nov 7 06:38 UTC · Nothing new
• Review 2 · dca4a1f · Nov 7 06:16 UTC · Nothing new
• Review 1 · 7b150b4 · Nov 7 06:12 UTC · Found 1 Medium Vulnerability and 2 Low Vulnerabilities

_{Fixed the findings? re-run the review, or tag @strix-security in a PR comment to run a fresh review.}

_{Review 5 on this PR · 17daeb6 · requested Nov 7 22:59 UTC on a new commit}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}

[strix-security]

Strix flagged 3 new security findings below. See the pinned summary comment for the full PR status.

[strix-security]

🔵 trustshell run matches the tool by basename, so a policy pinning one interpreter script can be satisfied by any binary of that name

Severity: MEDIUM · CWE-184

The demo teaches that with a policy granting only tool:node pinned to one script, "an interpreter runs ONLY a script the policy pinned". That guarantee is defeated by one token: run decides which program starts by the basename of argv[0] and then spawns that same string verbatim, so trustshell run --tool node -- /tmp/attacker/node task.js is ALLOWED by the pinning policy and executes the supplied binary, which ignores the pinned script entirely. I reproduced it against the committed dist: the substituted binary ran (wrote its own file) under a policy whose only grant was tool:node pinned to one sha256, while the genuine script-swap was still DENIED — so the script pin holds and only the executable identity is unverified. The policy stays owner-signed and the ledger records executable: "node" with the pinned script hash, so guard show cannot distinguish the bypass from a compliant run. Root cause is pre-existing and unchanged by this PR at src/cli/guard.ts:259-260 (basename) and :291 (verbatim spawn); the PR's new demo step at src/cli/demo.ts:105-106 exercises and markets that exact command form.

Prompt to fix with AI

This is a security vulnerability found during a code review.

Vulnerability: `trustshell run` matches the tool by basename, so a policy pinning one interpreter script can be satisfied by any binary of that name
Severity: MEDIUM
CWE: CWE-184

The demo teaches that with a policy granting only `tool:node` pinned to one script, "an interpreter runs ONLY a script the policy pinned". That guarantee is defeated by one token: `run` decides which program starts by the basename of `argv[0]` and then spawns that same string verbatim, so `trustshell run --tool node -- /tmp/attacker/node task.js` is ALLOWED by the pinning policy and executes the supplied binary, which ignores the pinned script entirely. I reproduced it against the committed dist: the substituted binary ran (wrote its own file) under a policy whose only grant was `tool:node` pinned to one sha256, while the genuine script-swap was still DENIED — so the script pin holds and only the executable identity is unverified. The policy stays owner-signed and the ledger records `executable: "node"` with the pinned script hash, so `guard show` cannot distinguish the bypass from a compliant run. Root cause is pre-existing and unchanged by this PR at `src/cli/guard.ts:259-260` (basename) and `:291` (verbatim spawn); the PR's new demo step at `src/cli/demo.ts:105-106` exercises and markets that exact command form.

Location: src/cli/guard.ts:259-260
Context: root cause: identity comes from basename(argv[0]) while argv[0] is spawned verbatim at line 291
```
// Before:
  const executable = basename(String(command[0])).replace(/\.(exe|cmd|bat|com)$/i, '').toLowerCase();
  const mismatch = executable !== tool.toLowerCase() ? [`the command starts ${executable}, not ${tool}: run allows an executable only by its own name`] : [];
// After:
  // The tool label must BE the executable that starts, not merely a file of the same name: a path form
  // (`/tmp/x/node`) is refused, so a pinned interpreter cannot be swapped for a different binary.
  const started = String(command[0]);
  const executable = basename(started).replace(/\.(exe|cmd|bat|com)$/i, '').toLowerCase();
  const byPath = /[\\/]/.test(started);
  const mismatch = byPath || executable !== tool.toLowerCase() ? [`the command starts ${started}, not ${tool}: run allows an executable only by its own name, resolved from PATH`] : [];
```

Location: src/cli/demo.ts:105-106
Context: the PR's new step exercises and markets the pin this bypass defeats
```
    const allowed = step('ALLOWED run: the pinned task starts and does its work',
      ['run', '--tool', 'node', '--', 'node', taskPath], { exit: 0 });
```

Location: src/cli/demo.ts:89-91
Context: the narrated guarantee the basename check does not uphold
```
    step('Allow one task: the node script we just wrote, pinned by its sha256',
      ['guard', 'allow', 'tool:node', '--script', taskPath], { exit: 0 },
      'an interpreter runs ONLY a script the policy pinned — swap the file and the pin no longer matches');
```

How to fix:
Decide the started program by its resolved identity, not by the basename of an attacker-supplied string: refuse a command whose `argv[0]` contains a path separator (or resolve it through PATH and compare it with the realpath of the tool the policy names) before the decision, and record the resolved path so `guard show` and the ledger show which binary actually started. Where a path form must stay supported for legitimate users, require the caller to pass an explicit `--exe <absolute path>` that is separately pinned by hash in the policy.

Please fix this vulnerability. If you propose a fix, make it concise and minimal.

_{React 👍 / 👎 to tune Strix for this repo. A repo collaborator (or the PR author) can resolve this thread to dismiss the finding.}

[strix-security]

the narrated guarantee the basename check does not uphold

[github-actions]

🧾 Receipt

1 claim(s) checked against GitHub's own check runs on 17daeb6: 0 verified · 1 not checked · 0 failed

Claim	Said in	Evidence	Result
build: tsc --project tsconfig.sdk.json builds clean (exit 0, no errors); dist/lib/kernel-client.js has no top-level @​noble require.	PR description	step `Compile the mission CLI` in passports, step `Compile the mission CLI and the C15 containment probes` in mission (runc), step `Build the trustshell CLI` in mission (runc), step `Compile the mission CLI and the C15 containment probes` in mission (runsc), step `Build the trustshell CLI` in mission (runsc), step `Run npm run sdk:build` in verify-paris passed, but check (failure) did not finish green on this commit and may cover the same ground.	⚪ NOT CHECKED

What this receipt does not prove

• A green check proves that check passed on this commit. It does not prove the check tested this change.
• Evidence is read at the strongest level each check offers: the run: command of the job, taken from the workflow file at this commit; else the step name and that step own result; else the check name alone. The Result column says which. A check name is a label, not evidence.
• At command level the receipt confirms the job runs a command that normally runs this kind of check. It cannot confirm the command asserted anything: a test script that exits 0 without running a test still reads as tests.
• A job whose steps cannot be read (a third-party check, or no actions: read permission) is matched by its name alone, and a job whose work happens inside a composite action shows no command.
• Claims are read from the PR description and the latest commit message by plain patterns. A claim worded unusually is not seen. Text in double quotes, code blocks and block quotes is ignored on purpose; text in single quotes is read, because a single quote is also an apostrophe.
• A check created after this receipt was written is not counted until the receipt runs again.

_{Receipts by TrustShell. Read-only: it reads this PR and its check runs, and writes only this comment. No code leaves the repo.}

[DealAppSeo]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved the conflict in package.json, preserving the demo and trust-cycle scripts, and merged main in commit 17daeb6.