@mh-gg/git 0.1.1-alpha.20260626T104441232Z

package/src/controlPlane.cjs

@@ -0,0 +1,257 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+const { parseMatterhornOrigin, originSlug } = require("./originUrl.cjs");
+const { authForDraft, loadUserSigningProfile } = require("./signing.cjs");
+const { dataRootFor, git, gitDirFromEnv, writeJsonFile } = require("./localMirror.cjs");
+const { isMatterhornPointer, materializeCasObjectOutbox, metadataForPointer } = require("./cas.cjs");
+
+const GIT_PLUGIN_ID = "com.matterhorn.examples.git";
+
+function stableId(prefix, value) {
+  return `${prefix}_${crypto.createHash("sha256").update(canonicalJson(value)).digest("hex").slice(0, 24)}`;
+}
+
+function outboxDirFor(originInput, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const gitDir = options.gitDir || gitDirFromEnv(options.cwd);
+  return path.join(dataRootFor(gitDir), "outbox", originSlug(origin));
+}
+
+function refUpdateDraft({ origin, ref, oldOid, newOid, profile, message, now = Date.now() }) {
+  const parsedOrigin = parseMatterhornOrigin(origin);
+  const signing = profile || loadUserSigningProfile(parsedOrigin.signing);
+  const payload = {
+    repoId: parsedOrigin.repo,
+    roomName: parsedOrigin.room,
+    ref,
+    oldOid: oldOid || null,
+    newOid: newOid || null,
+    expectedOldOid: oldOid || null,
+    fastForwardOnly: true,
+    source: "git-remote-matterhorn",
+    signingProfile: signing.profile,
+    message: message || `Update ${ref} from git-remote-matterhorn`
+  };
+  const draft = {
+    id: stableId("git_ref", { payload, actor: signing.actor, now }),
+    type: "git.ref.update",
+    pluginId: GIT_PLUGIN_ID,
+    payload,
+    createdAt: now,
+    actor: signing.actor
+  };
+  draft.auth = authForDraft(signing, draft);
+  return draft;
+}
+
+async function postJsonTo(target, body, label = "Matterhorn POST") {
+  const response = await fetch(target, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const text = await response.text();
+  let parsed;
+  try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { ok: false, reason: text }; }
+  if (!response.ok || parsed.ok === false) {
+    const error = new Error(parsed.reason || `${label} failed with ${response.status}`);
+    error.response = parsed;
+    throw error;
+  }
+  return parsed;
+}
+
+async function postJson(url, body) {
+  const target = url.endsWith("/matterhorn/operation") ? url : `${url.replace(/\/$/, "")}/matterhorn/operation`;
+  return postJsonTo(target, body, "Matterhorn operation POST");
+}
+
+async function postGitObject(url, envelope) {
+  const target = url.endsWith("/matterhorn/git/object") ? url : `${url.replace(/\/$/, "")}/matterhorn/git/object`;
+  return postJsonTo(target, envelope, "Matterhorn Git object POST");
+}
+
+function backendFor(origin, options = {}) {
+  return options.backend || origin.backend || process.env.MATTERHORN_GIT_CONTROL_URL;
+}
+
+async function publishDraft(originInput, draft, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const backend = backendFor(origin, options);
+  if (backend) return { mode: "http", response: await postJson(backend, draft) };
+  const dir = outboxDirFor(origin, options);
+  const file = path.join(dir, `${draft.id}.json`);
+  writeJsonFile(file, draft);
+  return { mode: "outbox", file };
+}
+
+async function publishChangedRefs(originInput, beforeRefs, afterRefs, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const profile = loadUserSigningProfile(origin.signing, options);
+  const changes = [];
+  const allRefs = new Set([...Object.keys(beforeRefs || {}), ...Object.keys(afterRefs || {})]);
+  for (const ref of [...allRefs].sort()) {
+    const oldOid = beforeRefs?.[ref] || null;
+    const newOid = afterRefs?.[ref] || null;
+    if (oldOid === newOid) continue;
+    const draft = refUpdateDraft({ origin, ref, oldOid, newOid, profile, message: options.message });
+    const result = await publishDraft(origin, draft, options);
+    changes.push({ ref, oldOid, newOid, draft, result });
+  }
+  return changes;
+}
+
+function manifestPublishDraft({ origin, metadata, profile, now = Date.now() }) {
+  const parsedOrigin = parseMatterhornOrigin(origin);
+  const signing = profile || loadUserSigningProfile(parsedOrigin.signing);
+  const payload = {
+    repoId: parsedOrigin.repo,
+    epoch: metadata.epoch,
+    manifestId: metadata.manifestId,
+    objectId: metadata.objectId,
+    clearSize: metadata.clearSize,
+    chunkCount: metadata.chunkCount,
+    pointerProfile: metadata.pointerProfile
+  };
+  const draft = {
+    id: stableId("git_manifest", { payload, actor: signing.actor }),
+    type: "git.manifest.publish",
+    pluginId: GIT_PLUGIN_ID,
+    payload,
+    createdAt: now,
+    actor: signing.actor
+  };
+  draft.auth = authForDraft(signing, draft);
+  return draft;
+}
+
+function chunkAdvertiseDraft({ origin, chunks, epoch, profile, batch = 0, now = Date.now() }) {
+  const parsedOrigin = parseMatterhornOrigin(origin);
+  const signing = profile || loadUserSigningProfile(parsedOrigin.signing);
+  const payload = { repoId: parsedOrigin.repo, epoch, chunks };
+  const draft = {
+    id: stableId("git_chunks", { payload, actor: signing.actor, batch }),
+    type: "git.chunk.advertise",
+    pluginId: GIT_PLUGIN_ID,
+    payload,
+    createdAt: now,
+    actor: signing.actor
+  };
+  draft.auth = authForDraft(signing, draft);
+  return draft;
+}
+
+async function publishPointerMetadata(originInput, pointerText, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const profile = loadUserSigningProfile(origin.signing, options);
+  const metadata = metadataForPointer(pointerText, origin, options);
+  const results = [];
+  if (options.stageObjects !== false) {
+    const staged = materializeCasObjectOutbox(origin, pointerText, options);
+    const backend = backendFor(origin, options);
+    if (backend) {
+      const uploads = [];
+      for (const file of staged.files) uploads.push(await postGitObject(backend, JSON.parse(fs.readFileSync(file, "utf8"))));
+      results.push({ kind: "objects", mode: "http-object", dir: staged.dir, files: staged.files, uploads });
+    } else {
+      results.push({ kind: "objects", mode: "cas-outbox", dir: staged.dir, files: staged.files });
+    }
+  }
+  const manifestDraft = manifestPublishDraft({ origin, metadata, profile, now: options.now || Date.now() });
+  results.push({ kind: "manifest", draft: manifestDraft, result: await publishDraft(origin, manifestDraft, options) });
+  const chunks = metadata.chunks || [];
+  for (let i = 0; i < chunks.length; i += 500) {
+    const batch = chunks.slice(i, i + 500);
+    if (!batch.length) continue;
+    const chunkDraft = chunkAdvertiseDraft({ origin, chunks: batch, epoch: metadata.epoch, profile, batch: i / 500, now: options.now || Date.now() });
+    results.push({ kind: "chunks", draft: chunkDraft, result: await publishDraft(origin, chunkDraft, options) });
+  }
+  return { metadata, results };
+}
+
+function treeEntriesForRef(mirrorPath, oid) {
+  try {
+    const tree = git(["--git-dir", mirrorPath, "ls-tree", "-r", "-z", oid], { encoding: "buffer" });
+    return (Buffer.isBuffer(tree) ? tree.toString("utf8") : String(tree)).split("\0");
+  } catch (matterhornIgnoredError) {
+    globalThis.__matterhornIgnoredError?.(matterhornIgnoredError, "packages/matterhorn-git/src/controlPlane.cjs");
+    return [];
+  }
+}
+
+function parseBlobTreeEntry(entry) {
+  if (!entry) return null;
+  const match = entry.match(/^([0-7]{6})\s+(\S+)\s+([0-9a-f]{40,64})\t(.+)$/);
+  if (!match || match[2] !== "blob") return null;
+  return { blob: match[3], filepath: match[4] };
+}
+
+function smallBlobText(mirrorPath, blob) {
+  try {
+    const size = Number(git(["--git-dir", mirrorPath, "cat-file", "-s", blob]).trim());
+    if (!Number.isFinite(size) || size > 4096) return null;
+    return git(["--git-dir", mirrorPath, "cat-file", "-p", blob]);
+  } catch (matterhornIgnoredError) {
+    globalThis.__matterhornIgnoredError?.(matterhornIgnoredError, "packages/matterhorn-git/src/controlPlane.cjs");
+    return null;
+  }
+}
+
+function rememberPointerBlob(pointers, seenBlobs, mirrorPath, entry) {
+  const parsed = parseBlobTreeEntry(entry);
+  if (!parsed || seenBlobs.has(parsed.blob)) return;
+  seenBlobs.add(parsed.blob);
+  const text = smallBlobText(mirrorPath, parsed.blob);
+  if (text && isMatterhornPointer(text)) pointers.set(text, { pointer: text, blob: parsed.blob, filepath: parsed.filepath });
+}
+
+function scanMirrorPointers(mirrorPath, refs = {}) {
+  const pointers = new Map();
+  const seenBlobs = new Set();
+  const objectIds = Object.values(refs || {}).filter(Boolean);
+  for (const oid of objectIds) {
+    for (const entry of treeEntriesForRef(mirrorPath, oid)) rememberPointerBlob(pointers, seenBlobs, mirrorPath, entry);
+  }
+  return [...pointers.values()].sort((a, b) => a.filepath.localeCompare(b.filepath));
+}
+
+async function publishPointersForMirrorRefs(originInput, mirrorPath, refs = {}, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const pointers = scanMirrorPointers(mirrorPath, refs);
+  const published = [];
+  for (const pointer of pointers) {
+    try {
+      const result = await publishPointerMetadata(origin, pointer.pointer, options);
+      published.push({ ...pointer, ...result });
+    } catch (error) {
+      if (options.allowMissingPointers) published.push({ ...pointer, error });
+      else throw error;
+    }
+  }
+  return published;
+}
+
+function listOutbox(originInput, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const dir = outboxDirFor(origin, options);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort().map((name) => path.join(dir, name));
+}
+
+module.exports = {
+  GIT_PLUGIN_ID,
+  chunkAdvertiseDraft,
+  listOutbox,
+  manifestPublishDraft,
+  outboxDirFor,
+  publishChangedRefs,
+  publishPointerMetadata,
+  publishPointersForMirrorRefs,
+  postGitObject,
+  publishDraft,
+  refUpdateDraft,
+  scanMirrorPointers,
+  stableId
+};

