ai-remote 0.1.0

package/src/protocols/ssh/transport.ts

@@ -0,0 +1,732 @@
+// The SSH transport layer (RFC 4253): version exchange, the binary packet
+// protocol, key exchange, and the AES-GCM cipher that protects everything
+// after it.
+//
+// Like the RDP client, this runs entirely in the browser. The gateway's
+// /ssh-ws endpoint is a byte relay and never sees a decrypted packet or a
+// password; the keys derived here exist only in this tab.
+
+import { MSG, DISCONNECT_REASON } from './messages';
+import {
+  SshReader,
+  SshWriter,
+  concatBytes,
+  encodeUtf8,
+} from './wire';
+import {
+  createKexClient,
+  deriveKey,
+  exchangeHash,
+  hostKeyFingerprint,
+  hostKeyType,
+  negotiableAlgorithms,
+  verifyHostKeySignature,
+} from './kex';
+import {
+  GATEWAY_KEEPALIVE_SIGNAL,
+  GATEWAY_READY_SIGNAL,
+  KEEPALIVE_INTERVAL_MS,
+} from '../../shared/signals';
+
+export const CLIENT_VERSION = 'SSH-2.0-CloudflareGateway_1.0';
+
+/** Only AEAD ciphers are offered, so the MAC list is never actually used. */
+const CIPHERS = {
+  'aes256-gcm@openssh.com': { keyLength: 32 },
+  'aes128-gcm@openssh.com': { keyLength: 16 },
+};
+const CIPHER_NAMES = Object.keys(CIPHERS);
+const MAC_NAMES = ['hmac-sha2-256', 'hmac-sha2-512'];
+const COMPRESSION_NAMES = ['none'];
+
+const GCM_BLOCK = 16;
+const GCM_TAG_BYTES = 16;
+const GCM_IV_BYTES = 12;
+const PLAIN_BLOCK = 8;
+const MIN_PADDING = 4;
+const MAX_PACKET_BYTES = 262_144;
+const VERSION_LINE_LIMIT = 8_192;
+
+const subtle = globalThis.crypto?.subtle;
+
+/** Pick the first client preference the host also offered (RFC 4253 7.1). */
+export function negotiate(clientNames, serverNames) {
+  return clientNames.find((name: string) => serverNames.includes(name)) || null;
+}
+
+/** An AES-GCM direction: one key, and an invocation counter that never repeats. */
+class GcmCipher {
+  key: CryptoKey;
+  fixed: Uint8Array;
+  counter: Uint8Array;
+
+  constructor(key: CryptoKey, iv: Uint8Array) {
+    this.key = key;
+    this.fixed = iv.slice(0, 4);
+    this.counter = iv.slice(4, 12);
+  }
+
+  static async create(keyBytes: Uint8Array, iv: Uint8Array) {
+    const key = await subtle.importKey('raw', keyBytes as unknown as BufferSource, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+    return new GcmCipher(key, iv);
+  }
+
+  /** The 12-byte nonce for this packet, then step the 64-bit counter. */
+  nextIv() {
+    const iv = concatBytes(this.fixed, this.counter);
+    for (let index = this.counter.length - 1; index >= 0; index--) {
+      this.counter[index] = (this.counter[index] + 1) & 0xff;
+      if (this.counter[index] !== 0) break;
+    }
+    return iv;
+  }
+}
+
+export class SshTransport extends EventTarget {
+  url: string;
+  verifyHost: (info: any) => Promise<boolean> | boolean;
+  log: (...args: any[]) => void;
+  socket: WebSocket | null;
+  closed: boolean;
+  buffer: Uint8Array;
+  serverVersion: string;
+  greeting: string[];
+  sendSequence: number;
+  receiveSequence: number;
+  outgoing: any;
+  incoming: any;
+  sessionId: Uint8Array | null;
+  kex: any;
+  kexQueue: Uint8Array[];
+  keepaliveTimer: any;
+  bytesSent: number;
+  bytesReceived: number;
+  encryptChain?: Promise<void>;
+  newKeysBarrier?: Promise<void> | null;
+  releaseNewKeys?: (() => void) | null;
+  pendingServerKexInit?: Uint8Array | null;
+  established?: boolean;
+
+  /**
+   * @param {string} url gateway WebSocket URL
+   * @param {object} options
+   * @param {(info: object) => Promise<boolean>} options.verifyHost decides
+   *   whether an unknown or changed host key may be used.
+   */
+  constructor(url: string, { verifyHost, log }: { verifyHost?: (info: any) => Promise<boolean> | boolean; log?: (...args: any[]) => void } = {}) {
+    super();
+
+    this.url = url;
+    this.verifyHost = verifyHost || (() => true);
+    this.log = log || (() => {});
+
+    this.socket = null;
+    this.closed = false;
+    this.buffer = new Uint8Array(0);
+    this.serverVersion = '';
+    this.greeting = [];
+
+    this.sendSequence = 0;
+    this.receiveSequence = 0;
+    this.outgoing = null;
+    this.incoming = null;
+    this.sessionId = null;
+
+    this.kex = null;
+    this.kexQueue = [];
+    this.keepaliveTimer = null;
+    this.bytesSent = 0;
+    this.bytesReceived = 0;
+  }
+
+  // --- connection ----------------------------------------------------------
+
+  connect() {
+    this.socket = new WebSocket(this.url);
+    this.socket.binaryType = 'arraybuffer';
+
+    this.socket.addEventListener('open', () => {
+      // The relay holds the host's first bytes until the browser says it is
+      // listening, exactly as the RDP client does.
+      this.socket.send(GATEWAY_READY_SIGNAL);
+      this.#write(encodeUtf8(`${CLIENT_VERSION}\r\n`));
+      this.keepaliveTimer = setInterval(() => {
+        if (this.socket?.readyState !== WebSocket.OPEN) return;
+
+        // Keeps the browser-to-gateway WebSocket alive. The gateway absorbs
+        // this frame, so it never reaches the host.
+        this.socket.send(GATEWAY_KEEPALIVE_SIGNAL);
+
+        // Which leaves the TCP leg silent whenever nobody is typing, and an
+        // idle TCP connection through a tunnel is a TCP connection about to be
+        // dropped. This is the request OpenSSH itself uses to keep one warm:
+        // servers answer it with a failure, which is a perfectly good answer --
+        // the point is the bytes, not the reply.
+        if (this.sessionId) {
+          try {
+            this.#sendPacket(new SshWriter(64)
+              .u8(MSG.GLOBAL_REQUEST)
+              .string('keepalive@openssh.com')
+              .u8(1)
+              .take());
+          } catch {
+            // A keepalive is not worth breaking a working session over.
+          }
+        }
+      }, KEEPALIVE_INTERVAL_MS);
+    });
+
+    this.socket.addEventListener('message', (event) => {
+      if (typeof event.data === 'string') return; // gateway control frame
+      this.#receive(new Uint8Array(event.data));
+    });
+
+    this.socket.addEventListener('close', (event) => {
+      this.#finish({
+        clean: event.code === 1000,
+        code: event.code,
+        message: event.reason || (
+          event.code === 1006
+            ? 'The gateway rejected or could not reach this SSH target. Confirm that SSH is published for this host.'
+            : ''
+        ),
+      });
+    });
+
+    // A failed WebSocket upgrade emits `error` immediately followed by
+    // `close`. The error event has no HTTP status or response body, while a
+    // relay that connected successfully can put the useful TCP failure in the
+    // close reason. Waiting for `close` preserves that explanation instead of
+    // replacing it with an opaque generic error.
+    this.socket.addEventListener('error', () => {
+      this.log('The SSH gateway WebSocket reported a transport error; waiting for its close reason.');
+    });
+  }
+
+  disconnect(message = 'Client disconnected') {
+    if (this.closed) return;
+    try {
+      const payload = new SshWriter(64)
+        .u8(MSG.DISCONNECT).u32(11).string(message).string('')
+        .take();
+      this.#sendPacket(payload);
+    } catch {}
+    // The packet may still be encrypting, and closing the socket under it
+    // would drop the goodbye the host is waiting for.
+    const socket = this.socket;
+    void Promise.resolve(this.encryptChain).finally(() => {
+      try { socket?.close(1000, 'Client disconnected'); } catch {}
+    });
+    this.#finish({ clean: true, code: 1000, message: '' });
+  }
+
+  #finish(detail) {
+    if (this.closed) return;
+    this.closed = true;
+    clearInterval(this.keepaliveTimer);
+    this.keepaliveTimer = null;
+    this.dispatchEvent(new CustomEvent('close', { detail }));
+  }
+
+  fail(error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (this.closed) return;
+    this.dispatchEvent(new CustomEvent('error', { detail: { message } }));
+    this.#finish({ clean: false, code: 4000, message });
+    try { this.socket?.close(4000, message.slice(0, 100)); } catch {}
+  }
+
+  #write(bytes: Uint8Array) {
+    if (this.socket?.readyState !== WebSocket.OPEN) return;
+    this.bytesSent += bytes.length;
+    this.socket.send(bytes);
+  }
+
+  // --- framing -------------------------------------------------------------
+
+  #receive(chunk: Uint8Array) {
+    this.bytesReceived += chunk.length;
+    this.buffer = this.buffer.length ? concatBytes(this.buffer, chunk) : chunk;
+
+    // Decryption is asynchronous, so the reader is a single chain rather than
+    // a loop: two overlapping drains could deliver packets out of order, and
+    // an out-of-order packet is a broken session.
+    this.drainChain = (this.drainChain || Promise.resolve())
+      .then(() => this.#drain())
+      .catch((error: unknown) => this.fail(error));
+  }
+
+  async #drain() {
+    if (this.closed) return;
+    if (!this.serverVersion && !this.#readVersion()) return;
+
+    while (!this.closed) {
+      // The host's NEWKEYS is the last packet under the old cipher. Nothing
+      // after it can be read until the new one is installed.
+      if (this.newKeysBarrier) {
+        const barrier = this.newKeysBarrier;
+        this.newKeysBarrier = null;
+        await barrier;
+        continue;
+      }
+
+      if (!this.incoming) {
+        const payload = this.#readPlainPacket();
+        if (!payload) return;
+        this.#dispatchPacket(payload);
+        continue;
+      }
+
+      const frame = this.#takeEncryptedFrame();
+      if (!frame) return;
+      this.#dispatchPacket(await this.#decrypt(frame));
+    }
+  }
+
+  /**
+   * The host may print any number of lines before its version line, and RFC
+   * 4253 says to show them: this is where a "banned by fail2ban" notice or a
+   * legal banner arrives.
+   */
+  #readVersion() {
+    while (true) {
+      const newline = this.buffer.indexOf(0x0a);
+      if (newline === -1) {
+        if (this.buffer.length > VERSION_LINE_LIMIT) {
+          throw new Error('SSH: the host sent no version line.');
+        }
+        return false;
+      }
+
+      let end = newline;
+      if (end > 0 && this.buffer[end - 1] === 0x0d) end--;
+      const line = new TextDecoder().decode(this.buffer.subarray(0, end));
+      this.buffer = this.buffer.subarray(newline + 1);
+
+      if (!line.startsWith('SSH-')) {
+        if (line.trim()) this.greeting.push(line);
+        continue;
+      }
+      if (!line.startsWith('SSH-2.0-') && !line.startsWith('SSH-1.99-')) {
+        throw new Error(`SSH: this host speaks ${line.split('-').slice(0, 2).join('-')}, which is too old.`);
+      }
+
+      this.serverVersion = line;
+      this.log('version', { server: line, greeting: this.greeting });
+      this.dispatchEvent(new CustomEvent('greeting', { detail: { lines: this.greeting.slice() } }));
+      void this.#startKex();
+      return true;
+    }
+  }
+
+  /** A packet from before the keys exist. Returns null when more bytes are due. */
+  #readPlainPacket() {
+    if (this.buffer.length < 5) return null;
+    const view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+    const packetLength = view.getUint32(0, false);
+    if (packetLength < 8 || packetLength > MAX_PACKET_BYTES) {
+      throw new Error('SSH: the host sent a packet of an impossible size.');
+    }
+    if (this.buffer.length < 4 + packetLength) return null;
+
+    const paddingLength = this.buffer[4];
+    if (paddingLength + 1 > packetLength) throw new Error('SSH: a packet claimed more padding than it had.');
+    const payload = this.buffer.slice(5, 4 + packetLength - paddingLength);
+    this.buffer = this.buffer.subarray(4 + packetLength);
+    this.receiveSequence = (this.receiveSequence + 1) >>> 0;
+    return payload;
+  }
+
+  /**
+   * With AES-GCM the length is authenticated but not encrypted, so the frame
+   * can be measured before anything is decrypted (RFC 5647).
+   */
+  #takeEncryptedFrame() {
+    if (this.buffer.length < 4) return null;
+    const view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+    const packetLength = view.getUint32(0, false);
+    if (packetLength < GCM_BLOCK || packetLength % GCM_BLOCK !== 0 || packetLength > MAX_PACKET_BYTES) {
+      throw new Error('SSH: the host sent a packet of an impossible size.');
+    }
+
+    const total = 4 + packetLength + GCM_TAG_BYTES;
+    if (this.buffer.length < total) return null;
+
+    const frame = this.buffer.slice(0, total);
+    this.buffer = this.buffer.subarray(total);
+    return frame;
+  }
+
+  async #decrypt(frame: Uint8Array) {
+    let plain;
+    try {
+      plain = new Uint8Array(await subtle.decrypt(
+        {
+          name: 'AES-GCM',
+          iv: this.incoming.nextIv(),
+          additionalData: frame.subarray(0, 4),
+          tagLength: GCM_TAG_BYTES * 8,
+        },
+        this.incoming.key,
+        frame.subarray(4)
+      ));
+    } catch {
+      throw new Error('SSH: a packet failed its integrity check, so the session was dropped.');
+    }
+
+    const paddingLength = plain[0];
+    if (paddingLength + 1 > plain.length) throw new Error('SSH: a packet claimed more padding than it had.');
+    this.receiveSequence = (this.receiveSequence + 1) >>> 0;
+    return plain.slice(1, plain.length - paddingLength);
+  }
+
+  #dispatchPacket(payload: Uint8Array) {
+    if (payload.length === 0) return;
+    const type = payload[0];
+
+    switch (type) {
+      case MSG.DISCONNECT: {
+        const reader = new SshReader(payload, 1);
+        const code = reader.u32();
+        const description = reader.string();
+        const reason = description || DISCONNECT_REASON[code] || `reason ${code}`;
+        this.dispatchEvent(new CustomEvent('hostdisconnect', { detail: { code, reason } }));
+        this.#finish({ clean: code === 11, code: 1000, message: reason });
+        try { this.socket?.close(1000, 'Host disconnected'); } catch {}
+        return;
+      }
+      case MSG.IGNORE:
+      case MSG.UNIMPLEMENTED:
+      case MSG.EXT_INFO:
+        return;
+      case MSG.DEBUG: {
+        const reader = new SshReader(payload, 1);
+        const alwaysDisplay = reader.boolean();
+        const message = reader.string();
+        this.log('debug', { message, alwaysDisplay });
+        if (alwaysDisplay) {
+          this.dispatchEvent(new CustomEvent('banner', { detail: { text: `${message}\r\n` } }));
+        }
+        return;
+      }
+      case MSG.KEXINIT:
+        void this.#onKexInit(payload);
+        return;
+      case MSG.NEWKEYS:
+        this.#onNewKeys();
+        return;
+      case MSG.GLOBAL_REQUEST: {
+        const reader = new SshReader(payload, 1);
+        reader.string();
+        if (reader.boolean()) this.#sendPacket(new Uint8Array([MSG.REQUEST_FAILURE]));
+        return;
+      }
+      // The answer to the keepalive global request. Either one means the host
+      // is still there, which is the whole point of having asked.
+      case MSG.REQUEST_SUCCESS:
+      case MSG.REQUEST_FAILURE:
+        return;
+      default:
+        break;
+    }
+
+    // A key exchange packet can only be answered by the exchange that is
+    // running, and everything else belongs to the layers above.
+    if (this.kex && type >= 30 && type <= 49) {
+      this.#deliverKexPacket(payload);
+      return;
+    }
+    this.dispatchEvent(new CustomEvent('packet', { detail: { type, payload } }));
+  }
+
+  // --- sending -------------------------------------------------------------
+
+  /** Application packets wait while a key exchange is in flight (RFC 4253 7.1). */
+  send(payload: Uint8Array) {
+    if (this.closed) return false;
+    if (this.kex?.running) {
+      this.kexQueue.push(payload);
+      return true;
+    }
+    this.#sendPacket(payload);
+    return true;
+  }
+
+  #sendPacket(payload: Uint8Array) {
+    if (this.closed || this.socket?.readyState !== WebSocket.OPEN) return;
+    if (!this.outgoing) {
+      this.#write(framePlain(payload));
+      this.sendSequence = (this.sendSequence + 1) >>> 0;
+      return;
+    }
+    void this.#encrypt(payload);
+  }
+
+  async #encrypt(payload: Uint8Array) {
+    // Packets must reach the host in the order they were built, and encryption
+    // is asynchronous, so each one waits for the one before it.
+    const previous = this.encryptChain || Promise.resolve();
+    this.encryptChain = previous.then(async () => {
+      if (this.closed || !this.outgoing) return;
+
+      const paddingLength = gcmPaddingLength(payload.length);
+      const plain = new Uint8Array(1 + payload.length + paddingLength);
+      plain[0] = paddingLength;
+      plain.set(payload, 1);
+      crypto.getRandomValues(plain.subarray(1 + payload.length));
+
+      const header = new SshWriter(4).u32(plain.length).take();
+      const sealed = new Uint8Array(await subtle.encrypt(
+        { name: 'AES-GCM', iv: this.outgoing.nextIv(), additionalData: header, tagLength: GCM_TAG_BYTES * 8 },
+        this.outgoing.key,
+        plain
+      ));
+
+      this.#write(concatBytes(header, sealed));
+      this.sendSequence = (this.sendSequence + 1) >>> 0;
+    }).catch((error: unknown) => this.fail(error));
+
+    return this.encryptChain;
+  }
+
+  // --- key exchange --------------------------------------------------------
+
+  async #startKex() {
+    if (this.kex?.running) return;
+
+    // Claimed before the first await: the host's own KEXINIT is usually already
+    // on the wire, and two exchanges starting at once would send two of ours.
+    this.kex = { running: true, clientKexInit: null, pending: null, inbox: [] };
+
+    try {
+      const offer = await negotiableAlgorithms();
+      const clientKexInit = buildKexInit(offer);
+      this.kex.clientKexInit = clientKexInit;
+      this.#sendPacket(clientKexInit);
+
+      const serverKexInit = this.pendingServerKexInit || await this.#nextKexPacket(MSG.KEXINIT);
+      this.pendingServerKexInit = null;
+      await this.#runKex(offer, clientKexInit, serverKexInit);
+    } catch (error) {
+      this.fail(error);
+    }
+  }
+
+  /** The host may ask for new keys at any point in a session. */
+  async #onKexInit(payload: Uint8Array) {
+    if (this.kex?.running) {
+      this.#deliverKexPacket(payload);
+      return;
+    }
+
+    this.log('rekey', { reason: 'the host asked for new keys' });
+    this.pendingServerKexInit = payload;
+    await this.#startKex();
+  }
+
+  /**
+   * Key exchange packets can arrive before the step that wants them: the host
+   * sends its reply and NEWKEYS back to back, while this side is still
+   * deriving a secret or waiting for the user to accept a host key. They are
+   * queued rather than dropped.
+   */
+  #deliverKexPacket(payload: Uint8Array) {
+    if (!this.kex) return;
+    if (this.kex.pending) {
+      const pending = this.kex.pending;
+      this.kex.pending = null;
+      pending(payload);
+      return;
+    }
+    this.kex.inbox.push(payload);
+  }
+
+  #nextKexPacket(expectedType) {
+    return new Promise((resolve, reject) => {
+      const check = (payload: Uint8Array) => {
+        if (expectedType !== undefined && payload[0] !== expectedType) {
+          reject(new Error(`SSH: expected message ${expectedType} during key exchange but got ${payload[0]}.`));
+          return;
+        }
+        resolve(payload);
+      };
+
+      const queued = this.kex.inbox.shift();
+      if (queued) {
+        check(queued);
+        return;
+      }
+      this.kex.pending = (payload: Uint8Array) => {
+        this.kex.pending = null;
+        check(payload);
+      };
+    });
+  }
+
+  async #runKex(offer, clientKexInit: Uint8Array, serverKexInit: Uint8Array) {
+    const server = parseKexInit(serverKexInit);
+    const kexAlgorithm = negotiate(offer.kex, server.kex);
+    const hostKeyAlgorithm = negotiate(offer.hostKey, server.hostKey);
+    const cipherToServer = negotiate(CIPHER_NAMES, server.cipherClientToServer);
+    const cipherToClient = negotiate(CIPHER_NAMES, server.cipherServerToClient);
+
+    if (!kexAlgorithm) throw new Error(`SSH: no shared key exchange method. The host offers ${server.kex.join(', ')}.`);
+    if (!hostKeyAlgorithm) throw new Error(`SSH: no host key type this browser can verify. The host offers ${server.hostKey.join(', ')}.`);
+    if (!cipherToServer || !cipherToClient) {
+      throw new Error(`SSH: the host does not offer AES-GCM, which is the only cipher this client can use. It offers ${server.cipherServerToClient.join(', ')}.`);
+    }
+
+    this.log('negotiated', {
+      kex: kexAlgorithm,
+      hostKey: hostKeyAlgorithm,
+      cipher: cipherToClient,
+      rekey: Boolean(this.sessionId),
+    });
+
+    const client = await createKexClient(kexAlgorithm);
+    this.#sendPacket(new SshWriter(128).u8(MSG.KEX_ECDH_INIT).string(client.publicKey).take());
+
+    const reply = new SshReader(await this.#nextKexPacket(MSG.KEX_ECDH_REPLY), 1);
+    const hostKeyBlob = reply.stringBytes();
+    const serverPublicKey = reply.stringBytes();
+    const signatureBlob = reply.stringBytes();
+
+    const sharedSecret = await client.sharedSecret(serverPublicKey);
+    const hash = await exchangeHash({
+      hash: client.hash,
+      clientVersion: CLIENT_VERSION,
+      serverVersion: this.serverVersion,
+      clientKexInit,
+      serverKexInit,
+      hostKeyBlob,
+      clientPublicKey: client.publicKey,
+      serverPublicKey,
+      sharedSecret,
+    });
+
+    const signatureValid = await verifyHostKeySignature({
+      algorithm: hostKeyAlgorithm,
+      keyBlob: hostKeyBlob,
+      signatureBlob,
+      exchangeHash: hash,
+    });
+    if (!signatureValid) {
+      throw new Error('SSH: the host key signature is invalid, so this is not the machine it claims to be.');
+    }
+
+    const fingerprint = await hostKeyFingerprint(hostKeyBlob);
+    if (!this.sessionId) {
+      // Trust is decided once per connection, against the key that has just
+      // proved it owns this exchange.
+      const accepted = await this.verifyHost({
+        fingerprint,
+        keyType: hostKeyType(hostKeyBlob),
+        algorithm: hostKeyAlgorithm,
+      });
+      if (!accepted) throw new Error('SSH: the host key was not accepted, so the connection was stopped.');
+      this.sessionId = hash;
+    }
+
+    this.#sendPacket(new Uint8Array([MSG.NEWKEYS]));
+    await this.#nextKexPacket(MSG.NEWKEYS);
+
+    const parameters = {
+      hash: client.hash,
+      sharedSecret,
+      exchangeHash: hash,
+      sessionId: this.sessionId,
+    };
+    const [ivToServer, ivToClient, keyToServer, keyToClient] = await Promise.all([
+      deriveKey({ ...parameters, letter: 'A', length: GCM_IV_BYTES }),
+      deriveKey({ ...parameters, letter: 'B', length: GCM_IV_BYTES }),
+      deriveKey({ ...parameters, letter: 'C', length: CIPHERS[cipherToServer].keyLength }),
+      deriveKey({ ...parameters, letter: 'D', length: CIPHERS[cipherToClient].keyLength }),
+    ]);
+
+    this.outgoing = await GcmCipher.create(keyToServer, ivToServer);
+    this.incoming = await GcmCipher.create(keyToClient, ivToClient);
+    this.kex.running = false;
+
+    // Both ciphers exist now, so the reader may go on.
+    this.releaseNewKeys?.();
+    this.releaseNewKeys = null;
+
+    const queued = this.kexQueue;
+    this.kexQueue = [];
+    for (const payload of queued) this.#sendPacket(payload);
+
+    const firstTime = !this.established;
+    this.established = true;
+    this.dispatchEvent(new CustomEvent('keys', {
+      detail: { fingerprint, kexAlgorithm, hostKeyAlgorithm, cipher: cipherToClient, firstTime },
+    }));
+  }
+
+  #onNewKeys() {
+    if (!this.kex) return;
+
+    // Hold the reader here: the host's very next packet is already encrypted
+    // with keys this side has not derived yet.
+    this.newKeysBarrier = new Promise((resolve) => { this.releaseNewKeys = resolve; });
+    this.#deliverKexPacket(new Uint8Array([MSG.NEWKEYS]));
+  }
+}
+
+/** Padding for a GCM packet: only the encrypted part is block aligned. */
+export function gcmPaddingLength(payloadLength) {
+  const unpadded = 1 + payloadLength;
+  let padding = GCM_BLOCK - (unpadded % GCM_BLOCK);
+  while (padding < MIN_PADDING) padding += GCM_BLOCK;
+  return padding;
+}
+
+/** A packet before any keys exist: the whole thing is block aligned. */
+export function framePlain(payload: Uint8Array) {
+  const unpadded = 5 + payload.length;
+  let padding = PLAIN_BLOCK - (unpadded % PLAIN_BLOCK);
+  if (padding < MIN_PADDING) padding += PLAIN_BLOCK;
+
+  const writer = new SshWriter(unpadded + padding);
+  writer.u32(1 + payload.length + padding);
+  writer.u8(padding);
+  writer.raw(payload);
+  const frame = writer.take();
+  const filler = new Uint8Array(padding);
+  crypto.getRandomValues(filler);
+  return concatBytes(frame, filler);
+}
+
+export function buildKexInit(offer) {
+  const cookie = new Uint8Array(16);
+  crypto.getRandomValues(cookie);
+
+  const writer = new SshWriter(512);
+  writer.u8(MSG.KEXINIT).raw(cookie);
+  writer.nameList(offer.kex);
+  writer.nameList(offer.hostKey);
+  writer.nameList(CIPHER_NAMES);          // client to server
+  writer.nameList(CIPHER_NAMES);          // server to client
+  writer.nameList(MAC_NAMES);
+  writer.nameList(MAC_NAMES);
+  writer.nameList(COMPRESSION_NAMES);
+  writer.nameList(COMPRESSION_NAMES);
+  writer.nameList([]);                    // languages
+  writer.nameList([]);
+  writer.boolean(false);                  // no guessed key exchange packet
+  writer.u32(0);                          // reserved
+  return writer.take();
+}
+
+export function parseKexInit(payload: Uint8Array) {
+  const reader = new SshReader(payload, 17); // message number and cookie
+  return {
+    kex: reader.nameList(),
+    hostKey: reader.nameList(),
+    cipherClientToServer: reader.nameList(),
+    cipherServerToClient: reader.nameList(),
+    macClientToServer: reader.nameList(),
+    macServerToClient: reader.nameList(),
+    compressionClientToServer: reader.nameList(),
+    compressionServerToClient: reader.nameList(),
+  };
+}