Skip to content

Commit a0a6437

Browse files
committed
WIP(#27237): contract review r3 — degrade wording, encoded-form scrub, walled install note
Claude-Session: https://claude.ai/code/session_01Utp6CaqVRa7ow6CjE1JwaG Co-authored-by: Claude <noreply@anthropic.com>
1 parent bda699c commit a0a6437

11 files changed

Lines changed: 207 additions & 42 deletions

File tree

‎packages/cloud-connection/src/marketplace-install-local-credential-refs.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,18 @@ describe('[#27237] the install answer names the connector credentials the packag
117117
expect(res.payload.data.credentialNote).not.toContain('BILLING_SET_REF');
118118
});
119119

120+
it('under a walled posture (the listing says nothing is writable) the note does not send anyone to the PUT route', async () => {
121+
const listConnectorCredentialRefs = vi.fn(async () => [
122+
{ ref: 'BILLING_MISSING_REF', status: 'missing', source: null, writable: false, declared: true, connectors: [] },
123+
]);
124+
const install = await bootPlugin({ listConnectorCredentialRefs });
125+
const res = await install([bearer('billing', 'BILLING_MISSING_REF')]);
126+
expect(res.payload?.success, JSON.stringify(res.payload)).toBe(true);
127+
expect(res.payload.data.credentialNote).toBe(installedCredentialNote(['BILLING_MISSING_REF'], { door: false }));
128+
expect(res.payload.data.credentialNote).not.toContain('credential-refs');
129+
expect(res.payload.data.credentialNote).toContain('server environment variable of the same name');
130+
});
131+
120132
it('with no automation service to ask, each reference is `unknown`, never assumed set', async () => {
121133
const install = await bootPlugin();
122134
const res = await install([bearer('billing', 'BILLING_SET_REF')]);

‎packages/cloud-connection/src/marketplace-install-local-plugin.ts‎

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -748,14 +748,23 @@ export interface InstalledCredentialRef {
748748
source: ConnectorCredentialRef['source'];
749749
}
750750

751-
/** [#27237] The install answer's sentence for the credentials not set yet. */
752-
export function installedCredentialNote(refs: readonly string[]): string {
751+
/**
752+
* [#27237] The install answer's sentence for the credentials not set yet.
753+
* `door: false` when the credential door cannot store any of them — the
754+
* automation service's listing says none is `writable`, as under the `group` /
755+
* `isolated` postures, where the door refuses — so the sentence does not send
756+
* an administrator to a route that will refuse.
757+
*/
758+
export function installedCredentialNote(refs: readonly string[], opts: { door?: boolean } = {}): string {
753759
const list = refs.map((r) => `'${r}'`).join(', ');
754760
return (
755761
`Connector credential${refs.length === 1 ? '' : 's'} ${list} ${refs.length === 1 ? 'needs' : 'need'} an `
756762
+ "administrator — not set, refused by the upstream, or unreadable now (each entry's `status` says which). The "
757763
+ 'connector instances naming them are installed degraded and materialize once each is set: '
758-
+ 'PUT /api/v1/automation/connectors/credential-refs/:ref, or a server environment variable of the same name.'
764+
+ (opts.door === false
765+
? "as a server environment variable of the same name, or in the host's credential resolver. This environment "
766+
+ 'does not store connector credentials through the credential door.'
767+
: 'PUT /api/v1/automation/connectors/credential-refs/:ref, or a server environment variable of the same name.')
759768
);
760769
}
761770

@@ -1982,8 +1991,12 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
19821991
// 7. [#27237] Which connector credentials the package names, and which
19831992
// are not set yet — after the re-sync above, so the listing reads
19841993
// what the reconcile it triggered saw.
1985-
const credentialRefs = await this.describeInstalledCredentialRefs(ctx, converted);
1994+
const described = await this.describeInstalledCredentialRefs(ctx, converted);
1995+
const credentialRefs = described?.entries;
19861996
const unsetRefs = (credentialRefs ?? []).filter((r) => r.status !== 'set').map((r) => r.ref);
1997+
// The door is named only when it can store one of them: a listing that
1998+
// says none is writable (a walled posture) gets the other places.
1999+
const door = described?.writable === undefined || unsetRefs.some((r) => described.writable!.has(r));
19872000

19882001
return c.json({
19892002
success: true,
@@ -2003,7 +2016,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
20032016
// [#27237] Omitted, not emptied, for a package whose connectors
20042017
// name no credential, so that answer's key set is unchanged.
20052018
...(credentialRefs !== undefined ? { credentialRefs } : {}),
2006-
...(unsetRefs.length > 0 ? { credentialNote: installedCredentialNote(unsetRefs) } : {}),
2019+
...(unsetRefs.length > 0 ? { credentialNote: installedCredentialNote(unsetRefs, { door }) } : {}),
20072020
upgradedFrom: conflict === 'marketplace' ? 'previous-marketplace-version' : null,
20082021
translationsLoaded: seededSummary.translationsLoaded,
20092022
seeded: seededSummary.seeded,
@@ -3510,11 +3523,13 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
35103523
* naming it installs degraded and materializes when an administrator sets
35113524
* it (`PUT /api/v1/automation/connectors/credential-refs/:ref`). With no
35123525
* automation service, or one that cannot list, the status is `unknown`.
3526+
* `writable` is the references the credential door can store, as the
3527+
* listing says; `undefined` when there is no listing to say it.
35133528
*/
35143529
private describeInstalledCredentialRefs = async (
35153530
ctx: PluginContext,
35163531
converted: unknown,
3517-
): Promise<InstalledCredentialRef[] | undefined> => {
3532+
): Promise<{ entries: InstalledCredentialRef[]; writable?: ReadonlySet<string> } | undefined> => {
35183533
const connectors = (converted as { connectors?: unknown } | null)?.connectors;
35193534
const declared = new Map<string, string[]>();
35203535
for (const raw of Array.isArray(connectors) ? connectors : []) {
@@ -3537,7 +3552,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
35373552
+ `each credential the package names as status 'unknown'. Cause: ${err?.message ?? err}`,
35383553
);
35393554
}
3540-
return [...declared.keys()].sort().map((ref) => {
3555+
const entries = [...declared.keys()].sort().map((ref): InstalledCredentialRef => {
35413556
const known = listing?.get(ref);
35423557
return {
35433558
ref,
@@ -3546,6 +3561,10 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
35463561
source: known?.source ?? null,
35473562
};
35483563
});
3564+
const writable = listing === undefined
3565+
? undefined
3566+
: new Set([...declared.keys()].filter((ref) => listing!.get(ref)?.writable !== false));
3567+
return { entries, ...(writable ? { writable } : {}) };
35493568
};
35503569

35513570
/**

‎packages/services/service-automation/src/connector-credential-door.test.ts‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,14 @@ import { AutomationServicePlugin, type CredentialResolver } from './plugin.js';
4545
import type { AutomationEngine } from './engine.js';
4646
import { SysConnectorCredential } from './sys-connector-credential.object.js';
4747
import { SysFlowCredential } from './sys-flow-credential.object.js';
48-
import { CONNECTOR_CREDENTIAL_OBJECT, ConnectorCredentialStore } from './connector-credentials.js';
48+
import {
49+
CONNECTOR_CREDENTIAL_OBJECT,
50+
ConnectorCredentialStore,
51+
credentialForms,
52+
upstreamRefusalMessage,
53+
withoutCredential,
54+
withoutCredentialThrown,
55+
} from './connector-credentials.js';
4956

5057
const REF = 'DUMMY_BILLING_TOKEN_27237';
5158
const DUMMY_VALUE = 'dummy-value-aaaa-0001';
@@ -610,3 +617,69 @@ describe('[#27237] seat review r1: under a walled posture the store is not in th
610617
expect((await engine.listConnectorCredentialRefs())[0]).toMatchObject({ source: 'env', status: 'set', writable: false });
611618
});
612619
});
620+
621+
describe('[#27237] contract review: an encoded spelling of the value is withheld too', () => {
622+
const USERNAME = 'svc_dummy_27237';
623+
// Characters that URL-encode, so the encoded spelling differs from the raw one.
624+
const ENCODABLE = 'dummy/value+eeee 0010';
625+
const b64 = (text: string) => Buffer.from(text, 'utf8').toString('base64');
626+
627+
it('lists the raw, URL-encoded and base64 spellings, and base64(`user:value`) for basic auth', () => {
628+
const forms = credentialForms(ENCODABLE, USERNAME);
629+
expect(forms).toContain(ENCODABLE);
630+
expect(forms).toContain(encodeURIComponent(ENCODABLE));
631+
expect(forms).toContain(b64(ENCODABLE).replace(/=+$/, ''));
632+
expect(forms).toContain(b64(`${USERNAME}:${ENCODABLE}`).replace(/=+$/, ''));
633+
const echoed = `Authorization: Basic ${b64(`${USERNAME}:${ENCODABLE}`)} url ?key=${encodeURIComponent(ENCODABLE)}`;
634+
const scrubbed = withoutCredential(echoed, forms);
635+
for (const form of forms) expect(scrubbed.includes(form), form.length.toString()).toBe(false);
636+
expect(scrubbed).toContain('[credential withheld]');
637+
const thrown = withoutCredentialThrown(Object.assign(new Error('outer'), { cause: new Error(echoed) }), forms) as Error;
638+
expect(String(thrown.message)).toBe('outer');
639+
expect((thrown as { cause?: unknown }).cause).toBeUndefined();
640+
expect(upstreamRefusalMessage({ message: echoed }, forms)).not.toContain(encodeURIComponent(ENCODABLE));
641+
});
642+
643+
it('a basic-auth instance whose upstream echoes the encoded header and URL: no spelling reaches the reason, the row or a log', async () => {
644+
const out = captureOutput();
645+
const header = b64(`${USERNAME}:${ENCODABLE}`);
646+
const provider = fakeProvider();
647+
const factory: ConnectorProviderFactory = (ctx) => {
648+
provider.state.materialized.push(ctx);
649+
const password = ctx.auth?.type === 'basic' ? ctx.auth.password : '';
650+
const echo = `sent Authorization: Basic ${b64(`${USERNAME}:${password}`)} to https://erp.example/?key=${encodeURIComponent(password)}`;
651+
if (provider.state.rejectAtMaterialization) throw new ConnectorCredentialRejectedError(`refused (HTTP 401): ${echo}`, 401);
652+
return {
653+
def: { name: ctx.name, label: ctx.label, type: 'api', actions: [{ key: 'request', label: 'Request' }] } as unknown as Connector,
654+
handlers: { request: async () => ({ status: 401, ok: false, body: { message: echo } }) },
655+
};
656+
};
657+
const erp = { ...billing('erp'), auth: { type: 'basic', username: USERNAME, credentialRef: REF } };
658+
const { engine, call } = await boot([erp], { provider: { ...provider, factory } });
659+
660+
// On a call (the rest / openapi shape).
661+
await engine.setConnectorCredential({ ref: REF, value: ENCODABLE, context: ADMIN });
662+
expect(await call('erp')).toMatchObject({ status: 401 });
663+
const onCall = engine.getConnectorDegradedReason('erp') ?? '';
664+
expect(onCall).toContain('[credential withheld]');
665+
const listedOnCall = JSON.stringify(await engine.listConnectorCredentialRefs());
666+
667+
// At materialization (the mcp shape).
668+
provider.state.rejectAtMaterialization = true;
669+
await engine.setConnectorCredential({ ref: REF, value: DUMMY_VALUE_2, context: ADMIN });
670+
const atMaterialization = engine.getConnectorDegradedReason('erp') ?? '';
671+
expect(atMaterialization).toContain('[credential withheld]');
672+
673+
for (const [where, text] of [
674+
['reason on a call', onCall],
675+
['listing after the call', listedOnCall],
676+
['reason at materialization', atMaterialization],
677+
['listing after materialization', JSON.stringify(await engine.listConnectorCredentialRefs())],
678+
['logs', out.text()],
679+
] as const) {
680+
for (const form of [header, encodeURIComponent(ENCODABLE), ENCODABLE, b64(`${USERNAME}:${DUMMY_VALUE_2}`).replace(/=+$/, '')]) {
681+
expect(text.includes(form), `${where}: a spelling of the value`).toBe(false);
682+
}
683+
}
684+
});
685+
});

‎packages/services/service-automation/src/connector-credentials.ts‎

Lines changed: 55 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ export class ConnectorCredentialStore {
309309
);
310310
}
311311
// Whatever else refused the write answers without the value it was handed.
312-
throw withoutCredentialThrown(err, args.value);
312+
throw withoutCredentialThrown(err, credentialForms(args.value));
313313
}
314314
return { created: !existing, revision };
315315
}
@@ -384,32 +384,72 @@ export class ConnectorCredentialStore {
384384
}
385385
}
386386

387+
/** What a scrub withholds: one value, or every spelling of it ({@link credentialForms}). */
388+
export type WithheldCredential = string | readonly string[] | undefined;
389+
390+
/** The shortest spelling a scrub withholds — a shorter one would blank ordinary words. */
391+
const MIN_WITHHELD_LENGTH = 4;
392+
393+
function base64Of(text: string): string {
394+
const bytes = new TextEncoder().encode(text);
395+
let binary = '';
396+
for (const byte of bytes) binary += String.fromCharCode(byte);
397+
return btoa(binary);
398+
}
399+
400+
/**
401+
* Every spelling of `value` an upstream or a client library may echo back:
402+
* the value itself; URL-encoded, as an api-key sent as a query parameter
403+
* travels in the request URL; base64; and, given the `basic` `username`,
404+
* base64(`username:value`), the `Authorization: Basic` header. A base64 form
405+
* is kept without its `=` padding, so an echo that drops the padding is
406+
* withheld too. Longest first, so a longer form is replaced before a shorter
407+
* one inside it.
408+
*/
409+
export function credentialForms(value: string | undefined, username?: string): string[] {
410+
if (!value) return [];
411+
const forms = new Set<string>([value, encodeURIComponent(value), base64Of(value).replace(/=+$/, '')]);
412+
if (username !== undefined) forms.add(base64Of(`${username}:${value}`).replace(/=+$/, ''));
413+
return [...forms].filter((f) => f.length >= MIN_WITHHELD_LENGTH).sort((a, b) => b.length - a.length);
414+
}
415+
416+
function withheldForms(secret: WithheldCredential): readonly string[] {
417+
if (secret === undefined) return [];
418+
if (typeof secret === 'string') return secret.length >= MIN_WITHHELD_LENGTH ? [secret] : [];
419+
return secret.filter((f) => f.length >= MIN_WITHHELD_LENGTH);
420+
}
421+
387422
/**
388-
* `message` with every occurrence of `secret` replaced. A provider's message
389-
* is foreign text; an upstream that echoes the credential back must not carry
390-
* it into a log line, a husk's reason or a stored status.
423+
* `message` with every occurrence of `secret` replaced — one value, or every
424+
* spelling {@link credentialForms} lists. A provider's message is foreign
425+
* text; an upstream that echoes the credential back, in any of those
426+
* spellings, must not carry it into a log line, a husk's reason or a stored
427+
* status.
391428
*/
392-
export function withoutCredential(message: string, secret: string | undefined): string {
393-
if (!secret || secret.length < 4) return message;
394-
return message.split(secret).join('[credential withheld]');
429+
export function withoutCredential(message: string, secret: WithheldCredential): string {
430+
let out = message;
431+
for (const form of withheldForms(secret)) out = out.split(form).join('[credential withheld]');
432+
return out;
395433
}
396434

397435
/**
398436
* `err` with `secret` withheld from its message, keeping the structural marks
399-
* a caller branches on (`code`, `status`, `name`). Returned unchanged when the
400-
* secret appears nowhere in its message chain; otherwise rebuilt without its
401-
* stack and cause, which carry the same text.
437+
* a caller branches on (`code`, `status`, `name`). Returned unchanged when no
438+
* spelling of the secret appears in its message chain; otherwise rebuilt
439+
* without its stack and cause, which carry the same text.
402440
*/
403-
export function withoutCredentialThrown(err: unknown, secret: string | undefined): unknown {
404-
if (!secret || secret.length < 4 || !(err instanceof Error)) return err;
441+
export function withoutCredentialThrown(err: unknown, secret: WithheldCredential): unknown {
442+
const forms = withheldForms(secret);
443+
if (forms.length === 0 || !(err instanceof Error)) return err;
405444
let leaks = false;
406445
let cur: unknown = err;
407446
for (let depth = 0; depth < 8 && cur instanceof Error; depth++) {
408-
if (cur.message.includes(secret) || (cur.stack ?? '').includes(secret)) leaks = true;
447+
const text = `${cur.message}\n${cur.stack ?? ''}`;
448+
if (forms.some((f) => text.includes(f))) leaks = true;
409449
cur = (cur as { cause?: unknown }).cause;
410450
}
411451
if (!leaks) return err;
412-
const scrubbed = new Error(withoutCredential(err.message, secret));
452+
const scrubbed = new Error(withoutCredential(err.message, forms));
413453
scrubbed.name = err.name;
414454
scrubbed.stack = undefined;
415455
const marks = err as { code?: unknown; status?: unknown };
@@ -562,7 +602,7 @@ export const UPSTREAM_REFUSAL_MESSAGE_MAX_LENGTH = 500;
562602
* `secret` withheld BEFORE the bound is applied, so a cut can never leave part
563603
* of it behind.
564604
*/
565-
export function upstreamRefusalMessage(body: unknown, secret: string | undefined): string | undefined {
605+
export function upstreamRefusalMessage(body: unknown, secret: WithheldCredential): string | undefined {
566606
let text: unknown;
567607
if (typeof body === 'string') {
568608
text = body;

‎packages/services/service-automation/src/plugin.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ import {
4040
SECRET_HANDLE_PREFIX,
4141
connectorCredentialFingerprint,
4242
credentialDoorRefusal,
43+
credentialForms,
4344
credentialRejectedOnCallReason,
4445
credentialRejectionStatusOf,
4546
isAcceptedCallResult,
@@ -389,6 +390,11 @@ function credentialRefOf(auth: ConnectorInstanceAuth | undefined): string | unde
389390
return auth.credentialRef;
390391
}
391392

393+
/** The `basic` username an instance sends beside its secret — what its `Authorization` header encodes with it. */
394+
function basicUsernameOf(auth: ConnectorInstanceAuth | undefined): string | undefined {
395+
return auth?.type === 'basic' ? auth.username : undefined;
396+
}
397+
392398
/**
393399
* Build the static {@link ResolvedConnectorAuth} a provider factory applies
394400
* from a declarative instance's `auth` and the secret its `credentialRef`
@@ -2275,7 +2281,7 @@ export class AutomationServicePlugin implements Plugin {
22752281
// [#27237] A provider's message is foreign text: an upstream that
22762282
// echoes the credential back must not carry it into the husk's
22772283
// reason, a log record or the thrown boot error.
2278-
const thrown = withoutCredentialThrown(err, credential?.value);
2284+
const thrown = withoutCredentialThrown(err, credentialForms(credential?.value, basicUsernameOf(entry.auth)));
22792285
// [#27237] The upstream refused the credential (ruling on
22802286
// #27237, comment 6470087293): degrade the instance and mark a
22812287
// stored credential `rejected` — never a failed boot, never a
@@ -3036,7 +3042,10 @@ export class AutomationServicePlugin implements Plugin {
30363042
info.name,
30373043
info.ref,
30383044
status,
3039-
upstreamRefusalMessage((result as { body?: unknown }).body, info.credential.value),
3045+
upstreamRefusalMessage(
3046+
(result as { body?: unknown }).body,
3047+
credentialForms(info.credential.value, basicUsernameOf(info.entry.auth)),
3048+
),
30403049
info.credential.source === 'object',
30413050
);
30423051
try {

0 commit comments

Comments
 (0)