@objectstack/service-settings 0.1.1

package/dist/index.js

@@ -0,0 +1,1697 @@
+// src/crypto-adapter.ts
+var NoopCryptoAdapter = class {
+  async encrypt(plaintext) {
+    return "b64:" + Buffer.from(plaintext, "utf8").toString("base64");
+  }
+  async decrypt(ciphertext) {
+    if (!ciphertext.startsWith("b64:")) {
+      return ciphertext;
+    }
+    return Buffer.from(ciphertext.slice(4), "base64").toString("utf8");
+  }
+  digest(plaintext) {
+    let h = 2166136261;
+    for (let i = 0; i < plaintext.length; i++) {
+      h ^= plaintext.charCodeAt(i);
+      h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+    }
+    return "fnv32:" + h.toString(16).padStart(8, "0");
+  }
+};
+
+// src/settings-service.types.ts
+function envKeyOf(namespace, key) {
+  const slug = `${namespace}_${key}`.replace(/[.-]/g, "_").toUpperCase();
+  return slug;
+}
+var SettingsLockedError = class extends Error {
+  constructor(namespace, key, reason = "locked-by-env") {
+    super(`Setting '${namespace}.${key}' is locked (${reason}).`);
+    this.namespace = namespace;
+    this.key = key;
+    this.reason = reason;
+    this.code = "SETTINGS_LOCKED";
+  }
+};
+var UnknownNamespaceError = class extends Error {
+  constructor(namespace) {
+    super(`No settings manifest registered for namespace '${namespace}'.`);
+    this.namespace = namespace;
+    this.code = "SETTINGS_UNKNOWN_NAMESPACE";
+  }
+};
+var UnknownKeyError = class extends Error {
+  constructor(namespace, key) {
+    super(`Key '${key}' is not declared in manifest '${namespace}'.`);
+    this.namespace = namespace;
+    this.key = key;
+    this.code = "SETTINGS_UNKNOWN_KEY";
+  }
+};
+
+// src/settings-service.ts
+var DEFAULT_OBJECT = "sys_setting";
+var LAYOUT_ONLY_TYPES = /* @__PURE__ */ new Set([
+  "group",
+  "info_banner",
+  "child_pane",
+  "title_value",
+  "action_button"
+]);
+var SettingsService = class {
+  constructor(opts = {}) {
+    this.registry = /* @__PURE__ */ new Map();
+    /** In-memory fallback when no engine is wired. */
+    this.memory = [];
+    /** Change subscribers, optionally scoped to a namespace. */
+    this.subscribers = /* @__PURE__ */ new Set();
+    this.engine = opts.engine;
+    this.crypto = opts.crypto ?? new NoopCryptoAdapter();
+    this.cryptoProvider = opts.cryptoProvider;
+    this.secretStore = opts.secretStore;
+    this.audit = opts.audit;
+    this.auditWriter = opts.auditWriter;
+    this.env = opts.env ?? (typeof process !== "undefined" ? process.env : {});
+    this.objectName = opts.objectName ?? DEFAULT_OBJECT;
+  }
+  /**
+   * Late-bind a data engine and (optionally) an audit sink. Plugins
+   * call this from `kernel:ready` once `objectql` is wired so the
+   * SettingsService swaps from its in-memory fallback to the real
+   * `sys_setting` table without re-registering the service.
+   */
+  bindEngine(engine, audit, extras) {
+    this.engine = engine;
+    if (audit) this.audit = audit;
+    if (extras?.secretStore) this.secretStore = extras.secretStore;
+    if (extras?.auditWriter) this.auditWriter = extras.auditWriter;
+    if (extras?.cryptoProvider) this.cryptoProvider = extras.cryptoProvider;
+  }
+  /**
+   * Cascade priority ranks for lock comparisons (lower = higher
+   * precedence). env<global<tenant<user<default. A locked row at a
+   * lower rank blocks writes at all higher ranks.
+   */
+  scopeRank(scope) {
+    switch (scope) {
+      case "global":
+        return 1;
+      case "tenant":
+        return 2;
+      case "user":
+        return 3;
+      default:
+        return 99;
+    }
+  }
+  // ---------------------------------------------------------------------
+  // Change events (Phase 1)
+  // ---------------------------------------------------------------------
+  /**
+   * Subscribe to `settings:changed` events. When `namespace` is set the
+   * handler only fires for that namespace, otherwise it fires for every
+   * mutation across the service.
+   *
+   * Returns an idempotent unsubscribe handle — call it from the
+   * consumer's shutdown hook to avoid leaks.
+   */
+  subscribe(namespace, handler) {
+    const entry = { ns: namespace, handler };
+    this.subscribers.add(entry);
+    return () => {
+      this.subscribers.delete(entry);
+    };
+  }
+  /**
+   * Dispatch a change event to all matching subscribers. Errors thrown
+   * by a handler are swallowed to keep the bus crash-safe — handlers
+   * are expected to enqueue async work themselves.
+   */
+  emitChange(event) {
+    if (this.subscribers.size === 0) return;
+    for (const sub of this.subscribers) {
+      if (sub.ns && sub.ns !== event.namespace) continue;
+      try {
+        sub.handler(event);
+      } catch {
+      }
+    }
+  }
+  // ---------------------------------------------------------------------
+  // Manifest registry
+  // ---------------------------------------------------------------------
+  /** Register (or replace) a manifest. Idempotent. */
+  registerManifest(manifest3) {
+    const scopes = /* @__PURE__ */ new Map();
+    const encryptedKeys = /* @__PURE__ */ new Set();
+    const defaults = /* @__PURE__ */ new Map();
+    const defaultScope = manifest3.scope ?? "tenant";
+    for (const spec of manifest3.specifiers) {
+      if (!spec.key || LAYOUT_ONLY_TYPES.has(spec.type)) continue;
+      scopes.set(spec.key, spec.scope ?? defaultScope);
+      if (spec.encrypted || spec.type === "password") encryptedKeys.add(spec.key);
+      if (typeof spec.default !== "undefined") defaults.set(spec.key, spec.default);
+    }
+    const prev = this.registry.get(manifest3.namespace);
+    const actions = prev?.actions ?? /* @__PURE__ */ new Map();
+    this.registry.set(manifest3.namespace, { manifest: manifest3, scopes, encryptedKeys, defaults, actions });
+  }
+  /** Look up a manifest, or throw `UnknownNamespaceError`. */
+  getManifest(namespace) {
+    const reg = this.registry.get(namespace);
+    if (!reg) throw new UnknownNamespaceError(namespace);
+    return reg.manifest;
+  }
+  /** List all registered manifests, optionally filtered by permission. */
+  listManifests(ctx = {}) {
+    const perms = new Set(ctx.permissions ?? []);
+    const all = Array.from(this.registry.values()).map((r) => r.manifest);
+    if (perms.size === 0) return all;
+    return all.filter((m) => perms.has(m.readPermission ?? "setup.access"));
+  }
+  /** Register a handler for an `action_button` declared in a manifest. */
+  registerAction(namespace, actionId, handler) {
+    const reg = this.registry.get(namespace);
+    if (!reg) throw new UnknownNamespaceError(namespace);
+    reg.actions.set(actionId, handler);
+  }
+  // ---------------------------------------------------------------------
+  // Resolver
+  // ---------------------------------------------------------------------
+  /** Resolve a single key. */
+  async get(namespace, key, ctx = {}) {
+    const reg = this.registry.get(namespace);
+    if (!reg) throw new UnknownNamespaceError(namespace);
+    if (!reg.scopes.has(key)) throw new UnknownKeyError(namespace, key);
+    const envName = envKeyOf(namespace, key);
+    const envRaw = this.env[envName];
+    if (typeof envRaw === "string") {
+      const def2 = reg.defaults.get(key);
+      const value = coerceEnvValue(envRaw, def2);
+      return {
+        value,
+        source: "env",
+        locked: true,
+        lockedReason: `Set via env: ${envName}`,
+        cascadeChain: [
+          { scope: "env", value, locked: true, lockedReason: `Set via env: ${envName}`, effective: true }
+        ]
+      };
+    }
+    const scope = reg.scopes.get(key);
+    const rows = await this.loadRows(namespace, scope === "user" ? ctx.userId ?? null : null);
+    const chain = [];
+    const globalRow = rows.find((r) => r.key === key && r.scope === "global");
+    if (globalRow) {
+      const value = await this.materialiseRow(globalRow);
+      chain.push({
+        scope: "global",
+        value,
+        locked: !!globalRow.locked,
+        lockedReason: globalRow.locked_reason ?? void 0
+      });
+    }
+    if (scope === "tenant" || scope === "user") {
+      const tenantRow = rows.find((r) => r.key === key && r.scope === "tenant");
+      if (tenantRow) {
+        chain.push({
+          scope: "tenant",
+          value: await this.materialiseRow(tenantRow),
+          locked: !!tenantRow.locked,
+          lockedReason: tenantRow.locked_reason ?? void 0
+        });
+      }
+    }
+    if (scope === "user") {
+      const userRow = rows.find((r) => r.key === key && r.scope === "user");
+      if (userRow) {
+        chain.push({
+          scope: "user",
+          value: await this.materialiseRow(userRow)
+        });
+      }
+    }
+    const def = reg.defaults.get(key);
+    chain.push({ scope: "default", value: def ?? null });
+    const lockedEntry = chain.find((e) => e.locked === true);
+    const effective = chain.find((e) => e.value !== null && e.value !== void 0) ?? chain[chain.length - 1];
+    effective.effective = true;
+    return {
+      value: effective.value,
+      source: effective.scope,
+      locked: !!lockedEntry,
+      lockedReason: lockedEntry?.lockedReason,
+      cascadeChain: chain
+    };
+  }
+  /** Resolve every value in a namespace + return the manifest. */
+  async getNamespace(namespace, ctx = {}) {
+    const reg = this.registry.get(namespace);
+    if (!reg) throw new UnknownNamespaceError(namespace);
+    const values = {};
+    for (const [key] of reg.scopes) {
+      values[key] = await this.get(namespace, key, ctx);
+    }
+    return { manifest: reg.manifest, values };
+  }
+  // ---------------------------------------------------------------------
+  // Reactive client (Phase 1)
+  // ---------------------------------------------------------------------
+  /**
+   * Build a reactive `ISettingsClient` for a namespace.
+   *
+   * The client maintains an internal snapshot of the resolved values,
+   * refreshing on every `settings:changed` event for the namespace.
+   * Consumers call `current` / `get(key)` for synchronous reads and
+   * register handlers via `onChange()`.
+   *
+   * `schema` is optional. When supplied, the snapshot is parsed (and
+   * defaulted) through the Zod schema on each refresh — this gives
+   * plugins strong types and runtime validation in one call. When
+   * absent, raw resolved values flow through unchanged (used by the
+   * dynamic console UI which validates per-field).
+   */
+  async createClient(namespace, opts = {}) {
+    const ctx = opts.ctx ?? {};
+    let snapshot = await this.snapshotOf(namespace, ctx, opts.parse);
+    const off = this.subscribe(namespace, () => {
+      void this.snapshotOf(namespace, ctx, opts.parse).then((next) => {
+        snapshot = next;
+      });
+    });
+    return {
+      namespace,
+      get current() {
+        return snapshot;
+      },
+      get(key) {
+        return snapshot[key];
+      },
+      onChange: (handler) => this.subscribe(namespace, handler),
+      refresh: async () => {
+        snapshot = await this.snapshotOf(namespace, ctx, opts.parse);
+      },
+      dispose: off
+    };
+  }
+  async snapshotOf(namespace, ctx, parse) {
+    const payload = await this.getNamespace(namespace, ctx);
+    const raw = {};
+    for (const [k, v] of Object.entries(payload.values)) raw[k] = v.value;
+    return parse ? parse(raw) : raw;
+  }
+  // ---------------------------------------------------------------------
+  // Mutations
+  // ---------------------------------------------------------------------
+  /** Persist a single key. Throws SettingsLockedError when env-locked. */
+  async set(namespace, key, value, ctx = {}) {
+    return (await this.setMany(namespace, { [key]: value }, ctx))[key];
+  }
+  /** Persist multiple keys atomically (best-effort). */
+  async setMany(namespace, patch, ctx = {}) {
+    const reg = this.registry.get(namespace);
+    if (!reg) throw new UnknownNamespaceError(namespace);
+    for (const key of Object.keys(patch)) {
+      if (!reg.scopes.has(key)) throw new UnknownKeyError(namespace, key);
+      const envRaw = this.env[envKeyOf(namespace, key)];
+      if (typeof envRaw === "string") throw new SettingsLockedError(namespace, key);
+      const scope = reg.scopes.get(key);
+      const rows = await this.loadRows(namespace, scope === "user" ? ctx.userId ?? null : null);
+      const upper = rows.find(
+        (r) => r.key === key && r.locked === true && this.scopeRank(r.scope) < this.scopeRank(scope)
+      );
+      if (upper) {
+        throw new SettingsLockedError(namespace, key, `locked-by-${upper.scope}`);
+      }
+    }
+    for (const [key, rawValue] of Object.entries(patch)) {
+      const scope = reg.scopes.get(key);
+      const userId = scope === "user" ? ctx.userId ?? null : null;
+      const isEncrypted = reg.encryptedKeys.has(key);
+      const isNull = rawValue === null || typeof rawValue === "undefined";
+      let storedValue = null;
+      let storedEnc = null;
+      let digest = "";
+      if (!isNull) {
+        if (isEncrypted) {
+          const plain = typeof rawValue === "string" ? rawValue : JSON.stringify(rawValue);
+          if (this.cryptoProvider && this.secretStore) {
+            const handle = await this.cryptoProvider.encrypt(plain, {
+              namespace,
+              key,
+              tenantId: ctx.tenantId
+            });
+            await this.secretStore.insert({
+              id: handle.id,
+              namespace,
+              key,
+              kms_key_id: handle.kmsKeyId,
+              alg: handle.alg,
+              version: handle.version,
+              ciphertext: handle.ciphertext
+            });
+            storedEnc = handle.id;
+            digest = this.cryptoProvider.digest(plain);
+          } else {
+            storedEnc = await this.crypto.encrypt(plain, { namespace, key });
+            digest = this.crypto.digest(plain);
+          }
+        } else {
+          storedValue = rawValue;
+          digest = this.crypto.digest(stableStringify(rawValue));
+        }
+      }
+      await this.upsertRow({
+        namespace,
+        key,
+        scope,
+        user_id: userId,
+        value: storedValue,
+        value_enc: storedEnc,
+        encrypted: isEncrypted,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        updated_by: ctx.userId ?? null
+      });
+      if (this.audit) {
+        await this.audit.record({
+          namespace,
+          key,
+          scope,
+          userId: ctx.userId,
+          action: isNull ? "reset" : "set",
+          valueDigest: isEncrypted ? "<encrypted:" + digest + ">" : digest,
+          encrypted: isEncrypted,
+          requestId: ctx.requestId
+        });
+      }
+      if (this.auditWriter) {
+        try {
+          await this.auditWriter.write({
+            namespace,
+            key,
+            scope,
+            action: isNull ? "reset" : "set",
+            source: "api",
+            actorId: ctx.userId,
+            oldHash: null,
+            newHash: isNull ? null : digest,
+            encrypted: isEncrypted,
+            requestId: ctx.requestId
+          });
+        } catch {
+        }
+      }
+      this.emitChange({
+        namespace,
+        key,
+        scope,
+        action: isNull ? "reset" : "set",
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    const out = {};
+    for (const key of Object.keys(patch)) {
+      out[key] = await this.get(namespace, key, ctx);
+    }
+    return out;
+  }
+  /** Invoke a declared action (test connection, rotate, …). */
+  async runAction(namespace, actionId, payload, ctx = {}) {
+    const reg = this.registry.get(namespace);
+    if (!reg) throw new UnknownNamespaceError(namespace);
+    const handler = reg.actions.get(actionId);
+    if (!handler) {
+      return {
+        ok: false,
+        severity: "error",
+        message: `No handler registered for action '${actionId}' in '${namespace}'.`
+      };
+    }
+    const values = {};
+    for (const [key] of reg.scopes) {
+      values[key] = (await this.get(namespace, key, ctx)).value;
+    }
+    try {
+      return await handler({ namespace, actionId, values, payload, ctx });
+    } catch (err) {
+      return {
+        ok: false,
+        severity: "error",
+        message: err?.message ?? "Action handler threw."
+      };
+    }
+  }
+  // ---------------------------------------------------------------------
+  // Persistence helpers (engine or in-memory)
+  // ---------------------------------------------------------------------
+  async loadRows(namespace, userId) {
+    if (this.engine) {
+      const where = { namespace };
+      if (userId !== null) where.user_id = userId;
+      const rows = await this.engine.find(this.objectName, {
+        where,
+        bypassTenantAudit: true
+      });
+      return rows.map((r) => ({
+        namespace: r.namespace,
+        key: r.key,
+        scope: r.scope,
+        user_id: r.user_id ?? null,
+        value: r.value ?? null,
+        value_enc: r.value_enc ?? null,
+        encrypted: Boolean(r.encrypted),
+        locked: Boolean(r.locked),
+        locked_reason: r.locked_reason ?? null,
+        updated_at: r.updated_at,
+        updated_by: r.updated_by ?? null
+      }));
+    }
+    return this.memory.filter(
+      (r) => r.namespace === namespace && (userId === null || r.user_id === userId || r.scope === "tenant" || r.scope === "global")
+    );
+  }
+  async upsertRow(row) {
+    if (this.engine) {
+      const where = {
+        namespace: row.namespace,
+        key: row.key,
+        scope: row.scope,
+        user_id: row.user_id ?? null
+      };
+      const bypass = row.scope === "global" ? { bypassTenantAudit: true } : {};
+      const existing = await this.engine.find(this.objectName, {
+        where,
+        limit: 1,
+        ...bypass
+      });
+      if (existing[0]) {
+        await this.engine.update(this.objectName, {
+          where,
+          data: { ...row },
+          ...bypass
+        });
+      } else {
+        await this.engine.insert(this.objectName, { ...row }, bypass);
+      }
+      return;
+    }
+    const idx = this.memory.findIndex(
+      (r) => r.namespace === row.namespace && r.key === row.key && r.scope === row.scope && (r.user_id ?? null) === (row.user_id ?? null)
+    );
+    if (idx >= 0) this.memory[idx] = row;
+    else this.memory.push(row);
+  }
+  async materialiseRow(row) {
+    if (row.encrypted) {
+      if (!row.value_enc) return null;
+      let plain;
+      if (this.cryptoProvider && this.secretStore && typeof row.value_enc === "string" && row.value_enc.startsWith("sec_")) {
+        const secret = await this.secretStore.get(row.value_enc);
+        if (!secret) return null;
+        plain = await this.cryptoProvider.decrypt(
+          {
+            id: secret.id,
+            kmsKeyId: secret.kms_key_id,
+            alg: secret.alg,
+            version: secret.version,
+            ciphertext: secret.ciphertext
+          },
+          { namespace: row.namespace, key: row.key }
+        );
+      } else {
+        plain = await this.crypto.decrypt(row.value_enc, {
+          namespace: row.namespace,
+          key: row.key
+        });
+      }
+      try {
+        return JSON.parse(plain);
+      } catch {
+        return plain;
+      }
+    }
+    return row.value ?? null;
+  }
+};
+function stableStringify(input) {
+  if (input === null || typeof input !== "object") return JSON.stringify(input);
+  if (Array.isArray(input)) return "[" + input.map(stableStringify).join(",") + "]";
+  const obj = input;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+function coerceEnvValue(raw, hint) {
+  if (typeof hint === "boolean") return raw === "true" || raw === "1" || raw === "yes";
+  if (typeof hint === "number") {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : raw;
+  }
+  if (Array.isArray(hint) || hint && typeof hint === "object") {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  return raw;
+}
+
+// src/in-memory-crypto-provider.ts
+import { createHash, randomBytes, createCipheriv, createDecipheriv } from "crypto";
+var InMemoryCryptoProvider = class {
+  constructor(opts = {}) {
+    this.key = opts.key ?? randomBytes(32);
+  }
+  async encrypt(plain, ctx) {
+    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, ctx) {
+    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, ctx) {
+    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) {
+    return "sha256:" + createHash("sha256").update(plain, "utf8").digest("hex");
+  }
+  aadOf(ctx) {
+    return [ctx.namespace, ctx.key].join("|");
+  }
+};
+
+// src/settings-routes.ts
+var defaultContext = (req) => {
+  const header = (name) => {
+    const v = req.headers?.[name];
+    return Array.isArray(v) ? v[0] : v;
+  };
+  const perms = header("x-permissions");
+  return {
+    userId: header("x-user-id"),
+    tenantId: header("x-tenant-id"),
+    permissions: perms ? perms.split(",").map((s) => s.trim()).filter(Boolean) : void 0,
+    requestId: header("x-request-id")
+  };
+};
+function sendError(res, status, code, message, extra) {
+  res.status(status).json({ error: { code, message, ...extra } });
+}
+function registerSettingsRoutes(http, service, opts = {}) {
+  const base = opts.basePath ?? "/api/settings";
+  const ctxOf = opts.contextFromRequest ?? defaultContext;
+  http.get(base, (async (req, res) => {
+    try {
+      const ctx = ctxOf(req);
+      const manifests = service.listManifests(ctx);
+      await res.json({ manifests });
+    } catch (err) {
+      sendError(res, 500, "INTERNAL", err?.message ?? "Failed to list manifests");
+    }
+  }));
+  http.get(`${base}/:namespace`, (async (req, res) => {
+    const ns = req.params.namespace;
+    try {
+      const ctx = ctxOf(req);
+      const payload = await service.getNamespace(ns, ctx);
+      await res.json(payload);
+    } catch (err) {
+      if (err instanceof UnknownNamespaceError) {
+        sendError(res, 404, "UNKNOWN_NAMESPACE", err.message);
+      } else {
+        sendError(res, 500, "INTERNAL", err?.message ?? "Failed to read namespace");
+      }
+    }
+  }));
+  http.put(`${base}/:namespace`, (async (req, res) => {
+    const ns = req.params.namespace;
+    const body = req.body ?? {};
+    try {
+      const ctx = ctxOf(req);
+      const result = await service.setMany(ns, body, ctx);
+      await res.json({ values: result });
+    } catch (err) {
+      if (err instanceof SettingsLockedError) {
+        sendError(res, 409, "SETTINGS_LOCKED", err.message, {
+          namespace: err.namespace,
+          key: err.key,
+          reason: err.reason
+        });
+      } else if (err instanceof UnknownNamespaceError) {
+        sendError(res, 404, "UNKNOWN_NAMESPACE", err.message);
+      } else if (err instanceof UnknownKeyError) {
+        sendError(res, 400, "UNKNOWN_KEY", err.message, { namespace: err.namespace, key: err.key });
+      } else {
+        sendError(res, 500, "INTERNAL", err?.message ?? "Failed to write namespace");
+      }
+    }
+  }));
+  http.post(`${base}/:namespace/:actionId`, (async (req, res) => {
+    const { namespace, actionId } = req.params;
+    try {
+      const ctx = ctxOf(req);
+      const result = await service.runAction(namespace, actionId, req.body, ctx);
+      const status = result.ok ? 200 : 400;
+      await res.status(status).json(result);
+    } catch (err) {
+      if (err instanceof UnknownNamespaceError) {
+        sendError(res, 404, "UNKNOWN_NAMESPACE", err.message);
+      } else {
+        sendError(res, 500, "INTERNAL", err?.message ?? "Action failed");
+      }
+    }
+  }));
+}
+
+// src/manifest.ts
+import { SysSetting, SysSecret, SysSettingAudit } from "@objectstack/platform-objects/system";
+var SETTINGS_PLUGIN_ID = "com.objectstack.service.settings";
+var SETTINGS_PLUGIN_VERSION = "0.1.0";
+var settingsObjects = [SysSetting, SysSecret, SysSettingAudit];
+var settingsPluginManifestHeader = {
+  id: SETTINGS_PLUGIN_ID,
+  namespace: "sys",
+  version: SETTINGS_PLUGIN_VERSION,
+  type: "plugin",
+  scope: "project",
+  name: "Settings Service",
+  description: "Generic settings registry + K/V resolver with Env > Tenant > User > Default precedence. ADR-0007."
+};
+
+// src/manifests/mail.manifest.ts
+var manifest = {
+  namespace: "mail",
+  version: 1,
+  label: "Mail Delivery",
+  icon: "Mail",
+  description: "SMTP and transactional email provider configuration.",
+  scope: "global",
+  readPermission: "setup.access",
+  writePermission: "setup.write",
+  category: "Communication",
+  order: 10,
+  specifiers: [
+    {
+      type: "group",
+      id: "provider",
+      label: "Provider",
+      required: false,
+      description: "Choose how this workspace sends outbound email."
+    },
+    {
+      type: "select",
+      key: "provider",
+      label: "Provider",
+      required: true,
+      default: "smtp",
+      options: [
+        { value: "smtp", label: "SMTP" },
+        { value: "sendgrid", label: "SendGrid" },
+        { value: "ses", label: "Amazon SES" },
+        { value: "postmark", label: "Postmark" }
+      ]
+    },
+    { type: "group", id: "smtp", label: "SMTP", required: false, visible: "${data.provider === 'smtp'}" },
+    {
+      type: "text",
+      key: "smtp_host",
+      label: "Host",
+      required: true,
+      description: "Example: smtp.example.com",
+      visible: "${data.provider === 'smtp'}"
+    },
+    {
+      type: "number",
+      key: "smtp_port",
+      label: "Port",
+      required: false,
+      default: 587,
+      min: 1,
+      max: 65535,
+      visible: "${data.provider === 'smtp'}"
+    },
+    {
+      type: "toggle",
+      key: "smtp_secure",
+      label: "Use TLS",
+      required: false,
+      default: true,
+      visible: "${data.provider === 'smtp'}"
+    },
+    {
+      type: "text",
+      key: "smtp_user",
+      label: "Username",
+      required: false,
+      visible: "${data.provider === 'smtp'}"
+    },
+    {
+      type: "password",
+      key: "smtp_password",
+      label: "Password",
+      required: false,
+      visible: "${data.provider === 'smtp'}"
+    },
+    { type: "group", id: "api_key", label: "API key", required: false, visible: "${data.provider !== 'smtp'}" },
+    {
+      type: "password",
+      key: "api_key",
+      label: "API key",
+      required: true,
+      encrypted: true,
+      visible: "${data.provider !== 'smtp'}"
+    },
+    { type: "group", id: "from_address", label: "From address", required: false },
+    {
+      type: "email",
+      key: "from_email",
+      label: "From email",
+      required: true,
+      description: "Example: no-reply@example.com"
+    },
+    { type: "text", key: "from_name", label: "From name", required: false, default: "ObjectStack" },
+    {
+      type: "action_button",
+      id: "test",
+      label: "Send test email",
+      required: false,
+      icon: "Send",
+      handler: { kind: "http", method: "POST", url: "/api/settings/mail/test" }
+    }
+  ]
+};
+var mailSettingsManifest = manifest;
+var mailTestActionHandler = async ({ values }) => {
+  const provider = String(values.provider ?? "smtp");
+  const fromEmail = values.from_email;
+  if (!fromEmail) {
+    return { ok: false, severity: "error", message: "Configure a from address before testing." };
+  }
+  if (provider === "smtp" && !values.smtp_host) {
+    return { ok: false, severity: "error", message: "SMTP host is required." };
+  }
+  if (provider !== "smtp" && !values.api_key) {
+    return { ok: false, severity: "error", message: "API key is required." };
+  }
+  return {
+    ok: true,
+    severity: "info",
+    message: `Configuration looks valid (provider=${provider}). Wire @objectstack/plugin-mail for actual delivery.`
+  };
+};
+
+// src/manifests/branding.manifest.ts
+var brandingSettingsManifest = {
+  namespace: "branding",
+  version: 1,
+  label: "Branding",
+  icon: "Palette",
+  description: "Workspace name, logo, and accent colour.",
+  scope: "tenant",
+  readPermission: "setup.access",
+  writePermission: "setup.write",
+  category: "Workspace",
+  order: 5,
+  specifiers: [
+    { type: "group", id: "identity", label: "Identity", required: false },
+    {
+      type: "text",
+      key: "workspace_name",
+      label: "Workspace name",
+      required: true,
+      default: "ObjectStack",
+      minLength: 1,
+      maxLength: 60
+    },
+    {
+      type: "email",
+      key: "support_email",
+      label: "Support email",
+      required: false,
+      description: "Example: support@example.com"
+    },
+    { type: "group", id: "appearance", label: "Appearance", required: false },
+    {
+      type: "select",
+      key: "theme_mode",
+      label: "Default theme",
+      required: false,
+      default: "system",
+      options: [
+        { value: "light", label: "Light" },
+        { value: "dark", label: "Dark" },
+        { value: "system", label: "Match system" }
+      ]
+    },
+    { type: "color", key: "accent_color", label: "Accent colour", required: false, default: "#6366f1" },
+    {
+      type: "url",
+      key: "logo_url",
+      label: "Logo URL",
+      required: false,
+      description: "Example: https://\u2026/logo.svg"
+    }
+  ]
+};
+
+// src/manifests/feature-flags.manifest.ts
+var featureFlagsSettingsManifest = {
+  namespace: "feature_flags",
+  version: 1,
+  label: "Feature Flags",
+  icon: "FlaskConical",
+  description: "Toggle experimental and beta features for this workspace.",
+  scope: "tenant",
+  readPermission: "setup.access",
+  writePermission: "setup.write",
+  category: "Beta",
+  order: 100,
+  beta: true,
+  specifiers: [
+    {
+      type: "info_banner",
+      id: "beta_notice",
+      label: "Heads up",
+      required: false,
+      bannerText: "Beta features may change without notice. Pin via env vars (e.g. `FEATURE_FLAGS_AI_ENABLED=true`) to lock for the whole deployment.",
+      bannerSeverity: "warning"
+    },
+    { type: "group", id: "productivity", label: "Productivity", required: false },
+    {
+      type: "toggle",
+      key: "ai_enabled",
+      label: "AI Assistant",
+      required: false,
+      default: false,
+      description: "Enables the in-app AI assistant panel."
+    },
+    { type: "toggle", key: "kanban_swimlanes", label: "Kanban swimlanes", required: false, default: false },
+    { type: "group", id: "collaboration", label: "Collaboration", required: false },
+    { type: "toggle", key: "realtime_cursors", label: "Realtime cursors", required: false, default: false },
+    { type: "toggle", key: "inline_comments", label: "Inline comments", required: false, default: true }
+  ]
+};
+
+// src/manifests/storage.manifest.ts
+var manifest2 = {
+  namespace: "storage",
+  version: 1,
+  label: "File Storage",
+  icon: "HardDrive",
+  description: "Backend used for attachments, exports, and user uploads. \u26A0 Switching adapter does not migrate existing files \u2014 files uploaded under the previous adapter become unreachable through the new one.",
+  scope: "global",
+  readPermission: "setup.access",
+  writePermission: "setup.write",
+  category: "Infrastructure",
+  order: 20,
+  specifiers: [
+    {
+      type: "group",
+      id: "adapter",
+      label: "Backend",
+      required: false,
+      description: "Choose where uploaded files are stored."
+    },
+    {
+      type: "select",
+      key: "adapter",
+      label: "Adapter",
+      required: true,
+      default: "local",
+      options: [
+        { value: "local", label: "Local filesystem" },
+        { value: "s3", label: "S3 / S3-compatible" }
+      ]
+    },
+    {
+      type: "group",
+      id: "local",
+      label: "Local",
+      required: false,
+      visible: "${data.adapter === 'local'}"
+    },
+    {
+      type: "text",
+      key: "local_root",
+      label: "Root directory",
+      required: false,
+      default: "./.objectstack/data/uploads",
+      description: "Filesystem path under which files are stored. Relative paths resolve from the server CWD.",
+      visible: "${data.adapter === 'local'}"
+    },
+    {
+      type: "group",
+      id: "s3",
+      label: "S3",
+      required: false,
+      visible: "${data.adapter === 's3'}"
+    },
+    {
+      type: "text",
+      key: "s3_bucket",
+      label: "Bucket",
+      required: true,
+      description: "Shared host bucket. Per-project files are namespaced via the projects/<projectId>/ prefix.",
+      visible: "${data.adapter === 's3'}"
+    },
+    {
+      type: "text",
+      key: "s3_region",
+      label: "Region",
+      required: true,
+      description: "Example: us-east-1",
+      visible: "${data.adapter === 's3'}"
+    },
+    {
+      type: "text",
+      key: "s3_endpoint",
+      label: "Endpoint",
+      required: false,
+      description: "Custom endpoint for S3-compatible providers (R2, MinIO, Wasabi). Leave blank for AWS S3.",
+      visible: "${data.adapter === 's3'}"
+    },
+    {
+      type: "text",
+      key: "s3_access_key_id",
+      label: "Access key ID",
+      required: true,
+      visible: "${data.adapter === 's3'}"
+    },
+    {
+      type: "password",
+      key: "s3_secret_access_key",
+      label: "Secret access key",
+      required: true,
+      encrypted: true,
+      visible: "${data.adapter === 's3'}"
+    },
+    {
+      type: "toggle",
+      key: "s3_force_path_style",
+      label: "Force path-style URLs",
+      required: false,
+      default: false,
+      description: "Enable for MinIO and most S3-compatible providers; disable for AWS S3.",
+      visible: "${data.adapter === 's3'}"
+    },
+    { type: "group", id: "limits", label: "Limits", required: false },
+    {
+      type: "number",
+      key: "presigned_ttl",
+      label: "Presigned URL TTL (seconds)",
+      required: false,
+      default: 3600,
+      min: 60,
+      max: 604800
+    },
+    {
+      type: "number",
+      key: "session_ttl",
+      label: "Upload session TTL (seconds)",
+      required: false,
+      default: 86400,
+      min: 300,
+      max: 604800,
+      description: "How long a chunked-upload session stays resumable."
+    },
+    {
+      type: "number",
+      key: "max_upload_mb",
+      label: "Max upload size (MB)",
+      required: false,
+      default: 100,
+      min: 1,
+      max: 10240
+    },
+    {
+      type: "action_button",
+      id: "test",
+      label: "Test connection",
+      required: false,
+      icon: "Plug",
+      handler: { kind: "http", method: "POST", url: "/api/settings/storage/test" }
+    }
+  ]
+};
+var storageSettingsManifest = manifest2;
+var storageTestActionHandler = async ({ values }) => {
+  const adapter = String(values.adapter ?? "local");
+  if (adapter === "local") {
+    const root = values.local_root;
+    if (!root) {
+      return { ok: false, severity: "error", message: "Configure a root directory before testing." };
+    }
+    return {
+      ok: true,
+      severity: "info",
+      message: `Local adapter configured (root=${root}). Mount @objectstack/service-storage to exercise live I/O.`
+    };
+  }
+  if (adapter === "s3") {
+    const missing = [];
+    if (!values.s3_bucket) missing.push("s3_bucket");
+    if (!values.s3_region) missing.push("s3_region");
+    if (!values.s3_access_key_id) missing.push("s3_access_key_id");
+    if (!values.s3_secret_access_key) missing.push("s3_secret_access_key");
+    if (missing.length) {
+      return { ok: false, severity: "error", message: `Missing required field${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}` };
+    }
+    return {
+      ok: true,
+      severity: "info",
+      message: `S3 adapter configured (bucket=${values.s3_bucket}, region=${values.s3_region}). Mount @objectstack/service-storage to exercise live I/O.`
+    };
+  }
+  return { ok: false, severity: "error", message: `Unknown adapter: ${adapter}` };
+};
+
+// src/manifests/index.ts
+var builtinSettingsManifests = [
+  brandingSettingsManifest,
+  mailSettingsManifest,
+  storageSettingsManifest,
+  featureFlagsSettingsManifest
+];
+
+// src/translations/en.ts
+var en = {
+  settingsCommon: {
+    sourceLabels: {
+      env: "Env",
+      global: "Global",
+      tenant: "Tenant",
+      user: "User",
+      default: "Default"
+    }
+  },
+  settings: {
+    mail: {
+      title: "Mail Delivery",
+      description: "SMTP and transactional email provider configuration.",
+      groups: {
+        provider: { title: "Provider", description: "Choose how this workspace sends outbound email." },
+        smtp: { title: "SMTP" },
+        api_key: { title: "API key" },
+        from_address: { title: "From address" }
+      },
+      keys: {
+        provider: {
+          label: "Provider",
+          options: {
+            smtp: "SMTP",
+            sendgrid: "SendGrid",
+            ses: "Amazon SES",
+            postmark: "Postmark"
+          }
+        },
+        smtp_host: { label: "Host", help: "Example: smtp.example.com" },
+        smtp_port: { label: "Port" },
+        smtp_secure: { label: "Use TLS" },
+        smtp_user: { label: "Username" },
+        smtp_password: { label: "Password" },
+        api_key: { label: "API key" },
+        from_email: { label: "From email", help: "Example: no-reply@example.com" },
+        from_name: { label: "From name" }
+      },
+      actions: {
+        test: { label: "Send test email" }
+      }
+    },
+    branding: {
+      title: "Branding",
+      description: "Workspace name, logo, and accent colour.",
+      groups: {
+        identity: { title: "Identity" },
+        appearance: { title: "Appearance" }
+      },
+      keys: {
+        workspace_name: { label: "Workspace name" },
+        support_email: { label: "Support email", help: "Example: support@example.com" },
+        theme_mode: {
+          label: "Default theme",
+          options: { light: "Light", dark: "Dark", system: "Match system" }
+        },
+        accent_color: { label: "Accent colour" },
+        logo_url: { label: "Logo URL", help: "Example: https://\u2026/logo.svg" }
+      }
+    },
+    feature_flags: {
+      title: "Feature Flags",
+      description: "Toggle experimental and beta features for this workspace.",
+      groups: {
+        productivity: { title: "Productivity" },
+        collaboration: { title: "Collaboration" }
+      },
+      keys: {
+        ai_enabled: {
+          label: "AI Assistant",
+          help: "Enables the in-app AI assistant panel."
+        },
+        kanban_swimlanes: { label: "Kanban swimlanes" },
+        realtime_cursors: { label: "Realtime cursors" },
+        inline_comments: { label: "Inline comments" }
+      }
+    },
+    storage: {
+      title: "File Storage",
+      description: "Backend used for attachments, exports, and user uploads. \u26A0 Switching adapter does not migrate existing files \u2014 files uploaded under the previous adapter become unreachable through the new one.",
+      groups: {
+        adapter: { title: "Backend", description: "Choose where uploaded files are stored." },
+        local: { title: "Local" },
+        s3: { title: "S3" },
+        limits: { title: "Limits" }
+      },
+      keys: {
+        adapter: {
+          label: "Adapter",
+          options: { local: "Local filesystem", s3: "S3 / S3-compatible" }
+        },
+        local_root: {
+          label: "Root directory",
+          help: "Filesystem path under which files are stored. Relative paths resolve from the server CWD."
+        },
+        s3_bucket: {
+          label: "Bucket",
+          help: "Shared host bucket. Per-project files are namespaced via the projects/<projectId>/ prefix."
+        },
+        s3_region: { label: "Region", help: "Example: us-east-1" },
+        s3_endpoint: {
+          label: "Endpoint",
+          help: "Custom endpoint for S3-compatible providers (R2, MinIO, Wasabi). Leave blank for AWS S3."
+        },
+        s3_access_key_id: { label: "Access key ID" },
+        s3_secret_access_key: { label: "Secret access key" },
+        s3_force_path_style: {
+          label: "Force path-style URLs",
+          help: "Enable for MinIO and most S3-compatible providers; disable for AWS S3."
+        },
+        presigned_ttl: { label: "Presigned URL TTL (seconds)" },
+        session_ttl: {
+          label: "Upload session TTL (seconds)",
+          help: "How long a chunked-upload session stays resumable."
+        },
+        max_upload_mb: { label: "Max upload size (MB)" }
+      },
+      actions: {
+        test: { label: "Test connection" }
+      }
+    }
+  }
+};
+
+// src/translations/zh-CN.ts
+var zhCN = {
+  settingsCommon: {
+    sourceLabels: {
+      env: "\u73AF\u5883\u53D8\u91CF",
+      global: "\u5168\u5C40",
+      tenant: "\u79DF\u6237",
+      user: "\u7528\u6237",
+      default: "\u9ED8\u8BA4"
+    }
+  },
+  settings: {
+    mail: {
+      title: "\u90AE\u4EF6\u6295\u9012",
+      description: "SMTP \u4E0E\u4E8B\u52A1\u6027\u90AE\u4EF6\u670D\u52A1\u5546\u914D\u7F6E\u3002",
+      groups: {
+        provider: { title: "\u670D\u52A1\u5546", description: "\u9009\u62E9\u6B64\u5DE5\u4F5C\u533A\u5982\u4F55\u53D1\u9001\u90AE\u4EF6\u3002" },
+        smtp: { title: "SMTP" },
+        api_key: { title: "API \u5BC6\u94A5" },
+        from_address: { title: "\u53D1\u4EF6\u5730\u5740" }
+      },
+      keys: {
+        provider: {
+          label: "\u670D\u52A1\u5546",
+          options: {
+            smtp: "SMTP",
+            sendgrid: "SendGrid",
+            ses: "Amazon SES",
+            postmark: "Postmark"
+          }
+        },
+        smtp_host: { label: "\u4E3B\u673A", help: "\u793A\u4F8B:smtp.example.com" },
+        smtp_port: { label: "\u7AEF\u53E3" },
+        smtp_secure: { label: "\u542F\u7528 TLS" },
+        smtp_user: { label: "\u7528\u6237\u540D" },
+        smtp_password: { label: "\u5BC6\u7801" },
+        api_key: { label: "API \u5BC6\u94A5" },
+        from_email: { label: "\u53D1\u4EF6\u5730\u5740", help: "\u793A\u4F8B:no-reply@example.com" },
+        from_name: { label: "\u53D1\u4EF6\u4EBA\u540D\u79F0" }
+      },
+      actions: {
+        test: { label: "\u53D1\u9001\u6D4B\u8BD5\u90AE\u4EF6" }
+      }
+    },
+    branding: {
+      title: "\u54C1\u724C",
+      description: "\u5DE5\u4F5C\u533A\u540D\u79F0\u3001Logo \u4E0E\u4E3B\u9898\u8272\u3002",
+      groups: {
+        identity: { title: "\u8EAB\u4EFD" },
+        appearance: { title: "\u5916\u89C2" }
+      },
+      keys: {
+        workspace_name: { label: "\u5DE5\u4F5C\u533A\u540D\u79F0" },
+        support_email: { label: "\u5BA2\u670D\u90AE\u7BB1", help: "\u793A\u4F8B:support@example.com" },
+        theme_mode: {
+          label: "\u9ED8\u8BA4\u4E3B\u9898",
+          options: { light: "\u6D45\u8272", dark: "\u6DF1\u8272", system: "\u8DDF\u968F\u7CFB\u7EDF" }
+        },
+        accent_color: { label: "\u4E3B\u9898\u8272" },
+        logo_url: { label: "Logo \u94FE\u63A5", help: "\u793A\u4F8B:https://\u2026/logo.svg" }
+      }
+    },
+    feature_flags: {
+      title: "\u529F\u80FD\u5F00\u5173",
+      description: "\u4E3A\u5F53\u524D\u5DE5\u4F5C\u533A\u5F00\u542F\u5B9E\u9A8C\u6027\u4E0E\u6D4B\u8BD5\u529F\u80FD\u3002",
+      groups: {
+        productivity: { title: "\u751F\u4EA7\u529B" },
+        collaboration: { title: "\u534F\u4F5C" }
+      },
+      keys: {
+        ai_enabled: {
+          label: "AI \u52A9\u624B",
+          help: "\u542F\u7528\u5E94\u7528\u5185 AI \u52A9\u624B\u9762\u677F\u3002"
+        },
+        kanban_swimlanes: { label: "\u770B\u677F\u6CF3\u9053" },
+        realtime_cursors: { label: "\u5B9E\u65F6\u5149\u6807" },
+        inline_comments: { label: "\u884C\u5185\u8BC4\u8BBA" }
+      }
+    },
+    storage: {
+      title: "\u6587\u4EF6\u5B58\u50A8",
+      description: "\u9644\u4EF6\u3001\u5BFC\u51FA\u6587\u4EF6\u4E0E\u7528\u6237\u4E0A\u4F20\u6240\u4F7F\u7528\u7684\u5B58\u50A8\u540E\u7AEF\u3002\u26A0 \u5207\u6362\u9002\u914D\u5668\u4E0D\u4F1A\u8FC1\u79FB\u5DF2\u6709\u6587\u4EF6 \u2014\u2014 \u901A\u8FC7\u65E7\u9002\u914D\u5668\u4E0A\u4F20\u7684\u6587\u4EF6\uFF0C\u5728\u65B0\u9002\u914D\u5668\u4E2D\u5C06\u4E0D\u53EF\u8BBF\u95EE\u3002",
+      groups: {
+        adapter: { title: "\u5B58\u50A8\u540E\u7AEF", description: "\u9009\u62E9\u4E0A\u4F20\u6587\u4EF6\u7684\u5B58\u653E\u4F4D\u7F6E\u3002" },
+        local: { title: "\u672C\u5730" },
+        s3: { title: "S3" },
+        limits: { title: "\u9650\u5236" }
+      },
+      keys: {
+        adapter: {
+          label: "\u9002\u914D\u5668",
+          options: { local: "\u672C\u5730\u6587\u4EF6\u7CFB\u7EDF", s3: "S3 / S3 \u517C\u5BB9" }
+        },
+        local_root: {
+          label: "\u6839\u76EE\u5F55",
+          help: "\u6587\u4EF6\u5B58\u653E\u7684\u6587\u4EF6\u7CFB\u7EDF\u8DEF\u5F84\u3002\u76F8\u5BF9\u8DEF\u5F84\u76F8\u5BF9\u4E8E\u670D\u52A1\u8FDB\u7A0B\u7684\u5DE5\u4F5C\u76EE\u5F55\u3002"
+        },
+        s3_bucket: {
+          label: "Bucket",
+          help: "\u5171\u4EAB\u4E3B\u673A Bucket\u3002\u5404\u9879\u76EE\u7684\u6587\u4EF6\u901A\u8FC7 projects/<projectId>/ \u524D\u7F00\u8FDB\u884C\u9694\u79BB\u3002"
+        },
+        s3_region: { label: "\u533A\u57DF", help: "\u793A\u4F8B:us-east-1" },
+        s3_endpoint: {
+          label: "Endpoint",
+          help: "S3 \u517C\u5BB9\u670D\u52A1(R2\u3001MinIO\u3001Wasabi)\u7684\u81EA\u5B9A\u4E49 Endpoint;AWS S3 \u8BF7\u7559\u7A7A\u3002"
+        },
+        s3_access_key_id: { label: "Access Key ID" },
+        s3_secret_access_key: { label: "Secret Access Key" },
+        s3_force_path_style: {
+          label: "\u5F3A\u5236\u8DEF\u5F84\u98CE\u683C URL",
+          help: "MinIO \u4E0E\u5927\u591A\u6570 S3 \u517C\u5BB9\u670D\u52A1\u8BF7\u5F00\u542F;AWS S3 \u8BF7\u5173\u95ED\u3002"
+        },
+        presigned_ttl: { label: "\u9884\u7B7E\u540D URL \u6709\u6548\u671F(\u79D2)" },
+        session_ttl: {
+          label: "\u5206\u7247\u4E0A\u4F20\u4F1A\u8BDD\u6709\u6548\u671F(\u79D2)",
+          help: "\u5206\u7247\u4E0A\u4F20\u4F1A\u8BDD\u4FDD\u6301\u53EF\u7EED\u4F20\u7684\u65F6\u957F\u3002"
+        },
+        max_upload_mb: { label: "\u5355\u6587\u4EF6\u6700\u5927\u4E0A\u4F20(MB)" }
+      },
+      actions: {
+        test: { label: "\u6D4B\u8BD5\u8FDE\u63A5" }
+      }
+    }
+  }
+};
+
+// src/translations/ja-JP.ts
+var jaJP = {
+  settingsCommon: {
+    sourceLabels: {
+      env: "\u74B0\u5883\u5909\u6570",
+      global: "\u30B0\u30ED\u30FC\u30D0\u30EB",
+      tenant: "\u30C6\u30CA\u30F3\u30C8",
+      user: "\u30E6\u30FC\u30B6\u30FC",
+      default: "\u30C7\u30D5\u30A9\u30EB\u30C8"
+    }
+  },
+  settings: {
+    mail: {
+      title: "\u30E1\u30FC\u30EB\u914D\u4FE1",
+      description: "SMTP \u304A\u3088\u3073\u30C8\u30E9\u30F3\u30B6\u30AF\u30B7\u30E7\u30F3\u30E1\u30FC\u30EB\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC\u8A2D\u5B9A\u3002",
+      groups: {
+        provider: { title: "\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC", description: "\u3053\u306E\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9\u306E\u9001\u4FE1\u65B9\u6CD5\u3092\u9078\u629E\u3057\u307E\u3059\u3002" },
+        smtp: { title: "SMTP" },
+        api_key: { title: "API \u30AD\u30FC" },
+        from_address: { title: "\u5DEE\u51FA\u4EBA\u30A2\u30C9\u30EC\u30B9" }
+      },
+      keys: {
+        provider: {
+          label: "\u30D7\u30ED\u30D0\u30A4\u30C0\u30FC",
+          options: {
+            smtp: "SMTP",
+            sendgrid: "SendGrid",
+            ses: "Amazon SES",
+            postmark: "Postmark"
+          }
+        },
+        smtp_host: { label: "\u30DB\u30B9\u30C8", help: "\u4F8B: smtp.example.com" },
+        smtp_port: { label: "\u30DD\u30FC\u30C8" },
+        smtp_secure: { label: "TLS \u3092\u4F7F\u7528" },
+        smtp_user: { label: "\u30E6\u30FC\u30B6\u30FC\u540D" },
+        smtp_password: { label: "\u30D1\u30B9\u30EF\u30FC\u30C9" },
+        api_key: { label: "API \u30AD\u30FC" },
+        from_email: { label: "\u5DEE\u51FA\u4EBA\u30A2\u30C9\u30EC\u30B9", help: "\u4F8B: no-reply@example.com" },
+        from_name: { label: "\u5DEE\u51FA\u4EBA\u540D" }
+      },
+      actions: {
+        test: { label: "\u30C6\u30B9\u30C8\u30E1\u30FC\u30EB\u9001\u4FE1" }
+      }
+    },
+    branding: {
+      title: "\u30D6\u30E9\u30F3\u30C7\u30A3\u30F3\u30B0",
+      description: "\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9\u540D\u30FB\u30ED\u30B4\u30FB\u30A2\u30AF\u30BB\u30F3\u30C8\u30AB\u30E9\u30FC\u3002",
+      groups: {
+        identity: { title: "\u30A2\u30A4\u30C7\u30F3\u30C6\u30A3\u30C6\u30A3" },
+        appearance: { title: "\u5916\u89B3" }
+      },
+      keys: {
+        workspace_name: { label: "\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9\u540D" },
+        support_email: { label: "\u30B5\u30DD\u30FC\u30C8\u30E1\u30FC\u30EB", help: "\u4F8B: support@example.com" },
+        theme_mode: {
+          label: "\u30C7\u30D5\u30A9\u30EB\u30C8\u30C6\u30FC\u30DE",
+          options: { light: "\u30E9\u30A4\u30C8", dark: "\u30C0\u30FC\u30AF", system: "\u30B7\u30B9\u30C6\u30E0\u306B\u5F93\u3046" }
+        },
+        accent_color: { label: "\u30A2\u30AF\u30BB\u30F3\u30C8\u30AB\u30E9\u30FC" },
+        logo_url: { label: "\u30ED\u30B4 URL", help: "\u4F8B: https://\u2026/logo.svg" }
+      }
+    },
+    feature_flags: {
+      title: "\u6A5F\u80FD\u30D5\u30E9\u30B0",
+      description: "\u3053\u306E\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9\u3067\u5B9F\u9A13\u7684\u30FB\u30D9\u30FC\u30BF\u6A5F\u80FD\u3092\u5207\u66FF\u3048\u307E\u3059\u3002",
+      groups: {
+        productivity: { title: "\u751F\u7523\u6027" },
+        collaboration: { title: "\u30B3\u30E9\u30DC\u30EC\u30FC\u30B7\u30E7\u30F3" }
+      },
+      keys: {
+        ai_enabled: {
+          label: "AI \u30A2\u30B7\u30B9\u30BF\u30F3\u30C8",
+          help: "\u30A2\u30D7\u30EA\u5185 AI \u30A2\u30B7\u30B9\u30BF\u30F3\u30C8\u30D1\u30CD\u30EB\u3092\u6709\u52B9\u5316\u3057\u307E\u3059\u3002"
+        },
+        kanban_swimlanes: { label: "\u30AB\u30F3\u30D0\u30F3\u306E\u30B9\u30A4\u30E0\u30EC\u30FC\u30F3" },
+        realtime_cursors: { label: "\u30EA\u30A2\u30EB\u30BF\u30A4\u30E0\u30AB\u30FC\u30BD\u30EB" },
+        inline_comments: { label: "\u30A4\u30F3\u30E9\u30A4\u30F3\u30B3\u30E1\u30F3\u30C8" }
+      }
+    },
+    storage: {
+      title: "\u30D5\u30A1\u30A4\u30EB\u30B9\u30C8\u30EC\u30FC\u30B8",
+      description: "\u6DFB\u4ED8\u30D5\u30A1\u30A4\u30EB\u30FB\u30A8\u30AF\u30B9\u30DD\u30FC\u30C8\u30FB\u30E6\u30FC\u30B6\u30FC\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9\u306B\u4F7F\u7528\u3059\u308B\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u3002\u26A0 \u30A2\u30C0\u30D7\u30BF\u30FC\u3092\u5207\u66FF\u3048\u3066\u3082\u65E2\u5B58\u30D5\u30A1\u30A4\u30EB\u306F\u79FB\u884C\u3055\u308C\u307E\u305B\u3093\u3002\u4EE5\u524D\u306E\u30A2\u30C0\u30D7\u30BF\u30FC\u3067\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9\u3055\u308C\u305F\u30D5\u30A1\u30A4\u30EB\u306F\u65B0\u3057\u3044\u30A2\u30C0\u30D7\u30BF\u30FC\u304B\u3089\u30A2\u30AF\u30BB\u30B9\u3067\u304D\u306A\u304F\u306A\u308A\u307E\u3059\u3002",
+      groups: {
+        adapter: { title: "\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9", description: "\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9\u30D5\u30A1\u30A4\u30EB\u306E\u4FDD\u5B58\u5148\u3092\u9078\u629E\u3057\u307E\u3059\u3002" },
+        local: { title: "\u30ED\u30FC\u30AB\u30EB" },
+        s3: { title: "S3" },
+        limits: { title: "\u5236\u9650" }
+      },
+      keys: {
+        adapter: {
+          label: "\u30A2\u30C0\u30D7\u30BF\u30FC",
+          options: { local: "\u30ED\u30FC\u30AB\u30EB\u30D5\u30A1\u30A4\u30EB\u30B7\u30B9\u30C6\u30E0", s3: "S3 / S3 \u4E92\u63DB" }
+        },
+        local_root: {
+          label: "\u30EB\u30FC\u30C8\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA",
+          help: "\u30D5\u30A1\u30A4\u30EB\u3092\u4FDD\u5B58\u3059\u308B\u30D5\u30A1\u30A4\u30EB\u30B7\u30B9\u30C6\u30E0\u30D1\u30B9\u3002\u76F8\u5BFE\u30D1\u30B9\u306F\u30B5\u30FC\u30D0\u30FC\u306E CWD \u304B\u3089\u89E3\u6C7A\u3055\u308C\u307E\u3059\u3002"
+        },
+        s3_bucket: {
+          label: "\u30D0\u30B1\u30C3\u30C8",
+          help: "\u5171\u6709\u30DB\u30B9\u30C8\u30D0\u30B1\u30C3\u30C8\u3002\u30D7\u30ED\u30B8\u30A7\u30AF\u30C8\u6BCE\u306E\u30D5\u30A1\u30A4\u30EB\u306F projects/<projectId>/ \u30D7\u30EC\u30D5\u30A3\u30C3\u30AF\u30B9\u3067\u5206\u96E2\u3055\u308C\u307E\u3059\u3002"
+        },
+        s3_region: { label: "\u30EA\u30FC\u30B8\u30E7\u30F3", help: "\u4F8B: us-east-1" },
+        s3_endpoint: {
+          label: "\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8",
+          help: "S3 \u4E92\u63DB\u30D7\u30ED\u30D0\u30A4\u30C0 (R2, MinIO, Wasabi) \u306E\u30AB\u30B9\u30BF\u30E0\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3002AWS S3 \u306E\u5834\u5408\u306F\u7A7A\u6B04\u3002"
+        },
+        s3_access_key_id: { label: "\u30A2\u30AF\u30BB\u30B9\u30AD\u30FC ID" },
+        s3_secret_access_key: { label: "\u30B7\u30FC\u30AF\u30EC\u30C3\u30C8\u30A2\u30AF\u30BB\u30B9\u30AD\u30FC" },
+        s3_force_path_style: {
+          label: "\u30D1\u30B9\u30B9\u30BF\u30A4\u30EB URL \u3092\u5F37\u5236",
+          help: "MinIO \u3084\u591A\u304F\u306E S3 \u4E92\u63DB\u30D7\u30ED\u30D0\u30A4\u30C0\u3067\u6709\u52B9\u5316\u3002AWS S3 \u3067\u306F\u7121\u52B9\u5316\u3002"
+        },
+        presigned_ttl: { label: "\u7F72\u540D\u4ED8\u304D URL \u306E\u6709\u52B9\u671F\u9593 (\u79D2)" },
+        session_ttl: {
+          label: "\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9\u30BB\u30C3\u30B7\u30E7\u30F3 TTL (\u79D2)",
+          help: "\u30C1\u30E3\u30F3\u30AF\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9\u306E\u518D\u958B\u53EF\u80FD\u671F\u9593\u3002"
+        },
+        max_upload_mb: { label: "\u6700\u5927\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9\u30B5\u30A4\u30BA (MB)" }
+      },
+      actions: {
+        test: { label: "\u63A5\u7D9A\u30C6\u30B9\u30C8" }
+      }
+    }
+  }
+};
+
+// src/translations/index.ts
+var settingsBuiltinTranslations = {
+  en,
+  "zh-CN": zhCN,
+  "ja-JP": jaJP
+};
+
+// src/settings-service-plugin.ts
+var SettingsServicePlugin = class {
+  constructor(opts = {}) {
+    this.name = SETTINGS_PLUGIN_ID;
+    this.version = SETTINGS_PLUGIN_VERSION;
+    this.type = "standard";
+    this.service = null;
+    this.opts = {
+      ...opts,
+      manifests: opts.manifests ?? builtinSettingsManifests,
+      actionHandlers: opts.actionHandlers ?? {
+        mail: { test: mailTestActionHandler },
+        storage: { test: storageTestActionHandler }
+      }
+    };
+  }
+  async init(ctx) {
+    this.service = new SettingsService({
+      crypto: this.opts.crypto,
+      env: this.opts.env
+    });
+    for (const m of this.opts.manifests ?? []) this.service.registerManifest(m);
+    for (const [ns, handlers] of Object.entries(this.opts.actionHandlers ?? {})) {
+      for (const [id, fn] of Object.entries(handlers)) {
+        this.service.registerAction(ns, id, fn);
+      }
+    }
+    ctx.registerService("settings", this.service);
+    ctx.logger?.info?.(
+      `SettingsServicePlugin: registered (manifests=${this.opts.manifests?.length ?? 0})`
+    );
+    try {
+      ctx.getService("manifest").register({
+        ...settingsPluginManifestHeader,
+        objects: settingsObjects
+      });
+    } catch {
+    }
+  }
+  async start(ctx) {
+    if (!this.service) return;
+    ctx.hook("kernel:ready", async () => {
+      try {
+        const i18n = ctx.getService("i18n");
+        let loaded = 0;
+        for (const [locale, data] of Object.entries(settingsBuiltinTranslations)) {
+          if (data && typeof data === "object") {
+            try {
+              i18n.loadTranslations(locale, data);
+              loaded++;
+            } catch (err) {
+              ctx.logger?.warn?.(
+                `SettingsServicePlugin: failed to load translations for '${locale}': ${err?.message ?? err}`
+              );
+            }
+          }
+        }
+        if (loaded > 0) {
+          ctx.logger?.info?.(
+            `SettingsServicePlugin: contributed built-in translations (${loaded} locale${loaded > 1 ? "s" : ""})`
+          );
+        }
+      } catch {
+      }
+      let engine = null;
+      try {
+        engine = ctx.getService("objectql");
+      } catch {
+      }
+      if (engine) {
+        this.service.bindEngine(
+          engine,
+          this.buildAuditSink(ctx, engine),
+          {
+            secretStore: this.buildSecretStore(engine),
+            auditWriter: this.buildAuditWriter(ctx, engine),
+            cryptoProvider: this.opts.cryptoProvider ?? new InMemoryCryptoProvider()
+          }
+        );
+      }
+      if (this.opts.registerRoutes === false) return;
+      let http = null;
+      try {
+        http = ctx.getService("http-server");
+      } catch {
+      }
+      if (!http) {
+        ctx.logger?.warn?.(
+          'SettingsServicePlugin: no HTTP server available \u2014 REST routes not registered. SettingsService is still reachable via kernel.getService("settings").'
+        );
+        return;
+      }
+      registerSettingsRoutes(http, this.service, { basePath: this.opts.basePath });
+      ctx.logger?.info?.(
+        "SettingsServicePlugin: REST routes registered at " + (this.opts.basePath ?? "/api/settings")
+      );
+    });
+  }
+  /** Glue an `engine.insert('sys_audit_log', …)` audit sink. */
+  buildAuditSink(ctx, engine) {
+    return {
+      record: async (entry) => {
+        try {
+          await engine.insert?.("sys_audit_log", {
+            actor_id: entry.userId ?? null,
+            entity_type: "sys_setting",
+            entity_id: `${entry.namespace}.${entry.key}`,
+            action: entry.action,
+            payload: {
+              namespace: entry.namespace,
+              key: entry.key,
+              scope: entry.scope,
+              encrypted: entry.encrypted,
+              digest: entry.valueDigest
+            },
+            request_id: entry.requestId ?? null,
+            occurred_at: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } catch (err) {
+          ctx.logger?.warn?.("SettingsServicePlugin: audit record failed: " + (err?.message ?? err));
+        }
+      }
+    };
+  }
+  /**
+   * 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).
+   */
+  buildSecretStore(engine) {
+    const eng = 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.
+   */
+  buildAuditWriter(ctx, engine) {
+    const eng = 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: (/* @__PURE__ */ new Date()).toISOString()
+          }, { bypassTenantAudit: true });
+        } catch (err) {
+          ctx.logger?.warn?.("SettingsServicePlugin: setting-audit write failed: " + (err?.message ?? err));
+        }
+      }
+    };
+  }
+};
+export {
+  NoopCryptoAdapter,
+  SETTINGS_PLUGIN_ID,
+  SETTINGS_PLUGIN_VERSION,
+  SettingsLockedError,
+  SettingsService,
+  SettingsServicePlugin,
+  UnknownKeyError,
+  UnknownNamespaceError,
+  brandingSettingsManifest,
+  builtinSettingsManifests,
+  envKeyOf,
+  featureFlagsSettingsManifest,
+  mailSettingsManifest,
+  mailTestActionHandler,
+  registerSettingsRoutes,
+  settingsBuiltinTranslations,
+  settingsObjects,
+  settingsPluginManifestHeader,
+  en as settingsTranslationsEn,
+  jaJP as settingsTranslationsJaJP,
+  zhCN as settingsTranslationsZhCN,
+  storageSettingsManifest,
+  storageTestActionHandler
+};
+//# sourceMappingURL=index.js.map