@topolo/sdk 0.21.2 → 0.21.3

package/dist/index.cjs

@@ -117,60 +117,6 @@ 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;
@@ -494,6 +440,139 @@ var TopoloHttpError = class extends TopoloSdkError {
   }
 };
 
+// src/action-secrets.ts
+var ACTION_SECRET_PREFIX = "topolo-secret:";
+function isActionSecretReference(value) {
+  return typeof value === "string" && value.startsWith(ACTION_SECRET_PREFIX);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sensitive(key, value) {
+  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (normalized === "capability") {
+    if (typeof value !== "string") return value !== null && value !== void 0 && typeof value !== "boolean" && typeof value !== "number";
+    const text2 = value.trim();
+    return Boolean(text2) && !/^[a-z][a-z0-9_-]{0,31}$/.test(text2);
+  }
+  return ["authorization", "cookie", "setcookie", "proxyauthorization"].includes(normalized) || /(token|secret|password|privatekey|apikey)$/.test(normalized);
+}
+function maskActionSecrets(value, secrets) {
+  let masked = value;
+  for (const [secret, reference] of secrets) {
+    const encoded = encodeURIComponent(secret);
+    const variants = [.../* @__PURE__ */ new Set([secret, encoded])].map((item) => item.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    masked = masked.replace(new RegExp(variants.join("|"), "g"), (match) => match === secret ? reference : encodeURIComponent(reference));
+  }
+  return masked;
+}
+async function resolveActionSecrets(value, store, secrets) {
+  if (isActionSecretReference(value)) {
+    if (!store) throw new TopoloSdkError("action_secret_store_required", "Protected action references require a secret store.");
+    const resolved = await store.load(value);
+    if (typeof resolved === "string" && resolved) secrets.set(resolved, value);
+    return resolved;
+  }
+  if (Array.isArray(value)) return Promise.all(value.map((item) => resolveActionSecrets(item, store, secrets)));
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, item]) => [key, await resolveActionSecrets(item, store, secrets)])));
+}
+async function protectActionResult(value, store) {
+  const secrets = /* @__PURE__ */ new Map();
+  async function protect(item, key = "") {
+    if (isActionSecretReference(item)) return item;
+    if (sensitive(key, item)) {
+      const reference = store ? await store.save(item) : "[REDACTED]";
+      if (typeof item === "string" && item) secrets.set(item, reference);
+      return reference;
+    }
+    if (Array.isArray(item)) return Promise.all(item.map((child) => protect(child)));
+    if (!isRecord(item)) return item;
+    return Object.fromEntries(await Promise.all(Object.entries(item).map(async ([name, child]) => [name, await protect(child, name)])));
+  }
+  const protectedValue = await protect(value);
+  async function protectEmbedded(item) {
+    if (typeof item === "string" && !isActionSecretReference(item) && maskActionSecrets(item, secrets) !== item) {
+      return store ? store.save(item) : maskActionSecrets(item, secrets);
+    }
+    if (Array.isArray(item)) return Promise.all(item.map(protectEmbedded));
+    if (!isRecord(item)) return item;
+    return Object.fromEntries(await Promise.all(Object.entries(item).map(async ([key, child]) => [key, await protectEmbedded(child)])));
+  }
+  return protectEmbedded(protectedValue);
+}
+function maskActionSecretValue(value, secrets) {
+  if (value instanceof Error) return maskActionSecretError(value, secrets);
+  if (typeof value === "string") return maskActionSecrets(value, secrets);
+  if (Array.isArray(value)) return value.map((item) => maskActionSecretValue(item, secrets));
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskActionSecretValue(item, secrets)]));
+}
+function maskActionSecretError(error, secrets) {
+  if (!(error instanceof Error)) return maskActionSecretValue(error, secrets);
+  const masked = Object.create(Object.getPrototypeOf(error));
+  for (const key of Object.getOwnPropertyNames(error)) {
+    const descriptor = Object.getOwnPropertyDescriptor(error, key);
+    if ("value" in descriptor) descriptor.value = maskActionSecretValue(descriptor.value, secrets);
+    Object.defineProperty(masked, key, descriptor);
+  }
+  return masked;
+}
+
+// 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/environment.ts
 var TOPOLO_RUNTIME_ENVIRONMENTS = ["production", "staging", "development", "local"];
 var TOPOLO_ENVIRONMENT_SERVICE_URLS = {
@@ -799,9 +878,9 @@ function inspectSchema(schema, path, root, depth) {
     return { path, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` };
   }
   const children = [];
-  if (isRecord(schema.properties)) children.push(...Object.entries(schema.properties));
-  if (isRecord(schema.$defs)) children.push(...Object.entries(schema.$defs));
-  if (isRecord(schema.definitions)) children.push(...Object.entries(schema.definitions));
+  if (isRecord2(schema.properties)) children.push(...Object.entries(schema.properties));
+  if (isRecord2(schema.$defs)) children.push(...Object.entries(schema.$defs));
+  if (isRecord2(schema.definitions)) children.push(...Object.entries(schema.definitions));
   children.push(
     ["additionalProperties", schema.additionalProperties],
     ["propertyNames", schema.propertyNames],
@@ -811,7 +890,7 @@ function inspectSchema(schema, path, root, depth) {
     ...arraySchemaEntries("oneOf", schema.oneOf)
   );
   for (const [key, child] of children) {
-    if (!isRecord(child)) continue;
+    if (!isRecord2(child)) continue;
     const issue = inspectSchema(child, `${path}.${key}`, root, depth + 1);
     if (issue) return issue;
   }
@@ -835,7 +914,7 @@ function validateNode(schema, value, path, root, errors, depth) {
   }
   if (Array.isArray(schema.allOf)) {
     for (const candidate of schema.allOf) {
-      if (isRecord(candidate)) validateNode(candidate, value, path, root, errors, depth + 1);
+      if (isRecord2(candidate)) validateNode(candidate, value, path, root, errors, depth + 1);
     }
   }
   if (Array.isArray(schema.anyOf) && !schema.anyOf.some((candidate) => candidateMatches(candidate, value, root, depth))) {
@@ -865,7 +944,7 @@ function validateNode(schema, value, path, root, errors, depth) {
   if (typeof value === "string") validateString(schema, value, path, errors);
   if (typeof value === "number") validateNumber(schema, value, path, errors);
   if (Array.isArray(value)) validateArray(schema, value, path, root, errors, depth);
-  if (isRecord(value)) validateObject(schema, value, path, root, errors, depth);
+  if (isRecord2(value)) validateObject(schema, value, path, root, errors, depth);
 }
 function validateObject(schema, value, path, root, errors, depth) {
   if (typeof schema.minProperties === "number" && Object.keys(value).length < schema.minProperties) {
@@ -874,25 +953,25 @@ function validateObject(schema, value, path, root, errors, depth) {
   if (typeof schema.maxProperties === "number" && Object.keys(value).length > schema.maxProperties) {
     errors.push({ path, code: "max_properties", message: `Expected at most ${schema.maxProperties} properties.` });
   }
-  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const properties = isRecord2(schema.properties) ? schema.properties : {};
   const required = Array.isArray(schema.required) ? schema.required.map(String) : [];
   for (const key of required) {
     if (!Object.prototype.hasOwnProperty.call(value, key)) {
       errors.push({ path: `${path}.${key}`, code: "required", message: "Required property is missing." });
     }
   }
-  if (isRecord(schema.propertyNames)) {
+  if (isRecord2(schema.propertyNames)) {
     for (const key of Object.keys(value)) {
       validateNode(schema.propertyNames, key, `${path}.${key}`, root, errors, depth + 1);
     }
   }
   for (const [key, child] of Object.entries(value)) {
     const childSchema = properties[key];
-    if (isRecord(childSchema)) {
+    if (isRecord2(childSchema)) {
       validateNode(childSchema, child, `${path}.${key}`, root, errors, depth + 1);
     } else if (schema.additionalProperties === false) {
       errors.push({ path: `${path}.${key}`, code: "additional_property", message: "Property is not declared by the action schema." });
-    } else if (isRecord(schema.additionalProperties)) {
+    } else if (isRecord2(schema.additionalProperties)) {
       validateNode(schema.additionalProperties, child, `${path}.${key}`, root, errors, depth + 1);
     }
   }
@@ -908,7 +987,7 @@ function validateArray(schema, value, path, root, errors, depth) {
     const unique = new Set(value.map((item) => JSON.stringify(item)));
     if (unique.size !== value.length) errors.push({ path, code: "unique_items", message: "Expected every item to be unique." });
   }
-  if (isRecord(schema.items)) {
+  if (isRecord2(schema.items)) {
     value.forEach((item, index) => validateNode(schema.items, item, `${path}[${index}]`, root, errors, depth + 1));
   }
 }
@@ -946,7 +1025,7 @@ function validateNumber(schema, value, path, errors) {
   }
 }
 function candidateMatches(candidate, value, root, depth) {
-  if (!isRecord(candidate)) return false;
+  if (!isRecord2(candidate)) return false;
   const issues = [];
   validateNode(candidate, value, "$", root, issues, depth + 1);
   return issues.length === 0;
@@ -960,24 +1039,24 @@ function resolveLocalReference(root, reference) {
       current = current[Number(token)];
       continue;
     }
-    if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, token)) return null;
+    if (!isRecord2(current) || !Object.prototype.hasOwnProperty.call(current, token)) return null;
     current = current[token];
   }
-  return isRecord(current) ? current : null;
+  return isRecord2(current) ? current : null;
 }
 function matchesType(type, value) {
   if (type === void 0) return true;
   if (Array.isArray(type)) return type.some((candidate) => matchesType(candidate, value));
   if (type === "null") return value === null;
   if (type === "array") return Array.isArray(value);
-  if (type === "object") return isRecord(value);
+  if (type === "object") return isRecord2(value);
   if (type === "integer") return typeof value === "number" && Number.isInteger(value);
   return typeof value === type;
 }
 function sameJsonValue(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
-function isRecord(value) {
+function isRecord2(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function isUrl(value) {
@@ -1234,7 +1313,7 @@ function fail(path, message) {
 
 // src/action-upload.ts
 function parseTopoloActionUploadContract(value) {
-  if (!isRecord2(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
+  if (!isRecord3(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
     throw new TopoloSdkError("upload_contract_unavailable", "This action does not publish a supported upload contract.");
   }
   const contentTypeField = requiredField(value.contentTypeField, "contentTypeField");
@@ -1313,17 +1392,17 @@ function prepareTopoloUrlSessionUploadInput(contractValue, byteLength, input, op
   };
 }
 function topoloUploadResponseValue(response, path) {
-  return path.split(".").reduce((value, segment) => isRecord2(value) ? value[segment] : void 0, response);
+  return path.split(".").reduce((value, segment) => isRecord3(value) ? value[segment] : void 0, response);
 }
 function redactTopoloUrlSessionResult(response, uploadUrlPath) {
   const redacted = cloneUploadValue(response);
   let target = redacted;
   const segments = uploadUrlPath.split(".");
   for (const segment of segments.slice(0, -1)) {
-    target = isRecord2(target) ? target[segment] : void 0;
+    target = isRecord3(target) ? target[segment] : void 0;
   }
   const finalSegment = segments.at(-1);
-  if (finalSegment && isRecord2(target) && finalSegment in target) target[finalSegment] = "[REDACTED]";
+  if (finalSegment && isRecord3(target) && finalSegment in target) target[finalSegment] = "[REDACTED]";
   redactUploadHeaders(redacted);
   return redacted;
 }
@@ -1347,7 +1426,7 @@ function mapUploadInput(contract, contentBase64, input, options) {
 }
 function cloneUploadValue(value) {
   if (Array.isArray(value)) return value.map(cloneUploadValue);
-  if (!isRecord2(value)) return value;
+  if (!isRecord3(value)) return value;
   return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneUploadValue(item)]));
 }
 function redactUploadHeaders(value) {
@@ -1355,9 +1434,9 @@ function redactUploadHeaders(value) {
     value.forEach(redactUploadHeaders);
     return;
   }
-  if (!isRecord2(value)) return;
+  if (!isRecord3(value)) return;
   for (const [key, item] of Object.entries(value)) {
-    if (key.toLowerCase() === "headers" && isRecord2(item)) {
+    if (key.toLowerCase() === "headers" && isRecord3(item)) {
       for (const header of Object.keys(item)) {
         if (["authorization", "cookie", "set-cookie", "proxy-authorization", "x-api-key"].includes(header.toLowerCase())) {
           item[header] = "[REDACTED]";
@@ -1386,7 +1465,7 @@ function decodedBase64Size(contentBase64) {
   return contentBase64.length / 4 * 3 - padding;
 }
 function parseCompleteContract(value) {
-  if (!isRecord2(value)) throw new TopoloSdkError("invalid_upload_contract", "The action upload completion contract is invalid.");
+  if (!isRecord3(value)) throw new TopoloSdkError("invalid_upload_contract", "The action upload completion contract is invalid.");
   return {
     actionId: requiredPath(value.actionId, "complete.actionId"),
     inputField: requiredField(value.inputField, "complete.inputField"),
@@ -1424,7 +1503,7 @@ function encodeTopoloActionBase64(bytes) {
   }
   return btoa(binary);
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
@@ -1437,6 +1516,8 @@ var TOPOLO_RESOURCE_ID_HEADER = "X-Topolo-Resource-ID";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
+  actionSecretStore;
+  actionSecrets = /* @__PURE__ */ new Map();
   credential;
   agent;
   actorContext;
@@ -1466,6 +1547,7 @@ var TopoloClient = class _TopoloClient {
     _TopoloClient.appIdCache.clear();
   }
   constructor(options) {
+    this.actionSecretStore = options.actionSecretStore;
     if (!options.credential) throw new TopoloAuthError("credential is required");
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
     this.credential = options.credential;
@@ -1487,6 +1569,7 @@ var TopoloClient = class _TopoloClient {
   }
   emit(event) {
     if (!this.debug) return;
+    event = maskActionSecretValue(event, this.actionSecrets);
     try {
       this.debug(event);
     } catch {
@@ -1872,7 +1955,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
-      if (!isRecord3(item)) continue;
+      if (!isRecord4(item)) continue;
       const s = item;
       const appId = typeof s.app_id === "string" ? s.app_id : typeof s.id === "string" ? s.id : null;
       if (!appId) continue;
@@ -1947,8 +2030,8 @@ var TopoloClient = class _TopoloClient {
       "app_topolo_auth.service_api_key_resources.list",
       { appId: service.appId }
     );
-    const payload = isRecord3(response) && isRecord3(response.data) ? response.data : response;
-    if (!isRecord3(payload) || !Array.isArray(payload.resources)) {
+    const payload = isRecord4(response) && isRecord4(response.data) ? response.data : response;
+    if (!isRecord4(payload) || !Array.isArray(payload.resources)) {
       throw new TopoloSdkError("resource_catalog_unavailable", "TopoloAuth did not return bindable resources.");
     }
     return {
@@ -2129,17 +2212,20 @@ var TopoloClient = class _TopoloClient {
   }
   async validateActionInput(action, input = {}) {
     const entry = await this.getAction(action);
-    return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, input) };
+    const resolved = await resolveActionSecrets(input, this.actionSecretStore, this.actionSecrets);
+    return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, resolved) };
   }
   async planAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
-    return this.planResolvedAction(entry, input, options);
+    const resolved = await resolveActionSecrets(input, this.actionSecretStore, this.actionSecrets);
+    return this.planResolvedAction(entry, resolved, options);
   }
   async prepareAction(action, input, options = {}) {
     const entry = await this.getAction(action);
     const example = (entry.agentContract?.examples ?? []).find((candidate) => Boolean(candidate?.input) && typeof candidate.input === "object" && !Array.isArray(candidate.input) && validateTopoloActionInput(entry.inputSchema, candidate.input).valid) ?? null;
     const selectedInput = input ?? example?.input ?? {};
-    const plan = this.planResolvedAction(entry, selectedInput, options);
+    const resolved = await resolveActionSecrets(selectedInput, this.actionSecretStore, this.actionSecrets);
+    const plan = this.planResolvedAction(entry, resolved, options);
     return {
       action: entry,
       example,
@@ -2176,7 +2262,7 @@ var TopoloClient = class _TopoloClient {
       confirmationRequired,
       confirmationProvided: options.confirm === true,
       executable: validation.valid && agentAccess !== "off" && (!confirmationRequired || options.confirm === true),
-      request,
+      request: maskActionSecretValue(request, this.actionSecrets),
       verification: stringArray(entry.agentContract?.verify),
       rollbackActionId: pickActionString(entry.agentContract?.rollbackActionId),
       nextActionIds: stringArray(entry.agentContract?.nextActionIds)
@@ -2206,6 +2292,7 @@ var TopoloClient = class _TopoloClient {
         `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`
       );
     }
+    input = await resolveActionSecrets(input, this.actionSecretStore, this.actionSecrets);
     const validation = validateTopoloActionInput(entry.inputSchema, input);
     if (!validation.valid) {
       throw new TopoloSdkError(
@@ -2236,22 +2323,31 @@ var TopoloClient = class _TopoloClient {
       }
     }
     const service = entry.appSlug || entry.appId;
-    const result = await this.request({
-      service,
-      ...entry.apiBaseUrl ? { baseUrl: entry.apiBaseUrl } : {},
-      method: entry.method,
-      path: mapped.path,
-      ...mapped.query ? { query: mapped.query } : {},
-      ...mapped.body !== void 0 ? { body: mapped.body } : {},
-      ...options.resource ? { resource: options.resource } : {},
-      ...resolvedActorEnvelope ? { actorEnvelope: resolvedActorEnvelope } : {},
-      headers: {
-        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
-        [TOPOLO_ACTION_NAME_HEADER]: entry.name
-      },
-      confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
-    });
-    return preserveSensitiveResult ? result : redactActionResult(result);
+    let result;
+    try {
+      result = await this.request({
+        service,
+        ...entry.apiBaseUrl ? { baseUrl: entry.apiBaseUrl } : {},
+        method: entry.method,
+        path: mapped.path,
+        ...mapped.query ? { query: mapped.query } : {},
+        ...mapped.body !== void 0 ? { body: mapped.body } : {},
+        ...options.resource ? { resource: options.resource } : {},
+        ...resolvedActorEnvelope ? { actorEnvelope: resolvedActorEnvelope } : {},
+        headers: {
+          [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+          [TOPOLO_ACTION_NAME_HEADER]: entry.name
+        },
+        confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
+      });
+    } catch (error) {
+      throw maskActionSecretError(error, this.actionSecrets);
+    }
+    return preserveSensitiveResult ? result : await protectActionResult(result, this.actionSecretStore);
+  }
+  async releaseActionSecret(reference) {
+    if (!this.actionSecretStore) throw new TopoloSdkError("action_secret_store_required", "Protected action references require a secret store.");
+    await this.actionSecretStore.delete(reference);
   }
   async buildVerifiedAgentActorEnvelope(actionId, input, resource) {
     if (!this.actorContext) return void 0;
@@ -2398,7 +2494,7 @@ function resolveConfiguredAppId(slug, appIds) {
   return null;
 }
 function normalizeApiKeyResourceMetadata(input) {
-  if (!isRecord3(input)) return null;
+  if (!isRecord4(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const label = readString(input.label);
   const emptyLabel = readString(input.emptyLabel ?? input.empty_label);
@@ -2432,7 +2528,7 @@ function normalizeApiKeyResourceMetadataList(input) {
   return resources;
 }
 function normalizeBindableResource(input) {
-  if (!isRecord3(input)) return null;
+  if (!isRecord4(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const resourceId = readString(input.resourceId ?? input.resource_id);
   if (!resourceType || !resourceId) return null;
@@ -2443,13 +2539,13 @@ function normalizeBindableResource(input) {
     slug: readOptionalString(input.slug),
     status: readOptionalString(input.status),
     organizationId: readOptionalString(input.organizationId ?? input.organization_id),
-    metadata: isRecord3(input.metadata) ? input.metadata : {}
+    metadata: isRecord4(input.metadata) ? input.metadata : {}
   };
 }
 function normalizeResourceBindings(input) {
   if (!Array.isArray(input)) return [];
   return input.flatMap((binding) => {
-    if (!isRecord3(binding)) return [];
+    if (!isRecord4(binding)) return [];
     const resourceType = readString(binding.resourceType ?? binding.resource_type);
     const resourceId = readString(binding.resourceId ?? binding.resource_id);
     return resourceType && resourceId ? [{ resourceType, resourceId }] : [];
@@ -2462,30 +2558,9 @@ function readOptionalString(value) {
   const normalized = readString(value);
   return normalized || null;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function redactActionResult(value) {
-  if (Array.isArray(value)) return value.map(redactActionResult);
-  if (!isRecord3(value)) return value;
-  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
-    key,
-    isSensitiveActionResultKey(key, item) ? "[REDACTED]" : redactActionResult(item)
-  ]));
-}
-function isSensitiveActionResultKey(key, value) {
-  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
-  if (normalized === "capability") return isCredentialShaped(value);
-  return ["authorization", "cookie", "setcookie", "proxyauthorization"].includes(normalized) || /(token|secret|password|privatekey|apikey)$/.test(normalized);
-}
-var PLAIN_ENUM_VALUE = /^[a-z][a-z0-9_-]{0,31}$/;
-function isCredentialShaped(value) {
-  if (typeof value !== "string") return value !== null && value !== void 0 && typeof value !== "boolean" && typeof value !== "number";
-  const trimmed = value.trim();
-  if (!trimmed) return false;
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) return true;
-  return !PLAIN_ENUM_VALUE.test(trimmed);
-}
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
   for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceUrls?.[serviceKey];
@@ -2555,14 +2630,14 @@ function catalogSearchQuery(options) {
   return query;
 }
 function normalizeCatalogPage(value) {
-  if (!isRecord3(value)) return { nextCursor: null, hasMore: false };
+  if (!isRecord4(value)) return { nextCursor: null, hasMore: false };
   return {
     nextCursor: typeof value.nextCursor === "string" && value.nextCursor ? value.nextCursor : null,
     hasMore: value.hasMore === true
   };
 }
 function normalizeServiceCatalogEntry(item) {
-  if (!isRecord3(item)) return null;
+  if (!isRecord4(item)) return null;
   const appId = typeof item.app_id === "string" ? item.app_id : typeof item.id === "string" ? item.id : null;
   if (!appId) return null;
   const permissions = Array.isArray(item.granted_permissions) ? item.granted_permissions.filter(
@@ -3027,7 +3102,7 @@ var INVERSE_OPERATIONS = /* @__PURE__ */ new Map([
   ["restore", "archive"],
   ["unpublish", "publish"]
 ]);
-function isRecord4(value) {
+function isRecord5(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function nonEmptyStrings(value) {
@@ -3065,10 +3140,10 @@ function collectionFor(action, resource) {
   return resource.endsWith("s") ? resource : `${resource}s`;
 }
 function isConcreteOutputSchema(schema) {
-  if (!isRecord4(schema)) return false;
+  if (!isRecord5(schema)) return false;
   if (typeof schema.$ref === "string" && schema.$ref.trim()) return true;
-  if (schema.type === "array" && isRecord4(schema.items) && Object.keys(schema.items).length > 0) return true;
-  if (isRecord4(schema.properties) && Object.keys(schema.properties).length > 0) return true;
+  if (schema.type === "array" && isRecord5(schema.items) && Object.keys(schema.items).length > 0) return true;
+  if (isRecord5(schema.properties) && Object.keys(schema.properties).length > 0) return true;
   return ["oneOf", "anyOf", "allOf"].some((key) => Array.isArray(schema[key]) && schema[key].some(isConcreteOutputSchema));
 }
 function resourceSchema(resource) {
@@ -3195,10 +3270,10 @@ function isDynamicIdentifier(hint) {
   return words === "id" || words.endsWith(" id");
 }
 function localReference(rootSchema, reference) {
-  if (!isRecord4(rootSchema) || typeof reference !== "string" || !reference.startsWith("#/")) return null;
+  if (!isRecord5(rootSchema) || typeof reference !== "string" || !reference.startsWith("#/")) return null;
   return reference.slice(2).split("/").reduce((value, segment) => {
     const key = segment.replaceAll("~1", "/").replaceAll("~0", "~");
-    return isRecord4(value) ? value[key] : void 0;
+    return isRecord5(value) ? value[key] : void 0;
   }, rootSchema);
 }
 function representativeNumber(schema, hint) {
@@ -3212,9 +3287,9 @@ function representativeNumber(schema, hint) {
   return integer ? Math.round(value) : value;
 }
 function sampleForSchema(schema, depth = 0, hint = "value", rootSchema = schema) {
-  if (!isRecord4(schema) || depth > 20) return null;
+  if (!isRecord5(schema) || depth > 20) return null;
   const referenced = localReference(rootSchema, schema.$ref);
-  if (isRecord4(referenced)) return sampleForSchema(referenced, depth + 1, hint, rootSchema);
+  if (isRecord5(referenced)) return sampleForSchema(referenced, depth + 1, hint, rootSchema);
   if (schema.const !== void 0) return schema.const;
   if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
   if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) return sampleForSchema(schema.oneOf[0], depth + 1, hint, rootSchema);
@@ -3234,8 +3309,8 @@ function sampleForSchema(schema, depth = 0, hint = "value", rootSchema = schema)
   }
   if (schema.type === "string") return isDynamicIdentifier(hint) ? void 0 : sampleString(schema, hint);
   if (schema.type === "null") return null;
-  if (schema.type === "object" || isRecord4(schema.properties)) {
-    const properties = isRecord4(schema.properties) ? schema.properties : {};
+  if (schema.type === "object" || isRecord5(schema.properties)) {
+    const properties = isRecord5(schema.properties) ? schema.properties : {};
     const required = new Set(Array.isArray(schema.required) ? schema.required : []);
     const entries = Object.entries(properties).filter(([key]) => required.has(key)).map(([key, child]) => [key, sampleForSchema(child, depth + 1, key, rootSchema)]).filter(([, value]) => value !== void 0);
     return Object.fromEntries(entries);
@@ -3243,9 +3318,9 @@ function sampleForSchema(schema, depth = 0, hint = "value", rootSchema = schema)
   return null;
 }
 function hasRequiredDynamicIdentifier(schema, depth = 0, rootSchema = schema) {
-  if (!isRecord4(schema) || depth > 20) return false;
+  if (!isRecord5(schema) || depth > 20) return false;
   const referenced = localReference(rootSchema, schema.$ref);
-  if (isRecord4(referenced)) return hasRequiredDynamicIdentifier(referenced, depth + 1, rootSchema);
+  if (isRecord5(referenced)) return hasRequiredDynamicIdentifier(referenced, depth + 1, rootSchema);
   if (Array.isArray(schema.oneOf)) {
     return schema.oneOf.some((candidate) => hasRequiredDynamicIdentifier(candidate, depth + 1, rootSchema));
   }
@@ -3255,10 +3330,10 @@ function hasRequiredDynamicIdentifier(schema, depth = 0, rootSchema = schema) {
   if (schema.type === "array") {
     return hasRequiredDynamicIdentifier(schema.items, depth + 1, rootSchema);
   }
-  if (schema.type !== "object" && !isRecord4(schema.properties)) return false;
-  const properties = isRecord4(schema.properties) ? schema.properties : {};
+  if (schema.type !== "object" && !isRecord5(schema.properties)) return false;
+  const properties = isRecord5(schema.properties) ? schema.properties : {};
   const required = new Set(Array.isArray(schema.required) ? schema.required : []);
-  return Object.entries(properties).some(([key, child]) => required.has(key) && (isRecord4(child) && child.type === "string" && isDynamicIdentifier(key) || hasRequiredDynamicIdentifier(child, depth + 1, rootSchema)));
+  return Object.entries(properties).some(([key, child]) => required.has(key) && (isRecord5(child) && child.type === "string" && isDynamicIdentifier(key) || hasRequiredDynamicIdentifier(child, depth + 1, rootSchema)));
 }
 function actionPrefix(name, operation) {
   const tokens = String(name || "").split(/[._:-]+/).filter(Boolean);
@@ -3331,13 +3406,13 @@ function enrichActionContract(manifest, action, allActions = manifest.actions ||
   const outputSchema = isConcreteOutputSchema(action.outputSchema) ? structuredClone(action.outputSchema) : derivedOutputSchema(action);
   const resource = resourceFor(action);
   const readOnly = action.readOnly !== void 0 ? action.readOnly === true : action.method === "GET";
-  const existing = isRecord4(action.agentContract) ? structuredClone(action.agentContract) : {};
+  const existing = isRecord5(action.agentContract) ? structuredClone(action.agentContract) : {};
   const declaredAgentContract = Object.keys(existing).length > 0;
-  const recovery = isRecord4(existing.recovery) ? existing.recovery : recoveryFor(action, allActions, appId);
+  const recovery = isRecord5(existing.recovery) ? existing.recovery : recoveryFor(action, allActions, appId);
   const rollbackActionId = typeof existing.rollbackActionId === "string" && existing.rollbackActionId.trim() ? existing.rollbackActionId.trim() : recovery.mode === "compensating_action" ? recovery.actionId : void 0;
   const inputExample = sampleForSchema(action.inputSchema);
   const expectedExample = readOnly ? `A successful response conforming to outputSchema; verify the returned ${resource.replaceAll("_", " ")} belongs to the selected resource context.` : `A successful response conforming to outputSchema; re-read the affected ${resource.replaceAll("_", " ")} to verify the intended change.`;
-  const examples = Array.isArray(existing.examples) && existing.examples.length > 0 ? existing.examples.map((example) => isRecord4(example) && Object.hasOwn(example, "input") ? { ...example, expected: typeof example.expected === "string" && example.expected.trim() ? example.expected : expectedExample } : { input: example, expected: expectedExample }) : [{
+  const examples = Array.isArray(existing.examples) && existing.examples.length > 0 ? existing.examples.map((example) => isRecord5(example) && Object.hasOwn(example, "input") ? { ...example, expected: typeof example.expected === "string" && example.expected.trim() ? example.expected : expectedExample } : { input: example, expected: expectedExample }) : [{
     input: inputExample ?? {},
     expected: expectedExample
   }];
@@ -3350,7 +3425,7 @@ function enrichActionContract(manifest, action, allActions = manifest.actions ||
       ...existing,
       docsUrl,
       ...existingDocsUrl && existingDocsUrl !== docsUrl ? { guideUrl: existingDocsUrl } : {},
-      resource: isRecord4(existing.resource) ? existing.resource : { kind: resource, idPath: readOnly && ["list", "search"].includes(operationFor(action)) ? "$.items[].id" : "$.id" },
+      resource: isRecord5(existing.resource) ? existing.resource : { kind: resource, idPath: readOnly && ["list", "search"].includes(operationFor(action)) ? "$.items[].id" : "$.id" },
       effects: nonEmptyStrings(existing.effects) ? existing.effects : [readOnly ? `Reads ${resource.replaceAll("_", " ")} data without changing service state.` : action.destructive === true || action.method === "DELETE" ? `Permanently removes or invalidates ${resource.replaceAll("_", " ")} state.` : `Changes ${resource.replaceAll("_", " ")} state in the selected Topolo resource context.`],
       errors: mergeErrors(defaultErrors(action), existing.errors),
       verify: nonEmptyStrings(existing.verify) ? existing.verify : [`Validate the response against outputSchema and ${readOnly ? "confirm it belongs to the selected resource context" : "re-read the affected resource to confirm the intended state"}.`],
@@ -3365,15 +3440,15 @@ function enrichActionContract(manifest, action, allActions = manifest.actions ||
 function actionContractCompleteness(action) {
   const contract = action?.agentContract;
   return {
-    inputSchema: isRecord4(action?.inputSchema),
+    inputSchema: isRecord5(action?.inputSchema),
     outputSchema: isConcreteOutputSchema(action?.outputSchema),
     effects: nonEmptyStrings(contract?.effects),
     errors: Array.isArray(contract?.errors) && contract.errors.length > 0,
     docs: typeof contract?.docsUrl === "string" && contract.docsUrl.startsWith("https://"),
     examples: Array.isArray(contract?.examples) && contract.examples.length > 0,
     verification: nonEmptyStrings(contract?.verify),
-    recovery: isRecord4(contract?.recovery) && ["not_applicable", "compensating_action", "irreversible"].includes(contract.recovery.mode),
-    agentContract: isRecord4(contract) && isRecord4(contract.resource) && nonEmptyStrings(contract.effects) && Array.isArray(contract.errors) && contract.errors.length > 0
+    recovery: isRecord5(contract?.recovery) && ["not_applicable", "compensating_action", "irreversible"].includes(contract.recovery.mode),
+    agentContract: isRecord5(contract) && isRecord5(contract.resource) && nonEmptyStrings(contract.effects) && Array.isArray(contract.errors) && contract.errors.length > 0
   };
 }
 
@@ -3850,7 +3925,7 @@ var DIMENSION_VALUE_TYPES = ["string", "number", "boolean", "date", "datetime"];
 var SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 function validateTopoloWidgetResponse(response) {
   const errors = [];
-  if (!isRecord5(response)) return { ok: false, errors: ["response must be an object"] };
+  if (!isRecord6(response)) return { ok: false, errors: ["response must be an object"] };
   exactValue(response.contractVersion, CONTRACT_VERSION, "contractVersion", errors);
   nonEmptyString(response.appId, "appId", errors);
   nonEmptyString(response.serviceName, "serviceName", errors);
@@ -4046,7 +4121,7 @@ function validateContribution(value, path, widget, errors) {
     nonEmptyString(value.workspaceSelector.resourceType, `${path}.workspaceSelector.resourceType`, errors);
     nonEmptyString(value.workspaceSelector.label, `${path}.workspaceSelector.label`, errors);
     booleanValue(value.workspaceSelector.supportsMultiple, `${path}.workspaceSelector.supportsMultiple`, errors);
-    if (value.workspaceSelector.mode === "required" && requiresContent(widget) && isRecord5(widget.resource) && typeof widget.resource.resourceId !== "string") {
+    if (value.workspaceSelector.mode === "required" && requiresContent(widget) && isRecord6(widget.resource) && typeof widget.resource.resourceId !== "string") {
       errors.push(`${path}.workspaceSelector requires a bound resourceId for ready or stale data`);
     }
   }
@@ -4198,36 +4273,36 @@ function widgetActionKeys(widget) {
   const keys = /* @__PURE__ */ new Set();
   for (const collection of [widget.controls, widget.actions]) {
     if (!Array.isArray(collection)) continue;
-    for (const action of collection) if (isRecord5(action) && typeof action.id === "string") keys.add(action.id);
+    for (const action of collection) if (isRecord6(action) && typeof action.id === "string") keys.add(action.id);
   }
   return keys;
 }
 function validateRuntimeSemantics(widget, contributionPath, declared, errors) {
   const metrics = Array.isArray(widget.metrics) ? widget.metrics : [];
   for (const metric of metrics) {
-    if (!isRecord5(metric) || typeof metric.key !== "string") continue;
+    if (!isRecord6(metric) || typeof metric.key !== "string") continue;
     if (!declared.metricKeys.has(metric.key)) errors.push(`${contributionPath}.metricDefinitions is missing runtime metric ${metric.key}`);
     validateRuntimeDimensions(metric.dimensions, declared.dimensionKeys, contributionPath, errors);
-    if (isRecord5(metric.series)) {
+    if (isRecord6(metric.series)) {
       if (typeof metric.series.id === "string" && !declared.seriesKeys.has(metric.series.id)) errors.push(`${contributionPath}.seriesDefinitions is missing runtime series ${metric.series.id}`);
       validateSeriesDimensions(metric.series, declared.dimensionKeys, contributionPath, errors);
     }
   }
   const series2 = Array.isArray(widget.series) ? widget.series : [];
   for (const item of series2) {
-    if (!isRecord5(item)) continue;
+    if (!isRecord6(item)) continue;
     if (typeof item.id === "string" && !declared.seriesKeys.has(item.id)) errors.push(`${contributionPath}.seriesDefinitions is missing runtime series ${item.id}`);
     validateSeriesDimensions(item, declared.dimensionKeys, contributionPath, errors);
   }
 }
 function validateSeriesDimensions(series2, known, path, errors) {
   if (!Array.isArray(series2.points)) return;
-  for (const point of series2.points) if (isRecord5(point)) validateRuntimeDimensions(point.dimensions, known, path, errors);
+  for (const point of series2.points) if (isRecord6(point)) validateRuntimeDimensions(point.dimensions, known, path, errors);
 }
 function validateRuntimeDimensions(value, known, path, errors) {
   if (!Array.isArray(value)) return;
   for (const dimension2 of value) {
-    if (isRecord5(dimension2) && typeof dimension2.key === "string" && !known.has(dimension2.key)) {
+    if (isRecord6(dimension2) && typeof dimension2.key === "string" && !known.has(dimension2.key)) {
       errors.push(`${path}.dimensions is missing runtime dimension ${dimension2.key}`);
     }
   }
@@ -4329,10 +4404,10 @@ function validateNotifications(value, path, errors, requireOne) {
   });
 }
 function requiresContent(widget) {
-  return isRecord5(widget.state) && (widget.state.status === "ready" || widget.state.status === "stale");
+  return isRecord6(widget.state) && (widget.state.status === "ready" || widget.state.status === "stale");
 }
 function recordValue(value, path, errors) {
-  if (!isRecord5(value)) {
+  if (!isRecord6(value)) {
     errors.push(`${path} must be an object`);
     return false;
   }
@@ -4397,7 +4472,7 @@ function isIsoTimestamp(value) {
 function isPositiveNumber(value) {
   return typeof value === "number" && value > 0;
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -4939,19 +5014,19 @@ var TOPOLO_WIDGET_OUTPUT_SCHEMA = Object.freeze({
   additionalProperties: false
 });
 function isTopoloWidgetOutputSchema(schema) {
-  if (!isRecord6(schema) || !isRecord6(schema.properties)) return false;
+  if (!isRecord7(schema) || !isRecord7(schema.properties)) return false;
   const properties = schema.properties;
-  const widgetItemSchema = isRecord6(properties.widgets) && isRecord6(properties.widgets.items) ? properties.widgets.items : void 0;
-  const widgetProperties = widgetItemSchema && isRecord6(widgetItemSchema.properties) ? widgetItemSchema.properties : void 0;
-  const contributionSchema = widgetProperties && isRecord6(widgetProperties.contribution) ? widgetProperties.contribution : void 0;
-  const contractVersion = isRecord6(properties.contractVersion) ? properties.contractVersion.const : void 0;
-  return schema.type === "object" && contractVersion === "3.0.0" && isRecord6(properties.widgets) && properties.widgets.type === "array" && widgetItemSchema?.type === "object" && hasRequired(schema, "contractVersion") && hasRequired(schema, "widgets") && hasRequired(widgetItemSchema, "contribution") && hasRequired(contributionSchema, "datasets") && hasRequired(contributionSchema, "compatibleVisualizations") && hasRequired(contributionSchema, "defaultVisualization");
+  const widgetItemSchema = isRecord7(properties.widgets) && isRecord7(properties.widgets.items) ? properties.widgets.items : void 0;
+  const widgetProperties = widgetItemSchema && isRecord7(widgetItemSchema.properties) ? widgetItemSchema.properties : void 0;
+  const contributionSchema = widgetProperties && isRecord7(widgetProperties.contribution) ? widgetProperties.contribution : void 0;
+  const contractVersion = isRecord7(properties.contractVersion) ? properties.contractVersion.const : void 0;
+  return schema.type === "object" && contractVersion === "3.0.0" && isRecord7(properties.widgets) && properties.widgets.type === "array" && widgetItemSchema?.type === "object" && hasRequired(schema, "contractVersion") && hasRequired(schema, "widgets") && hasRequired(widgetItemSchema, "contribution") && hasRequired(contributionSchema, "datasets") && hasRequired(contributionSchema, "compatibleVisualizations") && hasRequired(contributionSchema, "defaultVisualization");
 }
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function hasRequired(schema, field) {
-  return isRecord6(schema) && Array.isArray(schema.required) && schema.required.includes(field);
+  return isRecord7(schema) && Array.isArray(schema.required) && schema.required.includes(field);
 }
 
 // src/index.ts