Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions docs/agents/adding-capabilities.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down
29 changes: 22 additions & 7 deletions docs/agents/secret-host-approval.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions packages/worker/client/mcp-apps/generated-ui-shell.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,13 @@
description: string
app_id: string | null
allowed_hosts: Array<string>
allowed_capabilities: Array<string>
created_at: string
updated_at: string
ttl_ms: number | null
}

type ValueMetadata = {

Check warning on line 31 in packages/worker/client/mcp-apps/generated-ui-shell.ts

View workflow job for this annotation

GitHub Actions / 🧹 Lint

eslint(no-unused-vars)

Type alias 'ValueMetadata' is declared but never used.
name: string
scope: ValueScope
value: string
Expand Down Expand Up @@ -772,6 +773,10 @@
(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 ||
Expand Down
Loading
Loading