@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/config/configuration-chat-policy.js

@@ -0,0 +1,423 @@
+import { expandEnvironmentValue } from '@zhin.js/runtime';
+import { isUnknownConfigurationSchemaBoundary, sensitiveConfigKey as sensitiveKey } from './configuration-redaction.js';
+const accessMessages = Object.freeze({
+    sensitive: '敏感配置不能通过聊天读取或修改，请使用 CLI 或 Console。',
+    missing: '配置项不存在。',
+    unknown: '无法确认配置范围安全，请使用 CLI 或 Console。',
+    permission: '权限相关配置不能通过聊天读取或修改，请使用 CLI 或 Console。',
+    scope: '该配置不在聊天可管理范围内，请使用 CLI 或 Console。',
+    leaf: '聊天只能读写单个叶子字段（标量或标量数组）。',
+    required: '必填字段不能通过聊天删除。',
+});
+export class ConfigChatAccessError extends Error {
+    kind;
+    constructor(kind) {
+        super(accessMessages[kind]);
+        this.kind = kind;
+        this.name = 'ConfigChatAccessError';
+    }
+}
+/**
+ * Role, approval and allow/deny-list vocabulary (C4): `master`, `trusted`,
+ * `endpoints[*].master/trusted`, `ai.trigger.masters/trusted`, `toolHardGate.*`, and
+ * compound names such as `adminIds`, `ownerId`, `masterId`, `trustedUsers`,
+ * `superUsers`, `whitelist`, `allowlist`, `blacklist` or `bypassMasters`.
+ * Matched by contains/prefix/suffix after normalization (like `sensitiveConfigKey`) so
+ * casing, separators or compounds cannot bypass it. Deliberately fail-closed: an
+ * ordinary key that merely contains a role word (e.g. `masterVolume`) is CLI-only.
+ */
+export function isChatPermissionSegment(segment) {
+    const normalized = segment.replace(/[^a-z0-9]/giu, '').toLowerCase();
+    return /(?:master|owner|admin|trust|approv|permission|permit|privilege|superuser|sudo|operator|moderator|bypass|exempt|toolhardgate)/u.test(normalized)
+        || /(?:allow|deny|denied|white|black|block|ban|bann|safe|ignore)(?:ed)?(?:lists?|users?|userids?|ids?|groups?|senders?|members?)$/u.test(normalized)
+        || /^(?:allow|deny|white|black|block|ban)(?:ed)?(?:lists?)?$/u.test(normalized)
+        || /roles?(?:ids?)?$|^roles?|acls?$|grants?$/u.test(normalized);
+}
+/**
+ * Indirect role binding (M2): `endpoints[*].id|name` is the key that binds leaf
+ * `master`/`trusted` to an account, so remapping it from chat is a permission change.
+ */
+export function isChatIdentityRemapPath(path) {
+    return path.some((segment, index) => segment === 'endpoints' && /^(?:0|[1-9][0-9]*)$/u.test(path[index + 1] ?? '')
+        && /^(?:id|name|instanceid|endpointid)$/u.test((path[index + 2] ?? '').replace(/[^a-z0-9]/giu, '').toLowerCase()));
+}
+/**
+ * M1/B1: a chat `set` never plants a new `${…}` or `env://` reference (even with a
+ * non-credential-looking name), since a later `get` or runtime echo would expand it.
+ * Existing references are untouched by unrelated operations.
+ */
+export function assertChatValueHasNoEnvironmentReference(value, depth = 0) {
+    if (depth > 32)
+        throw new ConfigChatAccessError('unknown');
+    if (typeof value === 'string') {
+        if (value.includes('${') || /env:\/\//iu.test(value))
+            throw new ConfigChatAccessError('sensitive');
+        return;
+    }
+    if (Array.isArray(value))
+        for (const item of value)
+            assertChatValueHasNoEnvironmentReference(item, depth + 1);
+    else if (record(value))
+        for (const [key, item] of Object.entries(value)) {
+            assertChatValueHasNoEnvironmentReference(key, depth + 1);
+            assertChatValueHasNoEnvironmentReference(item, depth + 1);
+        }
+}
+function startsWith(path, prefix) {
+    return prefix.length <= path.length && prefix.every((segment, index) => path[index] === segment);
+}
+/** C3/C4 scope gate, checked before any schema proof or value read. */
+export function assertChatConfigurationScope(path, scope) {
+    if (!path.length)
+        throw new ConfigChatAccessError('leaf');
+    if (scope.declarationKeys.has(path[0]))
+        throw new ConfigChatAccessError('scope');
+    if (path.some(isChatPermissionSegment) || isChatIdentityRemapPath(path))
+        throw new ConfigChatAccessError('permission');
+    if (scope.hostKeys.includes(path[0]) && !scope.hostPaths.some(prefix => startsWith(path, prefix))) {
+        throw new ConfigChatAccessError('scope');
+    }
+}
+/** Whitelisted Host roots reachable from a (possibly shorter) `fields` scope. */
+export function chatHostRoots(prefix, scope) {
+    return scope.hostPaths.filter(entry => startsWith(entry, prefix) || startsWith(prefix, entry))
+        .map(entry => entry.length >= prefix.length ? entry : prefix);
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function own(value, key) { return Object.hasOwn(value, key); }
+function sensitive(schema) {
+    return schema.writeOnly === true || schema.secret === true || schema.format === 'password' || schema.component === 'password'
+        || record(schema['x-zhin-config']) && (schema['x-zhin-config'].secret === true || schema['x-zhin-config'].component === 'password');
+}
+function unknown() { throw new ConfigChatAccessError('unknown'); }
+function assertSafe(nodes) {
+    if (nodes.some(sensitive))
+        throw new ConfigChatAccessError('sensitive');
+}
+function intersect(left, right) {
+    // A combinatorial declaration is uncertain for this deliberately conservative
+    // reader, rather than permission to inspect arbitrary configuration values.
+    if (left.length * right.length > 64)
+        unknown();
+    return left.flatMap(a => right.map(b => [...a, ...b]));
+}
+function variants(value, root, seen = new Set()) {
+    if (!record(value) || seen.has(value))
+        unknown();
+    const nextSeen = new Set([...seen, value]);
+    if (isUnknownConfigurationSchemaBoundary(value, root)
+        || value.hidden === true || record(value['x-zhin-config']) && value['x-zhin-config'].hidden === true)
+        unknown();
+    let result = [[value]];
+    if (value.$ref !== undefined) {
+        if (typeof value.$ref !== 'string' || !value.$ref.startsWith('#/'))
+            unknown();
+        let referenced = root;
+        for (const raw of value.$ref.slice(2).split('/')) {
+            if (/~(?![01])/u.test(raw))
+                unknown();
+            const key = raw.replaceAll('~1', '/').replaceAll('~0', '~');
+            if (!record(referenced) || !own(referenced, key))
+                unknown();
+            referenced = referenced[key];
+        }
+        result = intersect(result, variants(referenced, root, nextSeen));
+    }
+    if (value.allOf !== undefined) {
+        if (!Array.isArray(value.allOf) || !value.allOf.length)
+            unknown();
+        for (const branch of value.allOf)
+            result = intersect(result, variants(branch, root, nextSeen));
+    }
+    for (const keyword of ['anyOf', 'oneOf'])
+        if (value[keyword] !== undefined) {
+            if (!Array.isArray(value[keyword]) || !value[keyword].length)
+                unknown();
+            result = intersect(result, value[keyword].flatMap(branch => variants(branch, root, nextSeen)));
+        }
+    return result;
+}
+function typeNames(nodes) {
+    const types = new Set();
+    for (const node of nodes) {
+        for (const type of Array.isArray(node.type) ? node.type : [node.type])
+            if (typeof type === 'string')
+                types.add(type);
+        if (record(node.properties) || record(node.patternProperties) || record(node.additionalProperties))
+            types.add('object');
+        if (node.items !== undefined || node.prefixItems !== undefined)
+            types.add('array');
+        const examples = own(node, 'const') ? [node.const] : Array.isArray(node.enum) ? node.enum : [];
+        for (const value of examples)
+            types.add(value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value);
+    }
+    if (!types.size || [...types].some(type => !['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'].includes(type)))
+        unknown();
+    return [...types];
+}
+function children(nodes, key) {
+    if (sensitiveKey(key))
+        throw new ConfigChatAccessError('sensitive');
+    const found = [];
+    for (const node of nodes) {
+        if (node.items !== undefined || node.prefixItems !== undefined || node.type === 'array') {
+            if (!/^(?:0|[1-9][0-9]*)$/u.test(key))
+                unknown();
+            const index = Number(key);
+            const modernPrefix = Array.isArray(node.prefixItems) ? node.prefixItems : undefined;
+            const legacyPrefix = !modernPrefix && Array.isArray(node.items) ? node.items : undefined;
+            const prefix = modernPrefix ?? legacyPrefix;
+            const item = prefix && index < prefix.length ? prefix[index] : legacyPrefix ? node.additionalItems : node.items;
+            if (item !== undefined)
+                found.push(item);
+            continue;
+        }
+        let matched = false;
+        if (record(node.properties) && own(node.properties, key)) {
+            found.push(node.properties[key]);
+            matched = true;
+        }
+        if (record(node.patternProperties))
+            for (const [pattern, schema] of Object.entries(node.patternProperties)) {
+                let matches;
+                try {
+                    matches = new RegExp(pattern, 'u').test(key);
+                }
+                catch {
+                    unknown();
+                }
+                if (matches) {
+                    found.push(schema);
+                    matched = true;
+                }
+            }
+        if (!matched && node.additionalProperties !== undefined)
+            found.push(node.additionalProperties);
+    }
+    if (!found.length)
+        unknown();
+    return found;
+}
+function descend(input, key, root) {
+    return input.flatMap(nodes => {
+        assertSafe(nodes);
+        let result = [[]];
+        for (const child of children(nodes, key))
+            result = intersect(result, variants(child, root));
+        return result;
+    });
+}
+function locate(root, path) {
+    let current = variants(root, root);
+    for (const key of path)
+        current = descend(current, key, root);
+    for (const nodes of current) {
+        assertSafe(nodes);
+        typeNames(nodes);
+    }
+    return current;
+}
+function inspectTree(current, root, values, seen = new Set()) {
+    const allowed = new Set(current.flatMap(typeNames));
+    for (const value of values) {
+        if (value === undefined)
+            continue;
+        const type = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+        if (!allowed.has(type) && !(type === 'number' && allowed.has('integer')))
+            unknown();
+        if (typeof value === 'string' && /^env:\/\//u.test(value) && sensitiveKey(value.slice(6)))
+            throw new ConfigChatAccessError('sensitive');
+    }
+    for (const nodes of current) {
+        assertSafe(nodes);
+        const types = typeNames(nodes);
+        if (!types.includes('object') && !types.includes('array'))
+            continue;
+        if (nodes.some(node => seen.has(node)))
+            unknown();
+        const nextSeen = new Set([...seen, ...nodes]);
+        const keys = new Set();
+        for (const node of nodes) {
+            if (record(node.properties))
+                for (const key of Object.keys(node.properties))
+                    keys.add(key);
+            if (record(node.patternProperties))
+                for (const schema of Object.values(node.patternProperties))
+                    inspectTree(variants(schema, root), root, [], nextSeen);
+            if (record(node.additionalProperties))
+                inspectTree(variants(node.additionalProperties, root), root, [], nextSeen);
+            if (types.includes('array')) {
+                const prefix = Array.isArray(node.prefixItems) ? node.prefixItems : Array.isArray(node.items) ? node.items : [];
+                for (const schema of prefix)
+                    inspectTree(variants(schema, root), root, [], nextSeen);
+                if (record(node.items))
+                    inspectTree(variants(node.items, root), root, [], nextSeen);
+            }
+        }
+        for (const value of values)
+            if (record(value) || Array.isArray(value))
+                for (const key of Object.keys(value))
+                    keys.add(key);
+        if (!keys.size && types.includes('object') && !nodes.some(node => record(node.properties) || record(node.additionalProperties) || node.additionalProperties === false))
+            unknown();
+        if (types.includes('array') && !nodes.some(node => record(node.items) || Array.isArray(node.prefixItems) || Array.isArray(node.items) || node.items === false))
+            unknown();
+        for (const key of keys) {
+            const childValues = values.map(value => value !== null && typeof value === 'object' && Object.hasOwn(value, key) ? value[key] : undefined);
+            inspectTree(descend([nodes], key, root), root, childValues, nextSeen);
+        }
+    }
+}
+/** Raw JSON Schema only. Unknown branches never confer access. No values are expanded. */
+export function assertChatConfigurationAccess(schema, path, values, deep = true, absolutePath = path) {
+    if (absolutePath.some(sensitiveKey))
+        throw new ConfigChatAccessError('sensitive');
+    if (!record(schema))
+        unknown();
+    const current = locate(schema, path);
+    const allowed = new Set(current.flatMap(typeNames));
+    for (const value of values)
+        if (value !== undefined) {
+            const type = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+            if (!allowed.has(type) && !(type === 'number' && allowed.has('integer')))
+                unknown();
+        }
+    if (deep) {
+        expandEnvironmentValue(values, name => { if (sensitiveKey(name))
+            throw new ConfigChatAccessError('sensitive'); return undefined; }, () => '');
+        for (const value of values)
+            if (typeof value === 'string' && /^env:\/\//u.test(value)
+                && sensitiveKey(value.slice(6)))
+                throw new ConfigChatAccessError('sensitive');
+        inspectTree(current, schema, values);
+    }
+}
+const scalarTypes = new Set(['string', 'number', 'integer', 'boolean', 'null']);
+/**
+ * Leaf-only chat writes: the target must resolve to scalars or arrays of scalars in
+ * every schema branch. Object targets would let a parent overwrite/removal bypass
+ * per-child checks, so they are rejected as `leaf`.
+ */
+export function chatLeafTypes(schema, path, values = []) {
+    if (!record(schema))
+        unknown();
+    const current = locate(schema, path);
+    // Desired files can be edited outside the Host. Schema bounds do not prove
+    // that the currently stored array actually contains only scalar values.
+    for (const value of values)
+        if (Array.isArray(value))
+            for (const item of value) {
+                if (!scalarTypes.has(item === null ? 'null' : typeof item))
+                    throw new ConfigChatAccessError('leaf');
+            }
+    const types = new Set();
+    for (const nodes of current) {
+        const names = typeNames(nodes);
+        if (names.includes('object'))
+            throw new ConfigChatAccessError('leaf');
+        if (names.includes('array')) {
+            if (!nodes.some(node => node.items !== undefined || node.prefixItems !== undefined))
+                unknown();
+            let prefixLength = 0;
+            let maxItems = Infinity;
+            for (const node of nodes) {
+                const prefix = Array.isArray(node.prefixItems) ? node.prefixItems : Array.isArray(node.items) ? node.items : [];
+                prefixLength = Math.max(prefixLength, prefix.length);
+                if (node.maxItems !== undefined) {
+                    if (typeof node.maxItems !== 'number' || !Number.isInteger(node.maxItems) || node.maxItems < 0)
+                        unknown();
+                    maxItems = Math.min(maxItems, node.maxItems);
+                }
+            }
+            // Every prefix position can have a different type. One position past the
+            // longest prefix represents the homogeneous tail; never iterate to maxItems.
+            for (let index = 0; index <= prefixLength && index < maxItems; index++) {
+                const key = String(index);
+                // A forbidden position also makes all later positions unreachable.
+                if (children(nodes, key).includes(false))
+                    break;
+                for (const items of descend([nodes], key, schema)) {
+                    if (typeNames(items).some(type => !scalarTypes.has(type)))
+                        throw new ConfigChatAccessError('leaf');
+                }
+            }
+        }
+        for (const name of names)
+            types.add(name);
+    }
+    return Object.freeze([...types]);
+}
+/** `unset` removes only optional leaves; any branch listing the key as required refuses. */
+export function assertChatOptionalLeaf(schema, path) {
+    if (!record(schema))
+        unknown();
+    chatLeafTypes(schema, path);
+    if (!path.length)
+        throw new ConfigChatAccessError('required');
+    const key = path.at(-1);
+    for (const nodes of locate(schema, path.slice(0, -1))) {
+        if (nodes.some(node => Array.isArray(node.required) && node.required.includes(key)))
+            throw new ConfigChatAccessError('required');
+    }
+}
+/** Prove the same properties-only ancestry used by root discovery, without enumerating siblings. */
+function declaredPropertyPath(schema, path) {
+    try {
+        let current = variants(schema, schema);
+        for (const key of path) {
+            // Listing never descends into array items or dynamic dictionary keys.
+            if (current.some(nodes => typeNames(nodes).includes('array'))
+                || !current.some(nodes => nodes.some(node => record(node.properties) && own(node.properties, key))))
+                return false;
+            current = descend(current, key, schema);
+        }
+        return true;
+    }
+    catch (error) {
+        if (error instanceof ConfigChatAccessError)
+            return false;
+        throw error;
+    }
+}
+/** Declared leaf paths below `path` (properties only), each still re-checked by the store. */
+export function chatConfigurationLeaves(schema, path, limit = 256) {
+    if (!record(schema) || !declaredPropertyPath(schema, path))
+        return [];
+    const found = [];
+    const walk = (relative) => {
+        if (found.length >= limit || relative.length > 12)
+            return;
+        if (relative.some(isChatPermissionSegment) || isChatIdentityRemapPath(relative) || relative.some(sensitiveKey))
+            return;
+        let current;
+        try {
+            current = locate(schema, relative);
+        }
+        catch (error) {
+            if (error instanceof ConfigChatAccessError)
+                return;
+            throw error;
+        }
+        try {
+            chatLeafTypes(schema, relative);
+            found.push(Object.freeze([...relative]));
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof ConfigChatAccessError))
+                throw error;
+        }
+        const keys = new Set();
+        for (const nodes of current)
+            for (const node of nodes)
+                if (record(node.properties))
+                    for (const key of Object.keys(node.properties))
+                        keys.add(key);
+        for (const key of [...keys].sort())
+            walk([...relative, key]);
+    };
+    walk(path);
+    return Object.freeze(found);
+}

package/lib/config/configuration-patch.d.ts

@@ -0,0 +1,16 @@
+import type { ConfigPatch, RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/** Raised for a malformed request or a path outside the caller's declared scope; nothing is written. */
+export declare class ConfigPatchScopeError extends Error {
+    constructor(message: string);
+}
+/** Structural request checks shared by the RPC boundary and the store. */
+export declare function normalizeConfigPatchOperations(value: unknown): readonly ConfigPatch[];
+/**
+ * Reads `x-zhin-config.patchPaths` from a plugin's own JSON Schema root: dotted Host sub-paths
+ * (at least two segments, e.g. `ai.knowledge`) the plugin owns besides its instance block.
+ */
+export declare function readDeclaredPatchPaths(schema: Readonly<Record<string, unknown>> | null, instanceKey: string): readonly (readonly string[])[];
+/** Resolves the allowlist for one caller scope. Plugin scopes always include their own block. */
+export declare function resolvePatchScope(document: RuntimeConfigDocument, instanceKey: string | undefined, declared: readonly (readonly string[])[]): readonly (readonly string[])[];
+export declare function assertPatchesInScope(patches: readonly ConfigPatch[], allowed: readonly (readonly string[])[], scopeLabel: string): void;
+export declare function readPath(document: RuntimeConfigDocument, path: readonly string[]): unknown;

package/lib/config/configuration-patch.js

@@ -0,0 +1,105 @@
+import { CONFIG_PATCH_LIMITS, HOST_CONFIG_PATCH_PATHS } from '@zhin.js/console-protocol';
+import { HOST_CONFIG_KEYS } from '@zhin.js/runtime';
+import { assertUnambiguousConfigKey } from './configuration-projection.js';
+import { isForbiddenConfigurationPathSegment } from './configuration-path.js';
+/** Host keys a plugin may never claim: declarations, the root plugin section and transport. */
+const UNCLAIMABLE_HOST_KEYS = new Set(['plugin', 'http']);
+const HOST_KEY_SET = new Set(HOST_CONFIG_KEYS);
+const SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/u;
+/** Raised for a malformed request or a path outside the caller's declared scope; nothing is written. */
+export class ConfigPatchScopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigPatchScopeError';
+    }
+}
+/** Structural request checks shared by the RPC boundary and the store. */
+export function normalizeConfigPatchOperations(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new ConfigPatchScopeError('patches 必须是非空数组');
+    if (value.length > CONFIG_PATCH_LIMITS.maxOperations) {
+        throw new ConfigPatchScopeError(`一次最多 ${CONFIG_PATCH_LIMITS.maxOperations} 个 patch`);
+    }
+    return Object.freeze(value.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new ConfigPatchScopeError(`patches[${index}] 必须是对象`);
+        const operation = item;
+        const path = normalizePath(operation.path, `patches[${index}].path`);
+        if (operation.op === 'set') {
+            if (!Object.hasOwn(operation, 'value') || operation.value === undefined) {
+                throw new ConfigPatchScopeError(`patches[${index}] 的 set 需要 value；删除请用 op: "remove"`);
+            }
+            return Object.freeze({ op: 'set', path, value: structuredClone(operation.value) });
+        }
+        if (operation.op === 'remove')
+            return Object.freeze({ op: 'remove', path });
+        throw new ConfigPatchScopeError(`patches[${index}].op 只能是 set 或 remove`);
+    }));
+}
+function normalizePath(value, label) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > CONFIG_PATCH_LIMITS.maxPathDepth) {
+        throw new ConfigPatchScopeError(`${label} 必须是 1–${CONFIG_PATCH_LIMITS.maxPathDepth} 段的字符串数组`);
+    }
+    for (const segment of value) {
+        if (typeof segment !== 'string' || !segment || segment.length > CONFIG_PATCH_LIMITS.maxSegmentLength
+            || isForbiddenConfigurationPathSegment(segment)) {
+            throw new ConfigPatchScopeError(`${label} 含有无效路径段`);
+        }
+    }
+    return Object.freeze([...value]);
+}
+/**
+ * Reads `x-zhin-config.patchPaths` from a plugin's own JSON Schema root: dotted Host sub-paths
+ * (at least two segments, e.g. `ai.knowledge`) the plugin owns besides its instance block.
+ */
+export function readDeclaredPatchPaths(schema, instanceKey) {
+    const metadata = schema?.['x-zhin-config'];
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+        return [];
+    const declared = metadata.patchPaths;
+    if (declared === undefined)
+        return [];
+    if (!Array.isArray(declared))
+        throw new ConfigPatchScopeError(`${instanceKey} 的 x-zhin-config.patchPaths 必须是字符串数组`);
+    return Object.freeze(declared.map((entry) => {
+        const path = typeof entry === 'string' ? entry.split('.') : [];
+        if (path.length < 2 || path.some(segment => !SEGMENT.test(segment) || isForbiddenConfigurationPathSegment(segment))
+            || !HOST_KEY_SET.has(path[0]) || UNCLAIMABLE_HOST_KEYS.has(path[0])) {
+            throw new ConfigPatchScopeError(`${instanceKey} 的 x-zhin-config.patchPaths 项 ${String(entry)} 无效：只能声明 Host 配置下至少两级的路径（如 ai.knowledge）`);
+        }
+        return Object.freeze(path);
+    }));
+}
+/** Resolves the allowlist for one caller scope. Plugin scopes always include their own block. */
+export function resolvePatchScope(document, instanceKey, declared) {
+    if (instanceKey === undefined)
+        return HOST_CONFIG_PATCH_PATHS;
+    if (HOST_KEY_SET.has(instanceKey)) {
+        throw new ConfigPatchScopeError(`${instanceKey} 是 Host 配置键，不是插件实例；请省略 instanceKey 使用 Host 白名单`);
+    }
+    try {
+        assertUnambiguousConfigKey(document, instanceKey);
+    }
+    catch {
+        throw new ConfigPatchScopeError(`未声明的插件实例：${instanceKey}`);
+    }
+    return Object.freeze([Object.freeze([instanceKey]), ...declared]);
+}
+export function assertPatchesInScope(patches, allowed, scopeLabel) {
+    for (const patch of patches) {
+        const inside = allowed.some(prefix => prefix.length <= patch.path.length
+            && prefix.every((segment, index) => patch.path[index] === segment));
+        if (!inside) {
+            throw new ConfigPatchScopeError(`路径 ${patch.path.join('.')} 不在 ${scopeLabel} 可写范围内（允许：${allowed.map(path => path.join('.')).join('、') || '无'}）`);
+        }
+    }
+}
+export function readPath(document, path) {
+    let value = document;
+    for (const segment of path) {
+        if (!value || typeof value !== 'object' || !Object.hasOwn(value, segment))
+            return undefined;
+        value = value[segment];
+    }
+    return structuredClone(value);
+}

