@zhin.js/host-http 1.2.1 → 1.3.0

package/lib/access-control.d.ts

@@ -1,4 +1,4 @@
-import { type ConsoleGrant, type ConsolePermission, type ConsolePluginPermissionInfo, type ConsolePluginPermissionLevelResolver, type ConsoleRpcPermissionRule, type ConsoleScopeTarget } from '@zhin.js/console-protocol';
+import { CONSOLE_UNKNOWN_RPC_CODE, type ConsoleDenialReason, type ConsoleGrant, type ConsolePermission, type ConsolePluginPermissionInfo, type ConsolePluginPermissionLevelResolver, type ConsoleRpcPermissionRule, type ConsoleScopeTarget } from '@zhin.js/console-protocol';
 /**
  * Console principals (ADR 0049 §1):
  * - `bootstrap`: the `http.token` before the first owner exists (`open: false`), or a Host
@@ -93,12 +93,36 @@ export type ConsoleRpcDecision = Readonly<{
     delegated?: true;
 }> | Readonly<{
     allowed: false;
-    code: 'setup_required' | 'unmapped' | 'forbidden';
+    /**
+     * `unknown_rpc`: the Host has no handler and no permission entry for the type (zhinjs/zhin#1250).
+     * Nothing runs; it is not a security refusal and callers do not audit it (see
+     * {@link isAuditedRpcDenial}). Every other code is a refusal that is audited.
+     */
+    code: 'setup_required' | 'unmapped' | 'forbidden' | typeof CONSOLE_UNKNOWN_RPC_CODE;
     error: string;
     permission: ConsolePermission | null;
+    /** Audit `detail.reason`; absent for `unknown_rpc`. */
+    reason?: ConsoleDenialReason;
 }>;
+export interface AuthorizeConsoleRpcOptions {
+    /**
+     * Whether this Host has a handler for an RPC type that is missing from the permission map. True
+     * (or no predicate) keeps the audited `unmapped` refusal — a handler without a permission entry
+     * is a development error; false answers `unknown_rpc`. Mapped types never consult it.
+     */
+    readonly registered?: (type: string) => boolean;
+}
+/** Whether a refused RPC is written to the audit log (`unknown_rpc` is not). */
+export declare function isAuditedRpcDenial(decision: ConsoleRpcDecision): boolean;
+/** Error text of an unknown RPC: the (truncated) type and nothing else. */
+export declare function unknownConsoleRpcError(type: unknown): string;
 /** RPC authorization for one principal and message (deny by default). */
-export declare function authorizeConsoleRpc(principal: ConsolePrincipal, message: Readonly<Record<string, unknown>>): ConsoleRpcDecision;
+export declare function authorizeConsoleRpc(principal: ConsolePrincipal, message: Readonly<Record<string, unknown>>, options?: AuthorizeConsoleRpcOptions): ConsoleRpcDecision;
+/**
+ * Why grants refuse `permission` at a target: `scope_denied` when some binding holds it at another
+ * adapter / endpoint, else `insufficient_permission`.
+ */
+export declare function grantsDenialReason(grants: readonly ConsoleGrant[], permission: string): ConsoleDenialReason;
 /**
  * For plugin RPC: whether the principal holds the rule's write permission (`feature.configure`,
  * or `endpoint.manage` for adapter account methods) at its target. The plugin RPC dispatcher
@@ -114,6 +138,8 @@ export type ConsoleHttpDecision = Readonly<{
     code: 'unauthorized' | 'forbidden' | 'setup_required';
     error: string;
     permission: string | null;
+    /** Audit `detail.reason`. */
+    reason: ConsoleDenialReason;
 }>;
 /**
  * HTTP authorization of a route under the API base. `principal` is undefined when no valid
@@ -121,7 +147,26 @@ export type ConsoleHttpDecision = Readonly<{
  */
 export declare function authorizeConsoleHttp(principal: ConsolePrincipal | undefined, method: string, relativePath: string): ConsoleHttpDecision;
 /** WebSocket upgrade authorization for non-bootstrap principals. */
+/** Audit `detail.reason` of a WebSocket {@link authorizeConsoleWebSocket} refused. */
+export declare function webSocketDenialReason(principal: ConsolePrincipal, pathname: string): ConsoleDenialReason;
 export declare function authorizeConsoleWebSocket(principal: ConsolePrincipal, pathname: string): boolean;
