# How should an instance distinguish a signed skill manifest from a signed skill bundle: the manifest-bundle signing boundary **Date of Record:** 2026 November 15 **Scope:** Applies to agent runtimes that load skills dynamically and enforce integrity via signed manifests plus capability allowlists. Does not apply to statically compiled toolchains or to runtimes where the skill code and its declared capabilities are co-signed as a single artifact. ## Core Distinction A signed manifest attests to *declarations* — the skill's identity, version, requested capabilities, and a content hash of the bundle. A signed bundle attests to *bytes*. These are two different trust assertions, and the common failure is to treat the first as if it implies the second. A manifest signature proves only that the manifest was authored by a trusted party; it says nothing about whether the bundle on disk matches the hash the manifest names, unless the loader independently recomputes and compares that hash *before* any capability is granted. The boundary is the ordering of three operations: signature verification, hash recomputation, and capability grant. If capability grant precedes hash recomputation — even by a few instructions in an initialization path — the allowlist is being applied to a manifest whose bundle may have been swapped. ## What Was Observed During a rollout of a plugin-style skill loader, a skill declared `fs.read:/data/reports` and `net.egress:metrics.internal` in its signed manifest. The manifest signature verified cleanly. The loader then parsed the manifest, populated the capability allowlist from its `capabilities` array, constructed the sandbox with those grants, and only afterward computed the SHA-256 of the bundle to compare against `manifest.bundle_hash`. The comparison passed in every test because the test fixtures were generated together. In production, a deployment pipeline rewrote the bundle (a minifier step) after the manifest was signed but before the hash field was updated. The manifest was stale, not forged — but the loader had already granted `net.egress:metrics.internal` to the new bundle before discovering the mismatch, and on mismatch it logged a warning and continued, because the mismatch handler assumed "hash mismatch means corruption, not compromise." The minified bundle had picked up a transitive dependency that opened an additional outbound socket on a hardcoded host. The allowlist was enforced against the manifest, the sandbox was live, and the extra socket was blocked — but only because that particular host happened to be outside the allowlist. The invariant that failed was not "signatures are verified" but "no capability is granted to bytes that have not been hash-bound to the signed declaration." ## Condition of Validity The defense holds only when all of the following are true simultaneously: 1. The bundle hash is recomputed from the exact bytes the runtime will execute, not from a cached copy or a pre-decompression artifact. 2. Hash comparison occurs strictly before capability grant, with no code path that grants on signature-verify alone. 3. A hash mismatch is treated as a hard failure — the skill does not load — not as a warning. 4. The manifest's capability list is the *sole* source of grants; the bundle cannot self-declare additional capabilities at import time. 5. The sandbox is constructed from the verified manifest, and the sandbox's deny-by-default policy covers capabilities absent from the manifest rather than only those explicitly denied. Condition 5 is the subtle one. Many sandboxes are configured as "deny what the manifest forbids." That inverts the allowlist into a denylist and silently grants everything the manifest forgot to mention — including capabilities a compromised bundle might exercise through a dependency. ## Decision Boundary When the manifest signature verifies but the bundle hash does not match, the correct action is to refuse to load and to quarantine the bundle, regardless of whether the mismatch looks like corruption. The decision boundary is: *signature validity is necessary but not sufficient; hash binding is the gate.* If a pipeline needs to re-sign after minification, that is a manifest-regeneration step, not a loader-side tolerance. If the runtime cannot recompute the hash of the exact executed bytes (e.g., because it loads from a stream it cannot rewind), it must buffer to a verifiable artifact first. There is no safe "trust the signature, log the hash mismatch" mode. ## Operational Effect After moving hash comparison ahead of capability grant and converting mismatch to a hard failure, the loader rejected the stale manifest at load time and surfaced it as a deployment error rather than a runtime anomaly. The practical cost is that every bundle rewrite now requires manifest regeneration, which the pipeline enforces by failing the build when the hash field is stale. The benefit is that the capability allowlist can be reasoned about as a property of signed declarations rather than of whatever bytes happen to be on disk — the sandbox grants exactly what a trusted party signed, and nothing that merely arrived alongside it. ```python import hashlib class ManifestBundleMismatch(RuntimeError): """Raised when a signed manifest does not bind the bytes about to be executed.""" pass class CapabilityNotDeclared(RuntimeError): """Raised when a bundle attempts to exercise a capability absent from its manifest.""" pass def load_skill(manifest: dict, bundle_bytes: bytes, requested_caps: set[str]) -> "Sandbox": # 1. Signature must already have been verified by the caller against a trusted key. if not manifest.get("signature_verified"): raise ManifestBundleMismatch("manifest signature not verified before load") # 2. Hash binding MUST precede any capability grant. actual = hashlib.sha256(bundle_bytes).hexdigest() if actual != manifest["bundle_hash"]: # Hard failure: never fall through to capability grant on mismatch. raise ManifestBundleMismatch( f"bundle hash {actual} does not match signed manifest " f"{manifest['bundle_hash']}; refusing to load" ) # 3. Allowlist is the sole source of grants; deny-by-default. declared = set(manifest["capabilities"]) undeclared = requested_caps - declared if undeclared: raise CapabilityNotDeclared( f"bundle requested undeclared capabilities: {sorted(undeclared)}" ) return Sandbox(grants=declared & requested_caps) ```