@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/schema/validate.d.ts

@@ -1,34 +1,57 @@
 /**
- * @fileoverview Universal schema validator — non-throwing.
+ * @file Universal schema validator — non-throwing. Accepts any Zod-shaped
+ *   schema (`.safeParse`-exposing) and returns a tagged result `{ ok: true,
+ *   value } | { ok: false, errors }` with normalized `{ path, message }`
+ *   issues. No runtime dependency on `zod` — detection is purely structural.
  *
- * Accepts any Zod-shaped schema (`.safeParse`-exposing) and returns a tagged
- * result `{ ok: true, value } | { ok: false, errors }` with normalized
- * `{ path, message }` issues. No runtime dependency on `zod` — detection
- * is purely structural.
+ * @example
+ *   ;```ts
+ *   import { z } from 'zod'
+ *   import { validateSchema } from '@socketsecurity/lib/schema/validate'
+ *
+ *   const User = z.object({ name: z.string() })
+ *   const r = validateSchema(User, data)
+ *   if (r.ok)
+ *     r.value.name // string
+ *   else r.errors // ValidationIssue[]
+ *   ```
  *
  * @internal
  * socket-lib additionally recognizes TypeBox schemas for its own internal
  * use (e.g. `src/ipc.ts`'s stub-file validation). That path is not a
  * supported consumer API.
+ */
+import type { Infer, ValidateResult, ValidationIssue } from './types';
+/**
+ * Detect a TypeBox schema structurally: object with a symbol key whose
+ * description is `'TypeBox.Kind'`, holding a string value.
  *
- * @example
- * ```ts
- * import { z } from 'zod'
- * import { validateSchema } from '@socketsecurity/lib/schema/validate'
- *
- * const User = z.object({ name: z.string() })
- * const r = validateSchema(User, data)
- * if (r.ok) r.value.name // string
- * else r.errors           // ValidationIssue[]
- * ```
+ * @internal
+ */
+export declare function isTypeBoxSchema(schema: unknown): boolean;
+/**
+ * Normalize a TypeBox `ValueError` iterator into plain issues. TypeBox paths
+ * are JSON Pointers (`/user/0/name`); convert to arrays.
+ *
+ * @internal
+ */
+export declare function normalizeTypeBoxErrors(errors: Iterable<{
+    path: string;
+    message: string;
+}>): ValidationIssue[];
+/**
+ * Normalize a Zod error object (v3 or v4) into plain issues. Both versions
+ * expose `.issues: Array<{ path, message }>`.
+ *
+ * @internal
  */
-import type { Infer, ValidateResult } from './types';
+export declare function normalizeZodError(err: unknown): ValidationIssue[];
 /**
  * Validate `data` against a Zod-style `schema`. Non-throwing.
  *
- * The return type narrows `value` to `Infer<S>`, so callers get
- * `z.infer<typeof S>` with no casts. Errors are normalized to
- * `{ path, message }` regardless of the underlying validator.
+ * The return type narrows `value` to `Infer<S>`, so callers get `z.infer<typeof
+ * S>` with no casts. Errors are normalized to `{ path, message }` regardless of
+ * the underlying validator.
  *
  * @throws {TypeError} When `schema` is not a recognized validator kind.
  */

package/dist/schema/validate.js

@@ -20,15 +20,21 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var validate_exports = {};
 __export(validate_exports, {
+  isTypeBoxSchema: () => isTypeBoxSchema,
+  normalizeTypeBoxErrors: () => normalizeTypeBoxErrors,
+  normalizeZodError: () => normalizeZodError,
   validateSchema: () => validateSchema
 });
 module.exports = __toCommonJS(validate_exports);
