Sealing and verification

Architecture, as built › Sealing and verification

A capsule is tamper-evident once it is sealed. NovaFabric has two independent mechanisms:

  1. The NovaSeal capsule seal (experimental). It is written into .seal/ at the end of capture and checked with nova verify <capsule>.
  2. The Evidence Bundle (works today). This is a ZIP with Ed25519-signed in-toto DSSE attestations, built by nova export-evidence and meant to be handed to a third party.

Both rest on SHA-256 and canonical JSON, and both cover the redaction proof.

Seal chain and the five verification checks

Diagram source (Mermaid)
flowchart LR
    subgraph seal["At capture: _seal_capsule (if configured)"]
        F["capsule files<br/>(all but capsule.yaml, .seal/)"] -->|SHA-256 + size| ED["evidence_digests<br/>in capsule.yaml"]
        ED --> CJ["canonical JSON manifest<br/>capsule_id = SHA-256"]
        CJ -->|ECDSA P-256 or Ed25519| DSSE[".seal/manifest.dsse"]
        DSSE -->|RFC 3161| TSR[".seal/manifest.dsse.tsr"]
        DSSE -->|append leaf| ML[("Merkle log DB")]
        ML --> LE[".seal/log-entry.json"]
    end
    subgraph verify["nova verify &lt;capsule&gt;"]
        V1[1 signature] --> V2[2 timestamp] --> V3[3 Merkle inclusion] --> V4[4 manifest binding] --> V5[5 per-file digests]
    end
    DSSE -.-> V1
    TSR -.-> V2
    LE -.-> V3
    ED -.-> V5

Turning sealing on

Sealing is opt-in. trust/novaseal/config.py:load_signing_profile looks for NOVAFABRIC_SEAL_CONFIG and then for $NOVAFABRIC_HOME/novaseal.yaml (~/.novafabric/novaseal.yaml when NOVAFABRIC_HOME is unset). If neither exists, capture skips sealing. Sealing never blocks a capture: on any error, capture/finalize.py:seal_capsule prints a warning and the capsule is kept, without .seal/. create_envelope refuses to sign with a key that does not match the configured certificate, so a capture never writes a seal that cannot verify.

First run (experimental, ADR-0301). nova init does not configure sealing; it offers nova seal init as a next step. That command (trust/novaseal/local_identity.py:init_local_identity) creates a dedicated ECDSA P-256 signing key, a local seal CA and a leaf certificate under keys/novaseal/ (private keys mode 600), and writes a managed novaseal.yaml (profile: local, no tsa_url, so no network access). The identity is self-asserted: a seal made with it proves that the holder of the key signed, not who that holder is. nova seal init --force rotates the key under the same CA and records a key_rotation entry in the Merkle log, so a verifier who pinned ca.crt.pem keeps validating old and new capsules. A novaseal.yaml that nova seal init did not write is never replaced.

The key comes from one of four signing profiles: local (a PEM key on disk), aws_kms, azure_kv or gcp_kms. The cloud profiles sign through a signing backend, so the private key never leaves the KMS. See NovaSeal configuration and key management.

What gets signed

  1. Per-file digests. capture/finalize.py:evidence_digests hashes every file in the capsule except capsule.yaml (which carries the result) and .seal/ (which does not exist yet). It records sha256 and size_bytes for each, writes the map into the manifest as evidence_digests, and rewrites capsule.yaml. The signed payload also names the manifest file it binds, _novaseal.manifest: capsule.yaml (reserved seal metadata, never part of capsule.yaml), so a verifier knows which file must exist.
  2. Canonical payload. trust/novaseal/__init__.py:NovaSeal.seal serialises the manifest as sorted-key compact JSON. The capsule_id is the SHA-256 of those bytes.
  3. DSSE envelope. trust/novaseal/envelope.py:create_envelope signs the payload with ECDSA P-256 / SHA-256. A local Ed25519 PEM key is also accepted. The payload type is application/vnd.novafabric.capsule+json, and each signature carries a keyid (SHA-256 of the signer certificate) and the certificate itself. The envelope is written to .seal/manifest.dsse. The signature is computed over the standard DSSE v1 pre-authentication encoding, so stock DSSE verifiers accept it. Seals made by v0.102.x and earlier used a non-standard encoding; nova verify still accepts them and labels them legacy envelope.

