just-secrets 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+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.

package/README.md

@@ -0,0 +1,135 @@
+# just-secrets
+
+Native OS secret storage for Node.js 24+. Zero dependencies, native addons, or install scripts.
+
+```sh
+npm install just-secrets
+```
+
+```js
+import { secrets } from 'just-secrets';
+
+await secrets.set({
+  service: 'com.example.cli',
+  name: 'api-token',
+  value: 'your-api-token',
+});
+
+const token = await secrets.get({ service: 'com.example.cli', name: 'api-token' });
+const deleted = await secrets.delete({ service: 'com.example.cli', name: 'api-token' });
+```
+
+Node 24 also supports `const { secrets } = require('just-secrets')`. TypeScript declarations ship with the package. There is no build step.
+
+## API
+
+Every operation is asynchronous and returns a Promise. Object and positional forms are interchangeable:
+
+```js
+await secrets.set({ service, name, value }); // Promise<void>
+await secrets.set(service, name, value);
+
+await secrets.get({ service, name });        // Promise<string | null>
+await secrets.get(service, name);
+
+await secrets.delete({ service, name });     // Promise<boolean>
+await secrets.delete(service, name);
+```
+
+- `set` creates a credential or replaces its value.
+- `get` returns `null` when the credential is absent.
+- `delete` returns `true` on deletion, or `false` when absent.
+- Unavailable stores, denied access, unexpected responses, and timeouts reject. They are not treated as missing credentials.
+- Empty values, whitespace, newlines, NUL, and Unicode are preserved exactly. Service and name are case-sensitive and are not normalized.
+- Service and name must be nonempty strings, each at most 256 UTF-8 bytes. Values must be strings of at most 2,560 UTF-8 bytes. Unpaired Unicode surrogates are rejected. Invalid arguments reject with `TypeError` or `RangeError`.
+
+macOS also has a 4,096-byte interactive-command buffer. A combination of long identifiers and a maximum-size value can exceed it; just-secrets rejects before starting the operation. Smaller identifiers or values are then required.
+
+just-secrets uses its own namespaced identifiers and storage representation; it does not discover or migrate credentials written by other libraries.
+
+## Platform requirements
+
+| OS | Native store | Bridge | Requirements |
+| --- | --- | --- | --- |
+| macOS | Login Keychain | `/usr/bin/security` | An accessible login keychain; macOS may prompt for access or unlock |
+| Linux | Secret Service, such as GNOME Keyring or compatible KWallet | `/usr/bin/secret-tool` | libsecret tools, a session D-Bus, and a running Secret Service provider |
+| Windows | Credential Manager | Windows PowerShell and the Windows Credentials API | Windows PowerShell 5.1 with `Add-Type` permitted and a credential-capable user logon session |
+
+The JavaScript package contains no native binaries. Windows uses a bundled PowerShell script with an embedded C# P/Invoke bridge, compiled by the OS's `Add-Type`. This requires no downloaded module or developer toolchain, but is not JavaScript-only execution. Restricted PowerShell environments may block it; just-secrets does not bypass those restrictions.
+
+On Debian/Ubuntu, install Linux prerequisites with:
+
+```sh
+sudo apt-get install libsecret-tools gnome-keyring
+```
+
+Installing the tools is not enough: a session bus and unlocked credential service must also be available. Headless containers, SSH sessions, and WSL often lack these. WSL uses the Linux backend; just-secrets does not automatically forward secrets to Windows. Unsupported operating systems reject without starting a subprocess.
+
+Windows credentials use `CRED_PERSIST_ENTERPRISE`: credentials persist for the user and may roam when supported by the account configuration.
+
+## Security model
+
+Secrets are encrypted at rest by the OS credential store. just-secrets never writes a plaintext vault, generates a file-encryption key, or falls back to weaker storage. It invokes known OS executables without a shell and sends secret input over pipes, not command-line arguments or environment variables. Internal encodings preserve exact strings; they are not encryption.
+
+Each subprocess has a 60-second timeout and a combined 1 MiB output limit. Child-process errors and output are not attached to thrown errors. Values are not cached between calls or logged by the library.
+
+This does not isolate secrets from malicious code running as the same OS user. On macOS, Keychain access is associated with `/usr/bin/security`, not a unique just-secrets application identity. Other programs invoking that tool can access items permitted to it. See [GitHub CLI's discussion of this tradeoff](https://github.com/cli/cli/blob/trunk/docs/macos-keyring.md). Windows and Linux access boundaries also depend on the user's session and store configuration.
+
+JavaScript and PowerShell strings cannot be reliably zeroized. Secrets exist in process memory while in use and may be exposed through debuggers, memory dumps, or compromised processes. Node copies some data internally; clearing individual buffers is not a complete memory-erasure guarantee. See [SECURITY.md](SECURITY.md).
+
+Linux explicitly checks and unlocks matching items before reading or deleting, rather than mistaking a locked item for absence. These multi-command operations are not transactional. Concurrent changes can cause rejection, and a timed-out or failed mutation may already have taken effect. Do not automatically retry mutations without checking the result.
+
+## Handling unavailable storage
+
+Storage failures never silently fall back to files. Applications can offer session-only credentials, ask the user to unlock their keychain, or explicitly accept an environment variable for CI:
+
+```js
+const token = process.env.MY_API_TOKEN ?? await secrets.get('com.example.cli', 'api-token');
+```
+
+Do not log secret values or arbitrary upstream error objects. just-secrets's operational errors carry a `code`:
+
+| Code | Meaning |
+| --- | --- |
+| `ERR_SECRETS_UNSUPPORTED` | Unsupported operating system |
+| `ERR_SECRETS_UNAVAILABLE` | Required executable or credential session unavailable |
+| `ERR_SECRETS_ACCESS_DENIED` | Access denied where the platform exposes a distinct status |
+| `ERR_SECRETS_TIMEOUT` | Credential operation exceeded its time limit |
+| `ERR_SECRETS_OUTPUT_LIMIT` | Unexpectedly large credential-tool output |
+| `ERR_SECRETS_STORE` | Other store failure or unexpected response |
+
+Not every backend can distinguish locked, denied, and unavailable states; these can surface as `ERR_SECRETS_STORE`. Callers should provide an unlock/setup recovery path rather than interpreting this code as absence.
+
+## Development
+
+Only Node.js 24+ and npm are required for development. There are no runtime or development npm dependencies.
+
+```sh
+npm ci
+npm test                  # node:test; injected adapters and real subprocess transport tests
+npm run test:coverage     # Node's built-in coverage
+npm run test:integration  # real native credential-store lifecycle
+npm run test:package      # pack, offline install, ESM/CommonJS import checks
+```
+
+Integration tests use a disposable keychain on macOS and UUID-namespaced credentials on Linux/Windows, with cleanup. They cover create, read, overwrite, delete, missing entries, Unicode, empty values, case-sensitive identity, and persistence across Node processes. They do not prove persistence across reboot.
+
+The GitHub Actions matrix runs Node 24 on Linux x64/ARM64, macOS Intel/Apple Silicon, and Windows x64. Linux CI starts an isolated GNOME Keyring session. Native Windows tests require the Windows runner; macOS and Linux mocks alone cannot validate the PowerShell bridge.
+
+## Publishing
+
+Repository: [vercel-labs/just-secrets](https://github.com/vercel-labs/just-secrets).
+
+After the full CI matrix passes, review the version and package contents, then publish using an npm account authorized for `just-secrets`:
+
+```sh
+npm run test:package
+npm pack --dry-run
+npm publish --access public
+```
+
+Publishing credentials and npm package ownership must be configured separately. This repository does not automatically publish on push.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security
+
+## Reporting vulnerabilities
+
+Do not post credentials or exploit details in a public issue. Report security vulnerabilities privately to [Vercel Security](https://vercel.com/security).
+
+## Boundaries
+
+- just-secrets stores credentials in the current user's native OS store. It is not a sandbox, secret broker, or defense against code running as that user.
+- On macOS, the trusted Keychain client is `/usr/bin/security`, not the JavaScript package or the calling application.
+- Linux requires a working Secret Service session. Windows requires a credential-capable logon session and permission to run the bundled PowerShell bridge.
+- Secrets travel through stdin/stdout pipes. They never enter subprocess arguments, generated script source, or library logs. Identifiers are not secrets and can appear in process arguments and native-store metadata.
+- There is no automatic plaintext, encrypted-file, memory-cache, or alternate-executable fallback.
+- The library bounds subprocess execution and output. It does not return captured stderr, stdout, or native exceptions in operational errors.
+- JavaScript and managed-runtime strings cannot be reliably erased. Debugging tools, crash dumps, OS audit tooling, or same-user malware may observe values while in use. Buffer cleanup does not guarantee complete zeroization.
+- The application remains responsible for avoiding secret disclosure after retrieval, choosing appropriate service/name scopes, controlling subprocess inheritance, and securing its dependencies and runtime.
+- Operations can fail after a mutation commits. Linux's search/unlock/read/delete sequence is not atomic, and timeouts do not imply rollback.
+
+## Review and tests
+
+Changes to subprocess invocation, encoding, error handling, or native bridges require regression tests. Run the native integration suite on every supported OS before release; mocked tests cannot validate OS access-control behavior. The package has no npm dependencies or install-time downloads.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "just-secrets",
+  "version": "0.0.1",
+  "description": "Native OS secret storage for Node.js. Zero dependencies.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:integration": "node --test --test-concurrency=1 test/native.integration.js",
+    "test:package": "node --test test/package.integration.js",
+    "test:coverage": "node --test --experimental-test-coverage test/*.test.js",
+    "prepack": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/just-secrets.git"
+  },
+  "homepage": "https://github.com/vercel-labs/just-secrets#readme",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/just-secrets/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "secrets",
+    "keychain",
+    "keyring",
+    "credentials",
+    "keytar",
+    "nodejs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/command.js

@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process';
+import { storeError } from './errors.js';
+
+// Deliberately private: public callers cannot choose an executable or disable limits.
+export function runCommand(executable, args, {
+  input = '', timeout = 60_000, maxOutput = 1024 * 1024,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(executable, args, {
+        shell: false,
+        windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // Do not load PowerShell profiles or permit cwd/PATH-based backend selection.
+        cwd: undefined,
+      });
+    } catch {
+      reject(storeError('Could not start the OS credential tool.', 'ERR_SECRETS_UNAVAILABLE'));
+      return;
+    }
+    const stdout = [], stderr = [];
+    let size = 0, failure, inputFailure, settled = false;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      for (const chunk of [...stdout, ...stderr]) chunk.fill(0);
+      stdout.length = stderr.length = 0;
+      if (error) reject(error);
+      else resolve(result);
+    };
+    const terminate = (error) => {
+      failure ??= error;
+      child.kill('SIGKILL');
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+      finish(failure);
+    };
+    const timer = setTimeout(() => terminate(storeError(
+      'The OS credential tool timed out. Unlock your credential store and retry.',
+      'ERR_SECRETS_TIMEOUT',
+    )), timeout);
+    for (const [stream, chunks] of [[child.stdout, stdout], [child.stderr, stderr]]) {
+      stream.on('data', (chunk) => {
+        if (settled) { chunk.fill(0); return; }
+        size += chunk.length;
+        if (size > maxOutput) {
+          chunk.fill(0);
+          terminate(storeError('The OS credential tool exceeded its output limit.', 'ERR_SECRETS_OUTPUT_LIMIT'));
+        } else chunks.push(chunk);
+      });
+      stream.on('error', () => terminate(storeError('Could not read the OS credential tool response.')));
+    }
+    child.on('error', (error) => {
+      const code = error.code === 'EACCES' || error.code === 'EPERM'
+        ? 'ERR_SECRETS_ACCESS_DENIED' : 'ERR_SECRETS_UNAVAILABLE';
+      finish(storeError('Could not start the OS credential tool. Check its installation and permissions.', code));
+    });
+    // Pipe error codes differ across platforms. Let the child report its own failure;
+    // a successful exit must not hide undelivered input. The timer still bounds the wait.
+    child.stdin.on('error', () => {
+      inputFailure = storeError('Could not send input to the OS credential tool.');
+    });
+    child.on('close', (code, signal) => {
+      if (settled) return;
+      if (signal !== null || !Number.isInteger(code)) {
+        finish(storeError('The OS credential tool terminated unexpectedly.'));
+        return;
+      }
+      if (code === 0 && inputFailure) {
+        finish(inputFailure);
+        return;
+      }
+      const out = Buffer.concat(stdout), err = Buffer.concat(stderr);
+      const result = { code, stdout: out.toString('utf8'), stderr: err.toString('utf8') };
+      out.fill(0);
+      err.fill(0);
+      finish(undefined, result);
+    });
+    child.stdin.end(input);
+  });
+}

