Initialize repository snapshot
This commit is contained in:
Vault Sovereign
225
spec/SENTINEL_OFFLINE_VERIFIER_REQUIREMENTS.md
Normal file
225
spec/SENTINEL_OFFLINE_VERIFIER_REQUIREMENTS.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user