@objectstack/service-settings 7.5.0 → 7.7.0

package/dist/index.d.cts

@@ -332,12 +332,36 @@ declare class SettingsService {
     private materialiseRow;
 }
 
-declare class InMemoryCryptoProvider implements ICryptoProvider {
+type EnvMap = Record<string, string | undefined>;
+/** Where the provider resolved its data key from (for diagnostics). */
+type KeySource = 'explicit' | 'env:OS_SECRET_KEY' | 'env:OS_DEV_CRYPTO_KEY' | 'file' | 'generated-file' | 'ephemeral';
+type CryptoMode = 'production' | 'development' | 'test';
+interface LocalCryptoProviderOptions {
+    /** Explicit 32-byte data key. Overrides all env / file resolution. */
+    key?: Buffer;
+    /**
+     * Env source. Defaults to `process.env`. Injectable so embedders and
+     * tests can drive key resolution deterministically.
+     */
+    env?: EnvMap;
+    /**
+     * Deployment mode. Controls whether an ephemeral / auto-generated key is
+     * tolerated. Defaults to auto-detection from `NODE_ENV`:
+     *  - `production`  → a stable key (env var or pre-existing file) is
+     *    REQUIRED; construction throws otherwise (fail loud).
+     *  - `development` → persists an auto-generated key to disk so restarts
+     *    reuse it; falls back to an ephemeral key (loud warning) if disk is
+     *    unwritable.
+     *  - `test`        → never touches disk; uses an ephemeral key silently.
+     */
+    mode?: CryptoMode;
+}
+declare class LocalCryptoProvider implements ICryptoProvider {
     private readonly key;
     private readonly useNoble;
-    constructor(opts?: {
-        key?: Buffer;
-    });
+    /** Where the active data key came from. Exposed for diagnostics/tests. */
+    readonly keySource: KeySource;
+    constructor(opts?: LocalCryptoProviderOptions);
     encrypt(plain: string, ctx: CryptoContext): Promise<CryptoHandle>;
     decrypt(handle: CryptoHandle, ctx: CryptoContext): Promise<string>;
     rotateKey(handle: CryptoHandle, ctx: CryptoContext): Promise<CryptoHandle>;
@@ -345,6 +369,12 @@ declare class InMemoryCryptoProvider implements ICryptoProvider {
     private encryptNode;
     private aadOf;
 }
+/**
+ * @deprecated Renamed to {@link LocalCryptoProvider}. The old name implied an
+ * "in-memory / ephemeral" key when the provider in fact persists its key
+ * (env var or on-disk file). Kept as an alias for backward compatibility.
+ */
+declare const InMemoryCryptoProvider: typeof LocalCryptoProvider;
 
 /** Configuration options for the SettingsServicePlugin. */
 interface SettingsServicePluginOptions {
@@ -360,9 +390,11 @@ interface SettingsServicePluginOptions {
     /**
      * Phase 3 KMS hook. When provided, encrypted specifier values are
      * routed through this provider into `sys_secret`; `sys_setting.value_enc`
-     * holds the handle id only. Defaults to `InMemoryCryptoProvider`
-     * (NOT suitable for production secrets — replace with an AWS / GCP
-     * KMS-backed implementation).
+     * holds the handle id only. Defaults to `LocalCryptoProvider`, an
+     * AES-256-GCM provider keyed off `OS_SECRET_KEY` (or a persisted dev key).
+     * In production it refuses to boot without a stable key rather than
+     * silently minting an ephemeral one. Swap in an AWS / GCP / Vault
+     * KMS-backed implementation for managed custody and per-tenant keys.
      */
     cryptoProvider?: ICryptoProvider;
     /** Override the default base path (`/api/settings`). */
@@ -612,4 +644,4 @@ declare const jaJP: TranslationData;
 
 declare const settingsBuiltinTranslations: TranslationBundle;
 
-export { type CryptoAdapter, InMemoryCryptoProvider, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, UnknownKeyError, UnknownNamespaceError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };
+export { type CryptoAdapter, type CryptoMode, InMemoryCryptoProvider, type KeySource, LocalCryptoProvider, type LocalCryptoProviderOptions, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, UnknownKeyError, UnknownNamespaceError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };

package/dist/index.d.ts

@@ -332,12 +332,36 @@ declare class SettingsService {
     private materialiseRow;
 }
 
-declare class InMemoryCryptoProvider implements ICryptoProvider {
+type EnvMap = Record<string, string | undefined>;
+/** Where the provider resolved its data key from (for diagnostics). */
+type KeySource = 'explicit' | 'env:OS_SECRET_KEY' | 'env:OS_DEV_CRYPTO_KEY' | 'file' | 'generated-file' | 'ephemeral';
+type CryptoMode = 'production' | 'development' | 'test';
+interface LocalCryptoProviderOptions {
+    /** Explicit 32-byte data key. Overrides all env / file resolution. */
+    key?: Buffer;
+    /**
+     * Env source. Defaults to `process.env`. Injectable so embedders and
+     * tests can drive key resolution deterministically.
+     */
+    env?: EnvMap;
+    /**
+     * Deployment mode. Controls whether an ephemeral / auto-generated key is
+     * tolerated. Defaults to auto-detection from `NODE_ENV`:
+     *  - `production`  → a stable key (env var or pre-existing file) is
+     *    REQUIRED; construction throws otherwise (fail loud).
+     *  - `development` → persists an auto-generated key to disk so restarts
+     *    reuse it; falls back to an ephemeral key (loud warning) if disk is
+     *    unwritable.
+     *  - `test`        → never touches disk; uses an ephemeral key silently.
+     */
+    mode?: CryptoMode;
+}
+declare class LocalCryptoProvider implements ICryptoProvider {
     private readonly key;
     private readonly useNoble;
-    constructor(opts?: {
-        key?: Buffer;
-    });
+    /** Where the active data key came from. Exposed for diagnostics/tests. */
+    readonly keySource: KeySource;
+    constructor(opts?: LocalCryptoProviderOptions);
     encrypt(plain: string, ctx: CryptoContext): Promise<CryptoHandle>;
     decrypt(handle: CryptoHandle, ctx: CryptoContext): Promise<string>;
     rotateKey(handle: CryptoHandle, ctx: CryptoContext): Promise<CryptoHandle>;
@@ -345,6 +369,12 @@ declare class InMemoryCryptoProvider implements ICryptoProvider {
     private encryptNode;
     private aadOf;
 }
+/**
+ * @deprecated Renamed to {@link LocalCryptoProvider}. The old name implied an
+ * "in-memory / ephemeral" key when the provider in fact persists its key
+ * (env var or on-disk file). Kept as an alias for backward compatibility.
+ */
+declare const InMemoryCryptoProvider: typeof LocalCryptoProvider;
 
 /** Configuration options for the SettingsServicePlugin. */
 interface SettingsServicePluginOptions {
@@ -360,9 +390,11 @@ interface SettingsServicePluginOptions {
     /**
      * Phase 3 KMS hook. When provided, encrypted specifier values are
      * routed through this provider into `sys_secret`; `sys_setting.value_enc`
-     * holds the handle id only. Defaults to `InMemoryCryptoProvider`
-     * (NOT suitable for production secrets — replace with an AWS / GCP
-     * KMS-backed implementation).
+     * holds the handle id only. Defaults to `LocalCryptoProvider`, an
+     * AES-256-GCM provider keyed off `OS_SECRET_KEY` (or a persisted dev key).
+     * In production it refuses to boot without a stable key rather than
+     * silently minting an ephemeral one. Swap in an AWS / GCP / Vault
+     * KMS-backed implementation for managed custody and per-tenant keys.
      */
     cryptoProvider?: ICryptoProvider;
     /** Override the default base path (`/api/settings`). */
@@ -612,4 +644,4 @@ declare const jaJP: TranslationData;
 
 declare const settingsBuiltinTranslations: TranslationBundle;
 
-export { type CryptoAdapter, InMemoryCryptoProvider, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, UnknownKeyError, UnknownNamespaceError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };
+export { type CryptoAdapter, type CryptoMode, InMemoryCryptoProvider, type KeySource, LocalCryptoProvider, type LocalCryptoProviderOptions, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, UnknownKeyError, UnknownNamespaceError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };

package/dist/index.js

@@ -572,36 +572,25 @@ function coerceEnvValue(raw, hint) {
   return raw;
 }
 
-// src/in-memory-crypto-provider.ts
-import { readEnvWithDeprecation } from "@objectstack/types";
+// src/local-crypto-provider.ts
 import { createHash, randomBytes, createCipheriv, createDecipheriv } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, join } from "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 = readEnvWithDeprecation("OS_HOME", "OBJECTSTACK_HOME") || (proc?.env?.HOME ? join(proc.env.HOME, ".objectstack") : void 0) || join(homedir(), ".objectstack");
-  return 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 (existsSync(path)) {
-      const raw = readFileSync(path, "utf8").trim();
-      const parsed = parseDevKey(raw);
-      if (parsed) return { key: parsed, path, generated: false };
-    }
-    const key = randomBytes(32);
-    mkdirSync(dirname(path), { recursive: true });
-    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 ? join(env.HOME, ".objectstack") : void 0) || join(homedir(), ".objectstack");
+  return 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;
@@ -612,11 +601,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 (!existsSync(path)) return void 0;
+    return parseKey(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 = randomBytes(32);
+    mkdirSync(dirname(path), { recursive: true });
+    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: 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 = 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));
@@ -629,8 +706,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;
       }
@@ -638,39 +715,11 @@ var loadNobleGcm = () => {
   }
   return nobleGcmPromise;
 };
-var InMemoryCryptoProvider = class {
+var LocalCryptoProvider = class {
   constructor(opts = {}) {
-    if (opts.key) {
-      this.key = opts.key;
-    } else {
-      const fromEnv = parseDevKey(
-        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 = 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) {
@@ -694,7 +743,7 @@ var InMemoryCryptoProvider = class {
     }
     return {
       id: "sec_" + randomBytes(16).toString("hex"),
-      kmsKeyId: "local:in-memory:v1",
+      kmsKeyId: "local:v1",
       alg: "aes-256-gcm",
       version: 1,
       ciphertext: blob
@@ -726,7 +775,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
     };
   }
@@ -744,6 +793,7 @@ var InMemoryCryptoProvider = class {
     return [ctx.namespace, ctx.key].join("|");
   }
 };
+var InMemoryCryptoProvider = LocalCryptoProvider;
 
 // src/settings-routes.ts
 var defaultContext = (req) => {
@@ -3023,7 +3073,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()
           }
         );
       }
@@ -3159,6 +3209,7 @@ function wrapEngineAsSettingsEngine(engine) {
 }
 export {
   InMemoryCryptoProvider,
+  LocalCryptoProvider,
   NoopCryptoAdapter,
   SETTINGS_PLUGIN_ID,
   SETTINGS_PLUGIN_VERSION,