Skip to content

Commit 470339e

Browse files
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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
'@objectstack/cli': patch
3+
---
4+
5+
feat(cli)!: a declared multi-replica `os start` on the redis cluster driver refuses to boot without `OS_AUTH_SECRET`, instead of minting a sign-in secret of its own on each replica
6+
7+
Clause-②: no (narrowing)
8+
Metadata-protocol: none
9+
10+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no stored row changes shape: what moves is whether `os start` generates a sign-in secret at boot for one deployment topology, and the refusal is a boot-time error that names its own remedy. Nothing at rest records the choice, so there is nothing for a migration to rewrite. -->
11+
12+
**BREAKING** for a deployment that declares several replicas (`OS_EXPECT_MULTI_NODE=true` or `OS_CLUSTER_REPLICAS` above 1) over the redis cluster driver (`OS_CLUSTER_DRIVER=redis`) and sets no `OS_AUTH_SECRET`. `os start` used to generate a sign-in secret into each replica's own `<home>/auth-secret`, so a session signed on one replica was refused on the others. It now exits 1 before generating anything, with one line naming `OS_AUTH_SECRET` and how to generate it.
13+
14+
The fix: generate one value and set the same `OS_AUTH_SECRET` on every replica, e.g. `OS_AUTH_SECRET=$(openssl rand -hex 32)`. A deployment that ran on a generated secret keeps its users' sessions by setting `OS_AUTH_SECRET` to the contents of the `auth-secret` file one replica already holds.
15+
16+
Unchanged: a single node (no replica declaration) keeps generating and reusing `<home>/auth-secret` exactly as before, on any cluster driver; a replica declaration over any other cluster driver keeps its current boot; and an `OS_AUTH_SECRET` (or its legacy names, or `--auth-secret`) set on every replica boots as before.

‎content/docs/deployment/cli.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -566,7 +566,7 @@ os start
566566
| `-d, --database <url>` | `OS_DATABASE_URL` | `file:…` / `:memory:` / `libsql://` / `postgres://` / `mongodb://` |
567567
| `--database-driver <kind>` | `OS_DATABASE_DRIVER` | Force `sqlite` \| `sqlite-wasm` \| `turso` \| `postgres` \| `mysql` \| `mongodb` when the URL is ambiguous |
568568
| `--database-auth-token <token>` | `OS_DATABASE_AUTH_TOKEN` | Auth token for libsql/Turso |
569-
| `--auth-secret <secret>` | `OS_AUTH_SECRET` / `AUTH_SECRET` | Secret for `@objectstack/plugin-auth`. If neither the flag nor the env var is set, `os start` **auto-generates one** and persists it at `<home>/auth-secret` |
569+
| `--auth-secret <secret>` | `OS_AUTH_SECRET` / `AUTH_SECRET` | Secret for `@objectstack/plugin-auth`. If neither the flag nor the env var is set, `os start` **auto-generates one** and persists it at `<home>/auth-secret` — except on a deployment that declares several replicas (`OS_EXPECT_MULTI_NODE=true` / `OS_CLUSTER_REPLICAS` > 1) over the redis cluster driver, where it refuses to start and names the variable |
570570
| `--home <dir>` | `OS_HOME` | Home directory for persistent state (default `<cwd>/.objectstack` when an `objectstack.config.ts` is present, otherwise `~/.objectstack`) |
571571
| `--environment-id <id>` | `OS_ENVIRONMENT_ID` | Environment identifier (default `env_local`) |
572572
| `-p, --port <port>` | `OS_PORT` / `PORT` | Listen port (default `3000`). **Production fails loudly if the port is busy** — see note below. |
@@ -618,7 +618,12 @@ as the project's **default** datasource it is refused at boot the same way.
618618
`AUTH_SECRET` env > a secret **auto-generated and persisted** at `<home>/auth-secret`
619619
on first run — so `/api/v1/auth/*` (login/register) and the Console's login flow work
620620
out of the box, without any manual secret provisioning. Set the env var (or flag)
621-
explicitly when you deploy across multiple nodes or want to rotate the secret.
621+
explicitly when you deploy across multiple nodes or want to rotate the secret: the same
622+
value on every replica. A start that declares several replicas
623+
(`OS_EXPECT_MULTI_NODE=true` / `OS_CLUSTER_REPLICAS` > 1) over the redis cluster driver
624+
does not generate one: without the variable it exits 1 on one line naming
625+
`OS_AUTH_SECRET` and how to generate it (`openssl rand -hex 32`), because each replica
626+
would otherwise mint its own and a session signed on one would be refused on the others.
622627
623628
<Callout type="info">
624629
**`os start` vs `os serve`:** `os serve` boots from `objectstack.config.ts` (TypeScript source).

