Skip to content

Commit b9e26de

Browse files
committed
wip(spec): close the authored connector entry; withhold URL credentials and non-object auth on read
Claude-Session: https://claude.ai/code/session_017xRBcVy4VXmkQjn2MGeaWk Co-authored-by: Claude <noreply@anthropic.com>
1 parent 004871f commit b9e26de

5 files changed

Lines changed: 466 additions & 12 deletions

File tree

‎packages/spec/src/data/datasource-credential-redaction.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -437,8 +437,16 @@ export function redactUrlPassword(value: string): string {
437437
* REFUSED at the write door — the same reasoning as the dropped inline keys.
438438
* A query left empty takes its `?` with it, so the served shape is exactly
439439
* what the write door accepts.
440+
*
441+
* `params` defaults to the datasource set; the connector read redactor
442+
* (`integration/connector-credential-redaction.ts`) passes its own name list
443+
* through this same function, so the two read paths keep ONE definition of
444+
* where a query runs and what a pair is.
440445
*/
441-
export function redactUrlCredentialQueryParams(value: string): string {
446+
export function redactUrlCredentialQueryParams(
447+
value: string,
448+
params: readonly string[] = CREDENTIAL_URL_QUERY_PARAM_NAMES,
449+
): string {
442450
const hashIdx = value.indexOf('#');
443451
const head = hashIdx === -1 ? value : value.slice(0, hashIdx);
444452
const fragment = hashIdx === -1 ? '' : value.slice(hashIdx);
@@ -447,7 +455,7 @@ export function redactUrlCredentialQueryParams(value: string): string {
447455
const kept = head
448456
.slice(queryIdx + 1)
449457
.split('&')
450-
.filter((pair) => credentialQueryParamOf(pair, CREDENTIAL_URL_QUERY_PARAM_NAMES) === undefined);
458+
.filter((pair) => credentialQueryParamOf(pair, params) === undefined);
451459
const base = head.slice(0, queryIdx);
452460
return `${kept.length > 0 ? `${base}?${kept.join('&')}` : base}${fragment}`;
453461
}

‎packages/spec/src/integration/connector-credential-redaction.test.ts‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
import { describe, it, expect } from 'vitest';
1212
import {
1313
CONNECTOR_CREDENTIAL_MAP_PATHS,
14+
CONNECTOR_CREDENTIAL_URL_QUERY_PARAM_NAMES,
1415
declaredConnectorAuthKeys,
1516
redactConnectorItem,
1617
} from './connector-credential-redaction';
@@ -142,6 +143,110 @@ describe('the connector redactor — runtime `authentication` and provider maps'
142143
});
143144
});
144145

