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 *
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
5684import { 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' ;
5787import { objectShapeOf , wrapperChainOf , zodDefOf } from '../kernel/metadata-credential-fields' ;
5888import 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 - z 0 - 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 - z 0 - 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. */
69152interface 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. */
157240function 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