@robota-sdk/agent-transport-webrtc 3.0.0-beta.100

package/src/pairing-channel-lifecycle.ts

@@ -0,0 +1,31 @@
+import type { IPairingChannel } from './pairing-gate-options.js';
+
+function send(channel: IPairingChannel, data: string): void {
+  try {
+    channel.send(data);
+  } catch {
+    // The peer is gone; pairing frames are best-effort once the carrier is closing.
+  }
+}
+
+function close(channel: IPairingChannel): void {
+  try {
+    channel.close();
+  } catch {
+    // The carrier is already closing or closed.
+  }
+}
+
+function reportDeliveryError(
+  callback: ((error: Error, event: string) => void) | undefined,
+  error: Error,
+  event: string,
+): void {
+  try {
+    callback?.(error, event);
+  } catch {
+    // A diagnostic callback cannot prevent carrier teardown or escape into the committed operation.
+  }
+}
+
+export const pairingChannel = Object.freeze({ send, close, reportDeliveryError });

package/src/pairing-controllers.ts

@@ -0,0 +1,81 @@
+import type { IIdentityContext } from '@robota-sdk/agent-remote-pairing';
+/**
+ * Constructing the admission controllers the gate drives.
+ *
+ * "Which controller runs, with what inputs" is a different subject from "what state is the gate in
+ * and what may reach the session" — the same boundary that already moved the frame vocabulary into
+ * `pairing-frames.ts` and the best-effort channel calls into `pairing-channel-lifecycle.ts`.
+ *
+ * Split out because `pairing-gate.ts` had reached the size limit, where the rule is to split rather
+ * than extend. These two functions were the largest thing in it that was not about gating, and they
+ * touch nothing of the gate's own state: they take inputs, wire a controller's `send` to the
+ * channel, and hand back the controller plus a settled/rejected outcome for the caller to act on.
+ */
+
+import { startHostReconnect, startPairingHandshake } from '@robota-sdk/agent-remote-pairing';
+
+import { pairingChannel } from './pairing-channel-lifecycle.js';
+
+import type { IHostReconnectConfig, IPairingChannel } from './pairing-gate-options.js';
+import type {
+  IPairingResult,
+  IReconnectResult,
+  TPairingRole,
+} from '@robota-sdk/agent-remote-pairing';
+
+/** What both controllers need to talk on the channel and bind to it. */
+export interface IControllerContext {
+  readonly cryptoContext: IIdentityContext;
+  readonly channel: IPairingChannel;
+  readonly localFingerprint: string;
+  readonly remoteFingerprint: string;
+  /** Handshake timeout (ms); fail closed on expiry. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Start the B3 first-pair handshake.
+ *
+ * `onAccepted`/`onRejected` rather than handing the promise back, so a caller cannot forget to
+ * attach a rejection path — an unhandled rejection here would leave a gate waiting forever on a
+ * handshake that already failed, which is a fail-OPEN shaped as a hang.
+ */
+export function startFirstPairController(
+  context: IControllerContext,
+  secret: string,
+  role: TPairingRole,
+  onAccepted: (result: IPairingResult) => void,
+  onRejected: () => void,
+  start: typeof startPairingHandshake = startPairingHandshake,
+): ReturnType<typeof startPairingHandshake> {
+  const controller = start(context.cryptoContext, {
+    secret,
+    role,
+    localFingerprint: context.localFingerprint,
+    remoteFingerprint: context.remoteFingerprint,
+    send: (frame) => pairingChannel.send(context.channel, JSON.stringify(frame)),
+    ...(context.timeoutMs !== undefined ? { timeoutMs: context.timeoutMs } : {}),
+  });
+  controller.result.then(onAccepted, onRejected);
+  return controller;
+}
+
+/** Start the E3 host-side reconnect exchange against a pinned device key. */
+export function startReconnectController(
+  context: IControllerContext,
+  config: IHostReconnectConfig,
+  onAccepted: (result: IReconnectResult) => void,
+  onRejected: () => void,
+): ReturnType<typeof startHostReconnect> {
+  const controller = startHostReconnect(context.cryptoContext, {
+    hostIdentityId: config.hostIdentityId,
+    localFingerprint: context.localFingerprint,
+    remoteFingerprint: context.remoteFingerprint,
+    hostPrivateKey: config.hostPrivateKey,
+    resolveDevicePublicKey: config.resolveDevicePublicKey,
+    send: (frame) => pairingChannel.send(context.channel, JSON.stringify(frame)),
+    ...(context.timeoutMs !== undefined ? { timeoutMs: context.timeoutMs } : {}),
+  });
+  controller.result.then(onAccepted, onRejected);
+  return controller;
+}

package/src/pairing-frames.ts

@@ -0,0 +1,34 @@
+/**
+ * Predicates over the pairing/reconnect frame vocabulary the gate admits pre-accept.
+ *
+ * Issue #2046: these are thin adapters over the OWNER codec in `@robota-sdk/agent-remote-pairing`,
+ * which decodes every required field (presence, base64url, length ceiling) rather than only the `t`
+ * discriminator this file used to check. A true answer means the narrowed value is well-formed; the
+ * browser `ResponderGate` imports the same codec, so one corpus governs both carriers.
+ */
+
+import {
+  decodeEnrollFrame,
+  decodePairingFrame,
+  decodeReconnectFrame,
+  type IEnrollFrame,
+  type TPairingFrame,
+  type TReconnectFrame,
+} from '@robota-sdk/agent-remote-pairing';
+
+export type { IEnrollFrame };
+
+/** True when a parsed value is a well-formed B3 pairing frame (`pair-nonce` | `pair-confirm`). */
+export function isPairingFrame(value: unknown): value is TPairingFrame {
+  return decodePairingFrame(value).ok;
+}
+
+/** True when a parsed value is a well-formed reconnect frame (`rc-hello` | `rc-host` | `rc-device`). */
+export function isReconnectFrame(value: unknown): value is TReconnectFrame {
+  return decodeReconnectFrame(value).ok;
+}
+
+/** True when a parsed value is a well-formed first-pair enrollment frame carrying a device SPKI. */
+export function isEnrollFrame(value: unknown): value is IEnrollFrame {
+  return decodeEnrollFrame(value).ok;
+}

package/src/pairing-gate-options.ts

@@ -0,0 +1,133 @@
+import type { IIdentityContext } from '@robota-sdk/agent-remote-pairing';
+/**
+ * The contract a `PairingGate` is constructed with (REMOTE-008 / -012 / -013, SEC-010, SEC-011).
+ *
+ * Separated from the gate itself because they are different responsibilities: this file says what a
+ * caller must supply, and `pairing-gate.ts` says what the machine does with it. Keeping them
+ * together made one file that had to be read in full to answer either question.
+ *
+ * Re-exported from `pairing-gate.ts`, so every existing import keeps working — the split is a
+ * reading change, not a migration.
+ */
+
+import type {
+  IPairingResult,
+  startPairingHandshake,
+  TPairingRole,
+} from '@robota-sdk/agent-remote-pairing';
+import type {
+  IProtocolSession,
+  ISessionMessageHandlerOptions,
+  SessionResumeBridge,
+  createSessionMessageHandler,
+} from '@robota-sdk/agent-transport';
+
+import type { IHandoffGrantProof } from './handoff-grant-gate.js';
+import type { ILocalPeerProof } from './local-peer-proof.js';
+
+/** The minimal data-channel surface the gate drives (the transport's data channel satisfies it). */
+export interface IPairingChannel {
+  send(data: string): void;
+  close(): void;
+  /**
+   * ARCH-030 / issue #1734: this channel's own count of what it has accepted and not yet written.
+   *
+   * Optional for the same reason `IDataChannelSink.bufferedAmount` is — the slice is structural and a
+   * test double may omit it — while a real `RTCDataChannel` always has it. It is here so the resume
+   * bridge's outbound boundary gets a reading: without one the replay path has no backpressure
+   * budget, which is a capability that exists and is never reached.
+   */
+  readonly bufferedAmount?: number;
+}
+
+/** E3 host reconnect/enrollment config. When present, the gate runs reactive (first-frame) mode detection. */
+export interface IHostReconnectConfig {
+  readonly hostIdentityId: string;
+  /** base64url SPKI advertised to a device at first-pair enrollment. */
+  readonly hostPublicSpki: string;
+  /** The host identity private key (signs reconnect challenges). */
+  readonly hostPrivateKey: CryptoKey;
+  /** Resolve a pinned device public key by id (undefined → unknown/revoked → fail closed). */
+  readonly resolveDevicePublicKey: (deviceId: string) => Promise<CryptoKey | undefined>;
+  /** Pin a device's public key on first-pair enrollment; throw to refuse before session attachment. */
+  readonly onEnroll: (deviceId: string, deviceSpki: string) => void;
+}
+
+/** What the receiving operator is told about a connection that would drive the session. */
+export interface IConnectionApprovalContext {
+  /** The device the handshake proved, when the carrier has a stable id for it. */
+  readonly deviceId?: string;
+  /** A trusted device coming back, rather than one pairing now. */
+  readonly viaReconnect: boolean;
+  /** Aborted when the connection goes away before an answer: withdraw the question. */
+  readonly signal: AbortSignal;
+}
+
+/**
+ * The receiving operator's say over one connection. `approve` resolves `true` only on the operator's
+ * explicit yes; `false` or a rejection refuses the connection.
+ */
+export interface IConnectionApproval {
+  approve(context: IConnectionApprovalContext): Promise<boolean>;
+}
+
+export interface IPairingGateOptions {
+  readonly cryptoContext: IIdentityContext;
+  readonly channel: IPairingChannel;
+  readonly session: IProtocolSession;
+  readonly secret: string;
+  readonly role: TPairingRole;
+  readonly localFingerprint: string;
+  readonly remoteFingerprint: string;
+  /** Handshake timeout (ms); fail closed on expiry. */
+  readonly timeoutMs?: number;
+  /** REMOTE-008: fired once admission accepts + the session is exposed. Carries the first-pair result (E4). */
+  readonly onAccept?: (result?: IPairingResult) => void;
+  /** REMOTE-008: fired once admission rejects/times out + the channel closes (host lifecycle → teardown). */
+  readonly onReject?: () => void;
+  /** REMOTE-012 E3: host reconnect/enrollment config. Absent → B4 first-pair-only behavior (unchanged). */
+  readonly reconnect?: IHostReconnectConfig;
+  /**
+   * REMOTE-013 E4: a session-scoped {@link SessionResumeBridge}. When set, the paired session flows through the
+   * bridge (seq-stamped + buffered) instead of a fresh `createSessionMessageHandler`, so the session survives a channel
+   * drop and can replay on reconnect. Accept ATTACHES the channel as the bridge's sink; cleanup DETACHES it
+   * (never disposes — the bridge is owned by the transport across reconnects).
+   */
+  readonly resumeBridge?: SessionResumeBridge;
+  /** Host-owned usage read models exposed only after this gate accepts. */
+  readonly personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  readonly usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  readonly storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  /** Trusted carrier-owned surface; WebRTC assigns `remote`. */
+  readonly surface?: ISessionMessageHandlerOptions['surface'];
+  /** #3282 §4 part b-2: WebRTC assigns `remote` — it proves no locality. */
+  readonly commandSurfaceLocality?: ISessionMessageHandlerOptions['commandSurfaceLocality'];
+  /**
+   * Post-accept session-frame delivery failure; owning transport performs drop cleanup.
+   *
+   * ARCH-030: was `TServerMessage['type'] | string`, which is just `string` — a union that reads as a
+   * narrowing and is not one. Stated as what it is.
+   */
+  readonly onDeliveryError?: (error: Error, event: string) => void;
+  /** SEC-010: require a rendezvous nonce before exposing the session. Absent → unchanged behavior. */
+  readonly localPeer?: ILocalPeerProof;
+  /**
+   * SEC-011 (issue #1865): require a verified cross-device hand-off grant before exposing the
+   * session. Absent → unchanged behavior.
+   *
+   * Independent of `localPeer` rather than exclusive with it, and demanded AFTER it when both are
+   * set. They answer different questions — the rendezvous binds the environment, the grant binds the
+   * transfer — and a hand-off between two sessions on ONE machine legitimately has both. Requiring
+   * both is strictly more restrictive than requiring either, which is the safe direction.
+   */
+  readonly handoffGrant?: IHandoffGrantProof;
+  /**
+   * Ask the receiving operator before exposing the session, after every proof above has run. Absent →
+   * unchanged behavior. A device first pairing is not pinned for reconnect until the operator allows
+   * it, so a refused device is not remembered.
+   */
+  readonly connectionApproval?: IConnectionApproval;
+  /** Injection seams (default to the real implementations). */
+  readonly startHandshake?: typeof startPairingHandshake;
+  readonly createHandler?: typeof createSessionMessageHandler;
+}

package/src/pairing-gate.ts

@@ -0,0 +1,397 @@
+/**
+ * Pairing gate for the WebRTC data channel (REMOTE-008 Stage B4-2b; extended for REMOTE-012 Stage E3 TOFU
+ * reconnect).
+ *
+ * The data channel is phase-separated: pre-accept it carries pairing/reconnect frames, post-accept only
+ * session messages. An eager subscription feeds {@link PairingGate.onInbound}; the session bridge is not
+ * built until acceptance, so no pre-accept peer frame can reach the live session.
+ *
+ * E3 selects first-pair (`pair-nonce`, then identity-key enrollment) or reconnect (`rc-hello`, pinned
+ * identities) from the client's first frame and exposes the session only after mutual acceptance.
+ *
+ * Fail-closed: a non-admission frame pre-accept never reaches the session early — while this side's verdict is
+ * pending it is HELD (bounded; a peer that says more is refused) and routed again once the gate moves on, since
+ * the peer may finish its half first and speak at once; it is discarded if admission fails. The handshake
+ * `result` is the ONLY accept signal;
+ * on reject/timeout the channel is closed and no session bridge is ever created; a post-close frame is ignored.
+ *
+ * When no E3 `reconnect` config is supplied the gate is **exactly** the B4 first-pair-only gate (eager host
+ * `pair-nonce`, no enrollment, no reconnect) — preserving existing behavior.
+ *
+ * SEC-010 adds an optional `local-proof` step between handshake acceptance and session exposure; see
+ * `local-peer-proof.ts` for why both of those edges are load-bearing.
+ */
+
+import {
+  deriveIdentityId,
+  importPublicKey,
+  startPairingHandshake,
+  type IPairingResult,
+} from '@robota-sdk/agent-remote-pairing';
+
+import { nextAdmissionStep } from './admission-steps.js';
+import type {
+  IConnectionApproval,
+  IConnectionApprovalContext,
+  IHostReconnectConfig,
+  IPairingChannel,
+  IPairingGateOptions,
+} from './pairing-gate-options.js';
+
+// Re-exported so every existing import of these names keeps working: the split moved where they are
+// DECLARED, and moving where they are imported from would be a migration this change is not.
+export type {
+  IConnectionApproval,
+  IConnectionApprovalContext,
+  IHostReconnectConfig,
+  IPairingChannel,
+  IPairingGateOptions,
+};
+import { judgeHandoffGrant } from './handoff-grant-gate.js';
+import { judgeLocalProof } from './local-peer-proof.js';
+import { pairingChannel } from './pairing-channel-lifecycle.js';
+import { startFirstPairController, startReconnectController } from './pairing-controllers.js';
+import { isEnrollFrame, isPairingFrame, isReconnectFrame } from './pairing-frames.js';
+import { attachSession } from './session-attachment.js';
+
+import type { IEnrollFrame } from './pairing-frames.js';
+
+/** How much a peer may say while the operator decides: a client's opening requests, not a stream. */
+const HELD_FRAMES_MAX = 32;
+const HELD_CHARS_MAX = 256 * 1024;
+
+type TGateState =
+  | 'awaiting-mode'
+  | 'pairing'
+  | 'enrolling'
+  | 'reconnecting'
+  | 'local-proof'
+  | 'handoff-grant'
+  | 'operator-approval'
+  | 'accepted'
+  | 'closed';
+
+export class PairingGate {
+  private state: TGateState;
+  /** Session message router — built ONLY on accept (nothing reaches the session before). */
+  private onSessionMessage?: (data: string) => void;
+  private handlerCleanup?: () => void;
+  private pairingController?: ReturnType<typeof startPairingHandshake>;
+  private reconnectController?: ReturnType<typeof startReconnectController>;
+  /** The first-pair result, held so it can be surfaced on accept (E4 uses its sessionKey). */
+  private pendingResult?: IPairingResult;
+  /** Held across the local-proof step so the reconnect ordering rule survives the detour. */
+  private pendingViaReconnect = false;
+  /** The device the handshake proved, for the operator's question. */
+  private pendingDeviceId?: string;
+  /** A first-pair device key, pinned only once every step has admitted the channel. */
+  private pendingEnrollment?: { readonly deviceId: string; readonly spki: string };
+  /**
+   * Session frames the peer sent while the operator was deciding. The peer's own handshake has
+   * already accepted, so it starts talking (a resume, a history request) at once; dropping those
+   * would leave an approved device waiting on answers to questions the host never saw. They reach
+   * the session only after a yes, and a peer that sends more than a bounded amount is refused.
+   */
+  private heldFrames: string[] = [];
+  private heldChars = 0;
+  /** Withdraws the question put to the operator when the connection goes away first. */
+  private approvalAbort?: AbortController;
+
+  constructor(private readonly options: IPairingGateOptions) {
+    if (options.reconnect) {
+      // E3 mode: stay reactive — the client's first frame selects first-pair vs reconnect.
+      this.state = 'awaiting-mode';
+    } else {
+      // Legacy B4 mode: eagerly start the first-pair handshake (host sends pair-nonce immediately).
+      this.state = 'pairing';
+      this.startFirstPair();
+    }
+  }
+
+  /**
+   * Route one inbound channel frame. Pre-accept: admission frames → the active controller, everything else
+   * HELD (bounded) until the gate moves on. Post-accept: session messages → the session bridge. Post-close:
+   * ignored.
+   */
+  onInbound(data: string): void {
+    if (this.state === 'closed') return;
+    if (this.state === 'accepted') {
+      this.onSessionMessage?.(data);
+      return;
+    }
+    if (this.state === 'operator-approval') {
+      this.hold(data);
+      return;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return; // undecodable pre-accept frame → drop
+    }
+
+    if (this.state === 'awaiting-mode') {
+      // First frame selects the mode (E3).
+      if (isReconnectFrame(parsed) && parsed.t === 'rc-hello') {
+        this.state = 'reconnecting';
+        this.startReconnect();
+        this.reconnectController?.onFrame(parsed);
+      } else if (isPairingFrame(parsed) && parsed.t === 'pair-nonce') {
+        this.state = 'pairing';
+        this.startFirstPair();
+        this.pairingController?.onFrame(parsed);
+      }
+      // anything else pre-mode → drop
+      return;
+    }
+
+    if (this.state === 'pairing') {
+      if (isPairingFrame(parsed)) this.pairingController?.onFrame(parsed);
+      else this.hold(data);
+      return;
+    }
+
+    if (this.state === 'reconnecting') {
+      if (isReconnectFrame(parsed)) this.reconnectController?.onFrame(parsed);
+      else this.hold(data);
+      return;
+    }
+
+    if (this.state === 'local-proof') {
+      const admission = judgeLocalProof(parsed, this.options.localPeer);
+      this.options.localPeer?.onAdmission?.(admission);
+      if (admission.admitted) this.accept(this.pendingResult, this.pendingViaReconnect);
+      else this.rejectAndClose();
+      return;
+    }
+
+    if (this.state === 'handoff-grant') {
+      // Verifying a signature is async, and this handler is not. The promise is consumed here rather
+      // than returned so a rejection cannot escape into the channel's message subscription — an
+      // unhandled rejection would leave the gate parked in this state with the channel open, which
+      // is a hang. `judgeHandoffGrant` already converts a throw into a refusal; this is the second
+      // layer, because a gate that can hang is a gate that fails open by waiting.
+      void this.judgeGrantFrame(parsed);
+      return;
+    }
+
+    if (this.state === 'enrolling') {
+      // Awaiting the peer's identity public key to pin, then expose the session.
+      if (isEnrollFrame(parsed)) this.completeEnrollment(parsed.spki);
+      else this.hold(data);
+      return;
+    }
+  }
+
+  /** Tear down: cleanup the session bridge (if built) and mark closed. Idempotent. */
+  cleanup(): void {
+    this.state = 'closed';
+    this.withdrawApproval();
+    this.handlerCleanup?.();
+    this.handlerCleanup = undefined;
+    this.onSessionMessage = undefined;
+  }
+
+  /**
+   * The channel closed. Before acceptance that is a refusal: nobody is left to admit, so a question
+   * still open with the operator is withdrawn and a later answer admits nothing. After acceptance the
+   * owning transport handles the drop.
+   */
+  onChannelClosed(): void {
+    if (this.state === 'accepted' || this.state === 'closed') return;
+    this.rejectAndClose();
+  }
+
+  private withdrawApproval(): void {
+    this.heldFrames = [];
+    this.heldChars = 0;
+    this.approvalAbort?.abort();
+    this.approvalAbort = undefined;
+  }
+
+  private startFirstPair(): void {
+    // `IPairingGateOptions` already carries every field `IControllerContext` asks for, so it is
+    // passed straight through — projecting it field by field would be a copy to keep in step.
+    this.pairingController = startFirstPairController(
+      this.options,
+      this.options.secret,
+      this.options.role,
+      (result) => this.onFirstPairAccepted(result),
+      () => this.rejectAndClose(),
+      this.options.startHandshake ?? startPairingHandshake,
+    );
+  }
+
+  private startReconnect(): void {
+    const cfg = this.options.reconnect;
+    if (!cfg) {
+      this.rejectAndClose();
+      return;
+    }
+    this.reconnectController = startReconnectController(
+      this.options,
+      cfg,
+      // reconnect → hold live forwarding until the client's resume replays
+      (result) => {
+        this.pendingDeviceId = result.deviceId;
+        this.accept(undefined, true);
+      },
+      () => this.rejectAndClose(),
+    );
+  }
+
+  /** B3 handshake accepted. Without E3: expose immediately. With E3: run first-pair enrollment first. */
+  private onFirstPairAccepted(result: IPairingResult): void {
+    if (this.state !== 'pairing') return;
+    this.pendingResult = result;
+    const cfg = this.options.reconnect;
+    if (!cfg) {
+      this.accept(result);
+      return;
+    }
+    // E3 enrollment: advertise the host public key; the peer's `enroll-key` completes it (then expose).
+    this.state = 'enrolling';
+    pairingChannel.send(
+      this.options.channel,
+      JSON.stringify({ t: 'enroll-key', spki: cfg.hostPublicSpki } satisfies IEnrollFrame),
+    );
+    this.replayHeld();
+  }
+
+  private completeEnrollment(deviceSpki: string): void {
+    if (this.state !== 'enrolling') return;
+    const cfg = this.options.reconnect;
+    if (!cfg) {
+      this.rejectAndClose();
+      return;
+    }
+    void (async (): Promise<void> => {
+      try {
+        // Validate the SPKI parses as a public key before pinning (fail closed on garbage).
+        await importPublicKey(deviceSpki);
+        const deviceId = await deriveIdentityId(deviceSpki);
+        if (this.state !== 'enrolling') return;
+        this.pendingDeviceId = deviceId;
+        this.pendingEnrollment = { deviceId, spki: deviceSpki };
+        this.accept(this.pendingResult);
+      } catch {
+        this.rejectAndClose();
+      }
+    })();
+  }
+
+  private accept(result?: IPairingResult, viaReconnect = false): void {
+    if (this.state === 'closed' || this.state === 'accepted') return;
+    // The steps this channel still owes. Demanded here rather than earlier because the handshake
+    // must already have bound the channel, and before anything below because that is where the
+    // session becomes reachable. The ordering argument lives in `admission-steps.ts`.
+    const owed = nextAdmissionStep(this.options, this.state);
+    if (owed !== null) {
+      this.pendingResult = result ?? this.pendingResult;
+      this.pendingViaReconnect = viaReconnect;
+      this.state = owed;
+      if (owed === 'operator-approval') void this.askOperator();
+      this.replayHeld();
+      return;
+    }
+    // Pin a first-pair device only now: a device a later step refused is not remembered.
+    const enrollment = this.pendingEnrollment;
+    this.pendingEnrollment = undefined;
+    if (enrollment !== undefined) {
+      try {
+        this.options.reconnect?.onEnroll(enrollment.deviceId, enrollment.spki);
+      } catch {
+        this.rejectAndClose();
+        return;
+      }
+    }
+    const attached = attachSession(this.options, viaReconnect, (error, event) =>
+      this.handleSessionDeliveryError(error, event),
+    );
+    this.onSessionMessage = attached.onSessionMessage;
+    this.handlerCleanup = attached.cleanup;
+    this.state = 'accepted';
+    this.options.onAccept?.(result);
+    const held = this.heldFrames;
+    this.heldFrames = [];
+    this.heldChars = 0;
+    for (const frame of held) {
+      if (this.state !== 'accepted') return;
+      this.onSessionMessage?.(frame);
+    }
+  }
+
+  /** The gate moved on: frames held under the previous state are routed again under the new one. */
+  private replayHeld(): void {
+    const held = this.heldFrames;
+    this.heldFrames = [];
+    this.heldChars = 0;
+    // Routed in order; once accepted, the rest go to the session through the same entry point.
+    for (const frame of held) {
+      if (this.state === 'closed') return;
+      this.onInbound(frame);
+    }
+  }
+
+  private hold(data: string): void {
+    this.heldChars += data.length;
+    this.heldFrames.push(data);
+    if (this.heldFrames.length > HELD_FRAMES_MAX || this.heldChars > HELD_CHARS_MAX) {
+      this.rejectAndClose();
+    }
+  }
+
+  /**
+   * The `operator-approval` state: ask, then admit only on an explicit yes. A failure to ask is a no,
+   * and an answer that arrives after the channel was torn down admits nothing.
+   */
+  private async askOperator(): Promise<void> {
+    const abort = new AbortController();
+    this.approvalAbort = abort;
+    const context: IConnectionApprovalContext = {
+      ...(this.pendingDeviceId !== undefined ? { deviceId: this.pendingDeviceId } : {}),
+      viaReconnect: this.pendingViaReconnect,
+      signal: abort.signal,
+    };
+    let allowed = false;
+    try {
+      allowed = (await this.options.connectionApproval?.approve(context)) === true;
+    } catch {
+      allowed = false;
+    }
+    if (this.state !== 'operator-approval' || abort.signal.aborted) return;
+    this.approvalAbort = undefined;
+    if (allowed) this.accept(this.pendingResult, this.pendingViaReconnect);
+    else this.rejectAndClose();
+  }
+
+  /** The async half of the `handoff-grant` state, kept off the synchronous message path. */
+  private async judgeGrantFrame(parsed: unknown): Promise<void> {
+    const admission = await judgeHandoffGrant(parsed, this.options.handoffGrant);
+    // A channel torn down while the signature was being checked must not be re-accepted by a verdict
+    // that arrives afterwards. Checked after the await, because that is the window it exists for.
+    if (this.state !== 'handoff-grant') return;
+    this.options.handoffGrant?.onAdmission?.(admission);
+    if (admission.admitted) this.accept(this.pendingResult, this.pendingViaReconnect);
+    else this.rejectAndClose();
+  }
+
+  private rejectAndClose(): void {
+    if (this.state === 'closed') return;
+    this.state = 'closed';
+    this.withdrawApproval();
+    pairingChannel.close(this.options.channel);
+    this.options.onReject?.();
+  }
+
+  private handleSessionDeliveryError(error: Error, event: string): void {
+    if (this.state === 'closed') return;
+    this.state = 'closed';
+    this.handlerCleanup?.();
+    this.handlerCleanup = undefined;
+    this.onSessionMessage = undefined;
+    pairingChannel.reportDeliveryError(this.options.onDeliveryError, error, event);
+    pairingChannel.close(this.options.channel);
+  }
+}