feat: add safeStorage with AES-256-GCM keyed by the macOS Keychain and Linux libsecret

Author: ipfizz

.github/workflows/validate.yml

@@ -24,11 +24,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Linux native deps (GTK 4 + WebKitGTK 6.0 + libnotify + Xvfb)
+      - name: Install Linux native deps (GTK 4 + WebKitGTK 6.0 + libnotify + libsecret + Xvfb)
         if: runner.os == 'Linux'
         run: |
           sudo apt-get update
-          sudo apt-get install -y libgtk-4-1 libwebkitgtk-6.0-4 libnotify4 xvfb
+          sudo apt-get install -y libgtk-4-1 libwebkitgtk-6.0-4 libnotify4 libsecret-1-0 xvfb
 
       - uses: oven-sh/setup-bun@v2
         with:

src/main/api/safe-storage.ts

@@ -0,0 +1,160 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { InvalidArgumentError, SambarError } from '../../common/errors';
+import { currentPlatform } from '../../common/platform';
+import { linuxLibsecretBackend } from '../platform/linux/libsecret-keyring';
+import { macosKeychainBackend } from '../platform/macos/cocoa-safe-storage';
+
+/**
+ * Encryption of strings tied to an OS-protected key — the drop-in equivalent of
+ * Electron's `safeStorage`.
+ *
+ * The key is a random 32-byte secret kept in the OS keyring (macOS Keychain,
+ * Linux libsecret) and never written to disk by Sambar. Strings are sealed with
+ * AES-256-GCM (authenticated — tampering throws on decrypt).
+ *
+ * DIVERGENCE FROM ELECTRON (deliberate): Electron falls back to a `basic_text`
+ * scheme (an obfuscated, effectively-plaintext key) when no OS keyring exists.
+ * Sambar does NOT — a key sitting next to the ciphertext is not protection. With
+ * no keyring, `isEncryptionAvailable()` returns `false` and
+ * `encryptString`/`decryptString` throw. Sambar also does not promise
+ * Electron-blob compatibility: a native, versioned blob format is used.
+ */
+
+export type SafeStorage = {
+  /** Whether a keyring-backed key is available so encrypt/decrypt can run. Never throws. */
+  isEncryptionAvailable(): boolean;
+  /** Seal `plainText` (UTF-8) into an authenticated blob. Throws if encryption is unavailable. */
+  encryptString(plainText: string): Buffer;
+  /** Open a blob produced by {@link encryptString}. Throws on tamper, bad format, or unavailability. */
+  decryptString(encrypted: Buffer): string;
+};
+
+/**
+ * The keyring seam the crypto layer delegates to for its 32-byte key. Injectable
+ * so the format/crypto logic is unit-tested with an in-memory fake — no FFI, no
+ * real keyring, never a blocking call in CI.
+ */
+export type KeyringBackend = {
+  /** Whether this host can store/retrieve a key. MUST be cheap + non-blocking + never throw. */
+  isAvailable(): boolean;
+  /** Fetch the existing 32-byte key or create+persist one. May throw (surfaced by encrypt/decrypt). */
+  getOrCreateKey(): Buffer;
+};
+
+const KEY_LENGTH = 32;
+/** GCM nonce length (96-bit IV — the GCM standard / fastest path). */
+const IV_LENGTH = 12;
+/** GCM authentication tag length. */
+const TAG_LENGTH = 16;
+/** Blob format version, so a future format can co-exist. */
+const VERSION = 0x01;
+/** Smallest valid blob: version + IV + (≥0 ciphertext) + tag. */
+const MIN_BLOB_LENGTH = 1 + IV_LENGTH + TAG_LENGTH;
+
+/**
+ * Blob layout: `[version:1][iv:12][ciphertext:N][tag:16]`. A random IV per
+ * encryption (never reused) + the GCM tag make the blob tamper-evident.
+ */
+const encryptWithKey = (key: Buffer, plainText: string): Buffer => {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plainText, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([Buffer.from([VERSION]), iv, ciphertext, tag]);
+};
+
+const decryptWithKey = (key: Buffer, blob: Buffer): string => {
+  if (blob.length < MIN_BLOB_LENGTH) {
+    throw new InvalidArgumentError('safeStorage: corrupt blob (too short)');
+  }
+  if (blob[0] !== VERSION) {
+    throw new InvalidArgumentError(
+      `safeStorage: unsupported blob version 0x${blob[0]?.toString(16)}`,
+    );
+  }
+  const iv = blob.subarray(1, 1 + IV_LENGTH);
+  const tag = blob.subarray(blob.length - TAG_LENGTH);
+  const ciphertext = blob.subarray(1 + IV_LENGTH, blob.length - TAG_LENGTH);
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  // GCM auth failure (tamper / wrong key) makes final() THROW — surface it loudly,
+  // never return garbage plaintext.
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+};
+
+/** Built-in backend for platforms with no keyring: reports unavailable, throws if forced. */
+const unavailableBackend: KeyringBackend = {
+  isAvailable: () => false,
+  getOrCreateKey: () => {
+    throw new SambarError(`safeStorage has no keyring backend on ${currentPlatform()}`);
+  },
+};
+
+let backend: KeyringBackend | undefined;
+let cachedKey: Buffer | undefined;
+let cachedAvailable: boolean | undefined;
+
+const getBackend = (): KeyringBackend => {
+  if (backend !== undefined) {
+    return backend;
+  }
+  const platform = currentPlatform();
+  if (platform === 'macos') {
+    return macosKeychainBackend;
+  }
+  if (platform === 'linux') {
+    return linuxLibsecretBackend;
+  }
+  return unavailableBackend;
+};
+
+/** Whether encryption is available — probed once, then memoised (Electron caches at startup). */
+const isAvailable = (): boolean => {
+  if (cachedAvailable === undefined) {
+    cachedAvailable = getBackend().isAvailable();
+  }
+  return cachedAvailable;
+};
+
+/**
+ * Read the keyring ONCE and cache the key for the process — only the first op
+ * pays the round-trip (on Linux, the one blocking D-Bus call); later ops are pure
+ * in-memory AES.
+ */
+const getKey = (): Buffer => {
+  if (cachedKey === undefined) {
+    const key = getBackend().getOrCreateKey();
+    if (key.length !== KEY_LENGTH) {
+      throw new SambarError(
+        `safeStorage: keyring returned a ${key.length}-byte key, expected ${KEY_LENGTH}`,
+      );
+    }
+    cachedKey = key;
+  }
+  return cachedKey;
+};
+
+/** Override the keyring backend AND clear the cached key + availability. Test-only. */
+export const setSafeStorageBackendForTesting = (fake: KeyringBackend | undefined): void => {
+  backend = fake;
+  cachedKey = undefined;
+  cachedAvailable = undefined;
+};
+
+export const safeStorage: SafeStorage = {
+  isEncryptionAvailable() {
+    return isAvailable();
+  },
+  encryptString(plainText) {
+    if (!isAvailable()) {
+      throw new SambarError('safeStorage: encryption is not available (no OS keyring)');
+    }
+    return encryptWithKey(getKey(), plainText);
+  },
+  decryptString(encrypted) {
+    if (!isAvailable()) {
+      throw new SambarError('safeStorage: encryption is not available (no OS keyring)');
+    }
+    return decryptWithKey(getKey(), encrypted);
+  },
+};