package/src/errors.js

@@ -0,0 +1,3 @@
+export function storeError(message, code = 'ERR_SECRETS_STORE') {
+  return Object.assign(new Error(message), { code });
+}

package/src/index.d.ts

@@ -0,0 +1,20 @@
+/** Identifies a credential within a service. */
+export interface SecretsOptions {
+  service: string;
+  name: string;
+}
+
+export interface Secrets {
+  /** Returns the stored secret, or null when it does not exist. */
+  get(options: SecretsOptions): Promise<string | null>;
+  get(service: string, name: string): Promise<string | null>;
+  /** Creates or replaces a secret in the native credential store. */
+  set(options: SecretsOptions & { value: string }): Promise<void>;
+  set(service: string, name: string, value: string): Promise<void>;
+  /** Returns true when deleted, or false when it does not exist. */
+  delete(options: SecretsOptions): Promise<boolean>;
+  delete(service: string, name: string): Promise<boolean>;
+}
+
+/** Native secret storage for Node.js 24+, using OS-provided credential tools. */
+export declare const secrets: Secrets;

package/src/index.js

@@ -0,0 +1,3 @@
+import { createSecrets } from './secrets.js';
+
+export const secrets = createSecrets();

package/src/linux.js

@@ -0,0 +1,97 @@
+import { runCommand } from './command.js';
+import { storeError } from './errors.js';
+
+const executable = '/usr/bin/secret-tool';
+const message = 'Linux credential operation failed; ensure /usr/bin/secret-tool and an unlocked Secret Service session are available';
+const prefix = 'secrets:v1:';
+const transportCodes = new Set([
+  'ERR_SECRETS_UNAVAILABLE', 'ERR_SECRETS_TIMEOUT', 'ERR_SECRETS_OUTPUT_LIMIT',
+  'ERR_SECRETS_STORE', 'ERR_SECRETS_ACCESS_DENIED',
+]);
+
+// Storage format (not encryption): canonical base64 of UTF-8 after secrets:v1:.
+// Encode identifiers too: argv and libsecret attributes cannot represent NUL.
+function encode(value) {
+  return prefix + Buffer.from(value, 'utf8').toString('base64');
+}
+
+function decode(output) {
+  if (!output.startsWith(prefix) || output.length > prefix.length + 3416) {
+    throw storeError(message);
+  }
+  const encoded = output.slice(prefix.length);
+  const bytes = Buffer.from(encoded, 'base64');
+  // Buffer's base64 and UTF-8 decoders are permissive; require lossless canonical forms.
+  const value = bytes.toString('utf8');
+  if (bytes.length > 2560 || bytes.toString('base64') !== encoded
+    || !Buffer.from(value, 'utf8').equals(bytes)) {
+    throw storeError(message);
+  }
+  return value;
+}
+
+export function createLinuxBackend({ run = runCommand } = {}) {
+  async function request(operation, service, name, value) {
+    const attributes = ['application', 'secrets', 'service', encode(service), 'name', encode(name)];
+    let result;
+    try {
+      result = await run(executable, [
+        operation,
+        ...(operation === 'store' ? ['--label=secrets'] : operation === 'search' ? ['--all', '--unlock'] : []),
+        '--', ...attributes,
+      ], { input: operation === 'store' ? encode(value) : '' });
+    } catch (error) {
+      const code = transportCodes.has(error?.code) ? error.code
+        : error?.code === 'ENOENT' ? 'ERR_SECRETS_UNAVAILABLE'
+          : error?.code === 'EACCES' || error?.code === 'EPERM' ? 'ERR_SECRETS_ACCESS_DENIED'
+            : 'ERR_SECRETS_STORE';
+      throw storeError(message, code);
+    }
+    if (!result || !Number.isInteger(result.code)
+      || typeof result.stdout !== 'string' || typeof result.stderr !== 'string') {
+      throw storeError(message);
+    }
+    if (result.code !== 0) throw storeError(message);
+    if (operation === 'search') {
+      // secret-tool search prints attributes to stderr even on success. Accept
+      // only our exact encoded attributes; retrieval/unlock diagnostics fail closed.
+      const expected = new Set([0, 2, 4].map(i => `attribute.${attributes[i]} = ${attributes[i + 1]}\n`));
+      const lines = result.stderr.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+      if (lines.some(line => !expected.has(line))) throw storeError(message);
+      if (result.stdout === '' && result.stderr === '') return false;
+      // Search retrieves secrets into the bounded pipe, never logs them. Validate
+      // complete records so missing secrets (locked items) cannot look successful.
+      const record = /\[[^\r\n\]]+\]\nlabel = [^\r\n]*\nsecret = (secrets:v1:[A-Za-z0-9+/=]*)\ncreated = [^\r\n]*\nmodified = [^\r\n]*\n(?:schema = [^\r\n]*\n)?/gy;
+      let end = 0;
+      let match;
+      while ((match = record.exec(result.stdout)) !== null) {
+        decode(match[1]);
+        end = record.lastIndex;
+      }
+      if (end === 0 || end !== result.stdout.length) throw storeError(message);
+      return true;
+    }
+    // Never trim: even whitespace stderr is a diagnostic, not absence.
+    if (result.stderr !== '' || (operation !== 'lookup' && result.stdout !== '')) throw storeError(message);
+    return operation === 'lookup' ? decode(result.stdout) : true;
+  }
+
+  return {
+    async get(service, name) {
+      if (!await request('search', service, name)) return null;
+      return request('lookup', service, name);
+    },
+    async set(service, name, value) {
+      await request('store', service, name, value);
+    },
+    async delete(service, name) {
+      // clear ignores locked matches. Only an empty all-items search proves absence.
+      // These calls are not atomic: relocking/removal can cause an error after
+      // mutation, and a concurrent writer can recreate an item after the final check.
+      if (!await request('search', service, name)) return false;
+      await request('clear', service, name);
+      if (await request('search', service, name)) throw storeError(message);
+      return true;
+    },
+  };
+}

