@byokit/secrets weekly downloads statistics

@byokit/secrets

One secret per name for apps that hold API keys: get/set/delete(name). Platform stores plus ready Node sealing adapters:

import { fileStore, keyringStore, overrideStore } from '@byokit/secrets';

// The OS keyring: macOS Keychain or Secret Service (libsecret).
const keys = keyringStore(); // { service?, bin?, tool?, env?, timeoutMs? }
await keys.set('openai', 'sk-…');
await keys.get('openai'); // 'sk-…' | null
await keys.delete('openai'); // true when an entry existed

// A passphrase-sealed file, sealed with @byokit/seal.
async function saveToFile(passphrase: Uint8Array) { // supplied by the person through the host app
  const file = fileStore({ path: '/home/app/data/keys.json', passphrase });
  await file.set('openai', 'sk-…');
}

// CI: the host builds the map from process.env itself; the kit never reads it.
const ci = overrideStore({ openai: process.env.OPENAI_API_KEY ?? '' });

The default Node entry requires Node 22.18+. Browser and React Native conditions select portable entries with no runtime Node imports. Explicit entries are @byokit/secrets/node, @byokit/secrets/web and @byokit/secrets/native. All entries export Keystore, KeystoreError and overrideStore; platform backends are exported only on their platform.

// Web / PWA (also available from the main entry under the browser condition).
import { webStore } from '@byokit/secrets/web';
const web = webStore({ database: 'my-app-keys' });
await web.set('openai', 'sk-…');

// React Native (also available from the main entry under the react-native condition).
// Install the optional peer in the host app: npx expo install expo-secure-store.
import { nativeStore } from '@byokit/secrets/native';
const phone = nativeStore({ prefix: 'my-app' });
await phone.set('openai', 'sk-…');

Backends

Native OS keyring (osKeyringStore({ service })). macOS Keychain, Windows Credential Manager and Linux Secret Service through the optional, exactly pinned @napi-rs/keyring 2.1.0 N-API binding. The synchronous form osKeyring({ service }) implements KeyringBackend for sealing; the store form implements the common async API. The binding loads only on an operation. Linux explicitly requires { linux: { store: 'secret-service' } }: no fallback to a kernel keyring that disappears on reboot. An absent/locked service or missing native binary throws KeystoreError with code: 'unavailable'. Only an actual absent entry returns null/false. Unsupported OSes throw unsupported. Names, service and values are validated before native calls; native errors are sanitized. Unlike the CLI backend, values ending in LF are preserved.

OS keyring (keyringStore). macOS Keychain through /usr/bin/security, Secret Service through /usr/bin/secret-tool, each spawned by absolute path. The secret reaches the CLI only on stdin, never in argv or env; every spawn gets an env built from nothing (PATH, LANG) plus only what the host passes in env (on Linux that is where DBUS_SESSION_BUS_ADDRESS goes). get strips the single trailing LF the CLI adds when it prints a secret, so a secret ending in a newline round-trips without it. Windows Credential Manager is unsupported in v1: on win32 every call rejects unsupported.

Passphrase file (fileStore). The whole map lives in one JSON file { v: 1, kdf: 'scrypt-16384-8-1', salt, box } where box is sealSecretBox over the entries under a scrypt key, with a fresh 16-byte salt per save. Writes go through the exported writeFileAtomic (0700 folders, 0600 file, rename over the target). A wrong passphrase rejects auth-failed and fails closed: nothing is returned and nothing is written. Prefer a Uint8Array passphrase: a string cannot be zeroed because the runtime keeps copies; derived keys are zeroed after use.

CI override (overrideStore). A validated copy of the map the host passes; get/set/delete work on the copy. In CI the host builds it from process.env itself — the kit never reads the environment, so a poisoned environment cannot change what the kit does.

Phone (nativeStore). Calls Expo SecureStore's async get/set/delete methods. The optional expo-secure-store peer loads on the first operation; importing the entry does not load native code. A host can supply secureStore with the same three methods for tests or another compatible secure backend. options passes SecureStore's keychainService, accessibility, authentication and access options consistently to every call. Native failures reject with a sanitized failed error; a missing peer rejects unavailable. There is no simulator plaintext fallback. Names are encoded as fixed-width UTF-16 hex under prefix (default byokit) to satisfy Expo's key alphabet without collisions. SecureStore can reject large values even below the kit's 1 MiB limit; authentication-protected values can become inaccessible after biometric changes. See Expo's installation and persistence guide. Native delete reads before deleting; concurrent callers may both report true.…