Keychain

OS keychain abstraction with encrypted-file fallback — stores / retrieves / removes a (service, account) -> password binding via the host operating system's native credential store. Operators reach for this from CLI bootstraps that need to materialize a database password, outbound webhook secret, SMTP relay credential, etc., without baking the value into a config file or env var.

Backend dispatch: - macOS -> /usr/bin/security (add-/find-/delete-generic-password) - Linux -> secret-tool from libsecret; password on stdin so it never reaches /proc//cmdline - Windows -> PowerShell + the CredentialManager module; password on stdin via [Console]::In.ReadToEnd(). Falls through to the file backend when CredentialManager is absent - File -> XChaCha20-Poly1305-sealed JSON whose KEK is derived via Argon2id from opts.passphrase. Wrap format is shared with b.vault.wrap (magic 0xE2). File mode 0o600, atomic via b.atomicFile.write.

Process-list-safety: every native-tool invocation passes the password on stdin. macOS security is invoked with -w - (the documented stdin sentinel); secret-tool always reads from stdin; PowerShell scripts use [Console]::In.ReadToEnd(). The plaintext never crosses argv on any backend.

Validation tier: config-time / entry-point. Bad opts throw KeychainError synchronously; native-tool failures surface as KeychainError with the tool's stderr included.

Audit: every call emits one of keychain.stored / keychain.retrieved / keychain.removed (or the .failed sibling). Audit metadata records service / account / backend / outcome. The password value is never audited.

b.keychain.store(opts) #

{
  {
    service:       string,        // required, no NUL/CR/LF bytes
    account:       string,        // required, no NUL/CR/LF bytes
    password:      string,        // required, non-empty
    fallbackFile?: string,        // absolute path; required if file fallback may engage
    passphrase?:   string,        // required when fallbackFile engages (Argon2id-derived KEK)
    preferFile?:   boolean,       // default: false
    audit?:        boolean,       // default: true (emits keychain.stored)
  }
}

Persist a (service, account) -> password binding to the platform's native credential store, falling back to an encrypted file when no native backend is reachable. The password crosses to the native tool on stdin so it never appears in /proc//cmdline or ps. Resolves to { stored: true, backend } on success. Bad opts throw KeychainError synchronously.

Set preferFile: true to skip native backend probing entirely (for deterministic CI / disposable container deployments).

await b.keychain.store({
  service:      "blamejs/db",
  account:      "primary",
  password:     "s3cr3t",
  fallbackFile: "/var/lib/blamejs/keychain.enc",
  passphrase:   process.env.BLAMEJS_KEYCHAIN_PASSPHRASE,
});
// → { stored: true, backend: "macos-security" }

b.keychain.retrieve(opts) #

{
  {
    service:       string,        // required
    account:       string,        // required
    fallbackFile?: string,        // absolute path; required for file-backend lookup
    passphrase?:   string,        // required when fallbackFile engages
    preferFile?:   boolean,       // default: false
    audit?:        boolean,       // default: true (emits keychain.retrieved)
  }
}

Look up the password for (service, account) from the native credential store, falling back to the encrypted file when the native store has no entry or no native backend is reachable. Resolves to { password, backend } on a hit, null on a clean miss. Native-tool failures surface as KeychainError with the tool's stderr included.

var got = await b.keychain.retrieve({
  service:      "blamejs/db",
  account:      "primary",
  fallbackFile: "/var/lib/blamejs/keychain.enc",
  passphrase:   process.env.BLAMEJS_KEYCHAIN_PASSPHRASE,
});
// → { password: "s3cr3t", backend: "macos-security" }  // or null on miss

b.keychain.remove(opts) #

{
  {
    service:       string,        // required
    account:       string,        // required
    fallbackFile?: string,        // absolute path; required for file-backend cleanup
    passphrase?:   string,        // required when fallbackFile engages
    preferFile?:   boolean,       // default: false
    audit?:        boolean,       // default: true (emits keychain.removed)
  }
}

Delete the (service, account) binding from both the native credential store (when reachable) and the encrypted file fallback (when fallbackFile is supplied). Resolves to true when at least one backend held the binding, false on a no-op. The double-sweep matters because a binding may have been stored on a prior boot under a different backend than the current host advertises.

var existed = await b.keychain.remove({
  service:      "blamejs/db",
  account:      "primary",
  fallbackFile: "/var/lib/blamejs/keychain.enc",
  passphrase:   process.env.BLAMEJS_KEYCHAIN_PASSPHRASE,
});
// → true

Last updated 2026-08-08T16:39:49.652Z by seeder.