Because redaction-proof.json is one of the digested files, the signature covers the redaction proof. A capsule cannot be re-redacted after sealing without breaking verification.

RFC 3161 timestamp

trust/novaseal/timestamp.py and trust/_rfc3161.py request a timestamp token over the envelope from a Time Stamping Authority and write it to .seal/manifest.dsse.tsr.

Timestamping is opt-in (ADR-0292). There is no default TSA.

Setting Behaviour
tsa_url / tsa_urls omitted or empty No timestamp and no network call; one warning per process
tsa_url: <url> That TSA, and only that one, is contacted
tsa_urls: [...] An ordered fallback list
TSA unreachable The seal still succeeds, with an empty .tsr and a warning

Through v0.102.x an omitted tsa_url meant https://freetsa.org/tsr; to keep that behaviour, set it explicitly. The timestamp covers the signed envelope, signature included, so it sits outside the signature by design; nova verify checks that the token's message imprint matches this envelope.

An intact token is not a trusted time (works today). Checking the token proves it is bound to this envelope and was not edited. It does not prove who the TSA is: anyone can mint a TSA certificate and sign any genTime, for example a backdated one. Only a TSA chain that reaches a TSA trust anchor you supply (nova verify --tsa-ca-bundle, or tsa_ca_certs in novaseal.yaml) makes the time trusted. There is no built-in default TSA trust bundle, and tsa_url anchors nothing (it is only where seals request tokens). The verifier reports this as timestamp_trust, separate from timestamp_ok:

timestamp_trust Meaning timestamp_ok
anchored token intact, and its TSA chain reached your TSA anchor at its genTime true
unanchored token intact and bound to this envelope; the TSA is not validated, so its time is a claim true
absent no token (timestamping is opt-in) null
invalid the token failed integrity, or failed the anchored chain check false

timestamp_ok keeps its meaning (token integrity) and an unanchored token does not change the exit code, because failing every timestamped capsule for every verifier without a TSA CA bundle would be a breaking change. Instead the text report prints UNANCHORED with the claimed genTime and TSA name, never OK, and nova verify --strict fails on it.

The Merkle log

trust/novaseal/merkle.py keeps an append-only log of seal events. It is not a tree over the files of one capsule.

The root is versioned (works today, ADR-0313). A log has one root version for its whole life, recorded in the log database and next to every root it hands out (root_version in log-entry.json, in consistency proofs and on witness checkpoints). An absent root_version means v1.

Version Written by Tree Commits to the tree size?
v2 every log created from ADR-0313 on RFC 6962 / RFC 9162 Merkle Tree Hash: split at the largest power of two, no duplication; RFC 9162 inclusion and consistency proofs yes
v1 every log and seal written before ADR-0313 an odd level is padded by duplicating its last node no — [a, b, c] and [a, b, c, c] share a root

Because a v1 root cannot tell n leaves from n + 1 with the last one duplicated (sealing the same capsule twice produces exactly that), every verification path compares a root together with its tree size, for both versions: verify_consistency_proof() needs old_size and new_size, nova verify fails a log-entry.json whose root_hash has no tree_size, and when the sealer's log is present it recomputes the recorded tree head from the log's own leaves. A v1 carried proof alone cannot detect a wrong tree_size; the report notes this. Existing v1 logs stay v1 and keep verifying. NovaFabric releases older than ADR-0313 cannot verify a v2 seal's carried proof.

