@zhin.js/host-http 1.2.0 → 1.2.2

package/lib/access-control.d.ts

@@ -122,6 +122,23 @@ export type ConsoleHttpDecision = Readonly<{
 export declare function authorizeConsoleHttp(principal: ConsolePrincipal | undefined, method: string, relativePath: string): ConsoleHttpDecision;
 /** WebSocket upgrade authorization for non-bootstrap principals. */
 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

@@ -128,13 +128,81 @@ 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),
+    }));
 }
 export function rpcAuditTarget(rule) {
     if (!rule)

package/lib/console-plugin-rpc.d.ts

@@ -1,7 +1,14 @@
 import type { RuntimeConsoleRpcContext, RuntimeConsoleRpcMessage, RuntimeConsoleRpcReply } from './console-rpc.js';
+/**
+ * Refusal of the global plugin switch (`plugin:set-enabled`, `feature.set-enabled` at `global`)
+ * by an instance: the switch is a gateway transaction (stop → write `disable_plugins` → start,
+ * rollback on failure) and is never written by the instance itself (ADR 0054 §4).
+ */
+export declare const PLUGIN_SWITCH_REQUIRES_GATEWAY = "\u63D2\u4EF6\u5168\u5C40\u542F\u505C\u7531\u7BA1\u7406\u7F51\u5173\u6267\u884C\uFF08\u505C\u6B62\u5B9E\u4F8B \u2192 \u5199\u5165 disable_plugins \u2192 \u542F\u52A8\uFF0C\u5931\u8D25\u56DE\u6EDA\uFF09\uFF1A\u8BF7\u5728 zhin start \u542F\u52A8\u7684 Console \u4E2D\u64CD\u4F5C\uFF0C\u6216\u8FD0\u884C zhin enable / zhin disable <\u63D2\u4EF6>";
 /**
  * Dispatches the plugin-management slice; undefined means the type belongs elsewhere. Package
  * installs / updates / uninstalls are not handled in the instance: they are gateway dependency
- * transactions (`gateway.packages.*`, ADR 0054 §4) that stop the instance first.
+ * transactions (`gateway.packages.*`, ADR 0054 §4) that stop the instance first, and so is the
+ * global plugin switch (`plugin:set-enabled`, refused here).
  */
 export declare function dispatchPluginConsoleRpc(type: string, message: RuntimeConsoleRpcMessage, ctx: RuntimeConsoleRpcContext): Promise<RuntimeConsoleRpcReply | undefined>;

package/lib/console-plugin-rpc.js

@@ -1,39 +1,24 @@
 import { PLUGIN_RPC } from '@zhin.js/console-protocol';
+/**
+ * Refusal of the global plugin switch (`plugin:set-enabled`, `feature.set-enabled` at `global`)
+ * by an instance: the switch is a gateway transaction (stop → write `disable_plugins` → start,
+ * rollback on failure) and is never written by the instance itself (ADR 0054 §4).
+ */
+export const PLUGIN_SWITCH_REQUIRES_GATEWAY = '插件全局启停由管理网关执行（停止实例 → 写入 disable_plugins → 启动，失败回滚）：请在 zhin start 启动的 Console 中操作，或运行 zhin enable / zhin disable <插件>';
 /**
  * Dispatches the plugin-management slice; undefined means the type belongs elsewhere. Package
  * installs / updates / uninstalls are not handled in the instance: they are gateway dependency
- * transactions (`gateway.packages.*`, ADR 0054 §4) that stop the instance first.
+ * transactions (`gateway.packages.*`, ADR 0054 §4) that stop the instance first, and so is the
+ * global plugin switch (`plugin:set-enabled`, refused here).
  */
 export async function dispatchPluginConsoleRpc(type, message, ctx) {
     const requestId = message.requestId;
     try {
         switch (type) {
-            case PLUGIN_RPC.SET_ENABLED: {
-                const instanceKey = stringField(message, 'instanceKey');
-                const enabled = message.enabled;
-                if (!instanceKey || typeof enabled !== 'boolean') {
-                    return { requestId, error: 'instanceKey and boolean enabled are required' };
-                }
-                if (!ctx.setPluginEnabled) {
-                    return { requestId, error: 'Plugin lifecycle management is not configured' };
-                }
-                const lifecycle = await ctx.setPluginEnabled(instanceKey, enabled);
-                ctx.publishEvent?.('plugin:lifecycle-updated', { instanceKey, enabled });
-                if (ctx.requestRestart) {
-                    setTimeout(() => void Promise.resolve(ctx.requestRestart?.()).catch(() => undefined), 500);
-                }
-                return {
-                    requestId,
-                    data: {
-                        success: true,
-                        instanceKey,
-                        enabled,
-                        disabled: lifecycle.disabled,
-                        restartRequired: true,
-                        message: `${instanceKey} 已${enabled ? '启用' : '停用'}，Host 正在重启`,
-                    },
-                };
-            }
+            case PLUGIN_RPC.SET_ENABLED:
+                // Global plugin on / off is a management gateway transaction (ADR 0054 §4): the gateway
+                // answers it before forwarding. Reaching the instance means no gateway is in front.
+                return { requestId, error: PLUGIN_SWITCH_REQUIRES_GATEWAY };
             case PLUGIN_RPC.INSPECT:
             case PLUGIN_RPC.APPLY:
             case PLUGIN_RPC.PLAN_VERIFICATION:

package/lib/console-rpc-extended/contracts.d.ts

@@ -1,3 +1,4 @@
+import type { ConsoleAdapterLoginDeclaration, ConsoleLoginFlow, ConsoleLoginOutcome } from '@zhin.js/console-protocol';
 interface LoginEndpointIdentity {
     readonly canonicalId: string;
     readonly instanceId: string;
@@ -20,27 +21,32 @@ export interface ConsoleRpcExtendedCtx {
     };
     /** Narrow generation-bound persistent-job port; null when Assistant is disabled. */
     resolveScheduleEngine?: () => ConsoleScheduleEngine | null | undefined;
-    /** LoginAssist list/submit/cancel（刷新后仍可消费扫码/滑块待办）。 */
-    loginAssist?: {
-        listPending(): readonly {
-            id: string;
-            adapter: string;
-            endpointKey: string;
-            endpointIdentity?: LoginEndpointIdentity;
-            type: string;
-            payload: Record<string, unknown>;
-            createdAt: number;
-            expiresAt?: number;
-        }[];
-        submit(id: string, value: string | Record<string, unknown>, endpointIdentity?: LoginEndpointIdentity): boolean;
-        cancel(id: string, reason?: string, endpointIdentity?: LoginEndpointIdentity): boolean;
-    };
+    /** LoginAssist list/submit/cancel（刷新后仍可消费扫码/滑块待办）；ADR 0058 flow methods are optional. */
+    loginAssist?: ConsoleLoginAssistPort;
+    /** ADR 0058: the Endpoint's login declaration and lease-scoped login control (`null` = unknown Endpoint). */
+    withEndpointLogin?: <T>(adapter: string, endpointKey: string, run: (login: ConsoleEndpointLoginAccess) => T | Promise<T>) => Promise<T | null>;
     /** Authenticated Root adapter; mutation DTOs deliberately contain no principal/decision fields. */
     workroomProfileControl?: ConsoleWorkroomProfileControlPort;
     /** Authenticated HTTP principal; never accepted from the RPC body. */
     authenticatedPrincipal?: Readonly<{
         principalId: string;
     }>;
+    /**
+     * The Endpoint the caller was authorized for when its grant covers this call only at an adapter /
+     * endpoint scope (never set for global grants, owners or in-process callers). Handlers that act on
+     * login tasks or flows restrict themselves to it; set by the dispatcher, never read from the body.
+     */
+    authorizedEndpoint?: Readonly<{
+        adapter: string;
+        endpointKey: string;
+    }>;
+    /**
+     * Whether the caller holds `endpoint.operate` on one Endpoint (set by the dispatcher from the
+     * authenticated principal, never read from the body). Login read RPCs return live challenge
+     * material (QR image, sensitive blocks, verification links, legacy `payload.image` / `url`) only
+     * when it says yes; absent (in-process callers without a principal) = trusted.
+     */
+    canOperateEndpoint?: (adapter: string, endpointKey: string) => boolean;
     workroomKnowledgeControl?: ConsoleWorkroomKnowledgeControlPort;
 }
 export interface ConsoleWorkroomProfileControlPort {
@@ -118,11 +124,60 @@ export interface ConsoleScheduleEngine {
     resumeJob(id: string): Promise<boolean>;
     listJobs(): Promise<Record<string, unknown>[]>;
 }
+/** `data` next to `error` carries a machine-readable code (e.g. `{ code: 'unsupported' }`). */
 export type ExtendedRpcResult = {
     data: unknown;
 } | {
     error: string;
+    data?: unknown;
 };
+/** Structural LoginAssist port (host/http must not import `@zhin.js/core`). */
+export interface ConsoleLoginAssistPort {
+    listPending(): readonly {
+        id: string;
+        adapter: string;
+        endpointKey: string;
+        endpointIdentity?: LoginEndpointIdentity;
+        type: string;
+        payload: Record<string, unknown>;
+        createdAt: number;
+        expiresAt?: number;
+        flowId?: string;
+        challengeId?: string;
+    }[];
+    submit(id: string, value: string | Record<string, unknown>, endpointIdentity?: LoginEndpointIdentity): boolean;
+    cancel(id: string, reason?: string, endpointIdentity?: LoginEndpointIdentity): boolean;
+    /** ADR 0058 */
+    listFlows?(): readonly ConsoleLoginFlow[];
+    getFlow?(adapter: string, endpointKey: string): ConsoleLoginFlow | undefined;
+    getFlowById?(id: string): ConsoleLoginFlow | undefined;
+    /**
+     * Event-safe copy of a flow (core `withoutLoginMedia`): no QR image, sensitive blocks redacted,
+     * verification links dropped. Returned to readers without `endpoint.operate` on the flow's
+     * Endpoint; without it the host strips every challenge's media and blocks.
+     */
+    eventSafeFlow?(flow: ConsoleLoginFlow): ConsoleLoginFlow;
+    submitAndWait?(id: string, value: string | Record<string, unknown>, options?: {
+        endpointIdentity?: LoginEndpointIdentity;
+        timeoutMs?: number;
+    }): Promise<{
+        accepted: boolean;
+        outcome?: ConsoleLoginOutcome;
+        pending?: boolean;
+        flow?: ConsoleLoginFlow;
+    }>;
+}
+export interface ConsoleEndpointLoginAccess {
+    readonly declaration?: ConsoleAdapterLoginDeclaration;
+    readonly control?: {
+        relogin?(request: {
+            signal?: AbortSignal;
+        }): Promise<void>;
+        refreshChallenge?(request: {
+            signal?: AbortSignal;
+        }): Promise<void>;
+    };
+}
 export interface ScheduleJobRow {
     id: string;
     cron: string;

package/lib/console-rpc-extended/dispatcher.js

@@ -1,6 +1,6 @@
 import { addCron, listSchedule, mutateCron, validateCron } from './schedule-rpc.js';
 import { actOnRequest, listInbox, listInboxMessages, listPendingRequests, listRecentInboxMessages, mapNoticeRow, mapRequestRow, markInboxConsumed, TABLE_NOTICE, TABLE_REQUEST, } from './inbox-rpc.js';
-import { cancelLogin, listLoginPending, submitLogin } from './login-rpc.js';
+import { cancelLogin, controlLogin, getLoginFlow, listLoginFlows, listLoginPending, submitLogin } from './login-rpc.js';
 import { deleteFriend, groupWriteOp, listChannels, listFriends, listGroupMembers, listGroups, } from './endpoint-rpc.js';
 import { mutateWorkroomKnowledge, mutateWorkroomProfile } from './workroom-rpc.js';
 export async function dispatchExtendedConsoleRpc(type, data, ctx) {
@@ -32,11 +32,18 @@ export async function dispatchExtendedConsoleRpc(type, data, ctx) {
         case 'request.reject':
             return actOnRequest(type, d, ctx);
         case 'login.list':
-            return listLoginPending(ctx);
+            return listLoginPending(d, ctx);
         case 'login.submit':
             return submitLogin(d, ctx);
         case 'login.cancel':
             return cancelLogin(d, ctx);
+        case 'login.flow.list':
+            return listLoginFlows(d, ctx);
+        case 'login.flow.get':
+            return getLoginFlow(d, ctx);
+        case 'login.relogin':
+        case 'login.refresh':
+            return controlLogin(type, d, ctx);
         case 'request.consumed':
             return markInboxConsumed(d, ctx, TABLE_REQUEST);
         case 'notice.consumed':

package/lib/console-rpc-extended/index.d.ts

@@ -1,2 +1,3 @@
-export type { ConsoleRpcExtendedCtx, ConsoleScheduleEngine, ConsoleWorkroomKnowledgeControlPort, ConsoleWorkroomProfileControlPort, ExtendedRpcResult, } from './contracts.js';
+export type { ConsoleRpcExtendedCtx, ConsoleScheduleEngine, ConsoleWorkroomKnowledgeControlPort, ConsoleWorkroomProfileControlPort, ExtendedRpcResult, ConsoleLoginAssistPort, ConsoleEndpointLoginAccess, } from './contracts.js';
+export { loginAuditDetail, LOGIN_SUBMIT_WAIT_MS } from './login-rpc.js';
 export { dispatchExtendedConsoleRpc } from './dispatcher.js';

package/lib/console-rpc-extended/index.js

@@ -1 +1,2 @@
+export { loginAuditDetail, LOGIN_SUBMIT_WAIT_MS } from './login-rpc.js';
 export { dispatchExtendedConsoleRpc } from './dispatcher.js';

package/lib/console-rpc-extended/login-rpc.d.ts

@@ -1,4 +1,27 @@
+import { LOGIN_RPC } from '@zhin.js/console-protocol';
 import type { ConsoleRpcExtendedCtx, ExtendedRpcResult } from './contracts.js';
-export declare function listLoginPending(ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult;
-export declare function submitLogin(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult;
+/** `login.submit` with `wait: true` waits at most this long for the login result. */
+export declare const LOGIN_SUBMIT_WAIT_MS = 15000;
+export declare function listLoginPending(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult;
+/**
+ * `login.submit { taskId, value, endpointIdentity?, adapter?, endpointKey?, wait? }`.
+ * `value` is a string (legacy) or `{ action, values }`. With `wait: true` the reply carries the login
+ * result (`{ accepted, outcome, flow }`) or `{ accepted, pending: true }` after 15 s; without it the
+ * legacy `{ success: true }` reply is unchanged.
+ */
+export declare function submitLogin(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): Promise<ExtendedRpcResult>;
 export declare function cancelLogin(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult;
+/**
+ * `login.flow.list { adapter?, endpointKey? }`: latest flow per Endpoint. Live challenge material
+ * only for Endpoints the caller may operate; the event-safe form otherwise (ADR 0058 §8).
+ */
+export declare function listLoginFlows(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult;
+/** `login.flow.get { flowId } | { adapter, endpointKey }` → `{ flow: … | null }`. */
+export declare function getLoginFlow(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult;
+/** `login.relogin` / `login.refresh { adapter, endpointKey }` through the Endpoint's login port. */
+export declare function controlLogin(type: typeof LOGIN_RPC.RELOGIN | typeof LOGIN_RPC.REFRESH, d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): Promise<ExtendedRpcResult>;
+/**
+ * Audit detail of a login RPC reply: the result category only (never values, never messages).
+ * `undefined` for other RPCs.
+ */
+export declare function loginAuditDetail(type: unknown, data: unknown): Readonly<Record<string, string>> | undefined;