package/src/macos.js

@@ -0,0 +1,65 @@
+import { runCommand } from './command.js';
+import { storeError } from './errors.js';
+
+const executable = '/usr/bin/security';
+const prefix = 'secrets:v1:';
+const encode = (value) => prefix + Buffer.from(value, 'utf8').toString('base64');
+// security -i has its own parser, not a shell. Never allow a second input line.
+const quote = (value) => '"' + value.replaceAll('\\', '\\\\').replaceAll('"', '\\"') + '"';
+const message = 'macOS Keychain operation failed. Check Keychain access and unlock your login keychain.';
+
+export function createMacosBackend({ run = runCommand, keychain = 'login.keychain-db' } = {}) {
+  if (/[\r\n\0]/u.test(keychain)) throw new TypeError('Invalid keychain path.');
+  const attributes = (service, name) => ['-s', encode(service), '-a', encode(name)];
+  function check(result, absent = false) {
+    if (absent && result.code === 44) return false;
+    if (result.code !== 0) {
+      const code = result.code === 36 || result.code === 128
+        ? 'ERR_SECRETS_ACCESS_DENIED' : 'ERR_SECRETS_STORE';
+      throw storeError(message, code);
+    }
+    return true;
+  }
+  // security can report errSecItemNotFound even when the keychain itself is missing.
+  const ready = async () => check(await run(executable, ['-q', 'show-keychain-info', keychain]));
+  return {
+    async get(service, name) {
+      await ready();
+      const result = await run(executable, [
+        '-q', 'find-generic-password', ...attributes(service, name), '-w', keychain,
+      ]);
+      if (!check(result, true)) return null;
+      const output = result.stdout.replace(/\n$/u, '');
+      if (!output.startsWith(prefix)) throw storeError(message);
+      const encoded = output.slice(prefix.length);
+      const bytes = Buffer.from(encoded, 'base64');
+      const value = bytes.toString('utf8');
+      if (bytes.length > 2560 || bytes.toString('base64') !== encoded
+        || !Buffer.from(value, 'utf8').equals(bytes)) throw storeError(message);
+      return value;
+    },
+    async set(service, name, value) {
+      const input = [
+        'add-generic-password', '-U', ...attributes(service, name),
+        '-w', encode(value), keychain,
+      ].map(quote).join(' ') + '\n';
+      // Apple's interactive reader uses a fixed 4096-byte buffer. Reject before spawning,
+      // rather than letting a truncated write succeed or become a second command.
+      if (Buffer.byteLength(input) >= 4096) {
+        throw new RangeError('The combined service, name, and value exceed the macOS command limit.');
+      }
+      await ready();
+      const result = await run(executable, ['-q', '-i'], { input });
+      check(result);
+      // Some security subcommands return -1, which interactive mode converts to success.
+      if (result.stderr !== '' || result.stdout !== '') throw storeError(message);
+    },
+    async delete(service, name) {
+      await ready();
+      const result = await run(executable, [
+        '-q', 'delete-generic-password', ...attributes(service, name), keychain,
+      ]);
+      return check(result, true);
+    },
+  };
+}

