@objectstack/service-settings 7.5.0 → 7.7.0

package/README.md

@@ -32,10 +32,44 @@ true` and writes (service or REST) fail with HTTP 409.
 
 ## Encryption
 
-`Specifier.encrypted: true` (implicit for `password`) round-trips the
-value through a pluggable `CryptoAdapter`. The default
-`NoopCryptoAdapter` is a base64 wrapper — production deployments must
-provide a real KMS adapter via plugin options.
+`Specifier.encrypted: true` (implicit for `password`) routes the value
+through a pluggable `ICryptoProvider` into `sys_secret`; only an opaque
+handle id lands in `sys_setting.value_enc`. The same provider backs every
+secret-at-rest in the platform: encrypted settings, ObjectQL `secret`
+fields, and runtime datasource credentials.
+
+### Default provider: `LocalCryptoProvider`
+
+The default is `LocalCryptoProvider` — AES-256-GCM keyed off a single
+32-byte data key. It resolves its key in order:
+
+1. **`OS_SECRET_KEY`** — the canonical production master key (32-byte hex
+   or base64). Set this in any container / multi-node deployment.
+   Generate one with `openssl rand -hex 32`. It **must be identical**
+   across every restart and every node, or previously-encrypted secrets
+   become undecryptable.
+2. `OS_DEV_CRYPTO_KEY` — dev convenience key (same format).
+3. A persisted file at `~/.objectstack/dev-crypto-key` (mode 0600). In
+   development this is auto-created so single-host dev loops survive
+   restarts; in production it is only *read*, never minted.
+
+**Fail-loud in production.** When `NODE_ENV=production` and no stable key
+source (env var or pre-existing file) is available, the provider refuses
+to start with an actionable error instead of silently generating an
+ephemeral key. This turns the old silent-data-loss footgun — every
+`sys_secret` value becoming undecryptable after a container restart or on
+a second node — into a config error at boot.
+
+Secrets surviving a restart is **correctness, not a premium feature**, so
+`LocalCryptoProvider` and the env-key path are open-source. KMS / Vault
+providers (managed custody, per-tenant keys, automatic rotation) plug in
+behind the same `ICryptoProvider` seam via `cryptoProvider` plugin option.
+
+> `InMemoryCryptoProvider` is a deprecated alias for `LocalCryptoProvider`
+> (the old name wrongly implied an ephemeral key).
+
+The legacy `CryptoAdapter` / `NoopCryptoAdapter` (a base64 wrapper) remains
+only as a pre-Phase-3 backward-compat path when no `cryptoProvider` is wired.
 
 ## Audit
 

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   InMemoryCryptoProvider: () => InMemoryCryptoProvider,
+  LocalCryptoProvider: () => LocalCryptoProvider,
   NoopCryptoAdapter: () => NoopCryptoAdapter,
   SETTINGS_PLUGIN_ID: () => SETTINGS_PLUGIN_ID,
   SETTINGS_PLUGIN_VERSION: () => SETTINGS_PLUGIN_VERSION,
@@ -631,36 +632,25 @@ function coerceEnvValue(raw, hint) {
   return raw;
 }
 
-// src/in-memory-crypto-provider.ts
-var import_types = require("@objectstack/types");
+// src/local-crypto-provider.ts
 var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
 var import_node_os = require("os");
 var import_node_path = require("path");
+var SECRET_KEY_ENV = "OS_SECRET_KEY";
 var DEV_KEY_ENV = "OS_DEV_CRYPTO_KEY";
 var DEV_KEY_LEGACY_ENV = "OBJECTSTACK_DEV_CRYPTO_KEY";
-var devKeyFallbackPath = () => {
-  const proc = globalThis?.process;
-  const home = (0, import_types.readEnvWithDeprecation)("OS_HOME", "OBJECTSTACK_HOME") || (proc?.env?.HOME ? (0, import_node_path.join)(proc.env.HOME, ".objectstack") : void 0) || (0, import_node_path.join)((0, import_node_os.homedir)(), ".objectstack");
-  return (0, import_node_path.join)(home, "dev-crypto-key");
+var processEnv = () => globalThis.process?.env ?? {};
+var detectMode = (env) => {
+  if (env.VITEST || env.NODE_ENV === "test") return "test";
+  if (env.NODE_ENV === "production") return "production";
+  return "development";
 };
-var loadOrCreateDevKey = () => {
-  try {
-    const path = devKeyFallbackPath();
-    if ((0, import_node_fs.existsSync)(path)) {
-      const raw = (0, import_node_fs.readFileSync)(path, "utf8").trim();
-      const parsed = parseDevKey(raw);
-      if (parsed) return { key: parsed, path, generated: false };
-    }
-    const key = (0, import_node_crypto.randomBytes)(32);
-    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(path), { recursive: true });
-    (0, import_node_fs.writeFileSync)(path, key.toString("base64"), { mode: 384 });
-    return { key, path, generated: true };
-  } catch {
-    return void 0;
-  }
+var keyFilePath = (env) => {
+  const home = env.OS_HOME || env.OBJECTSTACK_HOME || (env.HOME ? (0, import_node_path.join)(env.HOME, ".objectstack") : void 0) || (0, import_node_path.join)((0, import_node_os.homedir)(), ".objectstack");
+  return (0, import_node_path.join)(home, "dev-crypto-key");
 };
-var parseDevKey = (raw) => {
+var parseKey = (raw) => {
   if (!raw) return void 0;
   const trimmed = raw.trim();
   if (!trimmed) return void 0;
@@ -671,11 +661,99 @@ var parseDevKey = (raw) => {
     if (buf.length === 32) return buf;
   } catch {
   }
-  console.warn(
-    `[InMemoryCryptoProvider] ${DEV_KEY_ENV} is set but is not 32 bytes (hex or base64). Ignoring and generating an ephemeral key.`
-  );
   return void 0;
 };
+var loadExistingKey = (path) => {
+  try {
+    if (!(0, import_node_fs.existsSync)(path)) return void 0;
+    return parseKey((0, import_node_fs.readFileSync)(path, "utf8").trim());
+  } catch {
+    return void 0;
+  }
+};
+var loadOrCreateKey = (path) => {
+  try {
+    const existing = loadExistingKey(path);
+    if (existing) return { key: existing, generated: false };
+    const key = (0, import_node_crypto.randomBytes)(32);
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(path), { recursive: true });
+    (0, import_node_fs.writeFileSync)(path, key.toString("base64"), { mode: 384 });
+    return { key, generated: true };
+  } catch {
+    return void 0;
+  }
+};
+var INVALID_KEY_MSG = (name) => `[LocalCryptoProvider] ${name} is set but is not a 32-byte key (expected 64 hex chars or base64 of 32 bytes). Generate one with \`openssl rand -hex 32\`.`;
+var MISSING_PROD_KEY_MSG = (path) => `[LocalCryptoProvider] Refusing to start in production without a stable encryption key.
+  No ${SECRET_KEY_ENV} (or ${DEV_KEY_ENV}) is set and no persisted key file was found at:
+    ${path}
+  Minting a key here would make every sys_secret value (encrypted settings, secret
+  fields, datasource credentials) undecryptable after the next restart or on another node.
+  Fix: generate a 32-byte key and set it in the environment (identical across every
+  restart and every node), e.g.
+    ${SECRET_KEY_ENV}=$(openssl rand -hex 32)`;
+var warn = (msg) => {
+  try {
+    globalThis.console?.warn?.(msg);
+  } catch {
+  }
+};
+var legacyDeprecationWarned = { value: false };
+function resolveDataKey(opts) {
+  if (opts.key) return { key: opts.key, source: "explicit" };
+  const env = opts.env ?? processEnv();
+  const mode = opts.mode ?? detectMode(env);
+  if (env[SECRET_KEY_ENV] !== void 0) {
+    const parsed = parseKey(env[SECRET_KEY_ENV]);
+    if (parsed) return { key: parsed, source: "env:OS_SECRET_KEY" };
+    throw new Error(INVALID_KEY_MSG(SECRET_KEY_ENV));
+  }
+  let devRaw = env[DEV_KEY_ENV];
+  if (devRaw === void 0 && env[DEV_KEY_LEGACY_ENV] !== void 0) {
+    devRaw = env[DEV_KEY_LEGACY_ENV];
+    if (!legacyDeprecationWarned.value) {
+      legacyDeprecationWarned.value = true;
+      warn(
+        `[ObjectStack] Env var \`${DEV_KEY_LEGACY_ENV}\` is deprecated; rename it to \`${DEV_KEY_ENV}\`.`
+      );
+    }
+  }
+  if (devRaw !== void 0) {
+    const parsed = parseKey(devRaw);
+    if (parsed) return { key: parsed, source: "env:OS_DEV_CRYPTO_KEY" };
+    if (mode === "production") throw new Error(INVALID_KEY_MSG(DEV_KEY_ENV));
+    warn(`${INVALID_KEY_MSG(DEV_KEY_ENV)} Ignoring and generating a local key.`);
+  }
+  if (mode === "test") {
+    return { key: (0, import_node_crypto.randomBytes)(32), source: "ephemeral" };
+  }
+  const path = keyFilePath(env);
+  if (mode === "production") {
+    const existing = loadExistingKey(path);
+    if (existing) {
+      warn(
+        `[LocalCryptoProvider] No ${SECRET_KEY_ENV} set \u2014 using the persisted key at ${path}. For containers / multi-node, prefer setting ${SECRET_KEY_ENV} so every node shares one key.`
+      );
+      return { key: existing, source: "file" };
+    }
+    throw new Error(MISSING_PROD_KEY_MSG(path));
+  }
+  const persisted = loadOrCreateKey(path);
+  if (persisted) {
+    if (persisted.generated) {
+      warn(
+        `[LocalCryptoProvider] No ${SECRET_KEY_ENV}/${DEV_KEY_ENV} set \u2014 generated 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} explicitly so the key survives.`
+      );
+    }
+    return { key: persisted.key, source: persisted.generated ? "generated-file" : "file" };
+  }
+  const key = (0, import_node_crypto.randomBytes)(32);
+  warn(
+    `[LocalCryptoProvider] No ${SECRET_KEY_ENV} set and could not persist a fallback key at ${path} \u2014 generated an EPHEMERAL key. Existing encrypted settings/secrets will fail to decrypt after restart. Set ${SECRET_KEY_ENV} to a stable 32-byte key:
+  ${SECRET_KEY_ENV}=${key.toString("base64")}`
+  );
+  return { key, source: "ephemeral" };
+}
 var isWebContainerRuntime = () => {
   const g = globalThis;
   return typeof g !== "undefined" && (Boolean(g.process?.versions?.webcontainer) || Boolean(g.process?.env?.SHELL?.includes?.("jsh")) || Boolean(g.process?.env?.STACKBLITZ));
@@ -688,8 +766,8 @@ var loadNobleGcm = () => {
         const mod = await import("@noble/ciphers/aes.js");
         return mod.gcm;
       } catch (err) {
-        console.warn(
-          `[InMemoryCryptoProvider] WebContainer detected but @noble/ciphers not installed: ${err?.message ?? err}. Falling back to node:crypto (will throw).`
+        warn(
+          `[LocalCryptoProvider] WebContainer detected but @noble/ciphers not installed: ${err?.message ?? err}. Falling back to node:crypto (will throw).`
         );
         return void 0;
       }
@@ -697,39 +775,11 @@ var loadNobleGcm = () => {
   }
   return nobleGcmPromise;
 };
-var InMemoryCryptoProvider = class {
+var LocalCryptoProvider = class {
   constructor(opts = {}) {
-    if (opts.key) {
-      this.key = opts.key;
-    } else {
-      const fromEnv = parseDevKey(
-        (0, import_types.readEnvWithDeprecation)(DEV_KEY_ENV, DEV_KEY_LEGACY_ENV)
-      );
-      if (fromEnv) {
-        this.key = fromEnv;
-      } else {
-        const isTest = Boolean(
-          globalThis?.process?.env?.VITEST || globalThis?.process?.env?.NODE_ENV === "test"
-        );
-        const persisted = isTest ? void 0 : loadOrCreateDevKey();
-        if (persisted) {
-          this.key = persisted.key;
-          if (persisted.generated) {
-            console.warn(
-              `[InMemoryCryptoProvider] No ${DEV_KEY_ENV} set \u2014 generated a new AES-256-GCM key and persisted it to ${persisted.path} (mode 0600). Future restarts will reuse it automatically. For shared/CI environments, set ${DEV_KEY_ENV} explicitly in your environment.`
-            );
-          }
-        } else {
-          this.key = (0, import_node_crypto.randomBytes)(32);
-          if (!isTest) {
-            console.warn(
-              `[InMemoryCryptoProvider] No ${DEV_KEY_ENV} set and could not persist a fallback key \u2014 generated an ephemeral AES-256-GCM key. Existing encrypted settings (e.g. AI API keys) will fail to decrypt on next restart. To make the key survive restarts, add this to your .env:
-  ${DEV_KEY_ENV}=${this.key.toString("base64")}`
-            );
-          }
-        }
-      }
-    }
+    const resolved = resolveDataKey(opts);
+    this.key = resolved.key;
+    this.keySource = resolved.source;
     this.useNoble = isWebContainerRuntime();
   }
   async encrypt(plain, ctx) {
@@ -753,7 +803,7 @@ var InMemoryCryptoProvider = class {
     }
     return {
       id: "sec_" + (0, import_node_crypto.randomBytes)(16).toString("hex"),
-      kmsKeyId: "local:in-memory:v1",
+      kmsKeyId: "local:v1",
       alg: "aes-256-gcm",
       version: 1,
       ciphertext: blob
@@ -785,7 +835,7 @@ var InMemoryCryptoProvider = class {
     return {
       ...next,
       id: handle.id,
-      kmsKeyId: `local:in-memory:v${handle.version + 1}`,
+      kmsKeyId: `local:v${handle.version + 1}`,
       version: handle.version + 1
     };
   }
@@ -803,6 +853,7 @@ var InMemoryCryptoProvider = class {
     return [ctx.namespace, ctx.key].join("|");
   }
 };
+var InMemoryCryptoProvider = LocalCryptoProvider;
 
 // src/settings-routes.ts
 var defaultContext = (req) => {
@@ -3082,7 +3133,7 @@ var SettingsServicePlugin = class {
           {
             secretStore: this.buildSecretStore(engine),
             auditWriter: this.buildAuditWriter(ctx, engine),
-            cryptoProvider: this.opts.cryptoProvider ?? new InMemoryCryptoProvider()
+            cryptoProvider: this.opts.cryptoProvider ?? new LocalCryptoProvider()
           }
         );
       }
@@ -3219,6 +3270,7 @@ function wrapEngineAsSettingsEngine(engine) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   InMemoryCryptoProvider,
+  LocalCryptoProvider,
   NoopCryptoAdapter,
   SETTINGS_PLUGIN_ID,
   SETTINGS_PLUGIN_VERSION,