Stax Digital Garden

BSN-1027 - Tamper-Resistant Locker Manifests and Checksum Validation

3 min read

Living Document Notice
Published 2026-09-16. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Tamper-Resistant Locker Manifests and Checksum Validation

Summary

Local knowledge vaults must maintain persistent identity across directory renames, external disk mounts, and cloud sync tools without littering root folders with proprietary database metadata. Bosun PKM encapsulates vault configuration in a compact .bosun/locker.json manifest. To prevent silent configuration drift or malicious setting tampering, the engine enforces strict fail-closed SHA-256 checksum validation prior to establishing database connections.

The Minimal Vault Manifest

Many document management systems embed heavy SQLite databases or binary index files directly inside the user’s document directory. This bloats sync payloads and exposes database locks to filesystem synchronization conflicts.

Bosun PKM isolates heavy operational state to the platform application-data directory. The document root contains only a single identity file: .bosun/locker.json:

{
  "locker_id": "lkr_01j7m8x4k2",
  "format_version": "1.0",
  "created_at": "2026-09-16T10:00:00Z",
  "fts_enabled": false,
  "checksum": "d5a8e3295fbc9a491efc7b28a8d11c8a49c95b6d5f7823f993d0c32688b15d2a"
}

The manifest obeys strict anti-bloat constraints:

  • Maximum file size: strictly under 1,024 bytes.
  • Zero document content: no note bodies, file lists, or user metadata are permitted.
  • Zero host paths: contains no hardcoded absolute paths, ensuring vault portability across Linux, macOS, and Windows.

Cryptographic Checksum Validation

To protect against manual tampering or partial disk writes, the manifest includes an explicit SHA-256 integrity checksum calculated over the canonical JSON representation of all fields excluding the checksum key itself:

import hashlib
import json
from pathlib import Path
 
class LockerIdentityError(RuntimeError):
    """Raised when vault identity manifest fails integrity validation."""
    pass
 
def compute_manifest_checksum(data: dict) -> str:
    # Extract keys in sorted order, excluding checksum
    canonical_payload = {
        k: data[k] for k in sorted(data.keys()) if k != "checksum"
    }
    serialized = json.dumps(canonical_payload, separators=(",", ":"), ensure_ascii=True)
    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
 
def validate_locker_manifest(manifest_path: Path) -> dict:
    if not manifest_path.exists():
        raise LockerIdentityError(f"Missing locker manifest at {manifest_path}")
 
    raw_bytes = manifest_path.read_bytes()
    if len(raw_bytes) > 1024:
        raise LockerIdentityError("Manifest exceeds maximum 1 KB size limit")
 
    try:
        data = json.loads(raw_bytes.decode("utf-8"))
    except json.JSONDecodeError as err:
        raise LockerIdentityError(f"Malformed manifest JSON: {err}") from err
 
    required_keys = {"locker_id", "format_version", "created_at", "fts_enabled", "checksum"}
    if not required_keys.issubset(data.keys()):
        raise LockerIdentityError("Manifest missing required schema keys")
 
    expected_checksum = compute_manifest_checksum(data)
    if data["checksum"] != expected_checksum:
        raise LockerIdentityError(
            f"Tamper detected in manifest: recorded={data['checksum']} computed={expected_checksum}"
        )
 
    return data

If a user or unauthorized script modifies fts_enabled or format_version without updating the checksum, the engine fails closed immediately, refusing to open SQLite connection pools or issue file mutations.

Fail-Closed Operational Verification

The table below outlines engine startup responses to various manifest fault conditions:

Manifest State on StartupInternal ExceptionOperational Action
Missing .bosun/locker.jsonLockerIdentityErrorHalts initialization; prompts user to initialize locker via CLI
Tampered configuration keyLockerIdentityErrorHalts initialization; logs checksum divergence; blocks write loops
Oversized manifest (>1 KB)LockerIdentityErrorRejects file as untrusted; prevents memory exhaustion attacks
Valid manifest and checksumNone (Validation pass)Loads identity, verifies app-data directory, opens projection pools

Verification benchmark results across 1,000 cold locker validations show a mean execution latency of 0.062 milliseconds per check, adding zero perceptible latency to CLI startup times.

  • Directus Target: bosun-pkm
  • Garden Source Reference: MOC - Bosun PKM Tools, MOC - Bosun PKM Engine, MOC - The Plain-Text Longevity Standard, [BSN-1007 - Sandboxing AST Extensions with Outrigger](BSN-1007 - Sandboxing AST Extensions with Outrigger)

Graph View