magenta-canon 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Royal Ohio
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,255 @@
+<p align="center">
+  <img src="docs/magenta-canon-banner.png" alt="Magenta Canon — Verifiable MCP Gateway" width="820">
+</p>
+
+# Magenta Canon
+
+**A verifiable MCP accountability gateway for AI-agent tool calls.** It sits between an
+MCP host (Claude Code, Claude Desktop, Cursor, …) and downstream MCP tools, and:
+
+> **allows authorized calls · blocks unauthorized calls · records both · and
+> produces cryptographic evidence anyone can verify.**
+
+## In 60 seconds
+
+AI agents are starting to take real actions through tools (refunds, deploys,
+file writes). The unanswerable question becomes: *was that action authorized, and
+can you prove what actually happened?*
+
+Magenta answers it. You point your agent's MCP connection at the **Magenta
+Gateway**. For every tool call it:
+
+1. **gates** the call against an operator-delegated capability (e.g. "may refund
+   up to $100") — default **deny**;
+2. **witnesses** the decision — allowed *and* refused — as a hash-chained, signed
+   **execution receipt** in an append-only Merkle transparency log;
+3. **forwards** allowed calls to the real tool; **blocks** the rest (the tool is
+   never even contacted) and returns an error the agent can read.
+
+Afterward, anyone can run a **standalone verifier** over the published evidence
+and get `VERIFIED` — *without trusting the server that produced it.* Tamper with
+the record and verification fails. That's the whole point: not "trust our log,"
+but "verify the receipt yourself."
+
+## The proof (we don't rely on claims)
+
+Two recorded, reproducible, live end-to-end runs live in the repo:
+
+- **[`docs/MCP_GATEWAY_RUN.md`](docs/MCP_GATEWAY_RUN.md)** — the wedge: an agent
+  tried two tool calls; one was allowed, one was blocked, both were recorded, the
+  downstream tool's *own log* proves the blocked call never arrived, and
+  `magenta-verify` returned **VERIFIED**.
+- **[`docs/VERIFICATION_RUN.md`](docs/VERIFICATION_RUN.md)** — the trust anchor:
+  operator publishes evidence → independent verifier checks it → a tampered
+  bundle **fails** (exit code 1).
+
+Why this matters and where it's going: **[`docs/LAUNCH_MANIFESTO.md`](docs/LAUNCH_MANIFESTO.md)** — *Verifiable Agent Actions: stop trusting the log, verify the receipt.*
+
+## Architecture
+
+```
+  MCP host (Claude Code / Desktop / Cursor)
+        │  tools/call
+        ▼
+  ┌─────────────────────┐     gate + witness     ┌──────────────────────────┐
+  │   Magenta Gateway    │ ─────────────────────▶ │  Control plane            │
+  │   (stdio proxy)      │                        │  • capability gate        │
+  │                      │ ◀───── allow/deny ──── │  • transparency-log witness│
+  └─────────┬───────────┘                        │  • /api/trust/evidence    │
+            │ forward IF allowed                  └──────────────┬───────────┘
+            ▼                                                    │ signed receipts
+  downstream MCP tool                                            ▼
+  (refund, search, …)                          evidence bundle ──▶ magenta-verify
+                                                                   = VERIFIED ✓
+```
+
+The verifier imports **nothing** from the server — only `node:crypto` + `tweetnacl`
+— so it's independently auditable. See
+[`docs/MAGENTA_VERIFICATION_SPEC.md`](docs/MAGENTA_VERIFICATION_SPEC.md).
+
+## Quickstart — one command
+
+```bash
+npm install
+npm run demo
+```
+
+`npm run demo` runs the entire proof loop locally and narrates it end to end: it
+boots the control plane, bootstraps trust, drives the MCP gateway through one
+**allowed** and one **blocked** tool call, proves the blocked call never reached
+the downstream tool, publishes the evidence bundle, verifies it with the
+standalone `magenta-verify` (→ `VERIFIED`), then tampers with one byte of the
+record and shows verification **fails**. It is local/dev only — an ephemeral port
+and a fresh universe in a temp dir, cleaned up on exit.
+
+<details>
+<summary>Prefer the manual steps?</summary>
+
+```bash
+# 1. boot the control plane (the witness + evidence surface) and bootstrap trust
+INTERNAL_API_KEY=operator-secret-xyz MAGENTA_STATE_FILE=/tmp/magenta-state.json \
+  PORT=5000 npx tsx server/index.ts &
+# wait until it is healthy before bootstrapping (the server takes a few seconds)
+until curl -sf :5000/api/health >/dev/null 2>&1; do sleep 1; done
+curl -s -X POST :5000/internal/founder/ceremony \
+  -H 'X-Internal-Key: operator-secret-xyz' -d '{}'
+
+# 2. run the live gateway demo (gateway spawns a real downstream MCP server)
+DOWNSTREAM_LOG=/tmp/downstream-calls.log \
+  node scripts/mcp-demo-drive.mjs examples/magenta-gateway.demo.config.json
+
+# 3. publish evidence and verify it independently
+curl -s :5000/api/trust/evidence > bundle.json
+npx tsx scripts/magenta-verify.ts bundle.json     # → RESULT: VERIFIED
+```
+</details>
+
+Full walkthrough: [`docs/MCP_GATEWAY.md`](docs/MCP_GATEWAY.md).
+
+### From the repo vs. as a CLI
+
+- **From a repo checkout** (above): `npm install` then `npm run demo`.
+- **As a package/CLI** — the same three capabilities without cloning internals.
+  The first npm release is **`0.1.0`** under the **`next`** dist-tag (a proven
+  reference implementation, not production-hosted infra yet), so install from
+  `@next`:
+
+  ```bash
+  npx magenta-canon@next demo                 # the full local proof loop
+  npx magenta-canon@next verify <bundle.json> # independently verify an evidence bundle
+  npx magenta-canon@next gateway <config.json># run the stdio MCP capability gateway
+  ```
+
+  `verify` exits `0` on `VERIFIED`, `1` on `VERIFICATION FAILED`. The packaged
+  `demo` boots a **headless** control plane (no frontend needed). What ships,
+  what doesn't, and how to test the package locally:
+  [`docs/NPM_PACKAGING.md`](docs/NPM_PACKAGING.md). *(Packaging readiness — not yet
+  published to npm.)*
+
+## Connect your MCP host
+
+Point Claude Code / Claude Desktop / Cursor at the gateway (it proxies your real
+downstream MCP server, configured in `examples/magenta-gateway.demo.config.json`):
+
+```jsonc
+{
+  "mcpServers": {
+    "magenta-gated-tools": {
+      "command": "npx",
+      "args": [
+        "tsx",
+        "/abs/path/to/magenta-canon/scripts/mcp-gateway.ts",
+        "/abs/path/to/magenta-canon/examples/magenta-gateway.demo.config.json"
+      ]
+    }
+  }
+}
+```
+
+Every tool call your agent makes now flows through the gate and is witnessed.
+
+## Demo transcript
+
+```
+HANDSHAKE_OK tools=refund
+ALLOWED_CALL isError=false :: refund executed: {"amount_cents":8900,"order_id":"4471"}
+REFUSED_CALL isError=true  :: Blocked by Magenta capability gate: exceeds delegated
+  refund ceiling (25000 > 10000 cents). Witnessed as receipt e993d86ef721cf94…
+
+# downstream tool's own log — ground truth of what actually reached it:
+{"name":"refund","args":{"amount_cents":8900,"order_id":"4471"}}     ← only the allowed call
+# the blocked $250 refund is ABSENT — it never reached the tool.
+
+$ npx tsx scripts/magenta-verify.ts bundle.json
+  [PASS] STH signature verifies
+  [PASS] receipt chain intact
+  [PASS] recomputed Merkle root == signed STH root
+  RESULT: VERIFIED            (exit code 0)
+```
+
+## Security model
+
+Magenta gives **accountability**, not magic: an action is gated before it happens
+and recorded so that tampering is detectable **by an independent party**. The key
+honest condition — the insider guarantee holds only when the Signed Tree Head is
+**mirrored to an outside party**; the code emits/verifies it, the mirror is an
+operational step. Read the full threat model and assumptions:
+**[`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md)**.
+
+## Current status (honest)
+
+- ✅ **Proven reference implementation** — validated live in a development sandbox.
+- ✅ Capability gate, witness, signed receipts, standalone verifier, stdio MCP gateway — all tested (full suite green).
+- ⏳ **Production durability (single-writer / Postgres) is not yet complete** — the demo uses file-backed persistence.
+- ⏳ The demo's downstream MCP server is **minimal** (real stdio JSON-RPC, enough to prove the path; not a production tool server).
+- ⏳ Transport is **stdio only** — no Streamable HTTP, no hosted/multi-tenant.
+- Capabilities here are **operator-configured (Act 1, proven)**; per-call
+  **agent-signed certificates (Act 2)** are a stronger, separate mode also proven
+  (`docs/AGENT_ACCOUNTABILITY_SPEC.md`), not exercised by the stdio demo.
+
+This is a credible, reproducible wedge — **not** a claim of production readiness.
+
+## Open source vs. paid
+
+The verifier, spec, evidence formats, stdio gateway, and the local reference
+control plane are **free and open** under Apache-2.0 (verification must never
+require trusting us); hosted witness, external STH mirroring, multi-tenant /
+team policy control plane, remote HTTP gateway, and compliance reporting are the
+reserved paid surface — **not shipped in this repo**. This boundary is
+**ratified**: [`docs/OSS_VS_PAID.md`](docs/OSS_VS_PAID.md).
+
+## Docs index
+
+| Doc | What it is |
+|---|---|
+| [`docs/LAUNCH_MANIFESTO.md`](docs/LAUNCH_MANIFESTO.md) | The category thesis: verifiable agent accountability |
+| [`docs/DEMO_VIDEO_STORYBOARD.md`](docs/DEMO_VIDEO_STORYBOARD.md) | Storyboard + capture plan for the `npm run demo` video/GIF |
+| [`docs/MCP_GATEWAY.md`](docs/MCP_GATEWAY.md) | How the gateway works + run guide |
+| [`docs/MCP_GATEWAY_RUN.md`](docs/MCP_GATEWAY_RUN.md) | Live end-to-end gateway proof |
+| [`docs/VERIFICATION_RUN.md`](docs/VERIFICATION_RUN.md) | Live trust-anchor proof (+ negative control) |
+| [`docs/MAGENTA_VERIFICATION_SPEC.md`](docs/MAGENTA_VERIFICATION_SPEC.md) | Language-agnostic verification spec |
+| [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md) | Threat model & trust assumptions |
+| [`docs/AGENT_ACCOUNTABILITY_SPEC.md`](docs/AGENT_ACCOUNTABILITY_SPEC.md) | Agent-action accountability (Act 1 + Act 2) |
+| [`docs/OSS_VS_PAID.md`](docs/OSS_VS_PAID.md) | Open/paid boundary (ratified) |
+| [`docs/NPM_PACKAGING.md`](docs/NPM_PACKAGING.md) | What the npm package ships, and how to verify it locally |
+
+## Stack
+
+Express + TypeScript backend · React + Tailwind/shadcn frontend · Drizzle ORM
+(PostgreSQL, for the durability roadmap) · Ed25519 + SHA-256 + RFC 6962 Merkle.
+
+---
+
+## Platform operational requirements
+
+Magenta Canon also operates as a structural execution-eligibility control plane
+(binary ALLOWED/BLOCKED gating of software artifacts via computed conformance;
+epoch-based append-only baselines; non-circumventable, no override flags). The
+following operational rules are **load-bearing for the live deployment** and must
+be preserved.
+
+### Crawl & SEO enforcement (non-negotiable)
+
+All public pages MUST comply with the **Sovereign HTML Base Template** and the
+**Universal Crawl Enforcement Prompt** in `/docs`:
+
+1. Every page renders complete semantic HTML **without** JavaScript.
+2. Exactly one `<h1>` per page.
+3. Required: `<main>`, `<article>`, canonical link, JSON-LD.
+4. Head ordering: charset → viewport → title → description → robots → canonical.
+
+Validate by disabling JavaScript and viewing source; if `<title>`, `<meta
+description>`, `<link rel="canonical">`, exactly one `<h1>`, or `<article>` body
+text is missing, **the page is invalid.** Build-time check:
+
+```bash
+npm run crawl:lint
+```
+
+Any PR, agent, or refactor that violates these rules is invalid. See
+`docs/SOVEREIGN_HTML_BASE.html` (canonical template) and
+`docs/CRAWL_ENFORCEMENT.md` (full rules).
+
+## Contact
+
+cj@trendinghot.com

package/bin/magenta-canon.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * magenta-canon — CLI entry point for the open-source reference implementation.
+ *
+ *   npx magenta-canon demo               run the full local proof loop
+ *   npx magenta-canon verify <bundle>    independently verify an evidence bundle
+ *   npx magenta-canon gateway <config>   run the stdio MCP capability gateway
+ *   npx magenta-canon --help | --version
+ *
+ * This is a thin dispatcher: it does NOT change any verifier, witness, evidence,
+ * or gate behavior. It locates the package's existing entry scripts and runs
+ * them, resolving the `tsx` TypeScript runner robustly (whether hoisted into the
+ * consumer's node_modules or nested), so the CLI works the same from a global
+ * install, `npx`, or a repo checkout.
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const require = createRequire(import.meta.url);
+const pkg = require(path.join(ROOT, "package.json"));
+
+// Resolve the tsx CLI (dist/cli.mjs) from wherever it is installed.
+function tsxCli() {
+  try {
+    const pkgJson = require.resolve("tsx/package.json", { paths: [ROOT] });
+    return path.join(path.dirname(pkgJson), "dist", "cli.mjs");
+  } catch {
+    return null;
+  }
+}
+
+const USAGE = `magenta-canon ${pkg.version} — verifiable MCP gateway for AI-agent tool calls
+
+Usage:
+  magenta-canon demo                 Run the full local proof loop (allow, block,
+                                     witness, verify, and a tamper control).
+  magenta-canon verify <bundle.json> Independently verify an evidence bundle.
+                                     Exit 0 = VERIFIED, 1 = VERIFICATION FAILED.
+  magenta-canon gateway <config.json> Run the stdio MCP capability gateway
+                                     (a transparent proxy in front of a tool).
+  magenta-canon --help               Show this help.
+  magenta-canon --version            Print the version.
+
+Docs: https://github.com/royal-ohio/magenta-canon
+`;
+
+function run(cmd, args, opts = {}) {
+  const child = spawn(cmd, args, { cwd: ROOT, stdio: "inherit", ...opts });
+  child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 0));
+  child.on("error", (e) => { console.error(`magenta-canon: failed to start: ${e.message}`); process.exit(1); });
+}
+
+// Run one of the package's TypeScript entry scripts via tsx.
+function runTs(relScript, args) {
+  const cli = tsxCli();
+  const script = path.join(ROOT, relScript);
+  if (!existsSync(script)) { console.error(`magenta-canon: missing ${relScript} in package`); process.exit(1); }
+  if (!cli) { console.error("magenta-canon: could not locate 'tsx' (a dependency). Try reinstalling."); process.exit(1); }
+  run(process.execPath, [cli, script, ...args]);
+}
+
+const [sub, ...rest] = process.argv.slice(2);
+
+switch (sub) {
+  case "demo":
+    // demo.mjs is plain ESM and resolves tsx + headless mode itself.
+    run(process.execPath, [path.join(ROOT, "scripts", "demo.mjs"), ...rest]);
+    break;
+  case "verify":
+    if (!rest[0] || rest[0].startsWith("-") && rest[0] !== "--self-test") {
+      // pass flags through (e.g. --self-test, --version); only warn on no target
+    }
+    runTs("scripts/magenta-verify.ts", rest);
+    break;
+  case "gateway":
+    if (!rest[0]) { console.error("magenta-canon gateway: missing <config.json>\n\n" + USAGE); process.exit(2); }
+    runTs("scripts/mcp-gateway.ts", rest);
+    break;
+  case "-v":
+  case "--version":
+  case "version":
+    console.log(pkg.version);
+    break;
+  case undefined:
+  case "-h":
+  case "--help":
+  case "help":
+    process.stdout.write(USAGE);
+    break;
+  default:
+    console.error(`magenta-canon: unknown command '${sub}'\n\n` + USAGE);
+    process.exit(2);
+}

package/docs/MAGENTA_VERIFICATION_SPEC.md

@@ -0,0 +1,122 @@
+# Magenta Verification Spec v1
+
+**What this is:** the complete, language-agnostic recipe for verifying a Magenta
+agent-action record **without trusting — or running — the Magenta server.** If you
+can compute SHA-256 and verify an Ed25519 signature, you can implement this in any
+language and independently check that an agent's action log is authentic,
+append-only, and untampered. This is the document that makes "don't trust the
+operator" real: the operator publishes evidence, anyone verifies it.
+
+`scripts/magenta-verify.ts` is the reference implementation. It imports nothing
+from the server — only `node:crypto` and `tweetnacl` — so it is itself auditable.
+
+---
+
+## 1. Primitives
+
+| Name | Definition |
+|---|---|
+| `sha256hex(bytes)` | lowercase hex of SHA-256 over the bytes |
+| **canonical JSON** | keys sorted by UTF-8 code unit (recursively), no whitespace, `undefined` omitted, `null` preserved. (JCS-like; see §6) |
+| `canonicalHash(obj)` | `sha256hex( utf8( canonicalJSON(obj) ) )` |
+| `chainHash(prev, h)` | `sha256hex( utf8( prev concatenated with h ) )` — both are 64-char hex strings concatenated as text, then hashed |
+| Ed25519 | detached signatures over the **UTF-8 bytes of the message string**; keys and signatures are lowercase hex |
+
+---
+
+## 2. Execution receipt
+
+A receipt commits to an action and a decision by hash, and chains to its predecessor:
+
+```
+action_hash     = canonicalHash({ action, payload })
+decision_hash   = canonicalHash(decision)
+execution_hash  = canonicalHash({ action_hash, decision_hash, timestamp })
+receipt_hash    = chainHash(previous_receipt_hash, execution_hash)
+```
+
+The first receipt's `previous_receipt_hash` is the genesis value (64 zeros) or the
+server's configured genesis. `receipt_signature` is the issuer's Ed25519 signature
+over the canonical receipt body (all fields except `receipt_signature`).
+
+**Chain check** (per receipt `i`, in creation order, oldest-first):
+1. `execution_hash == canonicalHash({ action_hash, decision_hash, timestamp })`
+2. `receipt_hash == chainHash(previous_receipt_hash, execution_hash)`
+3. for `i > 0`: `previous_receipt_hash == receipts[i-1].receipt_hash`
+
+**Payload binding (optional):** given the original `payload` / `decision`, confirm
+`action_hash == canonicalHash({ action, payload })` and
+`decision_hash == canonicalHash(decision)`. This proves the human-readable content
+matches what the receipt committed to.
+
+---
+
+## 3. Merkle transparency log (RFC 6962 domain separation)
+
+Each receipt's `receipt_hash` is a leaf. Leaves are added in **creation order**.
+
+```
+hashLeaf(receipt_hash) = sha256hex( 0x00 || utf8(receipt_hash) )
+hashNode(left, right)  = sha256hex( 0x01 || fromHex(left) || fromHex(right) )
+```
+
+> Note the asymmetry, which a re-implementation MUST preserve: a leaf hashes the
+> UTF-8 bytes of the receipt-hash *string*; an internal node hashes the *raw bytes*
+> of its two child hex digests. Odd nodes are promoted unchanged to the next level.
+
+**Merkle root:** fold the leaf list with `hashNode` pairwise, promoting a lone
+trailing node, until one hash remains. Empty log → `sha256hex(<empty>)`.
+
+**Inclusion proof** for a leaf: the ordered list of sibling hashes with a `right`
+flag (true if the sibling is to the right). Verify by folding the leaf with each
+sibling (`hashNode(h, sibling)` if `right`, else `hashNode(sibling, h)`); the
+result must equal the published root.
+
+---
+
+## 4. Signed Tree Head (STH)
+
+```
+sthMessage = "magenta-sth-v1|" + tree_size + "|" + root_hash + "|" + timestamp + "|" + witness_pubkey
+```
+
+The witness signs `sthMessage` with its Ed25519 key (separate from the receipt
+issuer key). An STH is `{ tree_size, root_hash, timestamp, witness_pubkey, signature }`.
+
+**STH check:** `Ed25519.verify(utf8(sthMessage), fromHex(signature), fromHex(witness_pubkey))`.
+
+---
+
+## 5. What an auditor verifies
+
+Given evidence published by the operator (and a witness public key obtained
+out-of-band, e.g. mirrored to the auditor earlier):
+
+1. **STH authenticity** — the STH signature verifies under the witness key (§4).
+2. **Inclusion** — a specific receipt's leaf + proof recompute the STH's `root_hash` (§3).
+3. **Whole-log integrity** — recompute the Merkle root over all receipt leaves;
+   it must equal the STH `root_hash` (§3) — and the receipt chain checks (§2).
+4. **Append-only (consistency)** — given the full leaf list and an *older* STH the
+   auditor mirrored previously, the older `root_hash` must equal the root over the
+   first `older.tree_size` leaves, and both STHs must verify. A divergence means
+   history was rewritten.
+5. **Payload binding (optional)** — §2.
+
+**The insider property:** an operator who controls the process and the receipt
+issuer key can still forge a self-consistent receipt chain (§2 passes). But the
+operator cannot make the recomputed root match an STH the auditor *already holds*
+unless they also control the witness key and every mirror of that STH. So checks
+(1)+(3)+(4) against a pre-mirrored STH expose insider tampering.
+
+---
+
+## 6. Canonical JSON details
+
+- Sort object keys ascending by JavaScript string comparison (UTF-16 code unit,
+  which matches UTF-8 byte order for the ASCII key names used here).
+- Recurse into arrays (order preserved) and objects (keys sorted).
+- Omit properties whose value is `undefined`; preserve `null`.
+- No insignificant whitespace. Numbers per standard JSON.
+
+A conformant implementation in any language that reproduces these byte sequences
+will compute identical hashes and verify identical signatures.