Offline verification

When to use itCopy Anchor Link

Use the verifier when you hold an export and want to know how strongly it can be believed: an auditor reading a change, a CI job gating on evidence, a second team re-checking a run, or a developer of another verifier comparing results. It needs no engine and opens no network connection.

PrerequisitesCopy Anchor Link

• A checkout of the public repository and the Go toolchain declared by its go.mod.
• An export directory.
• The runner public key, the log public key and the log origin, each obtained out of band. A key file holds the 32-byte public key as 64 hexadecimal characters, with optional surrounding whitespace, in at most 1024 bytes.

git clone https://github.com/dsha256/numinance-spec.git
cd numinance-spec
go build -o ./bin/numi ./cli/numi

go run ./cli/numi evidence verify ... works the same way without a build step. Installing numi gives you this verifier and the other open commands. It does not install an autonomous engineer, and it cannot produce exports.

Command referenceCopy Anchor Link

numi evidence verify [flags] DIR

Exactly one key mode is required: pinned --runner-key, --trust-bundle-keys or --skip-signatures. None, or two, is a usage error (exit 2). --trust-bundle-keys is refused together with a pinned key or --skip-signatures. A key file over 1024 bytes is an error and is never read as a truncated key.

A full pass, in text and in JSONCopy Anchor Link

The fixture is conformance/evidence/v1/exports/closed-author, run from conformance/evidence/v1 of the spec checkout. It is a golden export generated with fixed test keys.

$ numi evidence verify --runner-key keys/runner.pub --log-key keys/log.pub --log-origin numinance.test/log --complete exports/closed-author
change: chg_01010101010101010101010101010101
records: 12, head sha256:8dec4e3d5cf4bd7650ef6010671298793c05493cb20c3dd946bc3ef805689e48
state: ended Closed
level: verified
chain: records link, hash and end as stated
signatures: verified under the pinned runner keys
anchor: head proved under the pinned log
attestation: signed, re-derived from the chain
credential_scopes: unsourced: no credential broker statement is in the attestation
network_policy: unsourced: no egress proxy statement is in the attestation
not applicable: deployment.json (not applicable at PR level: the change closed from Merging (design section 6) and was never released, deployed or observed)
not applicable: observation.json (not applicable at PR level: the change closed from Merging (design section 6) and was never released, deployed or observed)
result: verified

With --json the same run prints one object. The not_applicable array is shortened here for reading; the run printed the full strings.

{"ok":true,"change_id":"chg_01010101010101010101010101010101","records":12,
 "head_record_hash":"sha256:8dec4e3d5cf4bd7650ef6010671298793c05493cb20c3dd946bc3ef805689e48",
 "anchored_head_record_hash":"sha256:8dec4e3d5cf4bd7650ef6010671298793c05493cb20c3dd946bc3ef805689e48",
 "ended":true,"terminal_state":"Closed","sealed":false,
 "level":"verified","level_enum":"verified","weakened_by_flags":[],
 "chain":"records link, hash and end as stated",
 "signatures":"verified under the pinned runner keys",
 "anchor":"head proved under the pinned log",
 "attestation":"signed, re-derived from the chain",
 "not_applicable":[{"part":"deployment.json","not_applicable":true,"...":"..."},{"part":"observation.json","not_applicable":true,"...":"..."}],
 "credential_scopes":"unsourced: no credential broker statement is in the attestation",
 "network_policy":"unsourced: no egress proxy statement is in the attestation"}

The JSON reportCopy Anchor Link

A report is printed only when the verifier got as far as verifying a directory. Exit 2, a refused path (3) and a missing path (4) print none.

Exit codesCopy Anchor Link

Exit 6 is never produced by verify. Exit 5 is "a conflict" elsewhere in the numi table, but verify never produces a conflict: for verify, 5 means the directory is consistent and the check was weaker than verified. Exits 1, 7 and 8 depend on the environment and have no data vector.

Tampering is a named findingCopy Anchor Link

Copy the fixture, change one byte of one record (the risk_class of record 6 from READ to HIGH), and run the same command.

level: failed
FAIL digest_mismatch: a file differs from its index entry
FAIL chain_broken: a record does not match its record_hash
FAIL part_contradiction: a part is declared not applicable and the chain does not bear it out
FAIL part_contradiction: a part is declared not applicable and the chain does not bear it out
result: failed

The edit is caught three ways at once: the index digest no longer matches, the record no longer hashes to its record_hash, and, because the chain is no longer verified, the claim that deployment and observation are not applicable can no longer be borne out. All of these are findings and the exit is 3. Appending a line to diff.digest instead gives digest_mismatch, diff_mismatch and manifest_mismatch, also exit 3.

Pinning the wrong keyCopy Anchor Link

Pin a key that did not sign the export (keys/other-runner.pub) and the verifier does not fall back to the key the directory claims.

FAIL signer_untrusted: a record names a key that is not trusted
FAIL part_contradiction: a part is declared not applicable and the chain does not bear it out
FAIL part_contradiction: a part is declared not applicable and the chain does not bear it out
result: failed