package/src/secrets.js

@@ -0,0 +1,53 @@
+import { createMacosBackend } from './macos.js';
+import { createLinuxBackend } from './linux.js';
+import { createWindowsBackend } from './windows.js';
+import { storeError } from './errors.js';
+
+function validate(value, field, limit) {
+  if (typeof value !== 'string') throw new TypeError(`${field} must be a string.`);
+  if (!value.isWellFormed()) throw new TypeError(`${field} must contain valid Unicode.`);
+  if (field !== 'value' && value.length === 0) throw new TypeError(`${field} must not be empty.`);
+  if (Buffer.byteLength(value, 'utf8') > limit) {
+    throw new RangeError(`${field} must not exceed ${limit} UTF-8 bytes.`);
+  }
+  return value;
+}
+
+function parse(args, write) {
+  const object = args[0] !== null && typeof args[0] === 'object' && !Array.isArray(args[0]);
+  if (args.length !== (object ? 1 : write ? 3 : 2)) {
+    throw new TypeError('Expected an options object or service, name' + (write ? ', value.' : '.'));
+  }
+  const options = object ? args[0] : { service: args[0], name: args[1], value: args[2] };
+  return [validate(options.service, 'service', 256), validate(options.name, 'name', 256),
+    ...(write ? [validate(options.value, 'value', 2560)] : [])];
+}
+
+function systemBackend() {
+  switch (process.platform) {
+    case 'darwin': return createMacosBackend();
+    case 'linux': return createLinuxBackend();
+    case 'win32': return createWindowsBackend();
+    default: throw storeError('Native secret storage is supported on macOS, Linux, and Windows.', 'ERR_SECRETS_UNSUPPORTED');
+  }
+}
+
+// Factories are internal test seams, not package exports. No secret values are cached.
+export function createSecrets(resolveBackend = systemBackend) {
+  let backend;
+  const getBackend = () => backend ??= resolveBackend();
+  return Object.freeze({
+    async get(...args) {
+      const input = parse(args, false);
+      return getBackend().get(...input);
+    },
+    async set(...args) {
+      const input = parse(args, true);
+      await getBackend().set(...input);
+    },
+    async delete(...args) {
+      const input = parse(args, false);
+      return getBackend().delete(...input);
+    },
+  });
+}

