lunarfront-app/planning/27_Vault_Password_Manager.md

Music Store Management Platform

Vault — On-Premise Password Manager

Version 1.0 | Draft

1. Overview

LunarFront includes a built-in password vault for on-premise deployments. Music stores deal with dozens of credentials — supplier portals, distributor accounts, payment processor dashboards, shipping services, insurance logins, ASCAP/BMI licensing portals — and most store owners are not technical enough to adopt a separate password manager.

The vault is a simple, encrypted credential store baked into LunarFront. It encrypts all secrets at rest using AES-256-GCM with a key derived from a master passphrase. The key exists only in server memory and is discarded on restart.

On-premise only. Cloud/hosted deployments would require a more sophisticated key management approach (HSM, envelope encryption) and are out of scope for this design.

2. Security Model

2.1 Encryption

• Algorithm: AES-256-GCM (authenticated encryption)
• Key derivation: PBKDF2 or Argon2id from master passphrase + stored salt
• Each entry encrypted individually (not a single encrypted blob)
• Each entry gets its own random IV/nonce
• Encrypted fields: username, password, notes
• Plaintext fields: entry name, URL, category, tags (searchable)

2.2 Key Lifecycle

1. First-time setup: Admin sets master passphrase via the admin UI. System generates a random salt, derives the encryption key, encrypts a known verification string, and stores the salt + verification ciphertext in the database.
2. Server start: Vault is locked. Encryption key is not in memory. All vault API endpoints return 423 Locked.
3. Unlock: Admin enters master passphrase via the UI. System re-derives the key using the stored salt, verifies it against the verification ciphertext. If correct, key is held in memory. Vault endpoints become functional.
4. Server restart: Key is lost. Vault returns to locked state.
5. Lock (manual): Admin can lock the vault without restarting. Key is wiped from memory.

2.3 What's Encrypted vs. Plaintext

Field	Storage	Reason
name	Plaintext	Searchable, displayed in list
url	Plaintext	Searchable, displayed in list
category	Plaintext	Filterable
username	Encrypted	Credential
password	Encrypted	Credential
notes	Encrypted	May contain secrets
created_at	Plaintext	Metadata
updated_at	Plaintext	Metadata
created_by	Plaintext	Audit

2.4 Development Mode

In development, support a VAULT_PASSPHRASE environment variable to auto-unlock on startup. This avoids blocking the dev workflow. Never use this in production.

3. Database Schema

3.1 vault_config

Stores the salt and verification data. One row per company.

vault_config
  id              uuid PK
  company_id      uuid FK → company
  salt            bytea          -- random salt for key derivation
  verification    bytea          -- encrypted known string for passphrase verification
  kdf_algorithm   varchar(20)    -- 'argon2id' or 'pbkdf2'
  kdf_iterations  integer        -- iteration count / cost parameter
  created_at      timestamptz
  updated_at      timestamptz

3.2 vault_entry

Individual credential entries.

vault_entry
  id              uuid PK
  company_id      uuid FK → company
  name            varchar(255)   -- plaintext, searchable
  url             varchar(500)   -- plaintext, searchable
  category        varchar(100)   -- plaintext, filterable
  username_enc    bytea          -- AES-256-GCM encrypted
  username_iv     bytea          -- nonce for username
  password_enc    bytea          -- AES-256-GCM encrypted
  password_iv     bytea          -- nonce for password
  notes_enc       bytea          -- AES-256-GCM encrypted (nullable)
  notes_iv        bytea          -- nonce for notes (nullable)
  created_by      uuid FK → user
  updated_by      uuid FK → user
  created_at      timestamptz
  updated_at      timestamptz

3.3 vault_access_log

Append-only audit trail for credential access.

vault_access_log
  id              uuid PK
  company_id      uuid FK → company
  entry_id        uuid FK → vault_entry
  user_id         uuid FK → user
  action          varchar(20)    -- 'view', 'copy', 'create', 'update', 'delete'
  field           varchar(20)    -- 'password', 'username', 'notes' (for view/copy)
  ip_address      varchar(45)
  created_at      timestamptz

4. API Endpoints

All vault endpoints are prefixed with /v1/vault.

4.1 Vault Status & Management

Method	Path	Permission	Description
GET	/vault/status	Any authenticated	Returns { locked: bool, initialized: bool }
POST	/vault/initialize	vault.admin	Set master passphrase (first time only)
POST	/vault/unlock	vault.admin	Unlock vault with passphrase
POST	/vault/lock	vault.admin	Lock vault (wipe key from memory)
POST	/vault/change-passphrase	vault.admin	Change master passphrase (re-encrypts all entries)

