feat(core): initial release with 3-tier secret storage

Implements SmartSecret with macOS Keychain, Linux secret-tool, and AES-256-GCM encrypted file fallback backends. Zero runtime dependencies.

.gitignore

@@ -0,0 +1,24 @@
+.nogit/
+
+# artifacts
+coverage/
+public/
+pages/
+
+# installs
+node_modules/
+
+# caches
+.yarn/
+.cache/
+.rpt2_cache
+
+# builds
+dist/
+dist_*/
+
+# AI
+.claude/
+.serena/
+
+# custom

changelog.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 2025-02-24 - 1.0.0 - Initial Release
+- macOS Keychain backend via `security` CLI
+- Linux secret-tool backend via libsecret
+- AES-256-GCM encrypted file vault fallback
+- Automatic backend detection with graceful fallback

license

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npmextra.json

@@ -0,0 +1,28 @@
+{
+  "npmci": {
+    "npmAccessLevel": "public"
+  },
+  "gitzone": {
+    "projectType": "npm",
+    "module": {
+      "githost": "code.foss.global",
+      "gitscope": "push.rocks",
+      "gitrepo": "smartsecret",
+      "description": "OS keychain-based secret storage with encrypted-file fallback for Node.js.",
+      "npmPackagename": "@push.rocks/smartsecret",
+      "license": "MIT",
+      "keywords": [
+        "secret",
+        "keychain",
+        "credential",
+        "vault",
+        "encryption",
+        "security",
+        "keyring",
+        "libsecret",
+        "macos-keychain",
+        "aes-256-gcm"
+      ]
+    }
+  }
+}

package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@push.rocks/smartsecret",
+  "version": "1.0.0",
+  "private": false,
+  "description": "OS keychain-based secret storage with encrypted-file fallback for Node.js.",
+  "main": "dist_ts/index.js",
+  "typings": "dist_ts/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "test": "(tstest test/ --verbose)",
+    "build": "(tsbuild)",
+    "buildDocs": "tsdoc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://code.foss.global/push.rocks/smartsecret.git"
+  },
+  "keywords": [
+    "secret",
+    "keychain",
+    "credential",
+    "vault",
+    "encryption",
+    "security",
+    "keyring",
+    "libsecret",
+    "macos-keychain",
+    "aes-256-gcm"
+  ],
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/pushrocks/smartsecret/issues"
+  },
+  "homepage": "https://code.foss.global/push.rocks/smartsecret",
+  "devDependencies": {
+    "@git.zone/tsbuild": "^4.1.2",
+    "@git.zone/tsrun": "^2.0.1",
+    "@git.zone/tstest": "^3.1.8",
+    "@push.rocks/tapbundle": "^6.0.3",
+    "@types/node": "^22.15.0"
+  },
+  "files": [
+    "ts/**/*",
+    "ts_web/**/*",
+    "dist/**/*",
+    "dist_*/**/*",
+    "dist_ts/**/*",
+    "dist_ts_web/**/*",
+    "assets/**/*",
+    "cli.js",
+    "npmextra.json",
+    "readme.md"
+  ],
+  "browserslist": [
+    "last 1 chrome versions"
+  ]
+}

readme.hints.md

@@ -0,0 +1,12 @@
+# smartsecret hints
+
+## Architecture
+- 3-tier backend: macOS Keychain → Linux secret-tool → encrypted file vault
+- Zero runtime dependencies (Node.js built-ins only)
+- All OS interactions via child_process.execFile (no shell injection)
+
+## File Backend
+- Vault: AES-256-GCM, JSON file with { iv, ciphertext, tag } per entry
+- Keyfile: auto-generated 32 random bytes at ~/.config/smartsecret/.keyfile (mode 0600)
+- Key derivation: PBKDF2 (SHA-512, 100k iterations, service-name salt)
+- Atomic writes: write .tmp then rename()

readme.md

