vm-core/spec/SENTINEL_OFFLINE_VERIFIER_REQUIREMENTS.md

Sentinel v1 Offline Verifier Requirements

Artifact: vaultmesh-orgine-mobile/spec/SENTINEL_OFFLINE_VERIFIER_REQUIREMENTS.md
Purpose: Verify Sentinel evidence without network, without secrets, without the original runtime, using only exported artifacts.

---

0) Inputs

Verifier accepts either:

• a Seal Bundle directory (recommended), or
• a raw artifact directory (receipts + roots + integrity + manifest)

Required files (seal bundle mode):

• seal.json
• integrity.json
• verifier_manifest.json
• one or more receipt/event files (JSONL or sqlite export, as declared by seal)
• root history file(s) as declared by seal

---

1) Outputs

Verifier MUST produce:

• PASS or FAIL
• deterministic error codes + human-readable explanations
• a machine-readable verification_report.json containing:
  • verified ranges
  • computed roots
  • observed roots (from artifacts)
  • mismatches
  • corruption findings
  • toolchain / schema versions used
  • failure_code (or null)

---

2) Trust Model

• No trust in the producer.
• No trust in timestamps.
• No trust in filesystem ordering.
• Only trust:
  • schemas & canonicalization rules
  • cryptographic hashes
  • deterministic computation

---

3) Verification Phases (MUST implement all)

Phase A — Manifest & Schema Validation

A1. Schema validate

• Validate seal.json, integrity.json, verifier_manifest.json, and each event against their schemas.

Fail if:

• missing required fields
• unknown schema version without explicit compatibility support
• canonicalization version missing or unsupported

A2. Canonicalization version pin

• Verifier MUST enforce canonicalization_version from seal.json / manifest.
• If multiple are present, they MUST match.

---

Phase B — Integrity Manifest Verification

B1. File hash verification

• For every file listed in integrity.json, compute its hash and compare.

Fail if:

• any hash mismatch (hard fail)
• any required file missing (hard fail)
• any file present but not listed (soft fail or warning; policy configurable)

B2. Size & bounds checks

• Enforce max file sizes (configurable) to prevent decompression bombs / giant inputs.

Fail if:

• size exceeds limits without explicit override

---

Phase C — Event Canonicalization & Hashing

C1. Canonicalize every event

• Convert each event into canonical bytes per canonicalization.md.

C2. Compute event_hash

• Compute event_hash = H(canonical_event_bytes).

Fail if:

• event has event_hash and it does not match recomputed hash
• event has no event_hash AND v1 policy requires it (recommended hardening)

C3. Compute op_digest

• Verify op_digest matches canonicalized operation descriptor/params.

Fail if:

• op_digest mismatch

---

Phase D — Chain Verification (Tamper / Rollback Detection)

D1. prev_event_hash chain

• For each event in strict seq order:
• verify event.prev_event_hash == previous.event_hash

Fail if:

• missing seq values
• duplicate seq values
• non-monotonic seq
• chain discontinuity
• chain fork (two events with same seq)

D2. Trace linkage integrity (optional but recommended)

• Where trace_id exists, verify that:
  • action_intent exists before action_executed
  • If no action_executed, then shadow_receipt exists (policy may require)

Fail if (strict mode):

• execution without intent
• denial without shadow receipt (unless explicitly allowed as “impossible-to-write”)

---

Phase E — Merkle Root Verification

E1. Leaf definition

• Leaf = hash(event_hash OR canonical_event_bytes) as specified. Must be consistent with spec.

E2. Root recomputation

• Recompute roots for the receipt range in the seal.

Fail if:

• computed end root != seal.json.end_root
• root history continuity breaks (start root mismatch where applicable)

E3. Root timestamp is non-authoritative

• ts can be displayed but never treated as security-critical.

---

Phase F — Seal Verification

F1. Seal self-consistency

• seal range aligns with included receipts
• seal declares expected roots correctly
• integrity manifest covers all seal files

Fail if:

• declared range doesn’t match included data
• missing roots or receipts required for the range

F2. Optional seal signature (future)

• v1 may omit cryptographic signature; if present, verify it.

---

4) Failure Classes & Codes (Required)

Verifier must map failures to stable codes:

• E_SCHEMA_INVALID
• E_MANIFEST_HASH_MISMATCH
• E_MISSING_REQUIRED_FILE
• E_EVENT_HASH_MISMATCH
• E_CHAIN_DISCONTINUITY
• E_SEQ_NON_MONOTONIC
• E_ROOT_MISMATCH
• E_RANGE_MISMATCH
• E_CANON_VERSION_UNSUPPORTED
• E_OVERSIZE_INPUT
• E_REVOKED_CAPABILITY_USED

This is what makes audits repeatable.

---

5) Corruption Handling Requirements

If verifier detects:

• malformed JSONL segments
• partial file reads
• decode errors

It MUST:

• produce FAIL (unless “best-effort mode” is explicitly requested)
• report:
  • last good seq
  • affected byte ranges (if possible)
  • last valid root
• recommend recovery path:
  • verify older seal bundle
  • restore from WORM copy
  • compare to out-of-band seal digest

---

6) Determinism Requirements

Given identical inputs, verifier output must be byte-identical (except wallclock runtime fields).

• deterministic ordering rules (sort by seq, not file order)
• deterministic JSON serialization for reports (stable key order)

---

7) CLI Interface (Minimum)

• sentinel verify --bundle <path> [--strict] [--report <out.json>]
• sentinel verify --artifacts <dir> --range <since..until>
• sentinel compute-roots --events <events.jsonl>

---

8) Definition of Done

Verifier is “v1 complete” when it passes these drills:

1. Cold archaeology restore
2. Denial proof drill
3. Corruption drill
4. Rollback attempt detection drill