@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/config/configuration-redaction.js

@@ -0,0 +1,128 @@
+const unsupportedApplicators = Object.freeze([
+    'if', 'then', 'else', 'not', 'contains', 'dependencies', 'dependentSchemas',
+    '$dynamicRef', '$recursiveRef', '$dynamicAnchor', 'unevaluatedProperties', 'unevaluatedItems',
+]);
+/** Shared proof limit: these branches/resources need a resolver we do not provide. */
+export function isUnknownConfigurationSchemaBoundary(schema, root) {
+    return schema !== root && Object.hasOwn(schema, '$id')
+        || unsupportedApplicators.some(keyword => Object.hasOwn(schema, keyword))
+        || schema.$ref !== undefined && (typeof schema.$ref !== 'string' || !schema.$ref.startsWith('#/') || /~(?![01])/u.test(schema.$ref));
+}
+/** Credential names, excluding ordinary budgets such as maxTokens and tokenLimit. */
+export function sensitiveConfigKey(key) {
+    const normalized = key.replace(/[^a-z0-9]/giu, '').toLowerCase();
+    return /(?:password|passwd|secret|apikey|accesskey|privatekey|encrypt(?:ion)?key|encodingaeskey|credential|authorization|cookie)/u.test(normalized)
+        || normalized === 'pwd' || /(?:^|api|access|refresh|auth|bearer|bot|oauth|session|private|client|app|verify|verification)tokens?(?:v[0-9]+)?$/u.test(normalized);
+}
+export const REDACTED_CONFIG_VALUE = '[redacted]';
+const MAX_DEPTH = 32;
+// Retain uncertainty without changing the non-strict masker's best-effort behavior.
+const unresolvedSchema = Object.freeze({});
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function sensitiveSchema(schema) {
+    const metadata = schema['x-zhin-config'];
+    // `hidden` mirrors the configuration explanation contract: hidden fields are never echoed.
+    return schema.writeOnly === true || schema.secret === true || schema.hidden === true
+        || schema.format === 'password' || schema.component === 'password'
+        || record(metadata) && (metadata.secret === true || metadata.hidden === true || metadata.component === 'password');
+}
+/** Expands local `$ref` and every combinator branch; any branch's annotation applies. */
+function expand(node, root, seen = new Set()) {
+    if (!record(node) || seen.has(node) || seen.size > MAX_DEPTH)
+        return [unresolvedSchema];
+    const nextSeen = new Set([...seen, node]);
+    const nodes = [node];
+    if (typeof node.$ref === 'string' && node.$ref.startsWith('#/')) {
+        let referenced = root;
+        for (const raw of node.$ref.slice(2).split('/')) {
+            const key = raw.replaceAll('~1', '/').replaceAll('~0', '~');
+            referenced = record(referenced) && Object.hasOwn(referenced, key) ? referenced[key] : undefined;
+        }
+        nodes.push(...expand(referenced, root, nextSeen));
+    }
+    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+        const branches = node[keyword];
+        if (Array.isArray(branches))
+            for (const branch of branches)
+                nodes.push(...expand(branch, root, nextSeen));
+    }
+    return nodes;
+}
+function children(nodes, key, root) {
+    const next = [];
+    for (const node of nodes) {
+        let matched = false;
+        if (record(node.properties) && Object.hasOwn(node.properties, key)) {
+            next.push(...expand(node.properties[key], root));
+            matched = true;
+        }
+        if (record(node.patternProperties)) {
+            for (const [pattern, child] of Object.entries(node.patternProperties)) {
+                let test = false;
+                try {
+                    test = new RegExp(pattern, 'u').test(key);
+                }
+                catch {
+                    test = false;
+                }
+                if (test) {
+                    next.push(...expand(child, root));
+                    matched = true;
+                }
+            }
+        }
+        if (!matched && record(node.additionalProperties))
+            next.push(...expand(node.additionalProperties, root));
+        if (/^(?:0|[1-9][0-9]*)$/u.test(key)) {
+            const index = Number(key);
+            if (Array.isArray(node.prefixItems) && index < node.prefixItems.length)
+                next.push(...expand(node.prefixItems[index], root));
+            else if (record(node.items))
+                next.push(...expand(node.items, root));
+        }
+    }
+    return next;
+}
+function maskTree(value, nodes, root, depth, hidden) {
+    if (nodes.some(hidden))
+        return REDACTED_CONFIG_VALUE;
+    if (typeof value === 'string')
+        return /\$\{|^env:\/\//u.test(value) ? REDACTED_CONFIG_VALUE : value;
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth >= MAX_DEPTH)
+        return REDACTED_CONFIG_VALUE;
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((item, index) => maskTree(item, children(nodes, String(index), root), root, depth + 1, hidden)));
+    }
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key,
+        sensitiveConfigKey(key) ? REDACTED_CONFIG_VALUE : maskTree(item, children(nodes, key, root), root, depth + 1, hidden)])));
+}
+/**
+ * Masks `value`, stored at `path` (first segment is the section) under `sectionSchema`.
+ * A missing schema still applies key and environment-reference masking.
+ * `unknownSchema: 'redact'` (project reads and conflict evidence) also replaces any value under a schema
+ * boundary this masker cannot prove (`if`/`not`/`contains`/…, nested `$id`, non-local
+ * `$ref`; the chat policy's {@link isUnknownConfigurationSchemaBoundary}), since a secret
+ * annotation could hide behind it.
+ */
+export function maskConfigValue(sectionSchema, path, value, options = {}) {
+    const root = record(sectionSchema) ? sectionSchema : {};
+    const hidden = options.unknownSchema === 'redact'
+        ? node => node === unresolvedSchema || sensitiveSchema(node) || isUnknownConfigurationSchemaBoundary(node, root) : sensitiveSchema;
+    let nodes = record(sectionSchema) ? expand(sectionSchema, root) : [];
+    if (path.length > 0 && sensitiveConfigKey(path[0]))
+        return REDACTED_CONFIG_VALUE;
+    if (nodes.some(hidden))
+        return REDACTED_CONFIG_VALUE;
+    for (const key of path.slice(1)) {
+        if (sensitiveConfigKey(key))
+            return REDACTED_CONFIG_VALUE;
+        nodes = children(nodes, key, root);
+        if (nodes.some(hidden))
+            return REDACTED_CONFIG_VALUE;
+    }
+    return maskTree(value, nodes, root, 0, hidden);
+}

