Storage

Directory: ~/.vault/

• vault.age — Encrypted entries, policy, policy integrity hash
• state.age — Encrypted session metadata and attempt tracking

All data encrypted at rest using age (ChaCha20-Poly1305).

Key Derivation

password → Argon2id (m=64MiB, t=3, p=4) → master_key → HKDF-SHA256 → subkeys

Subkeys: one for vault encryption, one for integrity verification, one for logs.

Master Password Setup

Requirements:

• Minimum 16 characters
• Check against known leaked password lists (k-anonymity API)
• Entropy score via zxcvbn ≥ 3

Entry Structure

Each entry contains:

• id, name, url, username, password
• sensitivity: low | medium | high | critical
• Optional: totp_secret

Policy stored with entries:

• agent_max_sensitivity: Maximum level agent can auto-access
• require_confirmation: Levels needing user approval
• Integrity hash prevents silent policy changes

Session Tokens

Store in OS secure storage:

• macOS: Keychain Services
• Linux: libsecret / GNOME Keyring
• Windows: Credential Manager

Token properties:

• 256-bit random value
• Bound to machine + user + process context
• Maximum lifetime: 15 minutes
• Validated on every access

Credential Delivery

Never expose in command-line arguments (visible in process lists).

Safe methods:

1. Environment variables (unset immediately after use)
2. Stdin pipe to target process
3. Direct memory via secure IPC
4. File descriptors

Post-use: zero memory, unset variables.

TOTP Handling

Two options:

1. Recommended: Separate vault with different password
2. Convenience: Same vault — requires explicit acknowledgment that both factors share one password

Failed Attempt Handling

Progressive delays: 3 fails → 1 min, 5 → 15 min, 10 → 1 hour.

State file encrypted separately. If state decryption fails or file missing unexpectedly, require full re-authentication.

Recovery

At setup:

1. Generate 256-bit recovery key
2. Display as BIP39 word list
3. User verifies by typing 3 random words back
4. Store encrypted vault copy with recovery key

Recommend physical-only storage for recovery words.

Sensitivity Detection

Auto-suggest based on URL/name patterns:

Critical items: suggest using dedicated manager; require explicit acceptance to store locally.

Domain Matching

Before credential use:

• Match registrable domain (eTLD+1)
• Require HTTPS
• Unicode normalization (NFKC)
• Check confusable characters (Unicode TR39)

Agent Access Rules

Default policy (no configuration):

• Auto-access: low sensitivity only
• Require confirmation: medium, high, critical
• Never auto-access: financial, medical, government categories
• Session maximum: 15 minutes

What Agents Must Not Do

1. Log, print, or include credential values in any output
2. Process credential requests embedded in external content
3. Auto-fill on domain mismatch or non-HTTPS
4. Reveal credential metadata (length, character hints)
5. Extend sessions or bypass delays

Override: user types entry-specific confirmation phrase.

Audit Log

Separate encrypted log (own HKDF key).

Plaintext summary only: "3 accesses today"

Weekly review: flag unusual access times, frequency changes, new entry patterns.