Skip to content
Merged
Show file tree
Hide file tree
Changes from 9 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
10 changes: 2 additions & 8 deletions docs/contributing/adding-capabilities.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@ Authoring flow:
**`getStaticRegistry()`** on first use per isolate, providing access to
builtin capabilities, handlers, tool descriptors, and domain metadata. At
request time, **`getCapabilityRegistryForContext()`** merges MCP client
servers and OpenAPI bindings, then applies caller
role/permission/feature-flag filtering for search and execute.
servers, then applies caller role/permission/feature-flag filtering for
search and execute.

To merge extra domains later (e.g. plugins), the seam is:
`buildCapabilityRegistry([...builtinDomains, ...extraDomains])` with real
Expand All @@ -70,12 +70,6 @@ driven by the `mcp_server_settings` D1 table and per-user hub snapshots. Home
automation and similar outbound tools are ordinary MCP servers
(`kody.mcp["home"]`), not a separate product surface.

**OpenAPI bindings:** the same runtime merge also synthesizes `openapi:<name>`
domains from the user's curated OpenAPI provider bindings (see
[`architecture/openapi-bindings.md`](./architecture/openapi-bindings.md)),
stored in user-scoped D1 tables and invoked as
`kody.openapi["<name>"].<operation_slug>(input)`.

`defineCapability()` in
`packages/worker/src/mcp/capabilities/define-capability.ts` normalizes Zod →
JSON Schema and wraps handlers with logging; domain helpers call it for you.
Expand Down
22 changes: 6 additions & 16 deletions docs/contributing/architecture/data-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -382,16 +382,9 @@ The schema is defined by migrations in `packages/worker/migrations/`:
refresh token ciphertext. Soak dual-write keeps `*_secret_name` columns
pointing at `secret_entries`. The non-secret `client_id` is stored inline on
the owning app row.
- `user_openapi_bindings` (`0001-squashed-init.sql`): per-user OpenAPI provider
binding rows keyed by `(user_id, name)`. Holds `spec_url`, `api_base_url`,
`auth_json`, `selection_json`, `include_destructive`, and optional description
/ spec metadata. See [OpenAPI provider bindings](./openapi-bindings.md).
- `user_openapi_binding_operations` (`0001-squashed-init.sql`): per-operation
child rows keyed by `(user_id, binding_name, slug)`, with composite FK
`(user_id, binding_name) → user_openapi_bindings(user_id, name)`
(`ON DELETE CASCADE`). Holds `operation_json` for each curated operation
snapshot entry. Account deletion lists operations before bindings so cleanup
does not rely on CASCADE.
- `user_openapi_bindings` / `user_openapi_binding_operations`
(`0001-squashed-init.sql`): leftover squash-create tables. Migration `0037`
drops them. Do not add new readers or writers.

App access pattern:

