Keymaster Security Design

Keymaster Security Design

Component: Keymaster (Security Gatekeeper)
Status: ✅ In Active Implementation (Revision 14+)
Last Updated: April 23, 2026
Author: jstevh

Keymaster is the central security layer of the Metadata System. All files enter and leave exclusively through Keymaster. No direct filesystem access is allowed outside the Sandbox.

Core Security Principles

• Sandbox-Only Storage: Every file is immediately placed into an isolated Sandbox. No files ever live on the host outside Keymaster control.
• Content-Based Validation: Validation uses magic bytes + content scanning (not just file extensions) to detect disguised or malicious files.
• Metadata-Driven Organization: Files are automatically placed into folders based on extracted metadata.
• Known-Type Whitelist for Push: Only pre-approved document types can be pushed to nodes (starting with PDF).

High-Level Architecture

External World Keymaster (Security Core) Sandbox
───────────────────── ──────────────────────────── ─────────────────────
User drops file → Keymaster (Gatekeeper)
(e.g. PDF) → FileValidator + DocumentType
(magic bytes check) → Sandbox Root
→ Metadata-driven folder /sandbox/document-types/...
→ MObject registration (organized by type + date + uuid)
→ PushGuard (planned)
Only known DocumentType
↓ (optional)
Remote Node
text## Key Security Components

• Keymaster – Main gatekeeper with validateAndIngest(File)
• DocumentType – Enum defining official supported document types (PDF, DOCX, TXT, ...)
• FileValidator – Performs strong magic-byte validation and returns DocumentType
• FolderOrganizer – Creates clean metadata-driven paths
• PushGuard – (Planned) Whitelist enforcement before pushing to nodes

Secure File Flow (Current Implementation)

1. User selects file via addFileToSandboxInteractively()
2. FileValidator.validateDocument() checks magic bytes and returns DocumentType
3. If valid → create metadata-driven folder (/sandbox/document-types/YYYY-MM-DD-uuid/pdf/)
4. File is copied safely into the Sandbox
5. MObject is created and registered with rich metadata (documentType, mimeType, sandboxPath, etc.)

Security Guarantees

Feature	Status	How It Is Implemented	Benefit
Sandbox-Only	✅ Done	All files forced into isolated Sandbox	Strong containment
Strong Type Validation	✅ Done	Magic bytes via FileValidator + DocumentType	Prevents disguised malware
Metadata Folder Structure	✅ Done	Auto-generated paths with date + uuid	Better organization & auditability
Known Document Types	✅ Done	DocumentType enum (PDF first)	Foundation for whitelist
Push Whitelist	☐ Planned	PushGuard class (next)	Defense-in-depth

Progress & Next Steps (as of April 23, 2026)

• ✅ Keymaster.java updated with secure validateAndIngest()
• ✅ FileValidator.java with magic byte checks
• ✅ DocumentType enum added (PDF, DOCX, TXT, UNKNOWN)
• ✅ Files now stored in well-organized Sandbox folders
• ☐ Implement PushGuard for known-type whitelist before pushing to nodes
• ☐ Create [[Sandbox Design]] wiki page
• ☐ Expand validation to more document types

Related Pages:
[[Home]]
[[Sandbox Design]] (planned next)

---

*This page is part of the Metadata System design documentation. Updated after Revision 14+ wi