@objectstack/service-settings 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,601 @@
+import * as _objectstack_spec_contracts from '@objectstack/spec/contracts';
+import { ICryptoProvider, IHttpRequest, IHttpServer } from '@objectstack/spec/contracts';
+import { SettingsActionResult, SpecifierScope, SettingsChangeHandler, SettingsUnsubscribe, SettingsManifest, ResolvedSettingValue, SettingsNamespacePayload, TranslationData, TranslationBundle } from '@objectstack/spec/system';
+export { ResolvedSettingValue, SettingsActionResult, SettingsManifest, SettingsNamespacePayload, SpecifierScope } from '@objectstack/spec/system';
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * Pluggable adapter for at-rest encryption of `Specifier.encrypted: true`
+ * values. The default {@link NoopCryptoAdapter} provides a transparent
+ * base64 wrapping suitable for development and tests; production
+ * deployments MUST inject a real KMS-backed adapter.
+ *
+ * encrypt/decrypt are async to leave room for KMS round-trips.
+ */
+interface CryptoAdapter {
+    /** Returns the ciphertext blob to store in `sys_setting.value_enc`. */
+    encrypt(plaintext: string, ctx: {
+        namespace: string;
+        key: string;
+    }): Promise<string>;
+    /** Returns the plaintext used by the resolver. */
+    decrypt(ciphertext: string, ctx: {
+        namespace: string;
+        key: string;
+    }): Promise<string>;
+    /**
+     * Stable, short, non-reversible digest used for audit-log entries so
+     * operators can correlate value changes without leaking secrets.
+     */
+    digest(plaintext: string): string;
+}
+/**
+ * Development / test default. Base64-wraps the plaintext so the column
+ * isn't a literal mirror but provides no real confidentiality.
+ *
+ * Operators are expected to override this via
+ * `SettingsServicePluginOptions.crypto`.
+ */
+declare class NoopCryptoAdapter implements CryptoAdapter {
+    encrypt(plaintext: string): Promise<string>;
+    decrypt(ciphertext: string): Promise<string>;
+    digest(plaintext: string): string;
+}
+
+/** Caller identity used by the resolver and audit log. */
+interface SettingsContext {
+    /** Calling user id, when known. Required for `scope: 'user'` reads. */
+    userId?: string;
+    /** Tenant / project id. Reserved for multi-tenant deployments. */
+    tenantId?: string;
+    /** Permissions held by the caller (used by REST authz). */
+    permissions?: string[];
+    /** Source IP / request id for audit correlation. */
+    requestId?: string;
+}
+/** Storage row shape used by both the engine and the in-memory store. */
+interface SettingsRow {
+    namespace: string;
+    key: string;
+    scope: SpecifierScope;
+    user_id: string | null;
+    value: unknown | null;
+    value_enc: string | null;
+    encrypted: boolean;
+    /**
+     * When true, lower-scope rows for the same (namespace, key) are
+     * read-only — the resolver still returns this row's value and the
+     * mutation API throws `SettingsLockedError`. Only meaningful on
+     * upper-scope rows (`global`, `tenant`). (Phase 2)
+     */
+    locked?: boolean;
+    /** Human-readable reason the lock was applied (UI tooltip). */
+    locked_reason?: string | null;
+    updated_at?: string;
+    updated_by?: string | null;
+}
+/**
+ * Minimal data-engine surface used by the SettingsService. Mirrors the
+ * methods we actually call so we can stub it cleanly in tests without
+ * pulling the whole `IDataEngine`.
+ */
+interface SettingsEngine {
+    find(objectName: string, opts: {
+        where?: Record<string, unknown>;
+        limit?: number;
+        bypassTenantAudit?: boolean;
+    }): Promise<any[]>;
+    insert(objectName: string, data: Record<string, unknown>, opts?: {
+        bypassTenantAudit?: boolean;
+    }): Promise<any>;
+    update(objectName: string, opts: {
+        where: Record<string, unknown>;
+        data: Record<string, unknown>;
+        bypassTenantAudit?: boolean;
+    }): Promise<any>;
+    delete?(objectName: string, opts: {
+        where: Record<string, unknown>;
+    }): Promise<any>;
+}
+/** Optional audit hook — service-settings won't crash if absent. */
+interface SettingsAuditSink {
+    record(entry: {
+        namespace: string;
+        key: string;
+        scope: SpecifierScope;
+        userId?: string;
+        actor?: string;
+        action: 'set' | 'reset';
+        valueDigest: string;
+        encrypted: boolean;
+        requestId?: string;
+    }): Promise<void> | void;
+}
+/**
+ * Persistence hook for the `sys_secret` object — used by the secret
+ * split introduced in Phase 3. When provided, `SettingsService` writes
+ * encrypted specifier values via `ICryptoProvider` into `sys_secret`
+ * and stores only the handle id in `sys_setting.value_enc`. When
+ * absent, the legacy inline `crypto.encrypt → value_enc` path is used.
+ */
+interface SettingsSecretStore {
+    /** Insert a new secret row; returns the row id (handle id). */
+    insert(row: {
+        id: string;
+        namespace: string;
+        key: string;
+        kms_key_id: string;
+        alg: string;
+        version: number;
+        ciphertext: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Look up the latest ciphertext for a handle id; null when missing. */
+    get(id: string): Promise<{
+        id: string;
+        namespace: string;
+        key: string;
+        kms_key_id: string;
+        alg: string;
+        version: number;
+        ciphertext: string;
+    } | null>;
+    /** Replace an existing secret row (used by rotateKey). */
+    update(id: string, patch: {
+        kms_key_id?: string;
+        alg?: string;
+        version?: number;
+        ciphertext?: string;
+    }): Promise<void>;
+}
+/**
+ * Append-only writer for the `sys_setting_audit` object — Phase 3
+ * audit trail. Distinct from `SettingsAuditSink` (which still writes
+ * to the generic `sys_audit_log`) so audit consumers can subscribe
+ * to settings activity without scanning the firehose.
+ */
+interface SettingsAuditWriter {
+    write(entry: {
+        namespace: string;
+        key: string;
+        scope: SpecifierScope;
+        action: 'set' | 'reset' | 'lock' | 'unlock' | 'rotate';
+        source?: 'ui' | 'api' | 'migration' | 'import' | 'system';
+        actorId?: string;
+        oldHash?: string | null;
+        newHash?: string | null;
+        encrypted: boolean;
+        requestId?: string;
+        reason?: string;
+    }): Promise<void> | void;
+}
+/** Action handler signature for `Specifier.type === 'action_button'`. */
+type SettingsActionHandler = (input: {
+    namespace: string;
+    actionId: string;
+    values: Record<string, unknown>;
+    payload?: unknown;
+    ctx: SettingsContext;
+}) => Promise<SettingsActionResult> | SettingsActionResult;
+interface SettingsServiceOptions {
+    /** Persistence engine. When undefined, an in-memory store is used. */
+    engine?: SettingsEngine;
+    /** Crypto adapter for `encrypted` values. Defaults to NoopCryptoAdapter. */
+    crypto?: CryptoAdapter;
+    /**
+     * Phase 3 ICryptoProvider used together with `secretStore`. When both
+     * are wired, encrypted writes flow to `sys_secret` and `value_enc`
+     * holds the handle id. When omitted, the legacy inline `crypto`
+     * adapter path remains in effect (back-compat).
+     */
+    cryptoProvider?: _objectstack_spec_contracts.ICryptoProvider;
+    /** Phase 3 secret store backing the `sys_secret` object. */
+    secretStore?: SettingsSecretStore;
+    /** Audit sink. When undefined, writes still succeed but are not logged. */
+    audit?: SettingsAuditSink;
+    /** Phase 3 dedicated writer for `sys_setting_audit`. */
+    auditWriter?: SettingsAuditWriter;
+    /**
+     * `process.env`-like map. Defaults to `process.env`. Injected so
+     * unit tests can simulate locked values without polluting the host
+     * environment.
+     */
+    env?: Record<string, string | undefined>;
+    /** Object name backing the K/V store. Defaults to 'sys_setting'. */
+    objectName?: string;
+}
+/**
+ * Convert `(namespace, key)` to the env var convention defined in
+ * ADR-0007: uppercase, dots → underscores, hyphens → underscores.
+ */
+declare function envKeyOf(namespace: string, key: string): string;
+/** Thrown when a caller tries to write a value pinned by env. */
+declare class SettingsLockedError extends Error {
+    readonly namespace: string;
+    readonly key: string;
+    readonly reason: string;
+    readonly code: "SETTINGS_LOCKED";
+    constructor(namespace: string, key: string, reason?: string);
+}
+/** Thrown when the requested namespace has no registered manifest. */
+declare class UnknownNamespaceError extends Error {
+    readonly namespace: string;
+    readonly code: "SETTINGS_UNKNOWN_NAMESPACE";
+    constructor(namespace: string);
+}
+/** Thrown when a key isn't declared by the namespace's manifest. */
+declare class UnknownKeyError extends Error {
+    readonly namespace: string;
+    readonly key: string;
+    readonly code: "SETTINGS_UNKNOWN_KEY";
+    constructor(namespace: string, key: string);
+}
+
+/**
+ * Concrete SettingsService. See `src/settings-service.types.ts` for
+ * the supporting types and `README.md` for the high-level contract.
+ */
+declare class SettingsService {
+    private engine?;
+    private readonly crypto;
+    private cryptoProvider?;
+    private secretStore?;
+    private audit?;
+    private auditWriter?;
+    private readonly env;
+    private readonly objectName;
+    private readonly registry;
+    /** In-memory fallback when no engine is wired. */
+    private readonly memory;
+    /** Change subscribers, optionally scoped to a namespace. */
+    private readonly subscribers;
+    constructor(opts?: SettingsServiceOptions);
+    /**
+     * 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: SettingsEngine, audit?: SettingsAuditSink, extras?: {
+        secretStore?: SettingsSecretStore;
+        auditWriter?: SettingsAuditWriter;
+        cryptoProvider?: _objectstack_spec_contracts.ICryptoProvider;
+    }): void;
+    /**
+     * 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.
+     */
+    private scopeRank;
+    /**
+     * 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: string | undefined, handler: SettingsChangeHandler): SettingsUnsubscribe;
+    /**
+     * 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.
+     */
+    private emitChange;
+    /** Register (or replace) a manifest. Idempotent. */
+    registerManifest(manifest: SettingsManifest): void;
+    /** Look up a manifest, or throw `UnknownNamespaceError`. */
+    getManifest(namespace: string): SettingsManifest;
+    /** List all registered manifests, optionally filtered by permission. */
+    listManifests(ctx?: SettingsContext): SettingsManifest[];
+    /** Register a handler for an `action_button` declared in a manifest. */
+    registerAction(namespace: string, actionId: string, handler: SettingsActionHandler): void;
+    /** Resolve a single key. */
+    get<T = unknown>(namespace: string, key: string, ctx?: SettingsContext): Promise<ResolvedSettingValue<T>>;
+    /** Resolve every value in a namespace + return the manifest. */
+    getNamespace(namespace: string, ctx?: SettingsContext): Promise<SettingsNamespacePayload>;
+    /**
+     * 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).
+     */
+    createClient<T extends Record<string, unknown> = Record<string, unknown>>(namespace: string, opts?: {
+        ctx?: SettingsContext;
+        parse?: (raw: Record<string, unknown>) => T;
+    }): Promise<{
+        readonly namespace: string;
+        readonly current: T;
+        get<K extends keyof T>(key: K): T[K];
+        onChange(handler: SettingsChangeHandler): SettingsUnsubscribe;
+        refresh(): Promise<void>;
+        dispose(): void;
+    }>;
+    private snapshotOf;
+    /** Persist a single key. Throws SettingsLockedError when env-locked. */
+    set(namespace: string, key: string, value: unknown, ctx?: SettingsContext): Promise<ResolvedSettingValue>;
+    /** Persist multiple keys atomically (best-effort). */
+    setMany(namespace: string, patch: Record<string, unknown>, ctx?: SettingsContext): Promise<Record<string, ResolvedSettingValue>>;
+    /** Invoke a declared action (test connection, rotate, …). */
+    runAction(namespace: string, actionId: string, payload: unknown, ctx?: SettingsContext): Promise<SettingsActionResult>;
+    private loadRows;
+    private upsertRow;
+    private materialiseRow;
+}
+
+/** Configuration options for the SettingsServicePlugin. */
+interface SettingsServicePluginOptions {
+    /**
+     * Pre-register these manifests at boot. When omitted, the bundled
+     * builtin manifests (mail / branding / feature_flags) are loaded so
+     * a host gets a working Settings hub out of the box. Pass an empty
+     * array to opt out entirely.
+     */
+    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. */
+    registerRoutes?: boolean;
+    /** Override the env source. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /**
+     * Action handlers to register at boot, keyed by namespace and action
+     * id. The bundled `mail.test` handler is registered automatically
+     * unless this object is provided.
+     */
+    actionHandlers?: Record<string, Record<string, SettingsActionHandler>>;
+}
+/**
+ * SettingsServicePlugin — wires the SettingsService into the kernel.
+ *
+ *  1. `init`: instantiate the service, register it under `'settings'`,
+ *     and ship `sys_setting` to the manifest service so the engine
+ *     auto-provisions the table.
+ *  2. `start` → `kernel:ready`: bind the data engine (when present),
+ *     wire the audit sink (when present), mount REST routes.
+ */
+declare class SettingsServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    private readonly opts;
+    private service;
+    constructor(opts?: SettingsServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    /** Glue an `engine.insert('sys_audit_log', …)` audit sink. */
+    private buildAuditSink;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+
+/**
+ * REST surface for the SettingsService — see ADR-0007 §REST.
+ *
+ *   GET    /api/settings                       → visible manifests
+ *   GET    /api/settings/:namespace            → { manifest, values }
+ *   PUT    /api/settings/:namespace            → batch upsert
+ *   POST   /api/settings/:namespace/:actionId  → invoke declared action
+ *
+ * The route layer is a thin wrapper that maps thrown service errors
+ * into proper HTTP status codes; all business logic lives in
+ * `SettingsService`.
+ */
+
+interface SettingsRoutesOptions {
+    /** Base path. Default `/api/settings`. */
+    basePath?: string;
+    /**
+     * Extract caller identity from the request. The default reads
+     * `x-user-id` / `x-tenant-id` headers and parses
+     * `x-permissions` as a comma-separated list — fine for dev and
+     * straightforward to override in production wiring.
+     */
+    contextFromRequest?: (req: IHttpRequest) => SettingsContext;
+}
+declare function registerSettingsRoutes(http: IHttpServer, service: SettingsService, opts?: SettingsRoutesOptions): void;
+
+declare const SETTINGS_PLUGIN_ID = "com.objectstack.service.settings";
+declare const SETTINGS_PLUGIN_VERSION = "0.1.0";
+/** Objects owned by service-settings. Currently just the K/V store. */
+declare const settingsObjects: any[];
+/** Manifest header shared by compile-time config and runtime registration. */
+declare const settingsPluginManifestHeader: {
+    id: string;
+    namespace: string;
+    version: string;
+    type: "plugin";
+    scope: "project";
+    name: string;
+    description: string;
+};
+
+/** Mail Delivery — SMTP / API provider configuration. */
+declare const mailSettingsManifest: SettingsManifest;
+/** Built-in action handler stub for `mail/test`. */
+declare const mailTestActionHandler: SettingsActionHandler;
+
+/** Branding — workspace identity (name, logo, theme). */
+declare const brandingSettingsManifest: SettingsManifest;
+
+/** Feature Flags — opt into experimental capabilities. */
+declare const featureFlagsSettingsManifest: SettingsManifest;
+
+/** File Storage — local FS / S3-compatible backend configuration. */
+declare const storageSettingsManifest: SettingsManifest;
+/**
+ * Built-in fallback action handler for `storage/test`. The real
+ * implementation lives in `@objectstack/service-storage` and is
+ * registered by `StorageServicePlugin` on `kernel:ready` (it overrides
+ * this stub via `registerAction`). This fallback only validates the
+ * form so the button is still useful when the storage plugin is
+ * absent (e.g. in a unit-test kernel that mounts settings only).
+ */
+declare const storageTestActionHandler: SettingsActionHandler;
+
+/** Reference manifests bundled with service-settings. */
+
+/** Convenience aggregate — pass to `SettingsServicePlugin({ manifests })`. */
+declare const builtinSettingsManifests: {
+    namespace: string;
+    version: number;
+    label: string;
+    scope: "global" | "tenant" | "user";
+    readPermission: string;
+    writePermission: string;
+    specifiers: {
+        type: "number" | "group" | "info_banner" | "child_pane" | "title_value" | "action_button" | "email" | "phone" | "password" | "text" | "url" | "json" | "textarea" | "toggle" | "select" | "multiselect" | "radio" | "color" | "slider";
+        label: string;
+        required: boolean;
+        id?: string | undefined;
+        key?: string | undefined;
+        description?: string | undefined;
+        icon?: string | undefined;
+        default?: unknown;
+        visible?: {
+            dialect: "cel" | "js" | "cron" | "template";
+            source?: string | undefined;
+            ast?: unknown;
+            meta?: {
+                rationale?: string | undefined;
+                generatedBy?: string | undefined;
+            } | undefined;
+        } | {
+            dialect: "cel" | "js" | "cron" | "template";
+            source?: string | undefined;
+            ast?: unknown;
+            meta?: {
+                rationale?: string | undefined;
+                generatedBy?: string | undefined;
+            } | undefined;
+        } | undefined;
+        encrypted?: boolean | undefined;
+        scope?: "global" | "tenant" | "user" | undefined;
+        availableScopes?: ("global" | "tenant" | "user")[] | undefined;
+        lockable?: boolean | undefined;
+        readPermission?: string | undefined;
+        writePermission?: string | undefined;
+        deprecated?: boolean | undefined;
+        replacedBy?: string | undefined;
+        options?: {
+            value: string | number | boolean;
+            label: string;
+            description?: string | undefined;
+            icon?: string | undefined;
+        }[] | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        step?: number | undefined;
+        minLength?: number | undefined;
+        maxLength?: number | undefined;
+        pattern?: string | undefined;
+        rows?: number | undefined;
+        handler?: {
+            kind: "http";
+            method: "GET" | "PUT" | "POST" | "DELETE" | "PATCH";
+            url: string;
+            body?: Record<string, unknown> | undefined;
+            confirmText?: string | undefined;
+        } | {
+            kind: "action";
+            name: string;
+            params?: Record<string, unknown> | undefined;
+            confirmText?: string | undefined;
+        } | {
+            kind: "navigate";
+            url: string;
+            target: "_self" | "_blank";
+        } | undefined;
+        childNamespace?: string | undefined;
+        bannerText?: string | undefined;
+        bannerSeverity?: "error" | "success" | "info" | "warning" | undefined;
+    }[];
+    icon?: string | undefined;
+    description?: string | undefined;
+    helpText?: string | undefined;
+    category?: string | undefined;
+    order?: number | undefined;
+    visible?: {
+        dialect: "cel" | "js" | "cron" | "template";
+        source?: string | undefined;
+        ast?: unknown;
+        meta?: {
+            rationale?: string | undefined;
+            generatedBy?: string | undefined;
+        } | undefined;
+    } | {
+        dialect: "cel" | "js" | "cron" | "template";
+        source?: string | undefined;
+        ast?: unknown;
+        meta?: {
+            rationale?: string | undefined;
+            generatedBy?: string | undefined;
+        } | undefined;
+    } | undefined;
+    featureFlag?: string | undefined;
+    beta?: boolean | undefined;
+}[];
+
+/**
+ * English (en) — built-in settings manifest translations.
+ *
+ * Mirrors literals in `manifests/{mail,branding,feature-flags,storage}.manifest.ts`.
+ * Keeping them explicit here lets the resolver chain (locale → fallback → literal)
+ * always have at least an English entry to fall back to.
+ */
+declare const en: TranslationData;
+
+/**
+ * 简体中文 (zh-CN) — built-in settings manifest translations.
+ */
+declare const zhCN: TranslationData;
+
+/**
+ * 日本語 (ja-JP) — built-in settings manifest translations.
+ */
+declare const jaJP: TranslationData;
+
+/**
+ * Built-in Settings translations.
+ *
+ * Mirrors the CRM example's `src/translations/{en,zh-CN,ja-JP}.ts` convention —
+ * one file per locale, aggregated into a `TranslationBundle` here.
+ *
+ * Hosts merge `settingsBuiltinTranslations` into the i18next resource tree
+ * under whatever namespace makes sense (the console wires it as `system`),
+ * making keys resolvable as `<ns>.settings.<namespace>.{title,description,...}`.
+ */
+
+declare const settingsBuiltinTranslations: TranslationBundle;
+
+export { type CryptoAdapter, 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 };