@intx/hub-api 0.1.2

package/src/git-http/advertise-refs.ts

@@ -0,0 +1,226 @@
+/**
+ * Smart-HTTP `info/refs` advertisement for upload-pack and
+ * receive-pack. Produces a pkt-line stream of the shape:
+ *
+ *   <pkt># service=git-upload-pack\n</pkt>
+ *   0000
+ *   <pkt><sha> HEAD\0<caps with symref=HEAD:<target>>\n</pkt>
+ *   <pkt><sha> <ref>\n</pkt>
+ *   ...
+ *   0000
+ *
+ * The advertisement begins with HEAD when the repo has a born HEAD;
+ * HEAD carries the capability list NUL-separated and a
+ * `symref=HEAD:<target>` token so stock `git clone` lands on a real
+ * branch instead of leaving the working tree unborn. The visible refs
+ * follow in lexicographic order.
+ *
+ * Refs are filtered against `principal.tokenClaims.refPattern` via
+ * the shared simple-glob matcher before advertisement so a token
+ * cannot learn about refs outside its declared scope. HEAD is itself a
+ * symbolic alias and not subject to refPattern filtering, but it is
+ * only advertised when its target ref survives that filter — a token
+ * that cannot see the target cannot learn about HEAD either.
+ *
+ * When no refs survive filtering (or the repo is empty) the
+ * advertisement emits a single zero-oid `capabilities^{}` record so
+ * that stock `git clone` and `git ls-remote` accept the response.
+ */
+
+import type { RepoId } from "@intx/types/sidecar";
+import { glob } from "@intx/hub-common";
+
+import { writePktLine, writeFlush } from "./pkt-line";
+
+/**
+ * Principal contract consumed by the advertise layer. Kept narrow on
+ * purpose: the advertiser only needs the ref-scope claim, so any
+ * principal shape carrying `tokenClaims.refPattern` satisfies it.
+ */
+export type AdvertisePrincipal = {
+  readonly kind: string;
+  readonly tokenClaims: {
+    readonly refPattern: string;
+  };
+};
+
+export type RefEntry = {
+  readonly name: string;
+  readonly sha: string;
+};
+
+/**
+ * Result of resolving HEAD on the underlying repo. `symbolicTarget` is
+ * the ref HEAD symbolically points at (e.g. `refs/heads/main`); `sha`
+ * is the SHA that target currently resolves to. Both fields are
+ * required: a detached HEAD or an unborn HEAD is signalled by
+ * returning `null` from `resolveHead`, not by populating one field and
+ * leaving the other empty.
+ */
+export type HeadResolution = {
+  readonly symbolicTarget: string;
+  readonly sha: string;
+};
+
+/**
+ * Ref-listing capability the advertiser depends on. The substrate or
+ * a repo-direct adapter implements this; the advertiser does not care
+ * which.
+ */
+export interface RefSource {
+  listRefs(principal: AdvertisePrincipal, repoId: RepoId): Promise<RefEntry[]>;
+  /**
+   * Resolve HEAD into the ref it symbolically targets plus the SHA
+   * that ref currently resolves to. Returns `null` when HEAD is
+   * unborn (no commits yet), detached, or the on-disk repo does not
+   * exist. The advertiser uses the result to emit the
+   * `symref=HEAD:<target>` capability so stock `git clone` checks out
+   * a real branch.
+   */
+  resolveHead(
+    principal: AdvertisePrincipal,
+    repoId: RepoId,
+  ): Promise<HeadResolution | null>;
+}
+
+const INTERCHANGE_HUB_AGENT = "interchange-hub/0.0.0";
+
+const BASELINE_CAPABILITIES = [
+  "ofs-delta",
+  "object-format=sha1",
+  `agent=${INTERCHANGE_HUB_AGENT}`,
+];
+
+export const UPLOAD_PACK_CAPABILITIES = [
+  "side-band-64k",
+  ...BASELINE_CAPABILITIES,
+].join(" ");
+
+// receive-pack does not advertise `side-band-64k`: the handler returns
+// the `report-status` payload as raw pkt-lines, not channel-wrapped.
+// Advertising side-band-64k would invite the client to expect a
+// channel-framed response, which `handleReceivePack` does not emit.
+export const RECEIVE_PACK_CAPABILITIES = [
+  ...BASELINE_CAPABILITIES,
+  "report-status",
+].join(" ");
+
+export const EMPTY_REPO_OID = "0".repeat(40);
+
+type Service = "git-upload-pack" | "git-receive-pack";
+
+function filterAndSort(
+  refs: readonly RefEntry[],
+  refPattern: string,
+): RefEntry[] {
+  const allowed = refs.filter((r) => glob.match(refPattern, r.name));
+  allowed.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return allowed;
+}
+
+async function writeAdvertisement(
+  writer: WritableStreamDefaultWriter<Uint8Array>,
+  service: Service,
+  capabilities: string,
+  refs: readonly RefEntry[],
+  head: HeadResolution | null,
+): Promise<void> {
+  await writePktLine(writer, `# service=${service}\n`);
+  await writeFlush(writer);
+
+  // HEAD is only advertised when its symbolic target survives ref
+  // filtering: a token that cannot see the target ref has no business
+  // learning about HEAD either, and stock git would otherwise resolve
+  // the symref against a ref it never received and abort.
+  const headTargetVisible =
+    head !== null &&
+    refs.some((r) => r.name === head.symbolicTarget && r.sha === head.sha);
+
+  if (refs.length === 0) {
+    await writePktLine(
+      writer,
+      `${EMPTY_REPO_OID} capabilities^{}\0${capabilities}\n`,
+    );
+  } else if (head !== null && headTargetVisible) {
+    const capsWithSymref = `${capabilities} symref=HEAD:${head.symbolicTarget}`;
+    await writePktLine(writer, `${head.sha} HEAD\0${capsWithSymref}\n`);
+    for (const ref of refs) {
+      await writePktLine(writer, `${ref.sha} ${ref.name}\n`);
+    }
+  } else {
+    const first = refs[0];
+    if (first === undefined) {
+      throw new Error("advertise-refs: unreachable empty ref list");
+    }
+    await writePktLine(writer, `${first.sha} ${first.name}\0${capabilities}\n`);
+    for (let i = 1; i < refs.length; i++) {
+      const ref = refs[i];
+      if (ref === undefined) {
+        throw new Error("advertise-refs: unreachable undefined ref entry");
+      }
+      await writePktLine(writer, `${ref.sha} ${ref.name}\n`);
+    }
+  }
+
+  await writeFlush(writer);
+}
+
+function advertiseStream(
+  refSource: RefSource,
+  principal: AdvertisePrincipal,
+  repoId: RepoId,
+  service: Service,
+  capabilities: string,
+): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const sink = new WritableStream<Uint8Array>({
+        write(chunk) {
+          controller.enqueue(chunk);
+        },
+      });
+      const writer = sink.getWriter();
+      try {
+        const [allRefs, head] = await Promise.all([
+          refSource.listRefs(principal, repoId),
+          refSource.resolveHead(principal, repoId),
+        ]);
+        const refs = filterAndSort(allRefs, principal.tokenClaims.refPattern);
+        await writeAdvertisement(writer, service, capabilities, refs, head);
+        await writer.close();
+        controller.close();
+      } catch (err) {
+        await writer.abort(err).catch(() => undefined);
+        controller.error(err);
+      }
+    },
+  });
+}
+
+export async function advertiseUploadPack(
+  refSource: RefSource,
+  principal: AdvertisePrincipal,
+  repoId: RepoId,
+): Promise<ReadableStream<Uint8Array>> {
+  return advertiseStream(
+    refSource,
+    principal,
+    repoId,
+    "git-upload-pack",
+    UPLOAD_PACK_CAPABILITIES,
+  );
+}
+
+export async function advertiseReceivePack(
+  refSource: RefSource,
+  principal: AdvertisePrincipal,
+  repoId: RepoId,
+): Promise<ReadableStream<Uint8Array>> {
+  return advertiseStream(
+    refSource,
+    principal,
+    repoId,
+    "git-receive-pack",
+    RECEIVE_PACK_CAPABILITIES,
+  );
+}

