Add Phase 3 sys_secret crypto & audit

Introduce Phase 3 secret splitting and audit plumbing for SettingsService.

- Add InMemoryCryptoProvider: an AES-256-GCM in-memory ICryptoProvider used as a default KMS shim for tests/dev (not suitable for production). Supports encrypt/decrypt, rotateKey, and digest with AAD binding to (namespace,key).
- Extend manifest to include SysSecret and SysSettingAudit objects.
- Wire optional cryptoProvider, secretStore and auditWriter through SettingsServicePlugin and SettingsService.bindEngine so encrypted values can be persisted to a sys_secret row while sys_setting.value_enc stores only the handle id.
- Implement secretStore and auditWriter helpers in the plugin for engine-backed persistence and append-only audit writes (failures logged but do not abort setting writes).
- Update SettingsService to: route encrypted writes through the wired ICryptoProvider + secretStore (fallback to legacy inline crypto adapter when not provided), compute digests via provider when used, dereference sys_secret on reads when handle ids (sec_...) are present, and emit setting-audit entries via auditWriter.
- Add SettingsService types: SettingsSecretStore and SettingsAuditWriter interfaces.
- Add unit tests validating sys_secret routing, AAD binding, and rotateKey behavior.

This change enables storing ciphertexts in a dedicated sys_secret object, provides a pluggable KMS interface, and records per-setting audit events while preserving backward compatibility with the existing inline crypto adapter path.

Author: hotlong

packages/services/service-settings/src/in-memory-crypto-provider.ts

@@ -0,0 +1,95 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  CryptoContext,
+  CryptoHandle,
+  ICryptoProvider,
+} from '@objectstack/spec/contracts';
+import { createHash, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+
+/**
+ * InMemoryCryptoProvider — default ICryptoProvider used by the
+ * SettingsService when the host application does not wire a real KMS.
+ *
+ * Encryption: AES-256-GCM with a per-process random data key. The data
+ * key lives only in memory; restarting the process loses the ability
+ * to decrypt previously-written rows. This is intentional — operators
+ * MUST replace this with a KMS-backed provider before relying on
+ * `sys_secret` for production secrets. The provider's purpose is to:
+ *
+ *  - exercise the round-trip in unit tests and dev kernels;
+ *  - provide a "real-looking" handle format so consumers don't depend
+ *    on accidental implementation details of a no-op adapter;
+ *  - serve as a reference for what AwsKmsCryptoProvider /
+ *    GcpKmsCryptoProvider implementations need to satisfy.
+ *
+ * Handle format:
+ *   id        — `sec_` + 32 hex chars (122 bits of entropy)
+ *   kmsKeyId  — `local:in-memory:v<version>`
+ *   alg       — `aes-256-gcm`
+ *   version   — bumps on rotateKey()
+ *   ciphertext— base64(iv (12) || authTag (16) || cipher)
+ *
+ * AAD binding: the CryptoContext (namespace + key + tenantId) is
+ * folded into AES-GCM AAD so a ciphertext rewrapped from a different
+ * (ns, key) tuple fails decryption — guards against operators
+ * accidentally copying rows between namespaces.
+ */
+export class InMemoryCryptoProvider implements ICryptoProvider {
+  private readonly key: Buffer;
+
+  constructor(opts: { key?: Buffer } = {}) {
+    this.key = opts.key ?? randomBytes(32);
+  }
+
+  async encrypt(plain: string, ctx: CryptoContext): Promise<CryptoHandle> {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this.key, iv);
+    cipher.setAAD(Buffer.from(this.aadOf(ctx), 'utf8'));
+    const enc = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const blob = Buffer.concat([iv, tag, enc]).toString('base64');
+    return {
+      id: 'sec_' + randomBytes(16).toString('hex'),
+      kmsKeyId: 'local:in-memory:v1',
+      alg: 'aes-256-gcm',
+      version: 1,
+      ciphertext: blob,
+    };
+  }
+
+  async decrypt(handle: CryptoHandle, ctx: CryptoContext): Promise<string> {
+    const buf = Buffer.from(handle.ciphertext, 'base64');
+    const iv = buf.subarray(0, 12);
+    const tag = buf.subarray(12, 28);
+    const data = buf.subarray(28);
+    const decipher = createDecipheriv('aes-256-gcm', this.key, iv);
+    decipher.setAAD(Buffer.from(this.aadOf(ctx), 'utf8'));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+  }
+
+  async rotateKey(handle: CryptoHandle, ctx: CryptoContext): Promise<CryptoHandle> {
+    const plain = await this.decrypt(handle, ctx);
+    const next = await this.encrypt(plain, ctx);
+    return {
+      ...next,
+      id: handle.id,
+      kmsKeyId: `local:in-memory:v${handle.version + 1}`,
+      version: handle.version + 1,
+    };
+  }
+
+  digest(plain: string): string {
+    return 'sha256:' + createHash('sha256').update(plain, 'utf8').digest('hex');
+  }
+
+  private aadOf(ctx: CryptoContext): string {
+    // Bind ciphertext to (namespace,key) so a row cannot be moved across
+    // specifiers. Tenant binding is intentionally omitted because the
+    // handle is dereferenced from a `sys_setting` row already scoped to
+    // its tenant — adding tenant here would force the decrypt path to
+    // re-read that scope.
+    return [ctx.namespace, ctx.key].join('|');
+  }
+}

