@topolo/sdk 0.21.1 → 0.21.3

package/dist/node/credential-store.cjs

@@ -29,6 +29,7 @@ __export(credential_store_exports, {
   configPath: () => configPath,
   contextKey: () => contextKey,
   createPlatformInstallationSecretBackend: () => createPlatformInstallationSecretBackend,
+  createProtectedActionSecretStore: () => createProtectedActionSecretStore,
   credentialSourceFromConfig: () => credentialSourceFromConfig,
   deleteExternalAgentInstallation: () => deleteExternalAgentInstallation,
   envVarPrefix: () => envVarPrefix,
@@ -55,7 +56,7 @@ module.exports = __toCommonJS(credential_store_exports);
 var import_promises2 = require("fs/promises");
 var import_node_fs2 = require("fs");
 var import_node_os2 = require("os");
-var import_node_path2 = require("path");
+var import_node_path3 = require("path");
 
 // src/errors.ts
 var TopoloSdkError = class extends Error {
@@ -411,68 +412,12 @@ var TopoloOAuth = class {
   }
 };
 
-// src/environment.ts
-var TOPOLO_RUNTIME_ENVIRONMENTS = ["production", "staging", "development", "local"];
-var TOPOLO_ENVIRONMENT_SERVICE_URLS = {
-  production: {
-    auth: "https://auth.topolo.app",
-    developers: "https://developers.topolo.app"
-  },
-  staging: {
-    auth: "https://auth.stg.topolo.us",
-    developers: "https://developers.stg.topolo.us"
-  },
-  development: {
-    auth: "https://auth.topolo.dev",
-    developers: "https://developers.topolo.dev"
-  },
-  local: {}
-};
-function hostnameHasSuffix(hostname, suffix) {
-  return hostname === suffix || hostname.endsWith(`.${suffix}`);
-}
-function workersDevAccountMatches(hostname, account) {
-  if (!hostname.endsWith(".workers.dev")) return false;
-  const labels = hostname.slice(0, -".workers.dev".length).split(".");
-  return labels.length >= 2 && labels.at(-1) === account;
-}
-function originMatchesEnvironment(url, environment) {
-  const hostname = url.hostname.toLowerCase();
-  if (environment === "local") {
-    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
-  }
-  if (url.protocol !== "https:") return false;
-  if (environment === "production") {
-    return hostnameHasSuffix(hostname, "topolo.app") || hostnameHasSuffix(hostname, "topolo.io") || hostname === "api.ol0.me" || workersDevAccountMatches(hostname, "topolo");
-  }
-  if (environment === "staging") {
-    return hostnameHasSuffix(hostname, "stg.topolo.us") || workersDevAccountMatches(hostname, "topolo-staging");
-  }
-  return hostnameHasSuffix(hostname, "topolo.dev") || workersDevAccountMatches(hostname, "topolo-development");
-}
-function assertTopoloServiceUrlEnvironment(service, value, environment) {
-  let url;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new TopoloSdkError("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
-  }
-  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originMatchesEnvironment(url, environment)) {
-    throw new TopoloSdkError(
-      "environment_mismatch",
-      `Refusing Topolo service "${service}": ${url.origin} does not belong to ${environment}.`
-    );
-  }
-  return url.origin;
-}
-function topoloServiceOrigins(serviceUrls, environment) {
-  return Object.fromEntries(
-    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
-      service,
-      assertTopoloServiceUrlEnvironment(service, value, environment)
-    ])
-  );
-}
+// src/node/action-secret-store.ts
+var import_node_crypto = require("crypto");
+var import_node_path2 = require("path");
+
+// src/action-secrets.ts
+var ACTION_SECRET_PREFIX = "topolo-secret:";
 
 // src/node/installation-store.ts
 var import_node_child_process = require("child_process");
