# VaultMesh Sentinel v1 Specification

Status: Draft v1 (implementation-oriented)  
Goal: A space/IoT-grade “forensic continuity core” that remains truthful under isolation, capture, corruption, and time.  
Non-goals: availability guarantees, global consensus, remote control plane, “SIEM replacement,” full workflow UI.  

Non-goal clarification: Sentinel does not guarantee liveness or uptime under adversarial conditions. It guarantees detectability, attribution, and recoverable truth.

---

## 1) Sentinel v1 Operating Assumptions

- Correctness under isolation: Sentinel must remain verifiable with zero network for months/years.
- Federation optional: peers are witness augmenters, never required for correctness.
- Adversary present: assume capture, coercion, supply-chain drift, narrative pressure.
- Truth > uptime: Sentinel may degrade functionality, but must not silently lie.

---

## 2) System Invariants

Sentinel is “correct” iff all invariants hold.

### I-1 Append-only evidence

- Evidence events are append-only and monotonic by sequence number.
- Any truncation/rollback is detectable via root mismatch.

### I-2 Deterministic verification

- Given the same artifacts, verification must be deterministic across platforms.

### I-3 No silent denial

- If an operation is denied, a ShadowReceipt MUST be emitted (unless physically impossible).

### I-4 No authority amplification

- Automation and recovery actions may only narrow authority, never expand it.

### I-5 Corruption becomes evidence

- Storage corruption must emit CorruptionReceipt with scope of damage (pages/segments) and last known good root.

### I-6 Archaeology-first survivability

- A clean-room restore + verification must succeed using only exported artifacts + verifier.

---

## 3) Sentinel v1 Scope

### Included

- Evidence ledger (append-only receipts)
- Roots (deterministic Merkle)
- Seal bundles (portable witness packages)
- ShadowReceipts (proof of restraint)
- Minimal capability verification (scoped authority)
- Corruption detection + reporting
- Export + verification CLI

### Excluded (v1)

- Full federation sync
- Cloud dashboards
- Remote orchestration beyond export bundles
- Complex policy engines (keep minimal)
- On-chain anchoring required for correctness (optional)

---

## 4) Core Components

### 4.1 Receipt Ledger

Storage: single-file SQLite (preferred) OR append-only JSONL (fallback), but exported artifacts MUST be open and redundant.

Event types (minimum):
- `action_intent` (attempt to perform operation)
- `policy_decision` (recommended; record allow/deny reasoning, or embed in `action_intent.payload`)
- `action_executed` (operation performed)
- `shadow_receipt` (operation denied / restrained)
- `cap_grant` / `cap_revoke`
- `seal_created`
- `root_published`
- `corruption_detected`
- `boot_event` (startup, version, schema hash)
- `health_event` (periodic status, storage checks)

Fields (required per event):
- `event_id` (uuid)
- `seq` (u64 monotonic)
- `ts` (monotonic + wallclock if available)
- `event_type`
- `actor` (capability subject / device identity)
- `cap_hash` (hash of capability JSON or `"none"`)
- `op` (operation name / canonical descriptor)
- `op_digest` (hash of normalized op params)
- `result` (`ok`/`deny`/`error`)
- `root_before` / `root_after` (where applicable)
- `trace_id` (correlates intent → outcome)
- `prev_event_hash` (hash chain for quick tamper evidence)
- `event_hash` (hash of canonical event bytes; verifiable)
- `payload` (bounded JSON with strict schema)

Bounded payload rule: payload size must be capped (configurable), with overflow handled by chunking or external blob with hash reference.

### 4.2 Merkle Root Engine

- Maintain rolling Merkle root of receipt leaves (each leaf = hash(event_canonical_bytes)).
- Support incremental updates O(log n).
- Persist:
  - `ROOT.current.txt` (root + seq + timestamp)
  - `frontier.bin` (or equivalent) for fast restart
  - Deterministic canonicalization rules for event hashing.

Hash function: BLAKE3 (recommended) or SHA-256 (if platform constraints). Must be constant across builds.

### 4.3 Seal Bundles (Ouroboros Seals)

A seal is a portable, offline-verifiable “witness packet”.

Seal contents:
- `seal.json` (metadata + root + ranges)
- `receipts_range.jsonl` (or sqlite page range export)
- `roots.txt` (root history for covered range)
- `integrity.json` (hashes of included files)
- `verifier_manifest.json` (expected tool versions & checksums)

Seal creation policy (v1 default):
- Time-based (e.g., every 24h), OR
- Event-based (N high-risk operations), OR
- Tamper-signal triggered (see §6)

Seal cadence guidance (normative defaults; implementations MAY be stricter):
- Max time window: 24h between seals while in NORMAL mode.
- Max event window: 10,000 events between seals (configurable).
- Mandatory seal triggers: any `tamper_signal` or `corruption_detected` event SHOULD attempt an immediate seal creation (unless physically impossible).

Seal verification must not require network.

### 4.4 Capabilities (Trust, killable)

Format: signed JSON capability tokens.

Fields:
- `sub` (subject identity)
- `scopes[]` (fine-grained)
- `exp` (expiry)
- `nbf` (not-before)
- `aud` (sentinel instance id)
- `jti` (token id)

Rules:
- Deny if expired/invalid signature/wrong audience/revoked.
- Revocation is additive evidence: emits `cap_revoke` receipt.
- Emergency mode may narrow scopes only.