packages/services/service-settings/src/manifest.ts

@@ -1,12 +1,12 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { SysSetting } from '@objectstack/platform-objects/system';
+import { SysSetting, SysSecret, SysSettingAudit } from '@objectstack/platform-objects/system';
 
 export const SETTINGS_PLUGIN_ID = 'com.objectstack.service.settings';
 export const SETTINGS_PLUGIN_VERSION = '0.1.0';
 
 /** Objects owned by service-settings. Currently just the K/V store. */
-export const settingsObjects: any[] = [SysSetting];
+export const settingsObjects: any[] = [SysSetting, SysSecret, SysSettingAudit];
 
 /** Manifest header shared by compile-time config and runtime registration. */
 export const settingsPluginManifestHeader = {

packages/services/service-settings/src/settings-service-plugin.ts

@@ -4,8 +4,10 @@ import type { Plugin, PluginContext } from '@objectstack/core';
 import type { IHttpServer, IDataEngine } from '@objectstack/spec/contracts';
 import type { SettingsManifest } from '@objectstack/spec/system';
 import { SettingsService } from './settings-service.js';
-import type { SettingsAuditSink, SettingsEngine } from './settings-service.types.js';
+import type { ICryptoProvider } from '@objectstack/spec/contracts';
+import type { SettingsAuditSink, SettingsAuditWriter, SettingsEngine, SettingsSecretStore } from './settings-service.types.js';
 import type { CryptoAdapter } from './crypto-adapter.js';
+import { InMemoryCryptoProvider } from './in-memory-crypto-provider.js';
 import { registerSettingsRoutes } from './settings-routes.js';
 import {
   settingsObjects,
@@ -30,6 +32,15 @@ export interface SettingsServicePluginOptions {
   manifests?: SettingsManifest[];
   /** Override the default crypto adapter. */
   crypto?: CryptoAdapter;
+
+  /**
+   * 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).
+   */
+  cryptoProvider?: ICryptoProvider;
   /** Override the default base path (`/api/settings`). */
   basePath?: string;
   /** Disable REST route registration. */
@@ -147,6 +158,11 @@ export class SettingsServicePlugin implements Plugin {
         this.service!.bindEngine(
           engine as unknown as SettingsEngine,
           this.buildAuditSink(ctx, engine),
+          {
+            secretStore: this.buildSecretStore(engine),
+            auditWriter: this.buildAuditWriter(ctx, engine),
+            cryptoProvider: this.opts.cryptoProvider ?? new InMemoryCryptoProvider(),
+          },
         );
       }
 
@@ -198,4 +214,67 @@ export class SettingsServicePlugin implements Plugin {
       },
     };
   }
+
+  /**
+   * Phase 3: build a `sys_secret`-backed implementation of
+   * `SettingsSecretStore`. The store bypasses the tenant audit
+   * warning because secrets are scoped through their owning
+   * `sys_setting` row (which already carries the tenant context).
+   */
+  private buildSecretStore(engine: IDataEngine): SettingsSecretStore {
+    const eng: any = engine;
+    return {
+      async insert(row) {
+        await eng.insert('sys_secret', row, { bypassTenantAudit: true });
+        return { id: row.id };
+      },
+      async get(id) {
+        const rows = await eng.find('sys_secret', {
+          where: { id },
+          limit: 1,
+          bypassTenantAudit: true,
+        });
+        const row = Array.isArray(rows) ? rows[0] : rows?.data?.[0];
+        return row ?? null;
+      },
+      async update(id, patch) {
+        await eng.update('sys_secret', {
+          where: { id },
+          data: patch,
+          bypassTenantAudit: true,
+        });
+      },
+    };
+  }
+
+  /**
+   * Phase 3: append-only writer for `sys_setting_audit`. Failures here
+   * MUST NOT abort the settings write, so all calls are wrapped in a
+   * try/catch and reported through the plugin logger.
+   */
+  private buildAuditWriter(ctx: PluginContext, engine: IDataEngine): SettingsAuditWriter {
+    const eng: any = engine;
+    return {
+      write: async (entry) => {
+        try {
+          await eng.insert('sys_setting_audit', {
+            namespace: entry.namespace,
+            key: entry.key,
+            scope: entry.scope,
+            action: entry.action,
+            source: entry.source ?? 'api',
+            actor_id: entry.actorId ?? null,
+            old_hash: entry.oldHash ?? null,
+            new_hash: entry.newHash ?? null,
+            encrypted: !!entry.encrypted,
+            request_id: entry.requestId ?? null,
+            reason: entry.reason ?? null,
+            created_at: new Date().toISOString(),
+          }, { bypassTenantAudit: true });
+        } catch (err: any) {
+          ctx.logger?.warn?.('SettingsServicePlugin: setting-audit write failed: ' + (err?.message ?? err));
+        }
+      },
+    };
+  }
 }

