@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/secrets/keychain.js

@@ -0,0 +1,328 @@
+"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 keychain_exports = {};
+__export(keychain_exports, {
+  clearCache: () => clearCache,
+  deleteSecret: () => deleteSecret,
+  deleteSecretFromSlots: () => deleteSecretFromSlots,
+  deleteSecretFromSlotsSync: () => deleteSecretFromSlotsSync,
+  deleteSecretSync: () => deleteSecretSync,
+  detectPlatform: () => detectPlatform,
+  getBackendAvailability: () => getBackendAvailability,
+  readSecret: () => readSecret,
+  readSecretFromSlots: () => readSecretFromSlots,
+  readSecretFromSlotsSync: () => readSecretFromSlotsSync,
+  readSecretSync: () => readSecretSync,
+  writeSecret: () => writeSecret,
+  writeSecretSync: () => writeSecretSync,
+  writeSecretToSlots: () => writeSecretToSlots,
+  writeSecretToSlotsSync: () => writeSecretToSlotsSync
+});
+module.exports = __toCommonJS(keychain_exports);
+var import_node_os = require("node:os");
+var import_internal = require("./_internal");
+var import_macos = require("./macos");
+var import_linux = require("./linux");
+var import_windows = require("./windows");
+function clearCache() {
+  (0, import_internal.invalidateAll)();
+}
+async function deleteSecret({
+  service,
+  account
+}) {
+  let outcome;
+  switch (detectPlatform()) {
+    case "darwin":
+      outcome = await (0, import_macos.deleteMacOS)(service, account);
+      break;
+    case "linux":
+      outcome = await (0, import_linux.deleteLinux)(service, account);
+      break;
+    case "win32":
+      outcome = await (0, import_windows.deleteWindows)(service, account);
+      break;
+    default:
+      outcome = "absent";
+  }
+  (0, import_internal.invalidate)(service, account);
+  return outcome;
+}
+async function deleteSecretFromSlots({
+  service,
+  accounts
+}) {
+  const results = [];
+  for (const account of accounts) {
+    const outcome = await deleteSecret({ service, account });
+    results.push({ account, outcome });
+  }
+  return results;
+}
+function deleteSecretFromSlotsSync({
+  service,
+  accounts
+}) {
+  const results = [];
+  for (const account of accounts) {
+    const outcome = deleteSecretSync({ service, account });
+    results.push({ account, outcome });
+  }
+  return results;
+}
+function deleteSecretSync({
+  service,
+  account
+}) {
+  let outcome;
+  switch (detectPlatform()) {
+    case "darwin":
+      outcome = (0, import_macos.deleteMacOSSync)(service, account);
+      break;
+    case "linux":
+      outcome = (0, import_linux.deleteLinuxSync)(service, account);
+      break;
+    case "win32":
+      outcome = (0, import_windows.deleteWindowsSync)(service, account);
+      break;
+    default:
+      outcome = "absent";
+  }
+  (0, import_internal.invalidate)(service, account);
+  return outcome;
+}
+function detectPlatform() {
+  const p = (0, import_node_os.platform)();
+  if (p === "darwin" || p === "linux" || p === "win32") {
+    return p;
+  }
+  return "other";
+}
+function getBackendAvailability() {
+  const platform_ = detectPlatform();
+  switch (platform_) {
+    case "darwin": {
+      return {
+        available: (0, import_macos.isMacOSBackendAvailable)(),
+        toolName: "security(1)",
+        installHint: void 0
+      };
+    }
+    case "linux": {
+      const available = (0, import_linux.isLinuxBackendAvailable)();
+      return {
+        available,
+        toolName: "secret-tool",
+        installHint: available ? void 0 : "apt install libsecret-tools  (Debian/Ubuntu) | dnf install libsecret  (Fedora/RHEL)"
+      };
+    }
+    case "win32": {
+      return {
+        available: (0, import_windows.isWindowsBackendAvailable)(),
+        toolName: "PowerShell (CredentialManager / DPAPI)",
+        installHint: void 0
+      };
+    }
+    default:
+      return {
+        available: false,
+        toolName: "n/a",
+        installHint: `Platform ${(0, import_node_os.platform)()} is not supported.`
+      };
+  }
+}
+async function readSecret({
+  service,
+  account
+}) {
+  return (0, import_internal.dedupeRead)(service, account, async () => {
+    switch (detectPlatform()) {
+      case "darwin":
+        return (0, import_macos.readMacOS)(service, account);
+      case "linux":
+        return (0, import_linux.readLinux)(service, account);
+      case "win32":
+        return (0, import_windows.readWindows)(service, account);
+      default:
+        return void 0;
+    }
+  });
+}
+async function readSecretFromSlots({
+  service,
+  accounts
+}) {
+  for (const account of accounts) {
+    const value = await readSecret({ service, account });
+    if (value) {
+      return { value, account };
+    }
+  }
+  return void 0;
+}
+function readSecretFromSlotsSync({
+  service,
+  accounts
+}) {
+  for (const account of accounts) {
+    const value = readSecretSync({ service, account });
+    if (value) {
+      return { value, account };
+    }
+  }
+  return void 0;
+}
+function readSecretSync({
+  service,
+  account
+}) {
+  if ((0, import_internal.has)(service, account)) {
+    return (0, import_internal.getCached)(service, account);
+  }
+  let value;
+  switch (detectPlatform()) {
+    case "darwin":
+      value = (0, import_macos.readMacOSSync)(service, account);
+      break;
+    case "linux":
+      value = (0, import_linux.readLinuxSync)(service, account);
+      break;
+    case "win32":
+      value = (0, import_windows.readWindowsSync)(service, account);
+      break;
+    default:
+      value = void 0;
+  }
+  (0, import_internal.setCached)(service, account, value);
+  return value;
+}
+async function writeSecret({
+  service,
+  account,
+  value,
+  label
+}) {
+  if (!value || typeof value !== "string") {
+    throw new TypeError("writeSecret: value must be a non-empty string");
+  }
+  const platform_ = detectPlatform();
+  if (platform_ === "other") {
+    throw new Error(
+      `Unsupported platform: ${(0, import_node_os.platform)()}. Secret storage requires macOS, Linux, or Windows.`
+    );
+  }
+  const current = await readSecret({ service, account });
+  if (current === value) {
+    return "unchanged";
+  }
+  const lbl = label ?? `${service} credential`;
+  switch (platform_) {
+    case "darwin":
+      await (0, import_macos.writeMacOS)(service, account, value, lbl);
+      break;
+    case "linux":
+      await (0, import_linux.writeLinux)(service, account, value, lbl);
+      break;
+    case "win32":
+      await (0, import_windows.writeWindows)(service, account, value, lbl);
+      break;
+  }
+  (0, import_internal.setCached)(service, account, value);
+  return "written";
+}
+function writeSecretSync({
+  service,
+  account,
+  value,
+  label
+}) {
+  if (!value || typeof value !== "string") {
+    throw new TypeError("writeSecret: value must be a non-empty string");
+  }
+  const platform_ = detectPlatform();
+  if (platform_ === "other") {
+    throw new Error(
+      `Unsupported platform: ${(0, import_node_os.platform)()}. Secret storage requires macOS, Linux, or Windows.`
+    );
+  }
+  const current = readSecretSync({ service, account });
+  if (current === value) {
+    return "unchanged";
+  }
+  const lbl = label ?? `${service} credential`;
+  switch (platform_) {
+    case "darwin":
+      (0, import_macos.writeMacOSSync)(service, account, value, lbl);
+      break;
+    case "linux":
+      (0, import_linux.writeLinuxSync)(service, account, value, lbl);
+      break;
+    case "win32":
+      (0, import_windows.writeWindowsSync)(service, account, value, lbl);
+      break;
+  }
+  (0, import_internal.setCached)(service, account, value);
+  return "written";
+}
+async function writeSecretToSlots({
+  service,
+  accounts,
+  value,
+  label
+}) {
+  const results = [];
+  for (const account of accounts) {
+    const outcome = await writeSecret({ service, account, value, label });
+    results.push({ account, outcome });
+  }
+  return results;
+}
+function writeSecretToSlotsSync({
+  service,
+  accounts,
+  value,
+  label
+}) {
+  const results = [];
+  for (const account of accounts) {
+    const outcome = writeSecretSync({ service, account, value, label });
+    results.push({ account, outcome });
+  }
+  return results;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearCache,
+  deleteSecret,
+  deleteSecretFromSlots,
+  deleteSecretFromSlotsSync,
+  deleteSecretSync,
+  detectPlatform,
+  getBackendAvailability,
+  readSecret,
+  readSecretFromSlots,
+  readSecretFromSlotsSync,
+  readSecretSync,
+  writeSecret,
+  writeSecretSync,
+  writeSecretToSlots,
+  writeSecretToSlotsSync
+});

