@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/archive-writers.js

@@ -0,0 +1,197 @@
+import { crc32, deflateRaw, gzip } from './deflate.js';
+import { SitefileError } from './errors.js';
+/** Read `SOURCE_DATE_EPOCH`; undefined if unset, E_USAGE if malformed. */
+export function sourceDateEpoch(env = process.env) {
+    const raw = env.SOURCE_DATE_EPOCH;
+    if (raw === undefined || raw === '')
+        return undefined;
+    if (!/^\d{1,12}$/.test(raw))
+        throw new SitefileError('E_USAGE', `SOURCE_DATE_EPOCH must be a non-negative integer, got '${raw}'`);
+    return Number(raw);
+}
+const enc = new TextEncoder();
+function entriesOf(tree) {
+    return tree.entries().map(([p, n]) => {
+        if (!p.startsWith('/') || p.endsWith('/') || p.includes('\0') || p.includes('\\') || p.split('/').some((s, i) => i > 0 && (s === '' || s === '.' || s === '..'))) {
+            throw new SitefileError('E_EXPORT', `invalid artifact path '${p}'`);
+        }
+        const name = p.slice(1);
+        return { name, nameBytes: enc.encode(name), bytes: n.bytes, mode: n.mode };
+    });
+}
+export { crc32 };
+// --------------------------------------------------------------------- zip
+const ZIP_MAX_ENTRIES = 0xffff;
+const ZIP_MAX = 0xffffffff;
+function dosDateTime(epoch) {
+    if (epoch === undefined)
+        return { time: 0, date: (0 << 9) | (1 << 5) | 1 }; // 1980-01-01 00:00:00
+    const d = new Date(Math.max(epoch, 315532800) * 1000); // clamp to 1980-01-01
+    const year = Math.min(d.getUTCFullYear(), 2107);
+    // Seconds are stored in 2-second units.
+    return {
+        time: (d.getUTCHours() << 11) | (d.getUTCMinutes() << 5) | (d.getUTCSeconds() >> 1),
+        date: ((year - 1980) << 9) | ((d.getUTCMonth() + 1) << 5) | d.getUTCDate(),
+    };
+}
+/** Zip (no zip64). Deflate when it shrinks the data, otherwise stored. */
+export function writeZip(tree, options = {}) {
+    const entries = entriesOf(tree);
+    if (entries.length > ZIP_MAX_ENTRIES) {
+        throw new SitefileError('E_EXPORT', `zip export supports at most ${ZIP_MAX_ENTRIES} entries (zip64 is not implemented); got ${entries.length}`);
+    }
+    const { time, date } = dosDateTime(options.epoch);
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    for (const e of entries) {
+        if (e.nameBytes.length > 0xffff)
+            throw new SitefileError('E_EXPORT', `zip entry name is too long (${e.nameBytes.length} bytes): '${e.name.slice(0, 60)}…'`);
+        const deflated = deflateRaw(e.bytes);
+        const stored = deflated.length >= e.bytes.length;
+        const data = stored ? e.bytes : deflated;
+        if (e.bytes.length > ZIP_MAX || data.length > ZIP_MAX) {
+            throw new SitefileError('E_EXPORT', `zip export does not support files of 4 GiB or more (zip64 is not implemented): '/${e.name}'`);
+        }
+        if (offset > ZIP_MAX)
+            throw new SitefileError('E_EXPORT', 'zip export does not support archives of 4 GiB or more (zip64 is not implemented)');
+        const method = stored ? 0 : 8;
+        const crc = crc32(e.bytes);
+        const lh = Buffer.alloc(30);
+        lh.writeUInt32LE(0x04034b50, 0);
+        lh.writeUInt16LE(20, 4); // version needed
+        lh.writeUInt16LE(0x0800, 6); // UTF-8 names
+        lh.writeUInt16LE(method, 8);
+        lh.writeUInt16LE(time, 10);
+        lh.writeUInt16LE(date, 12);
+        lh.writeUInt32LE(crc, 14);
+        lh.writeUInt32LE(data.length, 18);
+        lh.writeUInt32LE(e.bytes.length, 22);
+        lh.writeUInt16LE(e.nameBytes.length, 26);
+        lh.writeUInt16LE(0, 28);
+        const ch = Buffer.alloc(46);
+        ch.writeUInt32LE(0x02014b50, 0);
+        ch.writeUInt16LE((3 << 8) | 20, 4); // made by: Unix, spec 2.0
+        ch.writeUInt16LE(20, 6);
+        ch.writeUInt16LE(0x0800, 8);
+        ch.writeUInt16LE(method, 10);
+        ch.writeUInt16LE(time, 12);
+        ch.writeUInt16LE(date, 14);
+        ch.writeUInt32LE(crc, 16);
+        ch.writeUInt32LE(data.length, 20);
+        ch.writeUInt32LE(e.bytes.length, 24);
+        ch.writeUInt16LE(e.nameBytes.length, 28);
+        // extra, comment, disk number, internal attrs = 0
+        ch.writeUInt32LE(((0o100000 | e.mode) << 16) >>> 0, 38);
+        ch.writeUInt32LE(offset, 42);
+        chunks.push(lh, e.nameBytes, data);
+        central.push(ch, e.nameBytes);
+        offset += 30 + e.nameBytes.length + data.length;
+    }
+    const cdSize = central.reduce((n, c) => n + c.length, 0);
+    if (offset + cdSize > ZIP_MAX)
+        throw new SitefileError('E_EXPORT', 'zip export does not support archives of 4 GiB or more (zip64 is not implemented)');
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(cdSize, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...chunks, ...central, end]);
+}
+// --------------------------------------------------------------------- tar
+const BLOCK = 512;
+const TAR_MAX_SIZE = 8 ** 11 - 1; // 11 octal digits
+function putOctal(h, at, width, value) {
+    h.write(value.toString(8).padStart(width - 1, '0') + '\0', at, 'latin1');
+}
+/** Largest prefix of `s` (UTF-8) not longer than `max` bytes, cut on a character boundary. */
+function utf8Head(s, max) {
+    const b = enc.encode(s);
+    if (b.length <= max)
+        return b;
+    let end = max;
+    while (end > 0 && (b[end] & 0xc0) === 0x80)
+        end--;
+    return b.subarray(0, end);
+}
+function tarHeader(name, prefix, size, mode, mtime, type) {
+    const h = Buffer.alloc(BLOCK);
+    h.set(name, 0);
+    putOctal(h, 100, 8, mode);
+    putOctal(h, 108, 8, 0); // uid
+    putOctal(h, 116, 8, 0); // gid
+    putOctal(h, 124, 12, size);
+    putOctal(h, 136, 12, mtime);
+    h.fill(0x20, 148, 156); // checksum placeholder
+    h.write(type, 156, 'latin1');
+    h.write('ustar\0', 257, 'latin1');
+    h.write('00', 263, 'latin1');
+    h.set(prefix, 345);
+    let sum = 0;
+    for (const b of h)
+        sum += b;
+    h.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 'latin1');
+    return h;
+}
+function padTo512(data) {
+    const rem = data.length % BLOCK;
+    return rem === 0 ? [data] : [data, Buffer.alloc(BLOCK - rem)];
+}
+function paxRecord(key, value) {
+    const body = enc.encode(` ${key}=${value}\n`);
+    // The length counts its own decimal digits.
+    let len = body.length + 1;
+    while (String(len).length + body.length !== len)
+        len = String(len).length + body.length;
+    return Buffer.concat([Buffer.from(String(len), 'latin1'), body]);
+}
+/** Split `name` for the ustar name/prefix fields, or undefined if it cannot fit. */
+function ustarSplit(nameBytes, name) {
+    if (nameBytes.length <= 100)
+        return { name: nameBytes, prefix: new Uint8Array(0) };
+    for (let i = 0; i < nameBytes.length; i++) {
+        if (nameBytes[i] !== 0x2f)
+            continue;
+        const prefix = nameBytes.subarray(0, i);
+        const rest = nameBytes.subarray(i + 1);
+        if (prefix.length > 155)
+            break;
+        if (rest.length <= 100 && rest.length > 0)
+            return { name: rest, prefix };
+    }
+    void name;
+    return undefined;
+}
+/** POSIX ustar; long names use the prefix field, then a pax `path` extended header. */
+export function writeTar(tree, options = {}) {
+    const mtime = options.epoch ?? 0;
+    const chunks = [];
+    let n = 0;
+    for (const d of options.dirs ?? [])
+        chunks.push(tarHeader(enc.encode(d + '/'), new Uint8Array(0), 0, 0o755, mtime, '5'));
+    for (const e of entriesOf(tree)) {
+        if (e.bytes.length > TAR_MAX_SIZE) {
+            throw new SitefileError('E_EXPORT', `tar export does not support files of 8 GiB or more: '/${e.name}'`);
+        }
+        let split = ustarSplit(e.nameBytes, e.name);
+        if (!split) {
+            const rec = paxRecord('path', e.name);
+            const pname = enc.encode(`PaxHeaders/${n++}`);
+            chunks.push(tarHeader(pname, new Uint8Array(0), rec.length, 0o644, mtime, 'x'), ...padTo512(rec));
+            split = { name: utf8Head(e.name, 100), prefix: new Uint8Array(0) };
+        }
+        chunks.push(tarHeader(split.name, split.prefix, e.bytes.length, e.mode, mtime, '0'), ...padTo512(e.bytes));
+    }
+    chunks.push(Buffer.alloc(BLOCK * 2));
+    return Buffer.concat(chunks);
+}
+/** gzip of the tar, header mtime 0 and no filename, so the stream is reproducible. */
+export function writeTgz(tree, options = {}) {
+    return gzipTar(writeTar(tree, options));
+}
+/** Reproducible gzip of an already-written tar (see deflate.ts for the exact format). */
+export function gzipTar(tar) {
+    return gzip(tar);
+}
+//# sourceMappingURL=archive-writers.js.map