146+
describe('the connector redactor — `auth` / `authentication` that is not an object', () => {
147+
it.each([
148+
['auth', 'a string', P(20)],
149+
['auth', 'a number', 4242],
150+
['auth', 'an array', [P(21)]],
151+
['authentication', 'a string', P(22)],
152+
] as const)('`%s` holding %s is withheld whole', (position, _what, value) => {
153+
const { item: served, redactedKeys } = redactConnectorItem({ ...base, [position]: value });
154+
expect(redactedKeys).toEqual([position]);
155+
expect(served).not.toHaveProperty(position);
156+
expect(holds(served, P(20), P(21), P(22))).toBe(false);
157+
expect(served.name).toBe('vendor');
158+
});
159+
160+
it.each([
161+
['an empty string', ''],
162+
['a null', null],
163+
] as const)('a cleared form (%s) is served as written and not reported', (_what, value) => {
164+
const item = { ...base, auth: value, authentication: value };
165+
expect(redactConnectorItem(item)).toEqual({ item, redactedKeys: [] });
166+
});
167+
});
168+
169+
describe('the connector redactor — credentials inside a URL under `providerConfig`', () => {
170+
const at = (providerConfig: Record<string, unknown>, extra: Record<string, unknown> = {}) =>
171+
redactConnectorItem({ ...base, providerConfig, ...extra });
172+
173+
it('rewrites the userinfo out of `baseUrl`, keeping the rest of the URL byte for byte', () => {
174+
const { item: served, redactedKeys } = at({ baseUrl: `https://svc:${P(30)}@api.vendor.example:8443/v2/?region=eu#top` });
175+
expect(redactedKeys).toEqual(['providerConfig.baseUrl']);
176+
expect((served.providerConfig as Record<string, unknown>).baseUrl).toBe('https://api.vendor.example:8443/v2/?region=eu#top');
177+
});
178+
179+
it('a bare token in the user part goes too', () => {
180+
const { item: served } = at({ baseUrl: `https://${P(31)}@api.vendor.example/v1` });
181+
expect((served.providerConfig as Record<string, unknown>).baseUrl).toBe('https://api.vendor.example/v1');
182+
});
183+
184+
it('strips each credential query parameter, case-insensitively, and keeps the others in order', () => {
185+
const { item: served, redactedKeys } = at({
186+
baseUrl: `https://api.vendor.example/v1?region=eu&API_KEY=${P(32)}&page=2&access_token=${P(33)}`,
187+
});
188+
expect(redactedKeys).toEqual(['providerConfig.baseUrl']);
189+
expect((served.providerConfig as Record<string, unknown>).baseUrl).toBe('https://api.vendor.example/v1?region=eu&page=2');
190+
});
191+
192+
it('covers `transport.url` and a URL `spec`, and leaves a package-relative `spec` path alone', () => {
193+
const { item: served, redactedKeys } = at({
194+
spec: `https://u:${P(34)}@spec.vendor.example/openapi.json?token=${P(35)}`,
195+
transport: { kind: 'http', url: `https://mcp.vendor.example/mcp?sig=${P(36)}` },
196+
});
197+
expect(redactedKeys).toEqual(['providerConfig.spec', 'providerConfig.transport.url']);
198+
expect(served.providerConfig).toEqual({
199+
spec: 'https://spec.vendor.example/openapi.json',
200+
transport: { kind: 'http', url: 'https://mcp.vendor.example/mcp' },
201+
});
202+
const relative = { ...base, providerConfig: { spec: './vendor-openapi.json' } };
203+
expect(redactConnectorItem(relative)).toEqual({ item: relative, redactedKeys: [] });
204+
});
205+
206+
it('strips the query parameter an `api-key` instance itself names with `paramName`', () => {
207+
const { item: served } = at(
208+
{ baseUrl: `https://api.vendor.example/v1?appid=${P(37)}&units=metric` },
209+
{ auth: { type: 'api-key', credentialRef: 'VENDOR_KEY', paramName: 'appid' } },
210+
);
211+
expect((served.providerConfig as Record<string, unknown>).baseUrl).toBe('https://api.vendor.example/v1?units=metric');
212+
expect(served.auth).toEqual({ type: 'api-key', credentialRef: 'VENDOR_KEY', paramName: 'appid' });
213+
});
214+
215+
it('a URL with no credential part, and a string that is not a URL, are untouched', () => {
216+
const item = {
217+
...base,
218+
providerConfig: {
219+
baseUrl: 'https://api.vendor.example/v1?region=eu',
220+
note: `call ?token=${P(38)} by hand`,
221+
include: ['search'],
222+
},
223+
};
224+
expect(redactConnectorItem(item)).toEqual({ item, redactedKeys: [] });
225+
});
226+
227+
it('arrays and dot-spelled keys are off the walk (the carry-forward cannot address them)', () => {
228+
const item = {
229+
...base,
230+
providerConfig: {
231+
servers: [`https://u:${P(39)}@a.example`],
232+
'v1.url': `https://u:${P(40)}@b.example`,
233+
},
234+
};
235+
expect(redactConnectorItem(item)).toEqual({ item, redactedKeys: [] });
236+
});
237+
238+
it('a map withheld whole is not walked for URLs: it is reported once, as the map', () => {
239+
const { redactedKeys } = at({ headers: { Referer: `https://u:${P(41)}@c.example` } });
240+
expect(redactedKeys).toEqual(['providerConfig.headers']);
241+
});
242+
243+
it('the query names include the datasource set and the HTTP conventions', () => {
244+
for (const name of ['password', 'authToken', 'api_key', 'apikey', 'access_token', 'token', 'key', 'sig', 'client_secret']) {
245+
expect(CONNECTOR_CREDENTIAL_URL_QUERY_PARAM_NAMES).toContain(name);
246+
}
247+
});
248+
});
249+
145250
describe('the connector redactor — purity and the untouched remainder', () => {
146251
it('never mutates its input, and leaves every other key (`_diagnostics` included) byte for byte', () => {
147252
const item = {

‎packages/spec/src/integration/connector-credential-redaction.ts‎

Lines changed: 129 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,28 @@
4141
* `Authorization` entry and an `Accept` entry are both strings — so the
4242
* whole map is withheld, the posture ruled for a webhook's `headers`
4343
* (`.meta({ credential: 'map' })`).
44+
* 4. **`auth` / `authentication` that is not an object, WHOLE.** Every door
45+
* that authors an entry refuses such a value (`invalid_type`), so a stored
46+
* one came from outside them, and what it holds cannot be judged key by
47+
* key: an `auth: '<token>'` is the secret itself. Withheld whole, fail
48+
* closed, rather than served as stored.
49+
* 5. **The credential parts of every URL under `providerConfig`** — rewritten,
50+
* not removed: the userinfo (`https://user:pass@host`, and the
51+
* `https://<token>@host` form several HTTP APIs read as a token, so the
52+
* user part goes too) and each credential query parameter
53+
* ({@link CONNECTOR_CREDENTIAL_URL_QUERY_PARAM_NAMES}, plus the
54+
* `auth.paramName` an `api-key` instance itself names), with the rest of
55+
* the URL byte for byte. That is the read half the datasource redactor
56+
* applies to a driver URL (`data/datasource-credential-redaction.ts`), and
57+
* the query half runs through the same `redactUrlCredentialQueryParams`.
58+
* It covers `providerConfig.baseUrl` (`rest`, `openapi`),
59+
* `providerConfig.transport.url` (`mcp` over http) and a URL
60+
* `providerConfig.spec` (`openapi`), and any other URL a provider keeps at
61+
* an OBJECT depth of `providerConfig`: a string is judged when it starts
62+
* with `scheme://`. Arrays are off the walk, as they are for the datasource
63+
* scrub, and so is a key spelled with a dot: the carry-forward addresses a
64+
* withheld position by its dotted path, so a position it cannot address
65+
* would turn a save of the served form into a silent credential deletion.
4466
*
4567
* ## Cleared forms, and what is never touched
4668
*
@@ -51,9 +73,17 @@
5173
* redaction is a SERVING act. The runtime reads connectors through the
5274
* protocol's execution read, which applies no serving decoration, so a
5375
* withheld map still reaches the provider that sends it.
76+
*
77+
* A rewritten URL is a withheld position like a removed one: it is named in
78+
* `redactedKeys`, and a save that sends the served URL back unchanged keeps the
79+
* stored one (the protocol's carry-forward compares the incoming value with
80+
* the served form and re-grafts the stored value only where they match), while
81+
* a URL the author edits is the author's word.
5482
*/
5583

5684
import { ConnectorInstanceAuthSchema } from '../shared/connector-auth.zod';
85+
import { CREDENTIAL_URL_QUERY_PARAM_NAMES } from '../data/driver/common.zod';
86+
import { redactUrlCredentialQueryParams } from '../data/datasource-credential-redaction';
5787
import { objectShapeOf, wrapperChainOf, zodDefOf } from '../kernel/metadata-credential-fields';
5888
import type { MetadataRedactionResult } from '../kernel/metadata-type-redaction';
5989

@@ -65,6 +95,59 @@ export const CONNECTOR_CREDENTIAL_MAP_PATHS: readonly (readonly string[])[] = Ob
6595
['providerConfig', 'transport', 'env'],
6696
]);
6797

98+
/**
99+
* The query parameters whose value a connector URL is read as carrying a
100+
* credential in (see the module note, item 5): the datasource set
101+
* (`password`, `authToken`) and the names HTTP APIs conventionally take a key,
102+
* token or signature under. Matched case-insensitively on the decoded name
103+
* (`credentialQueryParamOf`). A name here that holds no secret on some API
104+
* costs that API's served URL the parameter, never its stored value: the
105+
* carry-forward keeps it on a save of the served form.
106+
*/
107+
export const CONNECTOR_CREDENTIAL_URL_QUERY_PARAM_NAMES: readonly string[] = Object.freeze([
108+
...CREDENTIAL_URL_QUERY_PARAM_NAMES,
109+
'access_token',
110+
'api_key',
111+
'api-key',
112+
'apikey',
113+
'auth_token',
114+
'client_secret',
115+
'id_token',
116+
'key',
117+
'passwd',
118+
'refresh_token',
119+
'secret',
120+
'sig',
121+
'signature',
122+
'token',
123+
'x-api-key',
124+
]);
125+
126+
/** `scheme://` — the strings item 5 judges. */
127+
const URL_SCHEME_RE = /^[a-z][a-z0-9+.\-]*:\/\//i;
128+
129+
/**
130+
* `scheme://userinfo@` — the whole userinfo. Every class excludes `/?#`, so the
131+
* `@` must sit in the authority; the greedy class backtracks to the LAST `@`
132+
* before the path, the userinfo boundary RFC 3986 defines (the reading
133+
* `URL_USERINFO_RE` in the datasource module documents).
134+
*/
135+
const URL_USERINFO_RE = /^([a-z][a-z0-9+.\-]*:\/\/)[^/?#]*@/i;
136+
137+
/** One URL with its userinfo and credential query parameters removed; the input when there is none. */
138+
function redactConnectorUrl(value: string, params: readonly string[]): string {
139+
return redactUrlCredentialQueryParams(value.replace(URL_USERINFO_RE, '$1'), params);
140+
}
141+
142+
/** The query parameter names item 5 strips for `item`: the fixed set plus its own `auth.paramName`. */
143+
function credentialQueryParamsOf(item: Record<string, unknown>): readonly string[] {
144+
const auth = item.auth;
145+
const own = isPlainRecord(auth) && auth.type === 'api-key' && typeof auth.paramName === 'string' && auth.paramName !== ''
146+
? auth.paramName
147+
: undefined;
148+
return own === undefined ? CONNECTOR_CREDENTIAL_URL_QUERY_PARAM_NAMES : [...CONNECTOR_CREDENTIAL_URL_QUERY_PARAM_NAMES, own];
149+
}
150+
68151
/** One instance-auth kind as the union declares it: its literal-valued keys, and every key it declares. */
69152
interface DeclaredAuthKind {
70153
/** Each key whose schema is a literal, with the values it accepts (`type`, `grant`, `scheme`). */
@@ -153,22 +236,62 @@ function readAt(item: Record<string, unknown>, path: readonly string[]): { prese
153236
return { present: true, value: parent[leaf] };
154237
}
155238

156-
/** Every credential position present in `item`, as item-relative paths. */
239+
/** Every credential position present in `item` that is withheld by removal, as item-relative paths. */
157240
function credentialPathsOf(item: Record<string, unknown>): string[][] {
158241
const paths: string[][] = [];
159242
const auth = item.auth;
160243
if (isPlainRecord(auth)) {
161244
const declared = declaredConnectorAuthKeys(auth);
162245
for (const key of Object.keys(auth)) if (!declared.has(key)) paths.push(['auth', key]);
246+
} else {
247+
// Item 4: not an object, so withheld whole (a cleared form is skipped by the caller).
248+
paths.push(['auth']);
163249
}
164250
const authentication = item.authentication;
165251
if (isPlainRecord(authentication)) {
166252
for (const key of Object.keys(authentication)) if (key !== 'type') paths.push(['authentication', key]);
253+
} else {
254+
paths.push(['authentication']);
167255
}
168256
for (const path of CONNECTOR_CREDENTIAL_MAP_PATHS) paths.push([...path]);
169257
return paths;
170258
}
171259

260+
/** `item` with the value at `path` replaced, copying each container on the way; the input is never touched. */
261+
function withValueAt(item: Record<string, unknown>, path: readonly string[], value: unknown): Record<string, unknown> {
262+
const [head, ...rest] = path as [string, ...string[]];
263+
if (rest.length === 0) return { ...item, [head]: value };
264+
return { ...item, [head]: withValueAt(item[head] as Record<string, unknown>, rest, value) };
265+
}
266+
267+
/**
268+
* Item 5: every URL under `providerConfig`, at object depth, whose credential
269+
* parts {@link redactConnectorUrl} removes — the path and the rewritten value.
270+
*/
271+
function credentialUrlRewritesOf(
272+
item: Record<string, unknown>,
273+
): Array<{ path: string[]; value: string }> {
274+
const rewrites: Array<{ path: string[]; value: string }> = [];
275+
const providerConfig = item.providerConfig;
276+
if (!isPlainRecord(providerConfig)) return rewrites;
277+
const params = credentialQueryParamsOf(item);
278+
const walk = (node: Record<string, unknown>, prefix: readonly string[]): void => {
279+
for (const [key, value] of Object.entries(node)) {
280+
if (key.includes('.')) continue;
281+
const path = [...prefix, key];
282+
if (typeof value === 'string') {
283+
if (!URL_SCHEME_RE.test(value)) continue;
284+
const redacted = redactConnectorUrl(value, params);
285+
if (redacted !== value) rewrites.push({ path, value: redacted });
286+
} else if (isPlainRecord(value)) {
287+
walk(value, path);
288+
}
289+
}
290+
};
291+
walk(providerConfig, ['providerConfig']);
292+
return rewrites;
293+
}
294+
172295
/**
173296
* The built-in `connector` redactor: withholds the positions the module note
174297
* lists, names each in `redactedKeys` (dotted, sorted), and returns the input
@@ -183,6 +306,11 @@ export function redactConnectorItem(item: Record<string, unknown>): MetadataReda
183306
served = withoutKeyAt(served, path);
184307
redactedKeys.push(path.join('.'));
185308
}
309+
// After the removals, so a map withheld whole is never walked for URLs.
310+
for (const { path, value } of credentialUrlRewritesOf(served)) {
311+
served = withValueAt(served, path, value);
312+
redactedKeys.push(path.join('.'));
313+
}
186314
if (redactedKeys.length === 0) return { item, redactedKeys: [] };
187315
return { item: served, redactedKeys: redactedKeys.sort() };
188316
}

0 commit comments

Comments
 (0)