credstore

Cross-platform credential storage — OS keyring with AES-encrypted file backup.

A standalone secret manager that ships with Slife but has no dependency on it. Depends only on keyring, keyring-wincred, and keyrings-cryptfile.

Supports Windows, macOS, Linux (desktop + headless), and WSL (Windows Credential Manager via PowerShell bridge).

Install

pip install credstore
# or bundled with Slife:
uv tool install git+https://github.com/juzcn/slife.git

Verify: credstore status

No configuration needed. Run credstore set-password to enable encrypted backup.

CLI

Setup

credstore set-password    # creates ~/.credstore/credentials.crypt

Path overridable via CREDSTORE_FILE env var or credstore.json5.

Commands

¹ Master password required only if cryptfile exists.

get Modes

-p mode performs a dual-query consistency check:

• Both stores have the value AND they match → prints plaintext
• One store missing → error with recovery instructions
• Values differ → error, tells you which tool to run

inject / uninject

inject reads a secret from the keyring and persists it to the system environment:

When stdout is a TTY, inject prints an activation hint instead of the secret. The actual export command only flows through a pipe.

eval "$(credstore inject DEEPSEEK_API_KEY)"           # Bash/Zsh — activate now
Invoke-Expression (credstore inject DEEPSEEK_API_KEY)  # PowerShell — activate now

uninject reverses the operation — removes from registry or profile and prints the unset command.

list Output

  KEY                  SYSTEM KEYRING   CRYPTFILE        ENV    STATUS
  ────────             ──────────────   ──────────────   ────   ──────
  ANTHROPIC_API_KEY    ✔                ✔                —      synced
  DEEPSEEK_API_KEY     ✔                ✔                ✔      synced
  OPENAI_API_KEY       —                ✔                —      cryptfile only
  ────────             ──────────────   ──────────────   ────   ──────
  3 credential(s) — synced: 2, cryptfile only: 1, env: 1

Memory Safety

Secrets are immutable Python str objects — they cannot be zeroed in place. Mitigations:

1. Never batch-load — list collects only key names. Sync comparison fetches one value at a time and immediately dels it.
2. Prefer existence checks — exists_credential() / list_credential_keys() never retrieve secret content.
3. Explicit cleanup — every CLI handler dels secret references on all exit paths including error branches.

masked_input() echoes * per keystroke — paste works, actual value never displayed.

Python API

import credstore

# Read / check / delete (system keyring only, no prompt)
credstore.get_credential("myapp/api_key")      # → str | None
credstore.exists_credential("myapp/api_key")   # → bool  (NEVER returns secret)
credstore.list_credential_keys()               # → list[str]  (NEVER returns values)
credstore.set_credential("myapp/api_key", "sk-…")
credstore.delete_credential("myapp/api_key")   # → bool

# keyring: URI resolution
credstore.is_keyring_uri("keyring:myapp/k")    # → True
credstore.resolve_uri("keyring:myapp/k")       # → the secret value (or KeyError)
credstore.parse_keyring_uri("keyring:srv/k")   # → ("srv", "k") | None

# Shell formatting
credstore.format_export("KEY", "secret", "bash")   # → "export KEY='secret'"
credstore.format_unset("KEY", "bash")              # → "unset KEY"

# Diagnostics
credstore.check_backend()      # → {"available": True, "backend": "…", …}
credstore.get_backend_name()   # → "system keyring + cryptfile (dual-write)"

Python API talks to system keyring only — no master password, no prompt. Dual-write (keyring + cryptfile) is handled by the CLI.

Callers of get_credential() and resolve_uri() must del the returned value after use. Prefer exists_credential() when you only need to know if a credential exists.

Configuration

Optional credstore.json5 (searched at ./credstore.json5 then ~/.credstore/config.json5):

{
  // Override default cryptfile path
  cryptfile_path: "/custom/path/credentials.crypt",
}

Priority: CREDSTORE_FILE env var → credstore.json5 → ~/.credstore/credentials.crypt (or ./credentials.crypt in Slife dev mode).

Architecture

Backend Matrix

Credstore auto-selects the best available backend via keyring's priority system:

Dual-Write Flow

┌──────────────────────────────────────────────────┐
│  CLI (__main__.py)                               │
│  Interactive: masked_input(), master password     │
│  Atomic dual-write: cryptfile → keyring           │
│  Rollback on keyring failure                      │
├──────────────────────────────────────────────────┤
│  Python API (__init__.py)                        │
│  Programmatic: no prompt, system keyring only     │
├────────────────────┬─────────────────────────────┤
│  System Keyring    │  Cryptfile Backup           │
│  (primary)         │  (encrypted)                │
│  ────────────────  │  ───────────────────────    │
│  Win CredMan       │  keyrings.cryptfile         │
│  WSL (PowerShell)  │  AES-encrypted INI          │
│  macOS Keychain    │  Survives OS pw changes     │
│  Linux Secret Svc  │                             │
│  Linux keyutils    │                             │
└────────────────────┴─────────────────────────────┘

WSL Backend

On WSL, no Linux desktop keyring is available. WslBackend bridges to Windows Credential Manager by calling powershell.exe with embedded C# that P/Invokes advapi32.dll (CredReadW, CredWriteW, CredDeleteW). Priority 9.5 beats WinCredKeyring (9.0) when both are installed — our backend fixes target-format and encoding issues.

Keyutils Backend

On headless Linux (no D-Bus session), KeyutilsBackend stores credentials in the Linux kernel's persistent keyring (@p). Calls add_key and keyctl syscalls directly through ctypes — zero Python dependencies beyond stdlib. Each credential is a "user" key with description "credstore:<service>/<key>".

Credential Enumeration

credstore list reads keys from the OS credential store using platform-specific APIs:

Enumeration retrieves key names only — secret values are never batch-loaded. Sync comparison fetches one value at a time and immediately discards it.

License

MIT