Skip to content

Commit 9447f95

Browse files
fix(cli): os serve refuses to boot a standalone stack whose plugins lists an entry that may provide the crypto provider (#31320)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1X1zG3Xn4JonaKvDLLr5gnjL)_ Refs #28284 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:栈的 `plugins` 里没有插件实例(没有带 `init` 的项)时,`os serve` 走 standalone 启动,不加载作者写的 `plugins` 项。现在若其中某项声明了加密提供者(`providesServices: ['crypto-provider']`),或是无法导入的包名,则拒绝启动并点名该项;其它项照旧。 - **为什么改**:QA 第三轮发现的安全加固(细节按披露裁决不公开) - **风险与回滚**:只改 `@objectstack/cli`(patch)。新会被拒绝的只有:这类栈里声明了 `crypto-provider` 的项、无法导入的包名。standalone 启动前会按一次性 secret 命令的同样方式读取(导入)这些包名以判断其声明,但不启动它们。回滚即 revert 本 PR。 - **先看**:`packages/cli/src/commands/serve.ts` 的 `refuseSetAsideCryptoProviderPlugins`,以及 `run()` 里 `if (useArtifactFallback || shouldBootWithLibrary(config))` 开头的那一次调用。 - **两分钟验证**:`pnpm --filter @objectstack/cli exec vitest run --project integration src/commands/serve-host-crypto-provider.test.ts`,预期 27/27 通过。 - **需要你做的**:无,席位做 contract review 后落地。 ## What changes - **`os serve` refuses to boot a standalone stack whose `plugins` lists an entry that may provide the crypto provider.** A stack whose `plugins` lists no plugin instance boots the standalone stack, which does not load the authored `plugins` entries. The crypto provider (`crypto-provider`) seals every secret field, datasource credential and encrypted setting, so before that boot each authored entry is read for what it declares: - an entry that declares `providesServices: ['crypto-provider']` (ADR-0116) is refused, named, with the remedy (list the provider's plugin instance); - a package specifier that does not import declares nothing, and is refused through the existing `refuseUnloadedCryptoProviderPlugins`; - every other entry keeps today's handling. - Each entry is read the way the boot loop and the one-shot secret commands read one: a string is imported host-anchored (`Serve.importConfigPlugin`), an object is read as it is. Nothing is wrapped, mounted or initialized. - **New export** `refuseSetAsideCryptoProviderPlugins` beside `refuseUnloadedCryptoProviderPlugins` in `commands/serve.ts`. It throws the existing `HostCryptoProviderRefusal`. A host config (any entry with `init`) and a stack with no `plugins` are unchanged. ## Why QA 第三轮发现的安全加固(细节按披露裁决不公开) ## Verification Readings are on `4a2a6d1d4`, one commit that has since been rebased onto `main` at `f8c3ecc42` as `eb1a33b4e`. No `packages/cli` file changed between the two bases, so the suite reading carries over. The derived gates and type-check debt were run on `eb1a33b4e`. <details><summary>Pins, red-first and restore</summary> - New `packages/cli/test/serve-set-aside-crypto-provider-plugin.integration.test.ts`: four real `os serve` boots (src, through `runServe`). Two are refused and name the entry and `crypto-provider`: a stack whose `plugins` is one specifier that does not import, and a stack whose `plugins` is one object declaring the provider. Two CONTROLs reach the ready banner on a bound port: an object declaring another service, and a stack with no `plugins`. - `packages/cli/src/commands/serve-host-crypto-provider.test.ts`: four unit cases for `refuseSetAsideCryptoProviderPlugins`. They cover a specifier that does not import, a specifier importing a declaring plugin, and an object declaring the provider that is never initialized; the CONTROL is entries declaring other services or none, plus a missing or empty list. A source pin sits beside them: the check sits inside the standalone branch, before the authored list is replaced. 27 passed (27). - Red-first: with `serve.ts` set back to its `main` blob, the integration file read 2 failed | 2 passed (4); the two refusal cases were red and both CONTROLs green. Restored to the same blob as the commit: 4 passed (4). The CLI runs from `src` here, so no rebuild sits between mutation and run. </details> <details><summary>Package suite, build and typecheck</summary> - `pnpm turbo run build --filter=@objectstack/cli...`: exit 0. - `tsc --noEmit` in `packages/cli`: exit 0. - `pnpm --filter @objectstack/cli test` under the verify lock: Test Files 608 passed | 1 skipped (609), Tests 7531 passed | 9 skipped (7540), `VERDICT command-exit 0`. </details> <details><summary>Derived gates</summary> `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands`: 72 families on this diff, every one run and exit 0 (`check:type-check-debt` under the verify lock). `--ran` reconciliation: 72 derived, 72 run, 0 NOT-MEASURED, 0 UNRUN. `eslint --no-inline-config` on the three changed source files: exit 0. </details> Not measured: `os start` was not booted separately; it goes through the same `run()`. ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (No `packages/spec` change.) - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `eslint --no-inline-config` on the changed files: exit 0. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: not touched. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English, except the maintainer summary the lane's PRs carry. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. --- _Generated by [Claude Code](https://claude.ai/code/session_01FEkQ5mgePB9NQ4PNhvYVxk)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 30e0bd1 commit 9447f95

4 files changed

Lines changed: 228 additions & 0 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/cli': patch
3+
---
4+
5+
fix(cli): `os serve` refuses to boot a standalone stack whose `plugins` lists an entry that may provide the crypto provider
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
When a stack's `plugins` lists no plugin instance (no entry with `init`), `os serve` boots the standalone stack and does not load the authored `plugins` entries. It now refuses that boot when one of those entries may provide the crypto provider (`crypto-provider`), which seals every secret field, datasource credential and encrypted setting, and names the entry:
11+
12+
- an entry that declares `providesServices: ['crypto-provider']`;
13+
- a package specifier that does not import, which declares nothing.
14+
15+
An entry whose `providesServices` does not name the crypto provider (or that declares none) keeps today's handling. To boot a provider plugin, list its plugin instance in the stack's `plugins`.

‎packages/cli/src/commands/serve-host-crypto-provider.test.ts‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ import {
6464
HostCryptoProviderRefusal,
6565
refuseTwoCryptoProviderPlugins,
6666
refuseUnloadedCryptoProviderPlugins,
67+
refuseSetAsideCryptoProviderPlugins,
6768
} from './serve.js';
6869

6970
// [#10126] Pay the first load of what `serve.ts` reaches through dynamic
@@ -497,6 +498,51 @@ describe('a plugins entry that did not load refuses the boot unless it is ruled
497498
});
498499
});
499500

