dsh-cindy-host 0.1.20

package/src/host-routes.js

@@ -0,0 +1,266 @@
+/**
+ * The settings card's Host API.
+ *
+ * One prefix route registered on `ctx.webServer`, so the card — served from the
+ * same origin as the GUI — reads status and drives login with plain `fetch`.
+ * This is the pattern DSH's own plugins use for browser-facing Host surfaces
+ * (see `dsh-client-connection`'s `/api` route), and it avoids inventing a
+ * second transport for four small JSON calls.
+ *
+ * Nothing here decides state: every handler asks the runtime and answers with
+ * what the runtime says. The card is a renderer.
+ */
+import { randomUUID } from 'node:crypto';
+import { loadSession } from './credential-store.js';
+import { rememberedDeviceId } from './host-settings.js';
+import { requestLoginCode, verifyLoginCode, selectLoginAccount } from './cindy-login-flow.js';
+import { adoptSession, forgetSession } from './auth-session.js';
+
+/** Route prefix; the card hardcodes the same value. */
+export const API_PREFIX = '/api/dsh-cindy-host';
+
+/** Largest accepted JSON body. Four short scalars never come close. */
+const MAX_BODY_BYTES = 64 * 1024;
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+/** Whether a request arrived over the loopback interface. */
+export function isLoopbackRequest(req) {
+  const address = req?.socket?.remoteAddress;
+  // A socket with no address (an injected test double) is treated as local.
+  return address === undefined || address === null || LOOPBACK.has(address);
+}
+
+function sendJson(res, status, body) {
+  const payload = Buffer.from(JSON.stringify(body), 'utf8');
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': payload.byteLength, 'cache-control': 'no-store' });
+  res.end(payload);
+}
+
+/** Read and parse a JSON request body, refusing anything oversized or non-JSON. */
+export async function readJsonBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) throw new Error('BODY_TOO_LARGE');
+    chunks.push(chunk);
+  }
+  if (size === 0) return {};
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    return parsed !== null && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    throw new Error('BODY_NOT_JSON');
+  }
+}
+
+/**
+ * Build the handlers for one running runtime.
+ *
+ * The runtime is read lazily through `getRuntime`, because the plugin replaces
+ * it whenever settings restart the transport.
+ * @param options - the runtime accessor and an optional diagnostics producer.
+ * @returns one handler per route, each owning its own response.
+ */
+export function createHostRoutes({ getRuntime, getDiagnostics, getSettings, rememberDeviceId, auth = {} }) {
+  const loadCredential = auth.loadSession ?? loadSession;
+  const saveCredential = auth.adoptSession ?? adoptSession;
+  const forgetCredential = auth.forgetSession ?? forgetSession;
+  const verifyCredential = auth.verifyLoginCode ?? verifyLoginCode;
+  const selectCredential = auth.selectLoginAccount ?? selectLoginAccount;
+  /**
+   * The stable Cindy device handle for this Host.
+   *
+   * The credential is preferred because that is the identity the relay has already
+   * seen, but it is not the only source: a credential can legitimately vanish while
+   * the phone still holds a link to this Host's device id, so the id is also kept in
+   * settings. Generating a fresh one in that situation re-pairs the Host as a
+   * different device and makes the phone's existing link dangle.
+   * @returns the device id to log in with.
+   */
+  async function hostDeviceId() {
+    const stored = await loadCredential().catch(() => null);
+    const fromCredential = typeof stored?.deviceId === 'string' ? stored.deviceId.trim() : '';
+    const remembered = typeof getSettings === 'function'
+      ? (() => { try { return rememberedDeviceId(getSettings()); } catch { return ''; } })()
+      : '';
+    const deviceId = fromCredential !== '' ? fromCredential : (remembered !== '' ? remembered : randomUUID());
+    if (deviceId !== remembered && typeof rememberDeviceId === 'function') {
+      // Remembering is best effort: a settings write that fails must not cost the
+      // login the user is in the middle of.
+      try {
+        await rememberDeviceId(deviceId);
+      } catch {
+        // Ignored on purpose.
+      }
+    }
+    return deviceId;
+  }
+
+  /** Why the Host has (or has not) any data to serve — cheap, and only for diagnosis. */
+  function diagnostics() {
+    if (typeof getDiagnostics !== 'function') return undefined;
+    try {
+      return getDiagnostics();
+    } catch {
+      // Diagnostics must never be the reason a status read fails.
+      return undefined;
+    }
+  }
+
+  async function handleStatus(req, res) {
+    const runtime = getRuntime();
+    if (!runtime) {
+      sendJson(res, 200, { ok: true, installed: true, status: null, diagnostics: diagnostics() });
+      return;
+    }
+    sendJson(res, 200, { ok: true, installed: true, status: runtime.getStatus(), diagnostics: diagnostics() });
+  }
+
+  async function handleReconnect(req, res) {
+    const runtime = getRuntime();
+    if (!runtime) {
+      sendJson(res, 503, { ok: false, message: 'Cindy Host 运行时尚未就绪' });
+      return;
+    }
+    // The card's button is an escape hatch, not the mechanism: the Host retries on its
+    // own with backoff (`host-reconnect.js`). This path exists so a person can skip the
+    // wait — it drops any queued retry and forgets the ladder.
+    if (typeof runtime.reconnectNow === 'function') await runtime.reconnectNow();
+    else await runtime.connect();
+    sendJson(res, 200, { ok: true, status: runtime.getStatus() });
+  }
+
+  async function handleRequestCode(req, res, body) {
+    const result = await requestLoginCode({ kind: body.kind, identifier: body.identifier });
+    sendJson(res, result.ok ? 200 : 400, result);
+  }
+
+  async function handleVerifyCode(req, res, body) {
+    const result = await verifyCredential({
+      kind: body.kind,
+      identifier: body.identifier,
+      code: body.code,
+      deviceId: await hostDeviceId(),
+    });
+    if (!result.ok) {
+      sendJson(res, 400, result);
+      return;
+    }
+    const runtime = getRuntime();
+    await runtime?.beginIdentityChange?.();
+    await saveCredential(result.session);
+    // A login while the switch is already on must finish the connect the user
+    // asked for; with the switch off it only stores the session.
+    if (runtime) {
+      runtime.status.setLogin({ authenticated: true, required: false, kind: result.session.kind ?? null, identifier: result.session.identifier ?? null });
+      await runtime.connect();
+    }
+    sendJson(res, 200, { ok: true, deviceId: result.session.deviceId, status: runtime ? runtime.getStatus() : null });
+  }
+
+  async function handleSelectAccount(req, res, body) {
+    const result = await selectCredential({ loginTicket: body.loginTicket, accountId: body.accountId, deviceId: await hostDeviceId() });
+    if (!result.ok) {
+      sendJson(res, 400, result);
+      return;
+    }
+    const runtime = getRuntime();
+    await runtime?.beginIdentityChange?.();
+    await saveCredential(result.session);
+    if (runtime) {
+      runtime.status.setLogin({ authenticated: true, required: false });
+      await runtime.connect();
+    }
+    sendJson(res, 200, { ok: true, deviceId: result.session.deviceId, status: runtime ? runtime.getStatus() : null });
+  }
+
+  async function handleLogout(req, res) {
+    const runtime = getRuntime();
+    await runtime?.beginIdentityChange?.();
+    await forgetCredential();
+    if (runtime) await runtime.disconnect();
+    sendJson(res, 200, { ok: true, status: runtime ? runtime.getStatus() : null });
+  }
+
+  /**
+   * Run one channel against the real services, from this process.
+   *
+   * This exists because "the phone shows nothing" is otherwise unverifiable
+   * without a handset: two bugs were found only after a round trip, and both
+   * looked identical from here. It is a diagnostic, not a feature — it carries
+   * the same loopback-only trust boundary as every other route on this prefix,
+   * and it performs whatever the channel performs.
+   */
+  async function handleSelfTest(req, res, body) {
+    const runtime = getRuntime();
+    if (!runtime || typeof runtime.invokeForTest !== 'function') {
+      sendJson(res, 503, { ok: false, message: 'Cindy Host 运行时尚未就绪' });
+      return;
+    }
+    const channel = typeof body.channel === 'string' ? body.channel : '';
+    if (channel === '') {
+      sendJson(res, 400, { ok: false, message: 'self-test needs a channel' });
+      return;
+    }
+    const args = Array.isArray(body.args) ? body.args : [];
+    sendJson(res, 200, await runtime.invokeForTest(channel, args));
+  }
+
+  /**
+   * The route table: one entry per accepted method+path.
+   * @returns handlers keyed by method and pathname.
+   */
+  const table = new Map([
+    ['GET /status', handleStatus],
+    ['POST /reconnect', handleReconnect],
+    ['POST /login/request-code', handleRequestCode],
+    ['POST /login/verify-code', handleVerifyCode],
+    ['POST /login/select-account', handleSelectAccount],
+    ['POST /logout', handleLogout],
+    ['POST /selftest', handleSelfTest],
+  ]);
+
+  /** Paths that take a JSON body. */
+  const BODY_PATHS = new Set(['/reconnect', '/login/request-code', '/login/verify-code', '/login/select-account', '/logout', '/selftest']);
+
+  /**
+   * The one handler registered on the web server.
+   * @param req - incoming request.
+   * @param res - response owned by this handler.
+   */
+  async function handle(req, res) {
+    if (!isLoopbackRequest(req)) {
+      sendJson(res, 403, { ok: false, message: 'Cindy Host API is loopback-only' });
+      return;
+    }
+
+    const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+    const suffix = pathname.startsWith(API_PREFIX) ? pathname.slice(API_PREFIX.length) : pathname;
+    const handler = table.get(`${req.method ?? 'GET'} ${suffix}`);
+    if (handler === undefined) {
+      sendJson(res, 404, { ok: false, message: `Unknown Cindy Host route: ${req.method ?? 'GET'} ${pathname}` });
+      return;
+    }
+
+    let body = {};
+    if (BODY_PATHS.has(suffix)) {
+      try {
+        body = await readJsonBody(req);
+      } catch (error) {
+        sendJson(res, error instanceof Error && error.message === 'BODY_TOO_LARGE' ? 413 : 400, { ok: false, message: '请求体无效' });
+        return;
+      }
+    }
+
+    try {
+      await handler(req, res, body);
+    } catch {
+      if (!res.headersSent) sendJson(res, 500, { ok: false, message: 'Cindy Host 处理请求失败' });
+      else res.end();
+    }
+  }
+
+  return { handle, API_PREFIX };
+}

