@push.rocks/smartsecret 1.0.1

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@push.rocks/smartsecret",
+  "version": "1.0.1",
+  "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"
+  ]
+}

package/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()

package/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.

package/ts/00_commitinfo_data.ts

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

package/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';

package/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[]>;
+}

package/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);
+  }
+}

package/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 [];
+    }
+  }
+}

package/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 [];
+    }
+  }
+}