Skip to content

🐚 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 TypeIconEncrypted Payload FieldsMetadata Fields (Layer 2 Encrypted)
Vault Pearl (Login)πŸ”‘secret (Password), totp_secret (Seed), attachments (File IDs), custom_fieldstitle, username, url, category, notes, tags
Credit CardπŸ’³secret (Card Details), attachments (File IDs), custom_fieldstitle, username, category, notes, tags
IdentityπŸͺͺsecret (Identity Details), attachments (File IDs), custom_fieldstitle, username, category, notes, tags
Secure NoteπŸ“content (Markdown body), attachments (File IDs), custom_fieldstitle, 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:

  1. Open New Item Modal: Click the glowing + New Item button at the top of the vault sidebar, or press the keyboard shortcut N.
  2. Select Type: Choose Vault Pearl (Login) from the item type selector.
  3. 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).
  4. Organize into a Pod: In the Pod / Category field, type a pod path (e.g. Personal/Email or Dev/Cloud). ShellGuard creates hierarchical sub-pods dynamically with / separators.
  5. 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-keygen Parity: Public and private key outputs are byte-identical to standard OpenSSH ssh-keygen -t ed25519 and ssh-keygen -t rsa -b 4096 implementations.

2. Dual-Key Architecture & Serialization ​

  • Dual-Key Storage: Generated keypairs serialize into a structured JSON envelope { "publicKey": "...", "privateKey": "..." } sealed client-side inside the key_value column under Layer 1 ShellCryption.
  • Transparent Backward Compatibility: ShellGuard's parser (parseSshKeySecret) automatically detects whether key_value contains 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 like ssh -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_keys Command: Copies a ready-to-run shell one-liner:
    bash
    echo "ssh-ed25519 AAAAC3... user@host" >> ~/.ssh/authorized_keys
    Paste directly into an SSH session or cloud-init configuration to grant immediate server access.
  • Download .pem: Generates and downloads <sanitized-title>.pem directly in the browser with standard 0600-compatible line breaks for immediate use with ssh -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: ​

  1. Text: Plain textual key-value metadata (e.g. security questions, recovery emails, server ports).
  2. Hidden: Obfuscated masked values with one-click copy and toggle reveal (e.g. PINs, API secrets, master passwords).
  3. Checkbox: Boolean flags for credential states (e.g. "2FA Activated", "Requires VPN").
  4. 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}
  • Stored as opaque ciphertext in the custom_fields TEXT column (Migration 0003_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 / OR intersection 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:

  1. 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.
  2. 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 complete otpauth://totp/... URIs. Parameters like algorithm, digits, and period are parsed dynamically and preserved round-trip.
  • Zero-Knowledge Storage: The TOTP seed or URI is sealed client-side inside the totp_secret column 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 in ItemListPane.
  • 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-right AbyssalIngestionDock.
  • 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.

Sovereign Zero-Knowledge Secrets Vault. Released under AGPL-3.0. β€’ Privacy Policy