@topolo/sdk 0.18.0 → 0.20.0

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   actionContractCompleteness: () => actionContractCompleteness,
   applicationEntryFromCatalog: () => applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment: () => assertTopoloServiceUrlEnvironment,
+  calculateDpopJkt: () => calculateDpopJkt,
   canonicalJson: () => canonicalJson,
   canonicalTopoloErrorCode: () => canonicalTopoloErrorCode,
   canonicalTopoloRequestId: () => canonicalTopoloRequestId,
@@ -57,6 +58,7 @@ __export(index_exports, {
   compactActionPreparation: () => compactActionPreparation,
   compactActionResult: () => compactActionResult,
   compactActionValidation: () => compactActionValidation,
+  createDpopProof: () => createDpopProof,
   createTopolo: () => createTopolo,
   createTopoloAgentExecutionContext: () => createTopoloAgentExecutionContext,
   createTopoloWidgetError: () => createTopoloWidgetError,
@@ -101,7 +103,7 @@ function applyAuthHeaders(headers, credential) {
     headers.set("X-Api-Key", credential.apiKey);
     return;
   }
-  headers.set("Authorization", `Bearer ${credential.accessToken}`);
+  headers.set("Authorization", `${credential.kind === "dpop_access_token" ? "DPoP" : "Bearer"} ${credential.accessToken}`);
 }
 function applyAuditHeaders(headers, agent, requestId) {
   headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
@@ -115,6 +117,60 @@ function generateRequestId() {
   return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
 
+// src/dpop.ts
+var encoder = new TextEncoder();
+function encodeBase64Url(value) {
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function encodeJson(value) {
+  return encodeBase64Url(encoder.encode(JSON.stringify(value)));
+}
+async function sha256Base64Url(value) {
+  return encodeBase64Url(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+}
+function publicJwk(privateJwk) {
+  const { crv, kty, x, y } = privateJwk;
+  if (kty !== "EC" || crv !== "P-256" || !x || !y || !privateJwk.d) {
+    throw new TypeError("A private P-256 JSON Web Key is required for DPoP signing.");
+  }
+  return { crv, kty, x, y };
+}
+function canonicalTargetUrl(value) {
+  const url = new URL(value);
+  return `${url.origin}${url.pathname}`;
+}
+async function calculateDpopJkt(privateJwk) {
+  const jwk = publicJwk(privateJwk);
+  return sha256Base64Url(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }));
+}
+async function createDpopProof(input) {
+  const jwk = publicJwk(input.privateJwk);
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    input.privateJwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const header = encodeJson({ alg: "ES256", typ: "dpop+jwt", jwk });
+  const claims = encodeJson({
+    jti: crypto.randomUUID(),
+    iat: Math.floor(Date.now() / 1e3),
+    htm: input.method.toUpperCase(),
+    htu: canonicalTargetUrl(input.targetUrl),
+    ath: await sha256Base64Url(input.accessToken)
+  });
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    encoder.encode(`${header}.${claims}`)
+  );
+  return `${header}.${claims}.${encodeBase64Url(signature)}`;
+}
+
 // src/errors.ts
 var TopoloSdkError = class extends Error {
   code;
@@ -1471,7 +1527,6 @@ var TopoloClient = class _TopoloClient {
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
     const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
     if (platformAppId) headers.set("X-App-ID", platformAppId);
-    applyAuthHeaders(headers, this.credential);
     const actorEnvelope = opts.actorEnvelope === void 0 ? void 0 : parseActorEnvelope(opts.actorEnvelope);
     const requestId = actorEnvelope?.action.requestId ?? generateRequestId();
     applyAuditHeaders(headers, this.agent, requestId);
@@ -1505,9 +1560,19 @@ var TopoloClient = class _TopoloClient {
       }, this.timeoutMs);
       const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
       try {
+        const requestHeaders = new Headers(headers);
+        applyAuthHeaders(requestHeaders, this.credential);
+        if (this.credential.kind === "dpop_access_token") {
+          requestHeaders.set("DPoP", await createDpopProof({
+            accessToken: this.credential.accessToken,
+            method,
+            targetUrl: urlStr,
+            privateJwk: this.credential.privateJwk
+          }));
+        }
         return await this.fetchImpl(urlStr, {
           method,
-          headers: new Headers(headers),
+          headers: requestHeaders,
           body: opts.rawBody ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : null),
           signal
         });
@@ -1544,7 +1609,6 @@ var TopoloClient = class _TopoloClient {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
-          applyAuthHeaders(headers, refreshed);
           res = await fetchWithReadRetry();
         }
       }
@@ -4899,6 +4963,7 @@ function createTopolo(options) {
   actionContractCompleteness,
   applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment,
+  calculateDpopJkt,
   canonicalJson,
   canonicalTopoloErrorCode,
   canonicalTopoloRequestId,
@@ -4910,6 +4975,7 @@ function createTopolo(options) {
   compactActionPreparation,
   compactActionResult,
   compactActionValidation,
+  createDpopProof,
   createTopolo,
   createTopoloAgentExecutionContext,
   createTopoloWidgetError,

package/dist/index.d.cts

@@ -1,14 +1,13 @@
 /**
  * Auth credential types used by the SDK.
  *
- * Phase 1 supports two modes:
+ * Supported modes:
  *   - `api_key`: a single platform API key (service-scoped at issuance).
- *     Preferred for long-lived agent installs.
+ *     Used for service integrations that are not installation-bound.
  *   - `access_token`: a short-lived JWT from the interactive login flow.
  *     Used by TopoloCli after `topolo auth login`.
- *
- * Phase 2 will add OAuth access tokens issued by the authorization-code +
- * PKCE flow in TopoloAuth. Those will plug in as a third variant.
+ *   - `dpop_access_token`: a short-lived delegated token bound to an external
+ *     agent installation key. Every request proves possession of that key.
  */
 type TopoloCredential = {
     kind: 'api_key';
@@ -18,6 +17,11 @@ type TopoloCredential = {
     accessToken: string;
     refreshToken?: string;
     expiresAt?: number;
+} | {
+    kind: 'dpop_access_token';
+    accessToken: string;
+    privateJwk: JsonWebKey;
+    expiresAt?: number;
 };
 interface AgentIdentity {
     /** Display name of the agent or tool making requests. Included in audit headers. */
@@ -761,6 +765,14 @@ declare function actionContractCompleteness(
   action: ActionContractSource,
 ): Record<string, boolean>;
 
+declare function calculateDpopJkt(privateJwk: JsonWebKey): Promise<string>;
+declare function createDpopProof(input: {
+    accessToken: string;
+    method: string;
+    targetUrl: string;
+    privateJwk: JsonWebKey;
+}): Promise<string>;
+
 /**
  * Bootstrap seed URLs — the ONLY static service endpoints in the SDK.
  *
@@ -1694,4 +1706,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, calculateDpopJkt, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createDpopProof, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.d.ts

@@ -1,14 +1,13 @@
 /**
  * Auth credential types used by the SDK.
  *
- * Phase 1 supports two modes:
+ * Supported modes:
  *   - `api_key`: a single platform API key (service-scoped at issuance).
- *     Preferred for long-lived agent installs.
+ *     Used for service integrations that are not installation-bound.
  *   - `access_token`: a short-lived JWT from the interactive login flow.
  *     Used by TopoloCli after `topolo auth login`.
- *
- * Phase 2 will add OAuth access tokens issued by the authorization-code +
- * PKCE flow in TopoloAuth. Those will plug in as a third variant.
+ *   - `dpop_access_token`: a short-lived delegated token bound to an external
+ *     agent installation key. Every request proves possession of that key.
  */
 type TopoloCredential = {
     kind: 'api_key';
@@ -18,6 +17,11 @@ type TopoloCredential = {
     accessToken: string;
     refreshToken?: string;
     expiresAt?: number;
+} | {
+    kind: 'dpop_access_token';
+    accessToken: string;
+    privateJwk: JsonWebKey;
+    expiresAt?: number;
 };
 interface AgentIdentity {
     /** Display name of the agent or tool making requests. Included in audit headers. */
@@ -761,6 +765,14 @@ declare function actionContractCompleteness(
   action: ActionContractSource,
 ): Record<string, boolean>;
 
+declare function calculateDpopJkt(privateJwk: JsonWebKey): Promise<string>;
+declare function createDpopProof(input: {
+    accessToken: string;
+    method: string;
+    targetUrl: string;
+    privateJwk: JsonWebKey;
+}): Promise<string>;
+
 /**
  * Bootstrap seed URLs — the ONLY static service endpoints in the SDK.
  *
@@ -1694,4 +1706,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, calculateDpopJkt, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createDpopProof, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.js

@@ -4,7 +4,7 @@ function applyAuthHeaders(headers, credential) {
     headers.set("X-Api-Key", credential.apiKey);
     return;
   }
-  headers.set("Authorization", `Bearer ${credential.accessToken}`);
+  headers.set("Authorization", `${credential.kind === "dpop_access_token" ? "DPoP" : "Bearer"} ${credential.accessToken}`);
 }
 function applyAuditHeaders(headers, agent, requestId) {
   headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
@@ -18,6 +18,60 @@ function generateRequestId() {
   return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
 
+// src/dpop.ts
+var encoder = new TextEncoder();
+function encodeBase64Url(value) {
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function encodeJson(value) {
+  return encodeBase64Url(encoder.encode(JSON.stringify(value)));
+}
+async function sha256Base64Url(value) {
+  return encodeBase64Url(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+}
+function publicJwk(privateJwk) {
+  const { crv, kty, x, y } = privateJwk;
+  if (kty !== "EC" || crv !== "P-256" || !x || !y || !privateJwk.d) {
+    throw new TypeError("A private P-256 JSON Web Key is required for DPoP signing.");
+  }
+  return { crv, kty, x, y };
+}
+function canonicalTargetUrl(value) {
+  const url = new URL(value);
+  return `${url.origin}${url.pathname}`;
+}
+async function calculateDpopJkt(privateJwk) {
+  const jwk = publicJwk(privateJwk);
+  return sha256Base64Url(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }));
+}
+async function createDpopProof(input) {
+  const jwk = publicJwk(input.privateJwk);
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    input.privateJwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const header = encodeJson({ alg: "ES256", typ: "dpop+jwt", jwk });
+  const claims = encodeJson({
+    jti: crypto.randomUUID(),
+    iat: Math.floor(Date.now() / 1e3),
+    htm: input.method.toUpperCase(),
+    htu: canonicalTargetUrl(input.targetUrl),
+    ath: await sha256Base64Url(input.accessToken)
+  });
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    encoder.encode(`${header}.${claims}`)
+  );
+  return `${header}.${claims}.${encodeBase64Url(signature)}`;
+}
+
 // src/errors.ts
 var TopoloSdkError = class extends Error {
   code;
@@ -1374,7 +1428,6 @@ var TopoloClient = class _TopoloClient {
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
     const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
     if (platformAppId) headers.set("X-App-ID", platformAppId);
-    applyAuthHeaders(headers, this.credential);
     const actorEnvelope = opts.actorEnvelope === void 0 ? void 0 : parseActorEnvelope(opts.actorEnvelope);
     const requestId = actorEnvelope?.action.requestId ?? generateRequestId();
     applyAuditHeaders(headers, this.agent, requestId);
@@ -1408,9 +1461,19 @@ var TopoloClient = class _TopoloClient {
       }, this.timeoutMs);
       const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
       try {
+        const requestHeaders = new Headers(headers);
+        applyAuthHeaders(requestHeaders, this.credential);
+        if (this.credential.kind === "dpop_access_token") {
+          requestHeaders.set("DPoP", await createDpopProof({
+            accessToken: this.credential.accessToken,
+            method,
+            targetUrl: urlStr,
+            privateJwk: this.credential.privateJwk
+          }));
+        }
         return await this.fetchImpl(urlStr, {
           method,
-          headers: new Headers(headers),
+          headers: requestHeaders,
           body: opts.rawBody ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : null),
           signal
         });
@@ -1447,7 +1510,6 @@ var TopoloClient = class _TopoloClient {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
-          applyAuthHeaders(headers, refreshed);
           res = await fetchWithReadRetry();
         }
       }
@@ -4801,6 +4863,7 @@ export {
   actionContractCompleteness,
   applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment,
+  calculateDpopJkt,
   canonicalJson,
   canonicalTopoloErrorCode,
   canonicalTopoloRequestId,
@@ -4812,6 +4875,7 @@ export {
   compactActionPreparation,
   compactActionResult,
   compactActionValidation,
+  createDpopProof,
   createTopolo,
   createTopoloAgentExecutionContext,
   createTopoloWidgetError,

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,14 +1,15 @@
+import { SpawnSyncReturns } from 'node:child_process';
+
 /**
  * Auth credential types used by the SDK.
  *
- * Phase 1 supports two modes:
+ * Supported modes:
  *   - `api_key`: a single platform API key (service-scoped at issuance).
- *     Preferred for long-lived agent installs.
+ *     Used for service integrations that are not installation-bound.
  *   - `access_token`: a short-lived JWT from the interactive login flow.
  *     Used by TopoloCli after `topolo auth login`.
- *
- * Phase 2 will add OAuth access tokens issued by the authorization-code +
- * PKCE flow in TopoloAuth. Those will plug in as a third variant.
+ *   - `dpop_access_token`: a short-lived delegated token bound to an external
+ *     agent installation key. Every request proves possession of that key.
  */
 type TopoloCredential = {
     kind: 'api_key';
@@ -18,6 +19,11 @@ type TopoloCredential = {
     accessToken: string;
     refreshToken?: string;
     expiresAt?: number;
+} | {
+    kind: 'dpop_access_token';
+    accessToken: string;
+    privateJwk: JsonWebKey;
+    expiresAt?: number;
 };
 
 declare const TOPOLO_RUNTIME_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
@@ -25,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`.
  *
@@ -118,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,14 +1,15 @@
+import { SpawnSyncReturns } from 'node:child_process';
+
 /**
  * Auth credential types used by the SDK.
  *
- * Phase 1 supports two modes:
+ * Supported modes:
  *   - `api_key`: a single platform API key (service-scoped at issuance).
- *     Preferred for long-lived agent installs.
+ *     Used for service integrations that are not installation-bound.
  *   - `access_token`: a short-lived JWT from the interactive login flow.
  *     Used by TopoloCli after `topolo auth login`.
- *
- * Phase 2 will add OAuth access tokens issued by the authorization-code +
- * PKCE flow in TopoloAuth. Those will plug in as a third variant.
+ *   - `dpop_access_token`: a short-lived delegated token bound to an external
+ *     agent installation key. Every request proves possession of that key.
  */
 type TopoloCredential = {
     kind: 'api_key';
@@ -18,6 +19,11 @@ type TopoloCredential = {
     accessToken: string;
     refreshToken?: string;
     expiresAt?: number;
+} | {
+    kind: 'dpop_access_token';
+    accessToken: string;
+    privateJwk: JsonWebKey;
+    expiresAt?: number;
 };
 
 declare const TOPOLO_RUNTIME_ENVIRONMENTS: readonly ["production", "staging", "development", "local"];
@@ -25,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`.
  *
@@ -118,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.18.0",
-  "topoloPublishedVersion": "0.18.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",