package/src/windows.js

@@ -0,0 +1,63 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { runCommand } from './command.js';
+import { storeError } from './errors.js';
+
+const script = new URL('./windows.ps1', import.meta.url);
+const message = 'Windows credential operation failed';
+const transportCodes = new Set([
+  'ERR_SECRETS_UNAVAILABLE', 'ERR_SECRETS_TIMEOUT', 'ERR_SECRETS_OUTPUT_LIMIT',
+  'ERR_SECRETS_STORE', 'ERR_SECRETS_ACCESS_DENIED',
+]);
+
+export function createWindowsBackend({ run = runCommand } = {}) {
+  let command;
+  async function request(operation, service, name, value) {
+    const root = process.env.SystemRoot ?? process.env.SYSTEMROOT;
+    if (typeof root !== 'string' || !/^[a-z]:\\/i.test(root) || root.includes('\0')) {
+      throw storeError('Windows PowerShell is unavailable', 'ERR_SECRETS_UNAVAILABLE');
+    }
+    const executable = path.win32.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    let result;
+    try {
+      // Fixed source only: -Command works under the default Restricted file policy.
+      // Credential data remains on stdin, never interpolated into source or argv.
+      command ??= readFile(script, 'utf8').then(source => Buffer.from(source, 'utf16le').toString('base64'));
+      result = await run(executable, [
+        '-NoLogo', '-NoProfile', '-NonInteractive', '-InputFormat', 'Text', '-OutputFormat', 'Text',
+        '-EncodedCommand', await command,
+      ], { input: JSON.stringify({ operation, service, name, ...(operation === 'set' ? { value } : {}) }) });
+    } catch (error) {
+      throw storeError(message, transportCodes.has(error?.code) ? error.code : 'ERR_SECRETS_STORE');
+    }
+    let response;
+    try {
+      if (!result || !Number.isInteger(result.code) || typeof result.stdout !== 'string') throw null;
+      response = JSON.parse(result.stdout);
+      if (!response || typeof response !== 'object' || Array.isArray(response) || Object.keys(response).length !== 1) throw null;
+    } catch {
+      throw storeError(message);
+    }
+    if (result.code !== 0) {
+      if (response.error === 1168 && operation !== 'set') return operation === 'get' ? null : false;
+      const code = response.error === 5 ? 'ERR_SECRETS_ACCESS_DENIED'
+        : response.error === 1312 || response.error === 50 || response.error === 'ERR_SECRETS_UNAVAILABLE'
+          ? 'ERR_SECRETS_UNAVAILABLE' : 'ERR_SECRETS_STORE';
+      throw storeError(message, code);
+    }
+    if (result.stderr !== '' || !Object.hasOwn(response, 'value')) throw storeError(message);
+    if (operation === 'get') {
+      if (response.value !== null && (typeof response.value !== 'string'
+        || !response.value.isWellFormed() || Buffer.byteLength(response.value, 'utf8') > 2560)) throw storeError(message);
+      return response.value;
+    }
+    if (operation === 'delete' && typeof response.value === 'boolean') return response.value;
+    if (operation === 'set' && response.value === true) return;
+    throw storeError(message);
+  }
+  return {
+    get: (service, name) => request('get', service, name),
+    set: (service, name, value) => request('set', service, name, value),
+    delete: (service, name) => request('delete', service, name),
+  };
+}