package/src/git-http/pkt-line.test.ts

@@ -0,0 +1,220 @@
+import { describe, test, expect } from "bun:test";
+import {
+  readPktLine,
+  writePktLine,
+  writeFlush,
+  writeDelim,
+  writeErr,
+  PKT_LINE_MAX_PAYLOAD,
+} from "./pkt-line";
+import type { PktLine } from "./pkt-line";
+
+function head(lines: PktLine[]): PktLine {
+  const f = lines[0];
+  if (!f) throw new Error("expected at least one pkt-line");
+  return f;
+}
+
+function dataPayload(line: PktLine): Uint8Array {
+  if (line.kind !== "data") {
+    throw new Error(`expected data pkt-line, got ${line.kind}`);
+  }
+  return line.payload;
+}
+
+function bytes(...parts: (string | Uint8Array)[]): Uint8Array {
+  const enc = new TextEncoder();
+  const chunks = parts.map((p) => (typeof p === "string" ? enc.encode(p) : p));
+  const total = chunks.reduce((n, c) => n + c.length, 0);
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  return out;
+}
+
+function streamOf(...frames: Uint8Array[]): ReadableStream<Uint8Array> {
+  let i = 0;
+  return new ReadableStream({
+    pull(controller) {
+      if (i < frames.length) {
+        controller.enqueue(frames[i++]);
+      } else {
+        controller.close();
+      }
+    },
+  });
+}
+
+async function readAll(stream: ReadableStream<Uint8Array>): Promise<PktLine[]> {
+  const reader = stream.getReader();
+  const out: PktLine[] = [];
+  for (;;) {
+    const line = await readPktLine(reader);
+    if (line === null) break;
+    out.push(line);
+  }
+  return out;
+}
+
+describe("writePktLine round-trip", () => {
+  test("writes a standard data pkt-line with 4-byte hex length prefix", async () => {
+    const buf = new Uint8Array(
+      await collectWrites((w) => writePktLine(w, "hello\n")),
+    );
+    const expected = bytes("000ahello\n");
+    expect(Array.from(buf)).toEqual(Array.from(expected));
+  });
+
+  test("readPktLine parses what writePktLine produces", async () => {
+    const payload = bytes(
+      await collectWrites((w) => writePktLine(w, "want abc123\n")),
+    );
+    const lines = await readAll(streamOf(payload));
+    expect(lines.length).toBe(1);
+    const line = head(lines);
+    expect(line.kind).toBe("data");
+    expect(new TextDecoder().decode(dataPayload(line))).toBe("want abc123\n");
+  });
+
+  test("writeFlush emits 0000", async () => {
+    const buf = bytes(await collectWrites((w) => writeFlush(w)));
+    expect(new TextDecoder().decode(buf)).toBe("0000");
+  });
+
+  test("writeDelim emits 0001", async () => {
+    const buf = bytes(await collectWrites((w) => writeDelim(w)));
+    expect(new TextDecoder().decode(buf)).toBe("0001");
+  });
+
+  test("readPktLine recognises flush packet", async () => {
+    const lines = await readAll(streamOf(bytes("0000")));
+    expect(lines.length).toBe(1);
+    expect(head(lines).kind).toBe("flush");
+  });
+
+  test("readPktLine recognises delim packet", async () => {
+    const lines = await readAll(streamOf(bytes("0001")));
+    expect(lines.length).toBe(1);
+    expect(head(lines).kind).toBe("delim");
+  });
+
+  test("empty data line (length 0004) is allowed and yields zero-length payload", async () => {
+    const lines = await readAll(streamOf(bytes("0004")));
+    expect(lines.length).toBe(1);
+    const line = head(lines);
+    expect(line.kind).toBe("data");
+    expect(dataPayload(line).length).toBe(0);
+  });
+
+  test("writeErr emits an ERR pkt-line in the canonical shape", async () => {
+    const buf = bytes(await collectWrites((w) => writeErr(w, "forbidden ref")));
+    expect(new TextDecoder().decode(buf)).toBe("0016ERR forbidden ref\n");
+    const lines = await readAll(streamOf(buf));
+    expect(lines.length).toBe(1);
+    const line = head(lines);
+    expect(line.kind).toBe("data");
+    expect(new TextDecoder().decode(dataPayload(line))).toBe(
+      "ERR forbidden ref\n",
+    );
+  });
+});
+
+describe("readPktLine error handling", () => {
+  test("malformed length (non-hex characters) throws", async () => {
+    await expect(readAll(streamOf(bytes("zzzzfoo")))).rejects.toThrow(
+      /malformed pkt-line length/i,
+    );
+  });
+
+  test("length below 4 (and not 0000 or 0001) throws", async () => {
+    await expect(readAll(streamOf(bytes("0003")))).rejects.toThrow(
+      /reserved pkt-line length/i,
+    );
+  });
+
+  test("truncated body throws", async () => {
+    await expect(readAll(streamOf(bytes("0010abc")))).rejects.toThrow(
+      /truncated pkt-line/i,
+    );
+  });
+
+  test("truncated length header throws", async () => {
+    await expect(readAll(streamOf(bytes("00")))).rejects.toThrow(
+      /truncated pkt-line/i,
+    );
+  });
+
+  test("oversize payload (length > 65520) throws", async () => {
+    // 65521 = 0xFFF1 — one more byte than max pkt-line length
+    await expect(readAll(streamOf(bytes("fff1")))).rejects.toThrow(
+      /oversize pkt-line/i,
+    );
+  });
+});
+
+describe("readPktLine across stream chunk boundaries", () => {
+  test("length header split across chunks", async () => {
+    const lines = await readAll(streamOf(bytes("00"), bytes("0aHELLO\n")));
+    expect(lines.length).toBe(1);
+    const line = head(lines);
+    expect(line.kind).toBe("data");
+    expect(new TextDecoder().decode(dataPayload(line))).toBe("HELLO\n");
+  });
+
+  test("body split across chunks", async () => {
+    const lines = await readAll(streamOf(bytes("000aHEL"), bytes("LO\n")));
+    expect(lines.length).toBe(1);
+    expect(new TextDecoder().decode(dataPayload(head(lines)))).toBe("HELLO\n");
+  });
+
+  test("single byte at a time", async () => {
+    const frame = bytes("000aHELLO\n");
+    const chunks = Array.from(frame).map((b) => new Uint8Array([b]));
+    const lines = await readAll(streamOf(...chunks));
+    expect(lines.length).toBe(1);
+    expect(new TextDecoder().decode(dataPayload(head(lines)))).toBe("HELLO\n");
+  });
+
+  test("multiple frames mixed across chunk boundaries", async () => {
+    // "want abc" = 8 bytes -> frame length 0x0c ; "have def" same.
+    const lines = await readAll(
+      streamOf(bytes("000cwant"), bytes(" abc000chave def0000")),
+    );
+    expect(lines.map((l) => l.kind)).toEqual(["data", "data", "flush"]);
+  });
+});
+
+describe("writePktLine size constraints", () => {
+  test("rejects payload larger than max pkt-line payload", async () => {
+    const oversized = "x".repeat(PKT_LINE_MAX_PAYLOAD + 1);
+    await expect(
+      collectWrites((w) => writePktLine(w, oversized)),
+    ).rejects.toThrow(/oversize/i);
+  });
+
+  test("accepts payload of exactly max pkt-line payload size", async () => {
+    const max = "x".repeat(PKT_LINE_MAX_PAYLOAD);
+    const buf = bytes(await collectWrites((w) => writePktLine(w, max)));
+    // 0xFFF0 = 65520
+    expect(new TextDecoder().decode(buf.slice(0, 4))).toBe("fff0");
+    expect(buf.length).toBe(4 + PKT_LINE_MAX_PAYLOAD);
+  });
+});
+
+async function collectWrites(
+  fn: (w: WritableStreamDefaultWriter<Uint8Array>) => Promise<void>,
+): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  const sink = new WritableStream<Uint8Array>({
+    write(chunk) {
+      chunks.push(chunk);
+    },
+  });
+  const writer = sink.getWriter();
+  await fn(writer);
+  await writer.close();
+  return bytes(...chunks);
+}

