@ultimat3/realtime 1.0.0

package/src/pg-auth.ts

@@ -0,0 +1,300 @@
+// Single responsibility: Postgres authentication computations — MD5 legacy hashing and the
+// SCRAM-SHA-256 SASL exchange (RFC 5802 + RFC 7677). Pure crypto over bytes in, bytes out: the
+// socket, the message envelope and the AuthenticationXxx dispatch belong to pg-wire.ts, not here.
+
+import { ReplicationFailedError, ReplicationProtocolError } from './errors';
+import type { Rng } from './thundering-herd';
+
+export const SCRAM_SHA_256 = 'SCRAM-SHA-256';
+
+// No channel binding: `n,,` is the gs2-header for "client does not support channel binding".
+// `c=biws` in the final message is that same 3-byte header, base64'd — fixed, so it is spelled
+// out where used rather than recomputed on every exchange.
+const GS2_HEADER = 'n,,';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** One SASL exchange. Created per connection; never reused across connections. */
+export interface ScramSession {
+  readonly mechanism: string;
+  /** `n,,n=,r=<nonce>` — the payload of SASLInitialResponse (the wire framing is not yours). */
+  clientFirst(): Uint8Array;
+  /** server-first-message in, client-final-message out. */
+  clientFinal(serverFirst: Uint8Array): Promise<Uint8Array>;
+  /** server-final-message. Resolves when the server proved it knows the password; throws otherwise. */
+  verify(serverFinal: Uint8Array): Promise<void>;
+}
+
+class ScramSha256Session implements ScramSession {
+  readonly mechanism = SCRAM_SHA_256;
+  readonly #password: string;
+  readonly #clientNonce: string;
+  readonly #clientFirstBare: string;
+  #serverSignature: Uint8Array | undefined;
+  #finalized = false;
+
+  constructor(args: { password: string; nonce: string }) {
+    this.#password = args.password;
+    this.#clientNonce = args.nonce;
+    // The username is deliberately empty: Postgres takes it from the startup packet and only
+    // wants a SASLprep'd empty `n=` here, per its SCRAM implementation.
+    this.#clientFirstBare = `n=,r=${args.nonce}`;
+  }
+
+  clientFirst(): Uint8Array {
+    return encoder.encode(`${GS2_HEADER}${this.#clientFirstBare}`);
+  }
+
+  async clientFinal(serverFirst: Uint8Array): Promise<Uint8Array> {
+    if (this.#finalized) {
+      throw new ReplicationProtocolError({
+        stage: 'auth',
+        detail: 'clientFinal() was already called on this SCRAM session; a session is single-use',
+        fix: 'call scramSession() again to start a fresh exchange for the next connection attempt',
+      });
+    }
+    this.#finalized = true;
+
+    const serverFirstText = decoder.decode(serverFirst);
+    const { nonce: serverNonce, salt, iterations } = parseServerFirst(serverFirstText);
+    // The server must echo our nonce back as a prefix of the combined one — the RFC 5802 check
+    // that stands between this exchange and a server that never actually saw our client-first.
+    if (!serverNonce.startsWith(this.#clientNonce)) {
+      throw new ReplicationProtocolError({
+        stage: 'auth',
+        detail: `server nonce "${serverNonce}" does not extend client nonce "${this.#clientNonce}"`,
+        fix: 'x doctor db — the server did not echo the client nonce; check for a proxy on the replication URL',
+      });
+    }
+
+    const saltedPassword = await pbkdf2(this.#password, salt, iterations);
+    const clientKey = await hmac(saltedPassword, 'Client Key');
+    const storedKey = await sha256(clientKey);
+
+    const clientFinalWithoutProof = `c=biws,r=${serverNonce}`;
+    const authMessage = `${this.#clientFirstBare},${serverFirstText},${clientFinalWithoutProof}`;
+
+    const clientSignature = await hmac(storedKey, authMessage);
+    const clientProof = xorBytes(clientKey, clientSignature);
+
+    const serverKey = await hmac(saltedPassword, 'Server Key');
+    this.#serverSignature = await hmac(serverKey, authMessage);
+
+    return encoder.encode(`${clientFinalWithoutProof},p=${bytesToBase64(clientProof)}`);
+  }
+
+  async verify(serverFinal: Uint8Array): Promise<void> {
+    if (!this.#serverSignature) {
+      throw new ReplicationProtocolError({
+        stage: 'auth',
+        detail: 'verify() was called before clientFinal() produced a server signature to check',
+        fix: 'call clientFinal() with the server-first-message before verify()',
+      });
+    }
+
+    const text = decoder.decode(serverFinal);
+    const attrs = parseAttributes(text);
+
+    const serverError = attrs.get('e');
+    if (serverError !== undefined) {
+      throw new ReplicationFailedError({
+        stage: 'auth',
+        detail:
+          `server rejected the SCRAM exchange: ${serverError} — the password in DATABASE_URL ` +
+          "is not this role's, so either that value or the role itself has to change",
+        fix: 'psql "$DATABASE_URL" -c "ALTER ROLE <user> WITH PASSWORD \'<new>\'"',
+      });
+    }
+
+    const proof = attrs.get('v');
+    if (proof === undefined) {
+      throw new ReplicationProtocolError({
+        stage: 'auth',
+        detail: `server-final-message has neither "v=" nor "e=": "${text}"`,
+      });
+    }
+    // Every byte, no early return: a mismatch found sooner than a mismatch found later must take
+    // the same time, or the comparison itself becomes an oracle for guessing the right proof.
+    if (!constantTimeEqual(decodeBase64('server signature', proof), this.#serverSignature)) {
+      throw new ReplicationFailedError({
+        stage: 'auth',
+        detail:
+          'server-final-message signature does not match — the server could not prove it knows ' +
+          'the password, so DATABASE_URL points at something other than postgres, or the role ' +
+          'password changed under this connection',
+        fix: 'psql "$DATABASE_URL" -c "SELECT version()"',
+      });
+    }
+  }
+}
+
+export function scramSession(args: { password: string; nonce: string }): ScramSession {
+  return new ScramSha256Session(args);
+}
+
+/**
+ * 18 random bytes, base64 — the client nonce. RFC 5802 §5.1 requires a fresh nonce per exchange
+ * and points at RFC 4086 for what "random" has to mean there, so the default source is the
+ * CSPRNG: a predictable nonce lets an attacker who has recorded one exchange replay a proof
+ * against a client whose next nonce it can guess. `Rng` is the deterministic *test* seam and
+ * nothing else — production passes no argument.
+ */
+export function scramNonce(rng?: Rng): string {
+  const bytes = new Uint8Array(18);
+  if (rng === undefined) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(rng() * 256) & 0xff;
+    }
+  }
+  // Base64's alphabet never includes `,`, so the nonce can never collide with the attribute
+  // separator it will be embedded next to on the wire — nothing further to escape.
+  return bytesToBase64(bytes);
+}
+
+/**
+ * `md5` + md5(md5(password + user) + salt) — the AuthenticationMD5Password answer. The inner
+ * digest feeds the outer one as its *hex text*, not its raw bytes: that double encoding is
+ * Postgres's wire format, not a choice made here. MD5 has no WebCrypto entry, so this is the
+ * one spot in the module that reaches for `Bun.CryptoHasher` — the hash algorithm is legacy and
+ * the server's own choice, not one this module would otherwise make.
+ */
+export function md5Password(args: { user: string; password: string; salt: Uint8Array }): string {
+  const inner = new Bun.CryptoHasher('md5').update(args.password + args.user).digest('hex');
+  const outer = new Bun.CryptoHasher('md5').update(inner).update(args.salt).digest('hex');
+  return `md5${outer}`;
+}
+
+/** Picks SCRAM-SHA-256 out of the mechanism list the server offered, or throws. */
+export function chooseMechanism(offered: readonly string[]): string {
+  if (offered.includes(SCRAM_SHA_256)) return SCRAM_SHA_256;
+  throw new ReplicationProtocolError({
+    stage: 'auth',
+    detail:
+      offered.length === 0
+        ? 'the server offered no SASL mechanisms'
+        : `the server only offered ${offered.join(', ')} — channel binding ("-PLUS") is not supported here`,
+    fix: 'set password_encryption = scram-sha-256 on the server and recreate the role password',
+  });
+}
+
+/**
+ * The iteration count is the server's to choose, and `pbkdf2()` runs it before this client has
+ * proved anything about the peer — so an unbounded `i=` is a peer spending our CPU at will, on
+ * the connect path, where nothing above imposes a deadline. RFC 7677 §4 sets the floor at 4096
+ * and a real postgres sends exactly that, so two orders of magnitude of headroom refuses the
+ * attack without ever refusing a server.
+ */
+const MAX_SCRAM_ITERATIONS = 1_000_000;
+
+interface ServerFirst {
+  readonly nonce: string;
+  readonly salt: Uint8Array;
+  readonly iterations: number;
+}
+
+function parseServerFirst(text: string): ServerFirst {
+  const attrs = parseAttributes(text);
+  const nonce = attrs.get('r');
+  const saltB64 = attrs.get('s');
+  const iterationsText = attrs.get('i');
+  if (nonce === undefined || saltB64 === undefined || iterationsText === undefined) {
+    throw new ReplicationProtocolError({
+      stage: 'auth',
+      detail: `server-first-message is missing r=, s= or i=: "${text}"`,
+    });
+  }
+  if (!/^[1-9]\d*$/.test(iterationsText)) {
+    throw new ReplicationProtocolError({
+      stage: 'auth',
+      detail: `server-first-message iteration count "${iterationsText}" is not a positive integer`,
+    });
+  }
+  const iterations = Number.parseInt(iterationsText, 10);
+  if (iterations > MAX_SCRAM_ITERATIONS) {
+    throw new ReplicationProtocolError({
+      stage: 'auth',
+      detail: `server-first-message asked for ${iterationsText} PBKDF2 iterations, above the ${MAX_SCRAM_ITERATIONS} ceiling`,
+      fix: 'x doctor db — point the replication URL at postgres itself; a real server asks for 4096',
+    });
+  }
+  const salt = decodeBase64('salt', saltB64);
+  return { nonce, salt, iterations };
+}
+
+/** `k=v` pairs split on `,`. Unrecognised keys are ignored — RFC 5802 reserves them for extensions. */
+function parseAttributes(message: string): Map<string, string> {
+  const attrs = new Map<string, string>();
+  for (const segment of message.split(',')) {
+    const at = segment.indexOf('=');
+    if (at < 0) continue;
+    attrs.set(segment.slice(0, at), segment.slice(at + 1));
+  }
+  return attrs;
+}
+
+async function pbkdf2(password: string, salt: Uint8Array, iterations: number): Promise<Uint8Array> {
+  const key = await crypto.subtle.importKey('raw', encoder.encode(password), 'PBKDF2', false, [
+    'deriveBits',
+  ]);
+  const bits = await crypto.subtle.deriveBits(
+    // Copied into a fresh buffer: WebCrypto's `BufferSource` excludes a SharedArrayBuffer-backed
+    // view, and these values arrive as subarrays of the read buffer.
+    { name: 'PBKDF2', hash: 'SHA-256', salt: new Uint8Array(salt), iterations },
+    key,
+    256,
+  );
+  return new Uint8Array(bits);
+}
+
+async function hmac(key: Uint8Array, data: string): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    new Uint8Array(key),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const mac = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(data));
+  return new Uint8Array(mac);
+}
+
+async function sha256(data: Uint8Array): Promise<Uint8Array> {
+  return new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(data)));
+}
+
+function xorBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length);
+  for (let index = 0; index < a.length; index += 1) out[index] = (a[index] ?? 0) ^ (b[index] ?? 0);
+  return out;
+}
+
+/** Every byte, no early return — a timing side-channel on the server proof is a MITM's foothold. */
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  const length = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let index = 0; index < length; index += 1) {
+    diff |= (a[index] ?? 0) ^ (b[index] ?? 0);
+  }
+  return diff === 0;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** A server that sends a non-base64 attribute is a wire-format bug, not an auth failure. */
+function decodeBase64(label: string, value: string): Uint8Array {
+  try {
+    return Uint8Array.from(atob(value), (char) => char.charCodeAt(0));
+  } catch {
+    throw new ReplicationProtocolError({
+      stage: 'auth',
+      detail: `${label} "${value}" is not valid base64`,
+    });
+  }
+}