4.2 Entries

All return 423 Locked when vault is locked.

Method	Path	Permission	Description
GET	/vault/entries	vault.view	List entries (paginated, name/url/category only)
POST	/vault/entries	vault.edit	Create entry
GET	/vault/entries/:id	vault.view	Get entry (decrypts username, password, notes)
PATCH	/vault/entries/:id	vault.edit	Update entry
DELETE	/vault/entries/:id	vault.edit	Delete entry
POST	/vault/entries/:id/copy	vault.view	Log that user copied a credential

4.3 Audit

Method	Path	Permission	Description
GET	/vault/audit	vault.admin	Access log (paginated, filterable by user/entry)

4.4 Locked Response

When vault is locked, all entry/audit endpoints return:

{
  "error": {
    "message": "Vault is locked",
    "statusCode": 423
  }
}

5. Permissions

New permission domain: vault

Slug	Description
vault.view	View entry list, decrypt and view credentials
vault.edit	Create, update, delete entries
vault.admin	Initialize, unlock, lock, change passphrase, view audit log

Permission inheritance: vault.admin → vault.edit → vault.view

Default role assignments:

• Admin: vault.admin
• Manager: vault.edit
• All others: No vault access by default

6. Frontend

6.1 Sidebar

New "Vault" item in the Admin section (visible only with vault.view). Shows a lock icon when locked.

6.2 Pages

Vault List Page

• Search by name/URL
• Filter by category
• Table columns: Name, URL, Category, Updated
• Click row to view details
• "New Entry" button (requires vault.edit)

Vault Entry Detail

• Shows name, URL, category
• Username field with copy button (masked by default, click to reveal)
• Password field with copy button (masked by default, click to reveal)
• Notes (hidden by default, click to reveal)
• Edit/Delete buttons (requires vault.edit)
• Every reveal/copy action is logged

Vault Locked Page

• Shown when navigating to vault and it's locked
• Passphrase input + "Unlock" button (requires vault.admin)
• If not initialized: "Set Master Passphrase" flow with confirmation input

Vault Setup (First Time)

• Enter master passphrase (min 16 characters)
• Confirm passphrase
• Warning: "This passphrase cannot be recovered. If lost, all vault entries are permanently inaccessible."

6.3 UI Behaviors

• Password fields use type="password" with a toggle eye icon
• Copy-to-clipboard auto-clears after 30 seconds
• Toast notification on copy: "Password copied — clipboard will clear in 30s"
• Reveal auto-hides after 30 seconds
• No browser autocomplete on vault forms (autocomplete="off")

7. Operational Considerations

7.1 Passphrase Recovery

There is no recovery mechanism by design. If the master passphrase is lost, all encrypted entries are permanently inaccessible. The vault_config and vault_entry rows can be deleted to start fresh, but the old data is gone.

Document this clearly in the UI and in the setup flow.

7.2 Backup

Database backups include encrypted vault data. Without the master passphrase, the encrypted fields are useless. This is the correct behavior — a stolen backup should not expose credentials.

7.3 Passphrase Change

Changing the master passphrase requires:

1. Verify old passphrase
2. Derive new key from new passphrase + new salt
3. Decrypt every entry with old key, re-encrypt with new key (transaction)
4. Update vault_config with new salt + verification
5. Replace in-memory key

This is an expensive operation (scales with entry count) but should be rare.

7.4 Server Restart Behavior

After restart:

• Vault status: locked
• All vault API calls: 423
• Everything else in LunarFront: fully functional
• Admin unlocks when ready — no urgency, no data loss

7.5 Multiple Servers

If running multiple backend instances behind a load balancer, each instance needs to be unlocked independently (since the key is in-process memory). For multi-instance deployments, consider a shared unlock via Redis (store the derived key in Valkey with a TTL matching the server session). This is an optional enhancement — most on-prem music stores run a single instance.

8. Categories (Defaults)

Pre-populated categories that stores can customize:

• Suppliers
• Distributors
• Payment Processing
• Shipping & Freight
• Insurance
• Licensing (ASCAP, BMI, SESAC)
• Banking
• Software & Services
• Utilities
• Social Media
• Website & Hosting
• Other

9. Implementation Order

1. Database schema + migration
2. Encryption service (encrypt, decrypt, key derivation, verification)
3. Vault status/initialize/unlock/lock endpoints
4. Entry CRUD endpoints
5. Audit logging
6. Add vault.* permissions to RBAC seed
7. Frontend: locked page + unlock flow
8. Frontend: entry list + detail + create/edit
9. Frontend: audit log page
10. Tests: encryption unit tests, API integration tests