package/src/git-http/pkt-line.ts

@@ -0,0 +1,235 @@
+/**
+ * pkt-line framing as defined by Git's
+ * `Documentation/technical/protocol-common.txt`. A pkt-line is a
+ * 4-byte ASCII hex length header followed by `length - 4` bytes of
+ * payload. Two reserved special headers carry no payload:
+ *
+ * - `0000` flush packet (end of a logical message)
+ * - `0001` delim packet (separator inside a message)
+ *
+ * Maximum total frame length is 0xFFF0; thus the maximum payload
+ * size is 0xFFF0 - 4 = 65520.
+ */
+
+const HEADER_BYTES = 4;
+const MAX_FRAME_LENGTH = 0xfff0;
+
+export const PKT_LINE_MAX_PAYLOAD = MAX_FRAME_LENGTH - HEADER_BYTES; // 65520
+
+export type PktLine =
+  | { kind: "flush" }
+  | { kind: "delim" }
+  | { kind: "data"; payload: Uint8Array };
+
+function hexDigit(v: number): string {
+  if (v < 10) return String.fromCharCode(0x30 + v);
+  return String.fromCharCode(0x61 + (v - 10));
+}
+
+function hex4(n: number): string {
+  return (
+    hexDigit((n >> 12) & 0xf) +
+    hexDigit((n >> 8) & 0xf) +
+    hexDigit((n >> 4) & 0xf) +
+    hexDigit(n & 0xf)
+  );
+}
+
+function parseHex4(s: string): number {
+  let v = 0;
+  for (let i = 0; i < 4; i++) {
+    const c = s.charCodeAt(i);
+    let d: number;
+    if (c >= 0x30 && c <= 0x39) {
+      d = c - 0x30;
+    } else if (c >= 0x61 && c <= 0x66) {
+      d = c - 0x61 + 10;
+    } else if (c >= 0x41 && c <= 0x46) {
+      d = c - 0x41 + 10;
+    } else {
+      throw new Error(`malformed pkt-line length: ${JSON.stringify(s)}`);
+    }
+    v = (v << 4) | d;
+  }
+  return v;
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+function sliceBytes(a: Uint8Array, start: number, end?: number): Uint8Array {
+  const e = end ?? a.length;
+  const out = new Uint8Array(e - start);
+  out.set(a.subarray(start, e), 0);
+  return out;
+}
+
+/**
+ * Reader interface accepted by `readPktLine`: any object that yields
+ * `{ value, done }` results when `.read()` is called. The DOM
+ * `ReadableStreamDefaultReader<Uint8Array>` and the Node
+ * `node:stream/web` reader both satisfy this shape, so callers can
+ * pass `stream.getReader()` directly without type-juggling between
+ * the two reader flavours.
+ */
+export interface PktLineByteReader {
+  read(): Promise<{ done: boolean; value?: Uint8Array | undefined }>;
+}
+
+/**
+ * Buffered reader that exposes byte-exact reads and tolerates
+ * underlying chunks of any size, including chunks that split a
+ * pkt-line header or body.
+ */
+class BufferedByteReader {
+  private buf: Uint8Array = new Uint8Array(0);
+  private done = false;
+
+  constructor(private readonly reader: PktLineByteReader) {}
+
+  private async pull(): Promise<void> {
+    if (this.done) return;
+    const r = await this.reader.read();
+    if (r.done) {
+      this.done = true;
+      return;
+    }
+    const value = r.value;
+    if (value && value.length > 0) {
+      this.buf =
+        this.buf.length === 0
+          ? new Uint8Array(value)
+          : concatBytes(this.buf, value);
+    }
+  }
+
+  async readExact(n: number): Promise<Uint8Array | null> {
+    while (this.buf.length < n) {
+      if (this.done) {
+        if (this.buf.length === 0) return null;
+        throw new Error(
+          `truncated pkt-line: needed ${n} bytes, got ${this.buf.length}`,
+        );
+      }
+      await this.pull();
+    }
+    const out = sliceBytes(this.buf, 0, n);
+    this.buf = sliceBytes(this.buf, n);
+    return out;
+  }
+
+  async readExactOrThrow(n: number, what: string): Promise<Uint8Array> {
+    while (this.buf.length < n) {
+      if (this.done) {
+        throw new Error(
+          `truncated pkt-line ${what}: needed ${n} bytes, got ${this.buf.length}`,
+        );
+      }
+      await this.pull();
+    }
+    const out = sliceBytes(this.buf, 0, n);
+    this.buf = sliceBytes(this.buf, n);
+    return out;
+  }
+}
+
+const READER_BUFFER = new WeakMap<PktLineByteReader, BufferedByteReader>();
+
+function bufferFor(r: PktLineByteReader): BufferedByteReader {
+  let b = READER_BUFFER.get(r);
+  if (!b) {
+    b = new BufferedByteReader(r);
+    READER_BUFFER.set(r, b);
+  }
+  return b;
+}
+
+export async function readPktLine(
+  r: PktLineByteReader,
+): Promise<PktLine | null> {
+  const buf = bufferFor(r);
+  const header = await buf.readExact(HEADER_BYTES);
+  if (header === null) return null;
+  const h0 = header[0];
+  const h1 = header[1];
+  const h2 = header[2];
+  const h3 = header[3];
+  if (
+    h0 === undefined ||
+    h1 === undefined ||
+    h2 === undefined ||
+    h3 === undefined
+  ) {
+    throw new Error("truncated pkt-line: short header");
+  }
+  const headerStr = String.fromCharCode(h0, h1, h2, h3);
+  const length = parseHex4(headerStr);
+  if (length === 0) return { kind: "flush" };
+  if (length === 1) return { kind: "delim" };
+  if (length === 2 || length === 3) {
+    throw new Error(`reserved pkt-line length: ${headerStr}`);
+  }
+  if (length > MAX_FRAME_LENGTH) {
+    throw new Error(`oversize pkt-line: length ${length}`);
+  }
+  const bodyLen = length - HEADER_BYTES;
+  const payload =
+    bodyLen === 0
+      ? new Uint8Array(0)
+      : await buf.readExactOrThrow(bodyLen, "body");
+  return { kind: "data", payload };
+}
+
+function encodePayload(payload: string | Uint8Array): Uint8Array {
+  if (typeof payload === "string") return new TextEncoder().encode(payload);
+  return payload;
+}
+
+export async function writePktLine(
+  w: WritableStreamDefaultWriter<Uint8Array>,
+  payload: string | Uint8Array,
+): Promise<void> {
+  const body = encodePayload(payload);
+  if (body.length > PKT_LINE_MAX_PAYLOAD) {
+    throw new Error(
+      `oversize pkt-line payload: ${body.length} > ${PKT_LINE_MAX_PAYLOAD}`,
+    );
+  }
+  const length = body.length + HEADER_BYTES;
+  const header = new TextEncoder().encode(hex4(length));
+  const frame = new Uint8Array(header.length + body.length);
+  frame.set(header, 0);
+  frame.set(body, header.length);
+  await w.write(frame);
+}
+
+export async function writeFlush(
+  w: WritableStreamDefaultWriter<Uint8Array>,
+): Promise<void> {
+  await w.write(new TextEncoder().encode("0000"));
+}
+
+export async function writeDelim(
+  w: WritableStreamDefaultWriter<Uint8Array>,
+): Promise<void> {
+  await w.write(new TextEncoder().encode("0001"));
+}
+
+/**
+ * Emit an ERR pkt-line as used during upload-pack negotiation. Stock
+ * git surfaces this as `remote: <msg>; fatal: protocol error`. The
+ * frame body is `ERR <msg>\n`, encoded as a normal data pkt-line.
+ *
+ * Receive-pack reports failures with `ng <ref> <msg>` during the
+ * report-status phase instead; do not use writeErr there.
+ */
+export async function writeErr(
+  w: WritableStreamDefaultWriter<Uint8Array>,
+  msg: string,
+): Promise<void> {
+  await writePktLine(w, `ERR ${msg}\n`);
+}