@@ -481,6 +426,8 @@ 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";
+var MACOS_KEYCHAIN_CHUNK_SIZE = 96;
+var MACOS_KEYCHAIN_CHUNK_PREFIX = "topolo-keychain-chunks:v1:";
 var MACOS_KEYCHAIN_WRITE_SCRIPT = [
   "log_user 0",
   "set timeout 10",
@@ -520,41 +467,75 @@ 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();
+  const service = options.service ?? KEYCHAIN_SERVICE;
   if (platform2 === "darwin") {
+    const write = (account, value) => runOrThrow(spawn("/usr/bin/expect", ["-c", MACOS_KEYCHAIN_WRITE_SCRIPT], {
+      input: `${value}
+`,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        TOPOLO_KEYCHAIN_ACCOUNT: account,
+        TOPOLO_KEYCHAIN_SERVICE: service
+      }
+    }), "macOS Keychain write");
+    const read = (account) => {
+      const result = spawn("security", [
+        "find-generic-password",
+        "-a",
+        account,
+        "-s",
+        service,
+        "-w"
+      ], { encoding: "utf8" });
+      if (result.status === 44) return null;
+      return runOrThrow(result, "macOS Keychain read");
+    };
+    const remove = (account) => {
+      const result = spawn("security", [
+        "delete-generic-password",
+        "-a",
+        account,
+        "-s",
+        service
+      ], { encoding: "utf8" });
+      if (result.status !== 44) runOrThrow(result, "macOS Keychain delete");
+    };
+    const chunkAccount = (account, index) => `${account}:chunk:${index}`;
+    const chunkCount = (value) => {
+      if (!value?.startsWith(MACOS_KEYCHAIN_CHUNK_PREFIX)) return 0;
+      const count = Number(value.slice(MACOS_KEYCHAIN_CHUNK_PREFIX.length));
+      if (!Number.isSafeInteger(count) || count < 1) throw new Error("macOS Keychain chunk manifest is invalid.");
+      return count;
+    };
     return {
       async set(account, value) {
-        runOrThrow(spawn("/usr/bin/expect", ["-c", MACOS_KEYCHAIN_WRITE_SCRIPT], {
-          input: `${value}
-`,
-          encoding: "utf8",
-          env: {
-            ...process.env,
-            TOPOLO_KEYCHAIN_ACCOUNT: account,
-            TOPOLO_KEYCHAIN_SERVICE: KEYCHAIN_SERVICE
-          }
-        }), "macOS Keychain write");
+        const previousCount = chunkCount(read(account));
+        const chunks = Array.from(
+          { length: Math.max(1, Math.ceil(value.length / MACOS_KEYCHAIN_CHUNK_SIZE)) },
+          (_, index) => value.slice(index * MACOS_KEYCHAIN_CHUNK_SIZE, (index + 1) * MACOS_KEYCHAIN_CHUNK_SIZE)
+        );
+        try {
+          chunks.forEach((chunk, index) => write(chunkAccount(account, index), chunk));
+          write(account, `${MACOS_KEYCHAIN_CHUNK_PREFIX}${chunks.length}`);
+          for (let index = chunks.length; index < previousCount; index += 1) remove(chunkAccount(account, index));
+        } catch (error) {
+          chunks.forEach((_, index) => remove(chunkAccount(account, index)));
+          throw error;
+        }
       },
       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");
+        const manifest = read(account);
+        const count = chunkCount(manifest);
+        if (!count) return manifest;
+        const chunks = Array.from({ length: count }, (_, index) => read(chunkAccount(account, index)));
+        if (chunks.some((chunk) => chunk === null)) throw new Error("macOS Keychain installation secret is incomplete.");
+        return chunks.join("");
       },
       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");
+        const count = chunkCount(read(account));
+        for (let index = 0; index < count; index += 1) remove(chunkAccount(account, index));
+        remove(account);
       }
     };
   }