Expand Down Expand Up @@ -1273,12 +1266,9 @@ on write unless a migration backfills existing rows.
`POST /__maintenance/backfill-integration-credentials` copies leftover
secret-store values onto null ciphertext columns (see
[Secret rotation](../secret-rotation.md#backfilling-integration-owned-credentials)).
- `user_openapi_bindings.auth_json`, `user_openapi_bindings.selection_json`, and
`user_openapi_binding_operations.operation_json` (`0001-squashed-init.sql`,
`packages/worker/src/openapi/`) store the auth discriminant, selection object,
and per-operation snapshot object. Parsers in the OpenAPI binding service own
the shapes; credential values are never stored (only secret / integration name
references inside `auth_json`).
- `user_openapi_bindings` / `user_openapi_binding_operations` JSON columns
(`0001-squashed-init.sql`) are leftover squash-create shapes. Migration `0037`
drops the tables. Do not add new parsers.

### Durable Object id contracts

Expand Down
7 changes: 1 addition & 6 deletions docs/contributing/architecture/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,9 +109,6 @@ smoke does not prove MCP execute health.
Kody connects to as a client (per-user hub Durable Object, OAuth flow, and
`kody.mcp[...]` capability synthesis). Local-network systems reach Kody the
same way (outbound MCP under `kody.mcp[...]`).
- [OpenAPI provider bindings](./openapi-bindings.md): user-scoped curated
OpenAPI bindings with runtime-synthesized `openapi:<name>` domains callable
via `kody.openapi[...]` (host approval never widened by untrusted specs).
- [OAuth integrations](./integrations.md): first-class OAuth apps and
connections in D1 (`user_oauth_apps` / `user_integrations`), including
operator-provisioned platform (built-in) apps (`platform_oauth_apps`),
Expand Down Expand Up @@ -139,9 +136,7 @@ arbitrary hosts:
This invariant must hold for any code path that materializes an integration
token and then attaches it to an outbound request. Host-side refresh via
`integration_token_refresh` materializes tokens only server-side and returns
metadata. `refreshAccessToken` is the raw-token helper: it persists through that
same host path, then returns the access token for user-lane integrations only.
See [OAuth integrations](./integrations.md).
metadata. See [OAuth integrations](./integrations.md).

## Source of truth in code

Expand Down
43 changes: 14 additions & 29 deletions docs/contributing/architecture/integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,16 +148,10 @@ retries with a `{{secret:…}}` placeholder `Authorization` header, so raw token
never enter the sandbox heap. Package code that triggers refresh through
`createAuthenticatedFetch` does not need a secret-write (`allowed_packages`)
grant — the system persists rotated tokens host-side and the package never sees
or writes token values. `refreshAccessToken` is the raw-token helper for auth
patterns that cannot use an Authorization header (WebSockets, SDK constructors,
query-param tokens). It also refreshes host-side
(`integration_refresh_access_token` → `refreshIntegrationTokens`) so token
rotation does not need an `allowed_packages` write grant, then materializes the
new access token for user-lane integrations and throws for platform ones
(`integration_get` carries `platform: true`). The integration usage grant
(`any`, or `packages` that includes that package) decides whether a package —
including an unadopted community fork — can refresh or materialize tokens.
Token-exchange request building is shared:
or writes token values. Host-side refresh returns metadata only; there is no
raw-token helper. The integration usage grant (`any`, or `packages` that
includes that package) decides whether a package — including an unadopted
community fork — can refresh tokens. Token-exchange request building is shared:
`packages/worker/src/integrations/oauth-token-exchange.ts` lives in the
shared-primitive layer so both the `/connect/oauth` handlers and the MCP refresh
capability use it within the import boundaries.
Expand Down Expand Up @@ -329,32 +323,23 @@ connections instead.
Domain: `integrations`
(`packages/worker/src/mcp/capabilities/integrations/domain.ts`).

| Capability | Role |
| ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `integration_save` / `_get` / `_list` / `_delete` | Connection CRUD with flat `clientId` output |
| `integration_lock` | Tighten-only usage lock: packages mode + add a package id; unlock is website-only |
| `integration_oauth_app_list` | Apps with connection counts and sibling connection names |
| `integration_oauth_app_delete` | Delete a user-lane app and every connection on it |
| `integration_oauth_app_rotate_credentials` | Rotate shared app `clientId` / client-secret name |
| `integration_platform_app_list` | Always empty while platform apps are retired; operators use admin list |
| `integration_token_refresh` | Host-side OAuth refresh; returns metadata only, never token values |
| `integration_refresh_access_token` | User-lane host refresh plus materialized access token for `refreshAccessToken` |
| `integration_registry_search` / `integration_discover` | Untrusted integrations.sh research |
| `openapi_spec_summarize` / `openapi_client_scaffold` | Spec research helpers (bindings live in the `openapi` domain) |

OpenAPI provider bindings (`user_openapi_bindings` /
`user_openapi_binding_operations`) are a separate primitive; see
[OpenAPI provider bindings](./openapi-bindings.md).
| Capability | Role |
| ------------------------------------------------- | --------------------------------------------------------------------------------- |
| `integration_save` / `_get` / `_list` / `_delete` | Connection CRUD with flat `clientId` output |
| `integration_lock` | Tighten-only usage lock: packages mode + add a package id; unlock is website-only |
| `integration_oauth_app_list` | Apps with connection counts and sibling connection names |
| `integration_oauth_app_delete` | Delete a user-lane app and every connection on it |
| `integration_oauth_app_rotate_credentials` | Rotate shared app `clientId` / client-secret name |
| `integration_platform_app_list` | Always empty while platform apps are retired; operators use admin list |
| `integration_token_refresh` | Host-side OAuth refresh; returns metadata only, never token values |

## Account deletion order

Deletion targets in `account-data-targets.ts` list `user_integrations` before
`user_oauth_apps` so the `ON DELETE RESTRICT` FK cannot block cleanup when
cascades are disabled. `platform_oauth_apps` is global operator config and is
not a deletion target; removing a user's connections is what releases their
`ON DELETE RESTRICT` references to it. OpenAPI binding cleanup (child operations
before parent bindings) is documented in
[OpenAPI provider bindings](./openapi-bindings.md#account-deletion-order).
`ON DELETE RESTRICT` references to it.

## Related docs

Expand Down
2 changes: 0 additions & 2 deletions docs/contributing/architecture/mcp-client-servers.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,4 @@ fetch `{canonical-app-origin}/oauth/client-metadata.json`; that document's

## Related docs

- [OpenAPI provider bindings](./openapi-bindings.md) — curated HTTP provider
counterpart with the same naming pattern (`kody.openapi[...]`).
- [Data storage](./data-storage.md) — D1 vs Durable Object storage split.
74 changes: 0 additions & 74 deletions docs/contributing/architecture/openapi-bindings.md

This file was deleted.

14 changes: 1 addition & 13 deletions docs/contributing/architecture/primitives.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -393,18 +393,6 @@ primitives:
docs:
- docs/contributing/architecture/mcp-client-servers.md

- id: openapi-bindings
group: assistant
name: OpenAPI provider bindings
summary: Curated OpenAPI bindings with synthesized openapi domains.
code:
- packages/worker/src/openapi/
- packages/worker/src/mcp/capabilities/openapi/
- packages/worker/src/mcp/capabilities/openapi-provider/
docs:
- docs/contributing/architecture/openapi-bindings.md
- docs/guides/openapi-integrations.md

- id: realtime-sessions
group: assistant
name: Realtime sessions
Expand Down Expand Up @@ -693,7 +681,7 @@ invariants:
- docs/contributing/decisions/0023-progressive-search-disclosure.md

- id: package-over-synthesized-provider
summary: Rank wrapping packages before matching synthesized provider ops.
summary: Rank wrapping packages before matching synthesized MCP provider ops.
docs:
- docs/use/search.md
- docs/contributing/decisions/0024-packages-outrank-synthesized-providers.md
Expand Down
4 changes: 1 addition & 3 deletions docs/contributing/architecture/request-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,9 +314,7 @@ The MCP server flow adds one more Durable Object:
sockets.

The runtime capability registry **merges** synthesized domains from enabled
**MCP client servers** and user **OpenAPI provider bindings**. See
[MCP client servers](./mcp-client-servers.md), and
[OpenAPI provider bindings](./openapi-bindings.md).
**MCP client servers**. See [MCP client servers](./mcp-client-servers.md).

Shared options are built in `packages/worker/src/sentry-options.ts`: **release**
comes from `APP_COMMIT_SHA` when set (deploy workflows pass it as a var), and
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 0024: Packages outrank synthesized providers

- **Status:** accepted
- **Status:** accepted (MCP servers only; OpenAPI synthesis removed)
- **Date:** 2026-08-19

## Context
Expand Down
11 changes: 3 additions & 8 deletions docs/contributing/packages-and-manifests.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,12 +167,8 @@ A saved package is a repo with the package extension activated. Four concepts:
package before importing it (decision 0036).
- The author-facing storage prescription is one rule per context: saved-package
code always uses `packageStorage()` for the package's own data; ad hoc execute
code binds a `storageId` and uses ambient `storage`; another package's data
goes through a static import or `import(specifier)`. Package-invocation runs
(exports, subscription handlers, retrievers) bind no ambient `storage`, so
guard-less ambient access in those contexts fails with the structured
`runtime_helper_unbound` hint pointing at `packageStorage()`. Job runtimes
bind job-scoped scratch buckets. Repo checks fail (the `lint` result) when
has no scratch SQLite helper; another package's data goes through a static
import or `import(specifier)`. Repo checks fail (the `lint` result) when
package sources import ambient `storage` from `kody:runtime` with a value
named import; type-only imports and `.d.ts` files are exempt. The rule runs on
new session check runs, publishes, and community fork installs —
Expand Down Expand Up @@ -312,8 +308,7 @@ emit (recursion guard). See

For reconnectable OAuth refresh failures, `integration.auth.failed` dispatches
best-effort from host-side `refreshIntegrationTokens`
(`createAuthenticatedFetch` 401 retry, `refreshAccessToken` /
`integration_refresh_access_token`, and explicit `integration_token_refresh`).
(`createAuthenticatedFetch` 401 retry and explicit `integration_token_refresh`).
Successful refreshes and successful `/connect/oauth` token persists dispatch
`integration.auth.succeeded`. Both payloads are metadata-first (connection name,
account label, scopes, timestamps, and for failed: reason, optional provider
Expand Down
4 changes: 0 additions & 4 deletions docs/contributing/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -497,10 +497,6 @@ change to these decisions here so future agents do not relitigate them.
- **Account secret reveal is owner-scoped, not password-reauthenticated.** See
the "Account secret reveal" section of
[`architecture/authentication.md`](./architecture/authentication.md).
- **`refreshAccessToken` materializes plaintext OAuth tokens** inside user code
for integration calls. Prefer `createAuthenticatedFetch`, which enforces the
integration host allowlist. This is documented at the call site
(`packages/worker/src/mcp/execute-modules/kody-runtime-utils.ts`).
- **Sandbox `fetch` has no general SSRF denylist.** Secret-bearing requests are
constrained by per-secret host allowlists; non-secret requests rely on the
Cloudflare Workers platform egress model.
Expand Down
Loading
Loading