package/src/crypto.cjs

@@ -0,0 +1,213 @@
+const crypto = require("node:crypto");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+
+const XCHACHA20_POLY1305_ALG = "xchacha20-poly1305-ietf";
+const TAG_BYTES = 16;
+const NONCE_BYTES = 24;
+
+function toBuffer(value, label = "value") {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  if (typeof value === "string") return Buffer.from(value, "utf8");
+  throw new Error(`${label} must be a Buffer, Uint8Array, or string`);
+}
+
+function base64url(buffer) {
+  return Buffer.from(buffer).toString("base64url");
+}
+
+function fromBase64url(value, label = "base64url") {
+  try {
+    return Buffer.from(String(value || ""), "base64url");
+  } catch {
+    throw new Error(`${label} must be base64url encoded`);
+  }
+}
+
+function parseSecret(value, label = "secret") {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value);
+  const text = String(value || "").trim();
+  if (!text) throw new Error(`${label} is required`);
+  if (/^[0-9a-fA-F]{64}$/.test(text)) return Buffer.from(text, "hex");
+  try {
+    const decoded = Buffer.from(text, "base64url");
+    if (decoded.length >= 32) return decoded.subarray(0, 32);
+  } catch (matterhornIgnoredError) {
+    globalThis.__matterhornIgnoredError?.(matterhornIgnoredError, "packages/matterhorn-git/src/crypto.cjs");
+  }
+  try {
+    const decoded = Buffer.from(text, "base64");
+    if (decoded.length >= 32) return decoded.subarray(0, 32);
+  } catch (matterhornIgnoredError) {
+    globalThis.__matterhornIgnoredError?.(matterhornIgnoredError, "packages/matterhorn-git/src/crypto.cjs");
+  }
+  return crypto.createHash("sha256").update(text).digest();
+}
+
+function randomBytes(size) {
+  return crypto.randomBytes(size);
+}
+
+function sha256Hex(...parts) {
+  const hash = crypto.createHash("sha256");
+  for (const part of parts) hash.update(toBuffer(part));
+  return hash.digest("hex");
+}
+
+function hmacSha256Hex(key, ...parts) {
+  const hmac = crypto.createHmac("sha256", toBuffer(key, "key"));
+  for (const part of parts) hmac.update(toBuffer(part));
+  return hmac.digest("hex");
+}
+
+function hmacSha256Buffer(key, ...parts) {
+  const hmac = crypto.createHmac("sha256", toBuffer(key, "key"));
+  for (const part of parts) hmac.update(toBuffer(part));
+  return hmac.digest();
+}
+
+function deriveSubkey(root, context, size = 32, salt = "matterhorn-git-v1") {
+  const derived = crypto.hkdfSync("sha256", toBuffer(root, "root"), toBuffer(salt), toBuffer(context), size);
+  return Buffer.from(derived);
+}
+
+function deriveEpochSubkeys(epochRoot, { repoId, epoch }) {
+  const context = `repo=${repoId};epoch=${Number(epoch) || 1}`;
+  return {
+    chunkId: deriveSubkey(epochRoot, `rk-git chunk-id v1;${context}`),
+    chunkEnc: deriveSubkey(epochRoot, `rk-git chunk-enc v1;${context}`),
+    manifestId: deriveSubkey(epochRoot, `rk-git manifest-id v1;${context}`),
+    manifestEnc: deriveSubkey(epochRoot, `rk-git manifest-enc v1;${context}`)
+  };
+}
+
+function readU32LE(buffer, offset) {
+  return buffer.readUInt32LE(offset) >>> 0;
+}
+
+function writeU32LE(value, buffer, offset) {
+  buffer.writeUInt32LE(value >>> 0, offset);
+}
+
+function rotl32(value, bits) {
+  return ((value << bits) | (value >>> (32 - bits))) >>> 0;
+}
+
+function quarterRound(x, a, b, c, d) {
+  x[a] = (x[a] + x[b]) >>> 0; x[d] = rotl32(x[d] ^ x[a], 16);
+  x[c] = (x[c] + x[d]) >>> 0; x[b] = rotl32(x[b] ^ x[c], 12);
+  x[a] = (x[a] + x[b]) >>> 0; x[d] = rotl32(x[d] ^ x[a], 8);
+  x[c] = (x[c] + x[d]) >>> 0; x[b] = rotl32(x[b] ^ x[c], 7);
+}
+
+function hChaCha20(keyInput, nonceInput) {
+  const key = toBuffer(keyInput, "key");
+  const nonce = toBuffer(nonceInput, "nonce");
+  if (key.length !== 32) throw new Error("XChaCha20 key must be 32 bytes");
+  if (nonce.length !== 16) throw new Error("HChaCha20 nonce must be 16 bytes");
+  const constants = Buffer.from("expand 32-byte k", "ascii");
+  const state = new Uint32Array(16);
+  for (let i = 0; i < 4; i += 1) state[i] = readU32LE(constants, i * 4);
+  for (let i = 0; i < 8; i += 1) state[4 + i] = readU32LE(key, i * 4);
+  for (let i = 0; i < 4; i += 1) state[12 + i] = readU32LE(nonce, i * 4);
+  for (let round = 0; round < 10; round += 1) {
+    quarterRound(state, 0, 4, 8, 12);
+    quarterRound(state, 1, 5, 9, 13);
+    quarterRound(state, 2, 6, 10, 14);
+    quarterRound(state, 3, 7, 11, 15);
+    quarterRound(state, 0, 5, 10, 15);
+    quarterRound(state, 1, 6, 11, 12);
+    quarterRound(state, 2, 7, 8, 13);
+    quarterRound(state, 3, 4, 9, 14);
+  }
+  const out = Buffer.alloc(32);
+  writeU32LE(state[0], out, 0);
+  writeU32LE(state[1], out, 4);
+  writeU32LE(state[2], out, 8);
+  writeU32LE(state[3], out, 12);
+  writeU32LE(state[12], out, 16);
+  writeU32LE(state[13], out, 20);
+  writeU32LE(state[14], out, 24);
+  writeU32LE(state[15], out, 28);
+  return out;
+}
+
+function xNonceToIetf(keyInput, nonceInput) {
+  const key = toBuffer(keyInput, "key");
+  const nonce = toBuffer(nonceInput, "nonce");
+  if (key.length !== 32) throw new Error("XChaCha20 key must be 32 bytes");
+  if (nonce.length !== NONCE_BYTES) throw new Error("XChaCha20 nonce must be 24 bytes");
+  const subkey = hChaCha20(key, nonce.subarray(0, 16));
+  const ietfNonce = Buffer.concat([Buffer.alloc(4, 0), nonce.subarray(16, 24)]);
+  return { subkey, ietfNonce };
+}
+
+function canonicalAad(value) {
+  return Buffer.from(canonicalJson(value), "utf8");
+}
+
+function xChaCha20Poly1305Seal({ key, nonce = randomBytes(NONCE_BYTES), plaintext, aad = Buffer.alloc(0) }) {
+  const actualNonce = toBuffer(nonce, "nonce");
+  const { subkey, ietfNonce } = xNonceToIetf(key, actualNonce);
+  const cipher = crypto.createCipheriv("chacha20-poly1305", subkey, ietfNonce, { authTagLength: TAG_BYTES });
+  const aadBuffer = toBuffer(aad, "aad");
+  if (aadBuffer.length) cipher.setAAD(aadBuffer, { plaintextLength: toBuffer(plaintext, "plaintext").length });
+  const ciphertext = Buffer.concat([cipher.update(toBuffer(plaintext, "plaintext")), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return { alg: XCHACHA20_POLY1305_ALG, nonce: actualNonce, ciphertext, tag };
+}
+
+function xChaCha20Poly1305Open({ key, nonce, ciphertext, tag, aad = Buffer.alloc(0) }) {
+  const { subkey, ietfNonce } = xNonceToIetf(key, nonce);
+  const decipher = crypto.createDecipheriv("chacha20-poly1305", subkey, ietfNonce, { authTagLength: TAG_BYTES });
+  const aadBuffer = toBuffer(aad, "aad");
+  if (aadBuffer.length) decipher.setAAD(aadBuffer, { plaintextLength: toBuffer(ciphertext, "ciphertext").length });
+  decipher.setAuthTag(toBuffer(tag, "tag"));
+  return Buffer.concat([decipher.update(toBuffer(ciphertext, "ciphertext")), decipher.final()]);
+}
+
+function chunkAad({ repoId, epoch, chunkPlainId, clearLen, chunker, alg = "rk-git-chunks-v1" }) {
+  return canonicalAad({
+    kind: "matterhorn.git.chunk-object.v1",
+    repoId,
+    keyEpoch: Number(epoch),
+    chunkPlainId,
+    clearLen: Number(clearLen),
+    chunker,
+    aead: XCHACHA20_POLY1305_ALG,
+    alg
+  });
+}
+
+function manifestAad({ repoId, epoch, manifestId, alg = "rk-git-chunks-v1" }) {
+  return canonicalAad({
+    kind: "matterhorn.git.file-manifest.v1",
+    repoId,
+    keyEpoch: Number(epoch),
+    manifestId,
+    aead: XCHACHA20_POLY1305_ALG,
+    alg
+  });
+}
+
+module.exports = {
+  NONCE_BYTES,
+  TAG_BYTES,
+  XCHACHA20_POLY1305_ALG,
+  base64url,
+  canonicalAad,
+  chunkAad,
+  deriveEpochSubkeys,
+  deriveSubkey,
+  fromBase64url,
+  hChaCha20,
+  hmacSha256Buffer,
+  hmacSha256Hex,
+  manifestAad,
+  parseSecret,
+  randomBytes,
+  sha256Hex,
+  toBuffer,
+  xChaCha20Poly1305Open,
+  xChaCha20Poly1305Seal
+};

package/src/index.cjs

@@ -0,0 +1,11 @@
+module.exports = {
+  ...require("./chunker.cjs"),
+  ...require("./crypto.cjs"),
+  ...require("./cas.cjs"),
+  ...require("./controlPlane.cjs"),
+  ...require("./localMirror.cjs"),
+  ...require("./manifest.cjs"),
+  ...require("./originUrl.cjs"),
+  ...require("./remoteHelper.cjs"),
+  ...require("./signing.cjs")
+};

package/src/localMirror.cjs

@@ -0,0 +1,121 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { originSlug, parseMatterhornOrigin } = require("./originUrl.cjs");
+
+function gitDirFromEnv(cwd = process.cwd()) {
+  if (process.env.GIT_DIR) return path.resolve(cwd, process.env.GIT_DIR);
+  const dotGit = path.join(cwd, ".git");
+  if (fs.existsSync(dotGit)) return dotGit;
+  const result = spawnSync("git", ["rev-parse", "--git-dir"], { cwd, encoding: "utf8", windowsHide: true });
+  if (result.status === 0) return path.resolve(cwd, result.stdout.trim());
+  return dotGit;
+}
+
+function dataRootFor(gitDir) {
+  return path.resolve(process.env.MATTERHORN_GIT_DATA_DIR || path.join(gitDir, "matterhorn-sdk"));
+}
+
+function git(args, options = {}) {
+  const result = spawnSync("git", args, {
+    cwd: options.cwd || process.cwd(),
+    encoding: options.encoding || "utf8",
+    stdio: options.stdio || "pipe",
+    env: { ...process.env, ...(options.env || {}) },
+    windowsHide: true
+  });
+  if (result.status !== 0) {
+    const message = result.stderr || result.stdout || result.error?.message || `git ${args.join(" ")} failed`;
+    const error = new Error(message.trim());
+    error.result = result;
+    throw error;
+  }
+  return result.stdout;
+}
+
+function gitConfigGet(name, options = {}) {
+  try { return git(["config", "--get", name], { cwd: options.cwd }).trim(); } catch { return undefined; }
+}
+
+function configuredOrigin(options = {}) {
+  const explicit = options.origin || process.env.MATTERHORN_GIT_ORIGIN;
+  if (explicit) return explicit;
+  const matterhornOrigin = gitConfigGet("matterhorn.origin", options);
+  if (matterhornOrigin) return matterhornOrigin;
+  const remote = gitConfigGet("remote.origin.url", options);
+  if (remote && (remote.startsWith("matterhorn::") || remote.startsWith("matterhorn://") || remote.startsWith("matterhorn+"))) return remote;
+  throw new Error("Matterhorn Git origin is not configured. Run matterhorn-git install-filter <matterhorn-origin> or set MATTERHORN_GIT_ORIGIN.");
+}
+
+function mirrorPathFor(origin, options = {}) {
+  const gitDir = options.gitDir || gitDirFromEnv(options.cwd);
+  const root = dataRootFor(gitDir);
+  return path.join(root, "mirrors", originSlug(origin));
+}
+
+function ensureLocalMirror(originInput, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const mirrorPath = mirrorPathFor(origin, options);
+  if (!fs.existsSync(path.join(mirrorPath, "HEAD"))) {
+    fs.mkdirSync(path.dirname(mirrorPath), { recursive: true, mode: 0o700 });
+    git(["init", "--bare", mirrorPath], { cwd: options.cwd });
+    git(["--git-dir", mirrorPath, "symbolic-ref", "HEAD", `refs/heads/${options.defaultBranch || "main"}`], { cwd: options.cwd });
+  }
+  return { origin, mirrorPath };
+}
+
+function refsFileFor(originInput, options = {}) {
+  const origin = parseMatterhornOrigin(originInput);
+  const gitDir = options.gitDir || gitDirFromEnv(options.cwd);
+  const root = dataRootFor(gitDir);
+  return path.join(root, "state", originSlug(origin), "refs.json");
+}
+
+function readJsonFile(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonFile(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+
+function listMirrorRefs(mirrorPath) {
+  const stdout = git(["--git-dir", mirrorPath, "for-each-ref", "--format=%(objectname) %(refname)", "refs/heads", "refs/tags"], { cwd: process.cwd() });
+  const refs = {};
+  for (const line of stdout.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const [oid, ...nameParts] = trimmed.split(" ");
+    const name = nameParts.join(" ");
+    if (oid && name) refs[name] = oid;
+  }
+  return refs;
+}
+
+function readSavedRefs(originInput, options = {}) {
+  return readJsonFile(refsFileFor(originInput, options), { refs: {} }).refs || {};
+}
+
+function saveRefs(originInput, refs, options = {}) {
+  writeJsonFile(refsFileFor(originInput, options), { version: 1, refs, updatedAt: Date.now() });
+}
+
+module.exports = {
+  configuredOrigin,
+  dataRootFor,
+  gitConfigGet,
+  ensureLocalMirror,
+  git,
+  gitDirFromEnv,
+  listMirrorRefs,
+  mirrorPathFor,
+  readSavedRefs,
+  refsFileFor,
+  saveRefs,
+  writeJsonFile
+};

package/src/manifest.cjs

@@ -0,0 +1,60 @@
+const crypto = require("node:crypto");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+
+function hmacHex(key, value) {
+  const secret = Buffer.isBuffer(key) || key instanceof Uint8Array ? Buffer.from(key) : Buffer.from(String(key || "matterhorn-git-dev-key"));
+  return crypto.createHmac("sha256", secret).update(canonicalJson(value)).digest("hex");
+}
+
+function createLogicalManifestIdentity(input = {}, key = input.key) {
+  const material = {
+    kind: "matterhorn.git.logical-manifest.v1",
+    repoId: input.repoId,
+    epoch: input.epoch,
+    fileMode: input.fileMode || "100644",
+    clearSize: Number(input.clearSize || 0),
+    chunker: input.chunker || { name: "fastcdc", version: "v1" },
+    chunks: (input.chunks || []).map((chunk, index) => ({
+      index: Number.isFinite(chunk.index) ? chunk.index : index,
+      chunkPlainId: chunk.chunkPlainId || chunk.plainId,
+      clearLen: Number(chunk.clearLen || chunk.length || 0)
+    }))
+  };
+  return `hmac-sha256:${hmacHex(key, material)}`;
+}
+
+function createPointer(input = {}) {
+  const lines = [
+    "version https://matterhorn.gg/git-chunks/v1",
+    `repo ${input.repoId}`,
+    `epoch ${input.epoch}`,
+    `manifest-id ${input.manifestId}`,
+    `clear-size ${Number(input.clearSize || 0)}`,
+    `chunk-count ${Number(input.chunkCount || 0)}`,
+    `profile ${input.profile || "dedup-same-epoch/encrypted-manifest/no-padding"}`,
+    `alg ${input.alg || "rk-git-chunks-v1"}`
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+function parsePointer(text) {
+  const fields = {};
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const [key, ...rest] = trimmed.split(/\s+/);
+    fields[key] = rest.join(" ");
+  }
+  if (fields.version !== "https://matterhorn.gg/git-chunks/v1") throw new Error("Not a Matterhorn Git pointer");
+  return {
+    repoId: fields.repo,
+    epoch: Number(fields.epoch),
+    manifestId: fields["manifest-id"],
+    clearSize: Number(fields["clear-size"] || 0),
+    chunkCount: Number(fields["chunk-count"] || 0),
+    profile: fields.profile,
+    alg: fields.alg
+  };
+}
+
+module.exports = { createLogicalManifestIdentity, createPointer, parsePointer };