‎content/docs/deployment/self-hosting.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ workable default:
3434
| Variable | Why it must be set |
3535
|:---|:---|
3636
| `OS_DATABASE_URL` | Without it, data lands in a SQLite file under the ObjectStack home directory (`~/.objectstack`, or `<cwd>/.objectstack` next to a project config) — fine for one box, wrong for containers. Use `postgres://…`, `mysql://…`, `mongodb://…`, `libsql://…`, or a mounted `file:…` path (`postgres://…`'s driver is an **optional** package too — `npm install pg`, or the boot fails loudly rather than degrading to SQLite; `libsql://` / Turso is inferred, but its driver is an **optional** package — `npm install @objectstack/driver-turso`, or the boot fails loudly rather than degrading to SQLite; see [Drivers](/docs/data-modeling/drivers)). `mysql://…` is a supported deployment target that carries three dialect caveats — two of them integrity guarantees MySQL cannot enforce at the database — see [Drivers → MySQL dialect caveats](/docs/data-modeling/drivers#mysql-dialect-caveats) before choosing it; its driver is likewise an **optional** package — `npm install mysql2`, or the boot fails loudly rather than degrading to SQLite. `mongodb://…` is **single-tenant only**: the MongoDB driver has no row-level tenant isolation and refuses to boot unless the tenancy posture is `single` — see [Drivers → Multi-tenancy](/docs/data-modeling/drivers#multi-tenancy-not-supported). |
37-
| `OS_AUTH_SECRET` | Session secret for the auth plugin (`AUTH_SECRET` is the legacy alias). Without it, `os start` generates one and keeps it in `auth-secret` under the ObjectStack home directory, reused on restart: lose that file (a replaced container) and everyone is signed out. |
37+
| `OS_AUTH_SECRET` | Session secret for the auth plugin (`AUTH_SECRET` is the legacy alias). Without it, `os start` generates one and keeps it in `auth-secret` under the ObjectStack home directory, reused on restart: lose that file (a replaced container) and everyone is signed out. Several replicas declared over the redis cluster driver need one value set on every replica: there `os start` refuses to generate one. |
3838
| `OS_SECRET_KEY` | 32-byte master key encrypting every stored secret (`openssl rand -hex 32`). On a container's ephemeral filesystem the auto-minted key is **lost on restart**, making previously-encrypted secrets undecryptable. |
3939
| `OS_PORT` | `os start` **fails loudly** if the port is busy (it never auto-shifts like `os dev`). Pin it and keep your reverse-proxy upstream in sync. |
4040

‎packages/cli/src/commands/start-deployment-durability.test.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,21 @@
77
*/
88

99
import { describe, expect, it } from 'vitest';
10+
// Paid during collection, never inside a case's clock: `start.ts` loads these
11+
// lazily, and `check:test-source-alias` reads every one it can reach.
12+
import '@objectstack/cloud-connection';
13+
import '@objectstack/runtime';
14+
import '@objectstack/service-settings';
1015
import {
1116
DURABILITY_CHECK_ENV,
1217
INTERNAL_DEPLOYMENT_FINDINGS_ENV,
18+
MULTI_REPLICA_AUTH_SECRET_REFUSAL,
1319
formatDurabilityBootBlock,
1420
formatDurabilityRefusal,
1521
isDefaultedDatabase,
1622
missingDurableVariables,
1723
readDurabilityCheckSignal,
24+
declaresReplicasSharingState,
1825
sqliteFileOf,
1926
writeDeploymentFindingsChannel,
2027
} from './start.js';
@@ -137,3 +144,30 @@ describe('the channel to the server process', () => {
137144
expect(INTERNAL_DEPLOYMENT_FINDINGS_ENV in env).toBe(false);
138145
});
139146
});
147+
148+
describe('a declared multi-replica start on the redis cluster driver mints no sign-in secret of its own', () => {
149+
const asks = (env: Record<string, string | undefined>) => declaresReplicasSharingState(env as NodeJS.ProcessEnv);
150+
151+
it('refuses when several replicas are declared over the redis driver, by either declaration', async () => {
152+
expect(await asks({ OS_CLUSTER_REPLICAS: '3', OS_CLUSTER_DRIVER: 'redis' })).toBe(true);
153+
expect(await asks({ OS_EXPECT_MULTI_NODE: 'true', OS_CLUSTER_DRIVER: ' redis ' })).toBe(true);
154+
});
155+
156+
it('CONTROL: a single node keeps minting, on the redis driver too', async () => {
157+
expect(await asks({})).toBe(false);
158+
expect(await asks({ OS_CLUSTER_DRIVER: 'redis' })).toBe(false);
159+
expect(await asks({ OS_CLUSTER_REPLICAS: '1', OS_CLUSTER_DRIVER: 'redis' })).toBe(false);
160+
});
161+
162+
it('CONTROL: replicas declared over the memory driver, or none named, keep the boot they had', async () => {
163+
expect(await asks({ OS_CLUSTER_REPLICAS: '3', OS_CLUSTER_DRIVER: 'memory' })).toBe(false);
164+
expect(await asks({ OS_CLUSTER_REPLICAS: '3' })).toBe(false);
165+
});
166+
167+
it('the refusal is one line naming OS_AUTH_SECRET and how to generate it, and carries no value', () => {
168+
expect(MULTI_REPLICA_AUTH_SECRET_REFUSAL).not.toContain('\n');
169+
expect(MULTI_REPLICA_AUTH_SECRET_REFUSAL).toMatch(/^\[auth\] Refusing to start: several replicas are declared/);
170+
expect(MULTI_REPLICA_AUTH_SECRET_REFUSAL).toContain('but OS_AUTH_SECRET is not set');
171+
expect(MULTI_REPLICA_AUTH_SECRET_REFUSAL).toContain('set the same value on every replica, e.g. OS_AUTH_SECRET=$(openssl rand -hex 32)');
172+
});
173+
});

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -364,6 +364,19 @@ export default class Start extends Command {
364364
}
365365
}
366366

