Repository navigation
Commit 470339e
feat(cli)!: a declared multi-replica os start on the redis cluster driver refuses to boot without OS_AUTH_SECRET, instead of minting its own sign-in secret (#31718)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9EaMu5Cnk8LQVwSLuDZCP1u)_
Fixes #31600
Clause-②: no (narrowing) — measured: on base `fc4c3072` an `os start`
declaring several replicas (`OS_EXPECT_MULTI_NODE=true`) over the redis
cluster driver, with `OS_SECRET_KEY` set and no `OS_AUTH_SECRET`, booted
(redis cluster driver and redis cache adapter registered, `Press Ctrl+C
to stop`) and generated `{home}/auth-secret`; on head the same start
exits 1 on the refusal line and generates nothing.
Metadata-protocol: none
Skills-docs: updated here — `content/docs/deployment/cli.mdx` (the
`--auth-secret` row and the Authentication paragraph) and
`content/docs/deployment/self-hosting.mdx` (the `OS_AUTH_SECRET` row) no
longer say `os start` always generates a secret; `skills/**` says
nothing about `os start` generating one on a multi-replica deployment
(its only `OS_AUTH_SECRET` text is the image's durability refusal,
unchanged).
## 维护者速读
- **改了什么**:`os start` 在"声明多副本(`OS_EXPECT_MULTI_NODE=true` 或
`OS_CLUSTER_REPLICAS`>1)且集群驱动是 Redis"时,如果没设
`OS_AUTH_SECRET`,不再自己生成登录密钥,而是直接拒绝启动,打印一行:缺哪个变量、为什么、怎么生成(`openssl rand
-hex 32`),所有副本设同一个值。
- **为什么改**:以前每个副本各自生成一份密钥存在自己的盘上,r1 签发的登录 cookie 到 r3
就失效(卡上的冒烟现象,这里实测复现:两副本密钥不同,r2 不认 r1 的 cookie;密钥相同则两边都认)。
- **风险与回滚**:单节点(没声明多副本)照旧自动生成并复用 `{home}/auth-secret`,任何驱动都一样;声明多副本但驱动不是
Redis 的维持原样(R3:两个条件同时成立才生效)。会被拒绝的只有"多副本 + Redis + 没设密钥"这一种配置,修法就是设密钥。回滚
= revert 本 PR。
- **先看**:① `packages/cli/src/commands/start.ts` 生成密钥之前新加的那一段判断与
`declaresReplicasSharingState`;② 同文件的拒绝文案
`MULTI_REPLICA_AUTH_SECRET_REFUSAL`;③
`packages/cli/test/start-deployment-durability.integration.test.ts`
新增的三条真实 `os start` 用例。
- **两分钟验证**:`pnpm --filter @objectstack/cli exec vitest run
--maxWorkers=2 src/commands/start-deployment-durability.test.ts
test/start-deployment-durability.integration.test.ts`(需先 build CLI),预期
35 passed:其中多副本 + Redis + 无密钥的 `os start` 退出码 1、输出那一行、家目录里没有
`auth-secret`。
- **需要你做的**:无,席位落地。
## What changes
**`os start` refuses to generate a sign-in secret for a declared
multi-replica deployment on the redis cluster driver.** Where the
operator set no secret (`--auth-secret`, `OS_AUTH_SECRET` or its legacy
names unset or blank), `os start` now asks, before it generates
anything, whether the deployment runs replicas that share state. If it
does, it exits 1 on one line, in the data key refusal's shape:
```text
[auth] Refusing to start: several replicas are declared (OS_EXPECT_MULTI_NODE / OS_CLUSTER_REPLICAS>1) over the redis cluster driver, but OS_AUTH_SECRET is not set — each replica would mint its own sign-in secret, and a session signed on one would be refused on the others. Fix: generate one and set the same value on every replica, e.g. OS_AUTH_SECRET=$(openssl rand -hex 32)
```
The line names the variable and never a value. The refusal writes no
secret, so a replica that hits it leaves nothing on its volume.
**Where it lives, measured in step 0.** The only place a sign-in secret
is generated is `os start` itself (`readOrCreateAuthSecret`,
`{home}/auth-secret`; the image's home is the `/data/auth-secret` of the
card). `os serve` never generates one outside development: plugin-auth
refuses a production boot without `OS_AUTH_SECRET`. The data key's
missing-key refusal lives in the `serve` child (`LocalCryptoProvider`),
and `os start` already declines to opt that key into self-minting when
`OS_CLUSTER_DRIVER` is set. The secret is generated in the parent before
the child starts, so the refusal belongs in the parent, at the same
point as the image's durability check, which it follows.
**The predicate is not a second copy.** It is the rule every
multi-replica change keeps (cloud#3814 R3): replicas declared
(`declaresMultiNode`, the split-brain guard's reader) AND the `redis`
cluster driver. PR #31624 applies it in `planCacheAdapter` to the
registered cluster service's driver; its one pre-boot form already
exists as `sharesCloudBindingCredential(env, OS_CLUSTER_DRIVER)` in
`@objectstack/cloud-connection` (it trims the driver the way the `serve`
child does before composing the cluster service). `os start` asks that
function, through a lazy import of a package the CLI already declares. A
first attempt declared `@objectstack/service-cluster` on the CLI to
import `declaresMultiNode` directly;
`serve-cluster-host-resolution.test.ts` refuses that, because cluster
packages ship with the host app and the open-core CLI takes no static
dependency on them, so the dependency was dropped.
**Docs.** `content/docs/deployment/cli.mdx` (the `--auth-secret` row and
the Authentication paragraph) and
`content/docs/deployment/self-hosting.mdx` (the `OS_AUTH_SECRET` row)
said `os start` always generates a secret; they now name the one
topology where it refuses instead.
## Tests
- `packages/cli/src/commands/start-deployment-durability.test.ts`, new
top-level `describe`: the decision on real environments — refused for
`OS_CLUSTER_REPLICAS=3` and for `OS_EXPECT_MULTI_NODE=true` (with a
padded `' redis '`) over redis; CONTROL single node (no declaration,
redis alone, replicas `1`) not refused; CONTROL replicas declared over
`memory` or no driver not refused; the line is one line, starts with the
pinned first sentence, names `OS_AUTH_SECRET` and the generator. The
file also gains three module-top side-effect imports
(`@objectstack/cloud-connection`, `@objectstack/runtime`,
`@objectstack/service-settings`): `check:test-source-alias` asks every
edited test file that reaches a lazy import in its source to pay the
load during collection. Forced test edit, named here.
- `packages/cli/test/start-deployment-durability.integration.test.ts`,
new `describe` at the shipped entry (`bin/run.js` over `dist/`), no
Redis needed because the door is in `os start`: (1) replicas declared
over redis, no secret → exit 1, stderr carries the line, no
`auth-secret` anywhere under home or cwd; (2) the secret set → the door
passes (banner printed after it), nothing generated; (3) CONTROL
replicas declared over `memory` → the secret is generated exactly as
before (`.objectstack/auth-secret`). The single-node CONTROL is the
file's existing leg 3, which reads the generated `auth-secret` file.
Forced test edit, named here: `baseEnv` now also clears
`OS_EXPECT_MULTI_NODE`, `OS_CLUSTER_REPLICAS`,
`OS_ALLOW_MEMORY_CLUSTER_MULTINODE` and `OS_REDIS_URL`, so an inherited
declaration cannot reach the existing legs; the `test-budget` line is
re-read (26.9 s, budget 40 unchanged).
## Acceptance notes
- **The refusal is in `os start` only.** A deployment that runs `os
serve` directly already has to set `OS_AUTH_SECRET` (plugin-auth refuses
production without it), so it never generated a per-replica secret.
- **With the image's durability switch on**, a start missing
`OS_AUTH_SECRET` is refused by that check first (it lists every missing
variable); this line is reached only without the switch or with the
secret check passed.
- **The driver is read as written.** On open core with
`OS_CLUSTER_REPLICAS` > 1 and no multi-node gate registered, the `serve`
child falls back to the memory driver and the split-brain guard refuses
the boot anyway (measured on head with a shared secret set). That
configuration now meets this line first when no secret is set; it never
booted, so no boot is lost. `OS_EXPECT_MULTI_NODE=true` over redis did
boot on base and is the narrowed path.
- **A deployment that already ran on generated secrets** keeps its
sessions by setting `OS_AUTH_SECRET` to one replica's `auth-secret`
contents on every replica; the changeset says so.
## Verification
Local, on head `c96d6e73` unless a line says otherwise. Every exit code
below was captured before any pipe.
<details><summary>Step 0 and the real-Redis readings (redis-server
7.0.15, a probe app declaring the two cluster packages)</summary>
- Base `fc4c3072`, `OS_EXPECT_MULTI_NODE=true OS_CLUSTER_DRIVER=redis
OS_REDIS_URL=… OS_SECRET_KEY=…`, no auth secret: `ClusterServicePlugin:
registered "redis" driver`, `CacheServicePlugin: registered redis cache
adapter`, `Press Ctrl+C to stop`; `{home}/.objectstack/auth-secret`
generated.
- Head, the same environment: exit 1, the refusal line, 0 `auth-secret`
files.
- Head, the same with `OS_AUTH_SECRET` set: redis driver and redis cache
registered, `Press Ctrl+C to stop`, 0 `auth-secret` files.
- Two head replicas on one Redis and one shared SQLite file, one
`OS_AUTH_SECRET`: a cookie signed in on r1 reads the session on r1 and
on r2. The same pair with a different secret each (what base generated):
r1 reads it, r2 does not.
</details>
<details><summary>Tests and the ablation</summary>
- `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2
src/commands/start-deployment-durability.test.ts
test/start-deployment-durability.integration.test.ts
src/commands/serve-cluster-host-resolution.test.ts`: 3 files, 67 passed
(VERDICT command-exit 0).
- CLI unit tier `vitest run --project unit`: 405 files, 5728 passed
(VERDICT command-exit 0). `pnpm --filter @objectstack/cli typecheck`:
VERDICT command-exit 0 (tsc and the test-typecheck ledger, 3 files / 28
errors / 6 pinned signatures unchanged).
- Ablation (the refusal's one return made false, marker
`ABLATION_31600`, through `scripts/ablation-replace.mjs`): mutation
landed (anchor 1 → 0, blob `e9d80387` → `d55df8e4`), CLI rebuilt,
`ablation-dist-preflight` found the marker in 1 built file; 2 failed /
33 passed — the unit case `refuses when several replicas are declared
over the redis driver` (`expected false to be true`) and the spawn case
`OS_AUTH_SECRET unset: exit 1 …` (the child went on to the split-brain
guard instead). Restored: blob == HEAD, `git diff HEAD` empty; rebuilt,
`--absent` over 904 built files and a clean tree; 35/35 passed.
</details>
<details><summary>Derived gates and lint</summary>
`node scripts/pm/dispatch-gates.mjs --commands` derived 99 families on
`c96d6e73`; all 99 ran and exited 0. `check:type-check-debt` first
answered exit 3 (the lock was held by the dogfood run, queue-timeout,
nothing measured) and exited 0 under the lock afterwards. `--ran` with
every exit code recorded: `99 derived famil(ies) accounted for — 99 run,
0 NOT-MEASURED (a DERIVED zero …)`. On the earlier head `fd977a59` (with
the dropped dependency) `check:test-source-alias` was red and named the
three lazy loads the edited test file reaches; the module-top imports
fixed it.
`check-adr-0087-registration`: `1 declared-breaking changeset(s), each
carrying an ADR-0087 disposition` — `[BREAKING+bang+clause-②-narrowing]
not-required (no-migration-prescription)`.
`npx eslint --no-inline-config packages/cli` (the package has no lint
script): exit 0.
</details>
<details><summary>Full dogfood (owed by the narrowing arm)</summary>
On `c96d6e73`: the dependency closure built (`pnpm --filter
'@objectstack/dogfood^...' build`, VERDICT command-exit 0, before the
last two commits; the CLI and every package were rebuilt on `c96d6e73`
by `turbo run build --filter='./packages/**'`, VERDICT command-exit 0),
then `pnpm --filter @objectstack/dogfood test` under the verify lock:
VERDICT command-exit 0, Test Files 440 passed, 3 skipped (443); Tests
3652 passed, 41 skipped (3693). No failure.
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmNwSCrFC9AxLfZsBxf)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: objectstack-fleet[bot] <332303061+objectstack-fleet[bot]@users.noreply.github.com>1 parent cae8d8f commit 470339e
6 files changed
Lines changed: 168 additions & 4 deletions
File tree
- .changeset
- content/docs/deployment
- packages/cli
- src/commands
- test
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
566 | 566 | | |
567 | 567 | | |
568 | 568 | | |
569 | | - | |
| 569 | + | |
570 | 570 | | |
571 | 571 | | |
572 | 572 | | |
| |||
618 | 618 | | |
619 | 619 | | |
620 | 620 | | |
621 | | - | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
622 | 627 | | |
623 | 628 | | |
624 | 629 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
34 | 34 | | |
35 | 35 | | |
36 | 36 | | |
37 | | - | |
| 37 | + | |
38 | 38 | | |
39 | 39 | | |
40 | 40 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
7 | 7 | | |
8 | 8 | | |
9 | 9 | | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
10 | 15 | | |
11 | 16 | | |
12 | 17 | | |
| 18 | + | |
13 | 19 | | |
14 | 20 | | |
15 | 21 | | |
16 | 22 | | |
17 | 23 | | |
| 24 | + | |
18 | 25 | | |
19 | 26 | | |
20 | 27 | | |
| |||
137 | 144 | | |
138 | 145 | | |
139 | 146 | | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
364 | 364 | | |
365 | 365 | | |
366 | 366 | | |
| 367 | + | |
| 368 | + | |
| 369 | + | |
| 370 | + | |
| 371 | + | |
| 372 | + | |
| 373 | + | |
| 374 | + | |
| 375 | + | |
| 376 | + | |
| 377 | + | |
| 378 | + | |
| 379 | + | |
367 | 380 | | |
368 | 381 | | |
369 | 382 | | |
| |||
674 | 687 | | |
675 | 688 | | |
676 | 689 | | |
| 690 | + | |
| 691 | + | |
| 692 | + | |
| 693 | + | |
| 694 | + | |
| 695 | + | |
| 696 | + | |
| 697 | + | |
| 698 | + | |
| 699 | + | |
| 700 | + | |
| 701 | + | |
| 702 | + | |
| 703 | + | |
| 704 | + | |
| 705 | + | |
| 706 | + | |
| 707 | + | |
| 708 | + | |
| 709 | + | |
| 710 | + | |
| 711 | + | |
| 712 | + | |
| 713 | + | |
| 714 | + | |
| 715 | + | |
| 716 | + | |
| 717 | + | |
| 718 | + | |
| 719 | + | |
| 720 | + | |
| 721 | + | |
| 722 | + | |
677 | 723 | | |
678 | 724 | | |
679 | 725 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | | - | |
| 2 | + | |
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
| |||
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
32 | 38 | | |
33 | 39 | | |
34 | 40 | | |
| |||
106 | 112 | | |
107 | 113 | | |
108 | 114 | | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
109 | 119 | | |
110 | 120 | | |
111 | 121 | | |
| |||
292 | 302 | | |
293 | 303 | | |
294 | 304 | | |
| 305 | + | |
| 306 | + | |
| 307 | + | |
| 308 | + | |
| 309 | + | |
| 310 | + | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
| 319 | + | |
| 320 | + | |
| 321 | + | |
| 322 | + | |
| 323 | + | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
| 348 | + | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
| 353 | + | |
| 354 | + | |
| 355 | + | |
| 356 | + | |
| 357 | + | |
295 | 358 | | |
296 | 359 | | |
297 | 360 | | |
| |||
0 commit comments