@zhin.js/host-http 1.2.0 → 1.2.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-plugin-rpc.ts

@@ -5,10 +5,18 @@ import type {
   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 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: string,
@@ -18,32 +26,10 @@ export async function dispatchPluginConsoleRpc(
   const requestId = message.requestId as number | string | undefined;
   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/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';

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

@@ -1,39 +1,71 @@
-import type { ConsoleRpcExtendedCtx, ExtendedRpcResult } from './contracts.js';
+import { CONSOLE_LOGIN_UNSUPPORTED, LOGIN_RPC, type ConsoleLoginFlow } from '@zhin.js/console-protocol';
+import type { ConsoleEndpointLoginAccess, ConsoleLoginAssistPort, ConsoleRpcExtendedCtx, ExtendedRpcResult } from './contracts.js';
 import { strField } from './rpc-values.js';
 
-export function listLoginPending(ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult {
+const NOT_WIRED = '登录辅助未接线（LoginAssist 未挂载）';
+/** `login.submit` with `wait: true` waits at most this long for the login result. */
+export const LOGIN_SUBMIT_WAIT_MS = 15_000;
+
+export function listLoginPending(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult {
   const assist = ctx.loginAssist;
-  if (!assist) return { error: '登录辅助未接线（LoginAssist 未挂载）' };
-  const tasks = assist.listPending().map((task) => ({
+  if (!assist) return { error: NOT_WIRED };
+  const scope = loginScope(d, ctx);
+  if ('error' in scope) return scope;
+  const tasks = assist.listPending().filter((task) => inScope(scope, task)).map((task) => ({
     id: task.id,
     adapter: task.adapter,
     endpointKey: task.endpointKey,
     ...(task.endpointIdentity ? { endpointIdentity: task.endpointIdentity } : {}),
     type: task.type,
-    payload: task.payload,
+    payload: canOperate(ctx, task) ? task.payload : eventSafeLoginPayload(task.payload),
     createdAt: task.createdAt,
     expiresAt: task.expiresAt,
+    ...(task.flowId ? { flowId: task.flowId } : {}),
+    ...(task.challengeId ? { challengeId: task.challengeId } : {}),
   }));
   return { data: { tasks, count: tasks.length } };
 }
 
-export function submitLogin(
+/**
+ * `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 async function submitLogin(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
-): ExtendedRpcResult {
+): Promise<ExtendedRpcResult> {
   const assist = ctx.loginAssist;
-  if (!assist) return { error: '登录辅助未接线（LoginAssist 未挂载）' };
+  if (!assist) return { error: NOT_WIRED };
   const id = strField(d, 'taskId');
   if (!id) return { error: 'taskId is required' };
-  const raw = d.value ?? '';
-  const value = typeof raw === 'string' || (raw && typeof raw === 'object')
-    ? raw as string | Record<string, unknown>
-    : String(raw ?? '');
+  const value = readSubmitValue(d.value);
+  if (value === false) return { error: 'value must be a string or { action, values }' };
   const identity = readEndpointIdentity(d.endpointIdentity);
   if (identity === false) return { error: 'Invalid login Endpoint identity' };
-  const ok = identity ? assist.submit(id, value, identity) : assist.submit(id, value);
-  if (!ok) return { error: `login task not found: ${id}` };
-  return { data: { success: true } };
+  const target = checkTaskTarget(d, ctx, id);
+  if (target) return target;
+  try {
+    if (d.wait === true && assist.submitAndWait) {
+      const result = await assist.submitAndWait(id, value, {
+        ...(identity ? { endpointIdentity: identity } : {}),
+        timeoutMs: LOGIN_SUBMIT_WAIT_MS,
+      });
+      if (!result.accepted) return { error: `login task not found: ${id}` };
+      if (result.outcome) return { data: { accepted: true, outcome: result.outcome, ...(result.flow ? { flow: result.flow } : {}) } };
+      return { data: { accepted: true, pending: true, ...(result.flow ? { flow: result.flow } : {}) } };
+    }
+    const ok = identity ? assist.submit(id, value, identity) : assist.submit(id, value);
+    if (!ok) return { error: `login task not found: ${id}` };
+    return { data: { success: true } };
+  } catch (error) {
+    // LoginSubmissionError: the challenge stays open; its message never contains the value.
+    if (error instanceof Error && error.name === 'LoginSubmissionError') {
+      return { error: error.message, data: { code: (error as Error & { code?: string }).code ?? 'input_invalid' } };
+    }
+    throw error;
+  }
 }
 
 export function cancelLogin(
@@ -41,18 +73,219 @@ export function cancelLogin(
   ctx: ConsoleRpcExtendedCtx,
 ): ExtendedRpcResult {
   const assist = ctx.loginAssist;
-  if (!assist) return { error: '登录辅助未接线（LoginAssist 未挂载）' };
+  if (!assist) return { error: NOT_WIRED };
   const id = strField(d, 'taskId');
   if (!id) return { error: 'taskId is required' };
   const reason = strField(d, 'reason') || 'cancelled';
   const identity = readEndpointIdentity(d.endpointIdentity);
   if (identity === false) return { error: 'Invalid login Endpoint identity' };
+  const target = checkTaskTarget(d, ctx, id);
+  if (target) return target;
   const ok = identity ? assist.cancel(id, reason, identity) : assist.cancel(id, reason);
   if (!ok) return { error: `login task not found: ${id}` };
   return { data: { success: true } };
 }
 
-// ---------------------------------------------------------------- 社交读取
+/**
+ * `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 function listLoginFlows(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult {
+  const assist = ctx.loginAssist;
+  if (!assist) return { error: NOT_WIRED };
+  if (!assist.listFlows) return unsupported('login flows');
+  const scope = loginScope(d, ctx);
+  if ('error' in scope) return scope;
+  const flows = assist.listFlows().filter((flow) => inScope(scope, flow)).map((flow) => visibleFlow(assist, ctx, flow));
+  return { data: { flows, count: flows.length } };
+}
+
+/** `login.flow.get { flowId } | { adapter, endpointKey }` → `{ flow: … | null }`. */
+export function getLoginFlow(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult {
+  const assist = ctx.loginAssist;
+  if (!assist) return { error: NOT_WIRED };
+  if (!assist.getFlow || !assist.getFlowById) return unsupported('login flows');
+  const flowId = strField(d, 'flowId');
+  const scope = loginScope(d, ctx);
+  if ('error' in scope) return scope;
+  if (flowId) {
+    const flow = assist.getFlowById(flowId);
+    // A flow id names one Endpoint; a scoped caller cannot read another Endpoint's flow by id.
+    return { data: { flow: flow && inScope(scope, flow) ? visibleFlow(assist, ctx, flow) : null } };
+  }
+  if (!scope.adapter || !scope.endpointKey) return { error: 'flowId or adapter and endpointKey are required' };
+  const flow = assist.getFlow(scope.adapter, scope.endpointKey);
+  return { data: { flow: flow ? visibleFlow(assist, ctx, flow) : null } };
+}
+
+/** `login.relogin` / `login.refresh { adapter, endpointKey }` through the Endpoint's login port. */
+export async function controlLogin(
+  type: typeof LOGIN_RPC.RELOGIN | typeof LOGIN_RPC.REFRESH,
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const scope = loginScope(d, ctx);
+  if ('error' in scope) return scope;
+  const { adapter, endpointKey } = scope;
+  if (!adapter || !endpointKey) return { error: 'adapter and endpointKey are required' };
+  const relogin = type === LOGIN_RPC.RELOGIN;
+  const label = relogin ? 'relogin' : 'refresh challenge';
+  if (!ctx.withEndpointLogin) return unsupported(label);
+  const result = await ctx.withEndpointLogin(adapter, endpointKey, async (login: ConsoleEndpointLoginAccess) => {
+    const declared = relogin ? login.declaration?.relogin === true : login.declaration?.refreshQr === true;
+    const run = relogin ? login.control?.relogin : login.control?.refreshChallenge;
+    if (!declared || !run) return unsupported(label, adapter);
+    await run.call(login.control, {});
+    return { data: { accepted: true } } satisfies ExtendedRpcResult;
+  });
+  return result ?? { error: `Endpoint not found: ${adapter}/${endpointKey}` };
+}
+
+/**
+ * Audit detail of a login RPC reply: the result category only (never values, never messages).
+ * `undefined` for other RPCs.
+ */
+export function loginAuditDetail(type: unknown, data: unknown): Readonly<Record<string, string>> | undefined {
+  if (type !== LOGIN_RPC.SUBMIT && type !== LOGIN_RPC.CANCEL && type !== LOGIN_RPC.RELOGIN && type !== LOGIN_RPC.REFRESH) return undefined;
+  if (!data || typeof data !== 'object') return undefined;
+  const record = data as { outcome?: { result?: unknown; code?: unknown }; pending?: unknown; accepted?: unknown; success?: unknown; code?: unknown };
+  if (typeof record.code === 'string') return Object.freeze({ result: record.code });
+  if (record.outcome && typeof record.outcome.result === 'string') {
+    return Object.freeze({ result: record.outcome.result, ...(typeof record.outcome.code === 'string' ? { code: record.outcome.code } : {}) });
+  }
+  if (record.pending === true) return Object.freeze({ result: 'pending' });
+  if (record.accepted === true || record.success === true) return Object.freeze({ result: 'accepted' });
+  return undefined;
+}
+
+// ---------------------------------------------------------------- helpers
+
+function unsupported(what: string, adapter?: string): ExtendedRpcResult {
+  return {
+    error: `${CONSOLE_LOGIN_UNSUPPORTED}: ${adapter ? `${adapter} does not support ${what}` : `${what} not available on this host`}`,
+    data: { code: CONSOLE_LOGIN_UNSUPPORTED },
+  };
+}
+
+interface LoginScope { readonly adapter: string; readonly endpointKey: string }
+
+/**
+ * The Endpoint a login RPC is about: `adapter` / `endpointKey` read from `data` and the top level,
+ * exactly the fields the authorization map reads (ADR 0049). Sources that disagree, or a value that
+ * is not a string, are rejected. When the dispatcher admitted the caller only through an adapter /
+ * endpoint-scoped grant (`ctx.authorizedEndpoint`), the scope is that Endpoint and any other named
+ * target is rejected; global callers may omit it (`''` = no filter).
+ */
+function loginScope(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): LoginScope | { error: string } {
+  const sources = d.data && typeof d.data === 'object' && !Array.isArray(d.data)
+    ? [d.data as Record<string, unknown>, d]
+    : [d];
+  const read = (key: 'adapter' | 'endpointKey'): string | false => {
+    let found = '';
+    for (const source of sources) {
+      const value = source[key];
+      if (value === undefined || value === null || value === '') continue;
+      if (typeof value !== 'string') return false;
+      const text = value.trim();
+      if (!text) continue;
+      if (found && found !== text) return false;
+      found = text;
+    }
+    return found;
+  };
+  const adapter = read('adapter');
+  const endpointKey = read('endpointKey');
+  if (adapter === false || endpointKey === false) return { error: 'Conflicting login target (adapter / endpointKey)' };
+  const authorized = ctx.authorizedEndpoint;
+  if (!authorized) return { adapter, endpointKey };
+  if ((adapter && adapter !== authorized.adapter) || (endpointKey && endpointKey !== authorized.endpointKey)) {
+    return { error: 'Login target outside the authorized Endpoint' };
+  }
+  return { adapter: authorized.adapter, endpointKey: authorized.endpointKey };
+}
+
+/** The caller may handle this Endpoint's challenge (`endpoint.operate` there); no principal = trusted. */
+function canOperate(ctx: ConsoleRpcExtendedCtx, item: { readonly adapter: string; readonly endpointKey: string }): boolean {
+  return ctx.canOperateEndpoint ? ctx.canOperateEndpoint(item.adapter, item.endpointKey) : true;
+}
+
+/**
+ * A flow as this caller may see it: live for operators, otherwise the event-safe form (no QR image,
+ * sensitive blocks redacted, verification links dropped). A port without `eventSafeFlow` falls back
+ * to removing every challenge's media and blocks.
+ */
+function visibleFlow(assist: ConsoleLoginAssistPort, ctx: ConsoleRpcExtendedCtx, flow: ConsoleLoginFlow): ConsoleLoginFlow {
+  if (canOperate(ctx, flow)) return flow;
+  return assist.eventSafeFlow ? assist.eventSafeFlow(flow) : withoutChallengeMaterial(flow);
+}
+
+function withoutChallengeMaterial(flow: ConsoleLoginFlow): ConsoleLoginFlow {
+  if (!flow.steps.some((step) => step.challenge?.media || step.challenge?.blocks)) return flow;
+  return Object.freeze({
+    ...flow,
+    steps: Object.freeze(flow.steps.map((step) => {
+      if (!step.challenge || (!step.challenge.media && !step.challenge.blocks)) return step;
+      const { media, blocks: _blocks, ...challenge } = step.challenge;
+      return Object.freeze({
+        ...step,
+        challenge: Object.freeze({
+          ...challenge,
+          media: Object.freeze({
+            ...(media?.expiresAt !== undefined ? { expiresAt: media.expiresAt } : {}),
+            ...(media?.refreshable !== undefined ? { refreshable: media.refreshable } : {}),
+            ...(media?.qrImage ? { qrImageOmitted: true } : {}),
+            ...(media?.link || media?.captcha ? { linkOmitted: true } : {}),
+          }),
+        }),
+      });
+    })),
+  });
+}
+
+/**
+ * Legacy task payload without the QR image (`image`) and verification link (`url`, may carry a
+ * session id), marked `imageOmitted` / `urlOmitted` like the `endpoint.login.*` events.
+ */
+function eventSafeLoginPayload(payload: Record<string, unknown>): Record<string, unknown> {
+  // Allow-list: only the message survives; legacy adapters may put sid / ticket / device anywhere.
+  const safe: Record<string, unknown> = {};
+  if (typeof payload.message === 'string') safe.message = payload.message;
+  if (payload.image !== undefined) safe.imageOmitted = true;
+  if (payload.url !== undefined) safe.urlOmitted = true;
+  if (Object.keys(payload).some((key) => key !== 'message' && key !== 'image' && key !== 'url')) safe.fieldsOmitted = true;
+  return safe;
+}
+
+function inScope(scope: LoginScope, item: { readonly adapter: string; readonly endpointKey: string }): boolean {
+  return (!scope.adapter || item.adapter === scope.adapter) && (!scope.endpointKey || item.endpointKey === scope.endpointKey);
+}
+
+/** When the caller names an Endpoint, or was authorized for one, the task must belong to it. */
+function checkTaskTarget(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx, id: string): ExtendedRpcResult | undefined {
+  const scope = loginScope(d, ctx);
+  if ('error' in scope) return scope;
+  if (!scope.adapter && !scope.endpointKey) return undefined;
+  const task = ctx.loginAssist?.listPending().find((item) => item.id === id);
+  if (!task || !inScope(scope, task)) return { error: `login task not found: ${id}` };
+  return undefined;
+}
+
+function readSubmitValue(raw: unknown): string | Record<string, unknown> | false {
+  if (raw === undefined || raw === null) return '';
+  if (typeof raw === 'string') return raw;
+  if (typeof raw === 'number' || typeof raw === 'boolean') return String(raw);
+  if (typeof raw !== 'object' || Array.isArray(raw)) return false;
+  const record = raw as Record<string, unknown>;
+  if (record.action === undefined) return record;
+  if (typeof record.action !== 'string' || !record.action || record.action.length > 64) return false;
+  if (record.values !== undefined && (!record.values || typeof record.values !== 'object' || Array.isArray(record.values))) return false;
+  const values: Record<string, string> = {};
+  for (const [key, item] of Object.entries((record.values ?? {}) as Record<string, unknown>)) {
+    if (typeof item !== 'string' && typeof item !== 'number') return false;
+    values[key] = String(item);
+  }
+  return { action: record.action, values };
+}
 
 function readEndpointIdentity(value: unknown): { readonly canonicalId: string; readonly instanceId: string; readonly epoch: number; readonly incarnationId: string } | false | undefined {
   if (value === undefined) return undefined;