@topolo/sdk 0.19.0 → 0.20.0

package/dist/node/credential-store.cjs

@@ -28,11 +28,16 @@ __export(credential_store_exports, {
   clearProfileCredential: () => clearProfileCredential,
   configPath: () => configPath,
   contextKey: () => contextKey,
+  createPlatformInstallationSecretBackend: () => createPlatformInstallationSecretBackend,
   credentialSourceFromConfig: () => credentialSourceFromConfig,
+  deleteExternalAgentInstallation: () => deleteExternalAgentInstallation,
   envVarPrefix: () => envVarPrefix,
+  installationStorePath: () => installationStorePath,
+  listExternalAgentInstallations: () => listExternalAgentInstallations,
   normalizeEnvironment: () => normalizeEnvironment,
   profileForEnvironment: () => profileForEnvironment,
   readConfig: () => readConfig,
+  readExternalAgentInstallation: () => readExternalAgentInstallation,
   refreshContextCredentialIfNeeded: () => refreshContextCredentialIfNeeded,
   refreshCredentialIfNeeded: () => refreshCredentialIfNeeded,
   resolveAgentName: () => resolveAgentName,
@@ -43,13 +48,14 @@ __export(credential_store_exports, {
   topoloServiceOrigins: () => topoloServiceOrigins,
   writeConfig: () => writeConfig,
   writeContextCredential: () => writeContextCredential,
+  writeExternalAgentInstallation: () => writeExternalAgentInstallation,
   writeProfileConfig: () => writeProfileConfig
 });
 module.exports = __toCommonJS(credential_store_exports);
-var import_promises = require("fs/promises");
-var import_node_fs = require("fs");
-var import_node_os = require("os");
-var import_node_path = require("path");
+var import_promises2 = require("fs/promises");
+var import_node_fs2 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
 
 // src/errors.ts
 var TopoloSdkError = class extends Error {
@@ -468,6 +474,172 @@ function topoloServiceOrigins(serviceUrls, environment) {
   );
 }
 
+// src/node/installation-store.ts
+var import_node_child_process = require("child_process");
+var import_promises = require("fs/promises");
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var KEYCHAIN_SERVICE = "topolo-external-agent-installation";
+function installationStorePath() {
+  const override = process.env.TOPOLO_INSTALLATIONS_PATH?.trim();
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME || ((0, import_node_os.platform)() === "win32" ? (0, import_node_path.join)((0, import_node_os.homedir)(), "AppData", "Roaming") : (0, import_node_path.join)((0, import_node_os.homedir)(), ".config"));
+  return (0, import_node_path.join)(base, "topolo", "installations");
+}
+function installationPath(environment, id) {
+  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new TypeError("Installation id contains unsupported characters.");
+  return (0, import_node_path.join)(installationStorePath(), environment, `${id}.json`);
+}
+function accountName(environment, id) {
+  return `${environment}:${id}`;
+}
+function runOrThrow(result, operation) {
+  if (result.status !== 0) {
+    throw new Error(`${operation} failed: ${(result.stderr || result.error?.message || "platform credential store unavailable").trim()}`);
+  }
+  return result.stdout.trim();
+}
+function createPlatformInstallationSecretBackend(options = {}) {
+  const platform2 = options.platform ?? (0, import_node_os.platform)();
+  const spawn = options.spawn ?? ((command, args, spawnOptions) => (0, import_node_child_process.spawnSync)(command, args, spawnOptions));
+  const root = options.root ?? installationStorePath();
+  if (platform2 === "darwin") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("security", [
+          "add-generic-password",
+          "-U",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { input: `${value}
+`, encoding: "utf8" }), "macOS Keychain write");
+      },
+      async get(account) {
+        const result = spawn("security", [
+          "find-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { encoding: "utf8" });
+        if (result.status === 44) return null;
+        return runOrThrow(result, "macOS Keychain read");
+      },
+      async delete(account) {
+        const result = spawn("security", [
+          "delete-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE
+        ], { encoding: "utf8" });
+        if (result.status !== 44) runOrThrow(result, "macOS Keychain delete");
+      }
+    };
+  }
+  if (platform2 === "linux") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("secret-tool", [
+          "store",
+          "--label=Topolo external agent installation",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { input: value, encoding: "utf8" }), "Linux Secret Service write");
+      },
+      async get(account) {
+        const result = spawn("secret-tool", [
+          "lookup",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status === 1) return null;
+        return runOrThrow(result, "Linux Secret Service read");
+      },
+      async delete(account) {
+        const result = spawn("secret-tool", [
+          "clear",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status !== 1) runOrThrow(result, "Linux Secret Service delete");
+      }
+    };
+  }
+  if (platform2 === "win32") {
+    const secretPath = (account) => (0, import_node_path.join)(root, ".secrets", `${account.replace(":", "-")}.bin`);
+    const powershell = (script, path, input) => spawn(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", script],
+      { input, encoding: "utf8", env: { ...process.env, TOPOLO_SECRET_PATH: path } }
+    );
+    return {
+      async set(account, value) {
+        const path = secretPath(account);
+        await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$v=[Console]::In.ReadToEnd();$b=[Text.Encoding]::UTF8.GetBytes($v);$e=[Security.Cryptography.ProtectedData]::Protect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[IO.File]::WriteAllBytes($p,$e)";
+        runOrThrow(powershell(script, path, value), "Windows DPAPI write");
+      },
+      async get(account) {
+        const path = secretPath(account);
+        if (!(0, import_node_fs.existsSync)(path)) return null;
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$b=[IO.File]::ReadAllBytes($p);$d=[Security.Cryptography.ProtectedData]::Unprotect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Text.Encoding]::UTF8.GetString($d))";
+        return runOrThrow(powershell(script, path), "Windows DPAPI read");
+      },
+      async delete(account) {
+        await (0, import_promises.rm)(secretPath(account), { force: true });
+      }
+    };
+  }
+  throw new Error(`Secure external-agent installation storage is unsupported on ${platform2}.`);
+}
+async function writeExternalAgentInstallation(installation, secret, backend = createPlatformInstallationSecretBackend()) {
+  const path = installationPath(installation.environment, installation.id);
+  await backend.set(accountName(installation.environment, installation.id), JSON.stringify(secret));
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true, mode: 448 });
+    await (0, import_promises.writeFile)(temporary, `${JSON.stringify(installation, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    await (0, import_promises.rename)(temporary, path);
+    if ((0, import_node_os.platform)() !== "win32") await (0, import_promises.chmod)(path, 384);
+  } catch (error) {
+    await backend.delete(accountName(installation.environment, installation.id)).catch(() => void 0);
+    await (0, import_promises.rm)(temporary, { force: true });
+    throw error;
+  }
+}
+async function readExternalAgentInstallation(environment, id, backend = createPlatformInstallationSecretBackend()) {
+  const path = installationPath(environment, id);
+  if (!(0, import_node_fs.existsSync)(path)) return null;
+  const installation = JSON.parse(await (0, import_promises.readFile)(path, "utf8"));
+  const encodedSecret = await backend.get(accountName(environment, id));
+  if (!encodedSecret) throw new Error(`Protected secret is missing for installation ${id}.`);
+  return { installation, secret: JSON.parse(encodedSecret) };
+}
+async function listExternalAgentInstallations(environment) {
+  const directory = (0, import_node_path.join)(installationStorePath(), environment);
+  if (!(0, import_node_fs.existsSync)(directory)) return [];
+  const entries = await (0, import_promises.readdir)(directory, { withFileTypes: true });
+  const installations = await Promise.all(entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => JSON.parse(await (0, import_promises.readFile)((0, import_node_path.join)(directory, entry.name), "utf8"))));
+  return installations.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+async function deleteExternalAgentInstallation(environment, id, backend = createPlatformInstallationSecretBackend()) {
+  await backend.delete(accountName(environment, id));
+  await (0, import_promises.rm)(installationPath(environment, id), { force: true });
+}
+
 // src/node/credential-store.ts
 var TOPOLO_ENVIRONMENTS = TOPOLO_RUNTIME_ENVIRONMENTS;
 function contextKey(contextType, organizationId) {
@@ -477,14 +649,14 @@ var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
-  const base = process.env.XDG_CONFIG_HOME || ((0, import_node_os.platform)() === "win32" ? (0, import_node_path.join)((0, import_node_os.homedir)(), "AppData", "Roaming") : (0, import_node_path.join)((0, import_node_os.homedir)(), ".config"));
-  return (0, import_node_path.join)(base, "topolo", "config.json");
+  const base = process.env.XDG_CONFIG_HOME || ((0, import_node_os2.platform)() === "win32" ? (0, import_node_path2.join)((0, import_node_os2.homedir)(), "AppData", "Roaming") : (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".config"));
+  return (0, import_node_path2.join)(base, "topolo", "config.json");
 }
 async function readConfig() {
   const path = configPath();
-  if (!(0, import_node_fs.existsSync)(path)) return {};
+  if (!(0, import_node_fs2.existsSync)(path)) return {};
   try {
-    const raw = await (0, import_promises.readFile)(path, "utf8");
+    const raw = await (0, import_promises2.readFile)(path, "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -492,11 +664,11 @@ async function readConfig() {
 }
 async function writeConfig(config) {
   const path = configPath();
-  await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
-  await (0, import_promises.writeFile)(path, JSON.stringify(config, null, 2) + "\n", "utf8");
-  if ((0, import_node_os.platform)() !== "win32") {
+  await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(path), { recursive: true });
+  await (0, import_promises2.writeFile)(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  if ((0, import_node_os2.platform)() !== "win32") {
     try {
-      await (0, import_promises.chmod)(path, 384);
+      await (0, import_promises2.chmod)(path, 384);
     } catch {
     }
   }
@@ -612,18 +784,18 @@ var CONFIG_LOCK_TIMEOUT_MS = 5e3;
 var CONFIG_LOCK_STALE_MS = 12e4;
 async function withConfigWriteLock(operation) {
   const lockPath = `${configPath()}.lock`;
-  await (0, import_promises.mkdir)((0, import_node_path.dirname)(lockPath), { recursive: true });
+  await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(lockPath), { recursive: true });
   const startedAt = Date.now();
   while (true) {
     try {
-      await (0, import_promises.mkdir)(lockPath);
+      await (0, import_promises2.mkdir)(lockPath);
       break;
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       try {
-        const lock = await (0, import_promises.stat)(lockPath);
+        const lock = await (0, import_promises2.stat)(lockPath);
         if (Date.now() - lock.mtimeMs > CONFIG_LOCK_STALE_MS) {
-          await (0, import_promises.rm)(lockPath, { recursive: true, force: true });
+          await (0, import_promises2.rm)(lockPath, { recursive: true, force: true });
           continue;
         }
       } catch (inspectionError) {
@@ -639,7 +811,7 @@ async function withConfigWriteLock(operation) {
   try {
     return await operation();
   } finally {
-    await (0, import_promises.rm)(lockPath, { recursive: true, force: true });
+    await (0, import_promises2.rm)(lockPath, { recursive: true, force: true });
   }
 }
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
@@ -788,11 +960,16 @@ function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   clearProfileCredential,
   configPath,
   contextKey,
+  createPlatformInstallationSecretBackend,
   credentialSourceFromConfig,
+  deleteExternalAgentInstallation,
   envVarPrefix,
+  installationStorePath,
+  listExternalAgentInstallations,
   normalizeEnvironment,
   profileForEnvironment,
   readConfig,
+  readExternalAgentInstallation,
   refreshContextCredentialIfNeeded,
   refreshCredentialIfNeeded,
   resolveAgentName,
@@ -803,5 +980,6 @@ function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   topoloServiceOrigins,
   writeConfig,
   writeContextCredential,
+  writeExternalAgentInstallation,
   writeProfileConfig
 });

package/dist/node/credential-store.d.cts

@@ -1,3 +1,5 @@
+import { SpawnSyncReturns } from 'node:child_process';
+
 /**
  * Auth credential types used by the SDK.
  *
@@ -29,6 +31,48 @@ type TopoloRuntimeEnvironment = (typeof TOPOLO_RUNTIME_ENVIRONMENTS)[number];
 declare function assertTopoloServiceUrlEnvironment(service: string, value: string, environment: TopoloRuntimeEnvironment): string;
 declare function topoloServiceOrigins(serviceUrls: Record<string, string> | undefined, environment: TopoloRuntimeEnvironment): Record<string, string>;
 
+interface ExternalAgentInstallation {
+    id: string;
+    environment: TopoloRuntimeEnvironment;
+    organizationId: string;
+    principalId: string;
+    credentialId: string;
+    clientId: string;
+    displayName: string;
+    provider: string;
+    host: string;
+    model?: string;
+    dpopJkt: string;
+    createdAt: string;
+}
+interface ExternalAgentInstallationSecret {
+    clientSecret: string;
+    privateJwk: JsonWebKey;
+}
+interface InstallationSecretBackend {
+    set(account: string, value: string): Promise<void>;
+    get(account: string): Promise<string | null>;
+    delete(account: string): Promise<void>;
+}
+type Spawn = (command: string, args: string[], options: {
+    input?: string;
+    encoding: 'utf8';
+    env?: NodeJS.ProcessEnv;
+}) => SpawnSyncReturns<string>;
+declare function installationStorePath(): string;
+declare function createPlatformInstallationSecretBackend(options?: {
+    platform?: NodeJS.Platform;
+    spawn?: Spawn;
+    root?: string;
+}): InstallationSecretBackend;
+declare function writeExternalAgentInstallation(installation: ExternalAgentInstallation, secret: ExternalAgentInstallationSecret, backend?: InstallationSecretBackend): Promise<void>;
+declare function readExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<{
+    installation: ExternalAgentInstallation;
+    secret: ExternalAgentInstallationSecret;
+} | null>;
+declare function listExternalAgentInstallations(environment: TopoloRuntimeEnvironment): Promise<ExternalAgentInstallation[]>;
+declare function deleteExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<void>;
+
 /**
  * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
  *
@@ -122,4 +166,4 @@ declare function resolveServiceUrls(configUrls?: Record<string, string>, environ
 declare function assertServiceUrlForEnvironment(service: string, serviceUrl: string | undefined, environment?: TopoloEnvironment): void;
 declare function resolvedProfileConfig(config: TopoloConfig, environment?: TopoloEnvironment): TopoloEnvironmentProfile;
 
-export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, assertServiceUrlForEnvironment, assertTopoloServiceUrlEnvironment, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, topoloServiceOrigins, writeConfig, writeContextCredential, writeProfileConfig };
+export { ENVIRONMENT_DEFAULT_SERVICE_URLS, type ExternalAgentInstallation, type ExternalAgentInstallationSecret, type InstallationSecretBackend, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, assertServiceUrlForEnvironment, assertTopoloServiceUrlEnvironment, clearProfileCredential, configPath, contextKey, createPlatformInstallationSecretBackend, credentialSourceFromConfig, deleteExternalAgentInstallation, envVarPrefix, installationStorePath, listExternalAgentInstallations, normalizeEnvironment, profileForEnvironment, readConfig, readExternalAgentInstallation, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, topoloServiceOrigins, writeConfig, writeContextCredential, writeExternalAgentInstallation, writeProfileConfig };

package/dist/node/credential-store.d.ts

@@ -1,3 +1,5 @@
+import { SpawnSyncReturns } from 'node:child_process';
+
 /**
  * Auth credential types used by the SDK.
  *
@@ -29,6 +31,48 @@ type TopoloRuntimeEnvironment = (typeof TOPOLO_RUNTIME_ENVIRONMENTS)[number];
 declare function assertTopoloServiceUrlEnvironment(service: string, value: string, environment: TopoloRuntimeEnvironment): string;
 declare function topoloServiceOrigins(serviceUrls: Record<string, string> | undefined, environment: TopoloRuntimeEnvironment): Record<string, string>;
 
+interface ExternalAgentInstallation {
+    id: string;
+    environment: TopoloRuntimeEnvironment;
+    organizationId: string;
+    principalId: string;
+    credentialId: string;
+    clientId: string;
+    displayName: string;
+    provider: string;
+    host: string;
+    model?: string;
+    dpopJkt: string;
+    createdAt: string;
+}
+interface ExternalAgentInstallationSecret {
+    clientSecret: string;
+    privateJwk: JsonWebKey;
+}
+interface InstallationSecretBackend {
+    set(account: string, value: string): Promise<void>;
+    get(account: string): Promise<string | null>;
+    delete(account: string): Promise<void>;
+}
+type Spawn = (command: string, args: string[], options: {
+    input?: string;
+    encoding: 'utf8';
+    env?: NodeJS.ProcessEnv;
+}) => SpawnSyncReturns<string>;
+declare function installationStorePath(): string;
+declare function createPlatformInstallationSecretBackend(options?: {
+    platform?: NodeJS.Platform;
+    spawn?: Spawn;
+    root?: string;
+}): InstallationSecretBackend;
+declare function writeExternalAgentInstallation(installation: ExternalAgentInstallation, secret: ExternalAgentInstallationSecret, backend?: InstallationSecretBackend): Promise<void>;
+declare function readExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<{
+    installation: ExternalAgentInstallation;
+    secret: ExternalAgentInstallationSecret;
+} | null>;
+declare function listExternalAgentInstallations(environment: TopoloRuntimeEnvironment): Promise<ExternalAgentInstallation[]>;
+declare function deleteExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<void>;
+
 /**
  * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
  *
@@ -122,4 +166,4 @@ declare function resolveServiceUrls(configUrls?: Record<string, string>, environ
 declare function assertServiceUrlForEnvironment(service: string, serviceUrl: string | undefined, environment?: TopoloEnvironment): void;
 declare function resolvedProfileConfig(config: TopoloConfig, environment?: TopoloEnvironment): TopoloEnvironmentProfile;
 
-export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, assertServiceUrlForEnvironment, assertTopoloServiceUrlEnvironment, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, topoloServiceOrigins, writeConfig, writeContextCredential, writeProfileConfig };
+export { ENVIRONMENT_DEFAULT_SERVICE_URLS, type ExternalAgentInstallation, type ExternalAgentInstallationSecret, type InstallationSecretBackend, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, assertServiceUrlForEnvironment, assertTopoloServiceUrlEnvironment, clearProfileCredential, configPath, contextKey, createPlatformInstallationSecretBackend, credentialSourceFromConfig, deleteExternalAgentInstallation, envVarPrefix, installationStorePath, listExternalAgentInstallations, normalizeEnvironment, profileForEnvironment, readConfig, readExternalAgentInstallation, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, topoloServiceOrigins, writeConfig, writeContextCredential, writeExternalAgentInstallation, writeProfileConfig };

package/dist/node/credential-store.js

@@ -1,8 +1,8 @@
 // src/node/credential-store.ts
-import { mkdir, readFile, writeFile, chmod, rm, stat } from "fs/promises";
-import { existsSync } from "fs";
-import { homedir, platform } from "os";
-import { dirname, join } from "path";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, chmod as chmod2, rm as rm2, stat } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { homedir as homedir2, platform } from "os";
+import { dirname as dirname2, join as join2 } from "path";
 
 // src/errors.ts
 var TopoloSdkError = class extends Error {
@@ -421,6 +421,172 @@ function topoloServiceOrigins(serviceUrls, environment) {
   );
 }
 
+// src/node/installation-store.ts
+import { spawnSync } from "child_process";
+import { mkdir, readFile, readdir, rename, rm, writeFile, chmod } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir, platform as hostPlatform } from "os";
+import { dirname, join } from "path";
+var KEYCHAIN_SERVICE = "topolo-external-agent-installation";
+function installationStorePath() {
+  const override = process.env.TOPOLO_INSTALLATIONS_PATH?.trim();
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME || (hostPlatform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
+  return join(base, "topolo", "installations");
+}
+function installationPath(environment, id) {
+  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new TypeError("Installation id contains unsupported characters.");
+  return join(installationStorePath(), environment, `${id}.json`);
+}
+function accountName(environment, id) {
+  return `${environment}:${id}`;
+}
+function runOrThrow(result, operation) {
+  if (result.status !== 0) {
+    throw new Error(`${operation} failed: ${(result.stderr || result.error?.message || "platform credential store unavailable").trim()}`);
+  }
+  return result.stdout.trim();
+}
+function createPlatformInstallationSecretBackend(options = {}) {
+  const platform2 = options.platform ?? hostPlatform();
+  const spawn = options.spawn ?? ((command, args, spawnOptions) => spawnSync(command, args, spawnOptions));
+  const root = options.root ?? installationStorePath();
+  if (platform2 === "darwin") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("security", [
+          "add-generic-password",
+          "-U",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { input: `${value}
+`, encoding: "utf8" }), "macOS Keychain write");
+      },
+      async get(account) {
+        const result = spawn("security", [
+          "find-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { encoding: "utf8" });
+        if (result.status === 44) return null;
+        return runOrThrow(result, "macOS Keychain read");
+      },
+      async delete(account) {
+        const result = spawn("security", [
+          "delete-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE
+        ], { encoding: "utf8" });
+        if (result.status !== 44) runOrThrow(result, "macOS Keychain delete");
+      }
+    };
+  }
+  if (platform2 === "linux") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("secret-tool", [
+          "store",
+          "--label=Topolo external agent installation",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { input: value, encoding: "utf8" }), "Linux Secret Service write");
+      },
+      async get(account) {
+        const result = spawn("secret-tool", [
+          "lookup",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status === 1) return null;
+        return runOrThrow(result, "Linux Secret Service read");
+      },
+      async delete(account) {
+        const result = spawn("secret-tool", [
+          "clear",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status !== 1) runOrThrow(result, "Linux Secret Service delete");
+      }
+    };
+  }
+  if (platform2 === "win32") {
+    const secretPath = (account) => join(root, ".secrets", `${account.replace(":", "-")}.bin`);
+    const powershell = (script, path, input) => spawn(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", script],
+      { input, encoding: "utf8", env: { ...process.env, TOPOLO_SECRET_PATH: path } }
+    );
+    return {
+      async set(account, value) {
+        const path = secretPath(account);
+        await mkdir(dirname(path), { recursive: true });
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$v=[Console]::In.ReadToEnd();$b=[Text.Encoding]::UTF8.GetBytes($v);$e=[Security.Cryptography.ProtectedData]::Protect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[IO.File]::WriteAllBytes($p,$e)";
+        runOrThrow(powershell(script, path, value), "Windows DPAPI write");
+      },
+      async get(account) {
+        const path = secretPath(account);
+        if (!existsSync(path)) return null;
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$b=[IO.File]::ReadAllBytes($p);$d=[Security.Cryptography.ProtectedData]::Unprotect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Text.Encoding]::UTF8.GetString($d))";
+        return runOrThrow(powershell(script, path), "Windows DPAPI read");
+      },
+      async delete(account) {
+        await rm(secretPath(account), { force: true });
+      }
+    };
+  }
+  throw new Error(`Secure external-agent installation storage is unsupported on ${platform2}.`);
+}
+async function writeExternalAgentInstallation(installation, secret, backend = createPlatformInstallationSecretBackend()) {
+  const path = installationPath(installation.environment, installation.id);
+  await backend.set(accountName(installation.environment, installation.id), JSON.stringify(secret));
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    await mkdir(dirname(path), { recursive: true, mode: 448 });
+    await writeFile(temporary, `${JSON.stringify(installation, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    await rename(temporary, path);
+    if (hostPlatform() !== "win32") await chmod(path, 384);
+  } catch (error) {
+    await backend.delete(accountName(installation.environment, installation.id)).catch(() => void 0);
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+async function readExternalAgentInstallation(environment, id, backend = createPlatformInstallationSecretBackend()) {
+  const path = installationPath(environment, id);
+  if (!existsSync(path)) return null;
+  const installation = JSON.parse(await readFile(path, "utf8"));
+  const encodedSecret = await backend.get(accountName(environment, id));
+  if (!encodedSecret) throw new Error(`Protected secret is missing for installation ${id}.`);
+  return { installation, secret: JSON.parse(encodedSecret) };
+}
+async function listExternalAgentInstallations(environment) {
+  const directory = join(installationStorePath(), environment);
+  if (!existsSync(directory)) return [];
+  const entries = await readdir(directory, { withFileTypes: true });
+  const installations = await Promise.all(entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => JSON.parse(await readFile(join(directory, entry.name), "utf8"))));
+  return installations.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+async function deleteExternalAgentInstallation(environment, id, backend = createPlatformInstallationSecretBackend()) {
+  await backend.delete(accountName(environment, id));
+  await rm(installationPath(environment, id), { force: true });
+}
+
 // src/node/credential-store.ts
 var TOPOLO_ENVIRONMENTS = TOPOLO_RUNTIME_ENVIRONMENTS;
 function contextKey(contextType, organizationId) {
@@ -430,14 +596,14 @@ var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
-  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
-  return join(base, "topolo", "config.json");
+  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join2(homedir2(), "AppData", "Roaming") : join2(homedir2(), ".config"));
+  return join2(base, "topolo", "config.json");
 }
 async function readConfig() {
   const path = configPath();
-  if (!existsSync(path)) return {};
+  if (!existsSync2(path)) return {};
   try {
-    const raw = await readFile(path, "utf8");
+    const raw = await readFile2(path, "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -445,11 +611,11 @@ async function readConfig() {
 }
 async function writeConfig(config) {
   const path = configPath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(path, JSON.stringify(config, null, 2) + "\n", "utf8");
   if (platform() !== "win32") {
     try {
-      await chmod(path, 384);
+      await chmod2(path, 384);
     } catch {
     }
   }
@@ -565,18 +731,18 @@ var CONFIG_LOCK_TIMEOUT_MS = 5e3;
 var CONFIG_LOCK_STALE_MS = 12e4;
 async function withConfigWriteLock(operation) {
   const lockPath = `${configPath()}.lock`;
-  await mkdir(dirname(lockPath), { recursive: true });
+  await mkdir2(dirname2(lockPath), { recursive: true });
   const startedAt = Date.now();
   while (true) {
     try {
-      await mkdir(lockPath);
+      await mkdir2(lockPath);
       break;
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       try {
         const lock = await stat(lockPath);
         if (Date.now() - lock.mtimeMs > CONFIG_LOCK_STALE_MS) {
-          await rm(lockPath, { recursive: true, force: true });
+          await rm2(lockPath, { recursive: true, force: true });
           continue;
         }
       } catch (inspectionError) {
@@ -592,7 +758,7 @@ async function withConfigWriteLock(operation) {
   try {
     return await operation();
   } finally {
-    await rm(lockPath, { recursive: true, force: true });
+    await rm2(lockPath, { recursive: true, force: true });
   }
 }
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
@@ -740,11 +906,16 @@ export {
   clearProfileCredential,
   configPath,
   contextKey,
+  createPlatformInstallationSecretBackend,
   credentialSourceFromConfig,
+  deleteExternalAgentInstallation,
   envVarPrefix,
+  installationStorePath,
+  listExternalAgentInstallations,
   normalizeEnvironment,
   profileForEnvironment,
   readConfig,
+  readExternalAgentInstallation,
   refreshContextCredentialIfNeeded,
   refreshCredentialIfNeeded,
   resolveAgentName,
@@ -755,5 +926,6 @@ export {
   topoloServiceOrigins,
   writeConfig,
   writeContextCredential,
+  writeExternalAgentInstallation,
   writeProfileConfig
 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/sdk",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.19.0",
-  "topoloPublishedVersion": "0.19.0",
+  "version": "0.20.0",
+  "topoloPublishedVersion": "0.20.0",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "license": "UNLICENSED",
   "author": "Topolo",