@@ -563,9 +544,9 @@ function createPlatformInstallationSecretBackend(options = {}) {
       async set(account, value) {
         runOrThrow(spawn("secret-tool", [
           "store",
-          "--label=Topolo external agent installation",
+          "--label=Topolo protected credential",
           "service",
-          KEYCHAIN_SERVICE,
+          service,
           "account",
           account
         ], { input: value, encoding: "utf8" }), "Linux Secret Service write");
@@ -574,7 +555,7 @@ function createPlatformInstallationSecretBackend(options = {}) {
         const result = spawn("secret-tool", [
           "lookup",
           "service",
-          KEYCHAIN_SERVICE,
+          service,
           "account",
           account
         ], { encoding: "utf8" });
@@ -585,7 +566,7 @@ function createPlatformInstallationSecretBackend(options = {}) {
         const result = spawn("secret-tool", [
           "clear",
           "service",
-          KEYCHAIN_SERVICE,
+          service,
           "account",
           account
         ], { encoding: "utf8" });
@@ -656,6 +637,118 @@ async function deleteExternalAgentInstallation(environment, id, backend = create
   await (0, import_promises.rm)(installationPath(environment, id), { force: true });
 }
 
+// src/node/action-secret-store.ts
+function createProtectedActionSecretStore(options) {
+  const backend = options.backend ?? createPlatformInstallationSecretBackend({
+    service: "topolo-action-handoff",
+    root: (0, import_node_path2.join)(installationStorePath(), "action-handoff")
+  });
+  const now = options.now ?? Date.now;
+  async function account(reference) {
+    if (!/^topolo-secret:[0-9a-f-]{36}$/.test(reference)) throw new TopoloSdkError("invalid_action_secret_reference", "Invalid protected action reference.");
+    const identity = await options.identity();
+    if (!identity.user.id) throw new TopoloSdkError("action_secret_identity_required", "A verified identity is required for protected action handoff.");
+    if (identity.kind === "api_key" && !identity.apiKey?.id) throw new TopoloSdkError("action_secret_identity_required", "A verified API key identity is required for protected action handoff.");
+    const scope = (0, import_node_crypto.createHash)("sha256").update(JSON.stringify([
+      options.environment,
+      identity.user.principalId ?? identity.user.id,
+      identity.organization?.id ?? null,
+      identity.apiKey?.id ?? null
+    ])).digest("hex");
+    return `${scope}-${reference.slice(ACTION_SECRET_PREFIX.length)}`;
+  }
+  return {
+    async save(value) {
+      const reference = `${ACTION_SECRET_PREFIX}${(0, import_node_crypto.randomUUID)()}`;
+      await backend.set(await account(reference), JSON.stringify({ value, expiresAt: now() + 30 * 60 * 1e3 }));
+      return reference;
+    },
+    async load(reference) {
+      const key = await account(reference);
+      const encoded = await backend.get(key);
+      if (!encoded) throw new TopoloSdkError("action_secret_unavailable", "Protected action reference is missing or belongs to another identity or environment.");
+      let record;
+      try {
+        record = JSON.parse(encoded);
+      } catch {
+        throw new TopoloSdkError("action_secret_invalid", "Protected action reference is corrupt.");
+      }
+      if (!Number.isFinite(record?.expiresAt) || !Object.hasOwn(record, "value")) throw new TopoloSdkError("action_secret_invalid", "Protected action reference is corrupt.");
+      if (record.expiresAt <= now()) {
+        await backend.delete(key);
+        throw new TopoloSdkError("action_secret_expired", "Protected action reference expired. Repeat the originating action if its contract permits.");
+      }
+      return record.value;
+    },
+    async delete(reference) {
+      await backend.delete(await account(reference));
+    }
+  };
+}
+
+// src/environment.ts
+var TOPOLO_RUNTIME_ENVIRONMENTS = ["production", "staging", "development", "local"];
+var TOPOLO_ENVIRONMENT_SERVICE_URLS = {
+  production: {
+    auth: "https://auth.topolo.app",
+    developers: "https://developers.topolo.app"
+  },
+  staging: {
+    auth: "https://auth.stg.topolo.us",
+    developers: "https://developers.stg.topolo.us"
+  },
+  development: {
+    auth: "https://auth.topolo.dev",
+    developers: "https://developers.topolo.dev"
+  },
+  local: {}
+};
+function hostnameHasSuffix(hostname, suffix) {
+  return hostname === suffix || hostname.endsWith(`.${suffix}`);
+}
+function workersDevAccountMatches(hostname, account) {
+  if (!hostname.endsWith(".workers.dev")) return false;
+  const labels = hostname.slice(0, -".workers.dev".length).split(".");
+  return labels.length >= 2 && labels.at(-1) === account;
+}
+function originMatchesEnvironment(url, environment) {
+  const hostname = url.hostname.toLowerCase();
+  if (environment === "local") {
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+  }
+  if (url.protocol !== "https:") return false;
+  if (environment === "production") {
+    return hostnameHasSuffix(hostname, "topolo.app") || hostnameHasSuffix(hostname, "topolo.io") || hostname === "api.ol0.me" || workersDevAccountMatches(hostname, "topolo");
+  }
+  if (environment === "staging") {
+    return hostnameHasSuffix(hostname, "stg.topolo.us") || workersDevAccountMatches(hostname, "topolo-staging");
+  }
+  return hostnameHasSuffix(hostname, "topolo.dev") || workersDevAccountMatches(hostname, "topolo-development");
+}
+function assertTopoloServiceUrlEnvironment(service, value, environment) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originMatchesEnvironment(url, environment)) {
+    throw new TopoloSdkError(
+      "environment_mismatch",
+      `Refusing Topolo service "${service}": ${url.origin} does not belong to ${environment}.`
+    );
+  }
+  return url.origin;
+}
+function topoloServiceOrigins(serviceUrls, environment) {
+  return Object.fromEntries(
+    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
+      service,
+      assertTopoloServiceUrlEnvironment(service, value, environment)
+    ])
+  );
+}
+
 // src/node/credential-store.ts
 var TOPOLO_ENVIRONMENTS = TOPOLO_RUNTIME_ENVIRONMENTS;
 function contextKey(contextType, organizationId) {
@@ -665,8 +758,8 @@ 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_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");
+  const base = process.env.XDG_CONFIG_HOME || ((0, import_node_os2.platform)() === "win32" ? (0, import_node_path3.join)((0, import_node_os2.homedir)(), "AppData", "Roaming") : (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".config"));
+  return (0, import_node_path3.join)(base, "topolo", "config.json");
 }
 async function readConfig() {
   const path = configPath();
@@ -680,7 +773,7 @@ async function readConfig() {
 }
 async function writeConfig(config) {
   const path = configPath();
-  await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(path), { recursive: true });
+  await (0, import_promises2.mkdir)((0, import_node_path3.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 {
@@ -800,7 +893,7 @@ var CONFIG_LOCK_TIMEOUT_MS = 5e3;
 var CONFIG_LOCK_STALE_MS = 12e4;
 async function withConfigWriteLock(operation) {
   const lockPath = `${configPath()}.lock`;
-  await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(lockPath), { recursive: true });
+  await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(lockPath), { recursive: true });
   const startedAt = Date.now();
   while (true) {
     try {
@@ -977,6 +1070,7 @@ function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   configPath,
   contextKey,
   createPlatformInstallationSecretBackend,
+  createProtectedActionSecretStore,
   credentialSourceFromConfig,
   deleteExternalAgentInstallation,
   envVarPrefix,

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

@@ -26,11 +26,53 @@ type TopoloCredential = {
     expiresAt?: number;
 };
 
+interface TopoloActionSecretStore {
+    save(value: unknown): Promise<string>;
+    load(reference: string): Promise<unknown>;
+    delete(reference: string): Promise<void>;
+}
+
 declare const TOPOLO_RUNTIME_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
 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 CredentialIntrospection {
+    kind: 'api_key' | 'access_token';
+    authorizationMode: 'context_rbac' | 'oauth_scopes' | 'session_rbac' | 'api_key' | 'unknown';
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+        role: string;
+        permissions: string[];
+        principalId?: string | null;
+        principalType?: 'agent_employee' | 'external_agent' | null;
+        accountableUserId?: string | null;
+        agentInstanceId?: string | null;
+        installationId?: string | null;
+        provider?: string | null;
+        model?: string | null;
+        serviceScopes?: string[];
+        policyRef?: string | null;
+    };
+    organization: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+    apiKey: {
+        id: string | null;
+        name: string | null;
+        appId: string | null;
+        scopes: string[];
+        resourceBindings: Array<{
+            resourceType: string;
+            resourceId: string;
+        }>;
+    } | null;
+}
+
 interface ExternalAgentInstallation {
     id: string;
     environment: TopoloRuntimeEnvironment;
@@ -64,6 +106,7 @@ declare function createPlatformInstallationSecretBackend(options?: {
     platform?: NodeJS.Platform;
     spawn?: Spawn;
     root?: string;
+    service?: string;
 }): InstallationSecretBackend;
 declare function writeExternalAgentInstallation(installation: ExternalAgentInstallation, secret: ExternalAgentInstallationSecret, backend?: InstallationSecretBackend): Promise<void>;
 declare function readExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<{
@@ -73,6 +116,13 @@ declare function readExternalAgentInstallation(environment: TopoloRuntimeEnviron
 declare function listExternalAgentInstallations(environment: TopoloRuntimeEnvironment): Promise<ExternalAgentInstallation[]>;
 declare function deleteExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<void>;
 
+declare function createProtectedActionSecretStore(options: {
+    environment: TopoloRuntimeEnvironment;
+    identity: () => Promise<CredentialIntrospection>;
+    backend?: InstallationSecretBackend;
+    now?: () => number;
+}): TopoloActionSecretStore;
+
 /**
  * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
  *
@@ -166,4 +216,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, 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 };
+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, createProtectedActionSecretStore, 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

@@ -26,11 +26,53 @@ type TopoloCredential = {
     expiresAt?: number;
 };
 
+interface TopoloActionSecretStore {
+    save(value: unknown): Promise<string>;
+    load(reference: string): Promise<unknown>;
+    delete(reference: string): Promise<void>;
+}
+
 declare const TOPOLO_RUNTIME_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
 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 CredentialIntrospection {
+    kind: 'api_key' | 'access_token';
+    authorizationMode: 'context_rbac' | 'oauth_scopes' | 'session_rbac' | 'api_key' | 'unknown';
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+        role: string;
+        permissions: string[];
+        principalId?: string | null;
+        principalType?: 'agent_employee' | 'external_agent' | null;
+        accountableUserId?: string | null;
+        agentInstanceId?: string | null;
+        installationId?: string | null;
+        provider?: string | null;
+        model?: string | null;
+        serviceScopes?: string[];
+        policyRef?: string | null;
+    };
+    organization: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+    apiKey: {
+        id: string | null;
+        name: string | null;
+        appId: string | null;
+        scopes: string[];
+        resourceBindings: Array<{
+            resourceType: string;
+            resourceId: string;
+        }>;
+    } | null;
+}
+
 interface ExternalAgentInstallation {
     id: string;
     environment: TopoloRuntimeEnvironment;
@@ -64,6 +106,7 @@ declare function createPlatformInstallationSecretBackend(options?: {
     platform?: NodeJS.Platform;
     spawn?: Spawn;
     root?: string;
+    service?: string;
 }): InstallationSecretBackend;
 declare function writeExternalAgentInstallation(installation: ExternalAgentInstallation, secret: ExternalAgentInstallationSecret, backend?: InstallationSecretBackend): Promise<void>;
 declare function readExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<{
@@ -73,6 +116,13 @@ declare function readExternalAgentInstallation(environment: TopoloRuntimeEnviron
 declare function listExternalAgentInstallations(environment: TopoloRuntimeEnvironment): Promise<ExternalAgentInstallation[]>;
 declare function deleteExternalAgentInstallation(environment: TopoloRuntimeEnvironment, id: string, backend?: InstallationSecretBackend): Promise<void>;
 
+declare function createProtectedActionSecretStore(options: {
+    environment: TopoloRuntimeEnvironment;
+    identity: () => Promise<CredentialIntrospection>;
+    backend?: InstallationSecretBackend;
+    now?: () => number;
+}): TopoloActionSecretStore;
+
 /**
  * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
  *
@@ -166,4 +216,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, 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 };
+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, createProtectedActionSecretStore, credentialSourceFromConfig, deleteExternalAgentInstallation, envVarPrefix, installationStorePath, listExternalAgentInstallations, normalizeEnvironment, profileForEnvironment, readConfig, readExternalAgentInstallation, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, topoloServiceOrigins, writeConfig, writeContextCredential, writeExternalAgentInstallation, writeProfileConfig };