From 1fe33775a3194b51f60e08a7327cf832780480d6 Mon Sep 17 00:00:00 2001
From: samjanny <samjanny@gmail.com>
Date: Wed, 3 Jun 2026 15:53:19 +0200
Subject: [PATCH] verify: check content against the manifest runtime key;
 complete the example

A content document is signed by a runtime key, but only the manifest
declares which runtime key is authorized (its canary.runtime_pubkey), so
verifying a content document standalone could only report a signature
rejection. Add --expected-runtime-pubkey to verify: pass the manifest's
runtime key and the content (or transaction) signature is checked against
it. Without it the prior behavior holds, now with a note pointing at the
flag.

Extend examples/blog into an end-to-end site: add manifest.unsigned.json
and the signed manifest.json, and rewrite the README to walk the whole
flow - derive the three role keys, convert and sign the content, sign the
manifest, then verify the manifest from its onion (signature, canary,
origin binding) and verify the content against the manifest's runtime key.
Both verify steps accept. The README explains why the content needs the
manifest. All four example .json files regenerate byte for byte from the
documented commands, which were run verbatim to confirm.
---
 README.md                            |   4 +-
 examples/blog/README.md              | 102 ++++++++++++++++-----------
 examples/blog/manifest.json          |   1 +
 examples/blog/manifest.unsigned.json |  24 +++++++
 src/cli.rs                           |   8 +++
 src/commands/verify.rs               |  47 ++++++++----
 6 files changed, 132 insertions(+), 54 deletions(-)
 create mode 100644 examples/blog/manifest.json
 create mode 100644 examples/blog/manifest.unsigned.json

