@topolo/sdk 0.20.0 → 0.21.0

package/dist/index.cjs

@@ -1447,7 +1447,7 @@ var TopoloClient = class _TopoloClient {
   timeoutMs;
   fetchImpl;
   credentialProvider;
-  credentialLoadInFlight = null;
+  credentialLoadsInFlight = /* @__PURE__ */ new Map();
   refreshCredential;
   refreshInFlight = null;
   debug;
@@ -1504,7 +1504,16 @@ var TopoloClient = class _TopoloClient {
         `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
       );
     }
-    await this.loadCurrentCredential();
+    const actionId = requestActionId(opts.headers);
+    const taskId = opts.actorEnvelope?.delegation?.taskId ?? this.actorContext?.taskId;
+    let requestCredential = await this.loadCurrentCredential({
+      service: normalizeLookupKey(opts.service),
+      method,
+      path: opts.path,
+      ...actionId ? { actionId } : {},
+      ...taskId ? { taskId } : {},
+      ...opts.resource ? { resource: opts.resource } : {}
+    });
     const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
@@ -1561,13 +1570,13 @@ var TopoloClient = class _TopoloClient {
       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") {
+        applyAuthHeaders(requestHeaders, requestCredential);
+        if (requestCredential.kind === "dpop_access_token") {
           requestHeaders.set("DPoP", await createDpopProof({
-            accessToken: this.credential.accessToken,
+            accessToken: requestCredential.accessToken,
             method,
             targetUrl: urlStr,
-            privateJwk: this.credential.privateJwk
+            privateJwk: requestCredential.privateJwk
           }));
         }
         return await this.fetchImpl(urlStr, {
@@ -1603,12 +1612,13 @@ var TopoloClient = class _TopoloClient {
     };
     let res;
     try {
-      const attemptedCredential = this.credential;
+      const attemptedCredential = requestCredential;
       res = await fetchWithReadRetry();
       if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
+          requestCredential = refreshed;
           res = await fetchWithReadRetry();
         }
       }
@@ -1698,18 +1708,23 @@ var TopoloClient = class _TopoloClient {
     });
     return parsed;
   }
-  async loadCurrentCredential() {
-    if (!this.credentialProvider) return;
-    this.credentialLoadInFlight ??= this.credentialProvider().then((credential) => {
-      if (!credential) {
-        throw new TopoloAuthError("The configured Topolo credential is no longer available.");
-      }
-      this.credential = credential;
-      return credential;
-    }).finally(() => {
-      this.credentialLoadInFlight = null;
-    });
-    await this.credentialLoadInFlight;
+  async loadCurrentCredential(context) {
+    if (!this.credentialProvider) return this.credential;
+    const key = JSON.stringify(context);
+    let load = this.credentialLoadsInFlight.get(key);
+    if (!load) {
+      load = this.credentialProvider(context).then((credential) => {
+        if (!credential) {
+          throw new TopoloAuthError("The configured Topolo credential is no longer available.");
+        }
+        this.credential = credential;
+        return credential;
+      }).finally(() => {
+        this.credentialLoadsInFlight.delete(key);
+      });
+      this.credentialLoadsInFlight.set(key, load);
+    }
+    return load;
   }
   async refreshRejectedAccessToken(attemptedAccessToken) {
     if (this.credential.kind === "access_token" && this.credential.accessToken !== attemptedAccessToken) {
@@ -2039,6 +2054,14 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async issueExternalAgentCredential(input) {
+    const actionId = "app_topolo_auth.principal_credentials.issue";
+    const entry = await this.getAction(actionId);
+    if (entry.actionId !== actionId) {
+      throw new TopoloSdkError("unexpected_action", "External agent credential issuance resolved an unexpected action.");
+    }
+    return this.executeResolvedAction(entry, input, { confirm: true }, true);
+  }
   async uploadAction(action, content, input, options) {
     const entry = await this.getAction(action);
     const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
@@ -2170,7 +2193,7 @@ var TopoloClient = class _TopoloClient {
     }
     return this.executeResolvedAction(entry, input, options);
   }
-  async executeResolvedAction(entry, input, options) {
+  async executeResolvedAction(entry, input, options, preserveSensitiveResult = false) {
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     if (agentAccess === "off") {
       throw new TopoloPermissionError(
@@ -2228,7 +2251,7 @@ var TopoloClient = class _TopoloClient {
       },
       confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
     });
-    return redactActionResult(result);
+    return preserveSensitiveResult ? result : redactActionResult(result);
   }
   async buildVerifiedAgentActorEnvelope(actionId, input, resource) {
     if (!this.actorContext) return void 0;
@@ -2704,6 +2727,12 @@ function pickString(value) {
   }
   return void 0;
 }
+function requestActionId(headers) {
+  const value = Object.entries(headers ?? {}).find(
+    ([name]) => name.toLowerCase() === TOPOLO_ACTION_ID_HEADER.toLowerCase()
+  )?.[1];
+  return value?.trim() || void 0;
+}
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;

package/dist/index.d.cts

@@ -176,7 +176,7 @@ interface TopoloClientOptions {
      * Long-lived hosts use this to adopt context reauthentication and claim
      * changes without waiting for the previous token to fail with a 401.
      */
-    credentialProvider?: () => Promise<TopoloCredential | null>;
+    credentialProvider?: (context: TopoloCredentialRequestContext) => Promise<TopoloCredential | null>;
     /**
      * Refresh a rejected access-token credential. When supplied, the client
      * retries one 401 response with the returned credential. Concurrent 401s
@@ -191,6 +191,17 @@ interface TopoloClientOptions {
      */
     debug?: (event: TopoloDebugEvent) => void;
 }
+interface TopoloCredentialRequestContext {
+    service: string;
+    method: string;
+    path: string;
+    actionId?: string;
+    taskId?: string;
+    resource?: {
+        resourceType: string;
+        resourceId: string;
+    };
+}
 type TopoloDebugEvent = {
     phase: 'request';
     method: string;
@@ -388,6 +399,24 @@ interface TopoloActionPreparation {
     missingFields: string[];
     plan: TopoloActionPlan;
 }
+interface ExternalAgentCredentialIssueInput {
+    orgId: string;
+    principalId: string;
+    dpopJkt: string;
+    displayName?: string;
+    expiresAt?: number | null;
+}
+interface ExternalAgentCredentialIssueResult {
+    data: {
+        credential: {
+            id: string;
+            clientId: string;
+            clientSecret: string;
+            [key: string]: unknown;
+        };
+    };
+    [key: string]: unknown;
+}
 interface TopoloCatalogPage {
     nextCursor: string | null;
     hasMore: boolean;
@@ -421,7 +450,7 @@ declare class TopoloClient {
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly credentialProvider?;
-    private credentialLoadInFlight;
+    private readonly credentialLoadsInFlight;
     private readonly refreshCredential?;
     private refreshInFlight;
     private readonly debug?;
@@ -502,6 +531,7 @@ declare class TopoloClient {
         };
         actorEnvelope?: ActorEnvelope;
     }): Promise<T>;
+    issueExternalAgentCredential(input: ExternalAgentCredentialIssueInput): Promise<ExternalAgentCredentialIssueResult>;
     uploadAction<T = unknown>(action: string, content: Uint8Array | ArrayBuffer, input: Record<string, unknown>, options: TopoloActionUploadOptions & {
         confirm?: boolean;
         resource?: {
@@ -1706,4 +1736,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, 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 };
+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, type ExternalAgentCredentialIssueInput, type ExternalAgentCredentialIssueResult, 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 TopoloCredentialRequestContext, 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

@@ -176,7 +176,7 @@ interface TopoloClientOptions {
      * Long-lived hosts use this to adopt context reauthentication and claim
      * changes without waiting for the previous token to fail with a 401.
      */
-    credentialProvider?: () => Promise<TopoloCredential | null>;
+    credentialProvider?: (context: TopoloCredentialRequestContext) => Promise<TopoloCredential | null>;
     /**
      * Refresh a rejected access-token credential. When supplied, the client
      * retries one 401 response with the returned credential. Concurrent 401s
@@ -191,6 +191,17 @@ interface TopoloClientOptions {
      */
     debug?: (event: TopoloDebugEvent) => void;
 }
+interface TopoloCredentialRequestContext {
+    service: string;
+    method: string;
+    path: string;
+    actionId?: string;
+    taskId?: string;
+    resource?: {
+        resourceType: string;
+        resourceId: string;
+    };
+}
 type TopoloDebugEvent = {
     phase: 'request';
     method: string;
@@ -388,6 +399,24 @@ interface TopoloActionPreparation {
     missingFields: string[];
     plan: TopoloActionPlan;
 }
+interface ExternalAgentCredentialIssueInput {
+    orgId: string;
+    principalId: string;
+    dpopJkt: string;
+    displayName?: string;
+    expiresAt?: number | null;
+}
+interface ExternalAgentCredentialIssueResult {
+    data: {
+        credential: {
+            id: string;
+            clientId: string;
+            clientSecret: string;
+            [key: string]: unknown;
+        };
+    };
+    [key: string]: unknown;
+}
 interface TopoloCatalogPage {
     nextCursor: string | null;
     hasMore: boolean;
@@ -421,7 +450,7 @@ declare class TopoloClient {
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly credentialProvider?;
-    private credentialLoadInFlight;
+    private readonly credentialLoadsInFlight;
     private readonly refreshCredential?;
     private refreshInFlight;
     private readonly debug?;
@@ -502,6 +531,7 @@ declare class TopoloClient {
         };
         actorEnvelope?: ActorEnvelope;
     }): Promise<T>;
+    issueExternalAgentCredential(input: ExternalAgentCredentialIssueInput): Promise<ExternalAgentCredentialIssueResult>;
     uploadAction<T = unknown>(action: string, content: Uint8Array | ArrayBuffer, input: Record<string, unknown>, options: TopoloActionUploadOptions & {
         confirm?: boolean;
         resource?: {
@@ -1706,4 +1736,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, 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 };
+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, type ExternalAgentCredentialIssueInput, type ExternalAgentCredentialIssueResult, 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 TopoloCredentialRequestContext, 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

@@ -1348,7 +1348,7 @@ var TopoloClient = class _TopoloClient {
   timeoutMs;
   fetchImpl;
   credentialProvider;
-  credentialLoadInFlight = null;
+  credentialLoadsInFlight = /* @__PURE__ */ new Map();
   refreshCredential;
   refreshInFlight = null;
   debug;
@@ -1405,7 +1405,16 @@ var TopoloClient = class _TopoloClient {
         `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
       );
     }