package/src/windows.ps1

@@ -0,0 +1,138 @@
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+try {
+    if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') {
+        throw 'Unavailable'
+    }
+    [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false, $true)
+    [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false, $true)
+    Add-Type -TypeDefinition @'
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class SecretsCredentials {
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    private struct Credential {
+        public uint Flags;
+        public uint Type;
+        public IntPtr TargetName;
+        public IntPtr Comment;
+        public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+        public uint CredentialBlobSize;
+        public IntPtr CredentialBlob;
+        public uint Persist;
+        public uint AttributeCount;
+        public IntPtr Attributes;
+        public IntPtr TargetAlias;
+        public IntPtr UserName;
+    }
+
+    [DllImport("advapi32.dll", EntryPoint = "CredWriteW", CharSet = CharSet.Unicode, ExactSpelling = true, SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool CredWrite(ref Credential credential, uint flags);
+    [DllImport("advapi32.dll", EntryPoint = "CredReadW", CharSet = CharSet.Unicode, ExactSpelling = true, SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool CredRead(string target, uint type, uint flags, out IntPtr credential);
+    [DllImport("advapi32.dll", EntryPoint = "CredDeleteW", CharSet = CharSet.Unicode, ExactSpelling = true, SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool CredDelete(string target, uint type, uint flags);
+    [DllImport("advapi32.dll", ExactSpelling = true)]
+    private static extern void CredFree(IntPtr credential);
+
+    private static readonly Encoding Utf8 = new UTF8Encoding(false, true);
+    private static void Zero(IntPtr pointer, int length) {
+        if (pointer != IntPtr.Zero) for (int i = 0; i < length; i++) Marshal.WriteByte(pointer, i, 0);
+    }
+    public static string Target(string service, string name) {
+        // Length framing avoids both delimiter collisions and JSON serializer differences.
+        byte[] a = Utf8.GetBytes(service), b = Utf8.GetBytes(name);
+        if (a.Length > 256 || b.Length > 256) throw new ArgumentException();
+        byte[] framed = new byte[4 + a.Length + b.Length];
+        framed[0] = (byte)(a.Length >> 8); framed[1] = (byte)a.Length;
+        framed[2] = (byte)(b.Length >> 8); framed[3] = (byte)b.Length;
+        Buffer.BlockCopy(a, 0, framed, 4, a.Length);
+        Buffer.BlockCopy(b, 0, framed, 4 + a.Length, b.Length);
+        // Credential targets are case-insensitive; hex preserves identity under case folding.
+        string target = "secrets:" + BitConverter.ToString(framed).Replace("-", "").ToLowerInvariant();
+        if (target.Length > 32767) throw new ArgumentException();
+        return target;
+    }
+    public static void Write(string target, string value) {
+        byte[] bytes = Utf8.GetBytes(value);
+        IntPtr blob = IntPtr.Zero, targetPointer = IntPtr.Zero;
+        try {
+            if (bytes.Length > 2560) throw new ArgumentException();
+            targetPointer = Marshal.StringToCoTaskMemUni(target);
+            // Allocate one byte even for an empty secret; its native length remains zero.
+            blob = Marshal.AllocHGlobal(Math.Max(1, bytes.Length));
+            Marshal.WriteByte(blob, 0, 0);
+            if (bytes.Length != 0) Marshal.Copy(bytes, 0, blob, bytes.Length);
+            Credential credential = new Credential {
+                Type = 1, TargetName = targetPointer, CredentialBlob = blob,
+                CredentialBlobSize = (uint)bytes.Length, Persist = 3
+            };
+            if (!CredWrite(ref credential, 0)) throw new Win32Exception(Marshal.GetLastWin32Error());
+        } finally {
+            if (blob != IntPtr.Zero) { Zero(blob, Math.Max(1, bytes.Length)); Marshal.FreeHGlobal(blob); }
+            if (targetPointer != IntPtr.Zero) Marshal.ZeroFreeCoTaskMemUnicode(targetPointer);
+            Array.Clear(bytes, 0, bytes.Length);
+        }
+    }
+    public static string Read(string target) {
+        IntPtr pointer = IntPtr.Zero;
+        Credential credential = new Credential();
+        byte[] bytes = null;
+        try {
+            if (!CredRead(target, 1, 0, out pointer)) throw new Win32Exception(Marshal.GetLastWin32Error());
+            credential = (Credential)Marshal.PtrToStructure(pointer, typeof(Credential));
+            if (credential.CredentialBlobSize > 2560 || (credential.CredentialBlobSize != 0 && credential.CredentialBlob == IntPtr.Zero)) throw new ArgumentException();
+            bytes = new byte[(int)credential.CredentialBlobSize];
+            if (bytes.Length != 0) Marshal.Copy(credential.CredentialBlob, bytes, 0, bytes.Length);
+            return Utf8.GetString(bytes);
+        } finally {
+            if (bytes != null) Array.Clear(bytes, 0, bytes.Length);
+            if (pointer != IntPtr.Zero) {
+                try {
+                    // Rejected native lengths must not turn cleanup into an unbounded write.
+                    Zero(credential.CredentialBlob, (int)Math.Min(credential.CredentialBlobSize, 2560u));
+                } finally { CredFree(pointer); }
+            }
+        }
+    }
+    public static bool Delete(string target) {
+        if (!CredDelete(target, 1, 0)) throw new Win32Exception(Marshal.GetLastWin32Error());
+        return true;
+    }
+}
+'@
+    $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+    if ($request.service -isnot [string] -or $request.name -isnot [string]) { throw 'Invalid request' }
+    $target = [SecretsCredentials]::Target($request.service, $request.name)
+    switch -CaseSensitive ($request.operation) {
+        'get' { $value = [SecretsCredentials]::Read($target) }
+        'set' {
+            if ($request.value -isnot [string]) { throw 'Invalid request' }
+            [SecretsCredentials]::Write($target, $request.value)
+            $value = $true
+        }
+        'delete' { $value = [SecretsCredentials]::Delete($target) }
+        default { throw 'Invalid request' }
+    }
+    [Console]::Out.WriteLine((ConvertTo-Json -Compress -InputObject @{ value = $value }))
+    exit 0
+} catch {
+    # Never serialize exception messages: native and PowerShell errors can contain input.
+    $code = 'ERR_SECRETS_STORE'
+    if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') {
+        # Full-language APIs may themselves be forbidden, so use only a fixed ASCII literal.
+        Write-Output '{"error":"ERR_SECRETS_UNAVAILABLE"}'
+        exit 1
+    }
+    $exception = $_.Exception
+    while ($null -ne $exception.InnerException) { $exception = $exception.InnerException }
+    if ($exception -is [System.ComponentModel.Win32Exception]) { $code = $exception.NativeErrorCode }
+    [Console]::Out.WriteLine((ConvertTo-Json -Compress -InputObject @{ error = $code }))
+    exit 1
+}