ai-remote 0.1.0

package/src/protocols/rdp/tls.ts

@@ -0,0 +1,452 @@
+// A single-purpose TLS 1.2 client, written because neither of the TLS stacks
+// available to this gateway can be used for NLA:
+//
+//   * Cloudflare Workers' socket.startTls() validates the host certificate
+//     against public CAs with no opt-out, and RDP hosts use self-signed
+//     certificates.
+//   * CredSSP has to encrypt the host certificate's public key to prove the
+//     channel is not being relayed (MS-CSSP 3.1.5), and no runtime here exposes
+//     the certificate of a TLS session it established for us.
+//
+// Doing the handshake in JavaScript solves both at once: we see the certificate
+// and we decide what to do about it. Only what RDP needs is implemented -- TLS
+// 1.2, RSA key transport, AES-GCM records -- so this is a few hundred lines
+// rather than a library. The certificate is deliberately NOT validated, exactly
+// as mstsc does not validate it by default; CredSSP's binding of that
+// certificate to a password-derived key is what actually stops a MITM here.
+
+import { Reader, Writer, concatBytes } from './buffer';
+import { parseX509PublicKey } from './cert';
+import { rsaEncryptPkcs1 } from './crypto';
+
+const TLS_1_2 = 0x0303;
+
+const RECORD = {
+  CHANGE_CIPHER_SPEC: 20,
+  ALERT: 21,
+  HANDSHAKE: 22,
+  APPLICATION_DATA: 23,
+};
+
+const HANDSHAKE = {
+  CLIENT_HELLO: 1,
+  SERVER_HELLO: 2,
+  NEW_SESSION_TICKET: 4,
+  CERTIFICATE: 11,
+  SERVER_KEY_EXCHANGE: 12,
+  CERTIFICATE_REQUEST: 13,
+  SERVER_HELLO_DONE: 14,
+  CLIENT_KEY_EXCHANGE: 16,
+  FINISHED: 20,
+};
+
+/**
+ * Both suites use RSA key transport, so there is no ServerKeyExchange to verify
+ * and no ephemeral key agreement to implement. They differ only in PRF hash and
+ * key size.
+ */
+const CIPHER_SUITES = {
+  0x009c: { name: 'TLS_RSA_WITH_AES_128_GCM_SHA256', keyLength: 16, hash: 'SHA-256' },
+  0x009d: { name: 'TLS_RSA_WITH_AES_256_GCM_SHA384', keyLength: 32, hash: 'SHA-384' },
+};
+
+const ALERT_DESCRIPTIONS = {
+  0: 'close_notify',
+  10: 'unexpected_message',
+  20: 'bad_record_mac',
+  40: 'handshake_failure',
+  42: 'bad_certificate',
+  46: 'certificate_unknown',
+  47: 'illegal_parameter',
+  48: 'unknown_ca',
+  50: 'decode_error',
+  51: 'decrypt_error',
+  70: 'protocol_version',
+  71: 'insufficient_security',
+  80: 'internal_error',
+  90: 'user_canceled',
+  109: 'missing_extension',
+  112: 'unrecognized_name',
+};
+
+const ascii = (text: string) => new TextEncoder().encode(text);
+
+function u16(value) {
+  return new Uint8Array([(value >> 8) & 0xff, value & 0xff]);
+}
+
+function u24(value) {
+  return new Uint8Array([(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff]);
+}
+
+function u64(value) {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, BigInt(value));
+  return out;
+}
+
+// --- TLS 1.2 PRF (RFC 5246 5) ----------------------------------------------
+
+async function pHash(hash: Uint8Array, secret: Uint8Array, seed: Uint8Array, length: number) {
+  const key = await crypto.subtle.importKey('raw', secret, { name: 'HMAC', hash }, false, ['sign']);
+  const hmac = async (data: Uint8Array) => new Uint8Array(await crypto.subtle.sign('HMAC', key, data));
+
+  const blocks = [];
+  let produced = 0;
+  let a = await hmac(seed);
+
+  while (produced < length) {
+    const block = await hmac(concatBytes(a, seed));
+    blocks.push(block);
+    produced += block.length;
+    a = await hmac(a);
+  }
+
+  return concatBytes(...blocks).subarray(0, length);
+}
+
+const prf = (hash: Uint8Array, secret: Uint8Array, label: string, seed: Uint8Array, length: number) =>
+  pHash(hash, secret, concatBytes(ascii(label), seed), length);
+
+export class Tls12Client {
+  /**
+   * @param {(bytes: Uint8Array) => void} send        write raw bytes to the transport
+   * @param {(bytes: Uint8Array) => void} onData      decrypted application data
+   * @param {(error: Error) => void} onError          fatal protocol failure
+   */
+  constructor({ send, onData, onError }) {
+    this.sendRaw = send;
+    this.onData = onData;
+    this.onError = onError;
+
+    this.inbound = new Uint8Array(0);
+    this.transcript = [];
+    this.established = false;
+    this.serverPublicKey = null;
+    this.suite = null;
+    this.certificates = [];
+
+    this.readSequence = 0n;
+    this.writeSequence = 0n;
+    this.readEncrypted = false;
+    this.writeEncrypted = false;
+
+    // Records must be processed strictly in order, and every step is async.
+    this.queue = Promise.resolve();
+    this.handshakeDone = new Promise((resolve, reject) => {
+      this.resolveHandshake = resolve;
+      this.rejectHandshake = reject;
+    });
+  }
+
+  // --- handshake ------------------------------------------------------------
+
+  async start() {
+    this.clientRandom = new Uint8Array(32);
+    crypto.getRandomValues(this.clientRandom);
+
+    const extensions = concatBytes(
+      // signature_algorithms: rsa with sha256, sha384, sha1
+      u16(0x000d), u16(10), u16(8),
+      new Uint8Array([0x04, 0x01, 0x05, 0x01, 0x02, 0x01, 0x06, 0x01]),
+      // renegotiation_info: empty, which Schannel expects to see
+      u16(0xff01), u16(1), new Uint8Array([0x00])
+    );
+
+    const body = concatBytes(
+      u16(TLS_1_2),
+      this.clientRandom,
+      new Uint8Array([0]),                              // no session id
+      u16(4), u16(0x009c), u16(0x009d),                 // cipher suites
+      new Uint8Array([1, 0]),                           // compression: null
+      u16(extensions.length), extensions
+    );
+
+    await this.#sendHandshake(HANDSHAKE.CLIENT_HELLO, body);
+    return this.handshakeDone;
+  }
+
+  #record(type, payload: Uint8Array) {
+    return concatBytes(new Uint8Array([type]), u16(TLS_1_2), u16(payload.length), payload);
+  }
+
+  async #sendHandshake(type, body: Uint8Array) {
+    const message = concatBytes(new Uint8Array([type]), u24(body.length), body);
+    this.transcript.push(message);
+    await this.#sendRecord(RECORD.HANDSHAKE, message);
+  }
+
+  async #sendRecord(type, payload: Uint8Array) {
+    if (!this.writeEncrypted) {
+      this.sendRaw(this.#record(type, payload));
+      return;
+    }
+    this.sendRaw(this.#record(type, await this.#seal(type, payload)));
+  }
+
+  /** AES-GCM record protection (RFC 5288): explicit nonce, then ciphertext. */
+  async #seal(type, plaintext: Uint8Array) {
+    const sequence = this.writeSequence++;
+    const explicitNonce = u64(sequence);
+    const iv = concatBytes(this.keys.clientIv, explicitNonce);
+    const aad = concatBytes(u64(sequence), new Uint8Array([type]), u16(TLS_1_2), u16(plaintext.length));
+
+    const sealed = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 },
+      this.keys.clientKey,
+      plaintext
+    );
+
+    return concatBytes(explicitNonce, new Uint8Array(sealed));
+  }
+
+  async #open(type, fragment) {
+    const sequence = this.readSequence++;
+    const explicitNonce = fragment.subarray(0, 8);
+    const ciphertext = fragment.subarray(8);
+    const iv = concatBytes(this.keys.serverIv, explicitNonce);
+    const aad = concatBytes(
+      u64(sequence),
+      new Uint8Array([type]),
+      u16(TLS_1_2),
+      u16(ciphertext.length - 16)
+    );
+
+    const opened = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 },
+      this.keys.serverKey,
+      ciphertext
+    );
+
+    return new Uint8Array(opened);
+  }
+
+  async #deriveKeys(preMasterSecret) {
+    const { hash, keyLength } = this.suite;
+
+    this.masterSecret = await prf(
+      hash,
+      preMasterSecret,
+      'master secret',
+      concatBytes(this.clientRandom, this.serverRandom),
+      48
+    );
+
+    // AEAD suites need two keys and two 4-byte salts, and no MAC keys.
+    const keyBlock = await prf(
+      hash,
+      this.masterSecret,
+      'key expansion',
+      concatBytes(this.serverRandom, this.clientRandom),
+      keyLength * 2 + 8
+    );
+
+    const reader = new Reader(keyBlock);
+    const clientKeyBytes = reader.raw(keyLength);
+    const serverKeyBytes = reader.raw(keyLength);
+
+    this.keys = {
+      clientKey: await crypto.subtle.importKey('raw', clientKeyBytes, 'AES-GCM', false, ['encrypt']),
+      serverKey: await crypto.subtle.importKey('raw', serverKeyBytes, 'AES-GCM', false, ['decrypt']),
+      clientIv: reader.raw(4).slice(),
+      serverIv: reader.raw(4).slice(),
+    };
+  }
+
+  async #transcriptHash() {
+    const digest = await crypto.subtle.digest(this.suite.hash, concatBytes(...this.transcript));
+    return new Uint8Array(digest);
+  }
+
+  async #verifyData(label: string) {
+    return prf(this.suite.hash, this.masterSecret, label, await this.#transcriptHash(), 12);
+  }
+
+  // --- inbound --------------------------------------------------------------
+
+  /** Feed transport bytes. Calls are serialized, so order is preserved. */
+  receive(bytes: Uint8Array) {
+    this.queue = this.queue
+      .then(() => this.#consume(bytes))
+      .catch((error: unknown) => this.#fail(error));
+    return this.queue;
+  }
+
+  #fail(error: unknown) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    this.rejectHandshake(failure);
+    if (this.onError) this.onError(failure);
+  }
+
+  async #consume(bytes: Uint8Array) {
+    this.inbound = this.inbound.length === 0 ? bytes : concatBytes(this.inbound, bytes);
+
+    while (this.inbound.length >= 5) {
+      const type = this.inbound[0];
+      const length = (this.inbound[3] << 8) | this.inbound[4];
+      if (this.inbound.length < 5 + length) return;
+
+      const fragment = this.inbound.subarray(5, 5 + length);
+      this.inbound = this.inbound.subarray(5 + length).slice();
+
+      const payload = this.readEncrypted && type !== RECORD.CHANGE_CIPHER_SPEC
+        ? await this.#open(type, fragment)
+        : fragment;
+
+      await this.#handleRecord(type, payload);
+    }
+  }
+
+  async #handleRecord(type, payload: Uint8Array) {
+    if (type === RECORD.ALERT) {
+      const level = payload[0];
+      const description = payload[1];
+      const name = ALERT_DESCRIPTIONS[description] || `alert ${description}`;
+      if (name === 'close_notify') {
+        this.established = false;
+        return;
+      }
+      throw new Error(`TLS: the host sent a fatal alert: ${name}${level === 1 ? ' (warning)' : ''}`);
+    }
+
+    if (type === RECORD.CHANGE_CIPHER_SPEC) {
+      // Everything the host sends after this point is encrypted.
+      this.readEncrypted = true;
+      this.readSequence = 0n;
+      return;
+    }
+
+    if (type === RECORD.APPLICATION_DATA) {
+      if (this.onData && payload.length > 0) this.onData(payload);
+      return;
+    }
+
+    if (type !== RECORD.HANDSHAKE) return;
+
+    // One record can carry several handshake messages.
+    let offset = 0;
+    while (offset + 4 <= payload.length) {
+      const messageType = payload[offset];
+      const length = (payload[offset + 1] << 16) | (payload[offset + 2] << 8) | payload[offset + 3];
+      const message = payload.subarray(offset, offset + 4 + length);
+      const body = payload.subarray(offset + 4, offset + 4 + length);
+      offset += 4 + length;
+
+      // The Finished check covers every handshake message before it, so the
+      // transcript must include this one before it is verified.
+      if (messageType !== HANDSHAKE.FINISHED) this.transcript.push(message);
+      await this.#handleHandshake(messageType, body, message);
+    }
+  }
+
+  async #handleHandshake(type, body: Uint8Array, message: string) {
+    switch (type) {
+      case HANDSHAKE.SERVER_HELLO: {
+        const reader = new Reader(body);
+        const version = reader.u16be();
+        if (version !== TLS_1_2) {
+          throw new Error(`TLS: the host chose an unsupported version 0x${version.toString(16)}`);
+        }
+        this.serverRandom = reader.raw(32).slice();
+        reader.raw(reader.u8());                       // session id
+        const suiteId = reader.u16be();
+        this.suite = CIPHER_SUITES[suiteId];
+        if (!this.suite) {
+          throw new Error(`TLS: the host chose cipher suite 0x${suiteId.toString(16)}, which this client does not implement`);
+        }
+        reader.u8();                                   // compression method
+        return;
+      }
+
+      case HANDSHAKE.CERTIFICATE: {
+        const reader = new Reader(body);
+        const totalLength = (reader.u8() << 16) | reader.u16be();
+        const end = reader.offset + totalLength;
+        while (reader.offset < end) {
+          const certificateLength = (reader.u8() << 16) | reader.u16be();
+          this.certificates.push(reader.raw(certificateLength).slice());
+        }
+        if (this.certificates.length === 0) throw new Error('TLS: the host sent no certificate');
+
+        // The leaf comes first, and its key is what CredSSP will bind to.
+        this.serverPublicKey = parseX509PublicKey(this.certificates[0]);
+        return;
+      }
+
+      case HANDSHAKE.CERTIFICATE_REQUEST:
+        this.certificateRequested = true;
+        return;
+
+      case HANDSHAKE.SERVER_KEY_EXCHANGE:
+        throw new Error('TLS: the host chose an ephemeral key exchange, which this client does not implement');
+
+      case HANDSHAKE.SERVER_HELLO_DONE:
+        await this.#finishClientHandshake();
+        return;
+
+      case HANDSHAKE.NEW_SESSION_TICKET:
+        return;
+
+      case HANDSHAKE.FINISHED: {
+        const expected = await this.#verifyData('server finished');
+        const actual = body.subarray(0, 12);
+        const matches = expected.length === actual.length && expected.every((byte, i) => byte === actual[i]);
+        if (!matches) throw new Error('TLS: the host Finished message did not verify');
+
+        this.transcript.push(message);
+        this.established = true;
+        this.resolveHandshake({
+          cipherSuite: this.suite.name,
+          certificates: this.certificates,
+          publicKey: this.serverPublicKey,
+        });
+        return;
+      }
+
+      default:
+        return;
+    }
+  }
+
+  async #finishClientHandshake() {
+    if (this.certificateRequested) {
+      // An empty certificate list is the legal way to decline.
+      await this.#sendHandshake(HANDSHAKE.CERTIFICATE, u24(0));
+    }
+
+    // The premaster secret starts with the version the client first offered,
+    // which the host checks to detect a downgrade.
+    const preMasterSecret = new Uint8Array(48);
+    crypto.getRandomValues(preMasterSecret);
+    preMasterSecret[0] = 0x03;
+    preMasterSecret[1] = 0x03;
+
+    const encrypted = rsaEncryptPkcs1(
+      preMasterSecret,
+      this.serverPublicKey.modulus,
+      this.serverPublicKey.exponent
+    );
+    await this.#sendHandshake(HANDSHAKE.CLIENT_KEY_EXCHANGE, concatBytes(u16(encrypted.length), encrypted));
+
+    await this.#deriveKeys(preMasterSecret);
+
+    await this.#sendRecord(RECORD.CHANGE_CIPHER_SPEC, new Uint8Array([1]));
+    this.writeEncrypted = true;
+    this.writeSequence = 0n;
+
+    await this.#sendHandshake(HANDSHAKE.FINISHED, await this.#verifyData('client finished'));
+  }
+
+  // --- outbound -------------------------------------------------------------
+
+  /** Send application data once the handshake has completed. */
+  write(plaintext: Uint8Array) {
+    this.queue = this.queue
+      .then(async () => {
+        if (!this.established) throw new Error('TLS: write before the handshake finished');
+        await this.#sendRecord(RECORD.APPLICATION_DATA, plaintext);
+      })
+      .catch((error: unknown) => this.#fail(error));
+    return this.queue;
+  }
+}