-    await this.loadCurrentCredential();
+    const actionId = requestActionId(opts.headers);
+    const taskId = opts.actorEnvelope?.delegation?.taskId ?? this.actorContext?.taskId;
+    let requestCredential = await this.loadCurrentCredential({
+      service: normalizeLookupKey(opts.service),
+      method,
+      path: opts.path,
+      ...actionId ? { actionId } : {},
+      ...taskId ? { taskId } : {},
+      ...opts.resource ? { resource: opts.resource } : {}
+    });
     const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
@@ -1462,13 +1471,13 @@ var TopoloClient = class _TopoloClient {
       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") {
+        applyAuthHeaders(requestHeaders, requestCredential);
+        if (requestCredential.kind === "dpop_access_token") {
           requestHeaders.set("DPoP", await createDpopProof({
-            accessToken: this.credential.accessToken,
+            accessToken: requestCredential.accessToken,
             method,
             targetUrl: urlStr,
-            privateJwk: this.credential.privateJwk
+            privateJwk: requestCredential.privateJwk
           }));
         }
         return await this.fetchImpl(urlStr, {
@@ -1504,12 +1513,13 @@ var TopoloClient = class _TopoloClient {
     };
     let res;
     try {
-      const attemptedCredential = this.credential;
+      const attemptedCredential = requestCredential;
       res = await fetchWithReadRetry();
       if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
+          requestCredential = refreshed;
           res = await fetchWithReadRetry();
         }
       }
@@ -1599,18 +1609,23 @@ var TopoloClient = class _TopoloClient {
     });
     return parsed;
   }
