# 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