Skip to main content

​
Authentication

ID Wispera supports multiple vault authentication modes. All ultimately derive the same AES-256-GCM encryption key — they differ only in how the passphrase is resolved.

​
Passphrase Resolution Chain

The passphrase is resolved through a 4-step priority chain. The first successful method wins: 
1. Session token      (IDW_SESSION_TOKEN env var → sidecar file lookup)
2. OS Keychain        (macOS Keychain, Windows Credential Manager, Linux Secret Service)
3. IDW_PASSPHRASE     (environment variable or .env file)
4. Interactive prompt  (masked terminal input, CLI environments only)

​
PassphraseSource values

Each SDK returns a PassphraseResult with a source field indicating how the passphrase was resolved:
SourceMeaning
session-tokenResolved from IDW_SESSION_TOKEN via sidecar file
keychainRetrieved from OS keychain
env-varRead from IDW_PASSPHRASE process environment variable
dotenv-fileRead from a .env file ($CWD/.env or ~/.id-wispera/.env)
interactiveUser entered via TTY prompt

​
Authentication Modes

​
Session Token Mode (CI / Headless)

For CI pipelines and headless environments where a keychain is unavailable. Session tokens wrap the passphrase using Scrypt + AES-256-GCM and are stored in a sidecar file (~/.id-wispera/sessions.json). Session tokens provide headless vault access without storing the passphrase in plaintext. A token is generated via idw auth token create, which encrypts your vault passphrase with a key derived from the token itself (Scrypt + AES-256-GCM). The encrypted passphrase is stored in a sidecar file (~/.id-wispera/sessions.json). At runtime, the token is used to decrypt the passphrase in memory — the passphrase is never written to disk or environment. Create a session token: 
idw auth token create --label "ci-pipeline" --expires 24h
Supported durations: 24h, 7d, 30d. Use the token in CI: 
export IDW_SESSION_TOKEN="idwst_..."
idw list  # vault unlocks automatically via session token
Manage session tokens: 
# List active tokens
idw auth token list

# Revoke a token by hash prefix
idw auth token revoke abc123
The passphrase is always the root recovery path. The session token sidecar (sessions.json) is a convenience layer, never a dependency. If you lose all session tokens, the passphrase still unlocks the vault.

​
Session Token Sidecar Format

The ~/.id-wispera/sessions.json file uses a cross-SDK compatible schema:
FieldFormat
Token hashHex-encoded SHA-256
SaltHex-encoded
IVHex-encoded
Encrypted passphraseBase64url
Created / ExpiresISO 8601
LabelFree-text string
All three SDKs (TypeScript, Python, Go) read and write this format interchangeably.

​
Keychain Mode (Default for Local Development)

The recommended mode for interactive local development. The passphrase is stored in and resolved from the OS keychain: 
idw auth login
You will be prompted for your passphrase. It is stored in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) and retrieved automatically on subsequent operations. To remove the passphrase from the keychain: 
idw auth logout

​
IDW_PASSPHRASE (Environment Variable and .env File)

IDW_PASSPHRASE is a fully supported authentication method. If the IDW_PASSPHRASE environment variable is set, its value is used directly. Otherwise the provider checks $CWD/.env and then ~/.id-wispera/.env for the key. This mode is useful for local development in environments without an OS keychain (containers, WSL, minimal Linux). Environment variable: 
export IDW_PASSPHRASE="my-vault-passphrase"
idw list  # vault unlocks automatically
.env file: 
# .env file in project root or ~/.id-wispera/.env
# Comments are ignored
# Only IDW_PASSPHRASE is read — all other variables are skipped
IDW_PASSPHRASE=my-vault-passphrase

# Quoted values are supported (quotes are stripped)
IDW_PASSPHRASE="my-vault-passphrase"
IDW_PASSPHRASE='my-vault-passphrase'
Only IDW_PASSPHRASE is read from the .env file. No other variables are loaded into the process environment.
A warning is emitted to stderr if the .env file is world-readable (has the other-read permission bit set). For best security, restrict file permissions: chmod 600 .env.
Security best practices for IDW_PASSPHRASE:
  • Prefer a .env file with chmod 600 over exporting IDW_PASSPHRASE in your shell profile
  • The .env file is never loaded into the full process environment — only the IDW_PASSPHRASE value is extracted
  • For higher security, use the OS keychain (interactive) or session tokens (CI)

​
Interactive Prompt

If none of the above methods succeed, the CLI prompts for the passphrase via a secure TTY prompt (stdin is not echoed). This mode is disabled in headless environments (MCP server, CI).

​
Auth Status

Check the current authentication state and how the passphrase was resolved: 
idw auth status
Example output: 
Auth mode:    passphrase
Source:       os-keychain
Vault:        ~/.id-wispera/vault.json
Session tokens: 2 active (1 expiring in 3h)

​
Admin Passports

Provider admin credentials (AWS access keys, OpenAI admin keys, etc.) are now stored as encrypted passports inside the vault instead of plaintext environment variables. Each admin passport has:
  • Visa type: privilege
  • Tags: admin, admin:<provider>, provisioning

​
Bootstrap Wizard

The idw auth bootstrap command is an interactive wizard that collects your provider admin credentials and stores them as encrypted admin passports: 
idw auth bootstrap
The wizard prompts for each provider’s admin credentials and creates passports with the correct visa type, tags, and platform metadata.

​
Vault-Resolved Provisioning Auth

The provisionAndCreatePassport() function now optionally resolves auth from the vault when the auth parameter is omitted. It looks up admin passports by matching the admin:<provider> tag: 
import { provisionAndCreatePassport } from '@id-wispera/core';

// Auth resolved from vault — no explicit auth parameter
const { credential, passport } = await provisionAndCreatePassport(vault, {
  provider: 'openai',
  name: 'Coding Agent Key',
  humanOwner: 'alice@company.com',
  config: { provider: 'openai', organizationId: 'org-abc123', keyType: 'service-account' },
  tags: ['production', 'coding-agent'],
});
Run idw auth bootstrap once to set up admin passports, then all subsequent provisioning calls can resolve auth automatically from the vault.

​
Cross-SDK Parity

The auth module exists in all three SDKs with identical behavior:
SDKPackageKeychainCrypto
TypeScriptpackages/core/src/auth/keytar (optional)Web Crypto API (SubtleCrypto)
Pythonpackages/python/id_wispera/auth/keyring (optional)cryptography library
Gopackages/go/pkg/auth/Stub (go-keyring not yet wired)golang.org/x/crypto
All three SDKs implement:
  • Same 4-step resolution chain in the same order
  • Same .env file parser (comments, quote stripping, only reads IDW_PASSPHRASE)
  • Same world-readable file warning format
  • Same PassphraseSource values
  • Same PassphraseProviderOptions configuration (allowInteractive, allowEnvVar, promptFn, sidecarPath)

​
CLI Reference

CommandDescription
idw auth loginAuthenticate and store passphrase in OS keychain
idw auth logoutRemove passphrase from keychain
idw auth statusShow current auth state and source
idw auth token create [--label <name>] [--expires <duration>]Create a session token
idw auth token listList active session tokens
idw auth token revoke <hash-prefix>Revoke a session token
idw auth bootstrapInteractive wizard to set up admin passports

​
Next Steps

Credential injection

Use idw exec to inject vault credentials into subprocesses as environment variables.

Provisioning

Programmatically create API keys using vault-stored admin credentials.

Security architecture

Encryption model, session token design, and threat model.