Skip to content

Commit 14e25f5

Browse files
committed
wip: authoring-lint graduation, changeset, dogfood pins
Claude-Session: https://claude.ai/code/session_017xRBcVy4VXmkQjn2MGeaWk Co-authored-by: Claude <noreply@anthropic.com>
1 parent fda28c8 commit 14e25f5

3 files changed

Lines changed: 337 additions & 16 deletions

File tree

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object `auth`
6+
7+
Clause-②: no (narrowing)
8+
Metadata-protocol: narrowed
9+
10+
<!-- adr-0087: registered connector-entry-undeclared-key-refused -->
11+
12+
**BREAKING** accept-set narrowing on an authored connector entry (`DeclarativeConnectorEntrySchema`), at every door that parses it: `defineStack({ connectors })`, `os validate` / `os compile`, the metadata plugin's artifact load at boot and on reload, and the metadata save door `PUT /api/v1/meta/connector/:name`.
13+
14+
- **Before.** The entry was a plain object: a top-level key it does not declare parsed green and meant nothing to the runtime.
15+
- **Now.** The entry is closed. Such a key is refused by name with a located error (`unrecognized_keys` at the entry; at the save door `422 INVALID_METADATA`). A credential-shaped key (`apiKey`, `token`, `secret`, `password`, …) meets the `auth.credentialRef` prescription, and a provider setting written at the top level (`baseUrl`, `spec`, `transport`, `headers`, …) is pointed at `providerConfig`. The ADR-0010 protection envelope stays declared, so a package-stamped entry still parses. An artifact `os build` wrote carries no undeclared key (it serializes the parsed stack), so only a hand-assembled artifact can meet the refusal at boot.
16+
- **Unchanged.** `ConnectorSchema` — the def a plugin hands to `registerConnector`, and the shape `defineConnector()` parses — keeps its posture. Nothing in the runtime ever read an undeclared entry key, so no connector's behaviour moves.
17+
- **Read half.** The built-in `connector` redactor also withholds, on every read exit that serves a stored body through the metadata-type redactor registry: the userinfo and the credential query parameters of every URL under `providerConfig` (`baseUrl`, `transport.url`, a URL `spec`, and any other URL a provider keeps at object depth), the rest of each URL served byte for byte; and an `auth` or `authentication` value that is not an object, whole. A save of the served form keeps the stored value (the metadata protocol's carry-forward), and the runtime keeps reading the unredacted execution view.
18+
- `redactUrlCredentialQueryParams` (`@objectstack/spec/data`) takes an optional parameter-name list; its default, and every existing caller, is unchanged.
19+
20+
## FROM → TO
21+
22+
```ts
23+
// before — parsed green; neither key was read by anything
24+
{ name: 'billing_api', label: 'Billing API', type: 'api', provider: 'rest',
25+
baseUrl: 'https://billing.example.com', apiKey: '…',
26+
auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' } },
27+
28+
// after — refused by name; the provider setting moves under providerConfig, the secret moves out of metadata
29+
{ name: 'billing_api', label: 'Billing API', type: 'api', provider: 'rest',
30+
providerConfig: { baseUrl: 'https://billing.example.com' },
31+
auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' } },
32+
```
33+
34+
Set the secret under the name `credentialRef` gives (an environment variable in the open tier, or Setup → Connector credentials) and delete the key. There is deliberately no automatic rewrite: an undeclared key may be a provider setting whose home depends on the provider, or the only copy of a secret. The upgrade guide entry is `connector-entry-undeclared-key-refused`.
Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
//
3+
// The connector metadata doors, booted on the showcase with its own connector
4+
// plugins — the authored-entry close and two read-path withholdings:
5+
//
6+
// - WRITE: the save door refuses a connector entry carrying a top-level key the
7+
// entry does not declare — a scalar or a nested container — with the
8+
// `422 INVALID_METADATA` envelope, naming the key, and stores nothing.
9+
// - CONTROL: an instance that names its secret with `credentialRef` and keeps
10+
// its provider settings under `providerConfig` saves, materializes, and
11+
// dispatches upstream with the reference resolved.
12+
// - READ: a stored row whose provider URLs carry credential parts, and one
13+
// whose `auth` / `authentication` is not an object (both seeded through the
14+
// system context, the only way such a row is written), is served with those
15+
// parts withheld, to a member and to an administrator, in the item, list and
16+
// layered reads; the stored row itself is never touched.
17+
// - CARRY-FORWARD: a save of the served form keeps the stored URL whole, and
18+
// the instance still dispatches with it.
19+
//
20+
// Every credential below is an obviously-fake placeholder, and every assertion
21+
// on one is its absence from what a door served, or its presence at rest.
22+
23+
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
24+
import { createServer, type Server } from 'node:http';
25+
import type { AddressInfo } from 'node:net';
26+
import { type VerifyStack } from '@objectstack/verify';
27+
import { bootShowcase } from './showcase-boot.js';
28+
29+
const SYSTEM = { isSystem: true, positions: [], permissions: [] };
30+
31+
const PLACEHOLDERS = {
32+
topLevel: 'TEST_PLACEHOLDER_TOP_LEVEL_VALUE',
33+
nested: 'TEST_PLACEHOLDER_NESTED_VALUE',
34+
urlPassword: 'TEST_PLACEHOLDER_URL_PASSWORD',
35+
urlQuery: 'TEST_PLACEHOLDER_URL_QUERY',
36+
carried: 'TEST_PLACEHOLDER_CARRIED_QUERY',
37+
stringAuth: 'TEST_PLACEHOLDER_STRING_AUTH',
38+
stringAuthentication: 'TEST_PLACEHOLDER_STRING_AUTHENTICATION',
39+
resolvedRef: 'TEST_PLACEHOLDER_RESOLVED_REFERENCE',
40+
} as const;
41+
const ALL_PLACEHOLDERS = Object.values(PLACEHOLDERS).filter((p) => p !== PLACEHOLDERS.resolvedRef);
42+
43+
/** The reference every instance here names; set in this process's environment before any save. */
44+
const REF = 'CEU_CONTROL_CREDENTIAL_REF';
45+
const CONTROL = 'ceu_control';
46+
const URL_ROW = 'ceu_url_stored';
47+
const CARRIED = 'ceu_url_carried';
48+
const NON_OBJECT = 'ceu_non_object_auth';
49+
50+
const rowsOf = (r: any): any[] => (Array.isArray(r) ? r : Array.isArray(r?.records) ? r.records : Array.isArray(r?.value) ? r.value : []);
51+
const bodyOf = (row: any): Record<string, any> =>
52+
typeof row?.metadata === 'string' ? JSON.parse(row.metadata) : (row?.metadata ?? {});
53+
const itemOf = (json: any): Record<string, any> => (json?.item ?? json?.data?.item ?? json?.data ?? json) as Record<string, any>;
54+
const holdsAPlaceholder = (v: unknown): boolean => {
55+
const text = typeof v === 'string' ? v : JSON.stringify(v ?? null);
56+
return ALL_PLACEHOLDERS.some((p) => text.includes(p));
57+
};
58+
59+
describe('connector metadata doors: undeclared entry keys refused; URL credentials and non-object auth withheld on read', () => {
60+
let stack: VerifyStack;
61+
let admin: string;
62+
let member: string;
63+
let ql: any;
64+
let automation: any;
65+
let upstream: Server;
66+
let upstreamUrl: string;
67+
let upstreamHostPort: string;
68+
const received: string[] = [];
69+
let previousRef: string | undefined;
70+
71+
const stored = async (name: string) =>
72+
rowsOf(await ql.find('sys_metadata', { where: { type: 'connector', name }, context: SYSTEM }));
73+
74+
const instance = (name: string, over: Record<string, unknown> = {}) => ({
75+
name,
76+
label: `CEU ${name}`,
77+
type: 'api',
78+
description: 'A provider-bound instance for the connector entry and URL pins.',
79+
provider: 'rest',
80+
providerConfig: { baseUrl: upstreamUrl },
81+
auth: { type: 'bearer', credentialRef: REF },
82+
...over,
83+
});
84+
85+
/** One door read: 200, names the connector (positive control), and serves no placeholder. */
86+
const expectWithheld = async (token: string, path: string, names: readonly string[]) => {
87+
const res = await stack.apiAs(token, 'GET', path);
88+
const text = await res.text();
89+
expect(res.status, `${path}: ${text.slice(0, 200)}`).toBe(200);
90+
for (const name of names) expect(text.includes(name), `${path} names ${name}`).toBe(true);
91+
expect(holdsAPlaceholder(text), `${path} withholds every credential part`).toBe(false);
92+
return text;
93+
};
94+
95+
/** Dispatch the instance's generic `request` action once; the URL the upstream received. */
96+
const dispatch = async (name: string, path: string): Promise<string> => {
97+
const handler = automation.resolveConnectorAction(name, 'request');
98+
expect(handler, `${name} is materialized with its request action`).toBeTypeOf('function');
99+
const before = received.length;
100+
const out = await handler({ method: 'GET', path }, {});
101+
expect(out?.status, JSON.stringify(out)).toBe(200);
102+
expect(received.length).toBe(before + 1);
103+
return received[received.length - 1]!;
104+
};
105+
106+
const waitReady = async (name: string): Promise<void> => {
107+
const deadline = Date.now() + 15_000;
108+
let last = '';
109+
while (Date.now() < deadline) {
110+
const res = await stack.apiAs(admin, 'GET', '/automation/connectors');
111+
const json = (await res.json()) as any;
112+
const found = (json?.data?.connectors ?? []).find((c: any) => c?.name === name);
113+
last = JSON.stringify(found ?? null);
114+
if (found?.state === 'ready') return;
115+
await new Promise((r) => setTimeout(r, 100));
116+
}
117+
throw new Error(`connector ${name} never reached ready: ${last}`);
118+
};
119+
120+
/** A clean save makes the row; the system context then writes `body` over it. */
121+
const seed = async (name: string, body: Record<string, unknown>) => {
122+
const put = await stack.apiAs(admin, 'PUT', `/meta/connector/${name}`, instance(name));
123+
expect(put.status, await put.clone().text()).toBe(200);
124+
const [row] = await stored(name);
125+
await ql.update('sys_metadata', { id: row.id, metadata: JSON.stringify(body) }, { context: SYSTEM });
126+
};
127+
128+
beforeAll(async () => {
129+
upstream = createServer((req, res) => {
130+
received.push(req.url ?? '');
131+
res.writeHead(200, { 'Content-Type': 'application/json' });
132+
res.end('{"ok":true}');
133+
});
134+
await new Promise<void>((r) => upstream.listen(0, '127.0.0.1', () => r()));
135+
upstreamHostPort = `127.0.0.1:${(upstream.address() as AddressInfo).port}`;
136+
upstreamUrl = `http://${upstreamHostPort}`;
137+
previousRef = process.env[REF];
138+
process.env[REF] = PLACEHOLDERS.resolvedRef;
139+
140+
stack = await bootShowcase({});
141+
ql = await stack.kernel.getServiceAsync<any>('objectql');
142+
automation = await stack.kernel.getServiceAsync<any>('automation');
143+
admin = await stack.signIn();
144+
member = await stack.signUp('ceu-member@connector-entry.test');
145+
}, 180_000);
146+
147+
afterAll(async () => {
148+
await stack?.stop?.();
149+
await new Promise<void>((r) => (upstream ? upstream.close(() => r()) : r()));
150+
if (previousRef === undefined) delete process.env[REF];
151+
else process.env[REF] = previousRef;
152+
});
153+
154+
describe('WRITE: the save door refuses a top-level key the connector entry does not declare', () => {
155+
it.each([
156+
['a credential-shaped scalar', 'ceu_refused_scalar', { apiKey: PLACEHOLDERS.topLevel }, 'apiKey', 'credentialRef'],
157+
['a nested container', 'ceu_refused_nested', { extraConfig: { secret: PLACEHOLDERS.nested } }, 'extraConfig', 'Unrecognized'],
158+
['a misplaced provider setting', 'ceu_refused_provider', { baseUrl: 'http://127.0.0.1:9/v1' }, 'baseUrl', 'providerConfig'],
159+
] as const)('%s: 422 INVALID_METADATA naming the key, and nothing is stored', async (_label, name, extra, key, prescription) => {
160+
const res = await stack.apiAs(admin, 'PUT', `/meta/connector/${name}`, { ...instance(name), ...extra });
161+
const json = (await res.json()) as any;
162+
expect(res.status, JSON.stringify(json).slice(0, 400)).toBe(422);
163+
expect(json.code, JSON.stringify(json).slice(0, 400)).toBe('INVALID_METADATA');
164+
const issues = (json.issues ?? json.error?.issues ?? json.details?.issues ?? []) as Array<{ path?: unknown; code?: string; message?: string }>;
165+
const located = issues.find((i) => i.code === 'unrecognized_keys' && (i.path === '' || i.path === undefined));
166+
expect(located, JSON.stringify(issues).slice(0, 400)).toBeDefined();
167+
expect(located!.message).toContain(`\`${key}\``);
168+
expect(located!.message).toContain(prescription);
169+
expect(holdsAPlaceholder(json), 'the refusal never echoes the value').toBe(false);
170+
expect(await stored(name)).toHaveLength(0);
171+
const read = await stack.apiAs(member, 'GET', `/meta/connector/${name}`);
172+
expect(read.status, 'a refused entry is not served to anyone').toBe(404);
173+
});
174+
});
175+
176+
describe('CONTROL: a declared-keys-only instance saves and works', () => {
177+
it('saves, materializes ready, and dispatches with the reference resolved', async () => {
178+
const put = await stack.apiAs(admin, 'PUT', `/meta/connector/${CONTROL}`, instance(CONTROL, {
179+
providerConfig: { baseUrl: `${upstreamUrl}/v1` },
180+
}));
181+
expect(put.status, await put.clone().text()).toBe(200);
182+
await waitReady(CONTROL);
183+
expect(await dispatch(CONTROL, '/probe')).toBe('/v1/probe');
184+
});
185+
});
186+
187+
describe('READ: credential parts of a stored URL, and a non-object auth, are withheld from every reader', () => {
188+
beforeAll(async () => {
189+
await seed(URL_ROW, {
190+
...instance(URL_ROW, { label: 'CEU url (seeded)' }),
191+
providerConfig: {
192+
baseUrl: `http://svc:${PLACEHOLDERS.urlPassword}@${upstreamHostPort}/v1?api_key=${PLACEHOLDERS.urlQuery}&region=eu`,
193+
spec: `https://svc:${PLACEHOLDERS.urlPassword}@spec.invalid/openapi.json?token=${PLACEHOLDERS.urlQuery}`,
194+
transport: { kind: 'http', url: `https://mcp.invalid/mcp?access_token=${PLACEHOLDERS.urlQuery}` },
195+
},
196+
});
197+
await seed(NON_OBJECT, {
198+
...instance(NON_OBJECT, { label: 'CEU non-object (seeded)' }),
199+
auth: PLACEHOLDERS.stringAuth,
200+
authentication: PLACEHOLDERS.stringAuthentication,
201+
});
202+
});
203+
204+
it('guard the guard: the stored rows hold every seeded credential part', async () => {
205+
const url = bodyOf((await stored(URL_ROW))[0]);
206+
expect(url.label).toBe('CEU url (seeded)');
207+
expect(url.providerConfig.baseUrl).toContain(PLACEHOLDERS.urlPassword);
208+
expect(url.providerConfig.baseUrl).toContain(PLACEHOLDERS.urlQuery);
209+
expect(url.providerConfig.spec).toContain(PLACEHOLDERS.urlPassword);
210+
expect(url.providerConfig.transport.url).toContain(PLACEHOLDERS.urlQuery);
211+
const nonObject = bodyOf((await stored(NON_OBJECT))[0]);
212+
expect(nonObject.auth).toBe(PLACEHOLDERS.stringAuth);
213+
expect(nonObject.authentication).toBe(PLACEHOLDERS.stringAuthentication);
214+
});
215+
216+
it('the item read and the layered view withhold every part, for a member and for an administrator', async () => {
217+
for (const token of [member, admin]) {
218+
const urlText = await expectWithheld(token, `/meta/connector/${URL_ROW}`, [URL_ROW, 'CEU url (seeded)']);
219+
expect(itemOf(JSON.parse(urlText)).providerConfig).toEqual({
220+
baseUrl: `http://${upstreamHostPort}/v1?region=eu`,
221+
spec: 'https://spec.invalid/openapi.json',
222+
transport: { kind: 'http', url: 'https://mcp.invalid/mcp' },
223+
});
224+
await expectWithheld(token, `/meta/connector/${URL_ROW}/layers`, [URL_ROW]);
225+
226+
const nonObjectText = await expectWithheld(token, `/meta/connector/${NON_OBJECT}`, [NON_OBJECT, 'CEU non-object (seeded)']);
227+
const served = itemOf(JSON.parse(nonObjectText));
228+
expect(served).not.toHaveProperty('auth');
229+
expect(served).not.toHaveProperty('authentication');
230+
expect(served.provider).toBe('rest');
231+
await expectWithheld(token, `/meta/connector/${NON_OBJECT}/layers`, [NON_OBJECT]);
232+
}
233+
});
234+
235+
it('the list, both spellings, withholds every part, for a member and for an administrator', async () => {
236+
for (const token of [member, admin]) {
237+
await expectWithheld(token, '/meta/connector', [URL_ROW, NON_OBJECT, CONTROL]);
238+
await expectWithheld(token, '/meta/connectors', [URL_ROW, NON_OBJECT, CONTROL]);
239+
}
240+
});
241+
242+
it('the stored rows are never redacted: redaction is a serving act', async () => {
243+
expect(bodyOf((await stored(URL_ROW))[0]).providerConfig.baseUrl).toContain(PLACEHOLDERS.urlPassword);
244+
expect(bodyOf((await stored(NON_OBJECT))[0]).auth).toBe(PLACEHOLDERS.stringAuth);
245+
});
246+
});
247+
248+
describe('CARRY-FORWARD: a save of the served form keeps the stored URL, and dispatch still uses it', () => {
249+
it('the served URL drops the credential parameter; the re-saved row keeps it; the upstream receives it', async () => {
250+
const carriedUrl = `${upstreamUrl}/v1?api_key=${PLACEHOLDERS.carried}&region=eu`;
251+
const put = await stack.apiAs(admin, 'PUT', `/meta/connector/${CARRIED}`, instance(CARRIED, {
252+
providerConfig: { baseUrl: carriedUrl },
253+
}));
254+
expect(put.status, await put.clone().text()).toBe(200);
255+
await waitReady(CARRIED);
256+
257+
const read = await stack.apiAs(admin, 'GET', `/meta/connector/${CARRIED}`);
258+
const served = itemOf(await read.json());
259+
expect(served.providerConfig).toEqual({ baseUrl: `${upstreamUrl}/v1?region=eu` });
260+
expect(holdsAPlaceholder(served)).toBe(false);
261+
262+
const body = Object.fromEntries(Object.entries(served).filter(([k]) => !k.startsWith('_')));
263+
const resave = await stack.apiAs(admin, 'PUT', `/meta/connector/${CARRIED}`, { ...body, label: 'CEU carried (edited)' });
264+
expect(resave.status, await resave.clone().text()).toBe(200);
265+
const atRest = bodyOf((await stored(CARRIED))[0]);
266+
expect(atRest.label).toBe('CEU carried (edited)');
267+
expect(atRest.providerConfig.baseUrl).toBe(carriedUrl);
268+
269+
await waitReady(CARRIED);
270+
// No request path: the rest provider appends a path to the base URL as
271+
// text, so the base URL's own query stays the query only without one.
272+
expect(await dispatch(CARRIED, '')).toBe(`/v1?api_key=${PLACEHOLDERS.carried}&region=eu`);
273+
});
274+
});
275+
});

0 commit comments

Comments
 (0)