-/** Audit detail for an RPC: type, target and parameter key names only. */
-export declare function rpcAuditDetail(message: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+/**
+ * JSON length of the detail of one audit entry. The gateway stores at most 4096 characters of
+ * JSON detail; statements are cut so the whole detail stays below this budget once serialised
+ * (escapes such as `\n` count twice), so the stored detail always parses.
+ */
+export declare const AUDIT_DETAIL_JSON_LIMIT = 3500;
+export interface RpcAuditOptions {
+    /**
+     * Replaces literal values in SQL text (`'…'`) before it is recorded, with the dialect's own
+     * lexing (the database Host's `redactSql`). Without it no statement text is recorded at all.
+     */
+    readonly redactSql?: (sql: string) => string;
+}
+/**
+ * Audit detail for an RPC: type, target and parameter key names only — plus the statement text
+ * of Console database writes (pass the reply so the DDL a schema change ran is recorded), with
+ * literals redacted by `options.redactSql`.
+ */
+export declare function rpcAuditDetail(message: Readonly<Record<string, unknown>>, reply?: Readonly<Record<string, unknown>>, options?: RpcAuditOptions): Readonly<Record<string, unknown>>;
 export declare function rpcAuditTarget(rule: ConsoleRpcPermissionRule | null): string | undefined;

package/lib/access-control.js

@@ -1,4 +1,4 @@
-import { CONSOLE_PERMISSION_LIST, CONSOLE_WRITE_PERMISSIONS, expandPluginPermissions, grantsAllow, isPluginConsoleRpcType, resolveConsoleHttpPermission, resolveConsoleRpcPermission, resolveConsoleWsPermission, } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, CONSOLE_PERMISSION_LIST, CONSOLE_UNKNOWN_RPC_CODE, CONSOLE_WRITE_PERMISSIONS, expandPluginPermissions, grantsAllow, grantsAllowAlsoRequired, isPluginConsoleRpcType, resolveConsoleHttpPermission, resolveConsoleRpcPermission, resolveConsoleWsPermission, } from '@zhin.js/console-protocol';
 import { hasForwardingHeaders } from './trust-proxy.js';
 export function isUserPrincipal(principal) {
     return principal?.kind === 'user' || principal?.kind === 'api-token';
@@ -55,27 +55,67 @@ export function globalPermissions(principal, pluginPermissions = []) {
     }
     return expandPluginPermissions([...held], pluginPermissions);
 }
+/** Whether a refused RPC is written to the audit log (`unknown_rpc` is not). */
+export function isAuditedRpcDenial(decision) {
+    return !decision.allowed && decision.code !== CONSOLE_UNKNOWN_RPC_CODE;
+}
+/** Error text of an unknown RPC: the (truncated) type and nothing else. */
+export function unknownConsoleRpcError(type) {
+    return `RPC "${String(type ?? '').slice(0, 64)}" 不存在`;
+}
 /** RPC authorization for one principal and message (deny by default). */