package/src/pg-bytes.ts

@@ -0,0 +1,185 @@
+// Single responsibility: the byte primitives every Postgres frame is built from — big-endian
+// integers, NUL-terminated strings, length-prefixed blobs. Shared by the wire framing, the auth
+// handshake and the pgoutput decoder so none of them owns a second copy of "read an Int32".
+// A read past the end is `X_REPLICATION_PROTOCOL`, never a silent `NaN` or an empty string.
+
+import { ReplicationProtocolError } from './errors';
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+/** Cursor over a frame. Every read advances it; overrun throws rather than wrapping around. */
+export class ByteReader {
+  readonly #bytes: Uint8Array;
+  readonly #view: DataView;
+  readonly #stage: string;
+  #at: number;
+
+  constructor(bytes: Uint8Array, stage = 'decode') {
+    this.#bytes = bytes;
+    this.#view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    this.#stage = stage;
+    this.#at = 0;
+  }
+
+  get offset(): number {
+    return this.#at;
+  }
+
+  get remaining(): number {
+    return this.#bytes.length - this.#at;
+  }
+
+  #need(count: number): number {
+    const at = this.#at;
+    if (at + count > this.#bytes.length) {
+      throw new ReplicationProtocolError({
+        stage: this.#stage,
+        detail: `a message ended after ${this.#bytes.length} bytes while reading ${count} more at offset ${at}`,
+      });
+    }
+    this.#at = at + count;
+    return at;
+  }
+
+  uint8(): number {
+    return this.#view.getUint8(this.#need(1));
+  }
+
+  int16(): number {
+    return this.#view.getInt16(this.#need(2), false);
+  }
+
+  int32(): number {
+    return this.#view.getInt32(this.#need(4), false);
+  }
+
+  uint32(): number {
+    return this.#view.getUint32(this.#need(4), false);
+  }
+
+  int64(): bigint {
+    return this.#view.getBigInt64(this.#need(8), false);
+  }
+
+  uint64(): bigint {
+    return this.#view.getBigUint64(this.#need(8), false);
+  }
+
+  /** A single byte as its ASCII character — the tag every Postgres message leads with. */
+  tag(): string {
+    return String.fromCharCode(this.uint8());
+  }
+
+  take(count: number): Uint8Array {
+    const at = this.#need(count);
+    return this.#bytes.subarray(at, at + count);
+  }
+
+  /** The whole tail, without copying. */
+  rest(): Uint8Array {
+    return this.take(this.remaining);
+  }
+
+  utf8(count: number): string {
+    return decoder.decode(this.take(count));
+  }
+
+  /** NUL-terminated string. A frame that never terminates one is a truncated frame. */
+  cstring(): string {
+    const end = this.#bytes.indexOf(0, this.#at);
+    if (end < 0) {
+      throw new ReplicationProtocolError({
+        stage: this.#stage,
+        detail: `an unterminated string started at offset ${this.#at}`,
+      });
+    }
+    const value = decoder.decode(this.#bytes.subarray(this.#at, end));
+    this.#at = end + 1;
+    return value;
+  }
+}
+
+/** Builder for a frame. Grows geometrically; `finish()` hands back exactly the bytes written. */
+export class ByteWriter {
+  #bytes: Uint8Array;
+  #dataView: DataView;
+  #at = 0;
+
+  constructor(capacity = 128) {
+    this.#bytes = new Uint8Array(capacity);
+    this.#dataView = new DataView(this.#bytes.buffer);
+  }
+
+  get length(): number {
+    return this.#at;
+  }
+
+  /** Reserves `count` bytes and returns where they start — growing, and re-viewing, if needed. */
+  #room(count: number): number {
+    const at = this.#at;
+    if (at + count > this.#bytes.length) {
+      const grown = new Uint8Array(Math.max(this.#bytes.length * 2, at + count));
+      grown.set(this.#bytes.subarray(0, at));
+      this.#bytes = grown;
+      this.#dataView = new DataView(grown.buffer);
+    }
+    this.#at = at + count;
+    return at;
+  }
+
+  uint8(value: number): this {
+    this.#bytes[this.#room(1)] = value & 0xff;
+    return this;
+  }
+
+  int16(value: number): this {
+    // `#room` may replace the buffer, so the offset is taken before the view is touched.
+    const at = this.#room(2);
+    this.#dataView.setInt16(at, value, false);
+    return this;
+  }
+
+  int32(value: number): this {
+    const at = this.#room(4);
+    this.#dataView.setInt32(at, value, false);
+    return this;
+  }
+
+  int64(value: bigint): this {
+    const at = this.#room(8);
+    this.#dataView.setBigInt64(at, value, false);
+    return this;
+  }
+
+  raw(bytes: Uint8Array): this {
+    const at = this.#room(bytes.length);
+    this.#bytes.set(bytes, at);
+    return this;
+  }
+
+  utf8(value: string): this {
+    return this.raw(encoder.encode(value));
+  }
+
+  cstring(value: string): this {
+    return this.utf8(value).uint8(0);
+  }
+
+  finish(): Uint8Array {
+    return this.#bytes.slice(0, this.#at);
+  }
+}
+
+/** `0/16B3748` — how Postgres prints an LSN on the wire and in `pg_replication_slots`. */
+export const printLsn = (position: bigint): string =>
+  `${(position >> 32n).toString(16).toUpperCase()}/${(position & 0xffffffffn).toString(16).toUpperCase()}`;
+
+/** Postgres timestamps in the replication stream are µs since 2000-01-01, not the Unix epoch. */
+export const PG_EPOCH_MS = 946_684_800_000;
+
+export const pgTimestampToEpochMs = (micros: bigint): number =>
+  Number(micros / 1000n) + PG_EPOCH_MS;
+
+export const epochMsToPgTimestamp = (epochMs: number): bigint =>
+  BigInt(Math.trunc(epochMs) - PG_EPOCH_MS) * 1000n;

package/src/pg-connection-fixture.ts

@@ -0,0 +1,215 @@
+// Single responsibility: the one scripted Postgres server this package's `PgConnection` tests run
+// against — a fake `PgStream` plus a builder per backend message. Two test files need it, and two
+// private copies would be two chances to script a frame the real server never sends.
+// Not part of the public API — `index.ts` deliberately does not re-export it.
+
+import { ByteReader, ByteWriter } from './pg-bytes';
+import { PgConnection, type PgConnectionOptions } from './pg-connection';
+import { frame, type PgStream } from './pg-wire';
+
+export const encoder = new TextEncoder();
+export const decoder = new TextDecoder();
+
+/**
+ * A scriptable fake `PgStream`. `push()` queues chunks for `read()`; once the queue is empty and
+ * the stream has not `end()`-ed, `read()` parks until the next `push()`/`end()` — the shape a test
+ * needs to script a real request/response handshake. `write()` records every byte the client sent.
+ */
+export class FakeStream implements PgStream {
+  readonly writes: Uint8Array[] = [];
+  readonly #queue: Uint8Array[] = [];
+  #ended = false;
+  #parked: ((chunk: Uint8Array | undefined) => void) | undefined;
+  #closed = false;
+  #nextWriteError: Error | undefined;
+  #closeError: Error | undefined;
+
+  push(...chunks: readonly Uint8Array[]): void {
+    for (const chunk of chunks) {
+      const parked = this.#parked;
+      if (parked !== undefined) {
+        this.#parked = undefined;
+        parked(chunk);
+      } else {
+        this.#queue.push(chunk);
+      }
+    }
+  }
+
+  /** Clean EOF: releases a parked `read()` with `undefined`, and every one after it. */
+  end(): void {
+    this.#ended = true;
+    const parked = this.#parked;
+    if (parked !== undefined) {
+      this.#parked = undefined;
+      parked(undefined);
+    }
+  }
+
+  throwOnNextWrite(error: Error): void {
+    this.#nextWriteError = error;
+  }
+
+  /** A socket whose `close()` throws — the failure that must not replace the one being reported. */
+  throwOnClose(error: Error): void {
+    this.#closeError = error;
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  read(): Promise<Uint8Array | undefined> {
+    const next = this.#queue.shift();
+    if (next !== undefined) return Promise.resolve(next);
+    if (this.#ended) return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+      this.#parked = resolve;
+    });
+  }
+
+  write(bytes: Uint8Array): Promise<void> {
+    this.writes.push(bytes);
+    const error = this.#nextWriteError;
+    if (error !== undefined) {
+      this.#nextWriteError = undefined;
+      return Promise.reject(error);
+    }
+    return Promise.resolve();
+  }
+
+  close(): void {
+    this.#closed = true;
+    if (this.#closeError !== undefined) throw this.#closeError;
+  }
+}
+
+// --- Backend message builders: one per row of the wire table, `frame()` owns tag + length -------
+
+export const AUTH_OK = 0;
+export const AUTH_CLEARTEXT = 3;
+export const AUTH_MD5 = 5;
+export const AUTH_SASL = 10;
+export const AUTH_SASL_CONTINUE = 11;
+export const AUTH_SASL_FINAL = 12;
+export const AUTH_GSSAPI = 7;
+
+export const authMethod = (method: number, extra: Uint8Array = new Uint8Array(0)): Uint8Array =>
+  frame('R', new ByteWriter().int32(method).raw(extra).finish());
+export const authOk = (): Uint8Array => authMethod(AUTH_OK);
+export const authCleartext = (): Uint8Array => authMethod(AUTH_CLEARTEXT);
+export const authMd5 = (salt: Uint8Array): Uint8Array => authMethod(AUTH_MD5, salt);
+export const authGssapi = (): Uint8Array => authMethod(AUTH_GSSAPI);
+export const authSaslContinue = (payload: Uint8Array): Uint8Array =>
+  authMethod(AUTH_SASL_CONTINUE, payload);
+export const authSaslFinal = (payload: Uint8Array): Uint8Array =>
+  authMethod(AUTH_SASL_FINAL, payload);
+export const authSasl = (...mechanisms: readonly string[]): Uint8Array => {
+  const writer = new ByteWriter().int32(AUTH_SASL);
+  for (const mechanism of mechanisms) writer.cstring(mechanism);
+  return frame('R', writer.uint8(0).finish());
+};
+
+export const parameterStatus = (name: string, value: string): Uint8Array =>
+  frame('S', new ByteWriter().cstring(name).cstring(value).finish());
+
+export const backendKeyData = (pid: number, secret: number): Uint8Array =>
+  frame('K', new ByteWriter().int32(pid).int32(secret).finish());
+
+export const READY_IDLE = 'I'.charCodeAt(0);
+export const readyForQuery = (): Uint8Array =>
+  frame('Z', new ByteWriter().uint8(READY_IDLE).finish());
+
+export const rowDescriptionStub = (): Uint8Array => frame('T', new Uint8Array(0));
+
+export const dataRow = (...values: readonly (string | null)[]): Uint8Array => {
+  const writer = new ByteWriter().int16(values.length);
+  for (const value of values) {
+    if (value === null) {
+      writer.int32(-1);
+    } else {
+      const bytes = encoder.encode(value);
+      writer.int32(bytes.length).raw(bytes);
+    }
+  }
+  return frame('D', writer.finish());
+};
+
+export const commandComplete = (tag: string): Uint8Array =>
+  frame('C', new ByteWriter().cstring(tag).finish());
+
+export const fieldedMessage = (
+  tag: 'E' | 'N',
+  fields: Readonly<Record<string, string>>,
+): Uint8Array => {
+  const writer = new ByteWriter();
+  for (const [code, value] of Object.entries(fields)) {
+    writer.uint8(code.charCodeAt(0)).cstring(value);
+  }
+  return frame(tag, writer.uint8(0).finish());
+};
+export const errorResponse = (fields: Readonly<Record<string, string>>): Uint8Array =>
+  fieldedMessage('E', fields);
+export const noticeResponse = (fields: Readonly<Record<string, string>>): Uint8Array =>
+  fieldedMessage('N', fields);
+
+export const copyBothResponse = (): Uint8Array =>
+  frame('W', new ByteWriter().uint8(0).int16(0).finish());
+export const copyData = (payload: Uint8Array): Uint8Array => frame('d', payload);
+export const copyDoneFrame = (): Uint8Array => frame('c', new Uint8Array(0));
+
+/** One frontend `tag` + Int32 length + body frame — the shape `frame()` builds. */
+export const decodeFrame = (bytes: Uint8Array): { tag: string; body: Uint8Array } => {
+  const reader = new ByteReader(bytes);
+  const tag = reader.tag();
+  const length = reader.int32();
+  return { tag, body: reader.take(length - 4) };
+};
+
+/** The tagless startup packet: Int32 length, Int32 version, then key/value cstrings to `\0`. */
+export const decodeStartup = (
+  bytes: Uint8Array,
+): { version: number; params: Record<string, string> } => {
+  const reader = new ByteReader(bytes);
+  reader.int32(); // total length — implied by `bytes.length`, not needed to check the shape
+  const version = reader.int32();
+  const params: Record<string, string> = {};
+  for (;;) {
+    const key = reader.cstring();
+    if (key === '') break;
+    params[key] = reader.cstring();
+  }
+  return { version, params };
+};
+
+export const toBase64 = (bytes: Uint8Array): string => btoa(String.fromCharCode(...bytes));
+
+// --- Fixtures --------------------------------------------------------------------------------
+
+export const opts = (
+  stream: PgStream,
+  extra?: Partial<PgConnectionOptions>,
+): PgConnectionOptions => ({
+  stream,
+  user: 'repluser',
+  database: 'app',
+  ...extra,
+});
+
+/** A connection past the handshake, via the cheapest auth method — trust. */
+export async function openTrusted(
+  stream: FakeStream,
+  extra?: Partial<PgConnectionOptions>,
+): Promise<PgConnection> {
+  stream.push(authOk(), readyForQuery());
+  return PgConnection.open(opts(stream, extra));
+}
+
+export const START_REPLICATION_SQL = 'START_REPLICATION SLOT s LOGICAL 0/0';
+
+export async function openInCopyBoth(stream: FakeStream): Promise<PgConnection> {
+  const connection = await openTrusted(stream);
+  stream.push(copyBothResponse());
+  await connection.startCopyBoth(START_REPLICATION_SQL);
+  return connection;
+}