src/main/index.ts

@@ -35,6 +35,7 @@ export {
   type ProtocolResponse,
   protocol,
 } from './api/protocol';
+export { type SafeStorage, safeStorage } from './api/safe-storage';
 export { type Display, type Point, screen, type Size } from './api/screen';
 export { Session, session } from './api/session';
 export { shell, type Shell } from './api/shell';

src/main/module-list.ts

@@ -70,6 +70,7 @@ export const IMPLEMENTED_MODULES = [
   'Notification',
   'powerMonitor',
   'protocol',
+  'safeStorage',
   'screen',
   'session',
   'shell',

src/main/platform/linux/libsecret-ffi.ts

@@ -0,0 +1,97 @@
+import { dlopen, FFIType, type Pointer } from 'bun:ffi';
+import { UnsupportedPlatformError } from '../../../common/errors';
+import { currentPlatform } from '../../../common/platform';
+import { cstr } from '../cstr';
+
+/**
+ * libsecret symbols behind the Linux keyring backend of `safeStorage`.
+ *
+ * The simple-password API stores/looks up a single secret under a `SecretSchema`.
+ * We build the schema with {@link secret_schema_new} (libsecret owns the struct
+ * layout — no blind offset reasoning) carrying ZERO attributes, so the schema
+ * identifies one secret and the variadic attribute lists collapse to a trailing
+ * `NULL`. We pass `NULL` for every `GError**` out-param (a NULL/0 return already
+ * means "absent or failed"), which sidesteps GError ownership + pointer-precision
+ * entirely.
+ *
+ * These calls are SYNCHRONOUS (blocking D-Bus). They are gated off in CI and
+ * never run from unit tests (see `libsecret-keyring.ts`). Only callable on Linux.
+ */
+
+const LIBSECRET_PATH = 'libsecret-1.so.0';
+const SCHEMA_NAME = 'dev.sambar.safeStorage';
+/** `SECRET_SCHEMA_NONE` — the secret is tagged with the schema name, so a zero-attribute lookup finds it. */
+const SECRET_SCHEMA_NONE = 0;
+
+export const LIBSECRET_FFI_SYMBOLS = {
+  // (name, flags, ...attrs terminated by NULL) -> SecretSchema* (transfer-full).
+  secret_schema_new: {
+    args: [FFIType.cstring, FFIType.i32, FFIType.pointer],
+    returns: FFIType.pointer,
+  },
+  // (schema, collection|null, label, password, cancellable|null, error|null, NULL) -> gboolean
+  secret_password_store_sync: {
+    args: [
+      FFIType.pointer,
+      FFIType.cstring,
+      FFIType.cstring,
+      FFIType.cstring,
+      FFIType.pointer,
+      FFIType.pointer,
+      FFIType.pointer,
+    ],
+    returns: FFIType.i32,
+  },
+  // (schema, cancellable|null, error|null, NULL) -> gchar* (NULL if absent OR error)
+  secret_password_lookup_sync: {
+    args: [FFIType.pointer, FFIType.pointer, FFIType.pointer, FFIType.pointer],
+    returns: FFIType.pointer,
+  },
+  // (password) -> void; frees a transfer-full gchar* from lookup.
+  secret_password_free: {
+    args: [FFIType.pointer],
+    returns: FFIType.void,
+  },
+} as const;
+
+const cache: {
+  ffi: ReturnType<typeof dlopen<typeof LIBSECRET_FFI_SYMBOLS>> | undefined;
+  schema: Pointer | undefined;
+} = { ffi: undefined, schema: undefined };
+
+const requireLinux = (): void => {
+  const platform = currentPlatform();
+  if (platform !== 'linux') {
+    throw new UnsupportedPlatformError(
+      `libsecret is only supported on Linux; current platform is ${platform}`,
+    );
+  }
+};
+
+/** Open `libsecret-1.so.0` and expose the simple-password symbols. */
+export const loadLibsecretFFI = () => {
+  requireLinux();
+  if (cache.ffi) {
+    return cache.ffi;
+  }
+  const ffi = dlopen(LIBSECRET_PATH, LIBSECRET_FFI_SYMBOLS);
+  cache.ffi = ffi;
+  return ffi;
+};
+
+/** The shared, zero-attribute `SecretSchema*` (built + cached once). */
+export const secretSchema = (): Pointer => {
+  if (cache.schema !== undefined) {
+    return cache.schema;
+  }
+  const schema = loadLibsecretFFI().symbols.secret_schema_new(
+    cstr(SCHEMA_NAME),
+    SECRET_SCHEMA_NONE,
+    null,
+  );
+  if (schema === null) {
+    throw new Error('safeStorage: secret_schema_new() returned null');
+  }
+  cache.schema = schema;
+  return schema;
+};

src/main/platform/linux/libsecret-keyring.ts

@@ -0,0 +1,105 @@
+import { randomBytes } from 'node:crypto';
+import { CString, type Pointer } from 'bun:ffi';
+import type { KeyringBackend } from '../../api/safe-storage';
+import { cstr } from '../cstr';
+import { loadLibsecretFFI, secretSchema } from './libsecret-ffi';
+
+/**
+ * Linux libsecret backend for `safeStorage`. The 32-byte key is stored as a
+ * lowercase-hex STRING (libsecret passwords are NUL-terminated C strings, so raw
+ * bytes are unsafe) in the default login keyring under a fixed zero-attribute
+ * schema.
+ *
+ * The real store/lookup is SYNCHRONOUS (blocking D-Bus) and is gated behind
+ * `SAMBAR_ENABLE_LINUX_KEYRING` — CI never sets it, so the blocking path is
+ * unreachable under xvfb (echoing the GIO-read deadlock lesson). Crucially,
+ * `isAvailable()` is CHEAP + NON-BLOCKING: it only checks the gate + that the
+ * library dlopens; the one blocking keyring round-trip happens lazily inside
+ * `getOrCreateKey()` (called once, behind the API's key cache).
+ */
+
+const LABEL = 'Sambar safeStorage key';
+
+/** Whether the live keyring path is enabled. CI leaves this unset → backend reports unavailable. */
+const liveKeyringEnabled = (): boolean => process.env['SAMBAR_ENABLE_LINUX_KEYRING'] === '1';
+
+/** Read a transfer-full `gchar*` into a JS string and `secret_password_free` it. */
+const takePassword = (password: Pointer): string => {
+  const value = new CString(password).toString();
+  loadLibsecretFFI().symbols.secret_password_free(password);
+  return value;
+};
+
+/** Look up the stored hex key. Returns null if absent OR on any error. Never throws. */
+const lookupHex = (): string | null => {
+  const lib = loadLibsecretFFI();
+  let result: Pointer | null;
+  try {
+    // (schema, cancellable=null, error=null, NULL terminator). A NULL error
+    // out-param means a null return already covers "absent or failed".
+    result = lib.symbols.secret_password_lookup_sync(secretSchema(), null, null, null);
+  } catch {
+    return null;
+  }
+  return result === null ? null : takePassword(result);
+};
+
+/** Store the hex key. Returns false on any failure. */
+const storeHex = (hex: string): boolean => {
+  const lib = loadLibsecretFFI();
+  try {
+    // (schema, collection=null→default, label, password, cancellable=null, error=null, NULL)
+    const ok = lib.symbols.secret_password_store_sync(
+      secretSchema(),
+      null,
+      cstr(LABEL),
+      cstr(hex),
+      null,
+      null,
+      null,
+    );
+    return ok !== 0;
+  } catch {
+    return false;
+  }
+};
+
+/** Decode a stored hex value to a 32-byte key, or throw if it is malformed (never overwrite). */
+const decodeKey = (hex: string): Buffer => {
+  const buf = Buffer.from(hex, 'hex');
+  if (buf.length !== 32) {
+    throw new Error(
+      'safeStorage: existing Linux keyring key is malformed; refusing to overwrite it',
+    );
+  }
+  return buf;
+};
+
+export const linuxLibsecretBackend: KeyringBackend = {
+  // Cheap + non-blocking: the gate must be on AND the library must dlopen. The
+  // actual keyring round-trip is deferred to getOrCreateKey().
+  isAvailable: () => {
+    if (!liveKeyringEnabled()) {
+      return false;
+    }
+    try {
+      loadLibsecretFFI();
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  getOrCreateKey: () => {
+    const existing = lookupHex();
+    if (existing !== null) {
+      return decodeKey(existing);
+    }
+    const fresh = randomBytes(32);
+    if (!storeHex(fresh.toString('hex'))) {
+      throw new Error('safeStorage: failed to store key in the Linux keyring');
+    }
+    // Adopt whatever the keyring actually holds (a concurrent writer may have won).
+    const winner = lookupHex();
+    return winner !== null ? decodeKey(winner) : fresh;
+  },
+};