ShellGuard v0.0.2.6

🦞 ShellGuard — Release v0.0.2.6

"The Cryptographic Audit Hardening & Third-Party Auditability" — Phase 24: Vector Parity, Mechanized Constant-Time Sweeps, Auditor's Battery & Threat Model Addendum
ClawStack Studios ©™ · 2026-10-18 · AGPL-3.0

The reef achieves mathematical certainty and transparent third-party auditability. ShellGuard v0.0.2.6 (Build 28) hardens the cryptographic core — proving pure-TypeScript WebCrypto fallback parity against official NIST/RFC standards vectors, mechanizing constant-time comparisons across all authentication and administrative key paths, codifying an automated Docs-as-Code claim battery into the build gates, and formalizing runtime operational realities in the threat model.

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗   ██╔════╝ 
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝   ███████╗ 
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗   ██╔═══██╗
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║  ╚██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝ 
                                              ~ **ClawStack Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.6 (Build 28) of ShellGuard! This release elevates our cryptographic assertions from declarative claims into executable mathematical proofs. We have closed the final open soft spot in our cryptography suite: unskipping and proving our pure-TypeScript WebCrypto fallback engine against official published standards vectors (FIPS 180-4 SHA-256, RFC 2104 HMAC-SHA256, RFC 5869 HKDF-SHA256, and NIST SP 800-38D AES-256-GCM), achieving byte-identical parity with Node.js native cryptographic primitives. Furthermore, we have mechanized constant-time comparisons across all sensitive key comparison sites, introduced an automated Docs-as-Code claim battery into our build gates, and enriched our threat model with transparent operational boundaries.

---

💎 Key Themes & Highlights

🛡️ 1. Pure-TS WebCrypto Fallback Vector Parity (Task 47)

• Unskipped Standards Verification (tests/unit/webCryptoFallback.test.ts): The pure-TS WebCrypto fallback test suite (skipped since v0.0.1.2) is now fully unskipped, green, and executed on every CI run.
• Published Vector Compliance:
  • SHA-256: Verified against official FIPS 180-4 published test vectors ("", "abc", 1M 'a' stress vectors).
  • HMAC-SHA256: Verified against RFC 2104 / RFC 4231 standard test vectors.
  • HKDF-SHA256: Verified against RFC 5869 test vectors (extract-and-expand with PRK, salt, and info bindings).
  • AES-256-GCM: Verified against NIST SP 800-38D standard vectors (256-bit zero key, 96-bit IV, 128-bit plaintext, tag verification).
• Byte-Identical Native Parity: Proved that pure-TS fallback output matches native Node.js crypto output byte-for-byte across every supported cipher and hash.

⏱️ 2. Mechanized Constant-Time Comparison Sweep (Task 47)

• Universal Constant-Time Utility (src/server/utils/crypto.ts): Implemented constantTimeCompare(a, b) using Node's crypto.timingSafeEqual with dummy comparison buffering on length mismatch, eliminating timing side-channel leaks.
• Key-Path Refactoring: Refactored src/server/routes/auth.ts, src/server/routes/admin.ts, and src/server/middleware/auth.ts to route all secret comparisons (passwords, tokens, human keys, agent keys) through constantTimeCompare.
• Automated AST/Regex Build Gate (tests/build-gates.test.ts): Wired an automated sweep asserting zero raw === or !== comparisons on secret tokens or key material across server routes and middleware.

🧪 3. The Auditor's Claim Battery (Task 48)

• Docs-as-Code Invariant: Codified an automated claim battery in tests/build-gates.test.ts to ensure documentation strictly bows to code reality:
  • L1 (Rate Limiters): Asserts documented rate limits match src/server/middleware/rateLimiter.ts.
  • L3 (Key Prefixes): Asserts documented key prefix strings (hu-, lb-) match src/server/utils/crypto.ts and src/lib/crypto.ts.
  • L4 (Permission Masks): Asserts documented permission masks match Zod schemas in src/server/validation/schemas.ts.
  • L5 (AAD Namespaces): Asserts documented AAD namespace templates match cryptographic test fixtures.
• Falsifiable Mutation Verification: Tested to ensure any planted documentation lie immediately and loudly breaks the CI test oracle.

📖 4. Threat Model Addendum & Honest Security Boundaries (Task 48)

• Transparent Operational Realities (SECURITY.md & docs/architecture/threat-model.md):
  • In-Process Rate Limiting: Explicitly documented that in-memory rate limiting resets upon container restart and multi-instance clusters share no state (under YAGNI, no Redis requirement).
  • LRU Eviction: Documented per-key LRU cache eviction semantics with safe fallback to SQLite database lookups.
  • Redaction Coverage: Enumerated credential masking and redaction regexes used throughout logging and error pipelines.
  • Side-Channel Boundary: Documented in project/encryption-layers-spec.md §5 that pure-TS AES-GCM provides functional LAN availability on plain HTTP origins, not hardware-level side-channel immunity.

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────┐
│                 🌐 Client Layer (React 19 + Vite 6)                     │
│  ┌─────────────────────────┐  ┌──────────────────────────────────────┐  │
│  │   WebCrypto Subtle API  │  │   Pure-TS WebCrypto Fallback Engine  │  │
│  │ (HTTPS / Secure Origin) │  │  (FIPS 180-4, RFC 2104, RFC 5869,    │  │
│  │                         │  │   NIST SP 800-38D Vector Parity)     │  │
│  └───────────┬─────────────┘  └──────────────────┬───────────────────┘  │
│              │                                   │                      │
│              ▼                                   ▼                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │        Zero-Knowledge Cryptographic Layer (ShellCryption)         │  │
│  │   (Client-side AES-256-GCM + PBKDF2 600k / HKDF Key Derivation)   │  │
│  └───────────────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────────────┼──────────────────────────────────┘
                                       │ (Opaque Ciphertext + constantTime Auth)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              🔌 Server & API Layer (Express 5 Security Kernel)          │
│  ┌───────────────────────────────────┬───────────────────────────────┐  │
│  │ constantTimeCompare() Guards      │ In-Process Rate Limiter       │  │
│  │ (Zero === comparisons on secrets) │ (Documented container memory) │  │
│  ├───────────────────────────────────┼───────────────────────────────┤  │
│  │ Auditor's Battery Build Gate      │ requirePermission() Claws     │  │
│  │ (L1-L5 docs-bow-to-code checks)   │ (Strict Zod schema masks)     │  │
│  └───────────────────────────────────┴───────────────────────────────┘  │
└──────────────────────────────────────┬──────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                 🗄️ Bedrock Storage (SQLite + SQLCipher)                 │
│  ┌───────────────────────────┐       ┌───────────────────────────────┐  │
│  │ vault_pearls / notes / keys│ <───> │ segregated audit.sqlite       │  │
│  │ (Layer 2 metadata encrypted│       │ (Tamper-evident audit trails  │  │
│  │  + Layer 1 ShellCryption)  │       │  never joined with vault DB)  │  │
│  └───────────────────────────┘       └───────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Changes by Layer

Component	Files	Description
Cryptographic Primitives	src/server/utils/crypto.ts, src/lib/webCryptoFallback.ts	Added constantTimeCompare() with dummy length buffering; verified pure-TS standards vector parity.
Authentication & Middleware	src/server/routes/auth.ts, src/server/routes/admin.ts, src/server/middleware/auth.ts	Refactored all token/password equality checks to consume constantTimeCompare().
Verification & Build Gates	tests/unit/webCryptoFallback.test.ts, tests/build-gates.test.ts	Unskipped fallback test suite with NIST/RFC vectors; added Auditor's Battery and mechanized constant-time comparison CI sweep.
Threat Model & Security Policy	SECURITY.md, docs/architecture/threat-model.md, project/encryption-layers-spec.md	Formalized auditor's addendum (rate limiter resets, LRU eviction, redaction regexes, LAN side-channel boundary).

---

📋 Commit Ledger (Since v0.0.2.5)