A wrong log pin fails the same way. Pinning the right key with the wrong origin, or the wrong log key with the right origin, gives anchor_invalid, attestation_proof and manifest_mismatch, with messages that say "the checkpoint origin is not the pinned origin" or "the checkpoint signature does not verify under the pinned log key".

Binding the result to a change or a headCopy Anchor Link

A verifier cannot tell an export from another genuine export of the same change signed by the same keys. If you know the change or the head from another source, say so.

numi evidence verify \
  --runner-key keys/runner.pub --log-key keys/log.pub --log-origin numinance.test/log \
  --expect-change chg_01010101010101010101010101010101 \
  --expect-head sha256:8dec4e3d5cf4bd7650ef6010671298793c05493cb20c3dd946bc3ef805689e48 \
  exports/closed-author

result: verified

FAIL expectation_mismatch: the change is not the one expected
result: failed

--expect-head accepts either the last record's hash or the anchored hash. They differ on a sealed chain, where the last record is the seal and the log holds the terminal record before it.

Calling the package from GoCopy Anchor Link

numi evidence verify is a thin wrapper over evidenceverify.Verify. A Go program can call it directly. The package is in the module github.com/numinance/numinance-spec and has no dependency outside the standard library. No tagged release of the module is published, so until one is, point a replace at your checkout.

package main

import (
	"context"
	"crypto/ed25519"
	"fmt"
	"os"
	"time"

	"github.com/numinance/numinance-spec/sdk/go/evidenceverify"
)

func main() {
	dir, runnerFile, logFile := os.Args[1], os.Args[2], os.Args[3]

	runnerKey, err := evidenceverify.ReadKeyFile(runnerFile)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(2)
	}
	logKey, err := evidenceverify.ReadKeyFile(logFile)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(2)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	rep, err := evidenceverify.Verify(ctx, dir, evidenceverify.Options{
		RunnerKeys: []ed25519.PublicKey{runnerKey}, // pinned out of band
		LogKey:     logKey,                         // pinned out of band
		LogOrigin:  "numinance.test/log",
	})
	if err != nil {
		fmt.Fprintln(os.Stderr, "no report:", err)
		os.Exit(evidenceverify.ExitCode(nil, err))
	}

	fullPass := rep.ExitCode() == 0 && rep.LevelEnum == "verified" && len(rep.WeakenedByFlags) == 0
	fmt.Printf("level=%q level_enum=%q weakened_by_flags=%v findings=%v full_pass=%v\n",
		rep.Level, rep.LevelEnum, rep.WeakenedByFlags, rep.FindingCodes(), fullPass)
	os.Exit(rep.ExitCode())
}

module example.com/check

go 1.27

require github.com/numinance/numinance-spec v0.0.0

replace github.com/numinance/numinance-spec => /path/to/numinance-spec

This program was built with the Go toolchain against the spec checkout through exactly such a replace, with the module cache offline. It passed go vet and ran three times:

$ ./check exports/closed-author keys/runner.pub keys/log.pub
level="verified" level_enum="verified" weakened_by_flags=[] findings=[] full_pass=true

$ ./check exports/closed-author keys/other-runner.pub keys/log.pub
level="failed" level_enum="failed" weakened_by_flags=[] findings=[part_contradiction signer_untrusted] full_pass=false

$ ./check exports/nope keys/runner.pub keys/log.pub
no report: the directory does not exist

The exported surface you need is small. Options carries RunnerKeys, TrustBundleKeys, SkipSignatures, LogKey, LogOrigin, AllowUnanchored, AllowIncomplete, AllowUnsigned, Complete, ExpectChange and ExpectHead. Verify returns a *Report whose fields mirror the JSON keys above (LevelEnum, WeakenedByFlags, Findings, Absent). When there is no report, Verify returns an *Error whose Kind (KindUsage, KindInvalid, KindNotFound, KindUnavailable, KindTimeout, KindInternal) maps to exit codes 2, 3, 4, 7, 8 and 1 through ExitCode(rep, err). ParseKey and ReadKeyFile read key files the way the command does. Read the exact definitions in the package before you depend on a field.

What the verifier checks, in orderCopy Anchor Link

1. Read the directory and refuse what cannot be read.
2. Name check, then the index against every file.
3. Decode the summary.
4. Walk the chain: decode, links, signatures, bounds; then compare the summary and diff.digest with what the records give.
5. Anchor: decode signers.json, verify the head proof under the pinned log.
6. Derived parts: the three views, tool-events.ndjson, change.json.
7. Attestation: signature, re-derivation, per-change checkpoint and proof.
8. Ticket cross-check, then the manifest.
9. Parts present or declared absent, then the level.

Steps that need a verified chain do not run when the chain did not verify, and are reported as not checked. The directory checks, the index, the presence of the attestation and the manifest, and the parts always run, so one failure can come with others. The set of finding codes is normative; their order in a report is not.

TroubleshootingCopy Anchor Link