@heyquilt/seam 0.27.0 → 0.130.0

package/lib/quilts/sealed.js

@@ -0,0 +1,231 @@
+// Sealed quilts (plans/quilt-source-control/11.11): the server never sees a sealed quilt's file
+// contents. One data key per quilt and key version, made and held by its members' computers,
+// wrapped for each member's X25519 key; the server keeps only the wraps. Blob bytes are sealed
+// here (AES-256-GCM, magic QF1, the key version in the header) and their ids are keyed, so the
+// server cannot test whether the quilt holds a file it can guess:
+//   id_key = BLAKE3 derive_key("quilt sealed id v1", data_key)
+//   id     = BLAKE3 keyed(id_key, "quilt blob v1" ‖ plaintext)
+// Tree nodes, paths, sizes and commit records stay plaintext: the server builds snapshots, checks
+// protections and claims, and detects conflicts by path from them.
+//
+// This file is both sides: the codec a client seals and opens with, and the wrap format.
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { blake3 } from '@noble/hashes/blake3.js'
+import { diffMarkers } from './conflict-format.js'
+import { squareShort } from './errors.js'
+
+export const MAGIC = Buffer.from('QF1')
+const HEAD = MAGIC.length + 4 + 12
+const TAG = 16
+export const SEALED_OVERHEAD = HEAD + TAG
+const X25519_SPKI = Buffer.from('302a300506032b656e032100', 'hex')
+const ID_CONTEXT = Buffer.from('quilt sealed id v1')
+const BLOB_PREFIX = Buffer.from('quilt blob v1')
+const WRAP_INFO = Buffer.from('seam sealed wrap v1')
+
+/** The id key a data key gives (one per key version). */
+export const idKeyOf = (dataKey) => blake3(Buffer.from(dataKey), { context: ID_CONTEXT })
+/** A sealed quilt's blob id: keyed BLAKE3 of the plaintext. */
+export const sealedId = (idKey, plaintext) => Buffer.from(blake3(Buffer.concat([BLOB_PREFIX, Buffer.from(plaintext)]), { key: idKey })).toString('hex')
+
+/** Seals bytes under a key version: QF1 ‖ version u32 ‖ iv ‖ ciphertext ‖ tag. */
+export function sealBytes (dataKey, version, plaintext) {
+  const iv = crypto.randomBytes(12)
+  const head = Buffer.alloc(MAGIC.length + 4)
+  MAGIC.copy(head); head.writeUInt32BE(version, MAGIC.length)
+  const c = crypto.createCipheriv('aes-256-gcm', Buffer.from(dataKey), iv)
+  c.setAAD(head)
+  const body = Buffer.concat([c.update(Buffer.from(plaintext)), c.final()])
+  return Buffer.concat([head, iv, body, c.getAuthTag()])
+}
+
+/** The key version a sealed blob was sealed under, or null when the bytes are not sealed. */
+export function versionOf (sealed) {
+  const b = Buffer.from(sealed)
+  return b.length >= SEALED_OVERHEAD && b.subarray(0, MAGIC.length).equals(MAGIC) ? b.readUInt32BE(MAGIC.length) : null
+}
+
+export function openBytes (dataKey, sealed) {
+  const b = Buffer.from(sealed)
+  if (versionOf(b) == null) throw new Error('not a sealed blob')
+  const d = crypto.createDecipheriv('aes-256-gcm', Buffer.from(dataKey), b.subarray(MAGIC.length + 4, HEAD))
+  d.setAAD(b.subarray(0, MAGIC.length + 4))
+  d.setAuthTag(b.subarray(b.length - TAG))
+  return Buffer.concat([d.update(b.subarray(HEAD, b.length - TAG)), d.final()])
+}
+
+// ---- wraps: a data key for one member's X25519 key ----
+
+const rawX25519 = (keyObject) => keyObject.export({ format: 'der', type: 'spki' }).subarray(X25519_SPKI.length)
+const x25519Public = (raw) => crypto.createPublicKey({ key: Buffer.concat([X25519_SPKI, Buffer.from(raw, 'base64')]), format: 'der', type: 'spki' })
+/** A sealing key's id: `x25519:` and 16 hex of the sha256 of its raw public bytes. */
+export const sealingKeyId = (raw) => 'x25519:' + crypto.createHash('sha256').update(Buffer.from(raw, 'base64')).digest('hex').slice(0, 16)
+
+function wrapKey (shared, epk, recipient) {
+  return Buffer.from(crypto.hkdfSync('sha256', shared, Buffer.concat([epk, recipient]), WRAP_INFO, 32))
+}
+
+/** Wraps a data key for a member's X25519 public key (raw, base64): epk ‖ iv ‖ ciphertext ‖ tag. */
+export function wrapFor (publicKey, dataKey) {
+  const eph = crypto.generateKeyPairSync('x25519')
+  const epk = rawX25519(eph.publicKey)
+  const recipient = Buffer.from(publicKey, 'base64')
+  const k = wrapKey(crypto.diffieHellman({ privateKey: eph.privateKey, publicKey: x25519Public(publicKey) }), epk, recipient)
+  const iv = crypto.randomBytes(12)
+  const c = crypto.createCipheriv('aes-256-gcm', k, iv)
+  const body = Buffer.concat([c.update(Buffer.from(dataKey)), c.final()])
+  return Buffer.concat([epk, iv, body, c.getAuthTag()]).toString('base64')
+}
+
+export function unwrapWith (privateKey, wrap) {
+  const b = Buffer.from(wrap, 'base64')
+  const epk = b.subarray(0, 32)
+  const own = rawX25519(crypto.createPublicKey(privateKey))
+  const k = wrapKey(crypto.diffieHellman({ privateKey, publicKey: x25519Public(epk.toString('base64')) }), epk, own)
+  const d = crypto.createDecipheriv('aes-256-gcm', k, b.subarray(32, 44))
+  d.setAuthTag(b.subarray(b.length - TAG))
+  return Buffer.concat([d.update(b.subarray(44, b.length - TAG)), d.final()])
+}
+
+// ---- this computer's sealing key ----
+
+/** Where this computer's sealing key lives: SEAM_SEALING_KEY, else ~/.seam/sealing-key.pem. */
+export const sealingKeyFile = () => process.env.SEAM_SEALING_KEY || path.join(process.env.SEAM_HOME || path.join(os.homedir(), '.seam'), 'sealing-key.pem')
+
+/** This computer's X25519 key, made on first use: { privateKey, public_key (raw base64), id }. */
+export function localSealingKey (file = sealingKeyFile(), { make = true } = {}) {
+  if (!fs.existsSync(file)) {
+    if (!make) return null
+    const { privateKey } = crypto.generateKeyPairSync('x25519')
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, privateKey.export({ format: 'pem', type: 'pkcs8' }), { mode: 0o600 })
+  }
+  const privateKey = crypto.createPrivateKey(fs.readFileSync(file))
+  const pub = rawX25519(crypto.createPublicKey(privateKey)).toString('base64')
+  return { privateKey, public_key: pub, id: sealingKeyId(pub) }
+}
+
+/**
+ * A codec for a sealed quilt from its data keys ({ version: key }): ids are keyed with the
+ * newest version's key, which also seals; open() reads any version and checks the id.
+ */
+export function codecOf (keys) {
+  const versions = Object.keys(keys).map(Number).sort((a, b) => a - b)
+  if (!versions.length) throw new Error('no data key for this sealed quilt on this computer: ask a member who has it to run seam seal grant <your member id>')
+  const latest = versions[versions.length - 1]
+  const idKeys = new Map(versions.map((v) => [v, idKeyOf(keys[v])]))
+  return {
+    sealed: true,
+    version: latest,
+    idOf: (plaintext) => sealedId(idKeys.get(latest), plaintext),
+    seal: (plaintext) => sealBytes(keys[latest], latest, plaintext),
+    /** The plaintext of a sealed blob, checked against its id (a wrong object is reported, never used). */
+    open (id, sealed) {
+      const v = versionOf(sealed)
+      if (v == null || !keys[v]) throw new Error(`blob ${String(id).slice(0, 12)} is sealed under key version ${v}, which this computer does not hold`)
+      const plain = openBytes(keys[v], sealed)
+      if (sealedId(idKeys.get(v), plain) !== id) throw Object.assign(new Error(`blob ${String(id).slice(0, 12)} does not match its id after opening: reported, not used`), { code: 'id_mismatch', id })
+      return plain
+    },
+    plainSize: (sealedSize) => sealedSize - SEALED_OVERHEAD
+  }
+}
+
+/**
+ * The codec for `quilt` through `client`, or null when it is not sealed: this computer's
+ * sealing key opens the wraps the server holds for this member.
+ */
+export async function codecFor (client, quilt, { keyFile } = {}) {
+  const s = await client.seal(quilt)
+  if (!s.sealed) return null
+  const me = localSealingKey(keyFile, { make: false })
+  if (!me) throw new Error('This quilt is sealed and this computer has no sealing key: run seam seal key, then ask a member who has the quilt\'s key to run seam seal grant <your member id>.')
+  const keys = {}
+  for (const w of s.wraps) if (w.key_id === me.id) { try { keys[w.version] = unwrapWith(me.privateKey, w.wrap) } catch {} }
+  return codecOf(keys)
+}
+
+/**
+ * A sealed quilt's conflict as text with markers, made on the member's computer from its term
+ * (the server cannot read the sides): the same `diff` markers the server writes for other quilts.
+ */
+export async function materialiseSealed (term, termIdHex, readSide) {
+  const side = async (s) => (s && s.blob ? (await readSide(s.blob)).toString('utf8') : '')
+  const label = (s, which) => `${which} (${[s.by || 'someone', s.from_square && squareShort(s.from_square), s.from_commit && s.from_commit.slice(0, 8)].filter(Boolean).join(' · ')})`
+  const sides = await Promise.all(term.adds.map(async (s, i) => ({ text: s.blob ? await side(s) : null, label: label(s, i === 0 ? 'ours' : 'theirs'), by: s.by })))
+  return Buffer.from(diffMarkers({ sides, bases: await Promise.all(term.removes.map(side)), tag: `quilt-conflict ${termIdHex.slice(0, 12)}`, kind: term.kind }))
+}
+
+/** A `cat` answer's file as plaintext: opened with the codec when the quilt is sealed. */
+export async function catBytes (client, quilt, r, codec) {
+  if (!r.sealed) return Buffer.from(r.content, 'base64')
+  if (!codec) throw new Error('This quilt is sealed and this computer holds no key for it.')
+  if (r.conflict) {
+    return materialiseSealed(r.term_record, r.term, async (id) => {
+      const { blobs } = await client.blobs(quilt, [id])
+      return codec.open(id, Buffer.from(blobs[id], 'base64'))
+    })
+  }
+  return codec.open(r.blob, Buffer.from(r.content, 'base64'))
+}
+
+/** This computer's sealing key, made and registered with the server on first use. */
+export async function ensureSealingKey (client, { keyFile } = {}) {
+  const me = localSealingKey(keyFile)
+  await client.addSealingKey(me.public_key)
+  return me
+}
+
+/** A new sealed quilt's first key: made here, wrapped for this computer only. */
+export async function startSealed (client, quilt, memberId, { keyFile } = {}) {
+  const me = await ensureSealingKey(client, { keyFile })
+  return client.grantSeal(quilt, [{ version: 1, member_id: memberId, key_id: me.id, wrap: wrapFor(me.public_key, crypto.randomBytes(32)) }])
+}
+
+/** After switching a quilt to sealed: makes its first key here, unless a key is already wrapped. */
+export async function startSealedIfNew (client, quilt, opts) {
+  if ((await client.seal(quilt)).version) return null
+  return startSealed(client, quilt, (await client.quilt(quilt)).you.member_id, opts)
+}
+
+/** The quilt's data keys this computer holds, by version. */
+async function heldKeys (client, quilt, keyFile) {
+  const s = await client.seal(quilt)
+  if (!s.sealed) throw new Error(`${quilt} is not sealed`)
+  const me = localSealingKey(keyFile, { make: false })
+  const keys = {}
+  if (me) for (const w of s.wraps) if (w.key_id === me.id) { try { keys[w.version] = unwrapWith(me.privateKey, w.wrap) } catch {} }
+  if (!keys[s.version]) throw new Error(`This computer does not hold ${quilt}'s key (version ${s.version}): a member who does runs seam seal grant <your member id>.`)
+  return { s, keys, me }
+}
+
+/** Wraps the quilt's current key for every sealing key `member` has registered. */
+export async function grantSealed (client, quilt, member, { keyFile } = {}) {
+  const { s, keys } = await heldKeys(client, quilt, keyFile)
+  const { keys: theirs } = await client.sealingKeys(member)
+  if (!theirs.length) throw new Error(`${member} has no sealing key yet: they run seam seal key on their computer first.`)
+  return client.grantSeal(quilt, theirs.map((k) => ({ version: s.version, member_id: member, key_id: k.key_id, wrap: wrapFor(k.public_key, keys[s.version]) })))
+}
+
+/**
+ * A new key version, wrapped for everyone who holds the current one except `without` (removing
+ * a member): what they fetched stays readable to them, nothing sealed from now on is.
+ */
+export async function rotateSealed (client, quilt, { without = [], keyFile } = {}) {
+  const { s } = await heldKeys(client, quilt, keyFile)
+  const next = crypto.randomBytes(32)
+  const wraps = []
+  const members = [...new Set(s.holders.map((h) => h.member_id))].filter((m) => !without.includes(m))
+  for (const m of members) for (const k of (await client.sealingKeys(m)).keys) wraps.push({ version: s.version + 1, member_id: m, key_id: k.key_id, wrap: wrapFor(k.public_key, next) })
+  return client.rotateSeal(quilt, s.version + 1, wraps)
+}
+
+/** A sealed quilt's state in a few lines. */
+export function describeSeal (s) {
+  if (!s.sealed) return `${s.quilt} is not sealed.`
+  const who = [...new Set(s.holders.map((h) => h.member_id))]
+  return `${s.quilt} is sealed: key version ${s.version}, held by ${who.join(', ') || 'nobody yet'}. ${s.wraps.some((w) => w.version === s.version) ? 'You hold it.' : 'You do not hold it: ask one of them to run seam seal grant <your member id>.'}\nThe server sees paths, sizes, which files are equal, and commit details (author, message, times); never file contents.`
+}