• 31d28c1 — feat(crypto): merge Phase 24 crypto hardening & auditor battery (PR #6)
• 4ef6e07 — docs(agents): ratify post-review verification & adjacency sweep protocol
• aa59622 — feat(crypto): Phase 24 crypto hardening and auditor battery
• 7051310 — chore(jules): pre-heat Phase 24 tasks, targeted knowledge, and epistemic escape hatch
• f7f4684 — feat(agents): codify prep-jules-work skill and epistemic escape hatch

---

🚀 Upgrade & Verification Instructions

Upgrading via Docker / Unraid

docker pull ghcr.io/clawstackstudios/shellguard:latest
docker restart shellguard

Upgrading from Source

git fetch --tags
git checkout v0.0.2.6
npm install
npm run build
npm r...

ShellGuard v0.0.2.5

🦞 ShellGuard — Release v0.0.2.5

"The Bitwarden Item Integrity & Relational Molt" — Phase 23: Bitwarden-Model Item Integrity, Attachment Parent Enforcement & Dashboard Type Truth
ClawStack Studios ©™ · 2026-10-17 · AGPL-3.0

The reef ascends to total relational integrity. ShellGuard v0.0.2.5 (Build 27) aligns the vault data model strictly with the Bitwarden Item Integrity Model — enforcing that binary attachments are strictly child components of parent vault items, quarantining orphaned attachments non-destructively, validating note credential rejection, ensuring transactional relational cascades, exposing pre-flight storage quota capacity, and polishing the Vault Dashboard for pure type-truthfulness.

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ╚════██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗     █████╔╝
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║    ██╔═══╝ 
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝    ███████╗
                                              ~ **ClawStack Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.5 (Build 27) of ShellGuard! This release establishes end-to-end structural fidelity between the frontend interface and the Bedrock database schema. In adherence to the Bitwarden Item Integrity Model, binary attachments can never be created as standalone vault records—they exist solely as encrypted child components bound to a parent item (Passwords, Credit Cards, Identities, Secure Notes, and SSH Keys). Orphaned or unparented attachments are swept into a safe, non-destructive quarantine ledger with forensic audit logging, while deleted attachments cleanly cascade out of parent reference arrays.

---

💎 Key Themes & Highlights

🛡️ 1. Bitwarden-Model Item Integrity & Parent Enforcement (Task 45)

• Mandatory Parent Linkage (src/server/routes/attachments.ts): The POST /api/attachments endpoint now strictly requires valid parent_id and parent_type fields (pearl, note, key). Standalone attachment creation is structurally forbidden and returns 400 Bad Request.
• Atomic Transaction Linkage: When an attachment is uploaded, the parent item's attachments JSON ID array is updated within the exact same database transaction, eliminating partial creation states.
• Migration 0009 (0009_attachment_integrity.up.sql): Applied schema upgrades to vault_secure_attachments enforcing parent association columns and indices.
• Zero-Knowledge Invariant Preserved: Attachment payloads (file_data) remain opaque AES-256-GCM ShellCryption BLOBs. The server enforces relationship integrity without ever inspecting decrypted file bytes.

🧹 2. Non-Destructive Orphan Attachment Quarantine & Audit Logging

• Boot & Runtime Sweeper (src/server/utils/attachmentIntegrity.ts): Built quarantineOrphanAttachments() which scans for unparented or dangling attachment records and flags them is_quarantined = 1.
• Sacred Data Protection: Quarantined attachments are hidden from standard vault lists and download routes, but are never silently deleted. User data remains preserved on disk.
• Forensic Audit Redaction: Every quarantine action records an ATTACHMENT_QUARANTINED event in the segregated audit.sqlite database.

⚡ 3. Relational Cascading, Sweeper & Pre-Flight Quota (Sub-Stage 25.1)

• Relational Cascade on Delete: Calling DELETE /api/attachments/:id atomically removes the deleted attachment's ID from its parent item's attachments JSON array across vault_pearls, vault_secure_notes, and vault_ssh_keys, preventing dangling ghost IDs.
• On-Demand Runtime Sweeper Endpoint: Exposed POST /api/attachments/quarantine/sweep for administrators and maintenance workflows to sweep and isolate orphaned attachments on demand without rebooting the server.
• Pre-Flight Quota Inspection: Exposed GET /api/attachments/quota returning { used_bytes, quota_bytes, remaining_bytes } based on GROTTO_QUOTA_MB, enabling client dropzones to pre-validate available space before initiating uploads.

🔒 4. Note Credential Rejection Invariant

• Form-Contract Guard (src/server/validation/schemas.ts): Secure Notes strictly reject payloads containing credential fields such as secret. Secure Notes remain purely document and markdown ledgers, preventing improper credential leakage.

🎨 5. Dashboard Type Truth & Add-Menu Correction (Task 46)

• Add-Menu Simplification (Header.tsx): Removed the '📎 Attachment' entry from the + Add Item dropdown menu. Attachments are created and managed exclusively within their parent item's modal.
• Item List Type Truth (ItemListPane.tsx, VaultShell.tsx): Master item lists strictly present primary vault items (Passwords, Secure Notes, SSH Keys, Cards, Identities). Attachments render solely within their parent's detail pane.
• Deterministic Type Ordering: Items sort predictably by type: Passwords → Cards → Identities → Secure Notes → SSH Keys, with recency sorting within each group.

📜 6. Canonical Root AGENTS.md Governance Contract

• High-Agency Skill-Seed: Established repository root AGENTS.md articulating project philosophy, core invariables, immutable rules, architecture mapping seams, and tool bindings.

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────┐
│                 🌐 Client Layer (React 19 + Vite 6)                     │
│  ┌─────────────────────────┐  ┌──────────────────────────────────────┐  │
│  │    Header Add-Item +    │  │          ItemListPane                │  │
│  │ (Passwords, Cards,      │  │ (Deterministic Type Sort Order:      │  │
│  │  Identities, Notes,     │  │  Passwords → Cards → Identities →    │  │
│  │  SSH Keys — No Atts)    │  │  Notes → SSH Keys)                   │  │
│  └───────────┬─────────────┘  └──────────────────┬───────────────────┘  │
│              │                                   │                      │
│              ▼                                   ▼                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    ItemDetailPane / ItemFormModal                 │  │
│  │ (Attachments bound strictly as children to parent item's JSON ID) │  │
│  └───────────────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────────────┼──────────────────────────────────┘
                                       │ (REST with Parent Linkage)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              🔌 Server & API Layer (Express 5 Security Kernel)          │
│  ┌───────────────────────────────────┬───────────────────────────────┐  │
│  │ POST /api/attachments             │ DELETE /api/attachments/:id   │  │
│  │ (Requires parent_id + parent_type)│ (Cascades parent JSON IDs)    │  │
│  ├───────────────────────────────────┼───────────────────────────────┤  │
│  │ POST /api/attachments/quarantine  │ GET /api/attachments/quota    │  │
│  │ (Runtime sweep orphaned records)  │ (Returns quota capacity stats)│  │
│  └───────────────────────────────────┴───────────────────────────────┘  │
└──────────────────────────────────────┬──────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                 🗄️ Bedrock Storage (SQLite + SQLCipher)                 │
│  ┌───────────────────────────┐       ┌───────────────────────────────┐  │
│  │ vault_secure_attachments  │ <───> │ vault_pearls / notes / keys   │  │
│  │ (parent_id, parent_type,  │       │ (attachments JSON ID array    │  │
│  │  is_quarantined)          │       │  updated in transaction)      │  │
│  └───────────────────────────┘       └───────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Verification Receipts

• Unit & Integration Test Oracle: 29 test suites, 341 tests passing 100% green (1 skipped).
• TypeScript Strict Check: tsc --noEmit passed with 0 errors.
• Production Vite Build: Compiled cleanly without warnings or errors.
• VitePress Documentation Portal: Built cleanly in 100% compliance with Docs-as-Code.
• Cloud CI Pipeline: GitHub Actions Run #39023257850 passed 100% green across all verification matrices in 1m 32s.

ShellGuard v0.0.2.4

🦞 ShellGuard — Release v0.0.2.4

"The Reef Polish & Unified Ergonomics Molt" — Phase 22: Unified Zero-Knowledge Search Engine, Control Surface Consolidation & Ergonomics Verification
ClawStack Studios ©™ · 2026-09-23 · AGPL-3.0

The reef achieves unprecedented clarity and navigational velocity. ShellGuard v0.0.2.4 (Build 26) delivers a Robust Unified Client-Side Search Engine, prunes redundant global search bars across the header and sidebar, preserves high-speed local pod tree filtering, and re-verifies Eye-beside-Copy unmasking ergonomics across every secret field.

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██╗  ██╗
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██║  ██║
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ███████║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ╚════██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║         ██║
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝         ╚═╝
                                              ~ **ClawStack Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.4 (Build 26) of ShellGuard! This release delivers a streamlined, ergonomic control experience by eliminating UI clutter and powering the vault with a pure zero-knowledge search engine. Vault items are matched instantly in client memory across titles, usernames, primary and secondary URLs, decrypted note contents, custom field names and values, attachment filenames, and tags—with zero network leakage and automatic memory purge on lock.

---

💎 Key Themes & Highlights

🔍 1. Robust Unified Client-Side Search Engine (src/lib/vaultSearch.ts, Task 43)

• Deep In-Memory Search Corpus: Queries across the pre-decrypted in-memory corpus (vaultItems) without triggering redundant decryption cycles or disk reads.
• Multi-Field Matching:
  • Item title (e.g., website, service, or server name)
  • Username or identity handle
  • Primary URL and secondary login URIs
  • Pearl notes text
  • Decrypted Secure Note markdown content (secret)
  • Custom Fields: Matches both field names and field values across text, hidden, checkbox, and linked types
  • Binary attachment filenames (file_name)
  • Assigned bioluminescent tags
• Zero-Knowledge Invariant: Zero network requests. The search query never touches the wire, query parameters (?q=), or server logs. The server cannot search what it cannot decrypt.
• Lock Purge: When isLocked flips to true or upon logout, the active searchQuery state and in-memory filtered corpus are purged immediately.

🧹 2. Search Surface Consolidation & Clutter Elimination (Task 44)

• Header Simplification: Removed the top-right search input, search icon, and floating search dropdown from Header.tsx (-64 lines). The header is restored to a clean utility cluster containing only the + Add Menu, Account Switcher, and Theme Toggle.
• Sidebar Streamlining: Removed the redundant top search bar and duplicate dropdown under "Dashboard" in Sidebar.tsx (-214 lines).
• Pruned Dead Plumbing: Cleaned up 71 lines of orphaned search state, refs, keyboard shortcuts (/ and ⌘K), and click-outside listeners in src/App.tsx.

🌲 3. Ergonomic Pod-Scoped Search Preserved

• Dedicated Pod Tree Filtering (SidebarFolderTree.tsx): In accordance with ergonomic feedback, the dedicated "Search Pods..." input above the folder hierarchy was intentionally preserved. Users with extensive multi-tier pod structures can rapidly filter their folder tree without cluttering the global item feed.

👁️ 4. Eye-beside-Copy Ergonomics Re-Verified

• Masked Field Consistency: Re-verified across all masked rows (passwords, SSH private keys, and hidden custom fields) that the Eye/EyeOff unmask toggle sits strictly immediately to the left of the Copy button in the action cluster.
• Mask Invariant: Masked fields maintain full •••••••••••••••• masking without leaking character counts or exposing sensitive text on row hover.

🧪 5. Comprehensive Unit Testing

• 10 Dedicated Test Cases (tests/unit/vaultSearch.test.ts): Covers empty/whitespace queries, title matches, username matches, multi-URI array parsing, decrypted note content, custom fields, attachment filenames, tags (JSON array and comma-separated), and resilient malformed JSON handling.

📚 6. Dedicated VitePress Search Documentation Portal

• Unified Vault & Pod Search Guide (docs/vault-features/search.md): Comprehensive documentation detailing client-side zero-knowledge search mechanics (vaultSearch.ts), deep multi-field matching, in-memory lifecycle with lock purge, and the separation of concerns between Item List Pane search and Scoped Pod Tree filtering (SidebarFolderTree.tsx).
• Portal Integration: Fully integrated into docs/.vitepress/config.ts, docs/vault-features/index.md, docs/vault-features/the-grotto.md, and docs/reference/design-system.md.

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────┐
│                 🌐 Client Layer (React 19 + Vite 6)                     │
│  ┌─────────────────────────┐  ┌──────────────────────────────────────┐  │
│  │   SidebarFolderTree     │  │          ItemListPane                │  │
│  │ (Pods, Tags, Pod Search)│  │    (Unified Master Search Bar)       │  │
│  └───────────┬─────────────┘  └──────────────────┬───────────────────┘  │
│              │                                   │                      │
│              ▼                                   ▼                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                     vaultSearch Engine (RAM)                      │  │
│  │    (Title, User, URIs, Decrypted Notes, Custom Fields, Tags)       │  │
│  │              Zero-Knowledge • Purged on Lock                      │  │
│  └───────────────────────────────────┬───────────────────────────────┘  │
│                                      │                                  │
│  ┌───────────────────────────────────┴───────────────────────────────┐  │
│  │                      ItemDetailPane                               │  │
│  │     (Eye-beside-Copy Unmask Cluster, Decrypted Inline Content)    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Verification Receipts

• Unit Test Oracle: 27 test suites, 323 passing tests (1 skipped).
• TypeScript Strict Check: tsc --noEmit passed with 0 errors.
• Production Build: Built cleanly via Vite in 54.75s.
• Documentation Portal: Built cleanly via VitePress in 94.89s.
• Live Server Handshake: Ports :6464 (Web Shell) and :6565 (API Server) verified live and operational.

ShellGuard v0.0.2.3

🦞 ShellGuard — Release v0.0.2.3

"The Deep Ingestion & Vault Parity Molt" — Phase 21: Bulk Operations, Universal Bitwarden Ingestion, RFC 6238 TOTP, Dual Export Suite & Migration 0008 Note Attachments Parity
ClawStack Studios ©™ · 2026-09-22 · AGPL-3.0

The reef expands its reach into deeper currents. ShellGuard v0.0.2.3 (Build 25) delivers a battle-tested Multi-Select Batch Operations Suite, a Universal Bitwarden Ingestion Engine with interactive dry-run previews, client-side RFC 6238 TOTP generation, Password History auditing, Dual Export sovereignty (Encrypted JSON + Plaintext CSV/JSON), and Migration 0008 Note Attachments Parity unlocking 500MB encrypted attachments for Secure Notes alongside Pearls.

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝
                                              ~ **ClawStack Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.3 (Build 25) of ShellGuard! This release marks a pivotal evolution in vault ergonomics and data sovereignty. Users can now migrate entire vaults from Bitwarden or legacy CSV/JSON files with full folder-to-Pod mapping, preview import differences before committing, manage hundreds of vault items at once with sticky batch operations (moving pods, tagging, and bulk trash/deletion), track password change histories, generate two-factor authenticator codes directly inside the vault with live countdown rings, export encrypted or plaintext backups, and attach up to 500MB encrypted files to Secure Notes with complete cascade deletion guarantees.

---

💎 Key Themes & Highlights

⚡ 1. Multi-Select Batch Operations Suite (Phase 21, Task 42)

• Sticky Multi-Selection Engine (ItemListPane.tsx): Checkbox selection mode maintains selected item states across sorting, filtering, and tag switching without accidental state loss.
• Batch Pod Relocation (POST /api/vault/bulk-pod): Move multiple pearls, secure notes, and SSH keys to any destination Pod in a single atomic transaction.
• Batch Tagging (POST /api/vault/bulk-tags): Compound or strip bioluminescent tags across dozens of items simultaneously, preserving existing metadata.
• Batch Deletion (POST /api/vault/bulk-delete): Safely soft-delete or permanently purge batches of vault records with confirmation modals and automated selection cleanup.
• Floating Action Bar: Renders dynamically above the item feed when selections are active, offering one-click Pod, Tag, and Trash actions styled with Reef Modernist accents.

📥 2. Universal Bitwarden Ingestion & Multi-Format Importer (Phase 21, Task 41)

• Universal Bitwarden JSON Ingestion (src/lib/importers/bitwarden.ts): Ingests Logins (Pearls), Secure Notes, Credit Cards, and SSH keys/Identities with folder structures mapped automatically to sovereign Pods.
• ShellGuard Native JSON & CSV Formats: Standardized parsers for importing and exporting complete encrypted or decrypted vault datasets.
• Pre-Flight Dry-Run Diff Engine (POST /api/vault/bulk-import?dry_run=true): Provides an interactive preview before committing changes—displaying total items detected, valid items, duplicate collisions, and destination Pod breakdowns.
• Client-Side Bulk Encryption: All imported items are encrypted in the browser using AES-256-GCM Layer 1 ShellCryption before transit, ensuring zero-knowledge privacy across large payloads.

⏱️ 3. RFC 6238 Standardized TOTP Engine & Password History

• Client-Side TOTP Generation (src/lib/totpEngine.ts): Built-in 2FA authenticator engine supporting RFC 6238 standards (SHA-1, SHA-256, SHA-512, 6 or 8 digits, 30s or 60s periods).
• Live Countdown Ring & One-Click Copy: Visual circular timer indicator in ItemDetailPane.tsx with one-click clipboard copy for seamless login workflows.
• otpauth:// URI Parsing: Automatically parses secret keys, algorithms, digits, and periods from standard authenticator URIs during import or manual configuration.
• Item Password Generation History: Tracks up to 10 past password iterations per credential with timestamps sealed inside the encrypted payload, preventing lockouts during password rotation.

💾 4. Dual Export Suite (Encrypted & Plaintext)

• Encrypted JSON Export: Seals all vault credentials, notes, SSH keys, tags, and pod structures into an AES-256-GCM encrypted envelope keyed by the user's master password or a custom backup passphrase.
• Decrypted Plaintext CSV/JSON Export: High-friction confirmation modal with deliberate warning prompts allows exporting plaintext credentials for external migrations and physical cold storage.
• Zero-Persistence Export Streams: Data is processed purely in client-side memory using browser Blobs, preventing sensitive plaintext exposure on disk or server logs.

🗄️ 5. Migration 0008 Note Attachments Parity & Cascade Deletion

• Database Migration 0008_note_attachments_parity.sql: Introduces parent_note_id to vault_attachments with foreign key constraints, giving Secure Notes full parity with Pearls.
• 500MB Encrypted Attachments for Notes: Secure Notes now support full multipart streaming file uploads up to 500MB per file within the 1000MB owner quota.
• Hardened Cascade Deletion: Deleting a Pearl or Note automatically cascades to purge all associated encrypted disk chunks and database records.
• Ghost Pod Cleanup: Purging or relocating items automatically prunes unreferenced empty pods, preventing UI clutter.
• UI Clarification: Updated file size indicators to explicitly state Attachments (max 500MB per attachment).

🛡️ 6. Native WebCrypto Acceleration & Seam Hardening

• 600,000 PBKDF2-SHA256 Iterations: Hardware-accelerated key derivation via browser-native crypto.subtle, verified against RFC 6070 known-answer test vectors.
• Interaction Seam Hardening: Resolved modal dismissal leaks, deletion routing synchronization, and selection clearing across rapid UI operations.
• Deterministic Documentation Walk (walk-the-docs.md): Established an automated workflow ensuring all root and portal documentation strictly adheres to codebase reality.

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────┐
│                 🌐 Client Layer (React 19 + Vite 6)                     │
│  ┌─────────────────────────┐  ┌──────────────────────────────────────┐  │
│  │   SidebarFolderTree     │  │          ItemListPane                │  │
│  │ (Pods, Tags, Bulk Mode) │  │ (Sticky Multi-Select & Action Bar)   │  │
│  └───────────┬─────────────┘  └──────────────────┬───────────────────┘  │
│              │                                   │                      │
│              ▼                                   ▼                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                       ItemDetailPane                              │  │
│  │ (RFC 6238 TOTP Countdown, Password History, 500MB Note Attachments)│  │
│  └───────────────────────────────────┬───────────────────────────────┘  │
│                                      │                                  │
│  ┌───────────────────────────────────┴───────────────────────────────┐  │
│  │      Client-Side Ingestion & Export Suite (WebCrypto PBKDF2)      │  │
│  │   (Universal Bitwarden JSON, Native CSV/JSON, Encrypted Exports)  │  │
│  └───────────────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────────────┼──────────────────────────────────┘
                                       │ (Opaque Ciphertext REST API)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                 🔌 Server Layer (Express 5 + Helmet)                    │
│  ┌────────────────────────┐  ┌───────────────────────────────────────┐  │
│  │  requireAuth() Guard   │──│   Bulk Transactional Handlers         │  │
│  │  (Tenant Scope / Owner)│  │ (/bulk-import, /bulk-pod, /bulk-tags) │  │
│  └────────────────────────┘  └───────────────────┬───────────────────┘  │
│                                                  │                      │
│                                                  ▼                      │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │  Streaming Busboy Pipeline (500MB Limit / 1000MB Quota)           │  │
│  │  Cascade Deletion Coordinator (Disk Artifacts + Ghost Pod Purge)  │  │
│  └───────────────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────────────┼──────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              🖥️ Bedrock Storage (SQLite + Migration 0008)               │
│      (vault_pearls, vault_secure_notes, vault_ssh_keys, attachments)    │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Changes by Layer

Component	Files	Description
Database Migrations	migrations/0008_note_attachments_parity.{up,down}.sql	Adds parent_note_id column to vault_attachments with foreign key and cascade deletion
Server / API	src/server/routes/{vault,notes,attachments}.ts	Bulk import/pod/tags/...

ShellGuard v0.0.2.2

🦞 ShellGuard — Release v0.0.2.2

"The Bioluminescent Reef" — Phase 20: Vault Tagging System & Granular Filter Bar + 500MB Storage Ceiling + SSH Key Dual-Key Ergonomics
ClawStack Studios ©™ · 2026-09-19 · AGPL-3.0

The reef glows brighter and grows wider. ShellGuard v0.0.2.2 (Build 24) delivers a flexible, multi-dimensional Vault Tagging System that works seamlessly alongside hierarchical Pods, unlocks a 500MB per-file attachment ceiling (with 1000MB grotto quota), and introduces a purpose-built SSH Key Dual-Key Architecture engineered for terminal ergonomics and OpenSSH compliance.

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝
                                              ~ **ClawStack Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.2 (Build 24) of ShellGuard! This milestone empowers users to organize pearls, secure notes, and SSH keys across multiple categories using keyboard-friendly bioluminescent tags, run instant multi-tag intersection queries (AND / OR), upload large encrypted assets up to 500MB per file, and deploy generated SSH keys directly to remote servers with one-click terminal commands.

---

💎 Key Themes & Highlights

🏷️ 1. Vault Tagging System & Granular Filter Bar (Phase 20, Tasks 39/40)

• Database Migration 0006_vault_tags: Adds tags TEXT DEFAULT '[]' column and owner indices across vault_pearls, vault_secure_notes, and vault_ssh_keys.
• Layer 2 MetadataGuard Encryption: Tags are registered in metadataGuard.ts for per-row AES-256-GCM encryption on disk, preventing plaintext tag exposure in database backups while allowing authenticated server-side tag queries.
• Intersection Querying & Scoped Search: List routes (GET /api/vault, GET /api/notes, GET /api/ssh-keys) support ?tags=a,b query parameter with ownership scoping and forensic audit logging (audit_logs).
• TagSelectorInput Chips: Autocomplete suggestions, keyboard navigation (Enter/Comma), and inline color palette selection matching the Reef Modernist design tokens.
• Unified Bioluminescent Color Engine (podUtils.ts): Pods and tags share a deterministic color hashing algorithm (hashStringToColor) with user-specified overrides and headless test-environment safety.
• Collapsible Sidebar Tag Cloud & Multi-Filter Bar: Active tags render with item counts in SidebarFolderTree.tsx. The vault filter bar in ItemListPane.tsx allows compounding multiple tag filters with an interactive AND / OR toggle.

📎 2. 500MB Attachment Storage Ceiling (Phase 20 Sub-task)

• 10x File Size Expansion: Elevated the per-file attachment upload ceiling from 50MB to 500MB (ATTACHMENT_MAX_MB).
• Grotto Storage Quota Doubled: Owner storage quota increased from 500MB to 1000MB (1GB) (GROTTO_QUOTA_MB).
• Streaming Pipeline Validation: Busboy multipart streaming handles 500MB payloads with mid-stream 413 abort on quota breach. Nginx reverse-proxy configuration guidance elevated to 550M client body size.

🗝️ 3. SSH Key Dual-Key Architecture & Terminal Ergonomics (Phase 20 Sub-task)

• Dual-Key Storage Envelope: Generated keypairs serialize as { publicKey, privateKey } JSON sealed client-side inside key_value under Layer 1 ShellCryption.
• Zero-Migration Backward Compatibility: parseSshKeySecret() automatically detects dual-key envelopes or legacy raw PEM keys, preserving existing vault credentials without database changes.
• Strict RFC 7468 PEM Framing: Private keys strictly preserve -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- delimiters in monospace <pre> blocks, eliminating formatting errors in OpenSSH (ssh -i) and Git.
• High-Velocity Deployment Actions:
  • Copy Public Key: One-click extraction of the OpenSSH public string (ssh-ed25519 AAAAC3...).
  • Copy authorized_keys Command: Instant copy of echo "<pub>" >> ~/.ssh/authorized_keys ready to paste directly into server shells.
  • Download .pem: Direct in-browser download of <title>.pem for command-line use.
• Decoupled Form Inputs: The item editor separates Private Key PEM and Public Key inputs, preventing JSON serialization leaks during edits.

📐 4. Master-Detail Header Flush & Dynamic Version Resolver Integrity

• Flush Dashboard Headers: Fixed 5px height discrepancy between search bar header and detail pane header, locking both to a shared 64px (h-16) height for a seamless continuous border.
• Dynamic Version Resolver: Server dynamic version resolver (getAppVersion()) ensures complete ground-truth alignment with package.json.

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────┐
│             🌐 Client Layer (React 19 + Vite 6)              │
│  ┌────────────────────────┐     ┌────────────────────────┐  │
│  │   SidebarFolderTree    │     │      ItemListPane      │  │
│  │ (Pods + Tag Cloud)     │     │ (AND/OR Tag Filter Bar)│  │
│  └───────────┬────────────┘     └───────────┬────────────┘  │
│              │                              │               │
│              ▼                              ▼               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   ItemDetailPane                      │  │
│  │ (Layer 1 ShellCryption, SSH Dual-Key & PEM Download)  │  │
│  └───────────────────────────┬───────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────┘
                               │ (Opaque Ciphertext REST API)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│             🔌 Server Layer (Express 5 + Helmet)            │
│  ┌───────────────────────┐     ┌─────────────────────────┐  │
│  │  requireAuth() Guard  │ ──> │   MetadataGuard (AES)   │  │
│  │  (?tags=a,b Filtering)│     │  (Layer 2 Tag Storage)  │  │
│  └───────────────────────┘     └────────────┬────────────┘  │
│                                             │               │
│                                             ▼               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Tenant Isolation Filter (WHERE owner_uuid = ?)       │  │
│  │  Attachment Streaming (500MB Limit / 1000MB Quota)    │  │
│  └───────────────────────────┬───────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│          🖥️ Bedrock Storage (SQLite + Migration 0006)       │
│    (vault_pearls, vault_secure_notes, vault_ssh_keys tags)  │
└─────────────────────────────────────────────────────────────┘

---

📦 Changes by Layer

Component	Files	Description
Database Migrations	migrations/0006_vault_tags.{up,down}.sql	Adds tags TEXT DEFAULT '[]' column and owner indices across pearls, notes, and SSH keys
Server / API	src/server/routes/{vault,notes,sshKeys,attachments}.ts, src/server/utils/metadataGuard.ts	Tag filtering (?tags=a,b), Layer 2 metadata encryption, 500MB attachment limits, audit logging
Frontend / UI	src/components/Vault/{TagSelectorInput,SidebarFolderTree,ItemListPane,ItemDetailPane,ItemFormModal}.tsx	Autocomplete chips, tag cloud, AND/OR filter bar, dual-key SSH UI, and PEM actions
Shared Libraries	src/lib/{podUtils,keyGen,attachmentUtils,tagUtils}.ts	Unified color engine, SSH dual-key serialization/parsing, terminal command formatters
Documentation Portal	docs/vault-features/{the-grotto,attachments,index}.md, docs/reference/blueprint-schema.md	Comprehensive user and architectural documentation for tags, attachments, and SSH dual-key management
Test Oracle	tests/vault-tags.test.ts, tests/unit/keyGen.test.ts, all 20 test files	100% green test coverage (248 passed, 1 skipped)

---

🧪 Verification & Build Gates

• Test Oracle: 20/20 test suites passing (248 passed, 1 skipped, 0 failures).
• Typecheck & Linter: tsc --noEmit clean with zero errors.
• Production Build: vite build compiled cleanly.
• Documentation Portal: vitepress build docs compiled cleanly in 106s with zero broken links.
• Link & Diagram Integrity: docsLinks.test.ts (5/5) and mermaidDiagrams.test.ts (5/5) passing.

---

🚀 Upgrade & Verification Instructions

Upgrading via Docker / Unraid

docker pull ghcr.io/clawstackstudios/shellguard:latest
docker restart shellguard

Upgrading from Source

git fetch --tags
git checkout v0.0.2.2
npm install
npm run build
npm run scuttle:prod

---

Your reef. Your keys. Your secrets. — Trust the Shell. 🦞

ShellGuard v0.0.2.1

🦞 ShellGuard — Release v0.0.2.1

"The Deep Storage Molt" — Phase 19: Attachment SQLite BLOB Migration & Streaming Architecture
ClawStack Studios ©™ · 2026-09-18 · AGPL-3.0

The attachment grotto goes native. Encrypted file payloads move from base64
TEXT strings into native SQLite BLOB storage, uploads and downloads become
streamed wire contracts (Busboy multipart in, chunked substr reads out),
and the grotto gains real limits: a 50MB per-file ceiling and a 500MB
per-owner quota, both failing closed with 413. The vault UI gains live
upload progress with cancel, on-demand streamed decryption, encrypted inline
previews for images and PDFs — and the Eye-beside-Copy control ergonomics
pulled forward from Phase 22.

---

Key Themes

1. Native BLOB Storage — migration 0005 rebuilds vault_secure_attachments
   with file_data BLOB + size_bytes INTEGER; legacy TEXT rows are
   re-encoded in code (idempotent, transactional, VACUUM'd — no byte-level
   ghosts). Base64's 33% storage inflation is gone.
2. The Streaming Wire Contract — uploads are multipart: the ShellCryption
   envelope streams as already-encrypted bytes (zero-knowledge untouched, no
   base64 inflation); the list endpoint is metadata-only — payload BLOBs
   leave exclusively via GET /api/attachments/:id/file in 1MB chunks, so a
   vault listing never carries bulk ciphertext and downloads never spike RSS.
3. Limits & Quotas, Fail-Closed — 50MB per-file ceiling aborts mid-stream
   (ATTACHMENT_MAX_MB); 500MB grotto quota per owner_uuid
   (GROTTO_QUOTA_MB) via an exact SUM(size_bytes) aggregate; both yield
   413 and store nothing.
4. Streaming UI — real-time upload progress with cancel (XHR
   onprogress/abort), on-demand decryption (the client decrypts with the
   shellKey; the server never sees plaintext), and encrypted inline previews:
   images render from the decrypted payload, PDFs from a Blob object URL
   (never a data: URI on insecure origins).
5. Eye-beside-Copy Ergonomics (folded forward from P22/T44) — the Unmask
   (Eye/EyeOff) toggle sits immediately LEFT of Copy in the right-hand action
   cluster on every masked field row (password, SSH private key, hidden custom
   fields); the full-value mask invariant holds (every character → •).

Verification

• Full test oracle: 19 files / 230 tests green, 1 skipped (the
  Phase-24-targeted fallback-parity test) — including the new
  tests/attachments-blob.test.ts (6 tests: migration, backfill idempotence,
  multi-chunk streaming, per-file 413, quota 413, quota release)
• tsc --noEmit, vite build, docs:build — all clean
• docsLinks + mermaidDiagrams suites — 10/10
• tsc --noEmit, vite build, VitePress build — all clean

Deployment

docker compose pull && docker compose up -d --wait
# or
docker compose up -d --build

Data lives in ./data (db.sqlite + audit.sqlite). Set DB_ENCRYPTION_KEY
(strongly recommended). See QUICKSTART.md for the first-hatch walkthrough.

Commit Ledger (v0.0.2.0 → v0.0.2.1)

dee897f docs: sync Phase 19 BLOB/quota/streaming truth across the corpus
27df54b feat: streamed progress uploads, on-demand decryption & encrypted previews + Eye-beside-Copy (Phase 19 Task 38)
f4f6073 feat: attachment BLOB storage, streaming handlers & grotto quota (Phase 19 Task 37)

---

Your reef. Your keys. Your secrets. — Trust the Shell. 🦞

ShellGuard v0.0.2.0

🦞 ShellGuard — Release v0.0.2.0

“The Composite Reef” — Phase 18: Unified Bitwarden-Style Item Composition & In-Browser Keypair Generation
ClawStack Studios ©™ · 2026-09-17 · AGPL-3.0

ShellGuard's first MINOR-feature molt after the auditable corpus. The vault
becomes a composite reef: logins, notes and SSH keys carry their notes, TOTP
seeds, attachments and custom fields as one cohesive Bitwarden-style entity;
SSH keypairs are generated inside the browser (WebCrypto, Ed25519 /
RSA-4096) with output verified byte-identical to ssh-keygen; pod tallies are
proven (and locked by tests) to count primary items only. Alongside: the README
reorganized to the TOTP discipline, mermaid diagrams rendering on GitHub and
the portal, and the cryptologist's lens sealed into permanent memory.

---

Key Themes

1. In-Browser SSH Keypair Engine — WebCrypto generateKey (Ed25519 +
   RSA-4096), OpenSSH one-line + RFC-4716 public encodings, PKCS#8 private key
   sealed client-side (AAD vault_ssh_keys:{id}) — never transmitted raw.
   Secure-context feature detection with an honest plain-HTTP-LAN notice.
2. Bitwarden-Style SSH Key Section — the item form gains a full SSH
   private-key surface (paste/import or generate), public-key display with
   one-click copy in the detail pane; extra fields (notes/TOTP/attachments/
   custom fields) extended to SSH keys per the locked domain rules.
3. Pod-Tally Decoupling, Locked as Receipts — buildPodTree filters to
   primary types; tests now prove attachment rows never inflate folder badges.
4. The Composite Item Model Documented — vault_pearls as the primary
   composite entity; schema truth already carried it, the docs now say so.
5. Corpus & Portal Polish — README TOTP-style reorganization, mermaid
   rendering (portal plugin + GitHub-parseable labels), long-term memory bank
   with the sealed Auditor's Perspective, learning-proposal rules ratified.

Verification

• Full test oracle: 16 files / 221 tests green (incl. 6 new keyGen tests
  and 2 pod-decoupling receipt tests)
• ssh-keygen -y cross-verification: derived public == generated public for
  both Ed25519 and RSA-4096
• tsc --noEmit, vite build, VitePress build — all clean

Deployment

docker compose pull && docker compose up -d --wait
# or
docker compose up -d --build

Data lives in ./data (db.sqlite + audit.sqlite). Set DB_ENCRYPTION_KEY
(strongly recommended). See QUICKSTART.md for the first-hatch walkthrough.

Commit Ledger (v0.0.1.10 → v0.0.2.0)

61336a1 feat(vault): Bitwarden-style SSH key section with in-browser keypair generation (Phase 18 Task 36)
6f9b00d feat(vault): in-browser SSH keypair engine — Ed25519 + RSA-4096, ssh-keygen-verified (Phase 18 Task 35)
c6b74f1 docs(roadmap): frontmatter queue chain gains Phase 24
96e6047 docs(readme): TOTP-style reorganization — grouped features, merged encryption sections, collapsed references
ccdfd55 fix(docs): render mermaid diagrams — portal plugin + README label syntax
3d655d8 docs: adjust ShellGuard ASCII logo spacing in README
14d939a docs: adjust spacing and alignment of ShellGuard ASCII logo
ae55a5f docs: replace thumbnail PNG with favicon SVG in README
67bcf27 chore: rename auditable-corpus handoff to taskHandoff.md
df64545 feat: restore tighter original feature graphic & align README header to TOTP structure
f099808 docs(memory-bank): session handoff — the auditable corpus arc closed
bb9b95c docs(memory-bank): seal the Auditor's Perspective — long-term lens artifact
6b78c49 merge: brand assets refresh + VitePress link integrity (no release — docs deploy via main)
f3f6f68 feat: brand assets refresh + Web Design Bank + agent memory maintenance
1ba5f19 fix(docs): base-prefix Card hrefs + navigation-link integrity suite (all three link classes)
0a2c16c docs(memory-bank): initialize Long-Term Memory Bank + VitePress fix plan
cc8a872 docs: add Web Design Bank guidelines for consistent UI/UX development
2df6d63 rules: apply learning proposal — docs bow to code, ClawKey canon, env hazards, build-label sweep

---

Your reef. Your keys. Your secrets. — Trust the Shell. 🦞

ShellGuard v0.0.1.10

🦞 ShellGuard — Release v0.0.1.10

The Auditable Corpus — Chronology Restored, the ClawKey Canon, the Bidirectional Docs↔Code Audit, and Phase 24 Queued

~ ClawStack Mobile Studios©™ ~

---

🚀 The Core Summary

Welcome to v0.0.1.10 of ShellGuard — the release where the corpus itself
became the deliverable. Thirty-four commits, zero runtime-feature changes, and
the most consequential documentation release of the project: the corpus was
audited against the code that ships, proven wrong in eight places, corrected in
all of them, and permanently bound to the code by a governance law and a queued
verification phase. The application works and it is secure; this release makes
the corpus third-party auditable by construction.

---

🧭 Key Themes

1. Chronology Restored (Option C)

The roadmap's forward queue had been leapfrogged by a hands-on polish pass
(Phases 22/23 queued over 18–21), leaving the spine, the roadmap, and the memory
bank pointing at three different "next tasks." Lucas ruled the original queue
order stands. The meta-prompt spine was reorganized to the TOTP gold standard:
Stage N = Phase N−1 invariant restored across the whole file (the unphased
hotfix lives at the decimal slot Stage 18.5), four new queued stages authored
for Phases 18–21, the mermaid completed, and a dangling Phase-14 anchor plus two
partial anchors repaired — 26/26 roadmap links resolve by GitHub-faithful
slug. The ROADMAP itself was reorganized top-down chronological: YAML frontmatter
with current_position, the hotfix record moved out of the forward queue into an
inline 🕸️ Post-Hoc Interlude, Completed Releases reordered ascending
15→16→17 with truthful checkboxes, and the archive span corrected to
Phases 1–14.

2. The ClawStack Canon — ClawKey / ShellCryption / LobsterKeys

The house dictionary is now written into the architecture: ClawKey©™ (the
hu- identity JSON key — identity and ShellCryption seed in one artifact),
ShellCryption©™ (the client-side zero-knowledge engine), LobsterKeys©™
(the lb- agent keys, hash-only ledger since v0.0.1.9). ARCHITECTURE.md gained
§ The ClawKey Method — one narrative from setup to retract. The web vault's
user-facing strings now say ClawKey©™ (14 renames), matching the Android
companion — web and Android finally say the same word. Internal identifiers
(deriveShellKey, shellKey, ShellKeyFallback) are documented as
cross-project contracts, deliberately not renamed.

3. The Bidirectional Docs↔Code Audit — 8 Lies Corrected

Every documented invariant was diffed against its enforcing code. Eight docs-lies
found and corrected — the code was right in every case (docs bow to code):
rekey is PRAGMA rekey (not sqlcipher_export); authLimiter is 10
attempts/15m default (the 5/10m limiter is the admin plane's); the identity
file is shellguard_identity_<username>.json with shape {username, displayName, uuid, token, createdAt}; src/lib/customFields.ts was a phantom;
tls.ts is tlsManager.ts; the client crypto exports are the shipped names;
there are five permission masks (canMove is real — seven wizard presets);
and custom-field AAD is <table>_custom:{id}, proven by the test oracle.

The key alphabet was also corrected in the portal (base62, not hex — the
v0.0.1.9 correction finally reached the user-facing pages), the privacy policy
now names the real database files (db.sqlite + audit.sqlite), and the
portal's "Database Schema Ground Truth" page matches migration 0004 exactly.

4. Phase 24 Queued — Cryptographic Audit Hardening & Third-Party Auditability

The cryptographer's lens is formalized as Phase 24 (Tasks 47/48, provisional
v0.0.2.6 / Build 26 — Stage 25) at the queue tail: unskip the WebCrypto
fallback test against real NIST/RFC/SP vectors, mechanize the constant-time
sweep, make the claim battery an executable CI gate, and write the auditor's
threat-model addendum (in-process limiter semantics, LRU eviction, redaction
coverage). Documentation Impact blockquotes are embedded in every queued
phase (18–24) — docs-hygiene now rides in the schedule itself.

5. The Memory System Grew a Decision Log

The global decision-log rule was adopted: .clinerules/memory-bank/decision-log.md
(episodic navigation record, sliding window of 20) now lives alongside the bank,
with 14 backfilled entries from this arc. The lens entered the bank declaratively:
third-party auditable is a Core Requirement in projectBrief.md, and
systemPatterns.md carries the Auditability Invariants.

---

🔒 Security Posture (unchanged — verified)

No runtime behavior changed in this release. The security model was verified
against code: hash-only LobsterKey ledger, constant-time timingSafeEqual on
stored hashes, ownership scoping with 404 cross-owner reads, triple-layer
encryption, segregated redacted audit reef. The honest tradeoffs remain
documented (plain-HTTP LAN support, optional-at-boot DB encryption, raw
short-lived api- session tokens at rest).

---

🧪 Verification

Full pre-release loop on this exact tree: npm run lint ✓ · npm test ✓
(15 files / 210 passed / 1 skipped — the skipped webCryptoFallback vector test
is Phase 24 Task 47's first deliverable) · npm run build ✓ (59.0s) ·
VitePress docs:build ✓ (26.0s) · docs claim battery zero red · 34/34 portal
nav links · spine link audit 27/27.

---

📜 Commit Ledger (v0.0.1.9 → v0.0.1.10) — 34 commits

06ebeb7 docs(memory-bank): sync bank to the Phase 24 + lens pathway
0860c08 feat: add decision log agent rule and update learn workflow
541d851 docs(memory-bank): the cryptographer's lens enters the bank — Phase 24 receipt
533dee0 docs(genome): spine gains Stage 25 (Phase 24) + Documentation Impact lines on queued stages
06410e6 docs(roadmap): queue Phase 24 — Cryptographic Audit Hardening + Documentation Impact crawl
dd57ee5 docs(memory-bank): create Decision Log — episodic navigation record (global rule adopted)
6f16ac2 docs(memory-bank): sync bank to the bidirectional-audit pathway
164f14d docs(memory-bank): bidirectional audit receipts — 8 lies corrected, docs bow to code
a1afcdc docs(portal): bidirectional audit fixes — identity shape + limiter truth (L2,L3)
744a43c docs(security): bidirectional audit fixes — rekey, limiter counts, identity shape (L1-L3,L8)
e4c336b docs(architecture): bidirectional audit fixes — code is truth (L1,L3-L7)
021272c docs(memory-bank): restore reflection-log history (truncate-before-read self-inflicted)
e5361e2 docs(memory-bank): docs/ portal truth-sync receipts
08e02a6 docs(portal): truth-sync + ClawKey canon — privacy file names, base62 alphabet, HKDF salt
71c1d7e docs(portal): blueprint-schema synced to migration 0004 — hash-only LobsterKey ledger + pod purity
77d4303 docs(memory-bank): sync bank to the chronology+canon pathway
a640e09 docs(memory-bank): root-docs coherence + ClawKey canon receipts
818b38d feat(ui): ClawKey canon in user-facing strings — web says the same word as Android
354d69d docs(security,blueprint,readme,quickstart): v0.0.1.9 truth-sync + ClawKey canon
c7d5ed6 docs(architecture): sync to v0.0.1.9 runtime — ClawKey canon, hash-only ledger, pod purity
44eaebb docs(genome): README stale-claim sweep — 17 phases, v0.0.1.9 shipped, archive span 1-14
c515bed docs(memory-bank): reflect ROADMAP chronology pass — heredoc-emoji + checker lessons
5dd3979 docs(roadmap): reorganize to TOTP chronology — interlude inline, completed ascending, frontmatter
116d1db docs(memory-bank): re-point bank to Phase 18 — Option C queue restored
e08bb1e docs(genome): restore chronological queue — spine renumbered Stage N = Phase N-1
d353b88 docs(memory-bank): session handoff — bank pointed at Phase 22 (Reef Polish Pass)
c86c10a docs(genome): queue Phase 23 — Bitwarden-model item integrity (Tasks 45/46)
d893e32 docs(genome): Phase 22 expanded — unified zero-knowledge search + consolidation
d34749e docs(genome): queue Phase 22 — Reef Polish Pass (Task 43 eye relocation; Task 44 reserved)
0bb61bd merge: vault header flush + version-test integrity (post-v0.0.1.9 hotfix)
3464b18 docs(genome): post-additions — v0.0.1.9 shipped, roadmap molt & Stage 19 hotfix record
07ccd61 fix: flush vault master-detail headers + de-hardcode version test
632d7a3 docs(memory-bank): v0.0.1.9 released — systemic entry across all five bank files
9b5ec31 merge: v0.0.1.9 — application genome, coherence audit, Phase 17 key ledger hardening & CaraBase UI parity

---

🐳 Deployment (unchanged)

docker compose up -d --wait
# health: http://<host>:6464/api/health

Existing instances upgrade in place — no schema changes in this release
(the last migration remains 0004_key_ledger). Back up data/ as usual.
See QUICKSTART.md and docs/deployment/.

---

🔮 Next Molts

Phase 18 — Unified Bitwarden-Style Item Composition & In-Browser Keypair
Generation (Tasks 35/36, v0.0.2.0 / Build 20) is next, then Phases 19–23, and
Phase 24 closes the loop with the auditor's battery.

Maintained with cryptographic rigor by ClawStack Studios.

ShellGuard v0.0.1.9

🦞 ShellGuard — Release v0.0.1.9

The Application Genome — Reverse-Built /project System, Documentation Coherence Audit, and the Key Ledger Hardening (Phase 17)

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.1.9 of ShellGuard! This release ships the application's
genome: a reverse-built /project document-compiler system (meta-prompt
spine, receipt-backed roadmap, 10 spec oracles) from which the exact application
can be rebuilt from nothing. It closes the documentation coherence audit —
every dangling reference resolved, every docs-vs-runtime contradiction either
fixed or encoded as a queued phase — and lands Phase 17: Key Ledger Hardening
& Pod Purity, the release's security milestone: lb- Lobster Keys are now
stored as SHA-256 hashes only, and the server's hardcoded "Personal" pod is
gone. The Lobster Keys card UI is brought to 1:1 parity with CaraBase, with
full-value masking.

---

✨ Key Themes

🧬 1. The /project Reverse-Build Genome

• Meta-prompt spine (Stage 0 "void" → Stage 18): one paste-able prompt per
  phase; the roadmap discovers the specs; a cold reader can traverse the chain
  and make zero design decisions.
• Reverse-built roadmap: 16 phases / 32 task pairs (v0.0.0.0 →
  v0.0.1.8), every phase receipt-matched to real commits via gap-walking
  (git log --reverse between tags); 16/16 anchors + 20 flowchart edges verified.
• 10 spec oracles: architecture, database-schema, encryption-layers,
  routes-and-contracts, key-hierarchy, verification-gates, admin-suite,
  ui-ux-design-system, import-export, and the new shellcryption-spec.md —
  the client-side crypto oracle (HKDF derivation, envelope format, AAD
  namespace registry, decrypt passthrough ladder, invariants).
• Historical archive: Phases 1–13 preserved in
  .agents/memory-bank/ROADMAP-HISTORY.md under the 3-version sliding window.

🔍 2. Documentation Coherence Audit

• 50 dangling references repaired: project/ links repointed number-aware
  (Phases 1–13 → the archive, 14+ → the root sliding window) after the roadmap
  restructure; zero dangling edges remain (traversal-as-audit).
• Key alphabet corrected: docs claimed 64-hex key material; the runtime
  generates base62 (generateBase62(64) client / crypto.randomInt
  server) — ARCHITECTURE.md and key-hierarchy-spec.md now tell the truth.
• 10th oracle created: shellcryption-spec.md written from runtime ground
  truth (src/lib/shellCryption.ts), resolving the last dangling reference.
• Contradictions encoded, not papered over: the two docs-vs-runtime
  conflicts became Phase 17 (below) — the spec of record was never falsified.

🔐 3. Phase 17 — Key Ledger Hardening & Pod Purity [SECURITY]

• Hash-only agent key ledger: agent_keys now stores SHA-256 hashes
  (key_hash + key_fingerprint); the plaintext api_key column is retired.
  Migration 0004 + in-code backfill: legacy keys hashed in place (live
  keys keep authenticating), live agent api_tokens re-pointed from raw-key
  owner_uuid to the agent row id, the ledger rebuilt (SQLite refuses
  DROP COLUMN past a UNIQUE auto-index), and VACUUMed — freed pages no
  longer carry plaintext bytes.
• Plaintext shown exactly once: mint returns the raw lb- key once;
  every list response carries only the fingerprint. All auth paths —
  requireAuth (direct + token), the /api/auth/token sentinel (now
  constant-time against the stored hash), and the per-key rate limiter —
  operate on key_hash / agent id.
• Pod purity: DEFAULT 'Personal' purged from all four category columns
  (table rebuild); the category || 'Personal' fallback removed from
  vault.ts, notes.ts, sshKeys.ts, attachments.ts — uncategorized items
  persist as "", matching the client's normalizePod() semantics. Existing
  'Personal' rows are never rewritten.
• Proven by tests/agent-key-hash.test.ts: raw DB byte-scan (zero
  plaintext), legacy-backfill unit oracle (pre-migration keys keep working),
  one-time reveal, constant-time sentinel, revoke, and uncategorized
  persistence.

🎨 4. Lobster Keys UI — CaraBase 1:1 Card Parity

• The key row, faithful to CaraBase: masked by default, Eye/EyeOff toggle,
  Copy with 2s Copied feedback — over the SHA-256 fingerprint (the full key
  is revealed exactly once, in the wizard's generated step, which is already
  pixel-equivalent).
• Full-value masking: the hidden state covers the ENTIRE value — no
  leading/trailing cleartext (CaraBase's prefix/suffix mask algorithm was
  rejected as a leak).
• Tab alignment: heading, subtitle, and delete-confirmation wording aligned
  verbatim to CaraBase; Reef Modernist tokens preserved (the design-system
  invariant holds — structure 1:1, skin ShellGuard's).

🧪 5. Full Verification Loop

• 100% green test oracle: 210 tests passing across 15 suites
  (0 failures, 1 skipped) — including the 6-test key-ledger oracle.
• Strict TypeScript: clean tsc --noEmit.
• Production build: Vite build clean.
• The old buggy contract rewritten honestly: the metadata-encryption
  category test (which asserted the old 'Personal' fallback encryption) was
  updated to the uncategorized contract in the same change as the fix.

---

🏗️ Architectural Topology Map

Browser (React) → Express 5 API → SQLite (better-sqlite3-multiple-ciphers)
     ↓                    ↓                    ↓
ShellCryption      Per-Row Encryption     SQLCipher
(client-side)      (server-side)          (whole-DB)

hu- (human root) → SHA-256 only → lobsters.key_hash
lb- (agent keys) → SHA-256 only → agent_keys.key_hash   ← NEW in v0.0.1.9
api- (session)   → sessionStorage only

/project/  = the genome: spine → roadmap → 10 oracles (docs ARE the app)

---

📜 Commit Ledger (v0.0.1.8..v0.0.1.9)

aed63b8 docs(rules): persist session learnings — full-masking invariant, SQLite security-migration skill, batch-patch discipline
0bbc5be fix: fully mask the key row — no leading/trailing cleartext
9a27cb7 feat: Lobster Keys card key row — CaraBase 1:1 UI parity
7faf51d feat: Phase 17 — key ledger hardening & pod purity (v0.0.1.9)
e40b9f9 docs: genome coherence audit — ShellCryption oracle, dangling-ref repair & Phase 17 hotfix queue
2ec60f0 docs(memory-bank): record reverse-build genome session — summit state, sliding window, consolidated patterns
68d73cd docs: transcribe Phase 16 and close the spine - SUMMIT (v0.0.1.8)
4b6e52c docs: transcribe Phase 15 - sgtotp.bak Import Compatibility Layer (v0.0.1.7)
f12602a docs: transcribe Phase 14 - Native LAN TLS (v0.0.1.6)
5c96a18 docs: transcribe Phase 13 - Bitwarden-Style Custom Fields (v0.0.1.5 Milestone)
3cdf6d3 docs: transcribe Phase 12 - Pure TypeScript WebCrypto Fallback Engine (v0.0.1.4)
008d4ab docs: repair spine edge chain (P10->P11->P12), stale summit label, Phase 11 heading emoji
769cb22 docs: transcribe Phase 11 - Release Publishing CI & Iconography (v0.0.1.3)
3ccdd1b docs: transcribe Phase 10 - Deployment Hotfixes & Dev-Loop Formalization (v0.0.1.2)
47bddfd docs: sanitize Phase 9 anchor slug (drop emoji from heading)
024477a docs: transcribe Phase 9 - Genesis Release & Origin Hardening (v0.0.1)
daceac9 docs: rewire spine flowchart edge for Phase 9
adc01d4 docs: transcribe Phase 8 - Vault UX Renaissance
96ebc56 docs: transcribe Phase 7 - Multi-Account, QuickLogin & Landing Gateway
959ddae docs: transcribe Phase 6 - SuperLobster Admin Plane
8475713 docs: transcribe Phase 5 - Per-Row Metadata Encryption & Port Molt
a85fe51 docs: transcribe Phase 4 - Test Oracle, Container Deployment & License
0f5e007 docs: transcribe Phase 3 — Vault CRUD, Lobster Keys & Settings Storage
a8be8f6 docs: add intuitive-recognition agent rule for pattern-based decision making
d97634e docs: transcribe Phase 2 — SQLite Bedrock, Security Kernel & Identity Bridge
d880a5d docs: open reverse-build /project system with spine head and Phase 1

---

🚢 Deployment

docker pull ghcr.io/clawstackstudios/shellguard:v0.0.1.9
# or
docker pull ghcr.io/clawstackstudios/shellguard:latest

• Upgrading from v0.0.1.8: migration 0004 applies automatically on boot —
  existing lb- keys are hashed in place and keep working; live agent sessions
  are preserved until natural expiry. No manual action required.
• Note: the first boot after upgrade logs
  [Key Ledger] 🔐 Hashed N agent key(s) in place; plaintext api_key column retired. — that is the migration doing its job.
• Unraid users: update via the Community Applications template as usual.
• Existing 'Personal'-categorized items are untouched; only new items default
  to uncategorized ("").

---

Release grammar: tag → RELEASE doc → CHANGELOG → version bump. The GitHub
Release body mirrors this file verbatim via the release pipeline.

ShellGuard v0.0.1.8

🦞 ShellGuard — Release v0.0.1.8

Canonical Compliance & Full Documentation Bridge Parity — Official Privacy Policy, Mobile Companion Portal, and Ground-Truth Architecture

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.1.8 of ShellGuard! This release establishes the official, canonical Privacy Policy required for Google Play Store compliance, introduces a dedicated ShellGuard-TOTP Native Companion Documentation Portal, and achieves 100% two-sided bridge parity between our runtime codebase and user documentation.

We resolved documentation drift across database schemas, published missing top-level index portals (/vault-features/, /deployment/, /reference/), documented Bitwarden-style custom fields, Native LAN TLS (TLS_ENABLED=true), and .sgtotp.bak Android backup decryption, and aligned the 3-Step Rapid Onboarding lifecycle (Configure & Generate Keys → Start & Verify Container → Launch Vault & Molt Identity) across all documentation entry points.

---

💎 Key Themes & Highlights

⚖️ 1. Official Privacy Policy & Google Play Store Compliance

• Canonical Hosting at /privacy: Published the official privacy policy in the permanent VitePress portal (docs/privacy.md), publicly accessible via GitHub Pages for mobile app store review guidelines.
• Dedicated ShellGuard-TOTP Specification (Section 5): Added deep-link anchor {#shellguard-totp-android-companion} with a Google Play Data Safety Fast-Card table confirming zero data collection, zero analytics, zero trackers, and zero third-party sharing.
• Hardware Permission Disclosures: Detailed explicit technical scopes for android.permission.CAMERA (ephemeral in-memory frame analysis; zero frames saved to disk or cache), Biometrics (hardware enclave isolation via Android KeyStore with zero biometric credential leakage), and Storage Access Framework (scoped user-initiated .sgtotp.bak backup export/import without broad media permissions).
• Display Shielding: Documented FLAG_SECURE window protection blocking screen captures, screen sharing, and task-switcher previews.

📱 2. ShellGuard-TOTP Native Mobile Companion Documentation Suite

• System Topology & Mirror Sync (docs/companion/index.md): Formalized the One-Way Mirror Sync architecture distinguishing sovereign local tokens from read-only mirrored vault credentials with interactive Mermaid dataflow diagrams.
• Hardware Security & KeyStore Enclaves (docs/companion/security.md): Deep-dived into TEE and StrongBox Keymaster AES-GCM-256 key wrapping, BiometricPrompt zero-knowledge biometric isolation, memory zeroization, and auto-lock lifecycles.
• Encrypted Backups Wire Format (docs/companion/sync-and-backups.md): Specified the shellguard-totp-backup-v1 envelope, HKDF-SHA256 derivation, AES-GCM-256 authenticated encryption with AAD (totp_backup:{ownerUuid}), and SHA-256 integrity verification.
• RFC 6238 TOTP Engine (docs/companion/totp-engine.md): Detailed the mathematical time-step algorithm ($T = \lfloor (t - T_0)/X \rfloor$), dynamic truncation, HMAC-SHA1/256/512 support, RFC 4648 Base32 sanitization, otpauth:// URI parameter decoding, and CameraX + ML Kit barcode analysis.

🌉 3. Two-Sided Bridge Parity & Documentation Hubs

• Top-Level Index Hubs: Built missing portals for docs/vault-features/index.md, docs/deployment/index.md, and docs/reference/index.md to eliminate navbar 404s and provide clear <CardGrid> navigation.
• Database Schema Ground Truth: Reconciled docs/reference/blueprint-schema.md with runtime reality (lobsters table name, agent_keys table name, id primary keys, custom_fields column, and audit_logs in audit.sqlite).
• Bitwarden-Style Custom Fields: Documented Text, Hidden, Checkbox, and Linked field types with client-side ShellCryption AAD namespaces in docs/vault-features/the-grotto.md.
• Native LAN TLS & WebCrypto Fallback: Documented TLS_ENABLED=true (self-signed 10-year EC P-256 certificate generation with dynamic LAN SANs) and pure TypeScript webCryptoFallback.ts for non-secure HTTP LAN contexts.
• Onboarding Alignment: Realigned the 3-Step Rapid Onboarding lifecycle (Configure & Generate Keys → Start & Verify → Launch Vault & Molt Identity) across docs/index.md, docs/getting-started/quickstart.md, and docs/deployment/docker.md.

🧪 4. Full Verification Loop & Test Stabilization

• Sequential Test Isolation: Configured fileParallelism: false in vitest.config.ts, eliminating port collisions and SQLite migration lock contention across full-suite test runs.
• 100% Green Test Oracle: 202 unit and integration tests passing across all 13 suites (0 failures, 1 skipped).
• Zero-Warning Production Documentation: VitePress build passes 100% clean with zero broken links and zero syntax warnings (npm run docs:build in 37.3s).
• Strict TypeScript Type Safety: Clean compilation with zero errors (tsc --noEmit).

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────────┐
│                       🖥️ ShellGuard Web Vault (:6464)                       │
│  • Sovereign zero-knowledge vault for logins, notes, SSH keys, attachments  │
│  • Client ShellCryption (hu- master key) + Bitwarden-style Custom Fields    │
│  • Client-side sgtotp.bak format sniffing & HKDF/AES-GCM decryption engine  │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                One-Way Mirror Sync    │ (GET /api/vault read-only cache)
                and .sgtotp.bak export │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                 📱 ShellGuard-TOTP Android Companion                        │
│  • Hardware KeyStore (TEE / StrongBox AES-GCM-256)                          │
│  • BiometricPrompt unlock + FLAG_SECURE window screenshot suppression       │
│  • RFC 6238 TOTP Engine (HMAC-SHA1/256/512) + CameraX in-memory scanner    │
│  • Sovereign Local Codes exported to encrypted .sgtotp.bak archives         │
└─────────────────────────────────────────────────────────────────────────────┘

---

📦 Changes by Layer

Component	Files	Description
Compliance & Privacy	docs/privacy.md	Canonical Privacy Policy with Section 5 ShellGuard-TOTP Android store disclosures.
Mobile Companion Docs	docs/companion/*.md	4 comprehensive guides: Index/Topology, Security, Sync & Backups, and RFC 6238 Engine.
Index Portals	docs/{vault-features,deployment,reference}/index.md	3 new top-level documentation hubs with <CardGrid> navigation.
Technical Reference	docs/reference/blueprint-schema.md, design-system.md, glossary.md	Ground-truth database schemas, design tokens, 6 theme palettes, and lexicon glossary.
Deployment & Ops	docs/deployment/docker.md, reverse-proxy.md, unraid.md	Complete Docker Compose guide, Native LAN TLS, and Unraid setup.
Onboarding	docs/index.md, docs/getting-started/quickstart.md	Realigned 3-Step Rapid Onboarding lifecycle (Configure → Start → Launch).
Navigation & Theme	docs/.vitepress/config.ts	Added Mobile Companion nav, sidebar entries, and index routing.
Test Stability	vitest.config.ts	Configured fileParallelism: false for zero-contention test execution.

---

📋 Commit Ledger (Since v0.0.1.7)

• ddc35f5 — docs: add official privacy policy and ShellGuard-TOTP store disclosures
• 124e4ab — docs: document privacy policy in CHANGELOG.md
• 80babe5 — merge: add official privacy policy and ShellGuard-TOTP store disclosures
• acab2ab — docs: add ShellGuard-TOTP native companion documentation suite
• 700c18c — merge: add ShellGuard-TOTP native companion documentation suite
• 1244c5f — docs: achieve two-sided bridge parity across documentation and runtime architecture
• e61675b — merge: achieve two-sided bridge parity across documentation and runtime architecture

---

🚀 Upgrade & Verification Instructions

Upgrading via Docker / Unraid

docker pull ghcr.io/clawstackstudios/shellguard:v0.0.1.8
docker restart shellguard

Upgrading from Source

git fetch --tags
git checkout v0.0.1.8
npm install
npm run build
npm run scuttle:prod