-var import_primordials = require("../primordials");
+var import_array = require("../primordials/array");
+var import_error = require("../primordials/error");
+var import_number = require("../primordials/number");
+var import_object = require("../primordials/object");
 function isTypeBoxSchema(schema) {
   if (schema === null || typeof schema !== "object") {
     return false;
   }
-  for (const sym of (0, import_primordials.ObjectGetOwnPropertySymbols)(schema)) {
+  for (const sym of (0, import_object.ObjectGetOwnPropertySymbols)(schema)) {
     if (sym.description === "TypeBox.Kind") {
       return typeof schema[sym] === "string";
     }
@@ -42,7 +48,7 @@ function normalizeTypeBoxErrors(errors) {
     out.push({
       path: segs.map((s) => {
         const n = Number(s);
-        return (0, import_primordials.NumberIsInteger)(n) && String(n) === s ? n : s;
+        return (0, import_number.NumberIsInteger)(n) && String(n) === s ? n : s;
       }),
       message: err.message
     });
@@ -54,13 +60,13 @@ function normalizeZodError(err) {
     return [{ path: [], message: String(err) }];
   }
   const issues = err.issues;
-  if (!(0, import_primordials.ArrayIsArray)(issues)) {
+  if (!(0, import_array.ArrayIsArray)(issues)) {
     return [{ path: [], message: "Unknown validation error" }];
   }
   return issues.map((issue) => {
     const i = issue;
     return {
-      path: (0, import_primordials.ArrayIsArray)(i.path) ? i.path : [],
+      path: (0, import_array.ArrayIsArray)(i.path) ? i.path : [],
       message: typeof i.message === "string" ? i.message : "Invalid value"
     };
   });
@@ -89,11 +95,14 @@ function validateSchema(schema, data) {
       errors: normalizeZodError(result.error)
     };
   }
-  throw new import_primordials.TypeErrorCtor(
+  throw new import_error.TypeErrorCtor(
     "validateSchema: unsupported schema kind. Expected a Zod schema or an object with a safeParse method."
   );
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  isTypeBoxSchema,
+  normalizeTypeBoxErrors,
+  normalizeZodError,
   validateSchema
 });

package/dist/sea/detect.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file SEA (Single Executable Application) binary detection + path accessor.
+ *   Two responsibilities (mirror of `src/smol/detect.ts` shape):
+ *
+ *   1. `isSeaBinary()` — memoized boolean detector for whether the current process
+ *      is running as a Node.js Single Executable Application. Probes via Node
+ *      24+'s `node:sea.isSea()` native API; falls back to `false` on older
+ *      runtimes.
+ *   2. `getSeaBinaryPath()` — returns the path of the SEA binary
+ *      (`process.argv[0]` normalized) when running as SEA, otherwise
+ *      `undefined`. Defensive across runtimes: returns `false` / `undefined`
+ *      cleanly on stock Node < 24, browsers, Deno, Bun.
+ */
+/**
+ * Get the current SEA binary path. Only valid when running as a SEA binary.
+ *
+ * @example
+ *   ```typescript
+ *   const binPath = getSeaBinaryPath()
+ *   if (binPath) {
+ *   console.log(`Running as SEA binary: ${binPath}`)
+ *   }
+ *   ```
+ */
+export declare function getSeaBinaryPath(): string | undefined;
+/**
+ * Detect if the current process is running as a SEA binary. Uses Node.js 24+
+ * native API with caching for performance.
+ *
+ * @example
+ *   ;```typescript
+ *   if (isSeaBinary()) {
+ *     console.log('Running as a Single Executable Application')
+ *   }
+ *   ```
+ */
+export declare function isSeaBinary(): boolean;

package/dist/sea/{util.js → detect.js}

@@ -28,15 +28,18 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var util_exports = {};
-__export(util_exports, {
+var detect_exports = {};
+__export(detect_exports, {
   getSeaBinaryPath: () => getSeaBinaryPath,
   isSeaBinary: () => isSeaBinary
 });
-module.exports = __toCommonJS(util_exports);
+module.exports = __toCommonJS(detect_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_normalize = require("../paths/normalize");
 let _isSea;
+function getSeaBinaryPath() {
+  return isSeaBinary() && import_node_process.default.argv[0] ? (0, import_normalize.normalizePath)(import_node_process.default.argv[0]) : void 0;
+}
 function isSeaBinary() {
   if (_isSea === void 0) {
     try {
@@ -48,9 +51,6 @@ function isSeaBinary() {
   }
   return _isSea ?? false;
 }
-function getSeaBinaryPath() {
-  return isSeaBinary() && import_node_process.default.argv[0] ? (0, import_normalize.normalizePath)(import_node_process.default.argv[0]) : void 0;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getSeaBinaryPath,

package/dist/secrets/_internal.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Private internals for `secrets/` — process-scoped read cache for the
+ *   keychain backend. Underscore-prefixed and skipped by the export generator
+ *   (`dist/**\/_*` ignore pattern in
+ *   `scripts/fix/generate-package-exports.mts`) so this module is NOT part of
+ *   the public API surface. Imported by `./keychain.ts`. Every `readSecret`
+ *   call shells out to the OS credential CLI (`security`, `secret-tool`,
+ *   PowerShell). On macOS, the first read of a given entry by a new binary path
+ *   triggers a Keychain auth prompt unless the entry was written with `-A -T
+ *   ''` (which we now do — see `./macos.ts`). Even so, every read is a process
+ *   spawn, which costs a few ms per call. For tools that read the same secret
+ *   multiple times within one process (CLI commands handling multiple
+ *   subcommands, MCP request handlers serving sibling endpoints), a
+ *   process-scoped cache eliminates the redundant work. Lifetime: a single Node
+ *   process. The cache lives in module-level state; importing this module from
+ *   a child process gets a fresh cache. No persistence to disk — for that, see
+ *   `./rc.ts` which materializes a one-time `export` block into the shell rc.
+ *   Invalidation: callers MUST invalidate the cache when they write/delete the
+ *   same `{service, account}` pair. The public keychain.ts wraps writeSecret /
+ *   deleteSecret so cache eviction happens automatically. Concurrency:
+ *   in-flight reads of the same key share a single Promise so two `await
+ *   readSecret(...)` calls don't spawn two `security` processes for the same
+ *   entry. Once the Promise resolves, the value is cached. If the read returns
+ *   undefined (entry missing), `undefined` is cached too — callers that want a
+ *   re-check after creating the entry must call `invalidate`.
+ */
+export declare function cacheKey(service: string, account: string): string;
+/**
+ * Coordinate concurrent reads of the same key. The first caller registers a
+ * Promise; subsequent callers receive the same Promise instead of spawning
+ * another OS call. On settle, the Promise's inflight slot is dropped and the
+ * value is cached.
+ */
+export declare function dedupeRead(service: string, account: string, reader: () => Promise<string | undefined>): Promise<string | undefined>;
+/**
+ * Look up a cached value. Returns `undefined` for both "cached as absent" and
+ * "not yet cached" — callers that need to distinguish those cases should use
+ * `has` first.
+ */
+export declare function getCached(service: string, account: string): string | undefined;
+export declare function has(service: string, account: string): boolean;
+/**
+ * Drop a cached value. Called by `writeSecret` / `deleteSecret` after the
+ * underlying OS state changes so a subsequent `readSecret` reflects the new
+ * reality. Also called by `invalidateAll()` for service-wide refreshes.
+ */
+export declare function invalidate(service: string, account: string): void;
+/**
+ * Wipe the entire cache. Tests use this between cases; consumers generally
+ * don't need it (process exit drops the cache anyway).
+ */
+export declare function invalidateAll(): void;
+/**
+ * Store a value (or `undefined` to record an absent entry) so later reads of
+ * the same key short-circuit the OS call.
+ */
+export declare function setCached(service: string, account: string, value: string | undefined): void;

package/dist/secrets/_internal.js

@@ -0,0 +1,84 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var internal_exports = {};
+__export(internal_exports, {
+  cacheKey: () => cacheKey,
+  dedupeRead: () => dedupeRead,
+  getCached: () => getCached,
+  has: () => has,
+  invalidate: () => invalidate,
+  invalidateAll: () => invalidateAll,
+  setCached: () => setCached
+});
+module.exports = __toCommonJS(internal_exports);
+const valueCache = /* @__PURE__ */ new Map();
+const inflight = /* @__PURE__ */ new Map();
+function cacheKey(service, account) {
+  return `${service} ${account}`;
+}
+async function dedupeRead(service, account, reader) {
+  const key = cacheKey(service, account);
+  if (valueCache.has(key)) {
+    return valueCache.get(key);
+  }
+  const existing = inflight.get(key);
+  if (existing) {
+    return existing;
+  }
+  const promise = (async () => {
+    try {
+      const value = await reader();
+      valueCache.set(key, value);
+      return value;
+    } finally {
+      inflight.delete(key);
+    }
+  })();
+  inflight.set(key, promise);
+  return promise;
+}
+function getCached(service, account) {
+  return valueCache.get(cacheKey(service, account));
+}
+function has(service, account) {
+  return valueCache.has(cacheKey(service, account));
+}
+function invalidate(service, account) {
+  valueCache.delete(cacheKey(service, account));
+  inflight.delete(cacheKey(service, account));
+}
+function invalidateAll() {
+  valueCache.clear();
+  inflight.clear();
+}
+function setCached(service, account, value) {
+  valueCache.set(cacheKey(service, account), value);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cacheKey,
+  dedupeRead,
+  getCached,
+  has,
+  invalidate,
+  invalidateAll,
+  setCached
+});

package/dist/secrets/find.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @file Resolve a secret from the canonical fleet precedence order: process env
+ *   → OS keychain. Returns the value + the source it came from so the caller
+ *   can log which slot won. Why a helper instead of inlining: every consumer of
+ *   the fleet's Socket API token does the same dance — check
+ *   `process.env.SOCKET_API_TOKEN`, fall back to a legacy env-var alias, fall
+ *   back to `readSecret({...})` from the keychain. Tools drift on the exact
+ *   order and on which aliases they consider. This helper centralizes the
+ *   precedence so a token check in socket-cli, socket-mcp, depot, and ad-hoc
+ *   scripts all behave the same way. Not included: `.env` file parsing. Hosts
+ *   that want `.env` support should pre-populate `process.env` from `.env`
+ *   themselves (e.g. with `dotenv.config()` at process start). Folding `.env`
+ *   reads into this helper would couple the secrets API to a config-file parser
+ *   that's better lived at the application boundary. Prompt minimization: every
+ *   keychain read short-circuits through the process-scoped cache in
+ *   `./_internal.ts`. So calling `resolve` multiple times in one process spawns
+ *   at most one `security` (macOS) / `secret-tool` (Linux) / `powershell`
+ *   (Windows) per `{service, account}` pair. Combined with macOS's `-A -T ''`
+ *   ACL (set by `writeSecret`), this means: at most one Keychain auth prompt
+ *   across a process's entire lifetime — and zero prompts when the env-var path
+ *   covers the read.
+ */
+export interface ResolveOptions {
+    /**
+     * Logical service identifier for the keychain lookup. Same value the caller
+     * would pass to `writeSecret` / `readSecret`. Ignored when the env-var path
+     * resolves the value first.
+     */
+    service: string;
+    /**
+     * Names to try, in order. Each name is checked as both an env-var
+     * (`process.env[name]`) and a keychain account name. Env-var matches always
+     * beat keychain matches (env-var is cheaper and doesn't risk a Keychain
+     * prompt).
+     *
+     * Order matters: list the canonical name first so a legacy alias is only
+     * consulted when the canonical entry is missing.
+     */
+    accounts: readonly string[];
+    /**
+     * When `true`, skip the keychain fallback entirely. The resolver checks
+     * `process.env[account]` for each account and returns `undefined` immediately
+     * if none match. Use this in headless contexts (CI runners, bootstrap hooks)
+     * where a Keychain auth prompt is unacceptable.
+     *
+     * @default false
+     */
+    allowEnvOnly?: boolean | undefined;
+}
+export interface ResolveResult {
+    value: string;
+    /**
+     * Where the value came from: 'env' — `process.env[<account>]` had a non-empty
+     * value. 'keychain' — env-var was empty/missing; the value was read from the
+     * OS credential store under the matching account.
+     */
+    source: 'env' | 'keychain';
+    /**
+     * Which account in `accounts` was the actual hit.
+     */
+    account: string;
+}
+/**
+ * Pull a non-empty string from `process.env[name]`. Returns `undefined` for
+ * missing or empty values so the caller can fall through to the next source
+ * without distinguishing the two cases.
+ */
+export declare function readEnv(name: string): string | undefined;
+/**
+ * Resolve a secret following the canonical env → keychain order. Returns
+ * `undefined` when neither source has the value — the caller's signal to prompt
+ * the user or surface a setup hint.
+ */
+export declare function resolve(opts: ResolveOptions): Promise<ResolveResult | undefined>;
+/**
+ * Sync variant for non-async callers (hook initializers, schema validators that
+ * run before any `await` machinery exists).
+ */
+export declare function resolveSync(opts: ResolveOptions): ResolveResult | undefined;

package/dist/secrets/find.js

@@ -0,0 +1,84 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var find_exports = {};
+__export(find_exports, {
+  readEnv: () => readEnv,
+  resolve: () => resolve,
+  resolveSync: () => resolveSync
+});
+module.exports = __toCommonJS(find_exports);
+var import_keychain = require("./keychain");
+function readEnv(name) {
+  const value = process.env[name];
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+async function resolve(opts) {
+  const { accounts, allowEnvOnly, service } = opts;
+  for (let i = 0, { length } = accounts; i < length; i += 1) {
+    const account = accounts[i];
+    const fromEnv = readEnv(account);
+    if (fromEnv) {
+      return { value: fromEnv, source: "env", account };
+    }
+  }
+  if (allowEnvOnly) {
+    return void 0;
+  }
+  for (let i = 0, { length } = accounts; i < length; i += 1) {
+    const account = accounts[i];
+    const fromKeychain = await (0, import_keychain.readSecret)({ service, account });
+    if (fromKeychain) {
+      return { value: fromKeychain, source: "keychain", account };
+    }
+  }
+  return void 0;
+}
+function resolveSync(opts) {
+  const { accounts, allowEnvOnly, service } = opts;
+  for (let i = 0, { length } = accounts; i < length; i += 1) {
+    const account = accounts[i];
+    const fromEnv = readEnv(account);
+    if (fromEnv) {
+      return { value: fromEnv, source: "env", account };
+    }
+  }
+  if (allowEnvOnly) {
+    return void 0;
+  }
+  for (let i = 0, { length } = accounts; i < length; i += 1) {
+    const account = accounts[i];
+    const fromKeychain = (0, import_keychain.readSecretSync)({ service, account });
+    if (fromKeychain) {
+      return { value: fromKeychain, source: "keychain", account };
+    }
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  readEnv,
+  resolve,
+  resolveSync
+});

package/dist/secrets/keychain.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @file Cross-platform secret-storage helper. Reads / writes to the native OS
+ *   credential store (Keychain on macOS, Secret Service via libsecret on Linux,
+ *   Credential Manager + DPAPI on Windows). Consumers pick their own `{
+ *   service, account }` pair. API shape: readSecret({ service, account }) →
+ *   Promise<string | undefined> readSecretSync({ service, account }) → string |
+ *   undefined writeSecret({ service, account, value }) → Promise<void>
+ *   writeSecretSync({ service, account, value }) → void deleteSecret({ service,
+ *   account }) → Promise<'removed' | 'absent'> deleteSecretSync({ service,
+ *   account }) → 'removed' | 'absent' Multi-slot helpers exist for the common
+ *   case of writing the same value under multiple account names (e.g.
+ *   SOCKET_API_TOKEN + SOCKET_API_KEY for backwards compatibility):
+ *   readSecretFromSlots({ service, accounts }) writeSecretToSlots({ service,
+ *   accounts, value }) deleteSecretFromSlots({ service, accounts }) IMPORTANT:
+ *   do NOT invoke these helpers from a shell rc / .zshenv file (or any other
+ *   always-on-startup hook). On macOS each call triggers a Keychain auth
+ *   prompt; piling that into per-shell startup floods the user with prompts.
+ *   Use `write` from `./rc` to write a one-time literal `export` block into the
+ *   user's shell rc file instead. (Incident memory: socket-cli session
+ *   2026-05-15.)
+ */
+import type { BackendAvailability, SecretDeleteResult, SecretWriteResult } from './types';
+/**
+ * Drop the in-process read cache. Tests use this between cases to force a fresh
+ * OS call; production code generally doesn't need it (process exit drops the
+ * cache anyway, and `writeSecret` / `deleteSecret` already invalidate per-key
+ * entries automatically).
+ */
+export declare function clearCache(): void;
+export interface DeleteOptions {
+    service: string;
+    account: string;
+}
+/**
+ * Remove a secret from the OS credential store. Idempotent — succeeds whether
+ * the entry exists or not. Returns the per-slot outcome so callers can log
+ * "actually removed X" vs "X was already absent."
+ */
+export declare function deleteSecret({ service, account, }: DeleteOptions): Promise<'removed' | 'absent'>;
+export interface DeleteFromSlotsOptions {
+    service: string;
+    accounts: readonly string[];
+}
+export declare function deleteSecretFromSlots({ service, accounts, }: DeleteFromSlotsOptions): Promise<SecretDeleteResult[]>;
+export declare function deleteSecretFromSlotsSync({ service, accounts, }: DeleteFromSlotsOptions): SecretDeleteResult[];
+export declare function deleteSecretSync({ service, account, }: DeleteOptions): 'removed' | 'absent';
+export type { BackendAvailability, SecretDeleteResult, SecretWriteResult, } from './types';
+export type { SecretSlot } from './types';
+type Platform = 'darwin' | 'linux' | 'win32' | 'other';
+/**
+ * Resolve the current OS to one of our four backend categories.
+ *
+ * Exported only because the fleet's `export-top-level-functions` lint rule
+ * requires top-level functions to be exported for testability. Not part of the
+ * public `secrets/keychain` API surface — consumers should call `readSecret` /
+ * `writeSecret` / `getBackendAvailability` instead, which handle the dispatch
+ * internally.
+ *
+ * @internal
+ */
+export declare function detectPlatform(): Platform;
+/**
+ * Diagnostic: tell the operator whether the OS credential backend is reachable.
+ * Used by installers to report up-front (before any prompt fires) when
+ * libsecret-tools or the CredentialManager module aren't installed.
+ */
+export declare function getBackendAvailability(): BackendAvailability;
+export interface ReadOptions {
+    service: string;
+    account: string;
+}
+/**
+ * Read a single secret value from the OS credential store. Returns `undefined`
+ * when the entry doesn't exist OR when the backend tool isn't available — read
+ * paths never throw, so callers can fall through to env / .env / prompt
+ * cleanly.
+ */
+export declare function readSecret({ service, account, }: ReadOptions): Promise<string | undefined>;
+export interface ReadFromSlotsOptions {
+    service: string;
+    accounts: readonly string[];
+}
+/**
+ * Read from the first matching account. Used when multiple env-var names map to
+ * the same logical secret (e.g. SOCKET_API_TOKEN canonical + SOCKET_API_KEY
+ * legacy). Returns the value AND the account it came from so callers can warn
+ * on legacy hits.
+ */
+export declare function readSecretFromSlots({ service, accounts, }: ReadFromSlotsOptions): Promise<{
+    value: string;
+    account: string;
+} | undefined>;
+export declare function readSecretFromSlotsSync({ service, accounts, }: ReadFromSlotsOptions): {
+    value: string;
+    account: string;
+} | undefined;
+export declare function readSecretSync({ service, account, }: ReadOptions): string | undefined;
+export interface WriteOptions {
+    service: string;
+    account: string;
+    value: string;
+    /**
+     * Display label shown in Keychain Access.app / GNOME keyring etc. Defaults to
+     * `<service> credential`. Per-secret labels make the keyring UI navigable
+     * when a service has multiple entries.
+     */
+    label?: string | undefined;
+}
+/**
+ * Persist a single secret to the OS credential store. Throws on write failure —
+ * the caller is in a setup flow and should see why persistence failed, not
+ * silently continue.
+ *
+ * Returns the outcome: - `'written'` — value persisted (entry was absent or
+ * differed). - `'unchanged'` — current stored value already matches; no OS
+ * write performed. Useful for idempotent flows (re-running an installer
+ * shouldn't show "rewrote N secrets" when nothing actually changed).
+ */
+export declare function writeSecret({ service, account, value, label, }: WriteOptions): Promise<'written' | 'unchanged'>;
+export declare function writeSecretSync({ service, account, value, label, }: WriteOptions): 'written' | 'unchanged';
+export interface WriteToSlotsOptions {
+    service: string;
+    accounts: readonly string[];
+    value: string;
+    label?: string | undefined;
+}
+/**
+ * Persist the same value under each account name in `accounts`. Useful when a
+ * value needs to be reachable under several env-var names (legacy aliases,
+ * sibling tools). Each slot gets its own keychain entry — they all hold the
+ * same string.
+ *
+ * If any individual write throws, prior writes have already persisted. Failures
+ * aren't rolled back (the half-state is at worst a stale legacy alias, which
+ * the next successful write cleans up).
+ */
+export declare function writeSecretToSlots({ service, accounts, value, label, }: WriteToSlotsOptions): Promise<SecretWriteResult[]>;
+export declare function writeSecretToSlotsSync({ service, accounts, value, label, }: WriteToSlotsOptions): SecretWriteResult[];