Encrypted Vault Attachments β
ShellGuard features a dedicated Reference Model for encrypted file attachments, allowing you to attach license files, recovery keys, certificates, or documents directly to your vault pearls and secure notes.
π The Reference Model Architecture β
Instead of bloating credential rows with monolithic payloads, ShellGuard stores each attached file as an independent, fully encrypted record in vault_secure_attachments:
ββββββββββββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββββ
β vault_pearls (Login) β β vault_secure_attachments β
β β β β
β uuid: "pearl-123" β β uuid: "att-456" β
β title: "AWS Root Credentials" β β file_name: "root_credentials.csv" β
β attachments: '["att-456","att-789"]'ββββββββΊβ file_data: { AES-GCM-256 blob } β
ββββββββββββββββββββββββββββββββββββββββ β size_bytes: 42100 β
β β
ββββββββββββββββββββββββββββββββββββββββ β β
β vault_secure_notes (Note) β β uuid: "att-789" β
β β β file_name: "server_cert.pem" β
β uuid: "note-321" β β file_data: { AES-GCM-256 blob } β
β title: "Cluster Recovery Protocol" β β size_bytes: 8400 β
β attachments: '["att-789"]' ββββββββΊβ β
ββββββββββββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββββKey Technical Properties: β
- Zero-Standalone Invariant: Attachments are always child components of a primary vault item (Password, Card, Identity, Secure Note, or SSH Key). Standalone attachments are forbidden. A valid
parent_idandparent_typemust be provided during upload, or the server will return400 Bad Request. - 500 MB Hard Limit Per Attachment: Enforced mid-stream by the server's
Busboymultipart handler (ATTACHMENT_MAX_MB, default 500MB per attachment) β a breach destroys the request and returns413, never buffering past the ceiling. - 1000 MB (1 GB) Grotto Quota Per Owner: Total stored ciphertext is capped per
owner_uuid(GROTTO_QUOTA_MB, default 1000MB) via an exactSUM(size_bytes)aggregate β over-quota uploads yield413and store nothing. Clients can inspect remaining capacity pre-flight viaGET /api/attachments/quota. - Unlimited Attachments Per Parent Item: A login pearl, secure note, or SSH key can link to as many individual file attachments as needed via its JSON UUID array.
- Atomic Cascade Deletion: When a parent item is deleted, the backend automatically performs a foreign-key-safe cascade deletion of all linked attachment records in
vault_secure_attachments. Conversely, if an individual attachment is deleted (DELETE /api/attachments/:id), the backend cleanly transactionally purges the deleted ID from the parent item's JSON array. - Client-Side Encryption & Decryption: File bytes are encrypted in your browser before upload; the ShellCryption envelope streams as multipart bytes (no base64 inflation). The list endpoint never carries payloads β downloads stream the BLOB in 1MB chunks from
GET /api/attachments/:id/fileand decrypt in browser memory. - Inline Previews: Common image types and PDFs render in an encrypted preview modal β PDFs load from a Blob object URL (never a
data:URI, honoring the insecure-origin invariant). - Orphan Quarantine Engine: During server boot (and on-demand at runtime via
POST /api/attachments/quarantine/sweep), any unparented legacy or orphaned attachments are placed into quarantine (is_quarantined = 1). Quarantined attachments are hidden from lists and file streams but are never deleted to prevent data loss. Quarantine events are recorded in the audit logs.
Two-Stage Ingestion Pipeline β
Importing large archives with massive encrypted BLOBs requires an advanced ingestion pipeline to prevent browser lock-up.
Stage 1: Fast Manifest Commit β
When a .zip archive is dropped onto the Habitat Dropzone, ShellGuard uses the Web Streams API to sniff the contents, quickly extracting the JSON manifest and bypassing attachment parsing. Primary credentials (passwords, secure notes) are committed instantly (often in under 2 seconds) to unlock the Vault interface immediately.
Stage 2: Abyssal Ingestion Dock β
Attachments are placed in a background queue. The floating Abyssal Ingestion Dock appears in the bottom right of the vault interface, providing ergonomic controls:
- Pause/Resume
- Cancel All
- Retry on network failure
Reactive bioluminescence β
Items associated with in-flight background uploads feature reactive UI indicators. You will see pulsing (Uploading...) chips inside the ItemDetailPane.tsx and spinning loader icons on the row in the ItemListPane.tsx. These transitions instantly lock into a (Verified) state as each file safely hits the underlying SQLite datastore.