# Where must an instance verify signed capability declarations against injection canaries before trusting a tool manifest **Date of Record:** 2026 November 17 **Scope:** Applies to any agent runtime that loads tool/skill manifests carrying signed capability declarations and companion injection canaries (probe payloads embedded to detect manifest tampering or laundering). Does not cover runtime sandboxing of an already-trusted tool, nor transport-layer attestation of the manifest delivery channel. ## Core Distinction A signed capability declaration asserts *what the tool claims it will do*; an injection canary asserts *what the tool can be induced to do*. These are orthogonal attestations. The signature proves the declaration's integrity and author, not its truthfulness relative to the tool's actual behavior. The canary proves a specific injection surface is inert, not that the tool lacks other surfaces. The non-obvious invariant: **signature validity and canary cleanliness are independently necessary but jointly insufficient unless verified at the same instance of the manifest bytes.** A manifest that is signed over version `N` and canary-tested over version `N+1` passes both checks while being unverified in the only sense that matters. The verification must bind the canary result to the exact byte sequence the signature covers — otherwise you have verified two different objects and drawn one conclusion. ## What Was Observed A tool loader fetched manifests from a registry, verified the detached signature against the declared capability set, then ran the canary suite against the tool's declared entrypoint. In the failing case, the loader: 1. Verified signature over manifest blob `B_sig`. 2. Materialized the tool from a *resolved* manifest `B_run` produced by a post-processing step (default injection, capability merging from a parent manifest) that mutated the blob after signing. 3. Ran canaries against `B_run`. The canary suite passed because the injected defaults were benign. But the signature covered `B_sig`, which did not include those defaults. A subsequent registry-side change to the default-merging rules (adding a `network_egress: true` default) produced a tool with egress capability that was never signed and never canary-probed — the canary suite had no probe for egress because the signed declaration never listed it. Both checks reported green. The failure was silent for eleven days. The tell was a capability-set diff between `B_sig` and `B_run` that the loader logged at `DEBUG` and no one read. ## Condition of Validity The joint check is sound only when all three hold: - **Byte identity:** `hash(B_sig) == hash(B_run)` at the moment canaries execute, or the loader computes and signs a transformation receipt binding `B_sig` to `B_run` and verifies the receipt's signer is authorized for the transformation. - **Canary coverage completeness:** every capability in the *union* of signed and resolved capability sets has at least one canary probe. A capability present in `B_run` but absent from `B_sig` is an uncovered surface. - **Probe freshness:** the canary suite version is itself signed and pinned to the manifest schema version; a canary suite older than the schema cannot probe newly introduced capability fields. When any condition fails, the correct posture is *reject*, not *warn*. A warning on a provenance gap is operationally equivalent to acceptance, because the warning path is the one no one monitors. ## Decision Boundary The boundary is not "is the signature valid" but "does the verified object equal the executed object." Concretely: - If `B_sig == B_run` and canary coverage is complete → trust. - If `B_sig == B_run` but a capability in the signed set lacks a canary probe → quarantine; the manifest is unverified for that capability, not verified. - If `B_sig != B_run` and no transformation receipt → reject unconditionally, regardless of canary results. Canary cleanliness over an unsigned blob is evidence about an object you have not authenticated. - If `B_sig != B_run` with a valid transformation receipt → re-verify the receipt's signer authorization and re-run canaries over `B_run`, treating the receipt as a new signature over the union capability set. The subtle case: a transformation that *removes* capabilities is also a divergence. Removal can hide a canary probe's target, making the suite pass vacuously. Treat removal as requiring a receipt with the same rigor as addition. ## Operational Effect Binding canary results to the signed byte sequence converts a silent provenance gap into a hard load-time failure. In the observed deployment, adding a byte-identity assertion at the canary entrypoint and a coverage-completeness check over the capability union reduced the class of "signed but unverified" manifests to zero over the following quarter, at the cost of a small number of legitimate manifests being quarantined until their transformation receipts were issued. The quarantine rate was the price of closing the gap; the alternative was an unmonitored warning channel that had already failed once. The durable lesson: provenance verification is a *conjunction over a single object*, not a *conjunction over a workflow*. Every check must name the exact bytes it judged, and the runtime must refuse to execute bytes that no check named. ```python import hashlib from dataclasses import dataclass class ProvenanceDivergenceError(RuntimeError): """Raised when the object a canary judged differs from the object a signature covers.""" @dataclass(frozen=True) class Manifest: blob: bytes capabilities: frozenset[str] @property def digest(self) -> str: return hashlib.sha256(self.blob).hexdigest() def verify_joint_provenance( signed: Manifest, resolved: Manifest, canary_probed_capabilities: frozenset[str], transformation_receipt_valid: bool = False, ) -> None: # Byte identity is the load-bearing check. Canary results over `resolved` # say nothing about `signed` unless the two are the same object. if signed.digest != resolved.digest: if not transformation_receipt_valid: raise ProvenanceDivergenceError( f"resolved manifest {resolved.digest[:12]} diverges from signed " f"{signed.digest[:12]} with no authorized transformation receipt; " f"canary results over the resolved blob are inadmissible" ) # Coverage completeness over the union, not the resolved set alone. # A capability added by transformation is an uncovered surface. uncovered = (signed.capabilities | resolved.capabilities) - canary_probed_capabilities if uncovered: raise ProvenanceDivergenceError( f"capabilities {sorted(uncovered)} have no canary probe; " f"manifest is unverified for these surfaces, not verified" ) def load_manifest(signed: Manifest, resolved: Manifest, probes: frozenset[str]) -> Manifest: verify_joint_provenance(signed, resolved, probes) return resolved ```