π The Grotto & Pod Organization β
The Grotto is the primary vault dashboard in ShellGuard where users organize and manage their sovereign secrets into hierarchical, color-coded Pods.
π Supported Item Types β
| Item Type | Icon | Encrypted Payload Fields | Metadata Fields (Layer 2 Encrypted) |
|---|---|---|---|
| Vault Pearl (Login) | π | secret (Password), totp_secret (Seed), attachments (File IDs), custom_fields | title, username, url, category, notes, tags |
| Credit Card | π³ | secret (Card Details), attachments (File IDs), custom_fields | title, username, category, notes, tags |
| Identity | πͺͺ | secret (Identity Details), attachments (File IDs), custom_fields | title, username, category, notes, tags |
| Secure Note | π | content (Markdown body), attachments (File IDs), custom_fields | title, category, notes, tags |
| SSH Key | π» | key_value (Private Key β raw or generated keypair JSON), custom_fields, attachments (File IDs) | title, username, category, notes, tags |
| Encrypted Attachment | π | Encrypted file BLOB (AES-GCM up to 500 MB streaming, 1000 MB quota) | title, file_name, mime_type, category, parent_id, parent_type |
Bitwarden Item Integrity Model: The UI enforces a deterministic sort order across all lists: Passwords (
password) β Credit Cards (card) β Identities (identity) β Secure Notes (note) β SSH Keys (key). Attachments (attachment) are never standalone vault items and cannot be created independently; they exist exclusively as child components inside a parent item's detail pane. Unparented attachments are swept into quarantine on boot. Pod tallies count primary items only.
π Creating Your First Login Item β
Adding a credential to your sovereign vault takes seconds:
- Open New Item Modal: Click the glowing + New Item button at the top of the vault sidebar, or press the keyboard shortcut N.
- Select Type: Choose Vault Pearl (Login) from the item type selector.
- Enter Credentials:
- Title: A recognizable service name (e.g.
ProtonMail,GitHub). - Username: Your handle, email, or account ID.
- Password: Enter an existing password, or click the Dice icon to roll a high-entropy password using the built-in Pearl Password Generator.
- Website (URL): Target login domain (e.g.
https://github.com/login).
- Title: A recognizable service name (e.g.
- Organize into a Pod: In the Pod / Category field, type a pod path (e.g.
Personal/EmailorDev/Cloud). ShellGuard creates hierarchical sub-pods dynamically with/separators. - Save: Click Save Pearl. The secret payload is immediately sealed in browser RAM using Layer 1 AES-GCM-256 before being sent to the server.
π In-Browser SSH Keypair Generation & Dual-Key Management β
When adding or managing an SSH Key, ShellGuard provides an integrated, zero-knowledge keypair lifecycle engineered for terminal ergonomics and OpenSSH compliance:
1. In-Browser Keypair Generation β
- Supported Algorithms: Ed25519 (high-security Edwards-curve signature algorithm, 256-bit) and RSA-4096 (legacy compatibility).
- Zero-Knowledge Generation: Keys are derived entirely inside browser RAM via the WebCrypto API (
crypto.subtle). Private keys never touch the network in plaintext. ssh-keygenParity: Public and private key outputs are byte-identical to standard OpenSSHssh-keygen -t ed25519andssh-keygen -t rsa -b 4096implementations.
2. Dual-Key Architecture & Serialization β
- Dual-Key Storage: Generated keypairs serialize into a structured JSON envelope
{ "publicKey": "...", "privateKey": "..." }sealed client-side inside thekey_valuecolumn under Layer 1 ShellCryption. - Transparent Backward Compatibility: ShellGuard's parser (
parseSshKeySecret) automatically detects whetherkey_valuecontains a dual-key JSON object or a legacy raw PEM string. Legacy keys continue to unmask and copy flawlessly without database migrations. - Decoupled Form Inputs: The item edit modal provides dedicated, decoupled input fields for the Private Key (PEM) and the OpenSSH Public Key, preventing JSON serialization strings from ever leaking into user-facing textareas.
3. Clean PKCS#8 PEM Presentation & Formatting Invariants β
- Strict RFC 7468 Framing: Private keys strictly preserve their canonical
-----BEGIN PRIVATE KEY-----and-----END PRIVATE KEY-----delimiters. Without these exact boundaries, tools likessh -i,ssh-add, and Git clients fail with "invalid format" errors. - Multi-Line Styled Code Block: Unmasking the private key renders a formatted, monospace
<pre>block that clearly displays indentation and line wraps. - Eye-Beside-Copy Ergonomics: The unmask (Eye/EyeOff) toggle sits immediately to the left of the Copy action, preserving full-value mask invariants (
β’β’β’β’β’β’β’β’) until deliberately revealed.
4. Terminal Ergonomics & Deployment Actions β
The Item Detail Pane equips engineers with zero-friction deployment actions:
- Copy Public Key: Copies the standard single-line OpenSSH public string (e.g.
ssh-ed25519 AAAAC3... shellguard-generated). - Copy
authorized_keysCommand: Copies a ready-to-run shell one-liner:bashPaste directly into an SSH session or cloud-init configuration to grant immediate server access.echo "ssh-ed25519 AAAAC3... user@host" >> ~/.ssh/authorized_keys - Download
.pem: Generates and downloads<sanitized-title>.pemdirectly in the browser with standard0600-compatible line breaks for immediate use withssh -i <key>.pem user@host.
NOTE
Keypair generation requires a secure context (HTTPS or localhost) β the WebCrypto API is unavailable on plain-HTTP LAN origins. On insecure origins, ShellGuard displays a helpful notice while continuing to allow pasting, editing, and downloading existing keys. This browser platform constraint is handled with graceful fallbacks.
π§© Bitwarden-Style Custom Fields β
ShellGuard supports rich custom fields for vault pearls, secure notes, and SSH keys, matching Bitwarden's flexibility while maintaining triple-layer zero-knowledge encryption.
Supported Field Types: β
- Text: Plain textual key-value metadata (e.g. security questions, recovery emails, server ports).
- Hidden: Obfuscated masked values with one-click copy and toggle reveal (e.g. PINs, API secrets, master passwords).
- Checkbox: Boolean flags for credential states (e.g. "2FA Activated", "Requires VPN").
- Linked: Dynamic pointers referencing existing item fields (
Username,Password,URL,Notes,TOTP), preventing manual re-entry when fields are shared.
Cryptographic Isolation: β
- Custom fields are serialized to JSON and encrypted client-side before submission.
- Uses distinct AAD (Additional Authenticated Data) binding namespaces:
- Pearls:
vault_pearls_custom:{id} - Notes:
vault_secure_notes_custom:{id} - SSH Keys:
vault_ssh_keys_custom:{id}
- Pearls:
- Stored as opaque ciphertext in the
custom_fieldsTEXT column (Migration0003_custom_fields.up.sql).
π¨ User-Driven Pods & Hierarchical Categories β
ShellGuard provides 100% user-driven pod categorization with zero hardcoded phantom folders:
- Hierarchical Pathing: Sub-pods are created using
/delimiters (e.g.,Work/AWS,Personal/Banking). - Accent Palettes: Pods can be color-coded with curated bioluminescent hues (Emerald
#10b981, Cyan#06b6d4, Gold#f59e0b, Purple#8b5cf6, Rose#e4048a). - Category Normalization: Input categories are sanitized via
normalizePod()to ensure whitespace trimming, forward slash consistency, and safe grouping. - Cascade to Uncategorized: Deleting a pod safely shifts its child items to uncategorized (
""), preventing accidental credential loss.
π·οΈ Vault Tagging System & Granular Filter Bar β
ShellGuard supports multi-dimensional tagging alongside hierarchical pods:
- Tag Selector Input: Add and remove tags as keyboard chips with autocomplete suggestions and inline color palette selection.
- Unified Color Engine: Tags and pods share a bioluminescent palette engine with deterministic string hashing (
hashStringToColor) and explicit user overrides. - Sidebar Tag Cloud: A collapsible "TAGS" section in the navigation tree reflects all assigned tags with item counts.
- Granular Filter Bar: Combine multiple tag filters with dynamic
AND/ORintersection logic, clearing filters with a single click.
π Robust Unified Vault & Pod Search Engine β
ShellGuard separates search into two purpose-built, zero-knowledge search bars tailored to user focus:
- Item Search Bar (
ItemListPane): Consolidated directly above the credential list, querying in-memory decrypted titles, usernames, URLs, secondary URIs, notes, custom fields, attachment filenames, and tags in real time. - Pod Search Bar (
SidebarFolderTree): Anchored above the Pod tree in the navigation sidebar, providing high-speed scoped path filtering across 50+ pods without polluting credential search queries.
π Deep Dive: See the dedicated Unified Vault & Pod Search guide for full architectural specifications, security invariants, and surface consolidation rationale.
β±οΈ Dynamic RFC 6238 TOTP Authenticator Engine β
ShellGuard includes a zero-knowledge, client-side dynamic TOTP engine (totpUtils.ts):
- Dynamic Algorithm & Interval Support: Generates codes for standard and advanced authenticator configurations, supporting SHA1, SHA256, and SHA512 HMAC hashing, 6 or 8 digits, and custom refresh intervals (15s, 30s, 60s).
- Full URI & Seed Ingestion: Paste raw Base32 secret seeds (
JBSWY3DPEHPK3PXP) or completeotpauth://totp/...URIs. Parameters likealgorithm,digits, andperiodare parsed dynamically and preserved round-trip. - Zero-Knowledge Storage: The TOTP seed or URI is sealed client-side inside the
totp_secretcolumn under Layer 1 ShellCryption (vault_pearls_totp:{id}). - Client-Side Generation: Countdown rings and dynamic verification codes calculate purely in browser RAM with zero server interaction.
- Companion Mirroring: Stored TOTP parameters seamlessly mirror to the native ShellGuard-TOTP Android companion for offline authentication on your mobile device.
π Composite Item Features: Multi-URI & Password History β
ShellGuard provides rich composite credential features matching modern power-user workflows:
Multi-URI Row Support β
- Secondary Login Domains: Add arbitrary secondary URIs per login item (e.g.
https://accounts.google.com,https://mail.google.com,androidapp://...). - Domain Extraction & Quick Launch: Automatically parses hostnames and renders external launch buttons beside each URI row.
- Layer 2 Metadata Encryption: Secondary URIs are encrypted at rest using
MetadataGuard(vault_pearls.uris), matching the protection model of the primary URL.
Item Password Generation History β
- Per-Item Generation Tracking: Every time the password generator is triggered inside the item form, the previous password revision is preserved in the item's history drawer with a timestamp.
- Client-Side Layer 1 ShellCryption: Password history records are sealed in the browser under dedicated AAD
vault_pearls_history:{id}(vault_pearls.password_history), ensuring the server never sees historical passwords. - Interactive History Drawer: View previous passwords with unmask toggles, copy actions, and instant one-click restore.
β‘ Batch Multi-Selection, Pod Reassignment & Bulk Operations β
ShellGuard provides rich batch management tools to organize, migrate, and prune credentials in bulk:
- Tri-State Multi-Selection: Select individual items via checkbox, or toggle select-all across filtered views using the header tri-state checkbox.
- Floating Action Bar: Displays selected item counts with bulk actions (Move to Pod, Assign Tags, Delete Selected). Guarded automatically against display when the vault is locked (
!isLocked). - Bulk Move to Pod: Move multiple logins, notes, or keys to a destination pod in one action, fully preserving tags and metadata.
- Bulk Tag Assignment: Add tags across multiple selected items without wiping pre-existing tags.
- Bulk Delete with Safe Cascade: Batch remove selected items with a Reef Modernist confirmation modal (
ConfirmDialog); automatically cascades deletions to linked file attachments without orphan records. - Bulk Import with 207 Multi-Status: Import up to 1,000 items in a single atomic transaction. Any malformed records are reported with granular error resolution chips indicating item index, title, and validation reason while valid items persist cleanly.
π₯ Progressive Disclosure Quarantine & Floating Batch Actions β
In Phase 26, The Grotto gained native support for ephemeral import quarantine management:
- Progressive Disclosure Invariant: If no quarantined records exist, zero quarantine filter chips or batch action bars are rendered, preserving a clean workspace.
- Dynamic Quarantine Filter Chip: When active ungraduated records exist in state, a glowing
Quarantined (N)filter tab appears directly under the search bar inItemListPane. - Bioluminescent Badges: Each quarantined record displays an amber bioluminescent status badge indicating its active quarantine state.
- Centered Floating Batch Bar: When filtered to quarantined records, a centered action bar surfaces with instant Graduate All and
ConfirmDialog-guarded Revert Import controls, maintaining strict spatial separation from the bottom-rightAbyssalIngestionDock. - Inline Detail Pane Quarantine Card: Selecting any quarantined item surfaces an inspection banner in the detail pane with one-click Graduate to Vault and Revert Batch operations.