@neotales/linux-libsecret

Linux secret storage backed by the freedesktop.org Secret Service through libsecret.

Installation

npm install @neotales/linux-libsecret

Usage

import { getSecretString, isAvailable, saveSecret } from "@neotales/linux-libsecret";

if (isAvailable()) {
  saveSecret("my-service", "my-account", "my-secret");
  console.log(getSecretString("my-service", "my-account"));
}

The root module provides isAvailable, getSecret, getSecretString, saveSecret, removeSecret, and listSecrets.

Native FFI

import {
  Gio,
  isGioAvailable,
  isLinuxKeyringAvailable,
  Libsecret,
  LibsecretErrorHandle,
} from "@neotales/linux-libsecret/ffi";

if (isLinuxKeyringAvailable()) {
  const schema = Libsecret.secretSchemaNew(
    "org.freedesktop.Secret.Generic",
    0,
    "service",
    0,
    "account",
    0,
    null,
  );
  if (schema !== null) {
    const errorOut = new LibsecretErrorHandle();
    const password = Libsecret.secretPasswordLookupSync(
      schema,
      null,
      errorOut,
      "service",
      "my-service",
      "account",
      "my-account",
      null,
    );
    if (errorOut.error() !== null) throw errorOut.error();
    if (password !== null) Libsecret.secretPasswordFree(password);
  }
}

Libsecret exposes camelCase wrappers for libsecret's native functions. GError** is represented by a caller-created LibsecretErrorHandle, which is bound to the runtime on its first call, reset when reused there, and read with error(). Schemas and returned passwords are runtime-bound handles; password text is read with password.text() and the handle must be released with secretPasswordFree.

GIO cancellation is optional. Check isGioAvailable() before calling Gio.cancellableNew(), Gio.cancellableCancel(), or Gio.cancellableRelease(); those methods throw when GIO is unavailable. A GCancellableHandle is runtime-bound, can be passed to a synchronous password call, and must be released exactly once.

Runtime Notes

This package is Linux-specific. On other platforms isAvailable() returns false; root reads, removals, and lists return safe defaults, while /ffi calls throw when invoked.

• Deno requires --allow-ffi, for example: deno run --allow-ffi app.ts.
• Node.js 26+ uses native FFI with --experimental-ffi, for example: node --experimental-ffi app.ts.
• Node.js without native FFI can use the koffi fallback: npm install koffi. Koffi does not require a runtime flag.
• Bun uses its built-in FFI and needs no additional flag.
• libsecret-1.so.0, libglib-2.0.so.0, and libgobject-2.0.so.0 are required for the normal backend. libgio-2.0.so.0 may be absent unless you explicitly use GCancellable operations through Gio.
• Install your distribution's libsecret runtime or development package as appropriate; package names vary by distribution. Also run a Secret Service implementation. libsecret is the client library, not a Secret Service implementation.

License

MIT License