package/src/host-settings.js

@@ -0,0 +1,41 @@
+export const SETTINGS_NAMESPACE = 'dsh-cindy-host';
+
+// Network access is opt-in. A newly mounted bundle only projects local DSH data.
+//
+// `sessionFlags` is the one section a *controller* writes: DSH has no archived,
+// deleted or pinned session state, so the phone's 删除/归档/置顶 are this Host's own
+// bookkeeping and they have to survive a restart (see `session-flags.js`).
+export const DEFAULT_HOST_SETTINGS = Object.freeze({ transportEnabled: false, remoteControlEnabled: false, controllers: {}, deviceId: '', sessionFlags: {} });
+
+/**
+ * The Host's own relay identity, when it has one.
+ *
+ * It is stored here rather than derived from the credential because the credential
+ * can legitimately disappear — an expired token, a fresh install, or (as happened
+ * once) a refresh failure that used to delete it — while the identity is what a
+ * phone linked to. Losing the credential must not silently re-pair the Host as a
+ * different device.
+ * @param value - the settings section.
+ * @returns the device id, or an empty string when none was ever recorded.
+ */
+export function rememberedDeviceId(value) {
+  return typeof value?.deviceId === 'string' ? value.deviceId.trim() : '';
+}
+
+export function validateHostSettings(value) {
+  if (!value || typeof value !== 'object' || typeof value.transportEnabled !== 'boolean' || typeof value.remoteControlEnabled !== 'boolean' || !value.controllers || typeof value.controllers !== 'object') throw new Error('Invalid DSH Cindy Host settings');
+  if (value.deviceId !== undefined && typeof value.deviceId !== 'string') throw new Error('Invalid DSH Cindy Host settings');
+  for (const [id, entry] of Object.entries(value.controllers)) {
+    if (!id || !entry || !['authorized', 'revoked'].includes(entry.state)) throw new Error('Invalid controller authorization');
+  }
+  // An absent section is valid — every settings file written before this field
+  // existed has none, and rejecting it would fail the load instead of the flag.
+  if (value.sessionFlags !== undefined) {
+    if (value.sessionFlags === null || typeof value.sessionFlags !== 'object') throw new Error('Invalid session flags');
+    for (const [sessionId, flags] of Object.entries(value.sessionFlags)) {
+      if (sessionId === '' || flags === null || typeof flags !== 'object') throw new Error('Invalid session flags');
+      if (flags.status !== undefined && !['active', 'archived', 'deleted'].includes(flags.status)) throw new Error('Invalid session status flag');
+      if (flags.pinnedAt !== undefined && typeof flags.pinnedAt !== 'string') throw new Error('Invalid session pin flag');
+    }
+  }
+}