package/src/protocols/rdp/vchannel.ts

@@ -0,0 +1,89 @@
+// Static virtual channel framing (MS-RDPBCGR 2.2.6.1).
+//
+// A virtual channel PDU is a CHANNEL_PDU_HEADER followed by data, split across
+// as many MCS send-data PDUs as the chunk size requires. The header repeats the
+// total length in every chunk, so the receiver knows how much to expect before
+// the last one arrives.
+
+import { Reader, Writer, concatBytes } from './buffer';
+
+/** Channel option bits used when the channel is declared in Client Network Data. */
+export const CHANNEL_OPTION = {
+  INITIALIZED: 0x80000000,
+  ENCRYPT_RDP: 0x40000000,
+  COMPRESS_RDP: 0x00800000,
+  SHOW_PROTOCOL: 0x00200000,
+};
+
+const CHANNEL_FLAG_FIRST = 0x00000001;
+const CHANNEL_FLAG_LAST = 0x00000002;
+export const CHANNEL_FLAG_SHOW_PROTOCOL = 0x00000010;
+
+/** What RDP itself uses; a host may accept more, but never needs to. */
+export const CHANNEL_CHUNK_LENGTH = 1600;
+
+/**
+ * Split one logical channel message into wire chunks, each already carrying its
+ * CHANNEL_PDU_HEADER. An empty message still produces one chunk, because the
+ * header is what tells the host anything happened at all.
+ */
+export function chunkChannelData(data: Uint8Array, chunkSize = CHANNEL_CHUNK_LENGTH, extraFlags = 0) {
+  const chunks = [];
+
+  for (let offset = 0; offset < data.length || offset === 0; offset += chunkSize) {
+    const slice = data.subarray(offset, offset + chunkSize);
+    let flags = extraFlags;
+    if (offset === 0) flags |= CHANNEL_FLAG_FIRST;
+    if (offset + chunkSize >= data.length) flags |= CHANNEL_FLAG_LAST;
+
+    const writer = new Writer(slice.length + 8);
+    writer.u32le(data.length).u32le(flags).raw(slice);
+    chunks.push(writer.take());
+
+    if (data.length === 0) break;
+  }
+
+  return chunks;
+}
+
+/**
+ * Reassemble inbound chunks into whole messages. A chunk that arrives without a
+ * preceding FIRST is treated as its own message rather than dropped: some hosts
+ * send small PDUs with both flags set and others with neither.
+ */
+export class ChannelReassembler {
+  private parts: Uint8Array[];
+  private expectedLength: number;
+
+  constructor() {
+    this.parts = [];
+    this.expectedLength = 0;
+  }
+
+  /** Returns the completed message, or null while more chunks are pending. */
+  push(bytes: Uint8Array) {
+    if (bytes.length < 8) return null;
+
+    const reader = new Reader(bytes);
+    const totalLength = reader.u32le();
+    const flags = reader.u32le();
+    const data = reader.rest();
+
+    if (flags & CHANNEL_FLAG_FIRST) {
+      this.parts = [];
+      this.expectedLength = totalLength;
+    }
+
+    this.parts.push(data.slice());
+
+    const complete = (flags & CHANNEL_FLAG_LAST) !== 0;
+    if (!complete) return null;
+
+    const message = concatBytes(...this.parts);
+    this.parts = [];
+    // The declared length is authoritative: a final chunk may be padded.
+    return this.expectedLength && this.expectedLength < message.length
+      ? message.subarray(0, this.expectedLength)
+      : message;
+  }
+}

