fix(cli): let single-node os start auto-mint a crypto key (#2236)

Author: baozhoutao

.changeset/os-start-autokey.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/service-settings": patch
+"@objectstack/cli": patch
+---
+
+fix(cli): let single-node `os start` auto-mint a crypto key
+
+`os start` forces `NODE_ENV=production`, which made `LocalCryptoProvider` refuse
+to boot without `OS_SECRET_KEY` — breaking the documented zero-config quickstart
+(`npm i -g @objectstack/cli && os start`) on a clean machine.
+
+`LocalCryptoProvider` now honours an `OS_CRYPTO_AUTOKEY` opt-in in production: it
+mints AND persists a key to `~/.objectstack/dev-crypto-key`. The ephemeral
+fallback stays forbidden, so a non-writable / ephemeral filesystem still fails
+loud rather than running under a key that won't survive a restart. `os start`
+sets the flag only for single-node deployments (no `OS_CLUSTER_DRIVER`, no
+`OS_SECRET_KEY`); multi-node still fails loud until `OS_SECRET_KEY` is provided.

content/docs/guides/cloud-deployment.mdx

@@ -130,11 +130,35 @@ requests and do not run through a target environment kernel.
 | `OS_DATABASE_URL` | Local runtime business database URL. |
 | `OS_DATABASE_DRIVER` | Local runtime driver id. |
 | `OS_AUTH_SECRET` | Better Auth session secret for hosted runtimes. |
+| `OS_SECRET_KEY` | 32-byte master key for `sys_secret` encryption (encrypted settings, `secret` fields, datasource credentials). 64 hex chars or base64 of 32 bytes. |
+| `OS_CLUSTER_DRIVER` | Cluster coordination driver. When set, the runtime treats the deployment as multi-node. |
 | `OS_PORT` | HTTP listen port. |
 
 Third-party provider variables such as `OPENAI_API_KEY`, `TURSO_*`,
 `SMTP_*`, `RESEND_API_KEY`, and OAuth client secrets keep their provider names.
 
+<Callout type="warn">
+**Set `OS_SECRET_KEY` for any containerized or multi-node deployment.** The
+default `LocalCryptoProvider` encrypts every `sys_secret` value under one
+32-byte key. On a single host, `os start` mints and persists that key to
+`~/.objectstack/dev-crypto-key` automatically, so the zero-config quickstart
+just works. But on an **ephemeral filesystem (containers)** the minted key is
+lost on restart, and across **multiple nodes** each node would mint a
+*different* key — in both cases previously-encrypted secrets become
+undecryptable.
+
+Provision one stable key shared by every node and every restart:
+
+```bash
+OS_SECRET_KEY=$(openssl rand -hex 32)
+```
+
+When `OS_CLUSTER_DRIVER` is set (multi-node), `os start` will **not** auto-mint
+a key — it fails loud at boot until `OS_SECRET_KEY` is provided, rather than
+silently running under a key that won't survive. For production, prefer a
+managed KMS / Vault provider behind the same `ICryptoProvider` seam.
+</Callout>
+
 ---
 
 ## Related

packages/cli/src/commands/start.ts

@@ -237,6 +237,17 @@ export default class Start extends Command {
     // Allows `NODE_ENV=development objectstack start` to work for debugging.
     if (!localEnv.NODE_ENV) localEnv.NODE_ENV = 'production';
 
+    // Single-node self-host quickstart: forcing production above would make
+    // LocalCryptoProvider refuse to boot without OS_SECRET_KEY, breaking the
+    // documented zero-config `os start`. Opt the crypto provider into minting
+    // + persisting a key file (~/.objectstack/dev-crypto-key) so it works out
+    // of the box. A multi-node deploy (OS_CLUSTER_DRIVER set) must provision a
+    // shared OS_SECRET_KEY instead — each node minting its own key would
+    // diverge — so we do NOT opt in there; the provider still fails loud.
+    if (!localEnv.OS_CLUSTER_DRIVER && !localEnv.OS_SECRET_KEY) {
+      localEnv.OS_CRYPTO_AUTOKEY = '1';
+    }
+
     const binPath = process.argv[1];
     const child = spawn(
       process.execPath,

packages/services/service-settings/src/local-crypto-provider.test.ts

@@ -80,6 +80,26 @@ describe('LocalCryptoProvider — key resolution', () => {
     expect(existsSync(keyPath)).toBe(false);
   });
 
+  it('mints + persists a key in production when OS_CRYPTO_AUTOKEY is set (os start quickstart)', async () => {
+    const env = { NODE_ENV: 'production', HOME: home, OS_CRYPTO_AUTOKEY: '1' };
+    const a = new LocalCryptoProvider({ env });
+    expect(a.keySource).toBe('generated-file');
+    const h = await a.encrypt('quickstart-secret', ctx);
+    // A fresh instance reads the persisted file and decrypts prior ciphertext.
+    const b = new LocalCryptoProvider({ env });
+    expect(b.keySource).toBe('file');
+    expect(await b.decrypt(h, ctx)).toBe('quickstart-secret');
+  });
+
+  it('still fails loud with OS_CRYPTO_AUTOKEY when the key cannot be persisted', () => {
+    // Point HOME at a path under a regular *file* so mkdir/write fails — the
+    // opt-in must NOT degrade to an ephemeral key in production.
+    const blocker = join(home, 'not-a-dir');
+    writeFileSync(blocker, 'x');
+    const env = { NODE_ENV: 'production', OS_HOME: join(blocker, 'nested'), OS_CRYPTO_AUTOKEY: '1' };
+    expect(() => new LocalCryptoProvider({ env })).toThrow(/Refusing to start in production/);
+  });
+
   it('auto-creates + persists a key in development', async () => {
     const env = { NODE_ENV: 'development', HOME: home };
     const a = new LocalCryptoProvider({ env });

packages/services/service-settings/src/local-crypto-provider.ts

@@ -28,7 +28,9 @@ import { dirname, join } from 'node:path';
  *   4. Persisted file                 — `~/.objectstack/dev-crypto-key`
  *                                       (mode 0600). In development it is
  *                                       auto-created; in production it is
- *                                       only *read* (never minted).
+ *                                       only *read* unless `OS_CRYPTO_AUTOKEY`
+ *                                       opts the single-node self-host case
+ *                                       into minting + persisting it too.
  *   5. Ephemeral random key           — development/test only.
  *
  * ## Fail-loud guarantee (the reason this class exists)
@@ -46,9 +48,13 @@ import { dirname, join } from 'node:path';
  * To turn that silent data-loss into a config error at boot, the provider
  * REFUSES to mint a key in production: when `mode === 'production'` and no
  * stable key source (env var or pre-existing key file) is available, the
- * constructor throws an actionable error instead of generating one.
- * Development and test keep the ergonomic fallback so local loops and unit
- * tests stay frictionless.
+ * constructor throws an actionable error instead of generating one. The one
+ * exception is the `OS_CRYPTO_AUTOKEY` opt-in: a single-node self-host
+ * (`os start` on a durable filesystem) may mint + *persist* a key so the
+ * zero-config quickstart boots — but even then the ephemeral fallback stays
+ * forbidden, so a non-writable / ephemeral FS still fails loud rather than
+ * running under a key that won't survive a restart. Development and test keep
+ * the ergonomic fallback so local loops and unit tests stay frictionless.
  *
  * `mode` is auto-detected from `NODE_ENV` (`production` → strict;
  * `test`/`VITEST` → ephemeral, no disk; otherwise `development`) and can be
@@ -77,6 +83,14 @@ import { dirname, join } from 'node:path';
 const SECRET_KEY_ENV = 'OS_SECRET_KEY';
 const DEV_KEY_ENV = 'OS_DEV_CRYPTO_KEY';
 const DEV_KEY_LEGACY_ENV = 'OBJECTSTACK_DEV_CRYPTO_KEY';
+/**
+ * Opt-in that lets the strict production path mint + PERSIST a key (but never
+ * fall back to an ephemeral one). Set by `os start` for the single-node
+ * self-host quickstart so the documented zero-config boot works out of the
+ * box, while a real cluster deploy (which must provision `OS_SECRET_KEY`)
+ * leaves it unset and keeps the fail-loud guarantee. See `commands/start.ts`.
+ */
+const AUTOKEY_ENV = 'OS_CRYPTO_AUTOKEY';
 
 type EnvMap = Record<string, string | undefined>;
 
@@ -156,6 +170,12 @@ const parseKey = (raw: string | undefined): Buffer | undefined => {
   return undefined;
 };
 
+/** Truthy env flag: `1` / `true` / `yes` (case-insensitive). */
+const parseBool = (raw: string | undefined): boolean => {
+  const v = raw?.trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes';
+};
+
 /** Read an existing key file (no creation). Returns `undefined` on miss / IO error. */
 const loadExistingKey = (path: string): Buffer | undefined => {
   try {
@@ -255,9 +275,7 @@ function resolveDataKey(opts: LocalCryptoProviderOptions): ResolvedKey {
   const path = keyFilePath(env);
 
   if (mode === 'production') {
-    // Honour a pre-existing, operator-provisioned key file, but NEVER mint
-    // one here — auto-generation is the silent-data-loss footgun this guard
-    // exists to prevent.
+    // Honour a pre-existing, operator-provisioned key file first.
     const existing = loadExistingKey(path);
     if (existing) {
       warn(
@@ -266,6 +284,30 @@ function resolveDataKey(opts: LocalCryptoProviderOptions): ResolvedKey {
       );
       return { key: existing, source: 'file' };
     }
+
+    // Single-node self-host opt-in (`os start` on a durable filesystem): mint
+    // a key AND persist it so the zero-config quickstart boots. We still
+    // REFUSE the ephemeral fallback below — if the key cannot be written
+    // (read-only / ephemeral FS), running anyway would silently lose every
+    // sys_secret on the next restart, the exact footgun this guard prevents.
+    // Multi-node deploys must NOT opt in (each node would mint a divergent
+    // key); `os start` only sets the flag when no cluster driver is set.
+    if (parseBool(env[AUTOKEY_ENV])) {
+      const persisted = loadOrCreateKey(path);
+      if (persisted) {
+        if (persisted.generated) {
+          warn(
+            `[LocalCryptoProvider] No ${SECRET_KEY_ENV} set — minted a new AES-256-GCM key and ` +
+              `persisted it to ${path} (mode 0600). Restarts on this host reuse it automatically. ` +
+              `For containers, CI, or multi-node, set ${SECRET_KEY_ENV} so every node shares one key.`,
+          );
+        }
+        return { key: persisted.key, source: persisted.generated ? 'generated-file' : 'file' };
+      }
+      // Persist failed → fall through to the hard error. Never run ephemeral
+      // in production, even with the opt-in.
+    }
+
     throw new Error(MISSING_PROD_KEY_MSG(path));
   }