This document describes ID Wispera's security architecture and threat model.

ID Wispera is designed with security-first principles:

• Local-first: Credentials never leave your machine unless explicitly shared
• Zero-knowledge: Sharing uses client-side encryption
• Audit everything: Complete visibility into credential usage
• Policy enforcement: Declarative rules prevent unauthorized access

• Algorithm: AES-256-GCM
• Key Derivation: PBKDF2 with SHA-256 (100,000 iterations)
• Salt: 32 bytes, randomly generated per vault
• IV: 12 bytes, randomly generated per encryption operation

Master Passphrase → PBKDF2(passphrase, salt, 100000, SHA-256) → 256-bit key

The vault file contains:

• Version number (unencrypted)
• Salt (unencrypted, needed for key derivation)
• IV (unencrypted, needed for decryption)
• Encrypted passport data
• Encrypted audit log
• Metadata (unencrypted: creation time, passport count)

Share links use:

• Fresh AES-256-GCM key per share
• Key sent separately from encrypted payload
• Optional time and view limits

ID Wispera supports multiple authentication modes to unlock the vault. All modes derive the same AES-256-GCM decryption key; they differ only in how the passphrase is supplied.

In Passphrase Mode, the master passphrase is resolved through the PassphraseProvider chain, which is evaluated in order:

1. IDW_SESSION_TOKEN environment variable -- If set, the token is used to look up and decrypt the passphrase from the sidecar file (~/.id-wispera/sessions.json). This is the recommended path for CI/headless environments.
2. OS keychain -- On macOS (Keychain), Linux (libsecret/kwallet), and Windows (Credential Manager), the passphrase is retrieved from the system keychain. This is the recommended path for interactive developer use.
3. IDW_PASSPHRASE environment variable or .env file -- If the IDW_PASSPHRASE environment variable is set, its value is used directly. Otherwise the provider checks $CWD/.env and ~/.id-wispera/.env for the key. Only IDW_PASSPHRASE is read from the file; no other variables are loaded. A warning is emitted if the .env file is world-readable. This mode is useful for local development in environments without an OS keychain (containers, WSL, minimal Linux). For best security, restrict file permissions: chmod 600 .env.
4. Interactive prompt -- If none of the above succeed, the CLI prompts the user for their passphrase via a secure TTY prompt (stdin is not echoed).

Store your passphrase in the OS keychain with:

idw auth login

Check current authentication status:

idw auth status

Remove the keychain entry:

idw auth logout

Session tokens allow non-interactive vault access without exposing the master passphrase. Tokens are stored in the sidecar file at ~/.id-wispera/sessions.json, encrypted with PBKDF2 + AES-256-GCM (separate from the vault encryption).

Create a session token:

idw auth token create --name "github-actions" --expires 90d

The command prints a token string (idwst_...). Store it as a CI secret and set IDW_SESSION_TOKEN in the runner environment.

List active tokens:

idw auth token list

Revoke a token:

idw auth token revoke --name "github-actions"

The sidecar file (sessions.json) contains an encrypted mapping from token IDs to vault passphrases. Each entry is independently encrypted with PBKDF2 + AES-256-GCM using the token value as input key material. Compromising one token does not reveal other sessions. The sidecar file is permission-locked to 600 and excluded from vault backups.

1. Credential Theft

   • Encrypted at rest
   • Memory cleared after lock
   • No plaintext in logs

2. Unauthorized Access

   • Passphrase required
   • Policy enforcement
   • Audit trail

3. Credential Misuse

   • Scope limitations
   • Expiration enforcement
   • Revocation capability

4. Audit Trail Tampering

   • Append-only log
   • Encrypted with vault

5. Accidental Exposure

   • Credential detection
   • Masked display
   • .gitignore templates

1. Compromised Master Passphrase

   • Use a strong, unique passphrase
   • Consider a password manager

2. Compromised Machine

   • If your machine is compromised, credentials may be extracted
   • Use full-disk encryption

3. Memory Attacks

   • Credentials exist in memory while in use
   • Consider hardware security modules for high-security needs

4. Social Engineering

   • Train users on security awareness

5. Session Token Environment Variable Exposure

   • When IDW_SESSION_TOKEN is set in a CI runner, any process on the same machine can read it from /proc/<pid>/environ or equivalent
   • Limit token scope and expiry to reduce blast radius
   • Prefer short-lived tokens and revoke them after use

6. IDW_PASSPHRASE Environment Variable Exposure

   • When IDW_PASSPHRASE is set in the process environment, any process that can inspect the environment can read it
   • Prefer a .env file with restricted permissions (chmod 600) over exporting the variable in your shell profile
   • For higher security, use the OS keychain (interactive) or session tokens (CI)

• Minimum 12 characters recommended
• Mix of character types
• Unique to ID Wispera
• Store in a password manager or the OS keychain (idw auth login)
• Never commit to version control
• When using IDW_PASSPHRASE, prefer a .env file with chmod 600 over exporting in your shell profile

• Create short-lived, named tokens: idw auth token create --name "ci-deploy" --expires 7d
• Revoke tokens immediately when a CI pipeline is decommissioned
• Store tokens in your CI platform's secrets manager (e.g., GitHub Actions secrets, GitLab CI variables)
• Rotate tokens on a regular schedule
• Audit active tokens with idw auth token list

• Store on encrypted filesystem
• Regular backups (encrypted)
• Limit file permissions: chmod 600 vault.json
• Don't share the vault file directly

• Set expiration dates
• Rotate credentials regularly
• Revoke unused credentials
• Use minimum required scope
• Tag for organization

• Review audit logs regularly
• Monitor for suspicious activity
• Keep ID Wispera updated
• Use MCP server for agent access (not direct vault access)

ID Wispera can detect exposed credentials:

idw scan ./project

Detects:

• API keys (OpenAI, AWS, GitHub, etc.)
• JWTs
• Private keys
• Connection strings
• Generic secrets

Rules automatically enforced:

• Human owner required
• Maximum validity period
• Delegation depth limits
• Visa type restrictions

Every action is logged:

• Creation, access, modification
• Who performed the action
• When it occurred
• From which platform
• With what purpose

Zero-knowledge sharing:

• Client-side encryption
• Key never sent with payload
• Time and view limits
• Scope restrictions (full, read-only, metadata-only)

The audit log supports compliance requirements:

• Complete access history
• Actor identification
• Timestamp with timezone
• Platform and purpose tracking
• Export to CSV/JSON

ID Wispera is local-first:

• Credentials stored locally
• No cloud sync required
• Optional self-hosted sync
• Audit logs stay local

Policy engine supports:

• Role-based restrictions via tags
• Time-based access
• Approval workflows
• Delegation limits

1. Immediately revoke the credential:

   idw revoke <passport-id> --reason "Exposed in [location]"

2. Review audit log:

   idw audit <passport-id>

3. Rotate the credential at the source

4. Create new passport with fresh credential

1. Generate new credentials at all sources
2. Create a new vault
3. Import fresh credentials
4. Delete old vault securely

1. Review audit log for anomalies
2. Check for unauthorized access patterns
3. Verify delegation chains
4. Revoke suspicious passports
5. Notify affected parties

If you discover a security vulnerability:

1. Do not open a public issue
2. Email: security@id-wispera.ai
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
4. Allow time for a fix before disclosure