diff --git a/README.md b/README.md
index f12f84c..bc636ac 100644
--- a/README.md
+++ b/README.md
@@ -51,14 +51,16 @@ A manifest is driven through the full chain: signature (Stages 2-6), canary (Sta
 - `--now` sets the verified-time reference for the canary and origin-expiry checks (defaults to the corpus clock).
 - `--fetched-onion` is the onion address the manifest was fetched from; with it, Stage 9 origin binding runs. Omit to skip Stage 9.
 - `--content-index` is the served `/content_index.json`; when the manifest declares `content_root`, Stage 9b verifies it (and its absence with a declared `content_root` surfaces the fetch failure).
+- `--expected-runtime-pubkey` is the manifest's `canary.runtime_pubkey`; for a content or transaction document, it is the key the signature is checked against. Without it, a content/transaction has no authorized key and reports a signature rejection.
 
 Skipped stages are reported, so an accept is never mistaken for a full-pipeline pass.
 
 ```sh
 entangled-tool verify --input manifest.json --fetched-onion dkptfye...onion --content-index content_index.json
+entangled-tool verify --input post.json --expected-runtime-pubkey jzFtzi...F7o
 ```
 
-Content and transaction documents are verified through signature only here; their binding checks need the fetch path / submit body, which a future revision will accept.
+A content document is signed by a runtime key, and only the manifest declares which runtime key is authorized. So a content or transaction document is verified in the context of its manifest: pass `--expected-runtime-pubkey` to check its signature against the authorized key. See `examples/blog` for the full manifest-plus-content flow.
 
 ### `build <kind> --input <unsigned.json> (--key-seed-file <path> | --key-seed-hex <64 hex>) [--now <time>]`
 
diff --git a/examples/blog/README.md b/examples/blog/README.md
index cfe1f03..1b6d9f6 100644
--- a/examples/blog/README.md
+++ b/examples/blog/README.md
@@ -1,62 +1,84 @@
-# Example: a minimal Entangled blog post
+# Example: a minimal Entangled site
 
-This directory is a runnable example of authoring a content document with
-`entangled-tool`. It contains:
+This directory is a runnable, end-to-end example: it authors a content document
+from Markdown, signs it, builds the manifest that anchors the site, and verifies
+both. It shows the relationship Entangled is built on - the manifest authorizes a
+runtime key, the content is signed by that key, and verification checks the
+content in the manifest's context.
+
+## Files
 
 - `post.md` - a Markdown post exercising every construct the `content` command
   maps (headings, marks, a list, a code block, a quote, links, an image, a
   divider);
 - `assets/photo.png` - a 16x16 PNG the post references, so the image block's
   hash and dimensions are read from a real file;
-- `post.unsigned.json` - the unsigned content document `content` produces from
-  `post.md`, checked in as a reference of the output;
-- `post.json` - that document signed with `build content`, also checked in as a
-  reference. It is signed with the public test runtime seed from the spec
-  corpus (`ENTANGLED-v1.0-runtime-test0001`), not a real key; do not reuse it.
-  Regenerating with the flow below reproduces these two files byte for byte
-  (the conversion and signature are deterministic).
+- `post.unsigned.json` / `post.json` - the content document `content` produces
+  from `post.md`, and that document signed with `build content`;
+- `manifest.unsigned.json` / `manifest.json` - the site manifest and its signed
+  form. The manifest declares the publisher key, the carrier origin, and the
+  canary, whose `runtime_pubkey` is the key that signs the content.
+
+All four `.json` files are checked in as reference output. They are signed with
+the public test seeds from the spec corpus (`ENTANGLED-v1.0-publisher-test01`,
+`...-runtime-test0001`, `...-origin-test00001`), not real keys; do not reuse
+them. Regenerating with the flow below reproduces them byte for byte, since the
+conversion and the Ed25519 signatures are deterministic.
 
 ## The full flow
 
-From this directory:
+The example uses the corpus test seeds so the steps are reproducible. For a real
+site you would generate fresh seeds with `keygen` and store them offline.
 
 ```sh
-# 1. Generate a runtime key seed and keep it (store it offline for real use).
-entangled-tool keygen runtime --seed-file runtime.seed >/dev/null 2>&1 \
-  || entangled-tool keygen runtime | tee /dev/stderr | \
-     sed -n 's/^seed_hex: //p' > runtime.seed
+# 0. The three role seeds (here, the public corpus test seeds).
+printf '454e54414e474c45442d76312e302d7075626c69736865722d74657374303100' > publisher.seed
+printf '454e54414e474c45442d76312e302d72756e74696d652d746573743030303100' > runtime.seed
+printf '454e54414e474c45442d76312e302d6f726967696e2d74657374303030303100' > origin.seed
+
+# 1. Derive the public material. Note the runtime_pubkey (it goes in the
+#    manifest canary) and the origin onion address (it is the carrier address).
+entangled-tool keygen publisher --seed-file publisher.seed
+entangled-tool keygen runtime   --seed-file runtime.seed
+entangled-tool keygen origin    --seed-file origin.seed
 
 # 2. Convert the Markdown into an unsigned content document. The image path
-#    /assets/photo.png is read from ./assets/photo.png (the Markdown file's
-#    directory), and the hash, media type, and dimensions are filled in.
-entangled-tool content \
-  --markdown post.md \
-  --path /articles/first \
-  --title "A first post" \
-  --published-at 2026-05-07T00:00:00Z \
-  > post.unsigned.json
-
-# 3. Sign it with the runtime key.
+#    /assets/photo.png is read from ./assets/photo.png, and its hash, media
+#    type, and dimensions are filled in.
+entangled-tool content --markdown post.md --path /articles/first \
+  --title "A first post" --published-at 2026-05-07T00:00:00Z > post.unsigned.json
+
+# 3. Sign the content with the runtime key.
 entangled-tool build content --input post.unsigned.json --key-seed-file runtime.seed > post.json
-```
 
-`post.json` is now a signed content document ready to publish at
-`/articles/first`.
+# 4. Sign the manifest with the publisher key. manifest.unsigned.json already
+#    declares the runtime_pubkey and origin from step 1.
+entangled-tool build manifest --input manifest.unsigned.json \
+  --key-seed-file publisher.seed --now 2026-05-07T00:00:00Z > manifest.json
+
+# 5. Verify the manifest from its onion address: this runs the signature,
+#    canary (Stage 8), and origin binding (Stage 9) checks.
+entangled-tool verify --input manifest.json \
+  --fetched-onion dkptfyethnbfsj7qsxscia4w6lg4yssjca2gdrqlk457qav2lkna4xqd.onion
+
+# 6. Verify the content in the manifest's context: pass the manifest's
+#    canary.runtime_pubkey so the content signature is checked against the key
+#    the manifest authorizes.
+entangled-tool verify --input post.json \
+  --expected-runtime-pubkey jzFtziEJkbIdjI15I4u3ni3bBa6IFElyyjEmMVSGF7o
+```
 
-Step 1 prints a secret seed; in a real ceremony you would generate it once,
-store it offline, and reuse the file. See the top-level README's "Handling key
-seeds" section.
+Steps 5 and 6 both report `accept`; step 5 also prints `canary_state: Fresh`.
 
-## A note on verifying content
+## Why the content needs the manifest
 
-`entangled-tool verify` checks a content document's signature against the
-runtime key the **manifest** authorizes for the site. A content document on its
-own does not carry that key, so verifying `post.json` standalone reports a
-signature rejection (the command has no authorized runtime key to check
-against) - this is expected, not a failure of the document. In a real client
-the content is verified in the context of the verified manifest. `verify` is
-most useful here against a manifest, where it runs the canary, origin-binding,
-and content-index stages too.
+A content document carries no key of its own: it is signed by a runtime key, and
+only the manifest says which runtime key is authorized (its
+`canary.runtime_pubkey`). So verifying `post.json` standalone, without
+`--expected-runtime-pubkey`, reports a signature rejection - there is no
+authorized key to check against. That is the whole point of the manifest:
+identity and authorization live there, not in the individual document. This is
+also where the canary, origin binding, and content-index checks run.
 
 ## What gets rejected
 
diff --git a/examples/blog/manifest.json b/examples/blog/manifest.json
new file mode 100644
index 0000000..c09be8d
--- /dev/null
+++ b/examples/blog/manifest.json
@@ -0,0 +1 @@
+{"canary":{"issued_at":"2026-05-07T00:00:00Z","next_expected":"2026-06-06T00:00:00Z","runtime_pubkey":"jzFtziEJkbIdjI15I4u3ni3bBa6IFElyyjEmMVSGF7o","statement":"No warrants received."},"kind":"manifest","min_refresh_interval":3600,"navigation":[{"label":"Home","path":"/"}],"origin":{"address":"dkptfyethnbfsj7qsxscia4w6lg4yssjca2gdrqlk457qav2lkna4xqd.onion","carrier":"tor-v3","origin_pubkey":"Gp8y4JM7Qlkn8JXkJAOW8s3MSkkQNGHGC1c7-AK6Wpo"},"publisher_pubkey":"moyzpl3i5hUIcMNRLPMxir4sdmSO3gO79gLUtvYDWxc","sig":"hhT2nXE_AqT-WGNjKns28vKI1HDx9SMzKOMRTwt8DmxJtFc8EXbwHpE2fvu5l5uXhshcYHC4shE3UU_wDG3PAQ","spec_version":"1.0","state_policy":[],"updated":"2026-05-07T00:00:00Z"}
diff --git a/examples/blog/manifest.unsigned.json b/examples/blog/manifest.unsigned.json
new file mode 100644
index 0000000..bfe6399
--- /dev/null
+++ b/examples/blog/manifest.unsigned.json
@@ -0,0 +1,24 @@
+{
+  "spec_version": "1.0",
+  "publisher_pubkey": "moyzpl3i5hUIcMNRLPMxir4sdmSO3gO79gLUtvYDWxc",
+  "origin": {
+    "carrier": "tor-v3",
+    "address": "dkptfyethnbfsj7qsxscia4w6lg4yssjca2gdrqlk457qav2lkna4xqd.onion",
+    "origin_pubkey": "Gp8y4JM7Qlkn8JXkJAOW8s3MSkkQNGHGC1c7-AK6Wpo"
+  },
+  "canary": {
+    "runtime_pubkey": "jzFtziEJkbIdjI15I4u3ni3bBa6IFElyyjEmMVSGF7o",
+    "issued_at": "2026-05-07T00:00:00Z",
+    "next_expected": "2026-06-06T00:00:00Z",
+    "statement": "No warrants received."
+  },
+  "state_policy": [],
+  "navigation": [
+    {
+      "label": "Home",
+      "path": "/"
+    }
+  ],
+  "min_refresh_interval": 3600,
+  "updated": "2026-05-07T00:00:00Z"
+}
\ No newline at end of file
diff --git a/src/cli.rs b/src/cli.rs
index 047586c..cacc3e7 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -188,6 +188,14 @@ pub struct VerifyArgs {
     /// Manifest documents only.
     #[arg(long)]
     pub content_index: Option<std::path::PathBuf>,
+
+    /// The runtime public key (base64url) the manifest authorizes, i.e. its
+    /// canary.runtime_pubkey. Supply it to verify a content or transaction
+    /// document's signature in the context of its manifest. Without it, a
+    /// content/transaction is checked with no authorized key and reports a
+    /// signature rejection. Content and transaction documents only.
+    #[arg(long)]
+    pub expected_runtime_pubkey: Option<String>,
 }
 
 #[derive(Debug, clap::Args)]
diff --git a/src/commands/verify.rs b/src/commands/verify.rs
index e75ce22..2f0b254 100644
--- a/src/commands/verify.rs
+++ b/src/commands/verify.rs
@@ -39,8 +39,8 @@ pub fn run(args: VerifyArgs) -> Result<(), Error> {
     let kind = document_kind(&bytes)?;
     match kind.as_str() {
         "manifest" => verify_manifest(&args, &bytes, &now),
-        "content" => verify_content(&bytes),
-        "transaction" => verify_transaction(&bytes),
+        "content" => verify_content(&args, &bytes),
+        "transaction" => verify_transaction(&args, &bytes),
         other => Err(format!("unsupported document kind: {other}").into()),
     }
 }
@@ -95,33 +95,54 @@ fn verify_manifest(args: &VerifyArgs, bytes: &[u8], now: &EntangledTimestamp) ->
     Ok(())
 }
 
-fn verify_content(bytes: &[u8]) -> Result<(), Error> {
-    // No verified manifest is available at the CLI to supply the authorized
-    // runtime key, so signature verification reaches Stage 6 with no key and
-    // reports E_SIG_INVALID_KEY. A future revision will accept the manifest.
-    let placeholder = RuntimePubkey::from_bytes([0u8; 32]);
-    match parse_and_verify_content(bytes, &placeholder) {
+fn verify_content(args: &VerifyArgs, bytes: &[u8]) -> Result<(), Error> {
+    let (runtime_pk, has_key) = runtime_key(args)?;
+    match parse_and_verify_content(bytes, &runtime_pk) {
         Ok(_) => {
             println!("verdict: accept");
-            println!("note: signature only; supply the authorizing manifest for full verification");
+            print_runtime_note(has_key);
             Ok(())
         }
         Err(d) => report_reject(&d),
     }
 }
 
-fn verify_transaction(bytes: &[u8]) -> Result<(), Error> {
-    let placeholder = RuntimePubkey::from_bytes([0u8; 32]);
-    match parse_and_verify_transaction(bytes, &placeholder, None) {
+fn verify_transaction(args: &VerifyArgs, bytes: &[u8]) -> Result<(), Error> {
+    let (runtime_pk, has_key) = runtime_key(args)?;
+    match parse_and_verify_transaction(bytes, &runtime_pk, None) {
         Ok(_) => {
             println!("verdict: accept");
-            println!("note: signature only; supply the authorizing manifest for full verification");
+            print_runtime_note(has_key);
             Ok(())
         }
         Err(d) => report_reject(&d),
     }
 }
 
+/// Resolve the runtime key to verify a content/transaction signature against:
+/// the manifest-authorized key from `--expected-runtime-pubkey` when given, or
+/// a placeholder otherwise (in which case the signature check has no authorized
+/// key and will reject). Returns the key and whether a real one was supplied.
+fn runtime_key(args: &VerifyArgs) -> Result<(RuntimePubkey, bool), Error> {
+    match args.expected_runtime_pubkey.as_deref() {
+        Some(b64) => {
+            let key = RuntimePubkey::try_from(b64)
+                .map_err(|e| format!("--expected-runtime-pubkey is invalid: {e}"))?;
+            Ok((key, true))
+        }
+        None => Ok((RuntimePubkey::from_bytes([0u8; 32]), false)),
+    }
+}
+
+fn print_runtime_note(has_key: bool) {
+    if !has_key {
+        println!(
+            "note: no authorizing runtime key given; pass --expected-runtime-pubkey \
+             (the manifest's canary.runtime_pubkey) to verify against the manifest"
+        );
+    }
+}
+
 fn report_reject(diag: &Diagnostic) -> Result<(), Error> {
     println!("verdict: reject");
     println!("diagnostic: {}", diag.code);