package/lib/config/configuration.d.ts

@@ -0,0 +1,81 @@
+import { type ConsoleConfigApplication, type ConsoleConfigApplicationStatus, type ConsoleConfigApplyResult, type ConsoleConfigPatchRequest, type ConsoleConfigPatchResult, type ConsoleConfigProjectPatchResult, type ConsoleConfigProjectRead, type ConsoleConfigProjectReadRequest, type ConsoleConfigSource } from '@zhin.js/console-protocol';
+import type { PluginConfigValidation } from '@zhin.js/host-http';
+import { type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+import { type ConfigFileDocument, type EnvStore } from '@zhin.js/runtime';
+export interface ChatConfigurationField {
+    readonly path: readonly string[];
+    readonly type: readonly string[];
+}
+export interface ChatConfigurationRead {
+    readonly revision: string;
+    /** `get`: the single leaf value (already proven non-sensitive). */
+    readonly value?: unknown;
+    /** `fields`: chat-manageable leaves under the scope; never values. */
+    readonly fields?: readonly ChatConfigurationField[];
+}
+/** A Host-classified rejection before this operation attempted any commit. */
+export declare class ConfigChatRequestRejectedError extends Error {
+    readonly code = "configuration_request_rejected";
+    constructor();
+}
+/** Owns one project's Console configuration projection over the Root config authority. */
+export declare class ConsoleConfigurationStore {
+    #private;
+    constructor(options: {
+        readonly projectRoot: string;
+        readonly document: ConfigFileDocument;
+        readonly configDeclarations?: () => ReadonlyMap<string, Readonly<Record<string, unknown>>> | Promise<ReadonlyMap<string, Readonly<Record<string, unknown>>>>;
+        readonly environmentName?: string | (() => string);
+        readonly environmentForPlugin?: (pluginName: string) => Pick<EnvStore, 'has'> | undefined;
+        readonly applyConfiguration?: (expectedRevision?: string) => Promise<ConsoleConfigApplication>;
+        readonly readApplication?: () => ConsoleConfigApplication | undefined;
+        readonly validateConfiguration?: (document: RuntimeConfigDocument) => Promise<void>;
+    });
+    readSource(): Promise<ConsoleConfigSource>;
+    readDocument(): Promise<Record<string, unknown>>;
+    replaceSource(source: string, expectedRevision: string): Promise<{
+        readonly revision: string;
+        readonly restartRequired: boolean;
+    } & ConsoleConfigApplicationStatus>;
+    setKey(pluginName: string, data: unknown): Promise<{
+        restartRequired: boolean;
+    } & ConsoleConfigApplicationStatus>;
+    removeKey(pluginName: string): Promise<{
+        restartRequired: boolean;
+    } & ConsoleConfigApplicationStatus>;
+    /**
+     * Scoped, revision-checked path writes (`config:patch`). Paths outside the caller's
+     * allowlist are rejected before reading values; a stale revision returns the latest
+     * values instead of overwriting; every touched section is validated by its schema.
+     */
+    patch(request: ConsoleConfigPatchRequest): Promise<ConsoleConfigPatchResult>;
+    /**
+     * Trusted project administration (`config:patch-project`, full scope only). Same
+     * single-CAS core as {@link patch}, without the page allowlist; it does not widen
+     * `config:patch` / `HOST_CONFIG_PATCH_PATHS`. Declaration writes are rejected as
+     * `invalid`, conflict values are masked, and a thrown commit is `unconfirmed`.
+     */
+    patchProject(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>): Promise<ConsoleConfigProjectPatchResult>;
+    /** Host-authenticated owner chat. Policy checks share the mutation's CAS boundary. */
+    patchChat(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>): Promise<ConsoleConfigPatchResult>;
+    /**
+     * Trusted project read (`config:get-project`, full scope only). Values are masked by
+     * section schema, secret-like keys and unexpanded environment references unless the
+     * caller explicitly asks to `reveal`; a section whose schema cannot be read is masked whole.
+     */
+    readProject(request?: ConsoleConfigProjectReadRequest): Promise<ConsoleConfigProjectRead>;
+    /**
+     * Host-authenticated owner chat reads (C1). `get` returns one proven-safe leaf;
+     * `fields` lists manageable leaves and their types without values. Denials carry
+     * only a reason code.
+     */
+    readChat(path: readonly string[], mode: 'get' | 'fields'): Promise<ChatConfigurationRead>;
+    apply(expectedRevision: string): Promise<ConsoleConfigApplyResult>;
+    readEnvironmentFile(filename: string): Promise<string>;
+    writeEnvironmentFile(filename: string, content: string): Promise<void>;
+    readSchema(pluginName?: string): Promise<unknown>;
+    validatePluginConfig(pluginName: string, data: unknown, capturedDocument?: RuntimeConfigDocument): Promise<PluginConfigValidation>;
+    readAllSchemas(): Promise<Record<string, unknown>>;
+    listKeys(): Promise<string[]>;
+}
+export { configKeyPatch, configKeyRemovePatch, flattenConfigDocument } from './configuration-projection.js';