package/lib/src/attest.d.ts

@@ -0,0 +1,126 @@
+import type { BuildResult, Pins } from './executor.js';
+import type { Tree } from './tree.js';
+/**
+ * Build attestations for OCI site images (`build --provenance` / `--sbom`).
+ *
+ * Each attestation is an in-toto Statement v1 (one JSON blob) wrapped in an OCI 1.1 artifact
+ * manifest whose `subject` is the image manifest:
+ *
+ *   manifest  artifactType application/vnd.in-toto+json, config = the empty descriptor ({}),
+ *             one layer application/vnd.in-toto+json annotated in-toto.io/predicate-type,
+ *             subject = the image manifest descriptor
+ *
+ * - provenance: predicate https://slsa.dev/provenance/v1 (the Sitefile digest, build args except
+ *   secret-looking names, every import with its digest, the BASE image digest, the builder version)
+ * - sbom: predicate https://cyclonedx.org/bom, a CycloneDX 1.6 document listing every file in the
+ *   site layer (path in the image, SHA-256, mode, origin) and the BASE image
+ *
+ * The image manifest is never touched: an attestation points at it, so the image ID is the same with
+ * or without attestations. Everything is canonical JSON with no timestamps unless SOURCE_DATE_EPOCH
+ * is set, so the same build gives byte-identical attestations (in both implementations).
+ */
+/** Sitefile version recorded as the builder version (also `sitefile --version`). */
+export declare const SITEFILE_VERSION = "0.1.0";
+export declare const ATTEST: {
+    /** artifactType of the attestation manifest and media type of its layer. */
+    readonly inToto: 'application/vnd.in-toto+json';
+    readonly emptyConfig: 'application/vnd.oci.empty.v1+json';
+    readonly predicateAnnotation: 'in-toto.io/predicate-type';
+    readonly statement: 'https://in-toto.io/Statement/v1';
+    readonly slsa: 'https://slsa.dev/provenance/v1';
+    readonly cyclonedx: 'https://cyclonedx.org/bom';
+    readonly buildType: 'https://github.com/johnhenry/sitefile/blob/main/docs/CLI.md#attestations';
+    readonly builderId: 'https://github.com/johnhenry/sitefile';
+};
+/** The OCI empty descriptor's blob (`{}`). */
+export declare const EMPTY_JSON: NodeJS.NonSharedUint8Array;
+export declare const EMPTY_DIGEST: string;
+export interface AttestRequest {
+    readonly provenance: boolean;
+    readonly sbom: boolean;
+}
+/** One attestation (or any referrer): its index descriptor and the blobs it needs. */
+export interface Referrer {
+    /** Image-index descriptor: mediaType, digest, size, artifactType, annotations. */
+    readonly descriptor: ReferrerDescriptor;
+    /** digest -> bytes: the manifest, its config and its layers. */
+    readonly blobs: ReadonlyArray<readonly [string, Uint8Array]>;
+}
+export interface ReferrerDescriptor {
+    readonly mediaType: string;
+    readonly digest: string;
+    readonly size: number;
+    readonly artifactType?: string | undefined;
+    readonly annotations?: Readonly<Record<string, string>> | undefined;
+}
+/** What the provenance and SBOM say about a build (deterministic: no absolute paths, no times). */
+export interface BuildFacts {
+    /** The Sitefile's path relative to the context (its basename when it lives elsewhere). */
+    readonly sitefile: string;
+    readonly sitefileDigest: string;
+    /** `--build-arg` / `--build-arg-file` values, except those whose names look secret. */
+    readonly args: Readonly<Record<string, string>>;
+    /** Names of the build args left out because they look secret (API_TOKEN, DB_PASSWORD, ...). */
+    readonly redactedArgs: readonly string[];
+    readonly platform: string;
+    /** Imports in declaration order with the digest the build used (Sitefile.lock's for remote ones). */
+    readonly imports: ReadonlyArray<{
+        readonly name: string;
+        readonly uri: string;
+        readonly resolved?: string | undefined;
+        readonly digest: string;
+        readonly gitCommit?: string | undefined;
+    }>;
+    readonly base?: {
+        readonly name: string;
+        readonly digest: string;
+    } | undefined;
+    /** `FROM image` stage bases, in stage order (FROM line, image name, image digest). */
+    /** `import`: the qualified name of the imported Sitefile (IMPORT … AS sitefile) whose stage it is. */
+    readonly images?: ReadonlyArray<{
+        readonly line: number;
+        readonly name: string;
+        readonly digest: string;
+        readonly import?: string | undefined;
+    }> | undefined;
+    /** `--strict-pins`: how each remote input was pinned (shown in the provenance). */
+    readonly pins?: Pins | undefined;
+    /** File origins start with the Sitefile label (relative to the cwd); they are rewritten to `sitefile`. */
+    readonly label: string;
+}
+/** The image an attestation is about. */
+export interface AttestSubject {
+    readonly digest: string;
+    readonly size: number;
+    /** The site's files (rooted at `/`) and where they sit in the image. */
+    readonly files: Tree;
+    readonly root: string;
+    /** org.opencontainers.image.title, if the image has one. */
+    readonly title?: string | undefined;
+}
+/** Whether a build-arg name looks like it holds a secret (any `_`-separated word is key, token, password, ...). */
+export declare function isSecretArgName(name: string): boolean;
+/** The Sitefile path the build used, as `build` resolves it. */
+export declare function sitefilePathOf(contextDir: string, sitefile: string | undefined): string;
+/** Collect the facts for a finished build. Reads the Sitefile again to digest it. */
+export declare function buildFacts(result: Pick<BuildResult, 'resources' | 'base' | 'pins' | 'images'>, options: {
+    readonly contextDir: string;
+    readonly sitefile?: string | undefined;
+    readonly label?: string | undefined;
+    readonly buildArgs?: Readonly<Record<string, string>> | undefined;
+    readonly platform?: string | undefined;
+}): Promise<BuildFacts>;
+/** SLSA provenance v1 predicate. */
+export declare function provenancePredicate(facts: BuildFacts, epoch: number | undefined): Record<string, unknown>;
+/** CycloneDX 1.6 SBOM: the image, its BASE and every file of the site layer. */
+export declare function sbomPredicate(subject: AttestSubject, facts: BuildFacts, epoch: number | undefined): Record<string, unknown>;
+/** Wrap a predicate in an in-toto statement about `subject` and an OCI artifact manifest. */
+export declare function attestationReferrer(subject: Pick<AttestSubject, 'digest' | 'size'>, predicateType: string, predicate: unknown): Referrer;
+/** The requested attestations for an image, provenance first. */
+export declare function makeAttestations(subject: AttestSubject, facts: BuildFacts, request: AttestRequest, epoch: number | undefined): Referrer[];
+/** An OCI image index listing referrers (the store's referrers file and the registry fallback tag). */
+export declare function encodeReferrersIndex(descriptors: readonly ReferrerDescriptor[]): Uint8Array;
+/** Parse a referrers index; entries that are not well-formed descriptors are dropped. */
+export declare function decodeReferrersIndex(bytes: Uint8Array): ReferrerDescriptor[];
+/** The referrers fallback tag for a subject digest (`sha256-<hex>`, distribution spec v1.1). */
+export declare function referrersTag(subject: string): string;

package/lib/src/attest.js

@@ -0,0 +1,220 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { sha256 } from './digest.js';
+import { SitefileError } from './errors.js';
+import { canonicalJson, MEDIA } from './oci.js';
+/**
+ * Build attestations for OCI site images (`build --provenance` / `--sbom`).
+ *
+ * Each attestation is an in-toto Statement v1 (one JSON blob) wrapped in an OCI 1.1 artifact
+ * manifest whose `subject` is the image manifest:
+ *
+ *   manifest  artifactType application/vnd.in-toto+json, config = the empty descriptor ({}),
+ *             one layer application/vnd.in-toto+json annotated in-toto.io/predicate-type,
+ *             subject = the image manifest descriptor
+ *
+ * - provenance: predicate https://slsa.dev/provenance/v1 (the Sitefile digest, build args except
+ *   secret-looking names, every import with its digest, the BASE image digest, the builder version)
+ * - sbom: predicate https://cyclonedx.org/bom, a CycloneDX 1.6 document listing every file in the
+ *   site layer (path in the image, SHA-256, mode, origin) and the BASE image
+ *
+ * The image manifest is never touched: an attestation points at it, so the image ID is the same with
+ * or without attestations. Everything is canonical JSON with no timestamps unless SOURCE_DATE_EPOCH
+ * is set, so the same build gives byte-identical attestations (in both implementations).
+ */
+/** Sitefile version recorded as the builder version (also `sitefile --version`). */
+export const SITEFILE_VERSION = '0.1.0';
+export const ATTEST = {
+    /** artifactType of the attestation manifest and media type of its layer. */
+    inToto: 'application/vnd.in-toto+json',
+    emptyConfig: 'application/vnd.oci.empty.v1+json',
+    predicateAnnotation: 'in-toto.io/predicate-type',
+    statement: 'https://in-toto.io/Statement/v1',
+    slsa: 'https://slsa.dev/provenance/v1',
+    cyclonedx: 'https://cyclonedx.org/bom',
+    buildType: 'https://github.com/johnhenry/sitefile/blob/main/docs/CLI.md#attestations',
+    builderId: 'https://github.com/johnhenry/sitefile',
+};
+/** The OCI empty descriptor's blob (`{}`). */
+export const EMPTY_JSON = new TextEncoder().encode('{}');
+export const EMPTY_DIGEST = sha256(EMPTY_JSON);
+const SECRET_WORDS = new Set(['apikey', 'auth', 'credential', 'credentials', 'key', 'passwd', 'password', 'pword', 'secret', 'token']);
+/** Whether a build-arg name looks like it holds a secret (any `_`-separated word is key, token, password, ...). */
+export function isSecretArgName(name) {
+    return name
+        .toLowerCase()
+        .split('_')
+        .some((w) => SECRET_WORDS.has(w));
+}
+/** The Sitefile path the build used, as `build` resolves it. */
+export function sitefilePathOf(contextDir, sitefile) {
+    return path.resolve(sitefile ?? path.join(contextDir, 'Sitefile'));
+}
+/** Collect the facts for a finished build. Reads the Sitefile again to digest it. */
+export async function buildFacts(result, options) {
+    const file = sitefilePathOf(options.contextDir, options.sitefile);
+    let bytes;
+    try {
+        bytes = new Uint8Array(await readFile(file));
+    }
+    catch (e) {
+        throw new SitefileError('E_NOT_FOUND', `cannot read Sitefile '${file}'`, undefined, { cause: e });
+    }
+    const rel = path.relative(path.resolve(options.contextDir), file);
+    const inside = rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    const sitefile = inside ? rel.split(path.sep).join('/') : path.basename(file);
+    const args = {};
+    const redactedArgs = [];
+    for (const [k, v] of Object.entries(options.buildArgs ?? {})) {
+        if (isSecretArgName(k))
+            redactedArgs.push(k);
+        else
+            args[k] = v;
+    }
+    redactedArgs.sort();
+    const imports = [...result.resources].map(([name, r]) => ({ name, uri: r.provenance.uri, resolved: r.provenance.resolvedUrl, digest: r.provenance.digest, gitCommit: r.provenance.gitCommit }));
+    return {
+        sitefile,
+        sitefileDigest: sha256(bytes),
+        args,
+        redactedArgs,
+        platform: options.platform ?? 'linux/amd64',
+        imports,
+        base: result.base ? { name: result.base.name, digest: result.base.manifestDigest } : undefined,
+        images: result.images?.map((i) => ({ line: i.line, name: i.name, digest: i.digest, ...(i.import !== undefined ? { import: i.import } : {}) })),
+        pins: result.pins,
+        label: options.label ?? (path.relative(process.cwd(), file) || path.basename(file)),
+    };
+}
+const hex = (digest) => digest.replace(/^sha256:/, '');
+function isoOf(epoch) {
+    return new Date(epoch * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/** SLSA provenance v1 predicate. */
+export function provenancePredicate(facts, epoch) {
+    const externalParameters = { sitefile: facts.sitefile, args: { ...facts.args }, platform: facts.platform };
+    if (facts.redactedArgs.length)
+        externalParameters.redactedArgs = [...facts.redactedArgs];
+    // --strict-pins: the build refused unpinned inputs; each remote dependency says what pinned it.
+    if (facts.pins)
+        externalParameters.strictPins = true;
+    const deps = [{ name: 'sitefile', uri: facts.sitefile, digest: { sha256: hex(facts.sitefileDigest) } }];
+    for (const i of facts.imports) {
+        const d = { name: `import:${i.name}`, uri: i.uri, digest: i.gitCommit !== undefined ? { gitCommit: i.gitCommit, sha256: hex(i.digest) } : { sha256: hex(i.digest) } };
+        if (i.resolved !== undefined && i.resolved !== i.uri)
+            d.downloadLocation = i.resolved;
+        const pin = facts.pins?.imports[i.name];
+        if (pin !== undefined)
+            d.annotations = { 'dev.sitefile.pin': pin };
+        deps.push(d);
+    }
+    for (const i of facts.images ?? []) {
+        // A stage of an imported Sitefile is `from:<import>:<line>` (its line is in that Sitefile); --strict-pins checked it there.
+        const pin = i.import === undefined ? facts.pins?.images?.[i.line] : undefined;
+        deps.push({ name: i.import === undefined ? `from:${i.line}` : `from:${i.import}:${i.line}`, uri: i.name, digest: { sha256: hex(i.digest) }, ...(pin ? { annotations: { 'dev.sitefile.pin': pin } } : {}) });
+    }
+    if (facts.base) {
+        deps.push({ name: 'base', uri: facts.base.name, digest: { sha256: hex(facts.base.digest) }, ...(facts.pins?.base ? { annotations: { 'dev.sitefile.pin': facts.pins.base } } : {}) });
+    }
+    const runDetails = { builder: { id: ATTEST.builderId, version: { sitefile: SITEFILE_VERSION } } };
+    if (epoch !== undefined)
+        runDetails.metadata = { startedOn: isoOf(epoch), finishedOn: isoOf(epoch) };
+    return { buildDefinition: { buildType: ATTEST.buildType, externalParameters, resolvedDependencies: deps }, runDetails };
+}
+/** CycloneDX 1.6 SBOM: the image, its BASE and every file of the site layer. */
+export function sbomPredicate(subject, facts, epoch) {
+    const metadata = {
+        tools: { components: [{ type: 'application', name: 'sitefile', version: SITEFILE_VERSION }] },
+        component: { type: 'container', 'bom-ref': 'image', name: subject.title ?? 'site', version: subject.digest },
+    };
+    if (epoch !== undefined)
+        metadata.timestamp = isoOf(epoch);
+    const components = [];
+    if (facts.base)
+        components.push({ type: 'container', 'bom-ref': 'base', name: facts.base.name, version: facts.base.digest });
+    const prefix = `${facts.label}:`;
+    for (const [p, n] of subject.files.entries()) {
+        const name = subject.root === '/' ? p : subject.root + p;
+        const origin = n.origin.startsWith(prefix) ? `${facts.sitefile}:${n.origin.slice(prefix.length)}` : n.origin;
+        components.push({
+            type: 'file',
+            'bom-ref': `file:${name}`,
+            name,
+            hashes: [{ alg: 'SHA-256', content: hex(n.digest) }],
+            properties: [
+                { name: 'sitefile:mode', value: n.mode.toString(8) },
+                { name: 'sitefile:origin', value: origin },
+            ],
+        });
+    }
+    return { bomFormat: 'CycloneDX', specVersion: '1.6', version: 1, metadata, components };
+}
+const enc = new TextEncoder();
+/** Wrap a predicate in an in-toto statement about `subject` and an OCI artifact manifest. */
+export function attestationReferrer(subject, predicateType, predicate) {
+    const statement = enc.encode(canonicalJson({ _type: ATTEST.statement, subject: [{ name: '_', digest: { sha256: hex(subject.digest) } }], predicateType, predicate }));
+    const layerDigest = sha256(statement);
+    const annotations = { [ATTEST.predicateAnnotation]: predicateType };
+    const manifest = enc.encode(canonicalJson({
+        schemaVersion: 2,
+        mediaType: MEDIA.manifest,
+        artifactType: ATTEST.inToto,
+        config: { mediaType: ATTEST.emptyConfig, digest: EMPTY_DIGEST, size: EMPTY_JSON.byteLength },
+        layers: [{ mediaType: ATTEST.inToto, digest: layerDigest, size: statement.byteLength, annotations }],
+        subject: { mediaType: MEDIA.manifest, digest: subject.digest, size: subject.size },
+        annotations,
+    }));
+    const digest = sha256(manifest);
+    return {
+        descriptor: { mediaType: MEDIA.manifest, digest, size: manifest.byteLength, artifactType: ATTEST.inToto, annotations },
+        blobs: [
+            [digest, manifest],
+            [EMPTY_DIGEST, EMPTY_JSON],
+            [layerDigest, statement],
+        ],
+    };
+}
+/** The requested attestations for an image, provenance first. */
+export function makeAttestations(subject, facts, request, epoch) {
+    const out = [];
+    if (request.provenance)
+        out.push(attestationReferrer(subject, ATTEST.slsa, provenancePredicate(facts, epoch)));
+    if (request.sbom)
+        out.push(attestationReferrer(subject, ATTEST.cyclonedx, sbomPredicate(subject, facts, epoch)));
+    return out;
+}
+/** An OCI image index listing referrers (the store's referrers file and the registry fallback tag). */
+export function encodeReferrersIndex(descriptors) {
+    return enc.encode(canonicalJson({ schemaVersion: 2, mediaType: MEDIA.index, manifests: descriptors }));
+}
+/** Parse a referrers index; entries that are not well-formed descriptors are dropped. */
+export function decodeReferrersIndex(bytes) {
+    const j = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    if (j.schemaVersion !== 2 || !Array.isArray(j.manifests))
+        throw new Error('not an OCI image index');
+    const out = [];
+    for (const m of j.manifests) {
+        if (typeof m?.digest !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(m.digest) || typeof m.size !== 'number' || !Number.isSafeInteger(m.size) || m.size < 0)
+            continue;
+        let annotations;
+        if (typeof m.annotations === 'object' && m.annotations !== null && !Array.isArray(m.annotations)) {
+            annotations = {};
+            for (const [k, v] of Object.entries(m.annotations))
+                if (typeof v === 'string')
+                    annotations[k] = v;
+        }
+        out.push({
+            mediaType: typeof m.mediaType === 'string' ? m.mediaType : MEDIA.manifest,
+            digest: m.digest,
+            size: m.size,
+            artifactType: typeof m.artifactType === 'string' ? m.artifactType : undefined,
+            annotations,
+        });
+    }
+    return out;
+}
+/** The referrers fallback tag for a subject digest (`sha256-<hex>`, distribution spec v1.1). */
+export function referrersTag(subject) {
+    return subject.replace(':', '-');
+}
+//# sourceMappingURL=attest.js.map

package/lib/src/bake.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `sitefile bake`: build several variants of a site from one bake file
+ * (`sitefile.bake.yaml`, `.yml` or `.json`), like `docker buildx bake`.
+ *
+ * The bake file names targets (each one a `sitefile build`: context, Sitefile,
+ * build args, arg files, `--target` stage, output, format, tags), optional
+ * `matrix` values that expand one target into several, `inherits` and groups.
+ * This module only reads and resolves the file into a {@link BakePlan}; the CLI
+ * (src/cli/bake.ts) runs the builds. No IO besides reading the bake file.
+ */
+/** The default bake file names, looked up in this order in the current directory. */
+export declare const BAKE_FILES: readonly string[];
+/** One build of a bake plan. Paths are as the CLI passes them to `build` (joined to the bake file's directory). */
+export interface BakeTarget {
+    readonly name: string;
+    readonly context: string;
+    readonly file: string;
+    /** Build args in definition order (inherited ones first). */
+    readonly args: Readonly<Record<string, string>>;
+    readonly argFiles: readonly string[];
+    /** `--target <stage>`. */
+    readonly target: string | null;
+    readonly output: string;
+    readonly format: string | null;
+    readonly tags: readonly string[];
+    /** The matrix values of an expanded target. */
+    readonly matrix: Readonly<Record<string, string>> | null;
+}
+export interface BakePlan {
+    /** The bake file as given (or found). */
+    readonly file: string;
+    readonly targets: readonly BakeTarget[];
+}
+/** A target as written (after type checks), before inheritance. */
+interface RawTarget {
+    context?: string;
+    file?: string;
+    args?: Record<string, string>;
+    'arg-files'?: string[];
+    target?: string;
+    output?: string;
+    format?: string;
+    tags?: string[];
+    matrix?: Array<[string, string[]]>;
+    inherits: string[];
+}
+interface Definition {
+    readonly label: string;
+    readonly targets: ReadonlyMap<string, RawTarget>;
+    readonly groups: ReadonlyMap<string, readonly string[]>;
+}
+/** Find the bake file: `file` when given, else the first of {@link BAKE_FILES} in the current directory. */
+export declare function findBakeFile(file: string | undefined): Promise<string>;
+/** Read and parse a bake file into its definition (no resolution yet). */
+export declare function loadBakeFile(file: string): Promise<unknown>;
+/** Check the shape of a parsed bake file. */
+export declare function parseBakeDefinition(value: unknown, label: string): Definition;
+/**
+ * Resolve a bake definition into the targets to build: `selected` names targets
+ * (a matrix target's name selects all its variants; a variant's own name selects
+ * it) and groups, in order, without duplicates. With none, the `default` group if
+ * there is one, else every target in file order. Unknown names are usage errors;
+ * targets whose outputs overlap, or that share a tag, are E_CONFLICT.
+ */
+export declare function resolveBake(def: Definition, file: string, selected: readonly string[]): BakePlan;
+/** Read, check and resolve a bake file. */
+export declare function bakePlan(file: string, selected: readonly string[]): Promise<BakePlan>;
+/** `--print --json`. */
+export declare function bakePlanJson(plan: BakePlan): unknown;
+/** `--print`: one block per target, then a count. */
+export declare function bakePlanText(plan: BakePlan): string;
+/** The `sitefile build` arguments of one target (before the CLI's pass-through flags). */
+export declare function buildArgv(t: BakeTarget): string[];
+export {};