-  async loadCurrentCredential() {
-    if (!this.credentialProvider) return;
-    this.credentialLoadInFlight ??= this.credentialProvider().then((credential) => {
-      if (!credential) {
-        throw new TopoloAuthError("The configured Topolo credential is no longer available.");
-      }
-      this.credential = credential;
-      return credential;
-    }).finally(() => {
-      this.credentialLoadInFlight = null;
-    });
-    await this.credentialLoadInFlight;
+  async loadCurrentCredential(context) {
+    if (!this.credentialProvider) return this.credential;
+    const key = JSON.stringify(context);
+    let load = this.credentialLoadsInFlight.get(key);
+    if (!load) {
+      load = this.credentialProvider(context).then((credential) => {
+        if (!credential) {
+          throw new TopoloAuthError("The configured Topolo credential is no longer available.");
+        }
+        this.credential = credential;
+        return credential;
+      }).finally(() => {
+        this.credentialLoadsInFlight.delete(key);
+      });
+      this.credentialLoadsInFlight.set(key, load);
+    }
+    return load;
   }
   async refreshRejectedAccessToken(attemptedAccessToken) {
     if (this.credential.kind === "access_token" && this.credential.accessToken !== attemptedAccessToken) {
@@ -1940,6 +1955,14 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async issueExternalAgentCredential(input) {
+    const actionId = "app_topolo_auth.principal_credentials.issue";
+    const entry = await this.getAction(actionId);
+    if (entry.actionId !== actionId) {
+      throw new TopoloSdkError("unexpected_action", "External agent credential issuance resolved an unexpected action.");
+    }
+    return this.executeResolvedAction(entry, input, { confirm: true }, true);
+  }
   async uploadAction(action, content, input, options) {
     const entry = await this.getAction(action);
     const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
@@ -2071,7 +2094,7 @@ var TopoloClient = class _TopoloClient {
     }
     return this.executeResolvedAction(entry, input, options);
   }
-  async executeResolvedAction(entry, input, options) {
+  async executeResolvedAction(entry, input, options, preserveSensitiveResult = false) {
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     if (agentAccess === "off") {
       throw new TopoloPermissionError(
@@ -2129,7 +2152,7 @@ var TopoloClient = class _TopoloClient {
       },
       confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
     });
-    return redactActionResult(result);
+    return preserveSensitiveResult ? result : redactActionResult(result);
   }
   async buildVerifiedAgentActorEnvelope(actionId, input, resource) {
     if (!this.actorContext) return void 0;
@@ -2605,6 +2628,12 @@ function pickString(value) {
   }
   return void 0;
 }
+function requestActionId(headers) {
+  const value = Object.entries(headers ?? {}).find(
+    ([name]) => name.toLowerCase() === TOPOLO_ACTION_ID_HEADER.toLowerCase()
+  )?.[1];
+  return value?.trim() || void 0;
+}
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;

package/package.json

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