π¦ Import & Sovereign Export β
ShellGuard adheres to the principle of absolute data sovereignty. Your secrets are never locked into proprietary formats or vendor databases. You can export, backup, migrate, or restore your vault across any ShellGuard instance or client companion at any time.
Navigate to Settings β Import & Export to manage data portability.
π€ Sovereign Export Formats β
1. Dual Vault Export Suite β
- Identity Re-Authentication: Requires re-entering your
hu-sovereign master key to authorize decryption of in-memory items before export. - Payload Scope: Complete vault archive containing pearls, logins (with multi-URI and password history), secure notes, SSH keys, attachments, and custom fields.
- Export Options:
- Encrypted Backup JSON (
shellguard-vault-backup-v1, Envelopev: 1): Sealed client-side via AES-256-GCM. Derives encryption keys from either your 256-bit ClawKey (HKDF-SHA256) or a custom user passphrase (PBKDF2-SHA256, 100,000 iterations). Enforces CSPRNG generation for salt and IV. Includes byte-exact SHA-256 checksum and AAD tamper protection. - Decrypted Plaintext JSON: Complete unencrypted vault schema suitable for cold offline storage or direct migration to another ShellGuard instance.
- RFC 4180 CSV Spreadsheet Export: Clean tabular export with a user-toggleable "Include Decrypted Passwords" audit control. Omitting passwords produces a sanitized credential registry for organizational hygiene auditing.
- Encrypted Backup JSON (
π₯ Import Formats & Compatibility β
ShellGuard features a unified client-side import engine capable of auto-detecting and ingesting five distinct backup formats:
1. Bitwarden Ingestion Parity (JSON & CSV) β
ShellGuard provides first-class, seamless migration from Bitwarden:
- Unencrypted Bitwarden JSON: Automatically parses
items[]across Logins, Secure Notes, and SSH keys. Normalizes Bitwarden folders to ShellGuard pods (normalizePod), converts multi-URIs into structured login rows, extracts password revision history, translates custom fields (Text,Hidden,Checkbox,Linked), and parses dynamic TOTP seeds (otpauth://URIs with SHA1/256/512, 6/8 digits, custom periods). - Bitwarden CSV: Adheres to RFC 4180 CSV standards for quoted multiline fields, commas, and escaped quotes.
- Encrypted Bitwarden Sniffer: Detects encrypted Bitwarden exports (
encrypted: true) and immediately informs the user to export unencrypted JSON/CSV from the Bitwarden web vault or use the Bitwarden CLI, preventing silent corrupt imports.
2. Sovereign ShellGuard Vault Backups (Encrypted & Plaintext) β
Upload any previously exported ShellGuard backup. If encrypted (v: 1), an in-browser modal prompts for either the active ClawKey or the custom passphrase used during export. The client decrypts, verifies integrity, displays the import preview, and re-seals each item under the current session's key.
3. ShellGuard-TOTP Android Backup (.sgtotp.bak) β
ShellGuard natively supports direct import of backups generated by the official ShellGuard-TOTP Android Companion:
- Auto-Sniffing: The file uploader automatically detects
.sgtotp.bakextensions and envelope headers. - Encrypted Backups (
shellguard-totp-backup-v1): When an encrypted companion backup is uploaded, an in-browser modal prompts for the export passphrase. Decryption is performed entirely client-side using HKDF-SHA256 and AES-GCM-256, verifying the AAD (totp_backup:{ownerUuid}) and the byte-exact SHA-256 payload checksum. - Plaintext Backups (
shellguard-totp-plain-export-v1): Unencrypted companion exports and raw JSON token arrays are parsed directly. - Normalization Invariants:
- Base32 Normalization: Secret seeds are sanitized (stripping spaces, hyphens, and converting to uppercase).
- Fresh UUID Assignment: Items receive new collision-free Web UUIDs.
- Pod Mapping: Android categories map to vault Pods using
normalizePod().
4. ShellGuard Mobile Android Backup (.sgvault.bak) β
ShellGuard natively supports full vault archives generated by the native ShellGuard Mobile client:
- Scope & Contents: Contains complete representations of all 5 record domains (Logins, Secure Notes, Credit Cards, Identities, and SSH Keys) along with custom fields and metadata.
- Envelope Security: Encrypted with AES-GCM-256 using keys derived from the master sovereign key or a custom export passphrase via PBKDF2-SHA256 (100,000 rounds).
- Client-Side Ingestion: Uploading
.sgvault.bakdecrypts entirely inside client memory, presents an interactive batch preview, and allows selective merging or full vault reconstruction.
β‘ High-Throughput Bulk Import & Partial-Failure Engine β
ShellGuard includes an optimized transactional bulk import engine (POST /api/vault/bulk-import) engineered for migrating large credential databases without single-item request round-trips:
- 10MB Scoped Payload Parser: Accommodates bulk imports of up to 1,000 items in a single HTTP request while preserving tight 1MB limits across other API endpoints.
- Transactional Atomicity: All valid items are committed inside an atomic SQLite transaction.
- Interactive UI Error Resolution: Skipped items are visually flagged in the Import view with warning badges and item chips detailing the zero-based index and field validation errors.
Habitat Full-Archive Mobility β
In Phase 25, ShellGuard introduced the Habitat ZIP Engine, enabling a truly portable, zero-knowledge, streaming full-archive packaging solution.
Streamed ZIP Generation β
To ensure a strict $O(\text{largest single file})$ bounded memory ceiling, Habitat export bypasses massive ArrayBuffer allocations. The generation relies on the client-zip web stream capability, lazily decrypting one attachment at a time directly to the browser's download manager.
Path Safety & Structure β
The archive contains an embedded manifest (shellguard_vault_export.json) that maps attachments dynamically. The file hierarchy is deterministically organized while stripping out potentially dangerous characters like ../ to prevent path traversal on ingestion:
attachments/<pod>/<item_title>__[<id_short>]/<file_name>ClawKey Challenge Gate β
Full decrypted backup generation requires explicit confirmation of the user's hu- ClawKey to guarantee malicious JavaScript payloads cannot silently dump the vault in the background.
π Two-Stage Habitat Ingestion Pipeline β
Importing large archives with dozens of encrypted attachments can traditionally freeze browser tabs. ShellGuard breaks this bottleneck with a Two-Stage Ingestion Pipeline:
- Stage 1 (Instant Vault Ingestion, <2s): Dropping a
.zipfile onto the Abyssal Dropzone triggerssniffHabitatArchive(). Usingfflate, the client extracts onlyshellguard_vault_export.jsonwithout decompressing binary attachments into memory. A Batch Import Preview modal displays item counts and attachment metrics. Upon user confirmation, primary items are committed atomically viaPOST /api/vault/bulk-importin under 2 seconds. The modal closes and the vault is immediately unlocked. - Stage 2 (Non-Blocking Abyssal Ingestion Dock): Binary attachment payloads are handed off to the persistent, floating
AbyssalIngestionDockanchored inVaultShell.tsx. Attachments stream in the background via sequential multipart uploads (POST /api/attachments), allowing the user to continue searching, editing, and using their vault uninterrupted. - Reactive Status Tracking: Vault items with in-flight uploads display glowing pulsing chips (
π filename (Uploading 45%...)) that transition reactively toπ filename (Verified)upon completion without requiring a page reload. - Lifecycle Protection: A
beforeunloadlistener warns the user if they attempt to navigate away while background uploads are active.
β³ Import Lifecycle Tracking & Ephemeral Quarantine β
In Phase 26, ShellGuard introduced the Import Lifecycle & Quarantine Engine, providing safety, traceability, and atomic rollback for newly migrated items:
1. Batch Stamping (imp_<uuid>) & Atomic Auditability β
Every execution of POST /api/vault/bulk-import dynamically generates a batch identifier (imp_ + UUIDv4) and stamps both import_batch_id and imported_at (ISO 8601 UTC) across all inserted pearls, notes, and SSH keys within the same database transaction.
2. Auto-Graduation on Edit β
When any quarantined item is edited by the user via PUT /api/vault/:id, PUT /api/notes/:id, or PUT /api/keys/:id, the system automatically clears import_batch_id and imported_at to NULL. The act of intentional user modification signals explicit trust, graduating the record into permanent vault status.
3. Ephemeral Quarantine & Progressive Disclosure β
Quarantined items feature bioluminescent countdown badges in the item list and an inline Quarantine Info card in the detail pane. To prevent UI clutter, quarantine filters and action bars follow strict progressive disclosure:
- If no quarantined records exist, zero quarantine filter chips or batch action bars are rendered.
- If ungraduated imported records exist, a dynamic Quarantined (N) filter chip appears in the list header, and a centered Floating Batch Action Bar surfaces when filtering to quarantined items.
4. Atomic Rollback & Attachment Cascade β
If an import introduces duplicate or unwanted credentials, users can click Revert Import from the Settings view, detail pane, or the centered floating batch action bar. Reversion:
- Cancels active in-flight uploads in the
globalIngestionQueue. - Issues
DELETE /api/vault/import-batches/:id. - Transactionally deletes all linked records and cascades to any associated binary attachments in
vault_secure_attachments. - Records an auditable
IMPORT_BATCH_REVERTEDsecurity event inaudit_logs.