Moving a host to v2 roots. Start a new log file (merkle_db) and list the retired v1 log under previous_merkle_dbs in novaseal.yaml. Verification then checks v1-era capsules against the log that sealed them; nothing is appended to a previous log. If you leave it out, a v1 capsule verified on the host reports sealer_log: unverifiable-other-version (see check 3 below).

A second Merkle construction belongs to the Evidence Bundle. evidence/merkle.py:capsule_merkle_root computes an RFC 6962-style root over all files in a capsule (the same tree shape as a v2 log root, over different leaves — the two are never mixed). That root is the subject digest of the bundle's in-toto statements (see below). Its v2 leaf (ADR-0310) commits to each file's capsule-relative path as well as its contents, so renaming or moving a file changes the root. v2 leaves use their own domain byte (0x02; v1 leaves 0x00, inner nodes 0x01), so a v1 root over other files cannot equal a v2 root. Roots recorded before ADR-0310 (v1, contents only) still verify through capsule_root_matches; a renamed capsule never satisfies a v2 root. Comment and annotation subjects deliberately stay on v1, so existing comments stay attached.

Verification: nova verify <capsule>

cli/verify.py:verify_cmd reads the NovaSeal configuration and checks each layer in turn:

# Check Passes when
1 DSSE signature The envelope signature verifies against the embedded certificate. The signing intent is reported as signed only when the copy inside the signed payload (_novaseal.signing_intent, ADR-0309) agrees with the entry's label; an edited label fails. A seal made before ADR-0309 reports label-only.
2 RFC 3161 token The token parses strictly, its status is granted and its message imprint matches this envelope. This is integrity, not trusted time: without a TSA CA bundle the line reads UNANCHORED and timestamp_trust is unanchored (see RFC 3161 timestamp). If no token is present, the output says NOT PRESENT, timestamp_ok is None (absent, not passed) and the seal stays valid, unless a TSA CA bundle is supplied. A token that cannot be parsed strictly (a BER encoding) is reported as a structural check only, never as OK, and still must prove the same bindings: the CMS signature verifies, the signed messageDigest equals the hash of the TSTInfo, and the TSTInfo messageImprint is this envelope's hash. A signature that cannot be extracted or checked fails (timestamp_ok False).
3 Merkle inclusion The proof carried in log-entry.json reproduces its root at its tree_size (under its root_version) and the entry names this capsule. If a local log is configured, it is checked as well: the recorded index must hold this leaf (a manifest sealed twice has the same leaf twice; each copy verifies at its own index), and the log's leaves must reproduce the recorded tree head (size and root). A log that holds other seals by the same signer is the signer's log, whatever its root version. An entry missing from the signer's log of the record's root version fails, carried proof or not, and so does a record claiming a newer root version than every signer's log (a v2 record against a v1 log: v2 logs came later). A v1 record on a host whose signer's log is v2 is checked against previous_merkle_dbs; without them it keeps its carried-proof result but reports sealer_log: unverifiable-other-version. Another signer's log, a fresh log, or no log keeps the carried-proof result.
4 Manifest binding The manifest the capsule was sealed with (_novaseal.manifest; capsule.yaml for any seal that carries evidence_digests) exists and equals the signed payload, and capsule_id matches. A missing sealed manifest fails. Any other manifest-named file (capsule.yaml, capsule.json) that the seal does not cover and that differs from the payload fails: readers accept capsule.json as a manifest, so it is a substitute, not an extra file. Only a seal that names no file (made before evidence_digests) reports a missing manifest as NOT PRESENT.
5 Per-file digests Every file listed in evidence_digests exists and matches its SHA-256. A file that a signed *_ref field names (for example tool_calls_ref: tool-calls.jsonl) but that was added after sealing fails. Other extra files, such as c2pa-manifest.json from nova export-c2pa, are listed as "not covered by the seal" and do not fail (ADR-0251 §5).

The exit code is 0 when every check passes, 1 otherwise, and 2 on a usage error (an incompatible flag combination, such as --crl-dir with no CA bundle). Optional hardening flags are experimental:

