vm-core/spec/SENTINEL_V1_SPEC.md

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