package/dist/secrets/linux.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Linux Secret Service backend via `secret-tool`. `secret-tool` is the
+ *   user-facing CLI for libsecret, which talks to any running Secret Service
+ *   provider (gnome-keyring, kwallet5, KeePassXC's Secret Service integration,
+ *   etc.). Most desktop Linux installs have one; headless / containerized hosts
+ *   do not. Storage shape: each item has a `service=<svc> user=<account>`
+ *   attribute pair plus the password body. Reads + writes use those two
+ *   attributes as the lookup key. The label (`--label`) is what shows up in the
+ *   user's keyring UI; we set it to the same string passed in by the caller. No
+ *   backing-file fallback. If `secret-tool` isn't on PATH or no Secret Service
+ *   provider is running, reads return `undefined` and writes throw with an
+ *   actionable hint — callers fall back to env variables for that session.
+ */
+export declare function deleteLinux(service: string, account: string): Promise<'removed' | 'absent'>;
+export declare function deleteLinuxSync(service: string, account: string): 'removed' | 'absent';
+export declare function isLinuxBackendAvailable(): boolean;
+export declare function readLinux(service: string, account: string): Promise<string | undefined>;
+export declare function readLinuxSync(service: string, account: string): string | undefined;
+export declare function writeLinux(service: string, account: string, value: string, label: string): Promise<void>;
+export declare function writeLinuxSync(service: string, account: string, value: string, label: string): void;

