diff --git a/docs/use/execute.md b/docs/use/execute.md index c252d0ca52..960c0c151c 100644 --- a/docs/use/execute.md +++ b/docs/use/execute.md @@ -23,8 +23,11 @@ helpers are runtime exports: valid identifier names, or **`await codemode["capability-id"](input)`** for non-identifier capability ids - use - **`import { refreshAccessToken, createAuthenticatedFetch } from 'kody:runtime'`** - for integration OAuth helpers + **`import { refreshAccessToken, createAuthenticatedFetch, oauthClientCredentials } from 'kody:runtime'`** + for OAuth helpers +- use **`import { secretHeaders } from 'kody:runtime'`** when an approved + `fetch` request needs host-derived auth headers from saved secrets, such as + Basic Auth from a saved client id and client secret - use **`import { storage } from 'kody:runtime'`** when the execute call is bound to a storage id - use **`import { workflows } from 'kody:runtime'`** to queue Cloudflare @@ -230,9 +233,9 @@ reconnect the MCP client if the host caches server instructions. ## Network and OAuth helpers The sandbox exposes global **`fetch`** plus secret placeholders in approved -contexts. OAuth helpers are imported from **`kody:runtime`**: +contexts. OAuth and secret-header helpers are imported from **`kody:runtime`**: -**`import { refreshAccessToken, createAuthenticatedFetch } from 'kody:runtime'`** +**`import { refreshAccessToken, createAuthenticatedFetch, oauthClientCredentials, secretHeaders } from 'kody:runtime'`** `createAuthenticatedFetch(providerName)` is async. Await it before calling the returned fetch wrapper: @@ -247,6 +250,55 @@ accounts may exist, such as `google`, `google-business`, or `google-youtube-brand`. Call **`integration_list`** up front when a provider may have multiple accounts connected. +For OAuth 2 `client_credentials` token exchanges that require +`Authorization: Basic base64(client_id:client_secret)`, save the client id and +client secret separately. Do **not** ask the user to precompute or save the +derived Basic header. Use `secretHeaders.basic(...)` directly in a fetch header, +or use `oauthClientCredentials(...)` for the token request: + +```ts +import { oauthClientCredentials } from 'kody:runtime' + +export default async function main() { + const token = await oauthClientCredentials({ + tokenUrl: 'https://api-m.paypal.com/v1/oauth2/token', + clientIdSecret: 'paypalClientId', + clientSecretSecret: 'paypalClientSecret', + scope: 'user', + }) + + return { tokenType: token.token_type, hasAccessToken: !!token.access_token } +} +``` + +The lower-level PayPal token request is: + +```ts +import { secretHeaders } from 'kody:runtime' + +export default async function main() { + const body = new URLSearchParams({ grant_type: 'client_credentials' }) + const response = await fetch('https://api-m.paypal.com/v1/oauth2/token', { + method: 'POST', + headers: { + Accept: 'application/json', + 'Content-Type': 'application/x-www-form-urlencoded', + Authorization: secretHeaders.basic({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }), + }, + body, + }) + return await response.json() +} +``` + +Kody resolves both saved secrets server-side, requires the token endpoint host +to be approved for both secrets, and only sends the derived Basic header in the +outbound request. + See [Secrets, values, and host approval](./secrets-and-values.md) for placeholders, host approval, and **`codemode.secret_list`** / **`secret_set`**. diff --git a/docs/use/secrets-and-values.md b/docs/use/secrets-and-values.md index a99c777e3c..d1e2475cc3 100644 --- a/docs/use/secrets-and-values.md +++ b/docs/use/secrets-and-values.md @@ -23,6 +23,31 @@ Outbound **`fetch`** can include placeholders such as **`{{secret:tokenName}}`** or **`{{secret:tokenName|scope=user}}`** in the URL, headers, or body. The host resolves them for **approved** destinations. +When an API requires Basic Auth derived from two saved secrets, import +**`secretHeaders`** from **`kody:runtime`** and put the opaque helper result in +the outbound fetch header: + +```ts +import { secretHeaders } from 'kody:runtime' + +await fetch('https://api-m.paypal.com/v1/oauth2/token', { + method: 'POST', + headers: { + Authorization: secretHeaders.basic({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }), + 'Content-Type': 'application/x-www-form-urlencoded', + }, + body: new URLSearchParams({ grant_type: 'client_credentials' }), +}) +``` + +Kody resolves both secrets and sends only the derived `Basic ...` header to the +approved host. The target host must be approved separately for both saved +secrets. + Some capability fields opt in with **`x-kody-secret: true`**; those accept the same placeholder form instead of raw credentials. diff --git a/packages/worker/src/mcp/execute-modules/codemode-utils.node.test.ts b/packages/worker/src/mcp/execute-modules/codemode-utils.node.test.ts index cacd629c58..fb1a03b8f2 100644 --- a/packages/worker/src/mcp/execute-modules/codemode-utils.node.test.ts +++ b/packages/worker/src/mcp/execute-modules/codemode-utils.node.test.ts @@ -6,7 +6,9 @@ import { createAuthenticatedFetch, createExecuteHelperPrelude, getExecuteHelperCapabilityNames, + oauthClientCredentials, refreshAccessToken, + secretHeaders, } from './codemode-utils.ts' type SecretSetCall = { @@ -22,6 +24,8 @@ type SandboxHelpers = { ) => Promise< (input: ExecuteRequestInput, init?: RequestInit) => Promise > + secretHeaders: typeof secretHeaders + oauthClientCredentials: typeof oauthClientCredentials } const spotifyIntegration = { @@ -200,6 +204,112 @@ test('createExecuteHelperPrelude persists rotated refresh token and access token ) }) +test('secretHeaders.basic returns an opaque Basic Auth placeholder', () => { + expect( + secretHeaders.basic({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }), + ).toBe( + '{{secret-basic:username=paypalClientId,password=paypalClientSecret|scope=user}}', + ) +}) + +test('oauthClientCredentials posts a Basic placeholder through fetch', async () => { + const fetchCalls: Array = [] + const fetchStub: typeof globalThis.fetch = async ( + input: ExecuteRequestInput, + init?: RequestInit, + ) => { + const request = new Request(input, init) + fetchCalls.push(request) + return new Response( + JSON.stringify({ + access_token: 'paypal-access-token', + token_type: 'Bearer', + }), + { + status: 200, + headers: { 'content-type': 'application/json' }, + }, + ) + } + + const tokenResponse = await withPatchedFetch(fetchStub, () => + oauthClientCredentials({ + tokenUrl: 'https://api-m.paypal.com/v1/oauth2/token', + clientIdSecret: 'paypalClientId', + clientSecretSecret: 'paypalClientSecret', + scope: 'user', + body: { + scope: 'openid', + }, + }), + ) + + expect(tokenResponse).toEqual({ + access_token: 'paypal-access-token', + token_type: 'Bearer', + }) + expect(fetchCalls).toHaveLength(1) + expect(fetchCalls[0]?.method).toBe('POST') + expect(fetchCalls[0]?.headers.get('authorization')).toBe( + '{{secret-basic:username=paypalClientId,password=paypalClientSecret|scope=user}}', + ) + expect(fetchCalls[0]?.headers.get('content-type')).toBe( + 'application/x-www-form-urlencoded', + ) + expect(await fetchCalls[0]?.text()).toBe( + new URLSearchParams({ + scope: 'openid', + grant_type: 'client_credentials', + }).toString(), + ) +}) + +test('createExecuteHelperPrelude exposes secret and client credentials helpers', async () => { + const prelude = createExecuteHelperPrelude() + const createSandboxHelpers = new Function( + 'codemode', + `${prelude}; return { secretHeaders, oauthClientCredentials };`, + ) as (codemodeNamespace: CodemodeNamespace) => SandboxHelpers + const fetchCalls: Array = [] + const fetchStub: typeof globalThis.fetch = async ( + input: ExecuteRequestInput, + init?: RequestInit, + ) => { + const request = new Request(input, init) + fetchCalls.push(request) + return new Response(JSON.stringify({ access_token: 'access-token' }), { + status: 200, + headers: { 'content-type': 'application/json' }, + }) + } + + const helpers = createSandboxHelpers({} satisfies CodemodeNamespace) + expect( + helpers.secretHeaders.basic({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }), + ).toBe( + '{{secret-basic:username=paypalClientId,password=paypalClientSecret|scope=user}}', + ) + await withPatchedFetch(fetchStub, () => + helpers.oauthClientCredentials({ + tokenUrl: 'https://api-m.paypal.com/v1/oauth2/token', + clientIdSecret: 'paypalClientId', + clientSecretSecret: 'paypalClientSecret', + scope: 'user', + }), + ) + expect(fetchCalls[0]?.headers.get('authorization')).toBe( + '{{secret-basic:username=paypalClientId,password=paypalClientSecret|scope=user}}', + ) +}) + test('getExecuteHelperCapabilityNames includes secret_set for refresh persistence', () => { expect(getExecuteHelperCapabilityNames()).toEqual([ 'integration_get', diff --git a/packages/worker/src/mcp/execute-modules/codemode-utils.ts b/packages/worker/src/mcp/execute-modules/codemode-utils.ts index 0d5a727cef..686f4cedd0 100644 --- a/packages/worker/src/mcp/execute-modules/codemode-utils.ts +++ b/packages/worker/src/mcp/execute-modules/codemode-utils.ts @@ -6,6 +6,7 @@ import { export { IntegrationHostNotAllowedError } type CapabilityResult = unknown +type SecretScope = 'session' | 'app' | 'user' export type CapabilityArgs = Record @@ -43,6 +44,38 @@ type ValueGetResult = { export type ExecuteRequestInput = string | URL | Request +export type BasicAuthSecretHeaderInput = { + usernameSecret: string + passwordSecret: string + scope?: SecretScope | null +} + +export type OAuthClientCredentialsInput = { + tokenUrl: string | URL + clientIdSecret: string + clientSecretSecret: string + scope?: SecretScope | null + authStyle?: 'basic' + body?: Record + headers?: Record +} + +export const secretHeaders = { + basic(input: BasicAuthSecretHeaderInput) { + return buildBasicAuthSecretPlaceholder({ + usernameSecret: normalizeSecretName( + input.usernameSecret, + 'usernameSecret', + ), + passwordSecret: normalizeSecretName( + input.passwordSecret, + 'passwordSecret', + ), + scope: normalizeOptionalSecretScope(input.scope), + }) + }, +} + export const EXECUTE_HELPER_CAPABILITY_NAMES = [ 'integration_get', 'value_get', @@ -97,6 +130,47 @@ export async function createAuthenticatedFetch( } } +export async function oauthClientCredentials( + input: OAuthClientCredentialsInput, +): Promise> { + const authStyle = (input.authStyle ?? 'basic') as string + if (authStyle !== 'basic') { + throw new Error( + `Unsupported OAuth client_credentials authStyle "${authStyle}".`, + ) + } + const body = new URLSearchParams(input.body ?? {}) + body.set('grant_type', 'client_credentials') + const headers = new Headers(input.headers) + if (!headers.has('Accept')) { + headers.set('Accept', 'application/json') + } + headers.set('Content-Type', 'application/x-www-form-urlencoded') + headers.set( + 'Authorization', + secretHeaders.basic({ + usernameSecret: input.clientIdSecret, + passwordSecret: input.clientSecretSecret, + scope: input.scope, + }), + ) + const response = await fetch(input.tokenUrl, { + method: 'POST', + headers, + body: body.toString(), + }) + const payload = (await response.json().catch(() => null)) as unknown + if (!response.ok) { + throw new Error( + `OAuth client_credentials request failed with HTTP ${response.status}.`, + ) + } + if (!payload || typeof payload !== 'object' || Array.isArray(payload)) { + throw new Error('OAuth client_credentials response was not a JSON object.') + } + return payload as Record +} + async function readIntegrationConfig( codemode: CodemodeNamespace, providerName: string, @@ -250,6 +324,32 @@ function buildSecretPlaceholder( return `{{secret:${name}|scope=${scope}}}` } +function buildBasicAuthSecretPlaceholder(input: { + usernameSecret: string + passwordSecret: string + scope?: SecretScope | null +}) { + return input.scope + ? `{{secret-basic:username=${input.usernameSecret},password=${input.passwordSecret}|scope=${input.scope}}}` + : `{{secret-basic:username=${input.usernameSecret},password=${input.passwordSecret}}}` +} + +function normalizeSecretName(value: string, fieldName: string) { + const normalized = value.trim() + if (!/^[a-zA-Z0-9._-]+$/.test(normalized)) { + throw new Error( + `${fieldName} must be a saved secret name using letters, numbers, dots, underscores, or hyphens.`, + ) + } + return normalized +} + +function normalizeOptionalSecretScope(scope: SecretScope | null | undefined) { + if (scope == null) return null + if (scope === 'app' || scope === 'session' || scope === 'user') return scope + throw new Error(`Unsupported secret scope "${scope}".`) +} + function resolveRequestUrl( input: ExecuteRequestInput, integration: IntegrationConfig, @@ -381,6 +481,33 @@ const __kodyAssertIntegrationHostAllowed = (integrationName, integration, url) = }; const __kodyBuildSecretPlaceholder = (name, scope) => \`{{secret:\${name}|scope=\${scope}}}\`; +const __kodyNormalizeSecretName = (value, fieldName) => { + const normalized = String(value ?? '').trim(); + if (!/^[a-zA-Z0-9._-]+$/.test(normalized)) { + throw new Error( + \`\${fieldName} must be a saved secret name using letters, numbers, dots, underscores, or hyphens.\`, + ); + } + return normalized; +}; +const __kodyNormalizeOptionalSecretScope = (scope) => { + if (scope == null) return null; + if (scope === 'app' || scope === 'session' || scope === 'user') return scope; + throw new Error(\`Unsupported secret scope "\${scope}".\`); +}; +const __kodyBuildBasicAuthSecretPlaceholder = (input) => { + const usernameSecret = __kodyNormalizeSecretName(input.usernameSecret, 'usernameSecret'); + const passwordSecret = __kodyNormalizeSecretName(input.passwordSecret, 'passwordSecret'); + const scope = __kodyNormalizeOptionalSecretScope(input.scope); + return scope + ? \`{{secret-basic:username=\${usernameSecret},password=\${passwordSecret}|scope=\${scope}}}\` + : \`{{secret-basic:username=\${usernameSecret},password=\${passwordSecret}}}\`; +}; +const secretHeaders = { + basic(input) { + return __kodyBuildBasicAuthSecretPlaceholder(input); + }, +}; const __kodyReadIntegrationConfig = async (providerName) => { const integrationGet = codemode.integration_get; if (typeof integrationGet !== 'function') { @@ -552,9 +679,47 @@ const __kodyCreateAuthenticatedFetch = async (providerName) => { ); }; }; +const __kodyOauthClientCredentials = async (input) => { + const authStyle = input.authStyle ?? 'basic'; + if (authStyle !== 'basic') { + throw new Error(\`Unsupported OAuth client_credentials authStyle "\${authStyle}".\`); + } + const body = new URLSearchParams(input.body ?? {}); + body.set('grant_type', 'client_credentials'); + const headers = new Headers(input.headers); + if (!headers.has('Accept')) { + headers.set('Accept', 'application/json'); + } + headers.set('Content-Type', 'application/x-www-form-urlencoded'); + headers.set( + 'Authorization', + secretHeaders.basic({ + usernameSecret: input.clientIdSecret, + passwordSecret: input.clientSecretSecret, + scope: input.scope, + }), + ); + const response = await fetch(input.tokenUrl, { + method: 'POST', + headers, + body: body.toString(), + }); + const payload = await response.json().catch(() => null); + if (!response.ok) { + throw new Error( + \`OAuth client_credentials request failed with HTTP \${response.status}.\`, + ); + } + if (!payload || typeof payload !== 'object' || Array.isArray(payload)) { + throw new Error('OAuth client_credentials response was not a JSON object.'); + } + return payload; +}; const refreshAccessToken = async (providerName) => __kodyRefreshAccessToken(providerName); const createAuthenticatedFetch = async (providerName) => __kodyCreateAuthenticatedFetch(providerName); +const oauthClientCredentials = async (input) => + __kodyOauthClientCredentials(input); `.trim() } diff --git a/packages/worker/src/mcp/fetch-gateway.node.test.ts b/packages/worker/src/mcp/fetch-gateway.node.test.ts index b94694b61d..55f9deaddd 100644 --- a/packages/worker/src/mcp/fetch-gateway.node.test.ts +++ b/packages/worker/src/mcp/fetch-gateway.node.test.ts @@ -1,6 +1,10 @@ import { expect, test, vi } from 'vitest' import { expandSecretPlaceholders } from '#mcp/fetch-gateway.ts' import { parseHostApprovalRequiredBatchMessage } from '#mcp/secrets/errors.ts' +import { + buildBasicAuthSecretPlaceholder, + parseBasicAuthSecretPlaceholders, +} from '#mcp/secrets/placeholders.ts' import * as secretService from '#mcp/secrets/service.ts' const env = { @@ -131,6 +135,219 @@ test('fetch gateway expands placeholders in form-urlencoded bodies', async () => } }) +test('fetch gateway parses derived Basic Auth secret placeholders', () => { + const placeholder = buildBasicAuthSecretPlaceholder({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }) + + expect(parseBasicAuthSecretPlaceholders(`Basic ${placeholder}`)).toEqual([ + { + username: { name: 'paypalClientId', scope: 'user' }, + password: { name: 'paypalClientSecret', scope: 'user' }, + scope: 'user', + }, + ]) +}) + +test('fetch gateway derives Basic Auth header after approving both secrets', async () => { + const resolveSpy = vi + .spyOn(secretService, 'resolveSecret') + .mockImplementation(async ({ name }) => { + const values: Record = { + paypalClientId: 'client-id', + paypalClientSecret: 'client-secret', + } + return { + found: name in values, + value: values[name] ?? null, + scope: name in values ? 'user' : null, + allowedHosts: name in values ? ['api-m.paypal.com'] : [], + allowedCapabilities: [], + } + }) + const placeholder = buildBasicAuthSecretPlaceholder({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }) + const request = new Request('https://api-m.paypal.com/v1/oauth2/token', { + method: 'POST', + headers: { + Authorization: placeholder, + 'Content-Type': 'application/x-www-form-urlencoded', + }, + body: new URLSearchParams({ + grant_type: 'client_credentials', + }).toString(), + }) + + try { + const transformed = await expandSecretPlaceholders({ + request, + props, + env, + }) + + expect(transformed.headers.get('Authorization')).toBe( + `Basic ${btoa('client-id:client-secret')}`, + ) + expect(await transformed.text()).toBe('grant_type=client_credentials') + expect(resolveSpy).toHaveBeenCalledWith( + expect.objectContaining({ + name: 'paypalClientId', + scope: 'user', + }), + ) + expect(resolveSpy).toHaveBeenCalledWith( + expect.objectContaining({ + name: 'paypalClientSecret', + scope: 'user', + }), + ) + } finally { + resolveSpy.mockRestore() + } +}) + +test.each(['Basic', 'basic', 'BASIC'])( + 'fetch gateway accepts a pre-prefixed derived Basic Auth placeholder with %s scheme', + async (scheme) => { + const resolveSpy = vi + .spyOn(secretService, 'resolveSecret') + .mockImplementation(async ({ name }) => { + const values: Record = { + paypalClientId: 'client-id', + paypalClientSecret: 'client-secret', + } + return { + found: name in values, + value: values[name] ?? null, + scope: name in values ? 'user' : null, + allowedHosts: name in values ? ['api-m.paypal.com'] : [], + allowedCapabilities: [], + } + }) + const request = new Request('https://api-m.paypal.com/v1/oauth2/token', { + headers: { + Authorization: `${scheme} ${buildBasicAuthSecretPlaceholder({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + })}`, + }, + }) + + try { + const transformed = await expandSecretPlaceholders({ + request, + props, + env, + }) + + expect(transformed.headers.get('Authorization')).toBe( + `Basic ${btoa('client-id:client-secret')}`, + ) + } finally { + resolveSpy.mockRestore() + } + }, +) + +test('fetch gateway reports missing secret for derived Basic Auth placeholders', async () => { + const resolveSpy = vi + .spyOn(secretService, 'resolveSecret') + .mockImplementation(async ({ name }) => ({ + found: name === 'paypalClientId', + value: name === 'paypalClientId' ? 'client-id' : null, + scope: name === 'paypalClientId' ? 'user' : null, + allowedHosts: name === 'paypalClientId' ? ['api-m.paypal.com'] : [], + allowedCapabilities: [], + })) + const request = new Request('https://api-m.paypal.com/v1/oauth2/token', { + headers: { + Authorization: buildBasicAuthSecretPlaceholder({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }), + }, + }) + + try { + await expect( + expandSecretPlaceholders({ request, props, env }), + ).rejects.toThrow('Secret "paypalClientSecret" was not found.') + } finally { + resolveSpy.mockRestore() + } +}) + +test.each([ + { + blockedSecretName: 'paypalClientId', + allowedHosts: { + paypalClientId: [], + paypalClientSecret: ['api-m.paypal.com'], + }, + }, + { + blockedSecretName: 'paypalClientSecret', + allowedHosts: { + paypalClientId: ['api-m.paypal.com'], + paypalClientSecret: [], + }, + }, +])( + 'fetch gateway requires host approval for derived Basic Auth $blockedSecretName', + async ({ blockedSecretName, allowedHosts }) => { + const resolveSpy = vi + .spyOn(secretService, 'resolveSecret') + .mockImplementation(async ({ name }) => { + const values: Record = { + paypalClientId: 'client-id', + paypalClientSecret: 'client-secret', + } + return { + found: name in values, + value: values[name] ?? null, + scope: name in values ? 'user' : null, + allowedHosts: allowedHosts[name as keyof typeof allowedHosts] ?? [], + allowedCapabilities: [], + } + }) + const request = new Request('https://api-m.paypal.com/v1/oauth2/token', { + headers: { + Authorization: buildBasicAuthSecretPlaceholder({ + usernameSecret: 'paypalClientId', + passwordSecret: 'paypalClientSecret', + scope: 'user', + }), + }, + }) + + try { + await expandSecretPlaceholders({ request, props, env }) + throw new Error('Expected host approval error.') + } catch (error) { + const message = error instanceof Error ? error.message : String(error) + const approvals = parseHostApprovalRequiredBatchMessage(message) + expect(approvals).toEqual([ + expect.objectContaining({ + secretName: blockedSecretName, + host: 'api-m.paypal.com', + approvalUrl: expect.stringContaining( + `/account/secrets/user/${blockedSecretName}?allowed-host=api-m.paypal.com`, + ), + }), + ]) + } finally { + resolveSpy.mockRestore() + } + }, +) + test('fetch gateway resolves path-only URLs against baseUrl', async () => { // Node's Request rejects path-only URLs; workerd allows them for codemode outbound fetch. const request = { diff --git a/packages/worker/src/mcp/fetch-gateway.ts b/packages/worker/src/mcp/fetch-gateway.ts index 09deb857b0..21210a5030 100644 --- a/packages/worker/src/mcp/fetch-gateway.ts +++ b/packages/worker/src/mcp/fetch-gateway.ts @@ -1,11 +1,15 @@ import { WorkerEntrypoint } from 'cloudflare:workers' import { buildSecretHostApprovalUrl } from '#mcp/secrets/host-approval.ts' import { + buildBasicAuthSecretPlaceholderFromReference, buildSecretPlaceholder, + parseBasicAuthSecretPlaceholders, + parseBasicAuthSecretPlaceholdersFromFormUrlEncoded, parseSecretPlaceholders, parseSecretPlaceholdersFromFormUrlEncoded, replaceSecretPlaceholders, replaceSecretPlaceholdersInFormUrlEncoded, + type ReferencedBasicAuthSecretPlaceholder, type ReferencedSecret, } from '#mcp/secrets/placeholders.ts' import { @@ -50,16 +54,31 @@ export async function expandSecretPlaceholders(input: { resolved: ResolvedSecret }> = [] const replacements = new Map() + const resolvedValues = new Map() const baseUrl = input.props.baseUrl.trim() if (!baseUrl) { throw new Error('Fetch gateway requires a non-empty baseUrl in props.') } + const basicAuthPlaceholders = dedupeBasicAuthSecretPlaceholders([ + ...collectReferencedBasicAuthSecretPlaceholders([ + input.request.url, + ...Array.from(headers.values()), + ]), + ...collectReferencedBasicAuthSecretPlaceholdersFromRequestBody( + headers, + requestBody, + ), + ]) const referencedSecrets = dedupeReferencedSecrets([ ...collectReferencedSecrets([ input.request.url, ...Array.from(headers.values()), ]), ...collectReferencedSecretsFromRequestBody(headers, requestBody), + ...basicAuthPlaceholders.flatMap((placeholder) => [ + placeholder.username, + placeholder.password, + ]), ]) const hasReferencedSecrets = referencedSecrets.length > 0 if (hasReferencedSecrets) { @@ -80,8 +99,28 @@ export async function expandSecretPlaceholders(input: { if (!replacements.has(placeholder)) { replacements.set(placeholder, resolved.value) } + if (!resolvedValues.has(placeholder)) { + resolvedValues.set(placeholder, resolved.value) + } resolvedSecrets.push({ referenced, resolved }) } + for (const placeholder of basicAuthPlaceholders) { + const renderedPlaceholder = + buildBasicAuthSecretPlaceholderFromReference(placeholder) + const authHeader = buildBasicAuthHeader({ + username: readResolvedSecretValue(resolvedValues, placeholder.username), + password: readResolvedSecretValue(resolvedValues, placeholder.password), + }) + for (const scheme of ['Basic', 'basic', 'BASIC']) { + const prefixedPlaceholder = `${scheme} ${renderedPlaceholder}` + if (!replacements.has(prefixedPlaceholder)) { + replacements.set(prefixedPlaceholder, authHeader) + } + } + if (!replacements.has(renderedPlaceholder)) { + replacements.set(renderedPlaceholder, authHeader) + } + } let requestedHost = '' if (hasReferencedSecrets) { const nextUrl = resolveRequestUrlForFetchGateway( @@ -216,6 +255,28 @@ function collectReferencedSecrets(values: Array) { ) } +function collectReferencedBasicAuthSecretPlaceholders( + values: Array, +) { + return dedupeBasicAuthSecretPlaceholders( + values.flatMap((value) => + value ? parseBasicAuthSecretPlaceholders(value) : [], + ), + ) +} + +function collectReferencedBasicAuthSecretPlaceholdersFromRequestBody( + headers: Headers, + requestBody: string | null, +) { + if (!requestBody) return [] + return isFormUrlEncodedRequest(headers) + ? dedupeBasicAuthSecretPlaceholders( + parseBasicAuthSecretPlaceholdersFromFormUrlEncoded(requestBody), + ) + : collectReferencedBasicAuthSecretPlaceholders([requestBody]) +} + function collectReferencedSecretsFromRequestBody( headers: Headers, requestBody: string | null, @@ -236,6 +297,19 @@ function dedupeReferencedSecrets(referencedSecrets: Array) { return Array.from(deduped.values()) } +function dedupeBasicAuthSecretPlaceholders( + placeholders: Array, +) { + const deduped = new Map() + for (const placeholder of placeholders) { + deduped.set( + buildBasicAuthSecretPlaceholderFromReference(placeholder), + placeholder, + ) + } + return Array.from(deduped.values()) +} + function replaceSecretPlaceholdersInRequestBody( headers: Headers, requestBody: string, @@ -259,3 +333,30 @@ async function readRequestBody(request: Request) { function shouldSendBody(method: string) { return method !== 'GET' && method !== 'HEAD' } + +function readResolvedSecretValue( + resolvedValues: ReadonlyMap, + referenced: ReferencedSecret, +) { + const placeholder = buildSecretPlaceholder(referenced) + const value = resolvedValues.get(placeholder) + if (value == null) { + throw new Error(createMissingSecretMessage(referenced.name)) + } + return value +} + +function buildBasicAuthHeader(input: { username: string; password: string }) { + return `Basic ${encodeBase64(`${input.username}:${input.password}`)}` +} + +function encodeBase64(value: string) { + const bytes = new TextEncoder().encode(value) + let binary = '' + const chunkSize = 0x8000 + for (let index = 0; index < bytes.length; index += chunkSize) { + const chunk = bytes.slice(index, index + chunkSize) + binary += String.fromCharCode(...chunk) + } + return btoa(binary) +} diff --git a/packages/worker/src/mcp/generated-ui-api.ts b/packages/worker/src/mcp/generated-ui-api.ts index 360ece7afd..bf0eec2a6e 100644 --- a/packages/worker/src/mcp/generated-ui-api.ts +++ b/packages/worker/src/mcp/generated-ui-api.ts @@ -14,6 +14,7 @@ import { } from '#mcp/generated-ui-app-session.ts' import { runCodemodeWithRegistry } from '#mcp/run-codemode-registry.ts' import { deleteSecret, listSecrets, saveSecret } from '#mcp/secrets/service.ts' +import { containsSecretPlaceholder } from '#mcp/secrets/placeholders.ts' import { secretScopeValues } from '#mcp/secrets/types.ts' const generatedUiAllowedScopes = ['session', 'app'] as const @@ -187,7 +188,7 @@ function createGeneratedUiExecuteHandler(env: Env) { { ok: false, error: - 'Generated UI executeCode may not return unresolved `{{secret:...}}` placeholders. Secret placeholders only resolve inside secret-aware fetch requests or capability inputs that explicitly opt into `x-kody-secret`. Use persisted values for non-secret configuration, and call `kodyWidget.sendMessage(...)` (for example after `import { kodyWidget } from "@kody/ui-utils"`) when the user needs to intervene.', + 'Generated UI executeCode may not return unresolved secret placeholders. Secret placeholders only resolve inside secret-aware fetch requests or capability inputs that explicitly opt into `x-kody-secret`. Use persisted values for non-secret configuration, and call `kodyWidget.sendMessage(...)` (for example after `import { kodyWidget } from "@kody/ui-utils"`) when the user needs to intervene.', logs: result.logs ?? [], }, 400, @@ -489,7 +490,7 @@ function jsonResponse(body: Record, status = 200) { function containsReturnedSecretPlaceholder(value: unknown): boolean { if (typeof value === 'string') { - return /\{\{secret:[a-zA-Z0-9._-]+/.test(value) + return containsSecretPlaceholder(value) } if (Array.isArray(value)) { return value.some((entry) => containsReturnedSecretPlaceholder(entry)) diff --git a/packages/worker/src/mcp/run-codemode-registry.ts b/packages/worker/src/mcp/run-codemode-registry.ts index 5dd00329bd..5edf426ddf 100644 --- a/packages/worker/src/mcp/run-codemode-registry.ts +++ b/packages/worker/src/mcp/run-codemode-registry.ts @@ -890,6 +890,8 @@ ${packagesHelperPrelude ? `${packagesHelperPrelude}\n` : ''} storage: typeof storage === 'undefined' ? undefined : storage, refreshAccessToken, createAuthenticatedFetch, + secretHeaders, + oauthClientCredentials, packageContext: ${JSON.stringify(options?.packageContext ?? null)}, serviceContext: ${JSON.stringify(options?.serviceContext ?? null)}, service: typeof service === 'undefined' ? null : service, diff --git a/packages/worker/src/mcp/secrets/placeholders.ts b/packages/worker/src/mcp/secrets/placeholders.ts index acda1100f8..5a3cdb7528 100644 --- a/packages/worker/src/mcp/secrets/placeholders.ts +++ b/packages/worker/src/mcp/secrets/placeholders.ts @@ -2,12 +2,20 @@ import { type SecretScope } from '#mcp/secrets/types.ts' const secretPlaceholderRegex = /\{\{secret:([a-zA-Z0-9._-]+)(?:\|scope=(session|app|user))?\}\}/g +const basicAuthSecretPlaceholderRegex = + /\{\{secret-basic:username=([a-zA-Z0-9._-]+),password=([a-zA-Z0-9._-]+)(?:\|scope=(session|app|user))?\}\}/g export type ReferencedSecret = { name: string scope: SecretScope | null } +export type ReferencedBasicAuthSecretPlaceholder = { + username: ReferencedSecret + password: ReferencedSecret + scope: SecretScope | null +} + export function parseSecretPlaceholders(value: string) { const secrets: Array = [] for (const match of value.matchAll(secretPlaceholderRegex)) { @@ -25,6 +33,28 @@ export function parseSecretPlaceholders(value: string) { return secrets } +export function parseBasicAuthSecretPlaceholders(value: string) { + const placeholders: Array = [] + for (const match of value.matchAll(basicAuthSecretPlaceholderRegex)) { + const usernameSecretName = match[1]?.trim() + const passwordSecretName = match[2]?.trim() + if (!usernameSecretName || !passwordSecretName) continue + const scope = parseSecretScope(match[3]) + placeholders.push({ + username: { + name: usernameSecretName, + scope, + }, + password: { + name: passwordSecretName, + scope, + }, + scope, + }) + } + return placeholders +} + export function parseSecretPlaceholdersFromFormUrlEncoded(value: string) { const secrets: Array = [] for (const [key, entryValue] of new URLSearchParams(value)) { @@ -34,12 +64,43 @@ export function parseSecretPlaceholdersFromFormUrlEncoded(value: string) { return secrets } +export function parseBasicAuthSecretPlaceholdersFromFormUrlEncoded( + value: string, +) { + const placeholders: Array = [] + for (const [key, entryValue] of new URLSearchParams(value)) { + placeholders.push(...parseBasicAuthSecretPlaceholders(key)) + placeholders.push(...parseBasicAuthSecretPlaceholders(entryValue)) + } + return placeholders +} + export function buildSecretPlaceholder(secret: ReferencedSecret) { return secret.scope ? `{{secret:${secret.name}|scope=${secret.scope}}}` : `{{secret:${secret.name}}}` } +export function buildBasicAuthSecretPlaceholder(input: { + usernameSecret: string + passwordSecret: string + scope?: SecretScope | null +}) { + return input.scope + ? `{{secret-basic:username=${input.usernameSecret},password=${input.passwordSecret}|scope=${input.scope}}}` + : `{{secret-basic:username=${input.usernameSecret},password=${input.passwordSecret}}}` +} + +export function buildBasicAuthSecretPlaceholderFromReference( + placeholder: ReferencedBasicAuthSecretPlaceholder, +) { + return buildBasicAuthSecretPlaceholder({ + usernameSecret: placeholder.username.name, + passwordSecret: placeholder.password.name, + scope: placeholder.scope, + }) +} + export function replaceSecretPlaceholders( value: string, replacements: ReadonlyMap, @@ -64,3 +125,13 @@ export function replaceSecretPlaceholdersInFormUrlEncoded( } return nextParams.toString() } + +export function containsSecretPlaceholder(value: string) { + return /\{\{secret(?::|-basic:)/.test(value) +} + +function parseSecretScope(scope: string | undefined) { + return scope === 'app' || scope === 'session' || scope === 'user' + ? scope + : null +} diff --git a/packages/worker/src/mcp/server-instructions.ts b/packages/worker/src/mcp/server-instructions.ts index 5f99964c8e..b19afd1d54 100644 --- a/packages/worker/src/mcp/server-instructions.ts +++ b/packages/worker/src/mcp/server-instructions.ts @@ -90,7 +90,7 @@ search - search({ entity: 'kody_official_guide:capability' }) execute -- Single ESM module string with a default export such as \`export default async function main(input = {}) { ... }\`; \`params\` are passed as the first argument. Import runtime APIs from \`kody:runtime\`. Example: \`import { codemode, refreshAccessToken, createAuthenticatedFetch, workflows } from 'kody:runtime'\`. Built-in capabilities returned by \`search\` are available through \`codemode\`: use \`await codemode.capability_id(input)\` for valid identifier names or \`await codemode["capability-id"](input)\` for non-identifier ids. \`workflows.create\` can queue either inline \`code\` or a saved-package \`exportName\` through the shared Workflow hub. Prefer one \`execute\` when the plan is clear. Full rules for \`fetch\`, placeholders, \`secret_list\` / \`value_get\`, and \`x-kody-secret\`: see the \`execute\` tool description. +- Single ESM module string with a default export such as \`export default async function main(input = {}) { ... }\`; \`params\` are passed as the first argument. Import runtime APIs from \`kody:runtime\`. Example: \`import { codemode, refreshAccessToken, createAuthenticatedFetch, oauthClientCredentials, secretHeaders, workflows } from 'kody:runtime'\`. Built-in capabilities returned by \`search\` are available through \`codemode\`: use \`await codemode.capability_id(input)\` for valid identifier names or \`await codemode["capability-id"](input)\` for non-identifier ids. \`workflows.create\` can queue either inline \`code\` or a saved-package \`exportName\` through the shared Workflow hub. Use \`secretHeaders.basic(...)\` or \`oauthClientCredentials(...)\` for client-credentials Basic Auth instead of asking users to precompute a Basic header. Prefer one \`execute\` when the plan is clear. Full rules for \`fetch\`, placeholders, \`secret_list\` / \`value_get\`, and \`x-kody-secret\`: see the \`execute\` tool description. - Cross-package imports use specifiers such as \`kody:@scope/my-package/export-name\`. For dynamic current-version calls inside package runtime code, prefer \`packages.invokeChecked({ kodyId, exportName, params })\` or \`packages.check(...)\` followed by \`packages.invoke(check.invoke)\`; use static imports for library-like bundled snapshots. Saved package names must be scoped (\`@scope/\`) and the leaf segment must match \`kody.id\`. Package jobs are owned by packages, ad hoc jobs can be scheduled with \`job_schedule\`, and package apps are optional package surfaces. - Official how-to guides from the Kody repo: if a requested package or workflow depends on a third-party integration, secrets, or OAuth, call \`kody_official_guide\` with \`guide: "integration_bootstrap"\` before building the package. Then load the relevant setup guide: \`oauth\` for standard third-party OAuth (\`/connect/oauth\`), \`connect_secret\` for secret collection, and \`secret_backed_integration\` for the default non-OAuth secret-backed recipe after bootstrap. If unsure, \`search\` for this capability and load the right guide before implementing. - Do not save or present an auth-dependent package as complete until \`search\` shows the required integration or secret reference exists and a minimal authenticated \`execute\` smoke test succeeds. diff --git a/packages/worker/src/mcp/tools/execute.ts b/packages/worker/src/mcp/tools/execute.ts index 916341e696..6e93ae3831 100644 --- a/packages/worker/src/mcp/tools/execute.ts +++ b/packages/worker/src/mcp/tools/execute.ts @@ -49,12 +49,12 @@ Sandbox surface: - Import runtime helpers from \`kody:runtime\`. - \`import { codemode } from 'kody:runtime'\` for builtin capabilities discovered by \`search\`; call valid identifier names as \`await codemode.capability_id(input)\`. If a capability id is not a valid JavaScript identifier, use bracket notation: \`await codemode["capability-id"](input)\`. Capability detail from \`search({ entity: "{name}:capability" })\` includes the exact snippet. - \`import { storage } from 'kody:runtime'\` for durable storage helpers on the bound \`storageId\`, including \`storage.sql(query, params?)\`. \`storage.sql\` returns \`{ columns, rows, rowCount, rowsRead, rowsWritten }\`; read query rows from \`.rows\`. -- \`import { refreshAccessToken, createAuthenticatedFetch } from 'kody:runtime'\` for OAuth integrations. Integration \`name\` may be account-specific (e.g. \`google-personal\`, \`google-business\`); call \`integration_list\` first when the task involves a provider that may have multiple accounts connected. +- \`import { refreshAccessToken, createAuthenticatedFetch, oauthClientCredentials, secretHeaders } from 'kody:runtime'\` for OAuth integrations and secret-derived auth headers. Integration \`name\` may be account-specific (e.g. \`google-personal\`, \`google-business\`); call \`integration_list\` first when the task involves a provider that may have multiple accounts connected. For APIs such as PayPal that require client-credentials Basic Auth, save the client id and client secret separately and use \`secretHeaders.basic({ usernameSecret: 'paypalClientId', passwordSecret: 'paypalClientSecret', scope: 'user' })\` in the Authorization header, or \`oauthClientCredentials(...)\` for the token request. Do not ask users to precompute or save a derived Basic header. - \`import { workflows } from 'kody:runtime'\` for durable Cloudflare Workflows. \`workflows.create\` accepts either inline \`code\` or a saved-package \`exportName\`; use \`workflow_list\` to inspect recent runs. - Optional \`params\` are passed as the first argument to the module default export. Prefer \`export default async function main(input = {}) { ... }\`; pass \`input\` to shared helpers explicitly. - \`import { packageContext } from 'kody:runtime'\` in saved package code when you need package metadata; it is \`null\` for ad hoc execute calls. - \`import { packages } from 'kody:runtime'\` exposes \`packages.check(...)\`, \`packages.invoke(...)\`, and \`packages.invokeChecked(...)\` only in saved package runtime contexts; it is \`null\` for ad hoc execute calls. Prefer \`invokeChecked\` for dynamic current-version package calls unless you already called \`check\` and pass \`check.invoke\` to \`invoke\`. -- \`fetch(...)\` is the host-provided network global; \`{{secret:name}}\` / \`{{secret:name|scope=user}}\` work in URL, headers, or body on approved hosts only. +- \`fetch(...)\` is the host-provided network global; \`{{secret:name}}\` / \`{{secret:name|scope=user}}\` work in URL, headers, or body on approved hosts only. \`secretHeaders.basic(...)\` returns an opaque placeholder for fetch headers; the gateway resolves both referenced secrets, enforces host approval for both, and sends only the derived Basic header. - Fields marked \`x-kody-secret: true\` accept the same placeholder form; respect per-secret allowed-capability lists. - Placeholders are not general string interpolation (they do not resolve in arbitrary return values). - Never place placeholder text into user-visible or third-party-visible content such as issue bodies, comments, prompts, logs, or returned strings. If you need to describe a placeholder literally, obfuscate it instead of embedding the exact \`{{secret:...}}\` token into content that may be sent over \`fetch\`. diff --git a/packages/worker/src/package-runtime/module-graph.node.test.ts b/packages/worker/src/package-runtime/module-graph.node.test.ts index 4a9982f681..1a91b1eeb2 100644 --- a/packages/worker/src/package-runtime/module-graph.node.test.ts +++ b/packages/worker/src/package-runtime/module-graph.node.test.ts @@ -2350,4 +2350,10 @@ test('buildKodyAppBundle runtime module exports package invocation helper', asyn expect(firstCall?.files?.['.__kody_virtual__/runtime.js']).toContain( 'export const packages = runtime.packages ?? null;', ) + expect(firstCall?.files?.['.__kody_virtual__/runtime.js']).toContain( + 'export const secretHeaders = runtime.secretHeaders;', + ) + expect(firstCall?.files?.['.__kody_virtual__/runtime.js']).toContain( + 'export const oauthClientCredentials = runtime.oauthClientCredentials;', + ) }) diff --git a/packages/worker/src/package-runtime/module-graph.ts b/packages/worker/src/package-runtime/module-graph.ts index 7fb164f91b..ce7c7d2631 100644 --- a/packages/worker/src/package-runtime/module-graph.ts +++ b/packages/worker/src/package-runtime/module-graph.ts @@ -269,6 +269,8 @@ export const codemode = __kodyCodemode; export const storage = runtime.storage; export const refreshAccessToken = runtime.refreshAccessToken; export const createAuthenticatedFetch = runtime.createAuthenticatedFetch; +export const secretHeaders = runtime.secretHeaders; +export const oauthClientCredentials = runtime.oauthClientCredentials; export const packageContext = runtime.packageContext ?? null; export const serviceContext = runtime.serviceContext ?? null; export const service = runtime.service ?? null; diff --git a/packages/worker/src/repo/checks.ts b/packages/worker/src/repo/checks.ts index 3f5180fd4a..b2cf25866d 100644 --- a/packages/worker/src/repo/checks.ts +++ b/packages/worker/src/repo/checks.ts @@ -285,6 +285,23 @@ type KodyStorageRuntime = { delete(key: string): Promise; clear(): Promise; }; +type KodySecretScope = 'user' | 'app' | 'session'; +type KodySecretHeadersRuntime = { + basic(input: { + usernameSecret: string; + passwordSecret: string; + scope?: KodySecretScope | null; + }): string; +}; +type KodyOauthClientCredentialsInput = { + tokenUrl: string | URL; + clientIdSecret: string; + clientSecretSecret: string; + scope?: KodySecretScope | null; + authStyle?: 'basic'; + body?: Record; + headers?: Record; +}; type KodyEmailRuntime = { getMessage(messageId: string): Promise; getAttachment(attachmentId: string): Promise; @@ -303,6 +320,10 @@ declare function refreshAccessToken(providerName: string): Promise; declare function createAuthenticatedFetch( providerName: string, ): Promise<(input: string | URL | Request, init?: RequestInit) => Promise>; +declare const secretHeaders: KodySecretHeadersRuntime; +declare function oauthClientCredentials( + input: KodyOauthClientCredentialsInput, +): Promise>; declare const packageContext: { packageId: string; kodyId: string } | null; declare const serviceContext: { serviceName: string } | null; declare const packages: KodyPackagesRuntime | null; @@ -332,6 +353,10 @@ declare module "kody:runtime" { export function createAuthenticatedFetch( providerName: string, ): Promise<(input: string | URL | Request, init?: RequestInit) => Promise>; + export const secretHeaders: KodySecretHeadersRuntime; + export function oauthClientCredentials( + input: KodyOauthClientCredentialsInput, + ): Promise>; export const packageContext: { packageId: string; kodyId: string } | null; export const serviceContext: { serviceName: string } | null; export const packages: KodyPackagesRuntime | null;