-export function authorizeConsoleRpc(principal, message) {
+export function authorizeConsoleRpc(principal, message, options = {}) {
     const rule = resolveConsoleRpcPermission(message.type, message);
     const permission = rule ? (rule.kind === 'exact' ? rule.permission : rule.read) : null;
     if (principal.kind === 'bootstrap') {
         if (principal.open) {
             return Object.freeze({ allowed: true, rule, permission, write: rule ? isWriteRule(rule) : true });
         }
-        return Object.freeze({ allowed: false, code: 'setup_required', error: '请先完成初始化：创建第一个所有者', permission });
+        return Object.freeze({
+            allowed: false, code: 'setup_required', error: '请先完成初始化：创建第一个所有者', permission,
+            reason: CONSOLE_DENIAL_REASONS.SETUP_REQUIRED,
+        });
     }
     if (!rule) {
-        return Object.freeze({ allowed: false, code: 'unmapped', error: `RPC "${String(message.type ?? '')}" 未登记权限`, permission: null });
+        const type = typeof message.type === 'string' ? message.type : '';
+        if (options.registered && !options.registered(type)) {
+            return Object.freeze({ allowed: false, code: CONSOLE_UNKNOWN_RPC_CODE, error: unknownConsoleRpcError(message.type), permission: null });
+        }
+        return Object.freeze({
+            allowed: false, code: 'unmapped', error: `RPC "${String(message.type ?? '')}" 未登记权限`, permission: null,
+            reason: CONSOLE_DENIAL_REASONS.UNMAPPED_PERMISSION,
+        });
     }
     if (isPluginConsoleRpcType(message.type)) {
         return Object.freeze({ allowed: true, rule, permission, write: isWriteRule(rule), delegated: true });
     }
     if (!grantsAllow(principal.grants, permission, rule.target)) {
-        return Object.freeze({ allowed: false, code: 'forbidden', error: `缺少权限 ${permission}`, permission });
+        return Object.freeze({
+            allowed: false, code: 'forbidden', error: `缺少权限 ${permission}`, permission,
+            reason: grantsDenialReason(principal.grants, permission),
+        });
+    }
+    // `alsoRequires` is held globally (same semantics as grantsAllowAlsoRequired): find the first missing one for the denial reason.
+    const missing = rule.kind === 'exact' && !grantsAllowAlsoRequired(principal.grants, rule)
+        ? rule.alsoRequires?.find(extra => !grantsAllowAlsoRequired(principal.grants, { ...rule, alsoRequires: [extra] }))
+        : undefined;
+    if (missing) {
+        return Object.freeze({
+            allowed: false, code: 'forbidden', error: `缺少权限 ${missing}`, permission,
+            reason: grantsDenialReason(principal.grants, missing),
+        });
     }
     return Object.freeze({ allowed: true, rule, permission, write: isWriteRule(rule) });
 }
+/**
+ * Why grants refuse `permission` at a target: `scope_denied` when some binding holds it at another
+ * adapter / endpoint, else `insufficient_permission`.
+ */
+export function grantsDenialReason(grants, permission) {
+    return grants.some(grant => grant.scope.kind !== 'global' && grant.permissions.includes(permission))
+        ? CONSOLE_DENIAL_REASONS.SCOPE_DENIED
+        : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+}
 function isWriteRule(rule) {
     return rule.kind === 'exact' ? CONSOLE_WRITE_PERMISSIONS.has(rule.permission) : false;
 }
@@ -90,7 +130,7 @@ export function pluginRpcWriteAllowed(principal, rule) {
     if (!rule)
         return false;
     const permission = rule.kind === 'exact' ? rule.permission : rule.write;
-    return grantsAllow(principal.grants, permission, rule.target);
+    return grantsAllow(principal.grants, permission, rule.target) && grantsAllowAlsoRequired(principal.grants, rule);
 }
 /**
  * HTTP authorization of a route under the API base. `principal` is undefined when no valid
@@ -102,15 +142,15 @@ export function authorizeConsoleHttp(principal, method, relativePath) {
     if (rule?.permission === 'public')
         return Object.freeze({ allowed: true, permission });
     if (!principal) {
-        return Object.freeze({ allowed: false, status: 401, code: 'unauthorized', error: 'Invalid or missing token', permission });
+        return Object.freeze({ allowed: false, status: 401, code: 'unauthorized', error: 'Invalid or missing token', permission, reason: CONSOLE_DENIAL_REASONS.NOT_AUTHENTICATED });
     }
     if (principal.kind === 'bootstrap') {
         if (principal.open || rule?.permission === 'bootstrap')
             return Object.freeze({ allowed: true, permission });
-        return Object.freeze({ allowed: false, status: 403, code: 'setup_required', error: '初始化令牌只能用于创建第一个所有者', permission });
+        return Object.freeze({ allowed: false, status: 403, code: 'setup_required', error: '初始化令牌只能用于创建第一个所有者', permission, reason: CONSOLE_DENIAL_REASONS.SETUP_REQUIRED });
     }
     if (!rule) {
-        return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: 'Route is not registered with a Console permission', permission: null });
+        return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: 'Route is not registered with a Console permission', permission: null, reason: CONSOLE_DENIAL_REASONS.UNMAPPED_ROUTE });
     }
     if (rule.permission === 'rpc' || rule.permission === 'authenticated' || rule.permission === 'bootstrap') {
         return Object.freeze({ allowed: true, permission });
@@ -118,9 +158,20 @@ export function authorizeConsoleHttp(principal, method, relativePath) {
     // Scoped permissions over plain HTTP have no knowable target: a global binding is required.
     if (grantsAllow(principal.grants, rule.permission))
         return Object.freeze({ allowed: true, permission });
-    return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: `缺少权限 ${rule.permission}`, permission });
+    return Object.freeze({
+        allowed: false, status: 403, code: 'forbidden', error: `缺少权限 ${rule.permission}`, permission,
+        reason: CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION,
+    });
 }
 /** WebSocket upgrade authorization for non-bootstrap principals. */
+/** Audit `detail.reason` of a WebSocket {@link authorizeConsoleWebSocket} refused. */
+export function webSocketDenialReason(principal, pathname) {
+    if (principal.kind === 'bootstrap')
+        return CONSOLE_DENIAL_REASONS.SETUP_REQUIRED;
+    return resolveConsoleWsPermission(pathname) === null
+        ? CONSOLE_DENIAL_REASONS.UNMAPPED_ROUTE
+        : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+}
 export function authorizeConsoleWebSocket(principal, pathname) {
     // Only the Console's own sockets are host-authenticated; plugin sockets use `auth: 'protocol'`.
     const permission = resolveConsoleWsPermission(pathname);
@@ -128,13 +179,116 @@ export function authorizeConsoleWebSocket(principal, pathname) {
         return principal.open;
     return permission !== null && grantsAllow(principal.grants, permission);
 }
-/** Audit detail for an RPC: type, target and parameter key names only. */
-export function rpcAuditDetail(message) {
+/**
+ * JSON length of the detail of one audit entry. The gateway stores at most 4096 characters of
+ * JSON detail; statements are cut so the whole detail stays below this budget once serialised
+ * (escapes such as `\n` count twice), so the stored detail always parses.
+ */
+export const AUDIT_DETAIL_JSON_LIMIT = 3_500;
+function statementTexts(message, reply) {
+    if (message.type === 'db:execute' || message.type === 'db:query')
+        return typeof message.sql === 'string' && message.sql ? [message.sql] : [];
+    const data = reply?.data && typeof reply.data === 'object' ? reply.data : undefined;
+    return (Array.isArray(data?.statements) ? data.statements : []).filter((entry) => typeof entry === 'string' && !!entry);
+}
+/**
+ * Statement text of Console SQL (`db:query` / `db:execute`, the DDL `db:schema:apply` ran or
+ * would have run), literals redacted; result rows are never recorded.
+ */
+function databaseStatementDetail(message, reply, options) {
+    if (message.type !== 'db:execute' && message.type !== 'db:query' && message.type !== 'db:schema:apply')
+        return {};
+    const change = message.type === 'db:schema:apply' && message.change && typeof message.change === 'object' ? message.change : {};
+    const texts = statementTexts(message, reply);
+    const redact = options?.redactSql;
+    return {
+        ...(message.type === 'db:execute' && message.dryRun === true ? { dryRun: true } : {}),
+        ...(typeof change.kind === 'string' ? { change: change.kind.slice(0, 64) } : {}),
+        ...(typeof change.table === 'string' ? { table: change.table.slice(0, 256) } : {}),
+        ...(texts.length && redact
+            ? { statements: texts.map(text => { try {
+                    return redact(text);
+                }
+                catch {
+                    return '[unavailable]';
+                } }) }
+            : texts.length ? { statementLength: texts.reduce((total, text) => total + text.length, 0) } : {}),
+    };
+}
+/** Cuts the longest statement until the serialised detail fits {@link AUDIT_DETAIL_JSON_LIMIT}. */
+function fitAuditDetail(detail) {
+    const statements = Array.isArray(detail.statements) ? [...detail.statements] : undefined;
+    if (!statements)
+        return detail;
+    let truncated = false;
+    for (;;) {
+        const candidate = { ...detail, statements, ...(truncated ? { truncated: true } : {}) };
+        const overflow = JSON.stringify(candidate).length - AUDIT_DETAIL_JSON_LIMIT;
+        if (overflow <= 0)
+            return { ...candidate, statements: Object.freeze(statements) };
+        truncated = true;
+        let longest = 0;
+        for (let index = 1; index < statements.length; index += 1)
+            if (statements[index].length > statements[longest].length)
+                longest = index;
+        const text = statements[longest];
+        if (text.length <= 1) {
+            statements.splice(longest, 1);
+            continue;
+        }
+        statements[longest] = `${text.slice(0, Math.max(0, text.length - overflow - 1))}…`;
+    }
+}
+/**
+ * Audit detail for an RPC: type, target and parameter key names only — plus the statement text
+ * of Console database writes (pass the reply so the DDL a schema change ran is recorded), with
+ * literals redacted by `options.redactSql`.
+ */
+export function rpcAuditDetail(message, reply, options) {
     const data = message.data && typeof message.data === 'object' && !Array.isArray(message.data)
         ? Object.keys(message.data).sort()
         : [];
     const keys = Object.keys(message).filter(key => key !== 'type' && key !== 'requestId' && key !== 'data').sort();
-    return Object.freeze({ type: String(message.type ?? ''), keys: Object.freeze([...new Set([...keys, ...data])]) });
+    return Object.freeze(fitAuditDetail({
+        type: String(message.type ?? '').slice(0, 256),
+        keys: Object.freeze([...new Set([...keys, ...data])].slice(0, 64).map(key => key.slice(0, 128))),
+        ...databaseStatementDetail(message, reply, options),
+        ...envDetail(message),
+    }));
+}
+const auditName = (value, max) => typeof value === 'string' && value ? value.slice(0, max) : undefined;
+/**
+ * Which dotenv file and variable names an `env:reveal` / `env:save` touched (issue #1250). Never a
+ * value: `changes[].value` and `content` are not read.
+ */
+function envDetail(message) {
+    if (message.type !== 'env:reveal' && message.type !== 'env:save')
+        return {};
+    const data = message.data && typeof message.data === 'object' && !Array.isArray(message.data) ? message.data : {};
+    const pick = (key) => message[key] ?? data[key];
+    const file = auditName(pick('filename'), 64);
+    if (message.type === 'env:reveal') {
+        const key = auditName(pick('key'), 128);
+        return { ...(file ? { file } : {}), ...(key ? { key } : {}) };
+    }
+    const changes = Array.isArray(pick('changes')) ? pick('changes') : undefined;
+    if (!changes)
+        return { ...(file ? { file } : {}), ...(pick('content') !== undefined ? { mode: 'replace' } : {}) };
+    const set = [];
+    const deleted = [];
+    for (const change of changes.slice(0, 64)) {
+        if (!change || typeof change !== 'object')
+            continue;
+        const key = auditName(change.key, 128);
+        if (key)
+            (change.delete === true ? deleted : set).push(key);
+    }
+    return {
+        ...(file ? { file } : {}),
+        set: Object.freeze(set),
+        deleted: Object.freeze(deleted),
+        ...(changes.length > 64 ? { truncated: true } : {}),
+    };
 }
 export function rpcAuditTarget(rule) {
     if (!rule)

package/lib/console-rest-pages-helpers.js

@@ -15,7 +15,13 @@ const INTROSPECTION_PAGE_SIZES = {
     endpoints: 30,
     bindings: 30,
     mcp: 30,
+    'recent-turns': 20,
 };
+/** Owning plugin of a capability row (`ConsoleIntrospectionOwner`, #1250): searchable by `q`. */
+const OWNER_FIELDS = [
+    (item) => stringProp(item, 'pluginInstance'),
+    (item) => stringProp(item, 'pluginPackage'),
+];
 // ---------------------------------------------------------------------------
 // Runtime snapshot introspection
 // ---------------------------------------------------------------------------
@@ -28,6 +34,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (c) => stringProp(c, 'pattern'),
                 (c) => stringProp(c, 'desc'),
                 (c) => stringProp(c, 'plugin'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -39,6 +46,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (m) => stringProp(m, 'phase'),
                 (m) => stringProp(m, 'target'),
                 (m) => stringProp(m, 'source'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -48,6 +56,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (c) => stringProp(c, 'name'),
                 (c) => stringProp(c, 'owner'),
                 (c) => stringProp(c, 'source'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -64,11 +73,22 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
         },
         {
             kind: 'bindings',
-            collect: (value) => ({ rows: value?.bindings?.() ?? [] }),
+            collect: async (value) => ({ rows: await value?.bindings?.() ?? [] }),
             fields: [
                 (a) => stringProp(a, 'name'),
                 (a) => stringProp(a, 'provider'),
                 (a) => stringProp(a, 'model'),
+                (a) => stringProp(a, 'displayName'),
+            ],
+        },
+        {
+            // #1250: the Agent workbench's recent conversations come from the turn trace archive, newest first.
+            kind: 'recent-turns',
+            collect: async (value) => ({ rows: await value?.recentTurns?.() ?? [] }),
+            fields: [
+                (t) => stringProp(t, 'sessionDisplayName'),
+                (t) => stringProp(t, 'sessionKey'),
+                (t) => stringProp(t, 'status'),
             ],
         },
         {
@@ -78,6 +98,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (t) => stringProp(t, 'name'),
                 (t) => stringProp(t, 'source'),
                 (t) => stringProp(t, 'description'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -91,6 +112,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (section) => stringProp(section, 'layer'),
                 (section) => stringProp(section, 'retention'),
                 (section) => stringProp(section, 'source'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -113,7 +135,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
             const lease = kind === 'endpoints' ? null : ctx.acquireAgentRuntime?.() ?? null;
             try {
                 const introspection = lease?.value.introspection;
-                const { rows, note } = collect(introspection);
+                const { rows, note } = await collect(introspection);
                 const query = url.searchParams;
                 const filter = query.get('filter')?.trim() || undefined;
                 const filtered = filterByFields([...rows], filter, fields);

package/lib/console-rest-pages.d.ts

@@ -35,7 +35,10 @@ export interface ConsoleAgentIntrospection {
     commands?(): readonly unknown[];
     middlewares?(): readonly unknown[];
     components?(): readonly unknown[];
-    bindings?(): readonly unknown[];
+    /** Agent bindings with the provider / model they actually run on (may read the provider graph). */
+    bindings?(): readonly unknown[] | Promise<readonly unknown[]>;
+    /** Recent Agent turns from the trace archive, newest first (#1250). */
+    recentTurns?(): readonly unknown[] | Promise<readonly unknown[]>;
     tools?(): readonly unknown[];
     promptSections?(): readonly unknown[];
     mcp?(): {

package/lib/console-rest-pages.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import { readJsonBody } from './json-body.js';
 import { jsonResponse } from '@zhin.js/host-http-contract';
 import { MarketplaceDetailCache, MarketplaceRegistry, isValidNpmPackageName, } from './marketplace-registry.js';
+import { informativeKeywords, isLocale, normalizePluginCategory, packageAuthorName, pickLocalizedText, readPluginMarketplaceMetadata, } from '@zhin.js/plugin-runtime';
 import { clampPositiveInt, decodePathParam, logInternalError, normalizeBase, parsePositiveInt, registerAgentSessionRoutes, registerIntrospectionRoutes, requireWriteScope, trimTrailingSlashes, } from './console-rest-pages-helpers.js';
 const PLUGINS_CACHE_TTL = 5 * 60 * 1000;
 const PACKAGE_DETAIL_CACHE_TTL = 5 * 60 * 1000;
@@ -202,6 +203,10 @@ function registerLogsRoutes(route, base, ctx) {
         });
     }, { summary: 'Cleanup old system logs', tags: ['console', 'logs'] });
 }
+/** Locale-keyed texts from an untrusted registry entry (reuses the published-manifest reader). */
+function localizedTextOf(value) {
+    return readPluginMarketplaceMetadata({ metadata: { displayNameI18n: value } }).displayNameI18n;
+}
 // ---------------------------------------------------------------------------
 // marketplace（legacy marketplace-rest-api.ts；plugins.json + npmmirror）
 // ---------------------------------------------------------------------------
@@ -225,20 +230,25 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
             const versions = meta.versions;
             const latestInfo = latest && versions ? versions[latest] : undefined;
             const time = meta.time;
+            // Marketplace fields come from the published manifest (`zhin.metadata`); the author is the
+            // package's author / maintainers, never the publishing account (`_npmUser`, a release bot).
+            const market = readPluginMarketplaceMetadata(latestInfo?.zhin);
             return {
                 name: meta.name,
                 version: latest,
-                description: meta.description || '',
+                ...(market.displayName ? { displayName: market.displayName } : {}),
+                ...(market.displayNameI18n ? { displayNameI18n: market.displayNameI18n } : {}),
+                ...(market.descriptionI18n ? { descriptionI18n: market.descriptionI18n } : {}),
+                ...(market.category ? { category: market.category } : {}),
+                description: latestInfo?.description || meta.description || '',
                 readme: meta.readme || '',
                 license: meta.license || latestInfo?.license || '',
                 homepage: meta.homepage || latestInfo?.homepage || '',
                 repository: meta.repository?.url ||
                     latestInfo?.repository?.url ||
                     '',
-                author: typeof meta.author === 'string'
-                    ? meta.author
-                    : meta.author?.name || '',
-                keywords: latestInfo?.keywords || [],
+                author: packageAuthorName(latestInfo ?? {}) ?? packageAuthorName(meta) ?? '',
+                keywords: informativeKeywords(latestInfo?.keywords),
                 engines: latestInfo?.engines || {},
                 peerDependencies: latestInfo?.peerDependencies || {},
                 versions: Object.keys(versions || {}),
@@ -250,30 +260,46 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
         const q = url.searchParams.get('q') ?? url.searchParams.get('keyword') ?? '';
         const pageNum = Math.max(1, parseInt(url.searchParams.get('page') ?? '1', 10) || 1);
         const pageSize = Math.min(100, Math.max(1, parseInt(url.searchParams.get('size') ?? url.searchParams.get('limit') ?? '20', 10) || 20));
-        const category = url.searchParams.get('category') ?? undefined;
+        const rawCategory = url.searchParams.get('category') || undefined;
+        const category = rawCategory === undefined ? undefined : normalizePluginCategory(rawCategory) ?? rawCategory;
         const official = url.searchParams.get('official') ?? undefined;
+        const rawLocale = url.searchParams.get('locale');
+        const locale = isLocale(rawLocale) ? rawLocale : undefined;
         const searchKeyword = q.trim().toLowerCase();
         try {
             const allPlugins = (await registry.list());
-            let plugins = allPlugins.map((p) => ({
-                name: p.name,
-                displayName: p.displayName || '',
-                version: p.version || '',
-                description: p.description || '',
-                author: p.author || '',
-                isOfficial: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
-                official: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
-                category: p.category || 'util',
-                keywords: p.tags || [],
-                npm: p.npm || `https://www.npmjs.com/package/${p.name}`,
-                date: p.lastUpdate || '',
-                downloads: p.downloads || { weekly: 0, monthly: 0 },
-                readme: p.readme || '',
-                license: p.license || '',
-            }));
+            let plugins = allPlugins.map((p) => {
+                const displayNameI18n = localizedTextOf(p.displayNameI18n);
+                const descriptionI18n = localizedTextOf(p.descriptionI18n);
+                const displayName = typeof p.displayName === 'string' ? p.displayName : '';
+                const description = typeof p.description === 'string' ? p.description : '';
+                return {
+                    name: p.name,
+                    // `locale` resolves the display texts for the caller; translations stay available either way.
+                    displayName: locale ? pickLocalizedText(displayNameI18n, locale, displayName) ?? '' : displayName,
+                    ...(displayNameI18n ? { displayNameI18n } : {}),
+                    version: p.version || '',
+                    description: locale ? pickLocalizedText(descriptionI18n, locale, description) ?? '' : description,
+                    ...(descriptionI18n ? { descriptionI18n } : {}),
+                    author: p.author || '',
+                    isOfficial: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
+                    official: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
+                    category: normalizePluginCategory(p.category) ?? 'utility',
+                    keywords: informativeKeywords(p.tags),
+                    npm: p.npm || `https://www.npmjs.com/package/${p.name}`,
+                    date: p.lastUpdate || '',
+                    downloads: p.downloads || { weekly: 0, monthly: 0 },
+                    readme: p.readme || '',
+                    license: p.license || '',
+                };
+            });
             if (searchKeyword) {
                 plugins = plugins.filter((p) => {
-                    const haystack = [p.name, p.displayName, p.description, ...(p.keywords || [])]
+                    const haystack = [
+                        p.name, p.displayName, p.description,
+                        ...Object.values(p.displayNameI18n ?? {}), ...Object.values(p.descriptionI18n ?? {}),
+                        ...p.keywords,
+                    ]
                         .join(' ')
                         .toLowerCase();
                     return haystack.includes(searchKeyword);