367+
// ── A declared multi-replica deployment shares ONE sign-in secret ──────
368+
// Minting one below is right for a single node and wrong for replicas:
369+
// each mints its own into its own home, and a session signed on one is
370+
// refused on the others. Asked only when the operator set none, and before
371+
// anything is generated, so the refusal writes no secret.
372+
if (
373+
(operatorAuthSecret === undefined || operatorAuthSecret.trim().length === 0)
374+
&& await declaresReplicasSharingState(process.env)
375+
) {
376+
process.stderr.write(`${MULTI_REPLICA_AUTH_SECRET_REFUSAL}\n`);
377+
process.exit(1);
378+
}
379+
367380
const persistedAuthSecret = operatorAuthSecret === undefined ? readOrCreateAuthSecret(homeDir) : undefined;
368381
const authSecret = persistedAuthSecret ? persistedAuthSecret.secret : operatorAuthSecret;
369382

@@ -674,6 +687,39 @@ export async function resolveStartDatabase(opts: {
674687
});
675688
}
676689

690+
/**
691+
* Whether this deployment runs replicas that share state, so must share one
692+
* sign-in secret too: several replicas declared (`OS_EXPECT_MULTI_NODE=true` /
693+
* `OS_CLUSTER_REPLICAS` > 1, the split-brain guard's `declaresMultiNode`) over
694+
* the redis cluster driver. Both are required, the rule every multi-replica
695+
* change keeps (cloud#3814 R3): a single node keeps minting into
696+
* `<home>/auth-secret`, and a declaration over any other driver keeps the boot
697+
* it had.
698+
*
699+
* ⛔ Not a second copy of that rule. It is asked of the one pre-boot form that
700+
* exists, `sharesCloudBindingCredential` (`OS_CLUSTER_DRIVER` in place of the
701+
* cluster service's driver, trimmed as the `serve` child trims it before
702+
* composing that service), from a package this command already declares. The
703+
* CLI declares no cluster package of its own: those ship with the host app
704+
* (`serve-cluster-host-resolution.test.ts` says why). Lazy, so oclif's
705+
* import-every-command startup does not pay for it.
706+
*/
707+
export async function declaresReplicasSharingState(env: NodeJS.ProcessEnv): Promise<boolean> {
708+
const { sharesCloudBindingCredential } = await import('@objectstack/cloud-connection');
709+
return sharesCloudBindingCredential(env, env.OS_CLUSTER_DRIVER);
710+
}
711+
712+
/**
713+
* The refusal, one line in the data key's shape (`LocalCryptoProvider`): what
714+
* is missing, what minting one would break, and how to generate the value.
715+
* It names the variable and never a value.
716+
*/
717+
export const MULTI_REPLICA_AUTH_SECRET_REFUSAL =
718+
'[auth] Refusing to start: several replicas are declared (OS_EXPECT_MULTI_NODE / OS_CLUSTER_REPLICAS>1) ' +
719+
'over the redis cluster driver, but OS_AUTH_SECRET is not set — each replica would mint its own sign-in ' +
720+
'secret, and a session signed on one would be refused on the others. Fix: generate one and set the same ' +
721+
'value on every replica, e.g. OS_AUTH_SECRET=$(openssl rand -hex 32)';
722+
677723
/**
678724
* Read the persisted AUTH_SECRET from `<home>/auth-secret`, or generate
679725
* one on first run and persist it so subsequent restarts keep existing

‎packages/cli/test/start-deployment-durability.integration.test.ts‎

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2-
// test-budget: 40 — three refusals that exit before any server starts, then two real `os start` boots (one on explicit settings; one on the defaults, which also signs up an owner, creates a member and reads the notice as each); the file read 27.6 s on a shared local box (no CI reading yet) x 1.25, rounded up to the next 10 s
2+
// test-budget: 40 — six starts that exit before any server answers (three image refusals; the multi-replica refusal, its pass and its memory-driver control), then two real `os start` boots (one on explicit settings; one on the defaults, which also signs up an owner, creates a member and reads the notice as each); the file read 27.6 s on a shared local box (no CI reading yet) x 1.25, rounded up to the next 10 s, and 26.9 s with the three multi-replica starts added
33

44
/**
55
* #30120, ruling A3 (record 6634240777) — the official image refuses to start
@@ -29,6 +29,12 @@
2929
* member is refused `403`, and neither the public auth config nor the
3030
* runtime config carries any of it.
3131
*
32+
* And, beside the image's refusal (#31600): a start that declares several
33+
* replicas over the redis cluster driver and sets no `OS_AUTH_SECRET` exits 1
34+
* on one line naming it, before it generates a secret; with the secret set it
35+
* passes, and replicas declared over the memory driver still generate one.
36+
* The single-node default keeps generating its own: leg 3 reads that file.
37+
*
3238
* The hide's audit row and the route's other refusals are pinned beside the
3339
* routes (`service-settings` `deployment-notice.routes.test.ts`).
3440
*
@@ -106,6 +112,10 @@ function baseEnv(home: string, over: Record<string, string | undefined> = {}): R
106112
AUTH_SECRET: undefined,
107113
BETTER_AUTH_SECRET: undefined,
108114
OS_CLUSTER_DRIVER: undefined,
115+
OS_EXPECT_MULTI_NODE: undefined,
116+
OS_CLUSTER_REPLICAS: undefined,
117+
OS_ALLOW_MEMORY_CLUSTER_MULTINODE: undefined,
118+
OS_REDIS_URL: undefined,
109119
OS_MODE: undefined,
110120
OS_PORT: undefined,
111121
PORT: undefined,
@@ -292,6 +302,59 @@ describe('#30120 — with the image switch on, a start missing its settings refu
292302
});
293303
});
294304

305+
// ---------------------------------------------------------------------------
306+
// 1b — several replicas declared over the redis cluster driver: no secret of its own
307+
// ---------------------------------------------------------------------------
308+
309+
describe('#31600 — a declared multi-replica start on the redis cluster driver mints no sign-in secret of its own', () => {
310+
// The data key is set on every leg, so the only thing each leg varies is the
311+
// sign-in secret and the topology. No leg needs a Redis: the door is asked in
312+
// `os start` itself, before the `serve` child composes any cluster driver.
313+
// Each leg is one synchronous `os start`, bounded by the spawn's own 120 s;
314+
// the two that reach the `serve` child read ~4 s locally, past vitest's
315+
// default 5 s per test on a loaded runner, so the leg carries the spawn's bound.
316+
const SPAWN_TIMEOUT_MS = 120_000;
317+
const LEG_TIMEOUT_MS = SPAWN_TIMEOUT_MS + 10_000;
318+
const start = (over: Record<string, string | undefined>) => {
319+
const home = tmp('os-31600-home-');
320+
const cwd = tmp('os-31600-cwd-');
321+
const run = spawnSync(process.execPath, [CLI, 'start', '--port', KERNEL_ASSIGNED_PORT], {
322+
cwd,
323+
env: childEnv({ ...baseEnv(home, { OS_SECRET_KEY: secret(), ...over }), NODE_ENV: undefined }),
324+
encoding: 'utf8',
325+
timeout: SPAWN_TIMEOUT_MS,
326+
});
327+
const minted = [...filesUnder(home), ...filesUnder(cwd)].filter((f) => /(^|\/)auth-secret$/.test(f));
328+
return { run, minted, out: `${run.stdout}\n${run.stderr}` };
329+
};
330+
const REFUSAL = /^\[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/m;
331+
332+
it('OS_AUTH_SECRET unset: exit 1 on the one line, before any secret is written', () => {
333+
const { run, minted, out } = start({ OS_CLUSTER_REPLICAS: '3', OS_CLUSTER_DRIVER: 'redis' });
334+
expect(run.status, out).toBe(1);
335+
expect(run.stderr).toMatch(REFUSAL);
336+
expect(run.stderr).toContain('e.g. OS_AUTH_SECRET=$(openssl rand -hex 32)');
337+
expect(out).not.toMatch(READY);
338+
expect(minted, out).toEqual([]);
339+
}, LEG_TIMEOUT_MS);
340+
341+
it('OS_AUTH_SECRET set: this door passes, and nothing is minted', () => {
342+
const { minted, out } = start({ OS_EXPECT_MULTI_NODE: 'true', OS_CLUSTER_DRIVER: 'redis', OS_AUTH_SECRET: secret() });
343+
expect(out).not.toMatch(REFUSAL);
344+
// The banner is printed after the door: the start went on to its child.
345+
expect(out).toMatch(/Database/);
346+
expect(minted, out).toEqual([]);
347+
}, LEG_TIMEOUT_MS);
348+
349+
it('CONTROL: replicas declared over the memory driver mint a secret exactly as before', () => {
350+
// The child then meets the split-brain guard, today's refusal for this
351+
// topology; the secret is minted in `os start` before that, as it always was.
352+
const { minted, out } = start({ OS_CLUSTER_REPLICAS: '3', OS_CLUSTER_DRIVER: 'memory' });
353+
expect(out).not.toMatch(REFUSAL);
354+
expect(minted, out).toEqual([join('.objectstack', 'auth-secret')]);
355+
}, LEG_TIMEOUT_MS);
356+
});
357+
295358
// ---------------------------------------------------------------------------
296359
// 2 — an explicit file: passes
297360
// ---------------------------------------------------------------------------

0 commit comments

Comments
 (0)