diff --git a/docs/agents/adding-capabilities.md b/docs/agents/adding-capabilities.md
index 6614fa924e..5907001bfd 100644
--- a/docs/agents/adding-capabilities.md
+++ b/docs/agents/adding-capabilities.md
@@ -104,6 +104,11 @@ runs. Missing secrets still fail with the same "secret not found" guidance used
elsewhere, and secret-bearing capability inputs still require an authenticated
user.
+When a secret has an `allowed_capabilities` policy, Kody also checks that the
+current capability name is explicitly listed before resolving the placeholder.
+An empty `allowed_capabilities` list means no capability is allowed to resolve
+the secret until entries are added.
+
Use this for capabilities that need to accept a secret value as an argument but
are not themselves the host-approval boundary. Good fits include:
@@ -284,6 +289,8 @@ scope narrow:
- annotate only the exact credential fields, not the whole object
- prefer this for local persistence or device-side credential flows
+- tell users which capability names should be added to a secret's
+ `allowed_capabilities` policy when a workflow depends on restricted secrets
- avoid using it for generic remote API wrappers where fetch-time host approval
should remain the enforcement point
@@ -295,8 +302,8 @@ Public MCP behavior should be verified through the compact tool surface:
ranked results
- use `execute` to confirm the capability runs correctly
-Prefer E2E tests in `packages/worker/src/mcp/*.mcp-e2e.test.ts` for the real
-MCP contract.
+Prefer E2E tests in `packages/worker/src/mcp/*.mcp-e2e.test.ts` for the real MCP
+contract.
Registry invariants (duplicate capability names, domain/capability mismatches,
duplicate domain registration) are covered in
diff --git a/docs/agents/secret-host-approval.md b/docs/agents/secret-host-approval.md
index 1eb51634c4..dcc0b48bde 100644
--- a/docs/agents/secret-host-approval.md
+++ b/docs/agents/secret-host-approval.md
@@ -5,18 +5,19 @@ secrets.
## Rule
-Allowed outbound hosts for a secret are privileged policy, not normal secret
+Allowed outbound hosts for a secret and allowed capabilities for direct
+capability-input secret resolution are privileged policy, not normal secret
metadata.
-That policy must not be created, widened, or modified by:
+Those policies must not be created, widened, or modified by:
- MCP tools
- execute-time sandboxed code
- generated UI code
- capability handlers that serve agent-driven secret creation or update flows
-Allowed outbound hosts may only be changed through the authenticated account
-admin UI approval flow.
+Allowed outbound hosts and allowed capabilities may only be changed through the
+authenticated account admin UI.
In this repo, that means the user must approve host access through the account
secrets experience, such as `/account/secrets` and the focused approval route at
@@ -29,7 +30,7 @@ allowlist unless the user has already approved one or more hosts in the admin
UI.
Saving or updating a secret value does not authorize sending that secret to any
-host.
+host or passing it into any capability.
If an outbound request uses a placeholder such as `{{secret:name}}` and the
target host is not already approved for that secret, the correct behavior is:
@@ -42,16 +43,22 @@ target host is not already approved for that secret, the correct behavior is:
## What agents must not do
Do not design or document any MCP capability, generated UI helper, or client
-library that allows agent-controlled writes to a secret's allowed hosts.
+library that allows agent-controlled writes to a secret's allowed hosts or
+allowed capabilities.
Specifically, do not:
- add `allowed_hosts` or equivalent fields to MCP-facing secret create/update
inputs
+- add `allowed_capabilities` or equivalent fields to MCP-facing secret
+ create/update inputs
- imply that a generated UI can self-authorize a host just because it can save a
secret
+- imply that execute-time capability calls can widen which capabilities may
+ consume a secret
- imply that execute-time code can widen egress permissions
-- treat host approval as ordinary secret metadata editing
+- treat host approval or capability allowlists as ordinary secret metadata
+ editing
If a workflow would be smoother by auto-approving a host, the fix should be
better guidance, helper APIs, or UX around the approval flow, not a new write
@@ -62,7 +69,10 @@ path that bypasses the admin UI.
When writing capability descriptions or agent-facing docs:
- say explicitly that secret save/update does not grant outbound use
+- say explicitly that secret save/update does not grant capability access
- say explicitly that only the authenticated account admin UI can approve hosts
+- say explicitly that only the authenticated account admin UI can restrict which
+ capabilities may consume a secret directly
- tell agents to inspect secret metadata before making a secret-bearing request
- tell agents to surface the approval link and stop on deny
@@ -84,6 +94,9 @@ That feature is for cases where the capability needs the secret value itself,
for example to store credentials on a local connector or pass them into a
device-local action.
+If a secret has an allowed-capabilities policy, Kody enforces that allowlist by
+capability name before resolving the placeholder for the handler.
+
Use it narrowly:
- mark only the exact sensitive fields
@@ -105,11 +118,13 @@ Generated UIs may:
- save those values as secrets
- save and read back non-secret values for public configuration
- inspect secret metadata, including current allowed hosts
+- inspect secret metadata, including current allowed capabilities
- present approval links returned from blocked requests
Generated UIs may not:
- set allowed hosts directly
+- set allowed capabilities directly
- bypass the admin approval route
- silently retry secret-bearing requests after a deny
- use `executeCode(...)` as a general string interpolation mechanism for
diff --git a/packages/worker/client/mcp-apps/generated-ui-shell.node.test.ts b/packages/worker/client/mcp-apps/generated-ui-shell.node.test.ts
index b9857e9f83..de6274acef 100644
--- a/packages/worker/client/mcp-apps/generated-ui-shell.node.test.ts
+++ b/packages/worker/client/mcp-apps/generated-ui-shell.node.test.ts
@@ -215,7 +215,6 @@ test('readSavedAppSourceFromHostToolResult preserves host tool errors', () => {
errorMessage: 'Saved app not found for this user.',
})
})
-
test('buildLocalMessageLogRuntimeSource logs sendMessage locally outside hosted contexts', () => {
const originalWindow = globalThis.window
const originalDocument = globalThis.document
diff --git a/packages/worker/client/mcp-apps/generated-ui-shell.ts b/packages/worker/client/mcp-apps/generated-ui-shell.ts
index dac6861894..a42711b0f1 100644
--- a/packages/worker/client/mcp-apps/generated-ui-shell.ts
+++ b/packages/worker/client/mcp-apps/generated-ui-shell.ts
@@ -22,6 +22,7 @@ type SecretMetadata = {
description: string
app_id: string | null
allowed_hosts: Array
+ allowed_capabilities: Array
created_at: string
updated_at: string
ttl_ms: number | null
@@ -772,6 +773,10 @@ function initializeGeneratedUiShell() {
(secret.app_id == null || typeof secret.app_id === 'string') &&
Array.isArray(secret.allowed_hosts) &&
secret.allowed_hosts.every((host) => typeof host === 'string') &&
+ Array.isArray(secret.allowed_capabilities) &&
+ secret.allowed_capabilities.every(
+ (capability) => typeof capability === 'string',
+ ) &&
typeof secret.created_at === 'string' &&
typeof secret.updated_at === 'string' &&
(secret.ttl_ms == null ||
diff --git a/packages/worker/client/routes/account-secrets.tsx b/packages/worker/client/routes/account-secrets.tsx
index e14b4469a8..3e0b16a061 100644
--- a/packages/worker/client/routes/account-secrets.tsx
+++ b/packages/worker/client/routes/account-secrets.tsx
@@ -42,6 +42,7 @@ type SecretListItem = {
appId: string | null
appTitle: string | null
allowedHosts: Array
+ allowedCapabilities: Array
createdAt: string
updatedAt: string
ttlMs: number | null
@@ -68,6 +69,7 @@ type EditorState = {
description: string
value: string
allowedHosts: Array
+ allowedCapabilities: Array
}
type SelectionState = {
@@ -108,10 +110,56 @@ function createEmptyEditorState(apps: Array): EditorState {
description: '',
value: '',
allowedHosts: [''],
+ allowedCapabilities: [''],
}
}
+function coerceStringRows(list: Array): Array {
+ return list.filter((item): item is string => typeof item === 'string')
+}
+
+/** Matches server `normalizeAllowedHosts` in `#mcp/secrets/allowed-hosts.ts`. */
+function clientNormalizeAllowedHosts(hosts: Array): Array {
+ return Array.from(
+ new Set(
+ hosts
+ .map((host) => host.trim().toLowerCase())
+ .filter((host) => host.length > 0),
+ ),
+ ).sort()
+}
+
+/** Matches server `normalizeAllowedCapabilities` in `#mcp/secrets/allowed-capabilities.ts`. */
+function clientNormalizeAllowedCapabilities(
+ capabilities: Array,
+): Array {
+ return Array.from(
+ new Set(
+ capabilities
+ .map((value) => value.trim())
+ .filter((value) => value.length > 0),
+ ),
+ ).sort((left, right) => left.localeCompare(right))
+}
+
+function collectRepeatedTextRows(
+ form: HTMLFormElement,
+ listName: 'allowed-hosts' | 'allowed-capabilities',
+): Array {
+ const root = form.querySelector(`[data-repeat-list="${listName}"]`)
+ if (!root) return []
+ const out: Array = []
+ for (const row of root.children) {
+ if (!(row instanceof HTMLElement)) continue
+ const input = row.querySelector('input[type="text"]')
+ if (input instanceof HTMLInputElement) out.push(input.value)
+ }
+ return out
+}
+
function createEditorStateFromSecret(secret: SecretDetail): EditorState {
+ const allowedHosts = coerceStringRows(secret.allowedHosts)
+ const allowedCapabilities = coerceStringRows(secret.allowedCapabilities)
return {
currentId: secret.id,
name: secret.name,
@@ -119,7 +167,9 @@ function createEditorStateFromSecret(secret: SecretDetail): EditorState {
appId: secret.appId ?? '',
description: secret.description,
value: secret.value,
- allowedHosts: secret.allowedHosts.length > 0 ? secret.allowedHosts : [''],
+ allowedHosts: allowedHosts.length > 0 ? allowedHosts : [''],
+ allowedCapabilities:
+ allowedCapabilities.length > 0 ? allowedCapabilities : [''],
}
}
@@ -255,6 +305,7 @@ function filterSecrets(
secret.appTitle ?? '',
secret.scope,
...secret.allowedHosts,
+ ...secret.allowedCapabilities,
]
.join(' ')
.toLowerCase()
@@ -435,11 +486,19 @@ export function AccountSecretsRoute(handle: Handle) {
event.preventDefault()
if (saveState !== 'idle') return
+ const form = event.currentTarget as HTMLFormElement
+
saveState = 'saving'
message = null
handle.update()
try {
+ const allowedHosts = clientNormalizeAllowedHosts(
+ collectRepeatedTextRows(form, 'allowed-hosts'),
+ )
+ const allowedCapabilities = clientNormalizeAllowedCapabilities(
+ collectRepeatedTextRows(form, 'allowed-capabilities'),
+ )
const response = await fetch(accountSecretsApiPath, {
method: 'POST',
headers: {
@@ -455,7 +514,8 @@ export function AccountSecretsRoute(handle: Handle) {
appId: editorState.scope === 'app' ? editorState.appId : null,
description: editorState.description,
value: editorState.value,
- allowedHosts: editorState.allowedHosts,
+ allowedHosts,
+ allowedCapabilities,
}),
})
if (response.status === 401) {
@@ -569,6 +629,37 @@ export function AccountSecretsRoute(handle: Handle) {
handle.update()
}
+ function updateAllowedCapability(index: number, value: string) {
+ editorState = {
+ ...editorState,
+ allowedCapabilities: editorState.allowedCapabilities.map(
+ (capabilityName, capabilityIndex) =>
+ capabilityIndex === index ? value : capabilityName,
+ ),
+ }
+ handle.update()
+ }
+
+ function addAllowedCapability() {
+ editorState = {
+ ...editorState,
+ allowedCapabilities: [...editorState.allowedCapabilities, ''],
+ }
+ handle.update()
+ }
+
+ function removeAllowedCapability(index: number) {
+ const nextCapabilities = editorState.allowedCapabilities.filter(
+ (_capabilityName, capabilityIndex) => capabilityIndex !== index,
+ )
+ editorState = {
+ ...editorState,
+ allowedCapabilities:
+ nextCapabilities.length > 0 ? nextCapabilities : [''],
+ }
+ handle.update()
+ }
+
return () => {
const currentHref = getCurrentHref()
const selection = getSelectionState(currentHref)
@@ -1181,10 +1272,13 @@ export function AccountSecretsRoute(handle: Handle) {
a secret can be used.
-
+
{editorState.allowedHosts.map((host, index) => (
updateAllowedHost(
@@ -1228,6 +1322,72 @@ export function AccountSecretsRoute(handle: Handle) {
+
+
+ Allowed capabilities
+
+ Only capabilities listed here can resolve this secret
+ when used with an
+ x-kody-secret
+ input.
+