@karpeleslab/teamclaude 1.0.6 → 1.0.8

package/src/alias.js

@@ -0,0 +1,123 @@
+// `claude` shell alias — print or install/uninstall.
+//
+// The alias simply routes plain `claude` through `teamclaude run`, which itself
+// probes the proxy and falls back to launching claude directly when it's down.
+// So the alias stays a dumb passthrough and all the smarts live in `run`.
+//
+// This only affects interactive shells (aliases aren't seen by editors/scripts
+// that exec `claude` themselves). It's intentionally lighter than a PATH shim:
+// no binary shadowing, one line per rc, trivially reversible.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, realpathSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+const MARKER = '# teamclaude alias';
+
+/** Basename of the user's login shell, e.g. "zsh". Defaults to bash. */
+export function detectShell() {
+  return (process.env.SHELL || '').split('/').pop() || 'bash';
+}
+
+/** Whether a bare command resolves on the current $PATH. */
+function commandOnPath(cmd) {
+  for (const dir of (process.env.PATH || '').split(':')) {
+    if (dir && existsSync(join(dir, cmd))) return true;
+  }
+  return false;
+}
+
+/**
+ * How the alias should invoke teamclaude. Prefer the bare `teamclaude` when it's
+ * on $PATH; otherwise embed the absolute path to this CLI (quoted) so the alias
+ * still works when teamclaude isn't installed on PATH — e.g. run from a clone.
+ */
+export function teamclaudeRef() {
+  if (commandOnPath('teamclaude')) return 'teamclaude';
+  const entry = process.argv[1];
+  if (!entry) return 'teamclaude';
+  let abs;
+  try { abs = realpathSync(entry); } catch { abs = entry; }
+  return `"${abs}"`;
+}
+
+/** The alias definition for a given shell family. */
+export function aliasLine(shell = detectShell(), ref = teamclaudeRef()) {
+  const body = `${ref} run --`;
+  if (shell === 'fish') return `alias claude '${body}'`;
+  return `alias claude='${body}'`;
+}
+
+/** The rc file an alias for this shell should live in. */
+export function rcPathForShell(shell = detectShell()) {
+  const home = homedir();
+  switch (shell) {
+    case 'zsh':  return join(home, '.zshrc');
+    case 'sh':   return join(home, '.profile');
+    case 'fish': {
+      const cfg = process.env.XDG_CONFIG_HOME || join(home, '.config');
+      return join(cfg, 'fish', 'conf.d', 'teamclaude.fish');
+    }
+    case 'bash':
+    default:     return join(home, '.bashrc');
+  }
+}
+
+export function printAlias({ shell = detectShell() } = {}) {
+  const line = aliasLine(shell);
+  console.log('# Route plain `claude` through the proxy (when it is running; direct otherwise).');
+  console.log('# Add this to your shell config:');
+  console.log('');
+  console.log(`  ${line}`);
+  console.log('');
+  console.log(`# Or install it automatically: teamclaude alias --install`);
+  console.log(`#   → writes to ${rcPathForShell(shell)} (override with --shell <bash|zsh|fish|sh>)`);
+}
+
+export function installAlias({ shell = detectShell(), rcPath = rcPathForShell(shell) } = {}) {
+  const line = aliasLine(shell);
+  mkdirSync(dirname(rcPath), { recursive: true });
+  let text = existsSync(rcPath) ? readFileSync(rcPath, 'utf8') : '';
+
+  if (text.includes(line)) {
+    console.log(`Alias already present in ${rcPath}`);
+    return;
+  }
+  if (text && !text.endsWith('\n')) text += '\n';
+  text += `${MARKER}\n${line}\n`;
+  writeFileSync(rcPath, text);
+  console.log(`Installed alias in ${rcPath}`);
+  console.log('Reload your shell (or open a new terminal) to use it.');
+}
+
+export function uninstallAlias({ shell = detectShell(), rcPath = rcPathForShell(shell) } = {}) {
+  if (!existsSync(rcPath)) {
+    console.log(`Nothing to remove (${rcPath} does not exist)`);
+    return;
+  }
+  const text = readFileSync(rcPath, 'utf8');
+  // Strip our marked block: the marker comment + the single line after it.
+  // Matching by marker (not by exact alias text) makes this robust even if the
+  // embedded teamclaude path differs from what's computed now.
+  const blockRe = new RegExp(`\\n?${escapeRe(MARKER)}\\n[^\\n]*\\n?`, 'g');
+  let cleaned = text.replace(blockRe, '\n');
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n');
+
+  if (cleaned === text) {
+    console.log(`Alias not found in ${rcPath}`);
+    return;
+  }
+
+  // For the dedicated fish drop-file, remove it entirely if now empty.
+  if (rcPath.endsWith('teamclaude.fish') && cleaned.trim() === '') {
+    rmSync(rcPath);
+    console.log(`Removed ${rcPath}`);
+    return;
+  }
+  writeFileSync(rcPath, cleaned);
+  console.log(`Removed alias from ${rcPath}`);
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/config.js

@@ -9,6 +9,32 @@ export function getConfigPath() {
   return join(configDir, 'teamclaude.json');
 }
 
+/**
+ * Path to the runtime state file (a sibling of the config). This holds volatile
+ * data learned at runtime — e.g. quota utilization observed passively from
+ * traffic — kept out of the hand-editable config so config stays clean and
+ * isn't rewritten on every state save.
+ */
+export function getStatePath() {
+  const cfg = getConfigPath();
+  return cfg.endsWith('.json') ? cfg.replace(/\.json$/, '.state.json') : cfg + '.state';
+}
+
+export async function loadState() {
+  try {
+    return JSON.parse(await readFile(getStatePath(), 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export async function saveState(state) {
+  const path = getStatePath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+}
+
 export function createDefaultConfig() {
   return {
     proxy: {

package/src/h2/frames.js

@@ -0,0 +1,83 @@
+// Minimal HTTP/2 framing (RFC 7540 §4) — just what the MITM relay needs:
+// split a byte stream into frames, re-serialize frames, and (de)construct
+// HEADERS/CONTINUATION header blocks so we can rewrite one header and re-emit.
+// All other frame types are forwarded verbatim by the relay.
+
+export const FRAME = {
+  DATA: 0x0, HEADERS: 0x1, PRIORITY: 0x2, RST_STREAM: 0x3, SETTINGS: 0x4,
+  PUSH_PROMISE: 0x5, PING: 0x6, GOAWAY: 0x7, WINDOW_UPDATE: 0x8, CONTINUATION: 0x9,
+};
+export const FLAG = { END_STREAM: 0x1, END_HEADERS: 0x4, PADDED: 0x8, PRIORITY: 0x20 };
+
+// Client connection preface: "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n" (RFC 7540 §3.5).
+export const PREFACE = Buffer.from('505249202a20485454502f322e300d0a0d0a534d0d0a0d0a', 'hex');
+
+/**
+ * Split as many complete frames as possible out of `buf`.
+ * Returns { frames, rest } where rest is the unconsumed tail (incomplete frame).
+ * Each frame: { type, flags, streamId, payload, raw } (payload/raw are subarrays).
+ */
+export function readFrames(buf) {
+  const frames = [];
+  let off = 0;
+  while (buf.length - off >= 9) {
+    const length = buf.readUIntBE(off, 3);
+    if (buf.length - off < 9 + length) break;
+    frames.push({
+      type: buf[off + 3],
+      flags: buf[off + 4],
+      streamId: buf.readUInt32BE(off + 5) & 0x7fffffff,
+      payload: buf.subarray(off + 9, off + 9 + length),
+      raw: buf.subarray(off, off + 9 + length),
+    });
+    off += 9 + length;
+  }
+  return { frames, rest: buf.subarray(off) };
+}
+
+/** Serialize one frame. */
+export function buildFrame({ type, flags = 0, streamId, payload = Buffer.alloc(0) }) {
+  const h = Buffer.alloc(9);
+  h.writeUIntBE(payload.length, 0, 3);
+  h[3] = type;
+  h[4] = flags;
+  h.writeUInt32BE(streamId & 0x7fffffff, 5);
+  return Buffer.concat([h, payload]);
+}
+
+/**
+ * Pull the header-block fragment out of a HEADERS payload, stripping any
+ * PADDED / PRIORITY prefixes. Returns { block, priority } where priority is the
+ * 5-byte priority field (or null). Padding is discarded.
+ */
+export function stripHeadersPayload(payload, flags) {
+  let off = 0;
+  let padLen = 0;
+  if (flags & FLAG.PADDED) { padLen = payload[0]; off = 1; }
+  let priority = null;
+  if (flags & FLAG.PRIORITY) { priority = Buffer.from(payload.subarray(off, off + 5)); off += 5; }
+  const block = Buffer.from(payload.subarray(off, payload.length - padLen));
+  return { block, priority };
+}
+
+/**
+ * Build a HEADERS frame (+ CONTINUATION frames if the block exceeds
+ * maxFrameSize) for a re-encoded header block. Padding is not re-added.
+ */
+export function buildHeaderBlock(streamId, block, { endStream = false, priority = null, maxFrameSize = 16384 } = {}) {
+  const prio = priority || Buffer.alloc(0);
+  const firstCap = Math.max(0, maxFrameSize - prio.length);
+  const firstChunk = block.subarray(0, firstCap);
+  let rest = block.subarray(firstChunk.length);
+
+  let hFlags = (endStream ? FLAG.END_STREAM : 0) | (priority ? FLAG.PRIORITY : 0);
+  if (rest.length === 0) hFlags |= FLAG.END_HEADERS;
+
+  const out = [buildFrame({ type: FRAME.HEADERS, flags: hFlags, streamId, payload: Buffer.concat([prio, firstChunk]) })];
+  while (rest.length) {
+    const chunk = rest.subarray(0, maxFrameSize);
+    rest = rest.subarray(chunk.length);
+    out.push(buildFrame({ type: FRAME.CONTINUATION, flags: rest.length === 0 ? FLAG.END_HEADERS : 0, streamId, payload: chunk }));
+  }
+  return Buffer.concat(out);
+}

package/src/h2/hpack.js

@@ -0,0 +1,314 @@
+// HPACK header compression (RFC 7541) — pure JS, no deps.
+//
+// Ported clean-room from the compcol Rust implementation (itself transcribed
+// from RFC 7541's appendices). Used by the MITM proxy to decode/re-encode the
+// HTTP/2 header block so it can rewrite only the `authorization` field while
+// leaving everything else intact. Names/values are Buffers (byte-exact).
+//
+// State note: an HPACK codec is stateful across header blocks (the dynamic
+// table evolves), so one HpackDecoder/HpackEncoder instance is kept per
+// direction per connection.
+
+// ── Huffman code table (RFC 7541 Appendix B): [code, bitLength] by symbol ──
+// Index = symbol value; index 256 = EOS.
+const CODES = [
+  [0x1ff8,13],[0x7fffd8,23],[0xfffffe2,28],[0xfffffe3,28],[0xfffffe4,28],[0xfffffe5,28],[0xfffffe6,28],[0xfffffe7,28],
+  [0xfffffe8,28],[0xffffea,24],[0x3ffffffc,30],[0xfffffe9,28],[0xfffffea,28],[0x3ffffffd,30],[0xfffffeb,28],[0xfffffec,28],
+  [0xfffffed,28],[0xfffffee,28],[0xfffffef,28],[0xffffff0,28],[0xffffff1,28],[0xffffff2,28],[0x3ffffffe,30],[0xffffff3,28],
+  [0xffffff4,28],[0xffffff5,28],[0xffffff6,28],[0xffffff7,28],[0xffffff8,28],[0xffffff9,28],[0xffffffa,28],[0xffffffb,28],
+  [0x14,6],[0x3f8,10],[0x3f9,10],[0xffa,12],[0x1ff9,13],[0x15,6],[0xf8,8],[0x7fa,11],
+  [0x3fa,10],[0x3fb,10],[0xf9,8],[0x7fb,11],[0xfa,8],[0x16,6],[0x17,6],[0x18,6],
+  [0x0,5],[0x1,5],[0x2,5],[0x19,6],[0x1a,6],[0x1b,6],[0x1c,6],[0x1d,6],
+  [0x1e,6],[0x1f,6],[0x5c,7],[0xfb,8],[0x7ffc,15],[0x20,6],[0xffb,12],[0x3fc,10],
+  [0x1ffa,13],[0x21,6],[0x5d,7],[0x5e,7],[0x5f,7],[0x60,7],[0x61,7],[0x62,7],
+  [0x63,7],[0x64,7],[0x65,7],[0x66,7],[0x67,7],[0x68,7],[0x69,7],[0x6a,7],
+  [0x6b,7],[0x6c,7],[0x6d,7],[0x6e,7],[0x6f,7],[0x70,7],[0x71,7],[0x72,7],
+  [0xfc,8],[0x73,7],[0xfd,8],[0x1ffb,13],[0x7fff0,19],[0x1ffc,13],[0x3ffc,14],[0x22,6],
+  [0x7ffd,15],[0x3,5],[0x23,6],[0x4,5],[0x24,6],[0x5,5],[0x25,6],[0x26,6],
+  [0x27,6],[0x6,5],[0x74,7],[0x75,7],[0x28,6],[0x29,6],[0x2a,6],[0x7,5],
+  [0x2b,6],[0x76,7],[0x2c,6],[0x8,5],[0x9,5],[0x2d,6],[0x77,7],[0x78,7],
+  [0x79,7],[0x7a,7],[0x7b,7],[0x7ffe,15],[0x7fc,11],[0x3ffd,14],[0x1ffd,13],[0xffffffc,28],
+  [0xfffe6,20],[0x3fffd2,22],[0xfffe7,20],[0xfffe8,20],[0x3fffd3,22],[0x3fffd4,22],[0x3fffd5,22],[0x7fffd9,23],
+  [0x3fffd6,22],[0x7fffda,23],[0x7fffdb,23],[0x7fffdc,23],[0x7fffdd,23],[0x7fffde,23],[0xffffeb,24],[0x7fffdf,23],
+  [0xffffec,24],[0xffffed,24],[0x3fffd7,22],[0x7fffe0,23],[0xffffee,24],[0x7fffe1,23],[0x7fffe2,23],[0x7fffe3,23],
+  [0x7fffe4,23],[0x1fffdc,21],[0x3fffd8,22],[0x7fffe5,23],[0x3fffd9,22],[0x7fffe6,23],[0x7fffe7,23],[0xffffef,24],
+  [0x3fffda,22],[0x1fffdd,21],[0xfffe9,20],[0x3fffdb,22],[0x3fffdc,22],[0x7fffe8,23],[0x7fffe9,23],[0x1fffde,21],
+  [0x7fffea,23],[0x3fffdd,22],[0x3fffde,22],[0xfffff0,24],[0x1fffdf,21],[0x3fffdf,22],[0x7fffeb,23],[0x7fffec,23],
+  [0x1fffe0,21],[0x1fffe1,21],[0x3fffe0,22],[0x1fffe2,21],[0x7fffed,23],[0x3fffe1,22],[0x7fffee,23],[0x7fffef,23],
+  [0xfffea,20],[0x3fffe2,22],[0x3fffe3,22],[0x3fffe4,22],[0x7ffff0,23],[0x3fffe5,22],[0x3fffe6,22],[0x7ffff1,23],
+  [0x3ffffe0,26],[0x3ffffe1,26],[0xfffeb,20],[0x7fff1,19],[0x3fffe7,22],[0x7ffff2,23],[0x3fffe8,22],[0x1ffffec,25],
+  [0x3ffffe2,26],[0x3ffffe3,26],[0x3ffffe4,26],[0x7ffffde,27],[0x7ffffdf,27],[0x3ffffe5,26],[0xfffff1,24],[0x1ffffed,25],
+  [0x7fff2,19],[0x1fffe3,21],[0x3ffffe6,26],[0x7ffffe0,27],[0x7ffffe1,27],[0x3ffffe7,26],[0x7ffffe2,27],[0xfffff2,24],
+  [0x1fffe4,21],[0x1fffe5,21],[0x3ffffe8,26],[0x3ffffe9,26],[0xffffffd,28],[0x7ffffe3,27],[0x7ffffe4,27],[0x7ffffe5,27],
+  [0xfffec,20],[0xfffff3,24],[0xfffed,20],[0x1fffe6,21],[0x3fffe9,22],[0x1fffe7,21],[0x1fffe8,21],[0x7ffff3,23],
+  [0x3fffea,22],[0x3fffeb,22],[0x1ffffee,25],[0x1ffffef,25],[0xfffff4,24],[0xfffff5,24],[0x3ffffea,26],[0x7ffff4,23],
+  [0x3ffffeb,26],[0x7ffffe6,27],[0x3ffffec,26],[0x3ffffed,26],[0x7ffffe7,27],[0x7ffffe8,27],[0x7ffffe9,27],[0x7ffffea,27],
+  [0x7ffffeb,27],[0xffffffe,28],[0x7ffffec,27],[0x7ffffed,27],[0x7ffffee,27],[0x7ffffef,27],[0x7fffff0,27],[0x3ffffee,26],
+  [0x3fffffff,30],
+];
+const EOS = 256;
+
+class HpackError extends Error {}
+
+// ── Huffman decode trie (built once) ──────────────────────────────────────
+const trie = { c0: [-1], c1: [-1], leaf: [-1] }; // node 0 = root
+(function buildTrie() {
+  for (let sym = 0; sym < CODES.length; sym++) {
+    const [code, len] = CODES[sym];
+    let node = 0;
+    for (let i = len - 1; i >= 0; i--) {
+      const bit = (code >>> i) & 1;
+      const arr = bit ? trie.c1 : trie.c0;
+      let next = arr[node];
+      if (next === -1) {
+        next = trie.leaf.length;
+        trie.c0.push(-1); trie.c1.push(-1); trie.leaf.push(-1);
+        arr[node] = next;
+      }
+      node = next;
+    }
+    trie.leaf[node] = sym;
+  }
+})();
+
+export function huffmanEncodedLen(buf) {
+  let bits = 0;
+  for (const b of buf) bits += CODES[b][1];
+  return Math.ceil(bits / 8);
+}
+
+export function huffmanEncode(buf) {
+  const out = [];
+  let acc = 0n, nbits = 0n;
+  for (const b of buf) {
+    const [code, len] = CODES[b];
+    acc = (acc << BigInt(len)) | BigInt(code);
+    nbits += BigInt(len);
+    while (nbits >= 8n) {
+      nbits -= 8n;
+      out.push(Number((acc >> nbits) & 0xffn));
+    }
+  }
+  if (nbits > 0n) {
+    const pad = 8n - nbits;
+    out.push(Number(((acc << pad) | ((1n << pad) - 1n)) & 0xffn));
+  }
+  return Buffer.from(out);
+}
+
+export function huffmanDecode(buf) {
+  const out = [];
+  let node = 0, depth = 0, allOnes = true;
+  for (const byte of buf) {
+    for (let i = 7; i >= 0; i--) {
+      const bit = (byte >> i) & 1;
+      node = bit ? trie.c1[node] : trie.c0[node];
+      depth++; allOnes = allOnes && bit === 1;
+      const sym = trie.leaf[node];
+      if (sym >= 0) {
+        if (sym === EOS) throw new HpackError('EOS symbol in input');
+        out.push(sym);
+        node = 0; depth = 0; allOnes = true;
+      }
+    }
+  }
+  if (depth >= 8 || !allOnes) throw new HpackError('bad Huffman padding');
+  return Buffer.from(out);
+}
+
+// ── integer codec (RFC 7541 §5.1) ─────────────────────────────────────────
+export function encodeInt(out, value, n, flags) {
+  const maxPrefix = (1 << n) - 1;
+  if (value < maxPrefix) { out.push(flags | value); return; }
+  out.push(flags | maxPrefix);
+  let v = value - maxPrefix;
+  while (v >= 128) { out.push((v & 0x7f) | 0x80); v = Math.floor(v / 128); }
+  out.push(v);
+}
+
+export function decodeInt(buf, pos, n) {
+  const maxPrefix = (1 << n) - 1;
+  if (pos >= buf.length) throw new HpackError('truncated integer');
+  let value = buf[pos] & maxPrefix;
+  let p = pos + 1;
+  if (value < maxPrefix) return [value, p];
+  let shift = 0;
+  for (;;) {
+    if (p >= buf.length) throw new HpackError('truncated integer');
+    const b = buf[p++];
+    if (shift >= 53) throw new HpackError('integer overflow');
+    value += (b & 0x7f) * 2 ** shift;
+    if (!(b & 0x80)) break;
+    shift += 7;
+  }
+  return [value, p];
+}
+
+// ── static table (RFC 7541 Appendix A) ─────────────────────────────────────
+const STATIC_TABLE = [
+  [':authority', ''], [':method', 'GET'], [':method', 'POST'], [':path', '/'],
+  [':path', '/index.html'], [':scheme', 'http'], [':scheme', 'https'], [':status', '200'],
+  [':status', '204'], [':status', '206'], [':status', '304'], [':status', '400'],
+  [':status', '404'], [':status', '500'], ['accept-charset', ''], ['accept-encoding', 'gzip, deflate'],
+  ['accept-language', ''], ['accept-ranges', ''], ['accept', ''], ['access-control-allow-origin', ''],
+  ['age', ''], ['allow', ''], ['authorization', ''], ['cache-control', ''],
+  ['content-disposition', ''], ['content-encoding', ''], ['content-language', ''], ['content-length', ''],
+  ['content-location', ''], ['content-range', ''], ['content-type', ''], ['cookie', ''],
+  ['date', ''], ['etag', ''], ['expect', ''], ['expires', ''],
+  ['from', ''], ['host', ''], ['if-match', ''], ['if-modified-since', ''],
+  ['if-none-match', ''], ['if-range', ''], ['if-unmodified-since', ''], ['last-modified', ''],
+  ['link', ''], ['location', ''], ['max-forwards', ''], ['proxy-authenticate', ''],
+  ['proxy-authorization', ''], ['range', ''], ['referer', ''], ['refresh', ''],
+  ['retry-after', ''], ['server', ''], ['set-cookie', ''], ['strict-transport-security', ''],
+  ['transfer-encoding', ''], ['user-agent', ''], ['vary', ''], ['via', ''],
+  ['www-authenticate', ''],
+].map(([n, v]) => [Buffer.from(n), Buffer.from(v)]);
+const STATIC_LEN = STATIC_TABLE.length;
+const ENTRY_OVERHEAD = 32;
+
+class DynamicTable {
+  constructor(maxSize) { this.entries = []; this.size = 0; this.maxSize = maxSize; }
+  setMaxSize(m) { this.maxSize = m; this.#evict(0); }
+  #entrySize(n, v) { return n.length + v.length + ENTRY_OVERHEAD; }
+  #evict(incoming) {
+    while (this.size + incoming > this.maxSize && this.entries.length) {
+      const [n, v] = this.entries.pop();
+      this.size -= this.#entrySize(n, v);
+    }
+  }
+  insert(name, value) {
+    const need = this.#entrySize(name, value);
+    this.#evict(need);
+    if (need <= this.maxSize) { this.entries.unshift([name, value]); this.size += need; }
+  }
+  get(index) {
+    if (index === 0) return null;
+    if (index <= STATIC_LEN) return STATIC_TABLE[index - 1];
+    const e = this.entries[index - STATIC_LEN - 1];
+    return e || null;
+  }
+  find(name, value) {
+    let nameOnly = null;
+    for (let i = 0; i < STATIC_TABLE.length; i++) {
+      const [n, v] = STATIC_TABLE[i];
+      if (n.equals(name)) {
+        if (v.equals(value)) return { index: i + 1, valueMatched: true };
+        if (nameOnly === null) nameOnly = i + 1;
+      }
+    }
+    for (let pos = 0; pos < this.entries.length; pos++) {
+      const [n, v] = this.entries[pos];
+      if (n.equals(name)) {
+        const index = STATIC_LEN + 1 + pos;
+        if (v.equals(value)) return { index, valueMatched: true };
+        if (nameOnly === null) nameOnly = index;
+      }
+    }
+    return nameOnly === null ? null : { index: nameOnly, valueMatched: false };
+  }
+}
+
+export const DEFAULT_TABLE_SIZE = 4096;
+
+function readString(block, pos) {
+  if (pos >= block.length) throw new HpackError('truncated string');
+  const huff = (block[pos] & 0x80) !== 0;
+  const [len, p] = decodeInt(block, pos, 7);
+  const end = p + len;
+  if (end > block.length) throw new HpackError('truncated string');
+  const raw = block.subarray(p, end);
+  return [huff ? huffmanDecode(raw) : Buffer.from(raw), end];
+}
+
+// A decoded/encodable field. name/value are Buffers; sensitive = never-indexed.
+export class HpackDecoder {
+  constructor(maxSize = DEFAULT_TABLE_SIZE) { this.table = new DynamicTable(maxSize); this.sizeLimit = maxSize; }
+  decode(block) {
+    const fields = [];
+    let pos = 0;
+    while (pos < block.length) {
+      const b = block[pos];
+      if (b & 0x80) { // §6.1 indexed
+        const [idx, np] = decodeInt(block, pos, 7); pos = np;
+        if (idx === 0) throw new HpackError('index 0');
+        const e = this.table.get(idx); if (!e) throw new HpackError('bad index');
+        fields.push({ name: e[0], value: e[1], sensitive: false });
+      } else if (b & 0x40) { // §6.2.1 literal w/ incremental indexing
+        const [name, value, np] = this.#readLiteral(block, pos, 6); pos = np;
+        this.table.insert(name, value);
+        fields.push({ name, value, sensitive: false });
+      } else if (b & 0x20) { // §6.3 dynamic table size update
+        const [newMax, np] = decodeInt(block, pos, 5); pos = np;
+        if (newMax > this.sizeLimit) throw new HpackError('size update over limit');
+        this.table.setMaxSize(newMax);
+      } else { // §6.2.2 / §6.2.3 (4-bit prefix; 0x10 = never indexed)
+        const sensitive = (b & 0x10) !== 0;
+        const [name, value, np] = this.#readLiteral(block, pos, 4); pos = np;
+        fields.push({ name, value, sensitive });
+      }
+    }
+    return fields;
+  }
+  #readLiteral(block, pos, prefix) {
+    const [idx, p0] = decodeInt(block, pos, prefix);
+    let p = p0, name;
+    if (idx === 0) { const [n, np] = readString(block, p); name = n; p = np; }
+    else { const e = this.table.get(idx); if (!e) throw new HpackError('bad name index'); name = e[0]; }
+    const [value, np] = readString(block, p);
+    return [name, value, np];
+  }
+}
+
+export class HpackEncoder {
+  constructor(maxSize = DEFAULT_TABLE_SIZE) {
+    this.table = new DynamicTable(maxSize);
+    this.useHuffman = true;
+    this.pendingSizeUpdate = maxSize === DEFAULT_TABLE_SIZE ? null : maxSize;
+    // When false, never insert into / reference the dynamic table — emit every
+    // field as a literal (full static matches still use the static index). This
+    // makes the encoder independent of the peer's SETTINGS_HEADER_TABLE_SIZE,
+    // which the MITM relay relies on (it doesn't track the upstream's table).
+    this.dynamicIndexing = true;
+  }
+  encode(fields) {
+    const out = [];
+    if (this.pendingSizeUpdate !== null) { encodeInt(out, this.pendingSizeUpdate, 5, 0x20); this.pendingSizeUpdate = null; }
+    for (const f of fields) this.#field(out, f);
+    return Buffer.from(out);
+  }
+  #field(out, f) {
+    const name = Buffer.isBuffer(f.name) ? f.name : Buffer.from(f.name);
+    const value = Buffer.isBuffer(f.value) ? f.value : Buffer.from(f.value);
+    if (f.sensitive) {
+      const m = this.table.find(name, value);
+      const nameIdx = (m && this.table.get(m.index)[0].equals(name)) ? m.index : null;
+      this.#literal(out, 0x10, 4, nameIdx, name, value);
+      return;
+    }
+    const m = this.table.find(name, value);
+    if (m && m.valueMatched) { encodeInt(out, m.index, 7, 0x80); return; } // indexed (static when no indexing)
+    if (this.dynamicIndexing) {
+      this.#literal(out, 0x40, 6, m ? m.index : null, name, value); // literal w/ incremental indexing
+      this.table.insert(name, value);
+    } else {
+      this.#literal(out, 0x00, 4, m ? m.index : null, name, value); // literal without indexing; no insert
+    }
+  }
+  #literal(out, pattern, prefix, nameIdx, name, value) {
+    if (nameIdx !== null) encodeInt(out, nameIdx, prefix, pattern);
+    else { encodeInt(out, 0, prefix, pattern); this.#string(out, name); }
+    this.#string(out, value);
+  }
+  #string(out, s) {
+    if (this.useHuffman && huffmanEncodedLen(s) < s.length) {
+      const coded = huffmanEncode(s);
+      encodeInt(out, coded.length, 7, 0x80);
+      for (const b of coded) out.push(b);
+    } else {
+      encodeInt(out, s.length, 7, 0x00);
+      for (const b of s) out.push(b);
+    }
+  }
+}
+
+export { HpackError };