package/src/host-status.js

@@ -0,0 +1,216 @@
+/**
+ * The Cindy Host's connection status — the single source of truth the settings
+ * card renders.
+ *
+ * The card never decides whether the Host is connected: it polls this snapshot
+ * and draws it. Every field here is produced by an observed event (an HTTP
+ * answer from Cindy, a relay frame, a socket close), never by a UI guess.
+ *
+ * State vocabulary is the six states the Settings card must show:
+ *   disconnected   the 连接手机 switch is off, or nothing has started
+ *   authenticating a Cindy session is being read, refreshed, or logged in
+ *   connecting     a connection was lost and is being retried automatically
+ *   waiting        the relay is online; no phone has reached this Host yet
+ *   connected      a phone opened a link or invoked this Host
+ *   failed         a concrete failure; `message` says which
+ *
+ * `connecting` is the state that makes a dropped socket survivable. Without it a Host
+ * that lost the relay had nowhere honest to put "retrying" and reported `failed`, which
+ * on a phone-controlled Host reads as "DSH is gone" until somebody presses reconnect.
+ * The Cindy client has exactly this middle state (`stopped | connecting | online`) and
+ * never shows a terminal failure for an ordinary network loss.
+ */
+
+/** Ordered state vocabulary; also the wire vocabulary of the status route. */
+export const CONNECTION_STATES = Object.freeze(['disconnected', 'authenticating', 'connecting', 'waiting', 'connected', 'failed']);
+
+/** Chinese labels for the card. Kept beside the states so both move together. */
+export const STATE_LABELS = Object.freeze({
+  disconnected: '未连接',
+  authenticating: '登录中',
+  connecting: '正在重连',
+  waiting: '等待手机连接',
+  connected: '已连接',
+  failed: '连接失败',
+});
+
+/** English labels, used when the page language is not Chinese. */
+export const STATE_LABELS_EN = Object.freeze({
+  disconnected: 'Not connected',
+  authenticating: 'Signing in',
+  connecting: 'Reconnecting',
+  waiting: 'Waiting for phone',
+  connected: 'Connected',
+  failed: 'Connection failed',
+});
+
+/** A device row the card may show; deviceId is the only required field. */
+function normalizeDevice(deviceId, patch) {
+  return {
+    deviceId,
+    name: typeof patch.name === 'string' && patch.name !== '' ? patch.name : deviceId.slice(0, 8),
+    platform: typeof patch.platform === 'string' ? patch.platform : null,
+    online: patch.online === true,
+    isController: patch.isController === true,
+    linkedAt: patch.linkedAt ?? null,
+    lastSeenAt: patch.lastSeenAt ?? null,
+  };
+}
+
+/** Whether a device row is a phone the user cares about. */
+export function isMobilePlatform(platform) {
+  return platform === 'ios' || platform === 'android';
+}
+
+/**
+ * Holds the Host's current status and notifies subscribers on change.
+ *
+ * Notifications are coalesced by value: `publish` runs only when the snapshot
+ * actually differs, so a relay that repeats a presence frame does not wake the
+ * card's poll loop for nothing.
+ */
+export class HostStatus {
+  #listeners = new Set();
+  #devices = new Map();
+  #ownDeviceId = null;
+  #status;
+
+  /** @param options - injectable clock for deterministic tests. */
+  constructor({ now = () => new Date() } = {}) {
+    this.now = now;
+    this.#status = {
+      state: 'disconnected',
+      stateLabel: STATE_LABELS.disconnected,
+      message: null,
+      login: { authenticated: false, required: false, kind: null, identifier: null },
+      host: null,
+      devices: [],
+      updatedAt: this.now().toISOString(),
+    };
+  }
+
+  /** @param listener - invoked after each replacement snapshot. @returns disposer. */
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  /** @returns a deep copy; callers may serialize it freely. */
+  snapshot() {
+    return {
+      ...this.#status,
+      login: { ...this.#status.login },
+      host: this.#status.host === null ? null : { ...this.#status.host },
+      devices: this.#status.devices.map((device) => ({ ...device })),
+    };
+  }
+
+  /** The relay-assigned device id of this Host, excluded from the device list. */
+  get ownDeviceId() {
+    return this.#ownDeviceId;
+  }
+
+  #publish(patch) {
+    const previous = JSON.stringify({ ...this.#status, updatedAt: '' });
+    const next = { ...this.#status, ...patch };
+    next.devices = [...this.#devices.values()]
+      .filter((device) => device.deviceId !== this.#ownDeviceId)
+      .sort(compareDevices);
+    next.stateLabel = STATE_LABELS[next.state] ?? next.state;
+    if (JSON.stringify({ ...next, updatedAt: '' }) === previous) return;
+    next.updatedAt = this.now().toISOString();
+    this.#status = next;
+    const snapshot = this.snapshot();
+    for (const listener of [...this.#listeners]) {
+      try {
+        listener(snapshot);
+      } catch {
+        // A broken observer must not corrupt the Host's own status.
+      }
+    }
+  }
+
+  /** Move to a state, replacing the failure message (or clearing it). */
+  setState(state, message = null) {
+    if (!CONNECTION_STATES.includes(state)) throw new Error(`Unknown Cindy host state: ${String(state)}`);
+    this.#publish({ state, message });
+  }
+
+  /** Record what the Host knows about the Cindy account behind the relay. */
+  setLogin({ authenticated, required = false, kind = null, identifier = null }) {
+    this.#publish({ login: { authenticated: authenticated === true, required: required === true, kind, identifier } });
+  }
+
+  /** Record this Host's relay identity from `hello-ack`, or clear it. */
+  setHost(host) {
+    if (host === null) {
+      this.#ownDeviceId = null;
+      this.#publish({ host: null });
+      return;
+    }
+    this.#ownDeviceId = typeof host.deviceId === 'string' ? host.deviceId : null;
+    this.#publish({ host: { deviceName: 'DSH Host', platform: 'desktop', appVersion: '0.1.0', online: true, protocolVersion: null, userId: null, ...host } });
+  }
+
+  /** Insert or merge one device row, preserving fields the patch omits. */
+  upsertDevice(deviceId, patch = {}) {
+    if (typeof deviceId !== 'string' || deviceId === '') return;
+    const existing = this.#devices.get(deviceId);
+    this.#devices.set(deviceId, normalizeDevice(deviceId, { ...existing, ...patch }));
+    this.#publish({});
+  }
+
+  /** Drop one device row (e.g. it left the account). */
+  removeDevice(deviceId) {
+    if (!this.#devices.delete(deviceId)) return;
+    this.#publish({});
+  }
+
+  /** Forget every device and accepted controller — the switch-off reset. */
+  clearDevices() {
+    if (this.#devices.size === 0) return;
+    this.#devices.clear();
+    this.#publish({});
+  }
+
+  /** Whether any device has actually reached this Host. */
+  get hasLinkedController() {
+    for (const device of this.#devices.values()) if (device.isController) return true;
+    return false;
+  }
+
+  /**
+   * Re-derive `connected`/`waiting` from the device ledger.
+   *
+   * Called after a controller arrives or leaves; never called while the Host is
+   * mid-handshake or failed, so a late frame cannot mask a real failure.
+   */
+  refreshConnectionState() {
+    if (this.#status.state === 'disconnected' || this.#status.state === 'failed') return;
+    if (this.hasLinkedController) this.setState('connected');
+    else if (this.#ownDeviceId !== null) this.setState('waiting');
+  }
+
+  /** Reset everything for a switch-off, in one publish. */
+  reset() {
+    this.#devices.clear();
+    this.#ownDeviceId = null;
+    this.#publish({
+      state: 'disconnected',
+      message: null,
+      host: null,
+      login: { authenticated: false, required: false, kind: null, identifier: null },
+    });
+  }
+}
+
+/** Phones first, then controllers, then by name and id for a stable order. */
+function compareDevices(left, right) {
+  return (
+    Number(isMobilePlatform(right.platform)) - Number(isMobilePlatform(left.platform)) ||
+    Number(right.isController) - Number(left.isController) ||
+    Number(right.online) - Number(left.online) ||
+    String(left.name).localeCompare(String(right.name)) ||
+    left.deviceId.localeCompare(right.deviceId)
+  );
+}

package/src/host-transfer-diagnostics.js

@@ -0,0 +1,50 @@
+import { createHmac, randomBytes } from 'node:crypto';
+
+/** Bounded observation only: never authority, work scheduling, credentials or file contents. */
+export function createTransferDiagnostics({ now = Date.now, limit = 128 } = {}) {
+  const capacity = Number.isSafeInteger(limit) && limit > 0 ? Math.min(128, limit) : 128;
+  const events = [];
+  const counts = Object.create(null);
+  const progress = new Map();
+  let salt = randomBytes(32);
+  const digest = (kind, value) => createHmac('sha256', salt).update(JSON.stringify([kind, value])).digest('hex');
+  const identify = ({ actor, owner, real, info } = {}) => ({
+    ...(typeof actor === 'string' && actor.length <= 256 ? { actorId: digest('actor', actor) } : {}),
+    ...(owner ? { ownerId: digest('owner', [owner.runtimeId, owner.epoch, owner.realm, owner.userId]) } : {}),
+    ...(typeof real === 'string' && real.length <= 32768 && info ?
+      { sourceId: digest('source', [real, info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs]) } : {}),
+  });
+  const names = new Set(['start', 'accepted', 'opening', 'presign', 'put', 'progress', 'cleanup', 'done', 'error', 'cancelled', 'offer-answer', 'dc-open', 'file-open', 'bytes-queued', 'eof-queued', 'closed']);
+  function record(input = {}) {
+    const transport = input.transport === 'peer' ? 'peer' : 'oss';
+    const event = names.has(input.event) ? input.event : 'other';
+    const key = transport + ':' + event;
+    counts[key] = Math.min(Number.MAX_SAFE_INTEGER, (counts[key] ?? 0) + 1);
+    const at = Number(now());
+    const identity = typeof input.transferId === 'string' ? input.transferId : input.connection;
+    if (event === 'progress' || event === 'bytes-queued') {
+      if (at - (progress.get(identity) ?? -Infinity) < 1000) return;
+      if (progress.size >= 64) progress.delete(progress.keys().next().value);
+      progress.set(identity, at);
+    }
+    const row = { transport, event, at };
+    const stages = new Set(['validate', 'validation', 'opening', 'verify', 'credential', 'presign', 'refresh', 'put', 'upload', 'close', 'cleanup', 'terminal']);
+    const codes = new Set(['INVALID_ARGUMENT', 'OVERSIZE', 'SOURCE_CHANGED', 'OWNER_UNVERIFIED', 'PRESIGN_FAILED', 'AUTH_FAILED', 'SOURCE_READ_FAILED', 'SIZE_MISMATCH', 'PUT_FAILED', 'INCOMPLETE_UPLOAD', 'NETWORK_ERROR', 'ABORTED', 'STAGE_TIMEOUT', 'IDLE_TIMEOUT', 'CANCELLED', 'UPLOAD_FAILED', 'FORBIDDEN', 'NOT_FOUND', 'FILE_PEER_CLOSED', 'FILE_PEER_TIMEOUT', 'FILE_PEER_CHANGED', 'FILE_PEER_REVOKED', 'FILE_PEER_BLOCK', 'FILE_PEER_DENIED']);
+    if (stages.has(input.stage)) row.stage = input.stage;
+    if (codes.has(input.code)) row.code = input.code;
+    for (const field of ['actorId', 'ownerId', 'sourceId']) {
+      if (typeof input[field] === 'string' && /^[a-f0-9]{64}$/.test(input[field])) row[field] = input[field];
+    }
+    // All caller-provided free text is excluded. IDs are opaque generated UUIDs, not actor IDs.
+    for (const field of ['transferId', 'connection']) {
+      if (typeof input[field] === 'string' && /^(exp_)?[a-f0-9-]{16,64}$/.test(input[field])) row[field] = input[field];
+    }
+    for (const field of ['size', 'uploaded', 'queuedBytes', 'status']) {
+      if (Number.isSafeInteger(input[field]) && input[field] >= 0) row[field] = input[field];
+    }
+    events.push(row);
+    if (events.length > capacity) events.splice(0, events.length - capacity);
+  }
+  return { record, identify, clear() { salt = randomBytes(32); events.length = 0; progress.clear(); for (const k of Object.keys(counts)) delete counts[k]; },
+    snapshot: () => ({ counters: { ...counts }, events: events.map(row => ({ ...row })) }) };
+}