package/dist/secrets/linux.js

@@ -0,0 +1,151 @@
+"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 linux_exports = {};
+__export(linux_exports, {
+  deleteLinux: () => deleteLinux,
+  deleteLinuxSync: () => deleteLinuxSync,
+  isLinuxBackendAvailable: () => isLinuxBackendAvailable,
+  readLinux: () => readLinux,
+  readLinuxSync: () => readLinuxSync,
+  writeLinux: () => writeLinux,
+  writeLinuxSync: () => writeLinuxSync
+});
+module.exports = __toCommonJS(linux_exports);
+var import_node_child_process = require("node:child_process");
+const SECRET_TOOL_BIN = "secret-tool";
+async function deleteLinux(service, account) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(
+      SECRET_TOOL_BIN,
+      ["clear", "service", service, "user", account],
+      { stdio: "ignore" }
+    );
+    child.on("error", () => resolve("absent"));
+    child.on("close", (status) => resolve(status === 0 ? "removed" : "absent"));
+  });
+}
+function deleteLinuxSync(service, account) {
+  const r = (0, import_node_child_process.spawnSync)(
+    SECRET_TOOL_BIN,
+    ["clear", "service", service, "user", account],
+    { stdio: "ignore" }
+  );
+  return r.status === 0 ? "removed" : "absent";
+}
+function isLinuxBackendAvailable() {
+  const r = (0, import_node_child_process.spawnSync)(SECRET_TOOL_BIN, ["--version"], { stdio: "ignore" });
+  return r.status === 0;
+}
+async function readLinux(service, account) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(
+      SECRET_TOOL_BIN,
+      ["lookup", "service", service, "user", account],
+      { stdio: ["ignore", "pipe", "pipe"] }
+    );
+    let stdout = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.on("error", () => resolve(void 0));
+    child.on("close", (status) => {
+      if (status !== 0) {
+        resolve(void 0);
+        return;
+      }
+      const out = stdout.trim();
+      resolve(out || void 0);
+    });
+  });
+}
+function readLinuxSync(service, account) {
+  const r = (0, import_node_child_process.spawnSync)(
+    SECRET_TOOL_BIN,
+    ["lookup", "service", service, "user", account],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
+  );
+  if (r.status !== 0) {
+    return void 0;
+  }
+  const out = r.stdout.trim();
+  return out || void 0;
+}
+async function writeLinux(service, account, value, label) {
+  return new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process.spawn)(
+      SECRET_TOOL_BIN,
+      ["store", `--label=${label}`, "service", service, "user", account],
+      { stdio: ["pipe", "pipe", "pipe"] }
+    );
+    let stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on(
+      "error",
+      (err) => reject(
+        new Error(
+          `secret-tool store failed: ${err.message}. Install libsecret-tools (apt install libsecret-tools / dnf install libsecret) or ensure a Secret Service provider (gnome-keyring, kwallet) is running.`
+        )
+      )
+    );
+    child.on("close", (status) => {
+      if (status === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(
+          `secret-tool store failed (status=${status}, user=${account}): ${stderr.trim()}. Install libsecret-tools (apt install libsecret-tools / dnf install libsecret) or ensure a Secret Service provider (gnome-keyring, kwallet) is running.`
+        )
+      );
+    });
+    child.stdin.end(value);
+  });
+}
+function writeLinuxSync(service, account, value, label) {
+  const r = (0, import_node_child_process.spawnSync)(
+    SECRET_TOOL_BIN,
+    ["store", `--label=${label}`, "service", service, "user", account],
+    {
+      encoding: "utf8",
+      input: value,
+      stdio: ["pipe", "pipe", "pipe"]
+    }
+  );
+  if (r.status !== 0) {
+    throw new Error(
+      `secret-tool store failed (status=${r.status}, user=${account}): ${r.stderr.trim()}. Install libsecret-tools (apt install libsecret-tools / dnf install libsecret) or ensure a Secret Service provider (gnome-keyring, kwallet) is running.`
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deleteLinux,
+  deleteLinuxSync,
+  isLinuxBackendAvailable,
+  readLinux,
+  readLinuxSync,
+  writeLinux,
+  writeLinuxSync
+});

package/dist/secrets/macos.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file MacOS Keychain backend via `security(1)`. The native `security` CLI
+ *   ships with macOS — no install step. We use generic-password items, which
+ *   are the simplest credential shape Keychain supports (service + account →
+ *   password string). Process model: each call spawns `security`. Read returns
+ *   the password on stdout; write uses `-w <value>` (we accept that the value
+ *   briefly appears in argv — `security` is local-only and runs in the user's
+ *   session, so the leakage surface is `ps(1)` for one other process on the
+ *   same user). Delete is best-effort. ACL: writes use `-A -T ''` so any
+ *   application on the user's account can read the entry without an extra
+ *   Keychain prompt. The first write still prompts once (creating / updating
+ *   the entry requires the user to authorize that one action), but every later
+ *   read is silent — sfw, socket-cli, MCP servers, and the bash shell itself
+ *   all read the same value with no UI. The trust model: the user explicitly
+ *   authorized the install flow that wrote this; the value is theirs to use
+ *   across their tooling, not a credential earmarked for a single binary path.
+ *   Revocable in Keychain Access.app if the user changes their mind. This
+ *   restores the original wheelhouse `token-storage.mts` behavior dropped in
+ *   v6's first cut.
+ */
+export declare function deleteMacOS(service: string, account: string): Promise<'removed' | 'absent'>;
+export declare function deleteMacOSSync(service: string, account: string): 'removed' | 'absent';
+export declare function isMacOSBackendAvailable(): boolean;
+export declare function readMacOS(service: string, account: string): Promise<string | undefined>;
+export declare function readMacOSSync(service: string, account: string): string | undefined;
+interface SpawnOpts {
+    stdio?: 'ignore' | 'pipe' | ['ignore', 'pipe', 'pipe'];
+}
+export declare function runAsync(args: readonly string[], opts?: SpawnOpts): Promise<{
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+export declare function writeMacOS(service: string, account: string, value: string, label: string): Promise<void>;
+export declare function writeMacOSSync(service: string, account: string, value: string, label: string): void;
+export {};

package/dist/secrets/macos.js

@@ -0,0 +1,165 @@
+"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 macos_exports = {};
+__export(macos_exports, {
+  deleteMacOS: () => deleteMacOS,
+  deleteMacOSSync: () => deleteMacOSSync,
+  isMacOSBackendAvailable: () => isMacOSBackendAvailable,
+  readMacOS: () => readMacOS,
+  readMacOSSync: () => readMacOSSync,
+  runAsync: () => runAsync,
+  writeMacOS: () => writeMacOS,
+  writeMacOSSync: () => writeMacOSSync
+});
+module.exports = __toCommonJS(macos_exports);
+var import_node_child_process = require("node:child_process");
+const SECURITY_BIN = "security";
+async function deleteMacOS(service, account) {
+  const r = await runAsync(
+    ["delete-generic-password", "-s", service, "-a", account],
+    { stdio: "ignore" }
+  );
+  return r.status === 0 ? "removed" : "absent";
+}
+function deleteMacOSSync(service, account) {
+  const r = (0, import_node_child_process.spawnSync)(
+    SECURITY_BIN,
+    ["delete-generic-password", "-s", service, "-a", account],
+    { stdio: "ignore" }
+  );
+  return r.status === 0 ? "removed" : "absent";
+}
+function isMacOSBackendAvailable() {
+  return true;
+}
+async function readMacOS(service, account) {
+  const r = await runAsync([
+    "find-generic-password",
+    "-s",
+    service,
+    "-a",
+    account,
+    "-w"
+  ]);
+  if (r.status !== 0) {
+    return void 0;
+  }
+  const out = r.stdout.trim();
+  return out || void 0;
+}
+function readMacOSSync(service, account) {
+  const r = (0, import_node_child_process.spawnSync)(
+    SECURITY_BIN,
+    ["find-generic-password", "-s", service, "-a", account, "-w"],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
+  );
+  if (r.status !== 0) {
+    return void 0;
+  }
+  const out = r.stdout.trim();
+  return out || void 0;
+}
+function runAsync(args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(SECURITY_BIN, args, {
+      stdio: opts.stdio ?? ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    if (child.stdout) {
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+      });
+    }
+    if (child.stderr) {
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+      });
+    }
+    child.on("error", () => resolve({ status: -1, stdout, stderr }));
+    child.on("close", (status) => resolve({ status, stdout, stderr }));
+  });
+}
+async function writeMacOS(service, account, value, label) {
+  const r = await runAsync([
+    "add-generic-password",
+    "-U",
+    "-A",
+    "-T",
+    "",
+    "-s",
+    service,
+    "-a",
+    account,
+    "-w",
+    value,
+    "-D",
+    label,
+    "-l",
+    label
+  ]);
+  if (r.status !== 0) {
+    throw new Error(
+      `security(1) add-generic-password failed (status=${r.status}, account=${account}): ${r.stderr.trim()}`
+    );
+  }
+}
+function writeMacOSSync(service, account, value, label) {
+  const r = (0, import_node_child_process.spawnSync)(
+    SECURITY_BIN,
+    [
+      "add-generic-password",
+      "-U",
+      "-A",
+      "-T",
+      "",
+      "-s",
+      service,
+      "-a",
+      account,
+      "-w",
+      value,
+      "-D",
+      label,
+      "-l",
+      label
+    ],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
+  );
+  if (r.status !== 0) {
+    throw new Error(
+      `security(1) add-generic-password failed (status=${r.status}, account=${account}): ${r.stderr.trim()}`
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deleteMacOS,
+  deleteMacOSSync,
+  isMacOSBackendAvailable,
+  readMacOS,
+  readMacOSSync,
+  runAsync,
+  writeMacOS,
+  writeMacOSSync
+});