@zhin.js/host-http 1.2.1 → 1.2.2

package/lib/console-rpc-handlers.js

@@ -250,15 +250,100 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
             const page = positiveInteger(message.page, 1);
             const pageSize = Math.min(positiveInteger(message.pageSize, 50), 500);
             const where = recordField(message.where);
+            const order = recordField(message.orderBy);
+            if (message.orderBy !== undefined && message.orderBy !== null
+                && (!order || typeof order.column !== 'string' || (order.direction !== 'asc' && order.direction !== 'desc'))) {
+                errorReply(payloads, requestId, 'orderBy must be { column, direction: "asc" | "desc" }');
+                return true;
+            }
             if (!ctx.database) {
                 emit({ requestId, data: { rows: [], total: 0, page, pageSize } });
                 return true;
             }
             try {
-                emit({ requestId, data: await ctx.database.select(table, page, pageSize, where) });
+                const orderBy = order ? { column: order.column, direction: order.direction } : undefined;
+                emit({ requestId, data: await ctx.database.select(table, page, pageSize, where, orderBy) });
+            }
+            catch (error) {
+                emit({ requestId, error: `Failed to select: ${errorMessage(error)}`, ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:query': {
+            const sql = sqlField(message);
+            if (!sql) {
+                errorReply(payloads, requestId, `sql is required (at most ${MAX_CONSOLE_SQL_LENGTH} characters)`);
+                return true;
+            }
+            if (!ctx.database?.query) {
+                unsupportedDatabaseFeature(payloads, requestId, 'SQL query');
+                return true;
+            }
+            try {
+                const maxRows = typeof message.maxRows === 'number' ? message.maxRows : undefined;
+                emit({ requestId, data: await ctx.database.query(sql, maxRows ? { maxRows } : undefined) });
             }
             catch (error) {
-                emit({ requestId, error: `Failed to select: ${errorMessage(error)}` });
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:execute': {
+            const sql = sqlField(message);
+            if (!sql) {
+                errorReply(payloads, requestId, `sql is required (at most ${MAX_CONSOLE_SQL_LENGTH} characters)`);
+                return true;
+            }
+            if (!ctx.database?.execute) {
+                unsupportedDatabaseFeature(payloads, requestId, 'SQL execution');
+                return true;
+            }
+            try {
+                emit({ requestId, data: await ctx.database.execute(sql, { dryRun: message.dryRun === true }) });
+            }
+            catch (error) {
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:schema:describe': {
+            const table = stringField(message, 'table');
+            if (!table) {
+                errorReply(payloads, requestId, 'table is required');
+                return true;
+            }
+            if (!ctx.database?.describe) {
+                unsupportedDatabaseFeature(payloads, requestId, 'Schema inspection');
+                return true;
+            }
+            try {
+                emit({ requestId, data: await ctx.database.describe(table) });
+            }
+            catch (error) {
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:schema:preview':
+        case 'db:schema:apply': {
+            const change = recordField(message.change);
+            if (!change) {
+                errorReply(payloads, requestId, 'change is required');
+                return true;
+            }
+            const database = ctx.database;
+            if (!database?.previewSchema || !database.applySchema) {
+                unsupportedDatabaseFeature(payloads, requestId, 'Schema editing');
+                return true;
+            }
+            try {
+                const plan = type === 'db:schema:apply'
+                    ? await database.applySchema(change, typeof message.confirm === 'string' ? message.confirm : undefined)
+                    : await database.previewSchema(change);
+                emit({ requestId, data: plan });
+            }
+            catch (error) {
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
             }
             return true;
         }
@@ -577,6 +662,43 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
             return false;
     }
 }
+/** Longest statement text the Console SQL editor sends. */
+export const MAX_CONSOLE_SQL_LENGTH = 100_000;
+function sqlField(message) {
+    const value = message.sql;
+    return typeof value === 'string' && value.trim() && value.length <= MAX_CONSOLE_SQL_LENGTH ? value : '';
+}
+const REFUSAL_NAMES = new Set(['ConsoleSqlRefusal', 'ConsoleSchemaRefusal', 'ConsoleSelectRefusal', 'SqliteQueryTimeoutError']);
+/**
+ * `data.code` of a refusal by the database port (`read_only`, `protected_table`, …), and the DDL a
+ * failed `db:schema:apply` attempted (`data.statements`, for the audit log).
+ */
+/** SQLSTATE of a driver error (PostgreSQL `code`, mysql2 `sqlState`), e.g. `42501` insufficient privilege. */
+function sqlStateOf(error) {
+    const record = error;
+    for (const candidate of [record.sqlState, record.code]) {
+        if (typeof candidate === 'string' && /^[0-9A-Z]{5}$/u.test(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function refusalData(error) {
+    if (!(error instanceof Error))
+        return {};
+    const attempted = error.statements;
+    const statements = Array.isArray(attempted) && attempted.every(entry => typeof entry === 'string') ? { statements: attempted } : {};
+    if (error.name === 'GatewayOwnedTableError')
+        return { data: { code: 'protected_table', ...statements } };
+    const code = error.code;
+    const refused = REFUSAL_NAMES.has(error.name) && typeof code === 'string';
+    // The server's SQLSTATE lets the Console explain e.g. 42501 from the restricted account (ADR 0059 §4).
+    const sqlState = refused ? undefined : sqlStateOf(error);
+    const data = { ...(refused ? { code } : {}), ...(sqlState ? { sqlState } : {}), ...statements };
+    return Object.keys(data).length ? { data } : {};
+}
+function unsupportedDatabaseFeature(payloads, requestId, feature) {
+    payloads.push({ requestId, error: `${feature} is not supported by this database Host`, data: { code: 'unsupported' } });
+}
 export function stringField(message, key) {
     const value = message[key];
     return typeof value === 'string' ? value.trim() : '';

package/lib/console-rpc.js

@@ -1,5 +1,5 @@
-import { CONFIG_PATCH_LIMITS, CONFIG_RPC, } from '@zhin.js/console-protocol';
-import { authorizeConsoleRpc } from './access-control.js';
+import { CONFIG_PATCH_LIMITS, CONFIG_RPC, grantsAllow, } from '@zhin.js/console-protocol';
+import { authorizeConsoleRpc, principalAllows } from './access-control.js';
 import { dispatchExtendedConsoleRpc } from './console-rpc-extended/index.js';
 import { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
 import { configurationSaveMessage, dispatchHostResourceConsoleRpc, invalidProjectPatchOperations, } from './console-rpc-handlers.js';
@@ -9,6 +9,20 @@ export function pickRpcReply(message, payloads) {
         ?? payloads[payloads.length - 1]
         ?? null);
 }
+/**
+ * The Endpoint a principal was admitted for when only an adapter / endpoint-scoped grant covers the
+ * call (B-1): handlers must then stay inside it. `undefined` when a global grant covers it.
+ */
+function scopedAuthorizedEndpoint(principal, decision) {
+    if (principal.kind === 'bootstrap' || !decision.permission || !decision.rule)
+        return undefined;
+    if (grantsAllow(principal.grants, decision.permission))
+        return undefined;
+    const target = decision.rule.target;
+    if (target.kind !== 'endpoint')
+        return undefined;
+    return Object.freeze({ adapter: target.adapter, endpointKey: target.endpoint });
+}
 export async function dispatchRuntimeConsoleRpc(message, ctx) {
     const payloads = [];
     const emit = (payload) => {
@@ -16,19 +30,30 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
     };
     const type = String(message.type ?? '');
     const requestId = message.requestId;
+    let authorizedEndpoint;
+    let canOperateEndpoint;
     if (ctx.principal) {
-        const decision = authorizeConsoleRpc(ctx.principal, message);
+        const principal = ctx.principal;
+        const decision = authorizeConsoleRpc(principal, message);
         if (!decision.allowed) {
             emit({ requestId, error: decision.error, code: decision.code });
             return payloads;
         }
+        authorizedEndpoint = scopedAuthorizedEndpoint(principal, decision);
+        // Same grant check the map applies to `login.submit` for that Endpoint (ADR 0058 §8).
+        canOperateEndpoint = (adapter, endpointKey) => principalAllows(principal, 'endpoint.operate', Object.freeze({ kind: 'endpoint', adapter, endpoint: endpointKey }));
     }
     // Extended RPC surface (cron/schedule、endpoint 社交/inbox)
     if (ctx.extended) {
-        const extended = await dispatchExtendedConsoleRpc(type, message, { ...ctx.extended, fullScope: ctx.authScope === 'full' });
+        const extended = await dispatchExtendedConsoleRpc(type, message, {
+            ...ctx.extended,
+            fullScope: ctx.authScope === 'full',
+            ...(authorizedEndpoint ? { authorizedEndpoint } : {}),
+            ...(canOperateEndpoint ? { canOperateEndpoint } : {}),
+        });
         if (extended !== undefined) {
             emit('error' in extended
-                ? { requestId, error: extended.error }
+                ? { requestId, error: extended.error, ...(extended.data !== undefined ? { data: extended.data } : {}) }
                 : { requestId, data: extended.data });
             return payloads;
         }

package/lib/index.d.ts

@@ -2,7 +2,7 @@ export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN,
 export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
 export { listHttpHostAddresses } from './addresses.js';
 export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, type AuthenticatedTokenPrincipal, type ConsoleAccess, type AuthScope, type TokenRegistryConfig, } from './token-registry.js';
-export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, type ConsoleAccessProvider, type ConsoleAuditEntry, type ConsoleBootstrapPrincipal, type ConsoleHttpDecision, type ConsolePrincipal, type ConsoleRequestMeta, type ConsoleRpcDecision, type ConsoleUserPrincipal, } from './access-control.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, type RpcAuditOptions, type ConsoleAccessProvider, type ConsoleAuditEntry, type ConsoleBootstrapPrincipal, type ConsoleHttpDecision, type ConsolePrincipal, type ConsoleRequestMeta, type ConsoleRpcDecision, type ConsoleUserPrincipal, } from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken, type ProtocolAuthRequest } from './protocol-auth.js';
 export { compileTrustProxy, hasForwardingHeaders, parseTrustProxy, resolveClientAddress, TrustProxyConfigError, type TrustProxyPredicate, type TrustProxySetting, } from './trust-proxy.js';
@@ -14,5 +14,5 @@ export { dispatchRuntimeConsoleRpc, pickRpcReply, type RuntimeConsolePage, type
 export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, type FileTreeNode, } from './project-files.js';
 export { registerConsoleRestPages, type ConsoleAgentIntrospection, type ConsoleAgentRuntime, type ConsoleAgentSessionTree, type ConsoleRestCtx, type ConsoleRestPagesOptions, } from './console-rest-pages.js';
-export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, } from './console-rpc-extended/index.js';
+export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, type ConsoleLoginAssistPort, type ConsoleEndpointLoginAccess, loginAuditDetail, LOGIN_SUBMIT_WAIT_MS, } from './console-rpc-extended/index.js';
 export * from './host-installer.js';

package/lib/index.js

@@ -13,5 +13,5 @@ export { dispatchRuntimeConsoleRpc, pickRpcReply, } from './console-rpc.js';
 export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, } from './project-files.js';
 export { registerConsoleRestPages, } from './console-rest-pages.js';
-export { dispatchExtendedConsoleRpc, } from './console-rpc-extended/index.js';
+export { dispatchExtendedConsoleRpc, loginAuditDetail, LOGIN_SUBMIT_WAIT_MS, } from './console-rpc-extended/index.js';
 export * from './host-installer.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -25,11 +25,11 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.2.1",
     "@zhin.js/host-http-contract": "1.2.0",
     "@zhin.js/logger": "1.1.3",
+    "@zhin.js/console-protocol": "1.2.2",
     "@zhin.js/schedule": "1.1.5",
-    "@zhin.js/plugin-runtime": "1.2.0"
+    "@zhin.js/plugin-runtime": "1.2.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/access-control.ts

@@ -237,13 +237,87 @@ export function authorizeConsoleWebSocket(principal: ConsolePrincipal, pathname:
   return permission !== null && grantsAllow(principal.grants, permission);
 }
 
-/** Audit detail for an RPC: type, target and parameter key names only. */
-export 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 const AUDIT_DETAIL_JSON_LIMIT = 3_500;
+
+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;
+}
+
+function statementTexts(message: Readonly<Record<string, unknown>>, reply: Readonly<Record<string, unknown>> | undefined): string[] {
+  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 as Record<string, unknown> : undefined;
+  return (Array.isArray(data?.statements) ? data.statements as unknown[] : []).filter((entry): entry is string => 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: Readonly<Record<string, unknown>>,
+  reply: Readonly<Record<string, unknown>> | undefined,
+  options: RpcAuditOptions | undefined,
+): Record<string, unknown> {
+  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 as Record<string, unknown> : {};
+  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: Record<string, unknown>): Record<string, unknown> {
+  const statements = Array.isArray(detail.statements) ? [...detail.statements as string[]] : 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: Readonly<Record<string, unknown>>,
+  reply?: Readonly<Record<string, unknown>>,
+  options?: RpcAuditOptions,
+): Readonly<Record<string, unknown>> {
   const data = message.data && typeof message.data === 'object' && !Array.isArray(message.data)
     ? Object.keys(message.data as Record<string, unknown>).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: ConsoleRpcPermissionRule | null): string | undefined {

package/src/console-rpc-extended/contracts.ts

@@ -1,3 +1,4 @@
+import type { ConsoleAdapterLoginDeclaration, ConsoleLoginFlow, ConsoleLoginOutcome } from '@zhin.js/console-protocol';
 interface LoginEndpointIdentity {
   readonly canonicalId: string;
   readonly instanceId: string;
@@ -21,25 +22,31 @@ export interface ConsoleRpcExtendedCtx {
   databaseHost?: { models: { get(name: string): unknown } };
   /** 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;
 }
 
@@ -98,7 +105,49 @@ export interface ConsoleScheduleEngine {
   listJobs(): Promise<Record<string, unknown>[]>;
 }
 
-export type ExtendedRpcResult = { data: unknown } | { error: string };
+/** `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>;
+  };
+}
 
 const CRON_NOT_WIRED =
   '持久化调度未接线：当前 Plugin Runtime ScheduleHost 仅支持插件注册的内存任务（list），' +

package/src/console-rpc-extended/dispatcher.ts

@@ -4,7 +4,7 @@ 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';
@@ -49,11 +49,18 @@ export async function dispatchExtendedConsoleRpc(
       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);

package/src/console-rpc-extended/index.ts

@@ -4,5 +4,8 @@ export type {
   ConsoleWorkroomKnowledgeControlPort,
   ConsoleWorkroomProfileControlPort,
   ExtendedRpcResult,
+  ConsoleLoginAssistPort,
+  ConsoleEndpointLoginAccess,
 } from './contracts.js';
+export { loginAuditDetail, LOGIN_SUBMIT_WAIT_MS } from './login-rpc.js';
 export { dispatchExtendedConsoleRpc } from './dispatcher.js';