@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/config/configuration-redaction.js

@@ -0,0 +1,75 @@
+/**
+ * Masks stored configuration values before they leave the store in a response that the
+ * caller did not ask to read (e.g. a trusted project patch conflict). Conservative: a
+ * schema secret/writeOnly/password/hidden annotation, a secret-like key, or an unexpanded
+ * environment reference (`${…}`, `env://…`) is replaced as a whole and never echoed.
+ */
+import { UNRESOLVED_CONFIG_SCHEMA, configSchemaChildren, expandConfigSchema, isConfigEnvironmentReference, isSecretConfigKey, isSecretConfigSchema, } from '@zhin.js/runtime';
+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 (the ADR 0057 predicate). */
+export const sensitiveConfigKey = isSecretConfigKey;
+export const REDACTED_CONFIG_VALUE = '[redacted]';
+const MAX_DEPTH = 32;
+// Retain uncertainty without changing the non-strict masker's best-effort behavior.
+const unresolvedSchema = UNRESOLVED_CONFIG_SCHEMA;
+const expand = expandConfigSchema;
+const children = configSchemaChildren;
+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 isSecretConfigSchema(schema) || schema.hidden === true
+        || record(metadata) && metadata.hidden === true;
+}
+function maskTree(value, nodes, root, depth, hidden) {
+    if (nodes.some(hidden))
+        return REDACTED_CONFIG_VALUE;
+    if (typeof value === 'string')
+        return isConfigEnvironmentReference(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';