packages/services/service-settings/src/settings-service.test.ts

@@ -356,3 +356,70 @@ describe('SettingsService — Phase 2 cascade chain + lock', () => {
     });
   });
 });
+
+describe('SettingsService — Phase 3 sys_secret + crypto provider + audit', () => {
+  it('routes encrypted writes through sys_secret when wired', async () => {
+    const { InMemoryCryptoProvider } = await import('./in-memory-crypto-provider.js');
+    const secretRows = new Map<string, any>();
+    const auditRows: any[] = [];
+
+    const svc = new SettingsService({
+      env: {},
+      cryptoProvider: new InMemoryCryptoProvider(),
+      secretStore: {
+        async insert(row) { secretRows.set(row.id, row); return { id: row.id }; },
+        async get(id) { return secretRows.get(id) ?? null; },
+        async update(id, patch) { secretRows.set(id, { ...secretRows.get(id), ...patch }); },
+      },
+      auditWriter: { write: (e) => { auditRows.push(e); } },
+    });
+    svc.registerManifest(mailSettingsManifest);
+
+    await svc.set('mail', 'api_key', 'super-secret-key', { tenantId: 't1' });
+
+    // sys_secret got the cipher; sys_setting only holds the handle id.
+    expect(secretRows.size).toBe(1);
+    const [secret] = [...secretRows.values()];
+    expect(secret.namespace).toBe('mail');
+    expect(secret.key).toBe('api_key');
+    expect(secret.alg).toBe('aes-256-gcm');
+    expect(secret.ciphertext).not.toContain('super-secret-key');
+
+    // Round-trip read returns the plaintext.
+    const r = await svc.get<string>('mail', 'api_key', { tenantId: 't1' });
+    expect(r.value).toBe('super-secret-key');
+
+    // Audit writer received the set event with a non-leaking digest.
+    expect(auditRows).toHaveLength(1);
+    expect(auditRows[0]).toMatchObject({
+      namespace: 'mail',
+      key: 'api_key',
+      action: 'set',
+      encrypted: true,
+    });
+    expect(auditRows[0].newHash).toMatch(/^sha256:/);
+    expect(auditRows[0].newHash).not.toContain('super-secret-key');
+  });
+
+  it('AAD binding rejects ciphertexts swapped across (namespace,key)', async () => {
+    const { InMemoryCryptoProvider } = await import('./in-memory-crypto-provider.js');
+    const provider = new InMemoryCryptoProvider();
+    const handle = await provider.encrypt('value', { namespace: 'mail', key: 'api_key' });
+    // Same handle, wrong context → must throw.
+    await expect(
+      provider.decrypt(handle, { namespace: 'mail', key: 'smtp_password' }),
+    ).rejects.toThrow();
+  });
+
+  it('rotateKey bumps version while preserving plaintext + handle id', async () => {
+    const { InMemoryCryptoProvider } = await import('./in-memory-crypto-provider.js');
+    const provider = new InMemoryCryptoProvider();
+    const ctx = { namespace: 'mail', key: 'api_key' };
+    const h1 = await provider.encrypt('hello', ctx);
+    const h2 = await provider.rotateKey(h1, ctx);
+    expect(h2.id).toBe(h1.id);
+    expect(h2.version).toBe(h1.version + 1);
+    expect(h2.ciphertext).not.toBe(h1.ciphertext);
+    expect(await provider.decrypt(h2, ctx)).toBe('hello');
+  });
+});