Vault Sharing

Share your vault with other users using end-to-end encrypted ECDH key exchange.

Overview

Vault sharing allows you to securely share your password vault with trusted users. The sharing process uses ECDH (Elliptic-curve Diffie–Hellman) key exchange to ensure that vault keys are never transmitted in plaintext.

Commands

Share a Vault

# Share your vault with another user
pwm vault share <vault-name> <email>
 
# Example
pwm vault share default alice@example.com

When you share a vault:

The recipient's public key is fetched from the server
Your vault key is re-encrypted using ECDH with their public key
An invitation is created and sent to the recipient

List Shared Vaults

# List vaults shared with you
pwm vault list --shared
 
# Output
┌─────────────────────────────────────────────────────┐
│  Shared Vaults                                      │
├─────────────────────────────────────────────────────┤
│  📁 Team Passwords    Owner: bob@example.com        │
│     Role: write       Entries: 15                   │
│                                                     │
│  📁 Family Vault      Owner: alice@example.com      │
│     Role: read        Entries: 8                    │
└─────────────────────────────────────────────────────┘

Accept an Invitation

# List pending invitations
pwm vault invitations
 
# Accept an invitation
pwm vault accept <invitation-id>

Access Roles

Role	Permissions
`admin`	Full control: read, write, delete, share with others
`write`	Read and modify entries
`read`	View entries only

How It Works

ECDH Key Exchange

1. Alice wants to share vault with Bob
 
2. Alice's device:
   - Fetches Bob's public key from server
   - Generates shared secret: ECDH(Alice_private, Bob_public)
   - Wraps vault key with shared secret
   - Sends wrapped key to server
 
3. Bob's device:
   - Downloads wrapped key
   - Generates same shared secret: ECDH(Bob_private, Alice_public)
   - Unwraps vault key
   - Decrypts vault entries

Security Properties

Zero-knowledge: Server never sees plaintext vault key
Forward secrecy: Compromised keys don't expose past shares
End-to-end: Only Alice and Bob can decrypt shared content

Examples

Share with a Team Member

# Share your work vault with a colleague
pwm vault share work-passwords colleague@company.com
 
# Output
✓ Invitation sent to colleague@company.com
  Invitation ID: abc123...
  Status: pending

Work with Shared Vaults

# Switch to a shared vault
pwm vault use shared:bob@example.com:team-passwords
 
# List entries from shared vault
pwm entry list
 
# Add entry to shared vault (requires write permission)
pwm entry add

Revoke Access

# Revoke a user's access to your vault
pwm vault revoke <vault-name> <email>
 
# Example
pwm vault revoke default alice@example.com

Invitation States

State	Description
`pending`	Invitation sent, waiting for recipient
`accepted`	Recipient accepted and can access vault
`revoked`	Access has been revoked by owner
`expired`	Invitation expired (7 day default TTL)

Best Practices

Verify recipient email - Double-check the email address before sharing
Use appropriate roles - Grant minimum necessary permissions
Review shared access - Periodically audit who has access to your vaults
Revoke unused access - Remove access for users who no longer need it

Vault Commands - Full vault management
Security: ECDH Sharing - Technical details
API: Sharing - API endpoints