package/lib/config/configuration-path.d.ts

@@ -0,0 +1,6 @@
+/** One immutable policy for parsed, structured-write and chat-read paths. */
+export declare function isForbiddenConfigurationPathSegment(segment: string): boolean;
+/** JSON Pointer preserves literal dots and slashes; dotted paths cover simple fields. */
+export declare function parseConfigurationPath(input: string): readonly string[];
+/** Lossless text, or undefined when the parser cannot address it. Callers quote token delimiters. */
+export declare function formatConfigurationPath(path: readonly string[]): string | undefined;

package/lib/config/configuration-path.js

@@ -0,0 +1,40 @@
+import { CONFIG_PATCH_LIMITS } from '@zhin.js/console-protocol';
+const forbidden = Object.freeze(['__proto__', 'constructor', 'prototype']);
+const simpleSegment = /^[A-Za-z0-9_-]+$/u;
+/** One immutable policy for parsed, structured-write and chat-read paths. */
+export function isForbiddenConfigurationPathSegment(segment) {
+    return forbidden.includes(segment);
+}
+/** JSON Pointer preserves literal dots and slashes; dotted paths cover simple fields. */
+export function parseConfigurationPath(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('Invalid configuration path');
+    if (input === '')
+        return Object.freeze([]);
+    const pointer = input.startsWith('/');
+    const segments = pointer ? input.slice(1).split('/').map(segment => {
+        if (/~(?![01])/u.test(segment))
+            throw new TypeError('Invalid configuration path');
+        return segment.replaceAll('~1', '/').replaceAll('~0', '~');
+    }) : input.split('.');
+    if (segments.length > CONFIG_PATCH_LIMITS.maxPathDepth || segments.some(segment => !segment
+        || segment.length > CONFIG_PATCH_LIMITS.maxSegmentLength || isForbiddenConfigurationPathSegment(segment)
+        || /[\u0000-\u001f\u007f]/u.test(segment) || (!pointer && !simpleSegment.test(segment)))) {
+        throw new TypeError('Invalid configuration path');
+    }
+    return Object.freeze(segments);
+}
+/** Lossless text, or undefined when the parser cannot address it. Callers quote token delimiters. */
+export function formatConfigurationPath(path) {
+    const text = path.every(segment => simpleSegment.test(segment)) ? path.join('.')
+        : `/${path.map(segment => segment.replaceAll('~', '~0').replaceAll('/', '~1')).join('/')}`;
+    try {
+        parseConfigurationPath(text);
+    }
+    catch (error) {
+        if (error instanceof TypeError)
+            return undefined;
+        throw error;
+    }
+    return text;
+}