501+
describe('a plugins entry the standalone boot sets aside refuses the boot unless it is ruled out as the crypto provider', () => {
502+
const refusalOf = async (authored: unknown, importSpecifier: (specifier: string) => Promise<unknown>): Promise<Error | undefined> => {
503+
try { await refuseSetAsideCryptoProviderPlugins(authored, importSpecifier); }
504+
catch (err) { return err as Error; }
505+
return undefined;
506+
};
507+
const notInstalled = async (specifier: string): Promise<unknown> => {
508+
throw new Error(`Failed to import plugin '${specifier}': not found`);
509+
};
510+
511+
it('a specifier that does not import declares nothing, and is refused, named by its specifier', async () => {
512+
const refusal = await refusalOf(['@acme/kms-crypto'], notInstalled);
513+
expect(refusal).toBeInstanceOf(HostCryptoProviderRefusal);
514+
expect(refusal!.message).toContain("plugins[0] ('@acme/kms-crypto') did not load");
515+
expect(refusal!.message).toContain(`'${CRYPTO_PROVIDER_SERVICE}'`);
516+
});
517+
518+
it('a specifier that imports a plugin declaring the provider is refused, named by its specifier', async () => {
519+
const plugin = providerPlugin('com.example.aws-kms-crypto', kmsProvider().provider);
520+
const refusal = await refusalOf(['@acme/aws-kms-crypto'], async () => ({ default: plugin }));
521+
expect(refusal).toBeInstanceOf(HostCryptoProviderRefusal);
522+
expect(refusal!.message).toContain("plugins[0] ('@acme/aws-kms-crypto') provides the crypto provider");
523+
expectNoKeyMaterial(refusal!.message);
524+
});
525+
526+
it('an object entry declaring the provider is read as it is, never booted, and refused by its name', async () => {
527+
let initialized = false;
528+
const entry = { name: 'com.example.vault-crypto', providesServices: [CRYPTO_PROVIDER_SERVICE], init: async () => { initialized = true; } };
529+
const refusal = await refusalOf([entry], notInstalled);
530+
expect(refusal!.message).toContain("plugins[0] ('com.example.vault-crypto') provides the crypto provider");
531+
expect(initialized).toBe(false);
532+
});
533+
534+
it('CONTROL: entries that declare other services, or none, and a missing list, are ruled out', async () => {
535+
expect(await refusalOf([
536+
{ name: 'com.example.widgets', providesServices: ['widgets'] },
537+
{ name: 'com.example.bundle', objects: [] },
538+
'@acme/widgets',
539+
null,
540+
], async () => ({ default: { name: 'com.example.plain', providesServices: ['plain'] } }))).toBeUndefined();
541+
expect(await refusalOf(undefined, notInstalled)).toBeUndefined();
542+
expect(await refusalOf([], notInstalled)).toBeUndefined();
543+
});
544+
});
545+
500546
describe('the deferred path: nothing is sealed by a provider the boot did not choose', () => {
501547
it('a credential bound before the post-start wiring is sealed by the registered provider', async () => {
502548
const kms = kmsProvider();
@@ -625,6 +671,15 @@ describe('the wiring inside run()', () => {
625671
expect(host).toBeGreaterThan(check);
626672
});
627673

674+
it('refuses a set-aside entry that may provide the crypto provider before the standalone stack replaces the authored plugins', () => {
675+
const branch = SERVE.indexOf('if (useArtifactFallback || shouldBootWithLibrary(config)) {');
676+
const check = SERVE.indexOf('await refuseSetAsideCryptoProviderPlugins(');
677+
const replaced = SERVE.indexOf('config = mergeBootConfig(originalConfig as any, bootResult as any) as any;');
678+
expect(branch).toBeGreaterThan(0);
679+
expect(check).toBeGreaterThan(branch);
680+
expect(replaced).toBeGreaterThan(check);
681+
});
682+
628683
it('checks the declared providers before the boot', () => {
629684
const check = SERVE.indexOf('refuseTwoCryptoProviderPlugins([...stackMountedPlugins, ...resolverMounted]);');
630685
const start = SERVE.indexOf('await runtime.start();');

‎packages/cli/src/commands/serve.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2867,6 +2867,13 @@ export default class Serve extends Command {
28672867
// boot modes live in a separate distribution and are no longer
28682868
// resolved from this package.
28692869
if (useArtifactFallback || shouldBootWithLibrary(config)) {
2870+
// The authored `plugins` is set aside below (the boot stack's own
2871+
// replaces it): an entry that may provide the crypto provider refuses
2872+
// the boot first. See the function.
2873+
await refuseSetAsideCryptoProviderPlugins(
2874+
stackBootPlugins(config, false),
2875+
async (specifier) => await Serve.importConfigPlugin(specifier, servedAppRootOrCwd()),
2876+
);
28702877
// The boot stack returns only `{plugins, api}` — preserve the
28712878
// original stack metadata (notably `requires`, `analyticsCubes`,
28722879
// `tiers`) so the capability resolver further down can read it.
@@ -6464,6 +6471,57 @@ export function refuseUnloadedCryptoProviderPlugins(unloaded: readonly UnloadedS
64646471
);
64656472
}
64666473

6474+
/**
6475+
* Refuse a boot that would set aside a `plugins` entry which may provide the
6476+
* crypto provider ({@link CRYPTO_PROVIDER_SERVICE}).
6477+
*
6478+
* A stack whose `plugins` holds no plugin instance (no entry with `init`) is
6479+
* not a host config: `os serve` boots the standalone stack and uses that
6480+
* stack's plugins in place of the authored list ({@link mergeBootConfig}), so
6481+
* no authored `plugins` entry is loaded. The provider seals every secret
6482+
* field, datasource credential and encrypted setting, and the one-shot secret
6483+
* commands read the same list, so an entry the boot sets aside must be ruled
6484+
* out by what it declares. Each entry is materialized the way the boot loop
6485+
* reads one (a string is imported host-anchored; an object is read as it is,
6486+
* never wrapped or booted) and is refused when it declares the provider in
6487+
* `providesServices` (ADR-0116), or when it does not import, since an entry
6488+
* that never materialized declares nothing. Every other entry keeps today's
6489+
* handling.
6490+
*/
6491+
export async function refuseSetAsideCryptoProviderPlugins(
6492+
authored: unknown,
6493+
importSpecifier: (specifier: string) => Promise<unknown>,
6494+
): Promise<void> {
6495+
if (!Array.isArray(authored)) return;
6496+
const unloaded: UnloadedStackPlugin[] = [];
6497+
const declaring: string[] = [];
6498+
for (const [index, entry] of authored.entries()) {
6499+
if (entry === undefined || entry === null || entry === false) continue;
6500+
let materialized: unknown;
6501+
try {
6502+
materialized = await materializeStackPlugin(entry, {
6503+
importSpecifier,
6504+
wrapBundle: async (bundle) => bundle,
6505+
});
6506+
} catch (error) {
6507+
unloaded.push({ index, entry, error });
6508+
continue;
6509+
}
6510+
if (cryptoProviderPlugins([materialized]).length > 0) {
6511+
const name = (materialized as { name?: unknown }).name;
6512+
declaring.push(typeof entry === 'string' ? `plugins[${index}] ('${entry}')` : `plugins[${index}] ('${String(name)}')`);
6513+
}
6514+
}
6515+
refuseUnloadedCryptoProviderPlugins(unloaded);
6516+
if (declaring.length === 0) return;
6517+
throw new HostCryptoProviderRefusal(
6518+
`Refusing to boot: ${declaring.join(', ')} ${declaring.length === 1 ? 'provides' : 'provide'} the crypto provider `
6519+
+ `('${CRYPTO_PROVIDER_SERVICE}'), but this stack's plugins lists no plugin instance, so os serve boots the `
6520+
+ 'standalone stack and does not load it. It seals every secret field, datasource credential and encrypted '
6521+
+ "setting, so this boot does not choose another one. Add the provider's plugin instance to the stack's plugins.",
6522+
);
6523+
}
6524+
64676525
/**
64686526
* What {@link createUnknownHostnameGuardPlugin} is constructed with.
64696527
*/
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
// test-budget: 40 — spawns `os serve` (src, via runServe) once per single-cause fixture: four boots, two refused and two that reach the ready banner; budget to be re-measured
3+
4+
/**
5+
* A stack whose `plugins` lists no plugin instance (no entry with `init`) is
6+
* not a host config: `os serve` boots the standalone stack and does not load
7+
* the authored `plugins` entries. It refuses that boot when one of those
8+
* entries may provide the crypto provider (`crypto-provider`), naming it:
9+
*
10+
* - a package specifier that does not import: nothing says what it provides;
11+
* - an entry that declares the crypto provider in `providesServices`;
12+
* - CONTROL: an entry that declares another service: the boot goes on;
13+
* - CONTROL: a stack with no `plugins` at all boots.
14+
*
15+
* A real `os serve` process per case (`runServe`): the check sits in `run()`,
16+
* before the standalone stack replaces the authored list.
17+
*/
18+
19+
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
20+
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
21+
import { tmpdir } from 'node:os';
22+
import { join } from 'node:path';
23+
import { runServe } from './helpers/serve-process.js';
24+
25+
/** Either terminal outcome: the complete ready banner, or the refusal line. */
26+
const SETTLED = /Press Ctrl\+C to stop|Refusing to boot/;
27+
const REFUSED = /Refusing to boot/;
28+
29+
const OBJECT = `objects: [{ name: 'csa_probe', label: 'Probe', fields: { title: { type: 'text', label: 'Title' } } }],`;
30+
31+
const CONFIGS = {
32+
unresolvable: `export default {
33+
plugins: ['@acme/not-installed-crypto-provider'],
34+
${OBJECT}
35+
};
36+
`,
37+
declaring: `export default {
38+
plugins: [{ name: 'com.acme.kms-crypto-provider', version: '1.0.0', providesServices: ['crypto-provider'] }],
39+
${OBJECT}
40+
};
41+
`,
42+
otherService: `export default {
43+
plugins: [{ name: 'com.acme.widgets', version: '1.0.0', providesServices: ['acme-widgets'] }],
44+
${OBJECT}
45+
};
46+
`,
47+
noPlugins: `export default {
48+
${OBJECT}
49+
};
50+
`,
51+
} as const;
52+
53+
const dirs: Partial<Record<keyof typeof CONFIGS, string>> = {};
54+
55+
beforeAll(() => {
56+
for (const [key, config] of Object.entries(CONFIGS) as Array<[keyof typeof CONFIGS, string]>) {
57+
const dir = mkdtempSync(join(tmpdir(), `os-crypto-plugin-set-aside-${key}-`));
58+
writeFileSync(join(dir, 'objectstack.config.ts'), config, 'utf8');
59+
dirs[key] = dir;
60+
}
61+
});
62+
63+
afterAll(() => {
64+
for (const dir of Object.values(dirs)) if (dir) rmSync(dir, { recursive: true, force: true });
65+
});
66+
67+
const boot = async (key: keyof typeof CONFIGS) => {
68+
const run = await runServe(dirs[key]!, [], { waitFor: SETTLED, timeoutMs: 150_000 });
69+
return { ...run, output: run.stdout + run.stderr };
70+
};
71+
72+
describe('os serve — a plugins entry the standalone boot sets aside and that may provide the crypto provider', () => {
73+
it('a specifier that does not import: the boot is refused, naming it', async () => {
74+
const { output, port } = await boot('unresolvable');
75+
expect(output, output).toMatch(REFUSED);
76+
expect(output).toContain('@acme/not-installed-crypto-provider');
77+
expect(output).toContain("'crypto-provider'");
78+
expect(port, 'a refused boot binds nothing').toBeUndefined();
79+
}, 180_000);
80+
81+
it('an entry that declares the crypto provider: the boot is refused, naming it', async () => {
82+
const { output, port } = await boot('declaring');
83+
expect(output, output).toMatch(REFUSED);
84+
expect(output).toContain('com.acme.kms-crypto-provider');
85+
expect(output).toContain("'crypto-provider'");
86+
expect(port).toBeUndefined();
87+
}, 180_000);
88+
89+
it('CONTROL: an entry that declares another service: the boot goes on', async () => {
90+
const { output, port } = await boot('otherService');
91+
expect(output, output).not.toMatch(REFUSED);
92+
expect(port).toBeGreaterThan(0);
93+
}, 180_000);
94+
95+
it('CONTROL: a stack with no plugins boots', async () => {
96+
const { output, port } = await boot('noPlugins');
97+
expect(output, output).not.toMatch(REFUSED);
98+
expect(port).toBeGreaterThan(0);
99+
}, 180_000);
100+
});

0 commit comments

Comments
 (0)