package/src/protocols/rdp/x224.ts

@@ -0,0 +1,139 @@
+// TPKT (RFC 1006) and X.224 framing, plus the RDP security negotiation that
+// rides on the very first exchange (MS-RDPBCGR 2.2.1.1 / 2.2.1.2).
+
+import { Reader, Writer } from './buffer';
+
+export const TPKT_VERSION = 0x03;
+export const TPKT_HEADER_LENGTH = 4;
+
+const X224_CONNECTION_REQUEST = 0xe0;
+const X224_CONNECTION_CONFIRM = 0xd0;
+const X224_DATA = 0xf0;
+
+const RDP_NEG_REQ = 0x01;
+const RDP_NEG_RSP = 0x02;
+const RDP_NEG_FAILURE = 0x03;
+
+export const NEG_FAILURE = {
+  SSL_REQUIRED: 0x00000001,
+  SSL_NOT_ALLOWED: 0x00000002,
+  SSL_CERT_NOT_ON_SERVER: 0x00000003,
+  INCONSISTENT_FLAGS: 0x00000004,
+  HYBRID_REQUIRED: 0x00000005,
+  SSL_WITH_USER_AUTH_REQUIRED: 0x00000006,
+};
+
+export const NEG_PROTOCOL = {
+  RDP: 0x00000000,
+  SSL: 0x00000001,
+  HYBRID: 0x00000002,
+  RDSTLS: 0x00000004,
+  HYBRID_EX: 0x00000008,
+};
+
+const NEG_FAILURE_MESSAGES = {
+  0x00000001: 'The host requires TLS. Choose the TLS security option for this target.',
+  0x00000002: 'The host does not allow TLS. Choose the "RDP (standard)" security option.',
+  0x00000003: 'The host has no certificate installed, so it cannot negotiate TLS.',
+  0x00000004: 'The host rejected the requested protocol flags as inconsistent.',
+  0x00000005: 'The host requires Network Level Authentication (NLA/CredSSP). Turn NLA off on the host, or set its security layer to "RDP".',
+  0x00000006: 'The host requires TLS with early user authentication, which this gateway does not support.',
+};
+
+/** X.224 Connection Request, carrying the protocols this client will accept. */
+export function connectionRequest(requestedProtocols: number) {
+  const writer = new Writer(32);
+  writer.u8(TPKT_VERSION).u8(0).u16be(19);
+  writer.u8(14).u8(X224_CONNECTION_REQUEST).u16be(0).u16be(0).u8(0);
+  writer.u8(RDP_NEG_REQ).u8(0).u16le(8).u32le(requestedProtocols);
+  return writer.take();
+}
+
+/**
+ * Read the X.224 Connection Confirm. Throws with the host's own explanation
+ * when it refuses the requested protocol.
+ */
+export function parseConnectionConfirm(frame: Uint8Array) {
+  const reader = new Reader(frame);
+  reader.skip(TPKT_HEADER_LENGTH);
+  reader.u8();
+  const code = reader.u8();
+  if (code !== X224_CONNECTION_CONFIRM) {
+    throw new Error(`RDP: expected an X.224 connection confirm, got TPDU code 0x${code.toString(16)}`);
+  }
+  reader.skip(5); // dst-ref, src-ref, class
+
+  // Servers that predate the negotiation extension simply stop here, which
+  // means "plain RDP security, as asked".
+  if (reader.remaining < 8) return { selectedProtocol: NEG_PROTOCOL.RDP, negotiated: false };
+
+  const type = reader.u8();
+  reader.u8();
+  reader.u16le();
+
+  if (type === RDP_NEG_FAILURE) {
+    const failureCode = reader.u32le();
+    const error = new Error(
+      NEG_FAILURE_MESSAGES[failureCode] ||
+      `The host refused the RDP connection (negotiation failure 0x${failureCode.toString(16)}).`
+    );
+    // A client negotiating automatically needs the code, not just the sentence.
+    error.negotiationFailure = failureCode;
+    throw error;
+  }
+  if (type !== RDP_NEG_RSP) {
+    return { selectedProtocol: NEG_PROTOCOL.RDP, negotiated: false };
+  }
+
+  return { selectedProtocol: reader.u32le(), negotiated: true };
+}
+
+/** Wrap a payload in TPKT + X.224 Data. */
+export function dataFrame(payload: Uint8Array) {
+  const writer = new Writer(payload.length + 7);
+  writer.u8(TPKT_VERSION).u8(0).u16be(payload.length + 7);
+  writer.u8(2).u8(X224_DATA).u8(0x80); // li, DT code, EOT
+  writer.raw(payload);
+  return writer.take();
+}
+
+/** Strip TPKT + X.224 Data headers from a complete frame. */
+export function dataPayload(frame: Uint8Array) {
+  if (frame.length < 7) throw new Error('RDP: X.224 data frame is too short');
+  return frame.subarray(7);
+}
+
+/**
+ * Split a byte stream into whole frames. RDP interleaves two framings on one
+ * connection: TPKT (first byte 0x03) and fast-path output (any other value),
+ * each with its own length encoding.
+ */
+export function splitFrames(buffer: Uint8Array) {
+  const frames = [];
+  let offset = 0;
+
+  while (buffer.length - offset >= 4) {
+    let frameLength;
+    let fastPath = false;
+
+    if (buffer[offset] === TPKT_VERSION) {
+      frameLength = (buffer[offset + 2] << 8) | buffer[offset + 3];
+      if (frameLength < TPKT_HEADER_LENGTH) {
+        throw new Error('RDP: malformed TPKT length');
+      }
+    } else {
+      fastPath = true;
+      // Fast-path length is 1 or 2 bytes; the high bit of the first marks which.
+      frameLength = buffer[offset + 1] & 0x80
+        ? ((buffer[offset + 1] & 0x7f) << 8) | buffer[offset + 2]
+        : buffer[offset + 1];
+      if (frameLength < 2) throw new Error('RDP: malformed fast-path length');
+    }
+
+    if (buffer.length - offset < frameLength) break;
+    frames.push({ fastPath, frame: buffer.subarray(offset, offset + frameLength) });
+    offset += frameLength;
+  }
+
+  return { frames, rest: buffer.subarray(offset) };
+}