package/lib/config/configuration-projection.d.ts

@@ -0,0 +1,6 @@
+import { type ConfigPatch, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/** The Console presents business sections, never the package-name declaration map. */
+export declare function flattenConfigDocument(document: RuntimeConfigDocument): Record<string, unknown>;
+export declare function assertUnambiguousConfigKey(document: RuntimeConfigDocument, key: string): void;
+export declare function configKeyPatch(document: RuntimeConfigDocument, key: string, data: unknown): ConfigPatch;
+export declare function configKeyRemovePatch(document: RuntimeConfigDocument, key: string): ConfigPatch;

package/lib/config/configuration-projection.js

@@ -0,0 +1,28 @@
+import { readPluginConfigurationMap } from '@zhin.js/plugin-runtime';
+import { HOST_CONFIG_KEYS, readApplicationPluginDeclaration } from '@zhin.js/runtime';
+const HOST_KEYS = new Set([...HOST_CONFIG_KEYS, 'plugin']);
+const FORBIDDEN = new Set(['__proto__', 'constructor', 'prototype']);
+/** The Console presents business sections, never the package-name declaration map. */
+export function flattenConfigDocument(document) {
+    readApplicationPluginDeclaration(document);
+    const flat = {};
+    for (const key of HOST_KEYS)
+        if (Object.hasOwn(document, key))
+            Object.defineProperty(flat, key, { value: document[key], enumerable: true, configurable: true, writable: true });
+    for (const [key, value] of Object.entries(readPluginConfigurationMap(document)))
+        Object.defineProperty(flat, key, { value, enumerable: true, configurable: true, writable: true });
+    return flat;
+}
+export function assertUnambiguousConfigKey(document, key) {
+    const declaration = readApplicationPluginDeclaration(document);
+    if (FORBIDDEN.has(key) || !HOST_KEYS.has(key) && !declaration.instances.some(item => item.instanceKey === key))
+        throw new Error(`Unknown configuration key: ${key}; edit the configuration source to change declarations`);
+}
+export function configKeyPatch(document, key, data) {
+    assertUnambiguousConfigKey(document, key);
+    return Object.freeze({ op: 'set', path: Object.freeze([key]), value: data });
+}
+export function configKeyRemovePatch(document, key) {
+    assertUnambiguousConfigKey(document, key);
+    return Object.freeze({ op: 'remove', path: Object.freeze([key]) });
+}

package/lib/config/configuration-redaction.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+type Schema = Readonly<Record<string, unknown>>;
+/** Shared proof limit: these branches/resources need a resolver we do not provide. */
+export declare function isUnknownConfigurationSchemaBoundary(schema: Schema, root: Schema): boolean;
+/** Credential names, excluding ordinary budgets such as maxTokens and tokenLimit. */
+export declare function sensitiveConfigKey(key: string): boolean;
+export declare const REDACTED_CONFIG_VALUE = "[redacted]";
+/**
+ * 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 declare function maskConfigValue(sectionSchema: Schema | null | undefined, path: readonly string[], value: unknown, options?: Readonly<{
+    unknownSchema?: 'redact';
+}>): unknown;
+export {};