package/lib/quilts/secrets.js

@@ -0,0 +1,86 @@
+// Secret scanning at commit time (plans/quilt-source-control/11.9): a commit's new file contents
+// are scanned before the transaction, O(changes), for known key shapes and for high-entropy
+// values assigned to secret-sounding names. A finding names its path, line, rule and an id
+// that is the same for the same value at the same path, so a person can let one through by its
+// id; it never carries the value. `.env` files are refused outright (only `.env.example`
+// passes). A Seam key found is revoked on the spot: Seam knows it is its own.
+import crypto from 'node:crypto'
+import { isText } from './textdiff.js'
+
+export const MODES = ['refuse', 'warn', 'off']
+export const MAX_SCAN = 2 * 1024 * 1024
+
+/** Each rule: an id, what it is in words, and its pattern (group 1, when there is one, is the secret). */
+export const RULES = [
+  { id: 'aws_access_key', what: 'an AWS access key', re: /\b((?:AKIA|ASIA)[0-9A-Z]{16})\b/g },
+  { id: 'github_token', what: 'a GitHub token', re: /\b(gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{50,})\b/g },
+  { id: 'api_key_sk', what: 'an API secret key (sk-…)', re: /\b(sk-(?:proj-|ant-)?[A-Za-z0-9_-]{20,})/g },
+  { id: 'slack_token', what: 'a Slack token', re: /\b(xox[abprs]-[A-Za-z0-9-]{10,})/g },
+  { id: 'private_key', what: 'a private key', re: /(-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----)/g },
+  { id: 'supabase_service_role', what: 'a Supabase service role key', re: /\b(eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})/g, check: (v) => /service_role/.test(jwtPayload(v)) },
+  // Random key bodies, not names that happen to start the same way (qa_access_key_hash).
+  { id: 'quilt_key', what: 'a Quilt key', re: /\b(q[arskt]_[A-Za-z0-9_-]{20,})/g, check: (v) => entropy(v.slice(3)) >= 3.5 },
+  { id: 'seam_key', what: 'a Seam key', re: /\b((?:sqt|ssk|sak|sok|sor|sip)_[A-Za-z0-9_-]{20,})/g, check: (v) => entropy(v.slice(4)) >= 3.5 }
+]
+const ASSIGN = /\b[\w.-]*(?:secret|token|passw(?:or)?d|api[_-]?key|private[_-]?key|access[_-]?key|credential)[\w.-]*["']?\s*[:=]\s*["']?([A-Za-z0-9+/_=.-]{20,})/gi
+
+function jwtPayload (jwt) { try { return Buffer.from(jwt.split('.')[1], 'base64url').toString('utf8') } catch { return '' } }
+
+/** Shannon entropy in bits per character. */
+export function entropy (s) {
+  const n = new Map()
+  for (const c of s) n.set(c, (n.get(c) || 0) + 1)
+  let h = 0
+  for (const k of n.values()) { const p = k / s.length; h -= p * Math.log2(p) }
+  return h
+}
+
+const findingId = (rule, path, value) => 'sf_' + crypto.createHash('sha256').update(`${rule}\0${path}\0${value}`).digest('hex').slice(0, 12)
+
+/** Whether a path is a .env file (refused outright; .env.example is a template, not secrets). */
+export const isEnvFile = (path) => { const b = path.split('/').pop(); return (b === '.env' || b.startsWith('.env.')) && b !== '.env.example' }
+
+/**
+ * The findings in one file: [{ id, rule, what, path, line, allowable }], and the Seam keys seen
+ * (values, so the caller can revoke them; they never go into an answer).
+ */
+export function scanFile (path, bytes) {
+  const findings = []
+  const seamKeys = []
+  if (isEnvFile(path)) findings.push({ id: findingId('env_file', path, ''), rule: 'env_file', what: 'a .env file', path, line: null, allowable: false })
+  if (!bytes || bytes.length > MAX_SCAN || !isText(bytes)) return { findings, seamKeys }
+  const lines = bytes.toString('utf8').split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const text = lines[i]
+    if (text.length > 10000) continue
+    const seen = new Set()
+    for (const r of RULES) {
+      r.re.lastIndex = 0
+      for (let m = r.re.exec(text); m; m = r.re.exec(text)) {
+        const v = m[1] || m[0]
+        if (r.check && !r.check(v)) continue
+        seen.add(v)
+        if (r.id === 'seam_key') seamKeys.push(v)
+        findings.push({ id: findingId(r.id, path, v), rule: r.id, what: r.what, path, line: i + 1, allowable: true })
+      }
+    }
+    ASSIGN.lastIndex = 0
+    for (let m = ASSIGN.exec(text); m; m = ASSIGN.exec(text)) {
+      const v = m[1]
+      if (seen.has(v) || entropy(v) < 4) continue
+      findings.push({ id: findingId('high_entropy', path, v), rule: 'high_entropy', what: 'a high-entropy value assigned to a secret-sounding name', path, line: i + 1, allowable: true })
+    }
+  }
+  return { findings, seamKeys }
+}
+
+/** The findings in a commit's new files ([{ path, bytes }]), with the Seam keys among them. */
+export function scanFiles (files) {
+  const findings = []
+  const seamKeys = []
+  for (const f of files) { const r = scanFile(f.path, f.bytes); findings.push(...r.findings); seamKeys.push(...r.seamKeys) }
+  return { findings, seamKeys }
+}
+
+/** One line per finding, never the value. */
+export const describeFinding = (f) => `${f.path}${f.line ? `:${f.line}` : ''}: ${f.what} (${f.id})`