### 4.5 ShadowReceipts (Proof of Restraint)

Emitted when:
- capability check fails
- policy denies
- budget insufficient (if using energy model)
- unsafe context (tamper signals, degraded mode)

Minimum fields:
- `reason_code` (enum)
- `reason_text` (short)
- `would_have_done` (op descriptor + digest)
- `constraints_applied` (scopes narrowed, mode escalated)
- `context_snapshot_hash` (hash of relevant context)

Canonical convention (recommended for audit clarity):
- `payload.side_effects` SHOULD be `"none"` for `shadow_receipt` events.
- `payload.reason_code` SHOULD be from a stable enum (e.g., `policy_violation`, `insufficient_capability`, `insufficient_budget`, `unsafe_context`, `backpressure`, `integrity_degraded`).

---

## 5) Execution Model (Action Gating)

Sentinel sits between “intent” and “effect”.

State machine:
1. `action_intent` emitted
2. Validate capability + context
3. If allowed → execute → emit `action_executed`
4. If denied → emit `shadow_receipt`
5. Always advance receipt root

No operation may execute without producing a receipt trail.

---

## 6) Tamper & Degradation Signals (v1 minimal)

Sentinel accepts a `tamper_signal` input stream (from hardware or host OS). v1 supports:
- acceleration spike / motion pattern
- unexpected power cycle
- secure clock jump / rollback
- enclosure open (if available)
- storage integrity failures

Response: never self-destruct. Instead:
- elevate mode to `DEGRADED`
- narrow allowable scopes
- increase sealing frequency
- emit `corruption_detected` or `tamper_signal` receipt

---

## 7) Storage Integrity & Corruption Handling

Requirements:
- periodic background scan (configurable duty cycle)
- per-page checksums (if sqlite: use `PRAGMA integrity_check` + custom page hashing if needed)
- on detection:
  - emit `corruption_detected`
  - record impacted ranges/pages
  - freeze mutating ops (or narrow to safe subset)
  - create an immediate seal bundle if possible

---

## 8) Interfaces

### 8.1 Local API (host integration)

Provide minimal host-callable interface (C FFI or HTTP on localhost, depending on platform).

Calls (v1):
- `submit_intent(op, params, cap_token) -> trace_id`
- `get_trace(trace_id) -> outcome + receipt references`
- `export_seal(since, until) -> path`
- `verify_bundle(path) -> ok + details`
- `get_root() -> current root + seq`
- `signal_tamper(kind, payload) -> emits receipt + mode shift`

### 8.2 CLI (must ship with artifacts)

Offline verifier requirements: `spec/SENTINEL_OFFLINE_VERIFIER_REQUIREMENTS.md`.

- `sentinel verify --bundle <path>`
- `sentinel compute-roots --from <artifact_dir>`
- `sentinel seal --since "24h"`
- `sentinel export --since "90d" --for auditor`

---

## 9) Artifact Layout (v1 canonical)

```
.state/
  ledger.sqlite
  frontier.bin
  seals/
    ouroboros_seal_YYYYMMDD_HHMMSS/
      seal.json
      receipts.jsonl
      roots.txt
      integrity.json
      verifier_manifest.json
ROOT.current.txt
receipts/
  receipts.jsonl (optional mirror)
  identity.jsonl
  mesh.jsonl
  treasury.jsonl (optional)
```

Mirror strategy: keep SQLite as primary, JSONL mirror for portability (configurable).

---

## 10) Security & Key Management (v1 minimum)

- Device identity keypair (Ed25519 recommended)
- Capability verification public keys pinned locally
- Revocation list stored append-only with receipts
- Keys must be exportable for succession but not casually readable
- Support “Operator Phone” as witness/verifier only (no full node requirement)

---

## 11) Performance & Footprint Targets

- Memory: < 64MB steady state (configurable)
- Storage: < 256MB baseline for 90 days (depends on event volume)
- Receipt append latency: target < 10ms typical
- Sealing: incremental, bounded CPU
- Deterministic behavior under load (backpressure emits ShadowReceipts)

---

## 12) Test & Drill Requirements (Definition of Done)

Required drills (must pass):

1. Cold archaeology restore
   - restore artifacts to empty dir
   - recompute roots
   - verify seals match
2. Denial proof drill
   - attempt forbidden op
   - confirm ShadowReceipt exists
   - confirm no `action_executed` receipt exists
3. Corruption drill
   - corrupt storage segment/pages
   - confirm corruption detected
   - confirm mode degrade + narrowed scopes
   - confirm immediate seal if possible
4. Coercion drill
   - simulate “must sign” request
   - confirm refusal recorded (ShadowReceipt)
   - confirm no authority expansion occurred

---

## 13) Versioning & Compatibility

- Sentinel v1 schemas are append-only. Any breaking change requires a v2 schema and a new `canonicalization_version`.
- Every artifact includes:
  - `sentinel_version`
  - `schema_version`
  - `hash_algo`
  - `canonicalization_version`
- Verifier must support at least:
  - N-2 schema versions (configurable)

---

## 14) v1 Deliverables

- `sentinel-core` library (Rust recommended)
- Sentinel CLI + verifier
- Seal bundle generator + verifier
- Minimal host API
- Reference integration example (IoT gateway simulator)
- Test suite for drills above