Skip to content

Replace keytar with @napi-rs/keyring for credential storage - #20

Closed
joerj123 wants to merge 1 commit into
mainfrom
replace-keytar-with-napi-rs-keyring
Closed

Replace keytar with @napi-rs/keyring for credential storage#20
joerj123 wants to merge 1 commit into
mainfrom
replace-keytar-with-napi-rs-keyring

Conversation

@joerj123

Copy link
Copy Markdown
Collaborator

What

Replace the keytar dependency with @napi-rs/keyring for storing Shop credentials in the OS secret store.

Why

keytar is archived/unmaintained and is a native addon that depends on an install-time build script to produce its binary. Modern package managers block dependency build scripts by default (pnpm v10+, bun), so a normal pnpm add @shopify/shop-cli never builds keytar. The result:

  • on macOS it silently fell back to a security-CLI shim, and
  • on Linux/Windows there was no fallback at all — the CLI couldn't read or write credentials and auth broke.

Enabling keytar required an extra, non-obvious manual approval step (pnpm approve-builds), and on Linux also system packages plus a running secret service. That's a poor first-run experience, especially for non-interactive/automated installs.

@napi-rs/keyring is actively maintained and ships prebuilt, per-platform binaries (as optional dependencies) with no install/build script. So:

  • pnpm add / npm install / bun add all work out of the box, with no build-approval prompt;
  • credentials stay encrypted at rest in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service);
  • prebuilt targets include musl, so Alpine/containers work too.

Changes

  • Swap keytar@napi-rs/keyring; rename KeytarSecretStoreOsKeyringSecretStore.
  • Remove the macOS-only security-CLI fallback (the library covers all three platforms natively).
  • Remove the now-unneeded pnpm.onlyBuiltDependencies allowlist.
  • The store is loaded lazily, so commands that don't need stored secrets (e.g. catalog search) still work when no secret store is available, and a single clear, actionable error is shown when the store can't be accessed.

Tradeoff

Headless environments with no secret service (e.g. a bare container) have no OS vault; the CLI now reports a clear error instead of hanging. There is intentionally no plaintext file fallback — credentials are always encrypted at rest.

Testing

  • pnpm typecheck && pnpm test && pnpm build pass.
  • Verified against the live API and the real OS keychain on macOS:
    • credential round-trip (get / set / overwrite / delete);
    • auth status, auth logout, config set-country / show, and catalog search;
    • a fresh packed-tarball install with no build-approval prompt, authenticating immediately.
  • Cross-platform note: the Linux/Windows prebuilt binaries are wired as optional deps; a run on those platforms is recommended as a follow-up.

keytar is unmaintained and is a native addon that relies on an
install-time build script to produce its binary. Modern package managers
skip dependency build scripts by default (pnpm v10+, bun), so a normal
install never built keytar: on macOS the CLI silently fell back to a
`security`-CLI shim, and on Linux/Windows there was no fallback, so it
could not read or write credentials and auth broke. Enabling keytar
required an extra manual build-approval step (and a running secret
service on Linux), a poor first-run experience.

@napi-rs/keyring is actively maintained and ships prebuilt, per-platform
binaries (incl. musl) as optional dependencies with no install/build
script, so installs work out of the box with no approval prompt, while
keeping credentials encrypted at rest in the OS keychain.

- Swap keytar -> @napi-rs/keyring (KeytarSecretStore -> OsKeyringSecretStore)
- Drop the macOS-only `security` CLI fallback; the library covers all platforms
- Remove the now-unneeded pnpm onlyBuiltDependencies allowlist
@joerj123
joerj123 force-pushed the replace-keytar-with-napi-rs-keyring branch from 621a0e4 to 493df72 Compare June 15, 2026 09:47
@joerj123 joerj123 closed this Jun 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant