@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/resources/vendor.js

@@ -0,0 +1,296 @@
+import { randomBytes } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { INTEGRITY_RE, sha256 } from '../digest.js';
+import { SitefileError, isSitefileError } from '../errors.js';
+import { MEDIA, parseManifest } from '../oci.js';
+import { selectPlatform } from '../registry-ops.js';
+import { extractArchive } from './archive.js';
+/**
+ * The vendor directory written by `sitefile vendor` (issue #96): every remote input's bytes under
+ * content-addressed names, plus a manifest that maps URLs and image tags to them.
+ *
+ *   <dir>/manifest.json          {"version":1,"resources":{url:{integrity,size,resolved}},"images":{ref:{digest,platform,manifest}}}
+ *   <dir>/blobs/sha256/<hex>     IMPORT bodies and BASE image blobs (index, manifest, config, layers)
+ *
+ * Builds prefer these copies over the network and verify each one against its digest (and, as for any
+ * fetch, against INTEGRITY and Sitefile.lock). Nothing secret is written: URLs with credentials are
+ * rejected before any fetch, and registry tokens or passwords never leave memory.
+ */
+export const DEFAULT_VENDOR_DIR = 'vendor/sitefile';
+export const VENDOR_MANIFEST = 'manifest.json';
+/** Validate a vendor directory: a relative path inside the build context. Returns it normalized (POSIX, no trailing slash). */
+export function vendorDirRel(input) {
+    const n = path.posix.normalize(input).replace(/\/+$/, '');
+    if (input === '' || path.posix.isAbsolute(input) || input.includes('\\') || n === '.' || n === '..' || n.startsWith('../')) {
+        throw new SitefileError('E_USAGE', `--vendor-dir expects a relative path inside the build context, got '${input}'`);
+    }
+    return n;
+}
+const blobRel = (dir, digest) => `${dir}/blobs/sha256/${digest.slice('sha256:'.length)}`;
+/**
+ * The vendor directory a build uses: `explicit` (which must have a manifest), else the default one if
+ * its manifest exists, else none.
+ */
+export async function findVendorDir(contextReal, explicit) {
+    const dir = vendorDirRel(explicit ?? DEFAULT_VENDOR_DIR);
+    const exists = await fs.stat(path.join(contextReal, ...dir.split('/'), VENDOR_MANIFEST)).then((st) => st.isFile(), () => false);
+    if (exists)
+        return dir;
+    if (explicit !== undefined) {
+        throw new SitefileError('E_NOT_FOUND', `vendor directory '${dir}' has no ${VENDOR_MANIFEST}; run 'sitefile vendor --vendor-dir ${dir}' first`);
+    }
+    return undefined;
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Parse and check a vendor manifest. Errors are E_VALIDATION naming the file. */
+export function parseVendorManifest(bytes, shown) {
+    const bad = (why) => new SitefileError('E_VALIDATION', `malformed vendor manifest ${shown}: ${why}`);
+    let data;
+    try {
+        data = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw bad('invalid JSON');
+    }
+    if (!isObject(data))
+        throw bad('expected a JSON object');
+    if (data.version !== 1)
+        throw bad(`unsupported version ${JSON.stringify(data.version) ?? 'undefined'} (expected 1)`);
+    const resources = {};
+    const images = {};
+    const rs = data.resources ?? {};
+    if (!isObject(rs))
+        throw bad('"resources" must be an object');
+    for (const [url, e] of Object.entries(rs)) {
+        if (!isObject(e) || typeof e.integrity !== 'string' || !INTEGRITY_RE.test(e.integrity) || typeof e.size !== 'number' || !Number.isSafeInteger(e.size) || e.size < 0 || typeof e.resolved !== 'string') {
+            throw bad(`entry for ${url} needs "integrity" (sha256:<64 hex>), "size" and "resolved"`);
+        }
+        resources[url] = { integrity: e.integrity, size: e.size, resolved: e.resolved };
+    }
+    const is = data.images ?? {};
+    if (!isObject(is))
+        throw bad('"images" must be an object');
+    for (const [ref, e] of Object.entries(is)) {
+        if (!isObject(e) || typeof e.digest !== 'string' || !INTEGRITY_RE.test(e.digest) || typeof e.platform !== 'string' || typeof e.manifest !== 'string' || !INTEGRITY_RE.test(e.manifest)) {
+            throw bad(`image entry for ${ref} needs "digest", "platform" and "manifest"`);
+        }
+        images[ref] = { digest: e.digest, platform: e.platform, manifest: e.manifest };
+    }
+    const git = {};
+    const gs = data.git ?? {};
+    if (!isObject(gs))
+        throw bad('"git" must be an object');
+    for (const [url, e] of Object.entries(gs)) {
+        if (!isObject(e) || typeof e.commit !== 'string' || !/^[0-9a-f]{40}$/.test(e.commit) || (e.kind !== 'tree' && e.kind !== 'file') ||
+            typeof e.integrity !== 'string' || !INTEGRITY_RE.test(e.integrity) || typeof e.size !== 'number' || !Number.isSafeInteger(e.size) || e.size < 0 ||
+            (e.kind === 'file' ? e.mode !== '644' && e.mode !== '755' : e.mode !== undefined)) {
+            throw bad(`git entry for ${url} needs "commit", "kind" (tree or file), "integrity", "size" (and "mode" for a file)`);
+        }
+        git[url] = { commit: e.commit, kind: e.kind, integrity: e.integrity, size: e.size, ...(e.kind === 'file' ? { mode: e.mode } : {}) };
+    }
+    return { version: 1, resources, images, ...(Object.keys(git).length ? { git } : {}) };
+}
+/** The manifest as `sitefile vendor` writes it: sorted keys, two-space indent, trailing newline. */
+export function serializeVendorManifest(m) {
+    const resources = {};
+    for (const url of Object.keys(m.resources).sort()) {
+        const e = m.resources[url];
+        resources[url] = { integrity: e.integrity, size: e.size, resolved: e.resolved };
+    }
+    const images = {};
+    for (const ref of Object.keys(m.images).sort()) {
+        const e = m.images[ref];
+        images[ref] = { digest: e.digest, platform: e.platform, manifest: e.manifest };
+    }
+    const git = {};
+    for (const url of Object.keys(m.git ?? {}).sort()) {
+        const e = m.git[url];
+        git[url] = { commit: e.commit, kind: e.kind, integrity: e.integrity, size: e.size, ...(e.mode !== undefined ? { mode: e.mode } : {}) };
+    }
+    return JSON.stringify({ version: 1, resources, images, ...(Object.keys(git).length ? { git } : {}) }, null, 2) + '\n';
+}
+function isIndex(bytes) {
+    try {
+        const j = JSON.parse(new TextDecoder().decode(bytes));
+        if (typeof j.mediaType === 'string')
+            return j.mediaType === MEDIA.index || j.mediaType === MEDIA.dockerList;
+        return Array.isArray(j.manifests);
+    }
+    catch {
+        return false;
+    }
+}
+/** A vendor directory opened through the build's sandboxed context reader. */
+export class Vendor {
+    dir;
+    local;
+    manifest;
+    constructor(
+    /** Context-relative directory. */
+    dir, local, manifest) {
+        this.dir = dir;
+        this.local = local;
+        this.manifest = manifest;
+    }
+    static async open(local, dir) {
+        const rel = `${dir}/${VENDOR_MANIFEST}`;
+        const f = await local.readFile(rel);
+        return new Vendor(dir, local, parseVendorManifest(f.bytes, rel));
+    }
+    resource(url) {
+        return Object.hasOwn(this.manifest.resources, url) ? this.manifest.resources[url] : undefined;
+    }
+    image(ref) {
+        return Object.hasOwn(this.manifest.images, ref) ? this.manifest.images[ref] : undefined;
+    }
+    git(url) {
+        const g = this.manifest.git;
+        return g && Object.hasOwn(g, url) ? g[url] : undefined;
+    }
+    /** The vendored content of a Git IMPORT, verified against its digest. */
+    async readGit(url, e, basename, limits, span) {
+        const bytes = await this.readBlob(e.integrity, `vendored copy of '${url}'`, span);
+        if (e.kind === 'file')
+            return { kind: 'file', bytes, mode: e.mode === '755' ? 0o755 : 0o644, basename };
+        const tree = await extractArchive(bytes, `vendored copy of '${url}'`, limits, span);
+        return { kind: 'tree', files: tree.entries().map(([p, n]) => [p, { bytes: n.bytes, mode: n.mode }]) };
+    }
+    /** The vendored body of `url`, verified against its digest. */
+    async readResource(url, e, span) {
+        return { bytes: await this.readBlob(e.integrity, `vendored copy of '${url}'`, span), finalUrl: e.resolved };
+    }
+    async readBlob(digest, what, span) {
+        const rel = blobRel(this.dir, digest);
+        const { bytes } = await this.local.readFile(rel, span);
+        const got = sha256(bytes);
+        if (got !== digest) {
+            throw new SitefileError('E_INTEGRITY', `${what} (${rel}) is corrupt: expected ${digest}, got ${got}; run 'sitefile vendor' again`, span);
+        }
+        return bytes;
+    }
+    async hasBlob(digest) {
+        try {
+            return (await this.local.stat(blobRel(this.dir, digest))) === 'file';
+        }
+        catch (e) {
+            if (isSitefileError(e, 'E_NOT_FOUND'))
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * Copy the vendored blobs of the image `rootDigest` (for `platform`) into the store, each verified,
+     * so pulling it finds everything locally. Stops quietly at the first blob that is not vendored: the
+     * pull then fetches the rest from the registry.
+     */
+    async seedStore(store, rootDigest, platform) {
+        if (!(await this.hasBlob(rootDigest)))
+            return;
+        const root = await this.readBlob(rootDigest, 'vendored image blob');
+        await store.putSmallBlob(root);
+        let manifest = root;
+        if (isIndex(root)) {
+            let d;
+            try {
+                d = selectPlatform(root, platform);
+            }
+            catch {
+                return;
+            }
+            if (!(await this.hasBlob(d.digest)))
+                return;
+            manifest = await this.readBlob(d.digest, 'vendored image blob');
+            await store.putSmallBlob(manifest);
+        }
+        let parsed;
+        try {
+            parsed = parseManifest(manifest);
+        }
+        catch {
+            return;
+        }
+        for (const d of [parsed.config, ...parsed.layers]) {
+            if (await store.hasBlob(d.digest, d.size))
+                continue;
+            if (!(await this.hasBlob(d.digest)))
+                return;
+            const bytes = await this.readBlob(d.digest, 'vendored image blob');
+            await store.importBlob(d.digest, d.size, (async function* () {
+                yield bytes;
+            })());
+        }
+    }
+}
+/** The nearest existing ancestor's real path, with the missing tail appended. */
+async function realpathLoose(p) {
+    const tail = [];
+    let cur = p;
+    for (;;) {
+        try {
+            return path.join(await fs.realpath(cur), ...tail.reverse());
+        }
+        catch {
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return p;
+            tail.push(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+const inside = (root, real) => real.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+/**
+ * Replace `<contextReal>/<dir>` with a vendor directory holding `manifestText` and `blobs`: written to a
+ * temporary sibling, then swapped in. Refuses a directory that resolves outside the context, a symlink,
+ * and an existing directory that is not a vendor directory (no manifest.json).
+ */
+export async function writeVendorDir(contextReal, dir, manifestText, blobs) {
+    const target = path.join(contextReal, ...dir.split('/'));
+    const parent = path.dirname(target);
+    if (!inside(contextReal, await realpathLoose(target))) {
+        throw new SitefileError('E_PATH_ESCAPE', `vendor directory '${dir}' resolves outside the build context`);
+    }
+    const st = await fs.lstat(target).catch(() => undefined);
+    if (st?.isSymbolicLink())
+        throw new SitefileError('E_EXPORT_UNSAFE', `vendor directory '${dir}' is a symlink; refusing to replace it`);
+    if (st && !st.isDirectory())
+        throw new SitefileError('E_EXPORT_UNSAFE', `vendor directory '${dir}' exists and is not a directory`);
+    if (st) {
+        const names = await fs.readdir(target);
+        if (names.length > 0 && !names.includes(VENDOR_MANIFEST)) {
+            throw new SitefileError('E_EXPORT_UNSAFE', `'${dir}' exists and is not a sitefile vendor directory (no ${VENDOR_MANIFEST}); remove it or choose another --vendor-dir`);
+        }
+    }
+    await fs.mkdir(parent, { recursive: true }).catch((e) => {
+        throw new SitefileError('E_EXPORT', `cannot write vendor directory '${dir}': ${e.message}`, undefined, { cause: e });
+    });
+    const parentReal = await fs.realpath(parent);
+    if (!inside(contextReal, parentReal) && parentReal !== contextReal) {
+        throw new SitefileError('E_PATH_ESCAPE', `vendor directory '${dir}' resolves outside the build context`);
+    }
+    const tag = `${process.pid}-${randomBytes(4).toString('hex')}`;
+    const tmp = path.join(parent, `.${path.basename(target)}.sitefile-vendor-tmp-${tag}`);
+    const old = path.join(parent, `.${path.basename(target)}.sitefile-vendor-old-${tag}`);
+    try {
+        await fs.mkdir(path.join(tmp, 'blobs', 'sha256'), { recursive: true });
+        for (const [digest, bytes] of [...blobs].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+            await fs.writeFile(path.join(tmp, 'blobs', 'sha256', digest.slice('sha256:'.length)), bytes);
+        }
+        await fs.writeFile(path.join(tmp, VENDOR_MANIFEST), manifestText);
+        if (st)
+            await fs.rename(target, old);
+        await fs.rename(tmp, target);
+    }
+    catch (e) {
+        await fs.rm(tmp, { recursive: true, force: true });
+        if (st && !(await fs.lstat(target).catch(() => undefined)))
+            await fs.rename(old, target).catch(() => undefined);
+        throw new SitefileError('E_EXPORT', `cannot write vendor directory '${dir}': ${e.message}`, undefined, { cause: e });
+    }
+    await fs.rm(old, { recursive: true, force: true });
+    return target;
+}
+//# sourceMappingURL=vendor.js.map

package/lib/src/resources/wbn-reader.d.ts

@@ -0,0 +1,44 @@
+import { type SourceSpan } from '../errors.js';
+import { Tree } from '../tree.js';
+import type { ArchiveLimits } from './types.js';
+/**
+ * Reader for unsigned Web Bundles, formats b1 and b2 (the WICG
+ * "draft-yasskin-wpack-bundled-exchanges" lineage and
+ * draft-ietf-wpack-bundled-responses). Layouts, as implemented by the WICG Go
+ * reference reader (go/bundle/decoder.go):
+ *
+ *   b2: array(5) [ magic, version "b2\0\0", section-lengths, sections, length ]
+ *   b1: array(6) [ magic, version "b1\0\0", primary URL (text), section-lengths, sections, length ]
+ *
+ * section-lengths is a byte string holding a CBOR array of (name, length) pairs;
+ * `sections` is an array with one item per pair; `responses` must be last. The
+ * trailing length is an 8-byte big-endian byte string equal to the bundle size.
+ * index = { url => value }: b2 value = [offset, length]; b1 value =
+ * [variants-value bstr, offset, length, ...] (empty variants-value: exactly one
+ * location). Offsets are counted from the first byte of the responses section's
+ * CBOR encoding. A response is array(2) [ bstr(CBOR map of bstr -> bstr incl.
+ * ":status"), body bstr ].
+ *
+ * Signatures, manifest and any unknown section are length-checked and ignored;
+ * nothing is verified or executed.
+ */
+export interface BundleEntry {
+    url: string;
+    status: number;
+    headers: Record<string, string>;
+    body: Uint8Array;
+}
+export interface WebBundle {
+    version: 'b1' | 'b2';
+    primaryUrl: string | undefined;
+    entries: BundleEntry[];
+}
+export declare function isWebBundle(bytes: Uint8Array): boolean;
+export declare function readWebBundle(bytes: Uint8Array, origin: string, limits: ArchiveLimits, span?: SourceSpan): WebBundle;
+/**
+ * Turn a bundle into a Tree. Only status-200 entries become files. When all
+ * such URLs share one origin the artifact path is the URL path; otherwise each
+ * path is prefixed with `/<host[:port]>`. A path ending in `/` maps to
+ * `<path>index.html`; segments are percent-decoded.
+ */
+export declare function webBundleToTree(bundle: WebBundle, origin: string, span?: SourceSpan): Tree;

package/lib/src/resources/wbn-reader.js

@@ -0,0 +1,302 @@
+import { SitefileError } from '../errors.js';
+import { normalizeVirtual } from '../paths.js';
+import { makeFile, Tree } from '../tree.js';
+import { CborError, decodeCbor, readCborHead } from '../cbor.js';
+const MAGIC = [0xf0, 0x9f, 0x8c, 0x90, 0xf0, 0x9f, 0x93, 0xa6];
+/** Magic prefix: array head, bstr(8) head, then the 8 magic bytes. */
+const HEAD_LEN = 10;
+/** The trailing length field: bstr(8) head + 8 bytes. */
+const TAIL_LEN = 9;
+const MAX_SECTION_LENGTHS = 8192;
+function hasMagic(b) {
+    if (b.length < HEAD_LEN || (b[0] !== 0x85 && b[0] !== 0x86) || b[1] !== 0x48)
+        return false;
+    return MAGIC.every((x, i) => b[2 + i] === x);
+}
+export function isWebBundle(bytes) {
+    return hasMagic(bytes);
+}
+export function readWebBundle(bytes, origin, limits, span) {
+    const bad = (why) => new SitefileError('E_ARCHIVE', `${origin}: web bundle: ${why}`, span);
+    try {
+        return read(bytes, origin, limits, span, bad);
+    }
+    catch (e) {
+        if (e instanceof CborError)
+            throw bad(`malformed CBOR: ${e.message}`);
+        throw e;
+    }
+}
+function read(bytes, origin, limits, span, bad) {
+    if (!hasMagic(bytes))
+        throw bad('bad magic bytes');
+    if (bytes.length < HEAD_LEN + 5)
+        throw bad('truncated header');
+    const isB1 = bytes[0] === 0x86;
+    if (bytes[HEAD_LEN] !== 0x44 || bytes[HEAD_LEN + 1] !== 0x62 || bytes[HEAD_LEN + 3] !== 0 || bytes[HEAD_LEN + 4] !== 0) {
+        throw bad('unrecognized version field');
+    }
+    const verDigit = bytes[HEAD_LEN + 2];
+    if (verDigit !== (isB1 ? 0x31 : 0x32)) {
+        throw bad(verDigit === 0x31 || verDigit === 0x32 ? 'header does not match its version' : 'unsupported version (expected b1 or b2)');
+    }
+    const version = isB1 ? 'b1' : 'b2';
+    let pos = HEAD_LEN + 5;
+    let primaryUrl;
+    if (isB1) {
+        const p = decodeCbor(bytes.subarray(pos), { maxItems: 1 });
+        if (typeof p.value !== 'string')
+            throw bad('primary URL is not a text string');
+        primaryUrl = p.value;
+        pos += p.end;
+    }
+    // section-lengths
+    const slHead = readCborHead(bytes, pos);
+    if (slHead.major !== 2 || typeof slHead.arg !== 'number')
+        throw bad('section-lengths is not a byte string');
+    if (slHead.arg >= MAX_SECTION_LENGTHS)
+        throw bad('section-lengths is too long');
+    if (slHead.next + slHead.arg > bytes.length)
+        throw bad('truncated section-lengths');
+    const sl = decodeCbor(bytes.subarray(slHead.next, slHead.next + slHead.arg), { maxItems: MAX_SECTION_LENGTHS });
+    if (!Array.isArray(sl.value) || sl.end !== slHead.arg || sl.value.length % 2 !== 0) {
+        throw bad('malformed section-lengths');
+    }
+    const sections = [];
+    pos = slHead.next + slHead.arg;
+    const secHead = readCborHead(bytes, pos);
+    if (secHead.major !== 4)
+        throw bad('sections is not an array');
+    if (secHead.arg !== sl.value.length / 2)
+        throw bad(`section-lengths declares ${sl.value.length / 2} sections but ${secHead.arg} are present`);
+    let cursor = secHead.next;
+    const seen = new Set();
+    for (let i = 0; i < sl.value.length; i += 2) {
+        const name = sl.value[i];
+        const length = sl.value[i + 1];
+        // CBOR unsigned integers only: a negative length would move the cursor backwards.
+        if (typeof name !== 'string' || typeof length !== 'number' || length < 0)
+            throw bad('malformed section-lengths entry');
+        if (seen.has(name))
+            throw bad(`duplicate section '${name}'`);
+        seen.add(name);
+        sections.push({ name, length, start: cursor });
+        cursor += length;
+        if (cursor > bytes.length - TAIL_LEN)
+            throw bad(`section '${name}' extends past the end of the bundle`);
+    }
+    const last = sections[sections.length - 1];
+    if (!last || last.name !== 'responses')
+        throw bad("the last section must be 'responses'");
+    // trailing length
+    if (cursor + TAIL_LEN !== bytes.length)
+        throw bad('section lengths do not add up to the bundle size');
+    if (bytes[cursor] !== 0x48)
+        throw bad('malformed trailing length field');
+    const declared = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getBigUint64(cursor + 1);
+    if (declared !== BigInt(bytes.length))
+        throw bad(`length field says ${declared} bytes but the bundle is ${bytes.length}`);
+    const section = (name) => {
+        const s = sections.find((x) => x.name === name);
+        return s && bytes.subarray(s.start, s.start + s.length);
+    };
+    const primarySection = section('primary');
+    if (primarySection) {
+        const p = decodeCbor(primarySection, { maxItems: 1 });
+        if (typeof p.value !== 'string' || p.end !== primarySection.length)
+            throw bad("malformed 'primary' section");
+        primaryUrl = p.value;
+    }
+    if (primaryUrl !== undefined) {
+        try {
+            new URL(primaryUrl);
+        }
+        catch {
+            throw bad(`primary URL '${primaryUrl}' is not an absolute URL`);
+        }
+    }
+    const indexSection = section('index');
+    if (!indexSection)
+        throw bad("missing 'index' section");
+    const responses = last;
+    const indexHead = readCborHead(indexSection, 0);
+    if (indexHead.major !== 5)
+        throw bad('index is not a map');
+    if (typeof indexHead.arg !== 'number' || indexHead.arg > limits.maxEntries) {
+        throw new SitefileError('E_ARCHIVE_LIMIT', `${origin}: web bundle has more than ${limits.maxEntries} entries`, span);
+    }
+    const index = decodeCbor(indexSection);
+    if (!(index.value instanceof Map) || index.end !== indexSection.length)
+        throw bad('malformed index section');
+    const parsed = new Map();
+    const entries = [];
+    let total = 0;
+    for (const [url, value] of index.value) {
+        if (typeof url !== 'string')
+            throw bad('index key is not a text string');
+        if (!Array.isArray(value))
+            throw bad(`index value for '${url}' is not an array`);
+        let loc;
+        if (isB1) {
+            const variants = value[0];
+            if (!(variants instanceof Uint8Array))
+                throw bad(`index value for '${url}' has no variants-value`);
+            if (value.length !== 3) {
+                throw bad(value.length % 2 === 1 && value.length > 3
+                    ? `'${url}' has multiple variants, which are not supported`
+                    : `index value for '${url}' has an invalid size`);
+            }
+            loc = value.slice(1);
+        }
+        else {
+            if (value.length !== 2)
+                throw bad(`index value for '${url}' must be [offset, length]`);
+            loc = value;
+        }
+        const [off, len] = loc;
+        // A negative offset or length (CBOR major type 1) would read outside the responses section.
+        if (typeof off !== 'number' || typeof len !== 'number' || off < 0 || len < 0) {
+            throw bad(`index offset/length for '${url}' is not an unsigned integer`);
+        }
+        if (off + len > responses.length)
+            throw bad(`response for '${url}' lies outside the responses section`);
+        const key = `${off}:${len}`;
+        let r = parsed.get(key);
+        if (!r) {
+            r = parseResponse(bytes.subarray(responses.start + off, responses.start + off + len), url, bad);
+            parsed.set(key, r);
+        }
+        total += r.body.byteLength;
+        if (total > limits.maxTotalBytes) {
+            throw new SitefileError('E_ARCHIVE_LIMIT', `${origin}: web bundle expands beyond ${limits.maxTotalBytes} bytes`, span);
+        }
+        entries.push({ url, status: r.status, headers: r.headers, body: r.body });
+    }
+    entries.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+    return { version, primaryUrl, entries };
+}
+const asciiOf = (b) => {
+    for (const x of b)
+        if (x > 0x7e || x < 0x20)
+            return undefined;
+    return Buffer.from(b).toString('latin1');
+};
+function parseResponse(b, url, bad) {
+    const r = decodeCbor(b, { maxItems: 16 });
+    if (!Array.isArray(r.value) || r.end !== b.length || r.value.length !== 2)
+        throw bad(`response for '${url}' is not [headers, body]`);
+    const [hdrBytes, body] = r.value;
+    if (!(hdrBytes instanceof Uint8Array) || !(body instanceof Uint8Array))
+        throw bad(`response for '${url}' must hold two byte strings`);
+    const h = decodeCbor(hdrBytes, { maxItems: 100_000 });
+    if (!(h.value instanceof Map) || h.end !== hdrBytes.length)
+        throw bad(`response headers for '${url}' are not a CBOR map`);
+    let status;
+    const headers = [];
+    for (const [k, v] of h.value) {
+        if (!(k instanceof Uint8Array) || !(v instanceof Uint8Array))
+            throw bad(`response headers for '${url}' must map byte strings to byte strings`);
+        const name = asciiOf(k);
+        const value = asciiOf(v);
+        if (name === undefined || value === undefined)
+            throw bad(`non-ASCII response header for '${url}'`);
+        if (name !== name.toLowerCase())
+            throw bad(`response header '${name}' for '${url}' is not lower-case`);
+        if (name.startsWith(':')) {
+            if (name !== ':status')
+                throw bad(`unexpected pseudo-header '${name}' for '${url}'`);
+            if (!/^\d{3}$/.test(value))
+                throw bad(`invalid :status '${value}' for '${url}'`);
+            status = Number(value);
+        }
+        else {
+            headers.push([name, value]);
+        }
+    }
+    if (status === undefined)
+        throw bad(`response for '${url}' has no :status`);
+    return { status, headers: Object.fromEntries(headers), body };
+}
+// --------------------------------------------------------------- to a Tree
+/**
+ * Turn a bundle into a Tree. Only status-200 entries become files. When all
+ * such URLs share one origin the artifact path is the URL path; otherwise each
+ * path is prefixed with `/<host[:port]>`. A path ending in `/` maps to
+ * `<path>index.html`; segments are percent-decoded.
+ */
+export function webBundleToTree(bundle, origin, span) {
+    const unsafe = (url, why) => new SitefileError('E_ARCHIVE_UNSAFE', `${origin}: unsafe web bundle URL '${url.replace(/\0/g, '\\0')}': ${why}`, span);
+    const items = [];
+    for (const entry of bundle.entries) {
+        if (entry.status !== 200)
+            continue;
+        const m = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)([^?#]*)(\?[^#]*)?(#.*)?$/.exec(entry.url);
+        if (!m)
+            throw unsafe(entry.url, 'not an absolute http(s) URL');
+        const scheme = m[1].toLowerCase();
+        if (scheme !== 'http' && scheme !== 'https')
+            throw unsafe(entry.url, `scheme '${scheme}:' is not allowed`);
+        if (m[5] !== undefined)
+            throw unsafe(entry.url, 'URL has a fragment');
+        if (m[2].includes('@'))
+            throw unsafe(entry.url, 'URL has credentials');
+        let u;
+        try {
+            u = new URL(`${scheme}://${m[2]}/`);
+        }
+        catch {
+            throw unsafe(entry.url, 'invalid host');
+        }
+        const rawPath = m[3] === '' ? '/' : m[3];
+        if (rawPath.includes('\\'))
+            throw unsafe(entry.url, 'backslash in path');
+        if (!rawPath.startsWith('/'))
+            throw unsafe(entry.url, 'invalid path');
+        const segs = rawPath.slice(1).split('/');
+        const trailing = segs[segs.length - 1] === '';
+        if (trailing)
+            segs.pop();
+        const decoded = [];
+        for (const s of segs) {
+            let d;
+            try {
+                d = decodeURIComponent(s);
+            }
+            catch {
+                throw unsafe(entry.url, 'invalid percent-encoding in path');
+            }
+            if (d === '')
+                throw unsafe(entry.url, 'empty path segment');
+            if (d === '.' || d === '..')
+                throw unsafe(entry.url, `'${d}' path segment`);
+            if (d.includes('\0'))
+                throw unsafe(entry.url, 'NUL byte in path');
+            if (d.includes('\\'))
+                throw unsafe(entry.url, 'backslash in path');
+            if (d.includes('/'))
+                throw unsafe(entry.url, 'encoded slash in path');
+            decoded.push(d);
+        }
+        if (trailing || decoded.length === 0)
+            decoded.push('index.html');
+        items.push({ entry, origin: `${scheme}://${u.host}`, host: u.host, path: '/' + decoded.join('/'), query: m[4] !== undefined });
+    }
+    const multi = new Set(items.map((i) => i.origin)).size > 1;
+    const files = new Map();
+    for (const it of items) {
+        const path = normalizeVirtual((multi ? `/${it.host}` : '') + it.path, span, 'web bundle URL path').path;
+        const prev = files.get(path);
+        if (prev && prev.url !== it.entry.url && (prev.query || it.query)) {
+            throw unsafe(it.entry.url, `its query string makes it collide with '${prev.url}' at '${path}'`);
+        }
+        if (prev) {
+            if (prev.node.digest !== makeFile(it.entry.body, '').digest) {
+                throw new SitefileError('E_CONFLICT', `${origin}: '${prev.url}' and '${it.entry.url}' both map to '${path}' with different content`, span);
+            }
+            continue;
+        }
+        files.set(path, { node: makeFile(it.entry.body, `${origin}:${it.entry.url}`), url: it.entry.url, query: it.query });
+    }
+    return Tree.fromFiles([...files].map(([p, f]) => [p, f.node]));
+}
+//# sourceMappingURL=wbn-reader.js.map

package/lib/src/schema.d.ts

@@ -0,0 +1,25 @@
+import { type SourceSpan } from './errors.js';
+export type SchemaType = 'string' | 'number' | 'boolean' | 'date' | 'list';
+type ItemType = Exclude<SchemaType, 'list'>;
+type EnumValue = string | number | boolean;
+export interface SchemaRule {
+    readonly key: string;
+    readonly type?: SchemaType;
+    readonly items?: ItemType;
+    readonly enum?: readonly EnumValue[];
+}
+/** A compiled schema; `label` names its file in messages. */
+export interface Schema {
+    readonly label: string;
+    readonly required: readonly string[];
+    readonly properties: readonly SchemaRule[];
+}
+/** Compile a parsed schema file. Errors are E_SCHEMA at `span` (the SCHEMA clause), prefixed with `what`. */
+export declare function compileSchema(value: unknown, label: string, what: string, span: SourceSpan): Schema;
+/**
+ * Check an import's value against a schema: each element of a list, or a single document. Every element must be
+ * an object (E_TYPE otherwise). The first mismatch fails with E_SCHEMA at `span`, naming the document (its `path`,
+ * or `#n` for the n-th element), the key, what was expected and what was found.
+ */
+export declare function checkSchema(value: unknown, schema: Schema, what: string, csv: boolean, span: SourceSpan): void;
+export {};