@@ -0,0 +1,193 @@
+# @push.rocks/smartsecret
+
+OS keychain-based secret storage with encrypted-file fallback for Node.js.
+
+## Install
+
+To install `@push.rocks/smartsecret`, use pnpm:
+
+```shell
+pnpm install @push.rocks/smartsecret
+```
+
+## Usage
+
+`@push.rocks/smartsecret` provides a unified API for storing and retrieving secrets. It automatically selects the best available backend for the current platform: macOS Keychain on macOS, `secret-tool` (libsecret / GNOME Keyring) on Linux, or an AES-256-GCM encrypted file as a universal fallback.
+
+### Basic Setup
+
+```typescript
+import { SmartSecret } from '@push.rocks/smartsecret';
+
+// Create an instance with default settings
+const secretStore = new SmartSecret();
+
+// Or specify a custom service name and vault path
+const secretStore = new SmartSecret({
+  service: 'my-application',
+  vaultPath: '/path/to/custom/vault.json',
+});
+```
+
+The `service` option acts as a namespace, isolating secrets so that different applications do not collide. It defaults to `'smartsecret'` when omitted.
+
+The `vaultPath` option only applies to the encrypted-file backend and controls where the vault JSON file is stored. It defaults to `~/.config/smartsecret/vault.json`.
+
+### Storing a Secret
+
+```typescript
+await secretStore.setSecret('api-key', 'sk-abc123xyz');
+```
+
+If a secret with the same account name already exists under the configured service, it is overwritten.
+
+### Retrieving a Secret
+
+```typescript
+const apiKey = await secretStore.getSecret('api-key');
+
+if (apiKey !== null) {
+  console.log('Retrieved secret:', apiKey);
+} else {
+  console.log('Secret not found');
+}
+```
+
+Returns `null` when no secret exists for the given account.
+
+### Deleting a Secret
+
+```typescript
+const wasDeleted = await secretStore.deleteSecret('api-key');
+console.log(wasDeleted); // true if the secret existed and was removed
+```
+
+Returns `false` if the secret did not exist.
+
+### Listing Accounts
+
+```typescript
+const accounts = await secretStore.listAccounts();
+console.log(accounts); // e.g. ['api-key', 'db-password', 'oauth-token']
+```
+
+Returns an array of account names that have stored secrets under the configured service.
+
+### Checking the Active Backend
+
+```typescript
+const backendType = await secretStore.getBackendType();
+console.log(backendType);
+// 'macos-keychain' | 'linux-secret-service' | 'file-encrypted'
+```
+
+This is useful for logging or diagnostics to understand which storage mechanism is in use at runtime.
+
+### Service-Based Isolation
+
+Different `SmartSecret` instances with different `service` names maintain completely separate secret namespaces, even when sharing the same underlying storage:
+
+```typescript
+const appSecrets = new SmartSecret({ service: 'my-app' });
+const ciSecrets = new SmartSecret({ service: 'ci-pipeline' });
+
+await appSecrets.setSecret('token', 'app-token-value');
+await ciSecrets.setSecret('token', 'ci-token-value');
+
+const appToken = await appSecrets.getSecret('token');  // 'app-token-value'
+const ciToken = await ciSecrets.getSecret('token');     // 'ci-token-value'
+```
+
+## API Reference
+
+### `SmartSecret`
+
+The main class. Instantiate it to store and retrieve secrets.
+
+#### Constructor
+
+```typescript
+new SmartSecret(options?: ISmartSecretOptions)
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `service` | `string` | `'smartsecret'` | Namespace for secret isolation |
+| `vaultPath` | `string` | `~/.config/smartsecret/vault.json` | Path to the encrypted vault file (file backend only) |
+
+#### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `setSecret` | `(account: string, secret: string) => Promise<void>` | Store or overwrite a secret |
+| `getSecret` | `(account: string) => Promise<string \| null>` | Retrieve a secret, or `null` if not found |
+| `deleteSecret` | `(account: string) => Promise<boolean>` | Delete a secret; returns `true` if it existed |
+| `listAccounts` | `() => Promise<string[]>` | List all account names for the configured service |
+| `getBackendType` | `() => Promise<TBackendType>` | Returns the active backend identifier |
+
+### Types
+
+```typescript
+type TBackendType = 'macos-keychain' | 'linux-secret-service' | 'file-encrypted';
+
+interface ISmartSecretOptions {
+  service?: string;
+  vaultPath?: string;
+}
+
+interface ISecretBackend {
+  readonly backendType: TBackendType;
+  isAvailable(): Promise<boolean>;
+  setSecret(account: string, secret: string): Promise<void>;
+  getSecret(account: string): Promise<string | null>;
+  deleteSecret(account: string): Promise<boolean>;
+  listAccounts(): Promise<string[]>;
+}
+```
+
+### Backend Classes
+
+Each backend implements `ISecretBackend` and can be used directly if needed:
+
+- `MacosKeychainBackend` -- macOS Keychain via the `security` CLI
+- `LinuxSecretServiceBackend` -- Linux Secret Service via `secret-tool`
+- `FileEncryptedBackend` -- AES-256-GCM encrypted JSON vault file
+
+## Backends
+
+`SmartSecret` tries each backend in order and uses the first one that reports itself as available.
+
+### macOS Keychain (`macos-keychain`)
+
+Used automatically on macOS when the `security` command-line tool is present (ships with macOS by default). Secrets are stored as generic password items in the user's default keychain. The `service` option maps to the keychain service name, and the `account` parameter maps to the keychain account name.
+
+### Linux Secret Service (`linux-secret-service`)
+
+Used automatically on Linux when `secret-tool` is installed. This integrates with GNOME Keyring, KDE Wallet, or any other provider that implements the freedesktop.org Secret Service D-Bus API. Install the tool on Debian/Ubuntu with:
+
+```shell
+sudo apt install libsecret-tools
+```
+
+Secrets are stored with `service` and `account` as lookup attributes.
+
+### Encrypted File (`file-encrypted`)
+
+The universal fallback that works on all platforms. Secrets are encrypted with AES-256-GCM and stored in a JSON vault file. A random 32-byte key is generated on first use and stored alongside the vault at `~/.config/smartsecret/.keyfile` (with `0600` permissions). The encryption key is derived from the keyfile using PBKDF2 with 100,000 iterations of SHA-512, salted with the service name.
+
+Vault writes are atomic (write to a temporary file, then rename) to prevent corruption. Both the keyfile and the vault file are created with restrictive file permissions.
+
+**File locations (defaults):**
+
+| File | Path |
+| --- | --- |
+| Vault | `~/.config/smartsecret/vault.json` |
+| Keyfile | `~/.config/smartsecret/.keyfile` |
+
+Both paths can be influenced by providing a custom `vaultPath` in the constructor options. The keyfile is always stored in the same directory as the vault.
+
+## License and Legal Information
+
+This project is licensed under the MIT license. For more details, see the `license` file in the repository.
+
+By using this package, you agree to the licensing terms.

test/test.ts

@@ -0,0 +1,94 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as smartsecret from '../ts/index.js';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+
+let testDir: string;
+let instance: smartsecret.SmartSecret;
+
+tap.test('setup - create temp directory', async () => {
+  testDir = path.join(os.tmpdir(), `smartsecret-test-${Date.now()}`);
+  fs.mkdirSync(testDir, { recursive: true });
+  instance = new smartsecret.SmartSecret({
+    service: 'smartsecret-test',
+    vaultPath: path.join(testDir, 'vault.json'),
+  });
+});
+
+tap.test('should report file-encrypted backend type', async () => {
+  const backendType = await instance.getBackendType();
+  // On CI/test environments without keychain, should fall back to file
+  expect(backendType).toEqual('file-encrypted');
+});
+
+tap.test('should set and get a secret', async () => {
+  await instance.setSecret('test-account', 'my-secret-value');
+  const result = await instance.getSecret('test-account');
+  expect(result).toEqual('my-secret-value');
+});
+
+tap.test('should return null for non-existent secret', async () => {
+  const result = await instance.getSecret('nonexistent');
+  expect(result).toBeNull();
+});
+
+tap.test('should overwrite an existing secret', async () => {
+  await instance.setSecret('test-account', 'updated-secret');
+  const result = await instance.getSecret('test-account');
+  expect(result).toEqual('updated-secret');
+});
+
+tap.test('should handle special characters in secrets', async () => {
+  const specialSecret = '!@#$%^&*()_+-=[]{}|;:\'",.<>?/\\`~\n\ttabs and newlines';
+  await instance.setSecret('special-chars', specialSecret);
+  const result = await instance.getSecret('special-chars');
+  expect(result).toEqual(specialSecret);
+});
+
+tap.test('should handle empty string secrets', async () => {
+  await instance.setSecret('empty-secret', '');
+  const result = await instance.getSecret('empty-secret');
+  expect(result).toEqual('');
+});
+
+tap.test('should list accounts', async () => {
+  const accounts = await instance.listAccounts();
+  expect(accounts).toContain('test-account');
+  expect(accounts).toContain('special-chars');
+  expect(accounts).toContain('empty-secret');
+});
+
+tap.test('should delete a secret', async () => {
+  const deleted = await instance.deleteSecret('test-account');
+  expect(deleted).toBeTrue();
+  const result = await instance.getSecret('test-account');
+  expect(result).toBeNull();
+});
+
+tap.test('should return false when deleting non-existent secret', async () => {
+  const deleted = await instance.deleteSecret('nonexistent');
+  expect(deleted).toBeFalse();
+});
+
+tap.test('should isolate secrets by service', async () => {
+  const otherInstance = new smartsecret.SmartSecret({
+    service: 'other-service',
+    vaultPath: path.join(testDir, 'vault.json'),
+  });
+
+  await otherInstance.setSecret('shared-name', 'other-value');
+  await instance.setSecret('shared-name', 'original-value');
+
+  const otherResult = await otherInstance.getSecret('shared-name');
+  const originalResult = await instance.getSecret('shared-name');
+
+  expect(otherResult).toEqual('other-value');
+  expect(originalResult).toEqual('original-value');
+});
+
+tap.test('cleanup - remove temp directory', async () => {
+  fs.rmSync(testDir, { recursive: true, force: true });
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @pushrocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smartsecret',
+  version: '1.0.0',
+  description: 'OS keychain-based secret storage with encrypted-file fallback for Node.js.',
+};

ts/index.ts

@@ -0,0 +1,5 @@
+export * from './smartsecret.classes.smartsecret.js';
+export type { ISecretBackend, TBackendType } from './smartsecret.backends.base.js';
+export { MacosKeychainBackend } from './smartsecret.backends.macos.js';
+export { LinuxSecretServiceBackend } from './smartsecret.backends.linux.js';
+export { FileEncryptedBackend } from './smartsecret.backends.file.js';

ts/smartsecret.backends.base.ts

@@ -0,0 +1,10 @@
+export type TBackendType = 'macos-keychain' | 'linux-secret-service' | 'file-encrypted';
+
+export interface ISecretBackend {
+  readonly backendType: TBackendType;
+  isAvailable(): Promise<boolean>;
+  setSecret(account: string, secret: string): Promise<void>;
+  getSecret(account: string): Promise<string | null>;
+  deleteSecret(account: string): Promise<boolean>;
+  listAccounts(): Promise<string[]>;
+}

ts/smartsecret.backends.file.ts

@@ -0,0 +1,153 @@
+import * as plugins from './smartsecret.plugins.js';
+import type { ISecretBackend, TBackendType } from './smartsecret.backends.base.js';
+
+interface IVaultEntry {
+  iv: string;       // hex
+  ciphertext: string; // hex
+  tag: string;       // hex
+}
+
+interface IVaultData {
+  [key: string]: IVaultEntry;
+}
+
+export class FileEncryptedBackend implements ISecretBackend {
+  public readonly backendType: TBackendType = 'file-encrypted';
+  private service: string;
+  private vaultPath: string;
+  private keyfilePath: string;
+
+  constructor(service: string, vaultPath?: string) {
+    this.service = service;
+    const configDir = vaultPath
+      ? plugins.path.dirname(vaultPath)
+      : plugins.path.join(plugins.os.homedir(), '.config', 'smartsecret');
+    this.vaultPath = vaultPath || plugins.path.join(configDir, 'vault.json');
+    this.keyfilePath = plugins.path.join(configDir, '.keyfile');
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true; // File backend is always available
+  }
+
+  async setSecret(account: string, secret: string): Promise<void> {
+    const key = await this.deriveKey();
+    const vault = await this.readVault();
+    const vaultKey = `${this.service}:${account}`;
+
+    const iv = plugins.crypto.randomBytes(12);
+    const cipher = plugins.crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(secret, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+
+    vault[vaultKey] = {
+      iv: iv.toString('hex'),
+      ciphertext: encrypted.toString('hex'),
+      tag: tag.toString('hex'),
+    };
+
+    await this.writeVault(vault);
+  }
+
+  async getSecret(account: string): Promise<string | null> {
+    const key = await this.deriveKey();
+    const vault = await this.readVault();
+    const vaultKey = `${this.service}:${account}`;
+
+    const entry = vault[vaultKey];
+    if (!entry) return null;
+
+    try {
+      const iv = Buffer.from(entry.iv, 'hex');
+      const ciphertext = Buffer.from(entry.ciphertext, 'hex');
+      const tag = Buffer.from(entry.tag, 'hex');
+
+      const decipher = plugins.crypto.createDecipheriv('aes-256-gcm', key, iv);
+      decipher.setAuthTag(tag);
+      const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+      return decrypted.toString('utf8');
+    } catch {
+      return null;
+    }
+  }
+
+  async deleteSecret(account: string): Promise<boolean> {
+    const vault = await this.readVault();
+    const vaultKey = `${this.service}:${account}`;
+
+    if (!(vaultKey in vault)) return false;
+
+    delete vault[vaultKey];
+    await this.writeVault(vault);
+    return true;
+  }
+
+  async listAccounts(): Promise<string[]> {
+    const vault = await this.readVault();
+    const prefix = `${this.service}:`;
+    return Object.keys(vault)
+      .filter((k) => k.startsWith(prefix))
+      .map((k) => k.slice(prefix.length));
+  }
+
+  private async deriveKey(): Promise<Buffer> {
+    const keyfileContent = await this.ensureKeyfile();
+    return new Promise((resolve, reject) => {
+      plugins.crypto.pbkdf2(
+        keyfileContent,
+        `smartsecret:${this.service}`,
+        100_000,
+        32,
+        'sha512',
+        (err, derivedKey) => {
+          if (err) reject(err);
+          else resolve(derivedKey);
+        },
+      );
+    });
+  }
+
+  private async ensureKeyfile(): Promise<Buffer> {
+    const dir = plugins.path.dirname(this.keyfilePath);
+    try {
+      await plugins.fs.promises.mkdir(dir, { recursive: true });
+    } catch {
+      // Already exists
+    }
+
+    try {
+      const content = await plugins.fs.promises.readFile(this.keyfilePath);
+      return content;
+    } catch {
+      // Generate new keyfile
+      const key = plugins.crypto.randomBytes(32);
+      await plugins.fs.promises.writeFile(this.keyfilePath, key, { mode: 0o600 });
+      return key;
+    }
+  }
+
+  private async readVault(): Promise<IVaultData> {
+    try {
+      const content = await plugins.fs.promises.readFile(this.vaultPath, 'utf8');
+      return JSON.parse(content) as IVaultData;
+    } catch {
+      return {};
+    }
+  }
+
+  private async writeVault(vault: IVaultData): Promise<void> {
+    const dir = plugins.path.dirname(this.vaultPath);
+    try {
+      await plugins.fs.promises.mkdir(dir, { recursive: true });
+    } catch {
+      // Already exists
+    }
+
+    const tmpPath = this.vaultPath + '.tmp';
+    await plugins.fs.promises.writeFile(tmpPath, JSON.stringify(vault, null, 2), {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    await plugins.fs.promises.rename(tmpPath, this.vaultPath);
+  }
+}

ts/smartsecret.backends.linux.ts

@@ -0,0 +1,109 @@
+import * as plugins from './smartsecret.plugins.js';
+import type { ISecretBackend, TBackendType } from './smartsecret.backends.base.js';
+
+function execFile(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    plugins.childProcess.execFile(cmd, args, { encoding: 'utf8' }, (err, stdout, stderr) => {
+      if (err) {
+        reject(Object.assign(err, { stdout, stderr }));
+      } else {
+        resolve({ stdout: stdout as string, stderr: stderr as string });
+      }
+    });
+  });
+}
+
+function spawnWithStdin(cmd: string, args: string[], stdinData: string): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = plugins.childProcess.spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout!.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
+    child.stderr!.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+      } else {
+        reject(Object.assign(new Error(`secret-tool exited with code ${code}`), { stdout, stderr }));
+      }
+    });
+    child.stdin!.write(stdinData);
+    child.stdin!.end();
+  });
+}
+
+export class LinuxSecretServiceBackend implements ISecretBackend {
+  public readonly backendType: TBackendType = 'linux-secret-service';
+  private service: string;
+
+  constructor(service: string) {
+    this.service = service;
+  }
+
+  async isAvailable(): Promise<boolean> {
+    if (process.platform !== 'linux') return false;
+    try {
+      await execFile('which', ['secret-tool']);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async setSecret(account: string, secret: string): Promise<void> {
+    // secret-tool store reads password from stdin
+    await spawnWithStdin('secret-tool', [
+      'store',
+      '--label', `${this.service}:${account}`,
+      'service', this.service,
+      'account', account,
+    ], secret);
+  }
+
+  async getSecret(account: string): Promise<string | null> {
+    try {
+      const { stdout } = await execFile('secret-tool', [
+        'lookup',
+        'service', this.service,
+        'account', account,
+      ]);
+      // secret-tool returns empty string if not found (exit 0) or exits non-zero
+      return stdout.length > 0 ? stdout : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async deleteSecret(account: string): Promise<boolean> {
+    try {
+      await execFile('secret-tool', [
+        'clear',
+        'service', this.service,
+        'account', account,
+      ]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async listAccounts(): Promise<string[]> {
+    try {
+      const { stdout } = await execFile('secret-tool', [
+        'search',
+        '--all',
+        'service', this.service,
+      ]);
+      const accounts: string[] = [];
+      const regex = /attribute\.account = (.+)/g;
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(stdout)) !== null) {
+        accounts.push(match[1].trim());
+      }
+      return [...new Set(accounts)];
+    } catch {
+      return [];
+    }
+  }
+}

ts/smartsecret.backends.macos.ts

@@ -0,0 +1,107 @@
+import * as plugins from './smartsecret.plugins.js';
+import type { ISecretBackend, TBackendType } from './smartsecret.backends.base.js';
+
+function execFile(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    plugins.childProcess.execFile(cmd, args, { encoding: 'utf8' }, (err, stdout, stderr) => {
+      if (err) {
+        reject(Object.assign(err, { stdout, stderr }));
+      } else {
+        resolve({ stdout: stdout as string, stderr: stderr as string });
+      }
+    });
+  });
+}
+
+export class MacosKeychainBackend implements ISecretBackend {
+  public readonly backendType: TBackendType = 'macos-keychain';
+  private service: string;
+
+  constructor(service: string) {
+    this.service = service;
+  }
+
+  async isAvailable(): Promise<boolean> {
+    if (process.platform !== 'darwin') return false;
+    try {
+      await execFile('which', ['security']);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async setSecret(account: string, secret: string): Promise<void> {
+    // Delete existing entry first (ignore errors if not found)
+    try {
+      await execFile('security', [
+        'delete-generic-password',
+        '-s', this.service,
+        '-a', account,
+      ]);
+    } catch {
+      // Not found — fine
+    }
+
+    await execFile('security', [
+      'add-generic-password',
+      '-s', this.service,
+      '-a', account,
+      '-w', secret,
+      '-U',
+    ]);
+  }
+
+  async getSecret(account: string): Promise<string | null> {
+    try {
+      const { stdout } = await execFile('security', [
+        'find-generic-password',
+        '-s', this.service,
+        '-a', account,
+        '-w',
+      ]);
+      return stdout.trim();
+    } catch {
+      return null;
+    }
+  }
+
+  async deleteSecret(account: string): Promise<boolean> {
+    try {
+      await execFile('security', [
+        'delete-generic-password',
+        '-s', this.service,
+        '-a', account,
+      ]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async listAccounts(): Promise<string[]> {
+    try {
+      const { stdout } = await execFile('security', [
+        'dump-keychain',
+      ]);
+      const accounts: string[] = [];
+      const serviceRegex = new RegExp(`"svce"<blob>="${this.service.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"`);
+      const lines = stdout.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (serviceRegex.test(lines[i])) {
+          // Look for the account line nearby
+          for (let j = Math.max(0, i - 5); j < Math.min(lines.length, i + 5); j++) {
+            const match = lines[j].match(/"acct"<blob>="([^"]+)"/);
+            if (match) {
+              accounts.push(match[1]);
+              break;
+            }
+          }
+        }
+      }
+      return [...new Set(accounts)];
+    } catch {
+      return [];
+    }
+  }
+}

ts/smartsecret.classes.smartsecret.ts

@@ -0,0 +1,66 @@
+import type { ISecretBackend, TBackendType } from './smartsecret.backends.base.js';
+import { MacosKeychainBackend } from './smartsecret.backends.macos.js';
+import { LinuxSecretServiceBackend } from './smartsecret.backends.linux.js';
+import { FileEncryptedBackend } from './smartsecret.backends.file.js';
+
+export interface ISmartSecretOptions {
+  service?: string;
+  vaultPath?: string;
+}
+
+export class SmartSecret {
+  private service: string;
+  private vaultPath?: string;
+  private backend: ISecretBackend | null = null;
+
+  constructor(options?: ISmartSecretOptions) {
+    this.service = options?.service ?? 'smartsecret';
+    this.vaultPath = options?.vaultPath;
+  }
+
+  private async getBackend(): Promise<ISecretBackend> {
+    if (this.backend) return this.backend;
+
+    const candidates: ISecretBackend[] = [
+      new MacosKeychainBackend(this.service),
+      new LinuxSecretServiceBackend(this.service),
+      new FileEncryptedBackend(this.service, this.vaultPath),
+    ];
+
+    for (const candidate of candidates) {
+      if (await candidate.isAvailable()) {
+        this.backend = candidate;
+        return this.backend;
+      }
+    }
+
+    // File backend is always available, so we should never reach here
+    this.backend = candidates[candidates.length - 1];
+    return this.backend;
+  }
+
+  async setSecret(account: string, secret: string): Promise<void> {
+    const backend = await this.getBackend();
+    await backend.setSecret(account, secret);
+  }
+
+  async getSecret(account: string): Promise<string | null> {
+    const backend = await this.getBackend();
+    return backend.getSecret(account);
+  }
+
+  async deleteSecret(account: string): Promise<boolean> {
+    const backend = await this.getBackend();
+    return backend.deleteSecret(account);
+  }
+
+  async listAccounts(): Promise<string[]> {
+    const backend = await this.getBackend();
+    return backend.listAccounts();
+  }
+
+  async getBackendType(): Promise<TBackendType> {
+    const backend = await this.getBackend();
+    return backend.backendType;
+  }
+}

ts/smartsecret.plugins.ts

@@ -0,0 +1,8 @@
+// node native scope
+import * as childProcess from 'child_process';
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+export { childProcess, crypto, fs, os, path };

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "paths": {}
+  },
+  "exclude": ["dist_*/**/*.d.ts"]
+}