package/lib/quilts/signing.js

@@ -38,8 +38,11 @@ const keyObject = (raw) => crypto.createPublicKey({ key: Buffer.concat([SPKI_PRE
 /** A key's id: `ed25519:` and the first 16 hex of the sha256 of its raw bytes. */
 export const keyId = (raw) => 'ed25519:' + crypto.createHash('sha256').update(Buffer.from(raw, 'base64')).digest('hex').slice(0, 16)
 
-export function verifySignature (raw, commitId, signature) {
-  try { return crypto.verify(null, Buffer.from(signedText(commitId)), keyObject(raw), Buffer.from(String(signature), 'base64')) } catch { return false }
+export function verifySignature (raw, commitId, signature) { return verifyText(raw, signedText(commitId), signature) }
+
+/** Whether `signature` is `raw`'s over `text` (a commit, or a policy confirmation, 11.4). */
+export function verifyText (raw, text, signature) {
+  try { return crypto.verify(null, Buffer.from(text), keyObject(raw), Buffer.from(String(signature), 'base64')) } catch { return false }
 }
 
 // ---- the client side: the private key on this computer ----
@@ -62,7 +65,8 @@ export function localKey (file = signingKeyFile()) {
   const priv = crypto.createPrivateKey(fs.readFileSync(file))
   const pub = crypto.createPublicKey(priv).export({ format: 'pem', type: 'spki' })
   const raw = rawPublicKey(pub)
-  return { public_key: pub, key: keyId(raw), sign: (commitId) => crypto.sign(null, Buffer.from(signedText(commitId)), priv).toString('base64') }
+  const signText = (text) => crypto.sign(null, Buffer.from(text), priv).toString('base64')
+  return { public_key: pub, key: keyId(raw), sign: (commitId) => signText(signedText(commitId)), signText }
 }
 
 /** Signs a commit with this computer's key and sends the signature. */

package/lib/quilts/tarball.js

@@ -0,0 +1,107 @@
+// One commit as a tarball (14, "One commit as a tarball"): the bytes are a pure function of the
+// entries and the time given. Entries sorted by path, mode from the tree entry (0644, 0755, or a
+// symlink), uid and gid 0, no user or group names, one mtime for every entry, a pax header only
+// where ustar cannot hold a path or a size, and gzip with no name and no timestamp.
+import zlib from 'node:zlib'
+
+const BLOCK = 512
+
+function octal (n, width) {
+  return n.toString(8).padStart(width - 1, '0') + '\0'
+}
+
+function header ({ name, size, mode, type, link = '', mtime }) {
+  const b = Buffer.alloc(BLOCK)
+  b.write(name, 0, 100, 'utf8')
+  b.write(octal(mode, 8), 100, 'ascii')
+  b.write(octal(0, 8), 108, 'ascii')
+  b.write(octal(0, 8), 116, 'ascii')
+  b.write(octal(size, 12), 124, 'ascii')
+  b.write(octal(mtime, 12), 136, 'ascii')
+  b.fill(' ', 148, 156)
+  b.write(type, 156, 'ascii')
+  b.write(link, 157, 100, 'utf8')
+  b.write('ustar\0', 257, 'ascii')
+  b.write('00', 263, 'ascii')
+  let sum = 0
+  for (const x of b) sum += x
+  b.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 'ascii')
+  return b
+}
+
+const pad = (n) => Buffer.alloc((BLOCK - (n % BLOCK)) % BLOCK)
+
+// A pax record: "<len> <key>=<value>\n", where len counts the whole record including itself.
+function paxRecord (key, value) {
+  const body = ` ${key}=${value}\n`
+  let len = Buffer.byteLength(body) + 1
+  while (String(len).length + Buffer.byteLength(body) !== len) len = String(len).length + Buffer.byteLength(body)
+  return `${len}${body}`
+}
+
+const fits = (s) => Buffer.byteLength(s) <= 100 && /^[\x20-\x7e]*$/.test(s)
+const MAX_USTAR_SIZE = 8 ** 11 - 1
+
+/**
+ * entries: [{ path, mode: 'file' | 'exec' | 'symlink', bytes }] (symlink: bytes are the target).
+ * mtime: seconds. Returns the .tar.gz as a Buffer.
+ */
+export function tarGz (entries, { mtime = 0 } = {}) {
+  // gzip writes no name and, with no mtime given, a zero timestamp: the same bytes every time.
+  return zlib.gzipSync(tar(entries, { mtime }), { level: 9 })
+}
+
+/** The same entries as a plain .tar (the whole-quilt archive: its files are compressed already). */
+export function tar (entries, { mtime = 0 } = {}) {
+  const parts = []
+  const sorted = [...entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  for (const e of sorted) {
+    const link = e.mode === 'symlink' ? Buffer.from(e.bytes).toString('utf8') : ''
+    const size = e.mode === 'symlink' ? 0 : e.bytes.length
+    const pax = []
+    if (!fits(e.path)) pax.push(paxRecord('path', e.path))
+    if (link && !fits(link)) pax.push(paxRecord('linkpath', link))
+    if (size > MAX_USTAR_SIZE) pax.push(paxRecord('size', String(size)))
+    if (pax.length) {
+      const body = Buffer.from(pax.join(''), 'utf8')
+      parts.push(header({ name: 'PaxHeader', size: body.length, mode: 0o644, type: 'x', mtime }), body, pad(body.length))
+    }
+    const name = fits(e.path) ? e.path : Buffer.from(e.path).subarray(0, 100).toString('latin1').replace(/[^\x20-\x7e]/g, '_')
+    parts.push(header({
+      name,
+      size: size > MAX_USTAR_SIZE ? 0 : size,
+      mode: e.mode === 'exec' ? 0o755 : e.mode === 'symlink' ? 0o777 : 0o644,
+      type: e.mode === 'symlink' ? '2' : '0',
+      link: fits(link) ? link : '',
+      mtime
+    }))
+    if (size) parts.push(Buffer.from(e.bytes), pad(size))
+  }
+  parts.push(Buffer.alloc(BLOCK * 2))
+  return Buffer.concat(parts)
+}
+
+/** Reads a plain .tar back: [{ path, bytes }] for regular files (ustar with pax path and size). */
+export function untar (buf) {
+  const out = []
+  let pax = {}
+  for (let at = 0; at + BLOCK <= buf.length;) {
+    const h = buf.subarray(at, at + BLOCK)
+    if (h.every((x) => x === 0)) break
+    const field = (from, len) => h.subarray(from, from + len).toString('utf8').replace(/\0.*$/s, '')
+    const type = field(156, 1) || '0'
+    let size = parseInt(field(124, 12).trim() || '0', 8)
+    if (pax.size) size = Number(pax.size)
+    const body = buf.subarray(at + BLOCK, at + BLOCK + size)
+    if (body.length !== size) throw new Error('the tar ends inside an entry')
+    at += BLOCK + size + ((BLOCK - (size % BLOCK)) % BLOCK)
+    if (type === 'x') {
+      pax = {}
+      for (const rec of body.toString('utf8').split('\n')) { const m = /^\d+ ([^=]+)=(.*)$/s.exec(rec); if (m) pax[m[1]] = m[2] }
+      continue
+    }
+    if (type === '0') out.push({ path: pax.path || field(0, 100), bytes: Buffer.from(body) })
+    pax = {}
+  }
+  return out
+}

package/lib/quilts/textdiff.js

@@ -32,21 +32,23 @@ export function hunks (a, b) {
 }
 
 /** +added −removed counts between two texts. */
-export function lineStat (a, b) {
+export function lineStat (a, b, { normalize } = {}) {
   let add = 0; let del = 0
-  for (const h of hunks(splitLines(a), splitLines(b))) { del += h.a[1]; add += h.b[1] }
+  const [la, lb] = [splitLines(a), splitLines(b)]
+  for (const h of normalize ? hunks(la.map(normalize), lb.map(normalize)) : hunks(la, lb)) { del += h.a[1]; add += h.b[1] }
   return { add, del }
 }
 
 /**
  * A unified diff of one file (git's format, 3 lines of context). `before`/`after` are strings,
- * or null when the file is added or deleted.
+ * or null when the file is added or deleted. `normalize` maps a line to what it compares as.
  */
-export function unified (path, before, after, { context = 3, fromPath = path } = {}) {
+export function unified (path, before, after, { context = 3, fromPath = path, normalize } = {}) {
   const a = splitLines(before ?? '')
   const b = splitLines(after ?? '')
   const head = [`--- ${before == null ? '/dev/null' : `a/${fromPath}`}`, `+++ ${after == null ? '/dev/null' : `b/${path}`}`]
-  const hs = hunks(a, b)
+  // normalize (ignore_whitespace): lines compare by it; the hunks still show the lines as they are.
+  const hs = normalize ? hunks(a.map(normalize), b.map(normalize)) : hunks(a, b)
   if (!hs.length) return ''
   const out = [...head]
   // Group hunks whose context overlaps.