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