​

Security Architecture

​

Overview

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

​

Encryption

​

Vault Encryption

​

Key Derivation

Master Passphrase
  → Scrypt(passphrase, salt, N=16384, r=8, p=1)
  → 256-bit AES key

​

At-Rest Encryption

​

In-Transit Encryption (Sharing)

• A fresh AES-256-GCM key generated per share
• The key is sent separately from the encrypted payload
• Optional time-based and view-count limits

​

Session Token Sidecar

​

Design Constraints

• Passphrase is always root recovery. The sidecar is a convenience layer, never a dependency. If all session tokens are lost, the passphrase still unlocks the vault.
• Tokens are scoped and time-limited. Each token has a label, creation time, and expiry (24h, 7d, or 30d). Expired tokens are ignored.
• Tokens are individually revocable. Revoking a token removes it from the sidecar. Other tokens and the passphrase are unaffected.
• Cross-SDK compatible. The sidecar uses hex-encoded hashes/salt/IV, base64url encrypted passphrase, and ISO 8601 dates — readable by all three SDKs.

​

Admin Passports

​

Credential Injection (idw exec)

• Credentials exist only in the child process environment, never the parent shell
• IDW_PASSPHRASE and IDW_SESSION_TOKEN are automatically stripped from child environments
• No shell expansion — direct process spawning with array arguments
• Credential values never appear in error messages
• Policy engine is evaluated before any credential is injected
• Complete audit trail with process-level metadata (command, PID, exit code, duration)

​

Threat Model

​

What We Protect Against

1. Credential Theft — Encrypted at rest, memory cleared after lock, no plaintext in logs or environment variables.
2. Unauthorized Access — Passphrase required (via keychain, prompt, or session token), 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, post-import plaintext deletion warnings.

​

What We Don’t Protect Against

1. Compromised Master Passphrase — If an attacker obtains your passphrase, they can decrypt the vault.
2. Compromised Machine — A fully compromised machine gives an attacker access to everything the user can access.
3. Memory Attacks — Sophisticated memory-forensics attacks may recover decrypted data from RAM.
4. Social Engineering — ID Wispera cannot prevent a user from being tricked into sharing credentials.

​

Security Best Practices

​

Passphrase Security

• Minimum 12 characters recommended
• Mix of character types (uppercase, lowercase, digits, symbols)
• Unique to ID Wispera — do not reuse passwords
• Use idw auth login to store the passphrase in your OS keychain
• For CI, use session tokens (idw auth token create); for containers and WSL, use IDW_PASSPHRASE via a .env file with chmod 600
• Never commit to version control

​

Vault Security

• Store on an encrypted filesystem
• Maintain regular backups (the backup is already encrypted)
• Limit file permissions:

chmod 600 vault.json

• Do not share the vault file directly — use the secure sharing workflow instead

​

Credential Hygiene

• Set expiration dates on all passports
• Rotate credentials regularly
• Revoke unused credentials promptly
• Use the minimum required scope
• Tag credentials for organization

​

Operational Security

• Review audit logs regularly
• Monitor for suspicious activity
• Keep ID Wispera updated to the latest version
• Use the MCP server for agent access instead of exposing credentials directly

​

Security Features

​

Credential Detection

​

Policy Enforcement

• Human owner requirements
• Maximum validity periods
• Delegation depth limits
• Visa type restrictions

​

Secure Sharing

• Zero-knowledge, client-side encryption
• Time-limited and view-limited share links
• No plaintext credentials on the server

​

Reporting Security Issues

• A description of the vulnerability
• Steps to reproduce
• Potential impact assessment

​

Next steps