What the sealer's log check can and cannot decide (sealer_log). The record's root_version lives in log-entry.json, which whoever wrote the capsule controls, and it is not inside the signature (the log entry is appended after signing; and a key holder could sign any value anyway). So the verifier never lets that field decide whether a log counts:

sealer_log Meaning
entry-found a supplied log holds the entry (log_inclusion is local-log, or failed on a mismatch)
missing the signer's log lacks the entry, or the record claims a newer root version than it — fails
unverifiable-other-version only a newer-version signer's log is available. A genuine pre-migration v1 capsule and a key holder's forgery claiming v1 look the same here. Not a failure by default; --strict fails
not-sealer-log the supplied logs hold no seals by this signer (another sealer's log, or a fresh one)
no-log no log on this machine
not-consulted the capsule's own log metadata failed first

Library callers pass the earlier logs as verify_seal_dir(..., previous_logs=[...]), or use verify_with_profile(seal_dir, profile), which opens merkle_db, previous_merkle_dbs and tsa_ca_certs from novaseal.yaml the way nova verify does. POST /api/runs/{id}/verify and the trust radar use trust/novaseal/capsule_verify.verify_capsule, the same function as nova verify. The radar shows an unanchored timestamp as a warning, not a passed axis. Verification opens a SQLite log read-only (mode=ro): it never creates, migrates or writes it. SQLite may add its -wal/-shm files next to a WAL-mode log.

Readers use the sealed manifest. The query indexer (nova query, nova trend, the runs list), the in-toto statement builder, the agent graph and GET /api/runs/{id}/children read a sealed capsule's manifest from the signed payload of .seal/manifest.dsse (novafabric/_capsule_manifest.read_capsule_manifest), never from an on-disk capsule.yaml or capsule.json. A substituted manifest therefore cannot change the status, asset or run id they report. They do not check the signature; nova verify does. The in-toto builder refuses (UnsealedManifestError) to attest a sealed capsule that carries an unsealed manifest file or signed-ref target.

nova verify also accepts an Evidence Bundle .zip, and runs the whole recipe below: manifest_hash, every artifact digest, every attestation's DSSE signature and each statement's subject (evidence/bundle_verify.py). Because manifest.json is not signed, the run subject is recomputed from the bundle's run-capsule/ copy and the lineage subject from edges.jsonl, rather than read from the manifest. For the same reason, the runs a bundle reports are exactly the runs its verified run statements sign: every subject entry must match a verified run statement (capsule hash, run_id and capsule_path_in_bundle), no entry may repeat, a legacy top-level run_id must be a signed run, and a signed run the manifest omits fails. A run statement must sign its predicate.run_id for a subject.run_id label to pass. manifest.json is read with a 64 MiB bound. The verifying key ships inside the bundle, so pass --public-key to pin the signer; without it the report says the signer is not pinned. It also accepts an export-manifest.json from a batch export. POST /api/evidence/{bundle_id}/verify in nova serve calls the same verify_bundle_archive, so the dashboard and the CLI cannot disagree. Its anchor is the operator's trust list (NOVAFABRIC_EVIDENCE_TRUSTED_KEYS, default $NOVAFABRIC_HOME/evidence-trusted-keys.pem, PEM public keys), never a key in the request: signer_trust is anchored, unanchored (no list: consistency only), untrusted (fails) or none. A configured list that cannot be used is an error, not "unanchored". The route reports run_ids (every signed run) and run_id (the signed run when exactly one verified, else null), never a label from the unsigned manifest. GET /api/evidence and GET /api/evidence/{bundle_id} report the same verifier's verdict as verified, cached per file identity (device, inode, size, mtime, ctime) and trust list.

Signer trust level (experimental, ADR-0301). Besides the pass/fail checks, nova verify reports what the verifier established about who signed, as identity_trust in the text report, in nova verify --json, in VerificationResult and in POST /api/runs/{id}/verify:

identity_trust Meaning Claim it permits
none no signature verified nothing
self-asserted signature verifies under the envelope's own certificate; nothing the verifier trusts vouches for it "unchanged since signed by the holder of this key"
local-ca-pinned --ca-bundle validated the chain to a nova seal init local CA the above, plus continuity with that installation across key rotations
ca-anchored --ca-bundle validated the chain to another CA "signed by a key certified by that CA", at that CA's assurance

The O=NovaFabric local seal identity (self-asserted) subject marker can only lower a label, never raise it. Where a key lived (file, KMS, HSM) cannot be seen from a capsule and is never claimed. A Sigstore trust level on --backend sigstore is planned.

Where verification can run. Every check uses only the capsule, so nova verify runs anywhere and never creates a log. The carried proof's root is not independently anchored, and the output says so. For a capsule sealed by v0.102.x or earlier, verified away from the sealer's log, check 3 prints NOT CHECKED — log not available and does not fail.

Maker-checker signing (experimental)

nova seal propose (maker) and nova seal approve (checker) add a separation-of-duties signature chain on top of the capsule seal. nova seal verify checks that chain. nova seal bypass creates a time-limited, audited exception. Every promote signer must chain to a pinned CA (--ca-bundle or NOVAFABRIC_PROMOTE_CA_BUNDLE, ADR-0315); with none configured, verification refuses (exit 3) unless --insecure-self-signed is given for development. A bypass counts only when it is signed by an approver in the latest policy, names this capsule, is unexpired by its signed valid_until, and the hash-chained audit log holds its seal.bypass.create entry and no seal.bypass.abort (review r8; opt out with NOVAFABRIC_PROMOTE_BYPASS_AUDIT_OPTIONAL=1 for a store copied without its log). A bypass whose file cannot be stored after its entry was written is withdrawn with a seal.bypass.abort entry. Appends to the audit log are serialised across threads and processes (fcntl.flock on the log plus an in-process lock), so concurrent writers never fork its hash chain (NovaSeal configuration §4.1). nova seal ratchet is an opt-in forward-secure per-node key ratchet. All of these live in cli/seal_propose.py.

The Evidence Bundle: verification without NovaFabric (works today)

nova export-evidence <capsule> -o bundle.zip runs evidence/bundle.py:EvidenceBundleBuilder:

  1. Check the capsule. The capsule must hold no symbolic link, and the required files, including redaction-proof.json, and the inputs/ and outputs/ directories must exist. Otherwise the export is refused, before anything is written. A link would put its target (for example ~/.ssh/id_rsa) into the bundle as capsule content, signed and past redaction; NovaFabric never writes one into a capsule, and a ZIP entry and the capsule Merkle root cannot represent one. The refusal names each link and whether it points inside or outside the capsule, or dangles. The path used to reach the capsule may itself be a link (runs/latest).
  2. Policy gate. The export decision is recorded in the audit log.
  3. Stage the contents: run-capsule/, lineage-subgraph/edges.jsonl, schemas/ and a README.md. The capsule is copied with links kept as links and checked again, so a link that appears after step 1 is refused, never followed.
  4. Sign attestations. It writes in-toto Statement v1 envelopes (attestations/run.intoto.json, redaction.intoto.json, lineage.intoto.json), signed with Ed25519 (evidence/intoto.py), each with a matching signature and public key. The run statement's subject is the capsule Merkle root.
  5. Write manifest.json (schemas/evidence-bundle.schema.json). It carries a SHA-256 for every artifact and a plain-text verification recipe.

What is in the bundle

This is the one authoritative list; other pages summarise it and link here. tests/docs/test_evidence_bundle_contents.py builds a real bundle and checks the list against the ZIP.

Entry What it is
run-capsule/ A copy of the whole capsule directory: capsule.yaml, the record streams, env.lock, redaction-proof.json (the secret-scan record), inputs/, outputs/ and, when the capsule was sealed at capture, .seal/
lineage-subgraph/edges.jsonl The capsule's lineage edges (empty when it recorded none)
schemas/ The JSON Schemas shipped with the exporting novafabric version
attestations/ Ed25519-signed in-toto Statement v1 DSSE envelopes: run (subject: the capsule Merkle root), redaction (subject: the redaction proof's chain hash), lineage, bundle (the members statement: the SHA-256 of every other file and of the manifest's fields), and energy when the capsule has energy-receipts.jsonl (experimental, ADR-0093)
signatures/ Each envelope's raw signature (.sig) and the signer's public key (.cert, PEM)
manifest.json SHA-256 and size of every other file, the attestation and signature index, subject.capsule_hash, the verification recipe and manifest_hash; with --with-custody, the chain-of-custody blocks (experimental, ADR-0095)
README.md The verification recipe in plain text; with --timestamp, also the OpenSSL steps for the token. Its digest in manifest.json is recorded after that section is added
manifest.dsse.tsr Only with --timestamp: an RFC 3161 token over attestations/run.intoto.json. Listed in artifacts[] like every other file, and also pinned by manifest_dsse_tsr_sha256

--dsse writes <bundle>.dsse.json next to the ZIP, not inside it.

The recipe needs only a SHA-256 tool and an Ed25519 verifier:

  1. Recompute the manifest hash.
  2. Recompute each artifact's SHA-256.
  3. Verify each DSSE envelope over its pre-authentication encoding.
  4. Check each statement's subject against what its predicate type covers: the run statement's subject is subject.capsule_hash, recomputed as the root of the files under run-capsule/; the lineage statement's is the SHA-256 of lineage-subgraph/edges.jsonl; the redaction statement's is the chain_hash in run-capsule/redaction-proof.json; an energy-receipts statement (present only when the run recorded energy) covers run-capsule/energy-receipts.jsonl. The bundle's own README.md carries the same recipe (evidence/bundle.py).
  5. Check the members statement (attestations/bundle.intoto.json): every file except manifest.json and the statement's own three files has the digest it signs, and the manifest's fields hash to its manifest_core_sha256.

Every member is signed (works today; review r8)

Before the members statement, nothing signed README.md, the vendored schemas/ or the manifest's own fields (verifier_instructions, schemas[]). manifest.json is not signed and its manifest_hash is a self-hash anyone can recompute, so a recipient holding a bundle whose README said "Verified by the EU AI Office" and whose run-capsule.schema.json accepted anything got PASSED from nova verify --public-key. Now:

Optional additions: --timestamp (an RFC 3161 token for the bundle), Rekor publication of the run envelope with --sigstore when NOVA_REKOR_URL is also set (skipped with a warning otherwise), and an outer DSSE envelope.

Other trust surfaces

Surface Maturity Where
Sigstore keyless signing, nova seal sign --backend sigstore and nova verify --backend sigstore experimental, needs the [sigstore] extra cli/seal_propose.py, cli/verify.py
Rekor transparency-log publication opt-in, best effort: nova seal approve / nova seal bypass publish when NOVA_REKOR_URL is set; an evidence bundle also needs nova export-evidence --sigstore promote/rekor_client.py
Witness cosigning of tree heads experimental, library only trust/novaseal/witness.py
Ledger checkpoint Merkle inclusion, nova ledger verify --merkle-db experimental trust/ledger/_verify.py — without --merkle-db, exit 0 only means the checkpoint's (unsigned) merkle block is self-consistent; a fabricated one-leaf tree passes. With it, the log must hold the checkpoint and reproduce the recorded tree head
PII redaction manifest (RedactionManifest, with its legal_hold_mode field; there is no capture flag for it) experimental, library only compliance/pii/manifest.py
Signed subject-proof reports (nova verify --check-redaction) experimental cli/redact.py

The roadmap and the decisions index track which further seal-layer capabilities are planned (for example, a dedicated network signing service and post-quantum signatures). None of them is implemented.