@johnhenry/sitefile 0.0.0-stage → 0.0.1

package/lib/src/resources/network.d.ts

@@ -0,0 +1,70 @@
+import { type SourceSpan } from '../errors.js';
+/**
+ * Explicit network settings for everything sitefile fetches (IMPORT over http(s), Git, registries).
+ * Nothing here is read from the environment implicitly: `HTTP(S)_PROXY` stays ignored, and the CLI
+ * reads `SITEFILE_PROXY` and friends through {@link networkFromEnv}. Embedders pass this in code
+ * (`FetchPolicy.network`, `RegistryOptions.network`).
+ */
+export interface NetworkSettings {
+    /** `http://[user:password@]host[:port]`: a CONNECT tunnel for https targets, absolute-form requests for http. */
+    readonly proxy?: string | undefined;
+    /** Hosts reached directly, never through the proxy (`NO_PROXY` syntax, see {@link hostMatches}). */
+    readonly noProxy?: readonly string[] | undefined;
+    /** When non-empty, only hosts matching one of these patterns may be contacted. */
+    readonly allowHosts?: readonly string[] | undefined;
+    /** Hosts never contacted; a deny rule beats an allow rule. */
+    readonly denyHosts?: readonly string[] | undefined;
+    /** Time limit for establishing the TCP connection (to the target, or to the proxy), ms. */
+    readonly connectTimeoutMs?: number | undefined;
+    /** Longest wait for data once connected (idle time), ms. */
+    readonly readTimeoutMs?: number | undefined;
+}
+/** A configured HTTP proxy, parsed. */
+export interface ProxyConfig {
+    readonly host: string;
+    readonly port: number;
+    /** `Basic …` when the URL carries credentials. */
+    readonly authorization?: string | undefined;
+    /** The proxy URL without credentials, for messages. */
+    readonly shown: string;
+}
+/** Split a list given as one string (commas and/or whitespace). */
+export declare function splitList(raw: string | undefined): string[];
+/** Parse a proxy URL, or throw E_USAGE. Credentials never appear in the message. */
+export declare function parseProxy(raw: string): ProxyConfig;
+/**
+ * True when `host` (as in a URL, IPv6 without brackets) on `port` matches `pattern`:
+ *   `*`                      every host
+ *   `example.com`            example.com and every subdomain (`.example.com` and `*.example.com` too)
+ *   `10.0.0.0/8`, `fd00::/8` IP-literal hosts in that network; `192.0.2.1`, `::1` that address
+ *   any of these + `:port`   only that port (`[::1]:8080` for IPv6)
+ * Patterns match the host as written in the URL: a name pattern never matches an IP literal and an
+ * IP pattern never matches a name, whatever it resolves to (the private-address rule covers that).
+ */
+export declare function hostMatches(host: string, port: number, pattern: string): boolean;
+/** Default port of an http(s) URL. */
+export declare function urlPort(url: URL): number;
+/**
+ * Apply the allow/deny host rules to one hop (every redirect, token realm and blob CDN hop included).
+ * Throws E_HOST_BLOCKED naming the rule; a deny rule beats an allow rule.
+ */
+export declare function checkHostRules(url: URL, network: NetworkSettings | undefined, shown: string, span?: SourceSpan): void;
+/** The proxy to use for `url`, or undefined for a direct connection (no proxy, or a no-proxy match). */
+export declare function proxyFor(url: URL, network: NetworkSettings | undefined): ProxyConfig | undefined;
+/** A usage problem in `network` (bad proxy URL, host pattern or timeout), or undefined. */
+export declare function networkProblem(network: NetworkSettings): string | undefined;
+/** Parse `SITEFILE_FETCH_TIMEOUT`: `<ms>` (connect and read) or `connect=<ms>,read=<ms>` (either part optional). */
+export declare function parseFetchTimeout(raw: string): {
+    connectTimeoutMs?: number;
+    readTimeoutMs?: number;
+};
+/**
+ * Network settings from `SITEFILE_PROXY`, `SITEFILE_NO_PROXY`, `SITEFILE_ALLOW_HOSTS`,
+ * `SITEFILE_DENY_HOSTS` (comma- or space-separated) and `SITEFILE_FETCH_TIMEOUT`. Empty values are unset.
+ * `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` are never read.
+ */
+export declare function networkFromEnv(env?: NodeJS.ProcessEnv): NetworkSettings;
+/** `over` on top of `base`: the proxy and timeouts are replaced, the host lists are joined (duplicates dropped). */
+export declare function mergeNetwork(base: NetworkSettings, over: NetworkSettings): NetworkSettings;
+/** True when any setting is present. */
+export declare function hasNetworkSettings(n: NetworkSettings | undefined): boolean;

package/lib/src/resources/network.js

@@ -0,0 +1,304 @@
+import { isIP } from 'node:net';
+import { SitefileError } from '../errors.js';
+/** Split a list given as one string (commas and/or whitespace). */
+export function splitList(raw) {
+    return (raw ?? '')
+        .split(/[\s,]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** A proxy URL with any credentials removed. */
+function shownProxy(raw) {
+    try {
+        const u = new URL(raw);
+        u.username = '';
+        u.password = '';
+        return u.href.replace(/\/$/, '');
+    }
+    catch {
+        return '<invalid url>';
+    }
+}
+/** Percent-decode, keeping invalid escapes as written (bytes decoded as UTF-8, lossily). */
+function percentDecode(s) {
+    const bytes = [];
+    for (let i = 0; i < s.length;) {
+        if (s[i] === '%' && /^[0-9a-fA-F]{2}$/.test(s.slice(i + 1, i + 3))) {
+            bytes.push(parseInt(s.slice(i + 1, i + 3), 16));
+            i += 3;
+        }
+        else {
+            const c = Buffer.from(s[i], 'utf8');
+            bytes.push(...c);
+            i += 1;
+        }
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+/** Parse a proxy URL, or throw E_USAGE. Credentials never appear in the message. */
+export function parseProxy(raw) {
+    const bad = () => new SitefileError('E_USAGE', `invalid proxy URL '${shownProxy(raw)}': expected http://[user:password@]host[:port]`);
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw bad();
+    }
+    if (u.protocol !== 'http:' || u.hostname === '' || (u.pathname !== '/' && u.pathname !== '') || u.search !== '' || u.hash !== '')
+        throw bad();
+    const host = u.hostname.replace(/^\[|\]$/g, '');
+    const port = u.port === '' ? 80 : Number(u.port);
+    const user = percentDecode(u.username);
+    const pass = percentDecode(u.password);
+    const authorization = user !== '' || pass !== '' ? `Basic ${Buffer.from(`${user}:${pass}`).toString('base64')}` : undefined;
+    return { host, port, authorization, shown: shownProxy(raw) };
+}
+function ipToBig(ip) {
+    const family = isIP(ip);
+    if (family === 4) {
+        const addr = ip.split('.').reduce((acc, b) => (acc << 8n) | BigInt(Number(b)), 0n);
+        return { family: 4, addr };
+    }
+    if (family === 6) {
+        let s = ip.toLowerCase();
+        const v4 = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(s);
+        if (v4) {
+            const [b0, b1, b2, b3] = v4.slice(1).map(Number);
+            s = s.slice(0, v4.index) + ((b0 << 8) | b1).toString(16) + ':' + ((b2 << 8) | b3).toString(16);
+        }
+        const [head, tail] = s.split('::');
+        const h = head ? head.split(':') : [];
+        const t = tail ? tail.split(':') : [];
+        const groups = [...h, ...(tail === undefined ? [] : new Array(8 - h.length - t.length).fill('0')), ...t];
+        if (groups.length !== 8)
+            return undefined;
+        return { family: 6, addr: groups.reduce((acc, g) => (acc << 16n) | BigInt(parseInt(g, 16)), 0n) };
+    }
+    return undefined;
+}
+const HOSTNAME_RE = /^[a-z0-9_-]+(?:\.[a-z0-9_-]+)*$/;
+/** Parse one pattern; undefined when it is not valid. */
+function parsePattern(raw) {
+    let p = raw.trim().toLowerCase();
+    if (p === '')
+        return undefined;
+    if (p === '*')
+        return { any: true };
+    let port;
+    // [v6]:port, [v6], v4:port, name:port. A bare IPv6 (two or more colons) has no port.
+    const bracket = /^\[([^\]]+)\](?::(\d+))?$/.exec(p);
+    if (bracket) {
+        p = bracket[1];
+        if (bracket[2] !== undefined)
+            port = Number(bracket[2]);
+    }
+    else if ((p.match(/:/g) ?? []).length === 1) {
+        const i = p.indexOf(':');
+        const ps = p.slice(i + 1);
+        if (!/^\d+$/.test(ps))
+            return undefined;
+        port = Number(ps);
+        p = p.slice(0, i);
+    }
+    if (port !== undefined && (port < 1 || port > 65535))
+        return undefined;
+    const withPort = (x) => (port === undefined ? x : { ...x, port });
+    const slash = p.indexOf('/');
+    if (slash !== -1) {
+        const ip = ipToBig(p.slice(0, slash));
+        const ps = p.slice(slash + 1);
+        if (!ip || !/^\d+$/.test(ps))
+            return undefined;
+        const prefix = Number(ps);
+        if (prefix > (ip.family === 4 ? 32 : 128))
+            return undefined;
+        return withPort({ net: { ...ip, prefix } });
+    }
+    const ip = ipToBig(p);
+    if (ip)
+        return withPort({ net: { ...ip, prefix: ip.family === 4 ? 32 : 128 } });
+    if (p.startsWith('*.'))
+        p = p.slice(2);
+    else if (p.startsWith('.'))
+        p = p.slice(1);
+    if (p.endsWith('.'))
+        p = p.slice(0, -1);
+    if (!HOSTNAME_RE.test(p))
+        return undefined;
+    return withPort({ domain: p });
+}
+/**
+ * True when `host` (as in a URL, IPv6 without brackets) on `port` matches `pattern`:
+ *   `*`                      every host
+ *   `example.com`            example.com and every subdomain (`.example.com` and `*.example.com` too)
+ *   `10.0.0.0/8`, `fd00::/8` IP-literal hosts in that network; `192.0.2.1`, `::1` that address
+ *   any of these + `:port`   only that port (`[::1]:8080` for IPv6)
+ * Patterns match the host as written in the URL: a name pattern never matches an IP literal and an
+ * IP pattern never matches a name, whatever it resolves to (the private-address rule covers that).
+ */
+export function hostMatches(host, port, pattern) {
+    const p = parsePattern(pattern);
+    return p !== undefined && matches(normalizeHost(host), port, p);
+}
+function normalizeHost(host) {
+    let h = host.toLowerCase();
+    if (h.startsWith('[') && h.endsWith(']'))
+        h = h.slice(1, -1);
+    if (h.endsWith('.'))
+        h = h.slice(0, -1);
+    return h;
+}
+function matches(host, port, p) {
+    if (p.any)
+        return true;
+    if (p.port !== undefined && p.port !== port)
+        return false;
+    if (p.domain !== undefined)
+        return host === p.domain || host.endsWith(`.${p.domain}`);
+    if (p.net) {
+        const ip = ipToBig(host);
+        if (!ip || ip.family !== p.net.family)
+            return false;
+        const bits = BigInt(ip.family === 4 ? 32 : 128);
+        const shift = bits - BigInt(p.net.prefix);
+        return ip.addr >> shift === p.net.addr >> shift;
+    }
+    return false;
+}
+/** The first pattern of `list` that matches, if any. */
+function firstMatch(host, port, list) {
+    const h = normalizeHost(host);
+    for (const raw of list ?? []) {
+        const p = parsePattern(raw);
+        if (p && matches(h, port, p))
+            return raw.trim();
+    }
+    return undefined;
+}
+/** Default port of an http(s) URL. */
+export function urlPort(url) {
+    return url.port !== '' ? Number(url.port) : url.protocol === 'http:' ? 80 : 443;
+}
+/**
+ * Apply the allow/deny host rules to one hop (every redirect, token realm and blob CDN hop included).
+ * Throws E_HOST_BLOCKED naming the rule; a deny rule beats an allow rule.
+ */
+export function checkHostRules(url, network, shown, span) {
+    if (!network)
+        return;
+    const host = normalizeHost(url.hostname);
+    const port = urlPort(url);
+    const denied = firstMatch(host, port, network.denyHosts);
+    if (denied !== undefined) {
+        throw new SitefileError('E_HOST_BLOCKED', `refusing to connect to ${host}: it matches deny-hosts rule '${denied}' (${shown})`, span);
+    }
+    if ((network.allowHosts ?? []).length > 0 && firstMatch(host, port, network.allowHosts) === undefined) {
+        throw new SitefileError('E_HOST_BLOCKED', `refusing to connect to ${host}: it matches no allow-hosts rule (${shown})`, span);
+    }
+}
+/** The proxy to use for `url`, or undefined for a direct connection (no proxy, or a no-proxy match). */
+export function proxyFor(url, network) {
+    if (!network?.proxy)
+        return undefined;
+    if (firstMatch(url.hostname, urlPort(url), network.noProxy) !== undefined)
+        return undefined;
+    return parseProxy(network.proxy);
+}
+// ------------------------------------------------------------------ configuration
+/** A usage problem in `network` (bad proxy URL, host pattern or timeout), or undefined. */
+export function networkProblem(network) {
+    if (network.proxy) {
+        try {
+            parseProxy(network.proxy);
+        }
+        catch (e) {
+            return e.message;
+        }
+    }
+    for (const [name, list] of [
+        ['no-proxy', network.noProxy],
+        ['allow-hosts', network.allowHosts],
+        ['deny-hosts', network.denyHosts],
+    ]) {
+        for (const p of list ?? []) {
+            if (!parsePattern(p))
+                return `invalid ${name} pattern '${p}': expected *, a host name (example.com, .example.com, *.example.com), an IP address or a CIDR network, optionally with :port`;
+        }
+    }
+    for (const [name, v] of [
+        ['connect timeout', network.connectTimeoutMs],
+        ['read timeout', network.readTimeoutMs],
+    ]) {
+        if (v !== undefined && (!Number.isSafeInteger(v) || v <= 0))
+            return `the ${name} must be a positive integer (ms)`;
+    }
+    return undefined;
+}
+function positiveMs(raw, what) {
+    if (!/^\d+$/.test(raw) || Number(raw) <= 0 || !Number.isSafeInteger(Number(raw))) {
+        throw new SitefileError('E_USAGE', `${what} expects a positive integer (ms), got '${raw}'`);
+    }
+    return Number(raw);
+}
+/** Parse `SITEFILE_FETCH_TIMEOUT`: `<ms>` (connect and read) or `connect=<ms>,read=<ms>` (either part optional). */
+export function parseFetchTimeout(raw) {
+    const s = raw.trim();
+    if (s === '')
+        return {};
+    if (/^\d+$/.test(s)) {
+        const ms = positiveMs(s, 'SITEFILE_FETCH_TIMEOUT');
+        return { connectTimeoutMs: ms, readTimeoutMs: ms };
+    }
+    const out = {};
+    for (const part of s.split(',')) {
+        const m = /^\s*(connect|read)\s*=\s*(\S*)\s*$/.exec(part);
+        if (!m)
+            throw new SitefileError('E_USAGE', `SITEFILE_FETCH_TIMEOUT expects <ms> or connect=<ms>,read=<ms>, got '${raw}'`);
+        const ms = positiveMs(m[2], `SITEFILE_FETCH_TIMEOUT ${m[1]}`);
+        if (m[1] === 'connect')
+            out.connectTimeoutMs = ms;
+        else
+            out.readTimeoutMs = ms;
+    }
+    return out;
+}
+/**
+ * Network settings from `SITEFILE_PROXY`, `SITEFILE_NO_PROXY`, `SITEFILE_ALLOW_HOSTS`,
+ * `SITEFILE_DENY_HOSTS` (comma- or space-separated) and `SITEFILE_FETCH_TIMEOUT`. Empty values are unset.
+ * `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` are never read.
+ */
+export function networkFromEnv(env = process.env) {
+    const proxy = (env.SITEFILE_PROXY ?? '').trim();
+    return {
+        ...(proxy !== '' ? { proxy } : {}),
+        ...(splitList(env.SITEFILE_NO_PROXY).length ? { noProxy: splitList(env.SITEFILE_NO_PROXY) } : {}),
+        ...(splitList(env.SITEFILE_ALLOW_HOSTS).length ? { allowHosts: splitList(env.SITEFILE_ALLOW_HOSTS) } : {}),
+        ...(splitList(env.SITEFILE_DENY_HOSTS).length ? { denyHosts: splitList(env.SITEFILE_DENY_HOSTS) } : {}),
+        ...parseFetchTimeout(env.SITEFILE_FETCH_TIMEOUT ?? ''),
+    };
+}
+/** `over` on top of `base`: the proxy and timeouts are replaced, the host lists are joined (duplicates dropped). */
+export function mergeNetwork(base, over) {
+    const join = (a, b) => {
+        const all = [...new Set([...(a ?? []), ...(b ?? [])])];
+        return all.length ? all : undefined;
+    };
+    const out = {
+        proxy: over.proxy ?? base.proxy,
+        noProxy: join(base.noProxy, over.noProxy),
+        allowHosts: join(base.allowHosts, over.allowHosts),
+        denyHosts: join(base.denyHosts, over.denyHosts),
+        connectTimeoutMs: over.connectTimeoutMs ?? base.connectTimeoutMs,
+        readTimeoutMs: over.readTimeoutMs ?? base.readTimeoutMs,
+    };
+    for (const k of Object.keys(out))
+        if (out[k] === undefined)
+            delete out[k];
+    return out;
+}
+/** True when any setting is present. */
+export function hasNetworkSettings(n) {
+    return !!n && Object.values(n).some((v) => v !== undefined && !(Array.isArray(v) && v.length === 0));
+}
+//# sourceMappingURL=network.js.map

package/lib/src/resources/types.d.ts

@@ -0,0 +1,69 @@
+import type { NetworkSettings } from './network.js';
+import type { Tree } from '../tree.js';
+export interface Provenance {
+    /** The URI as written (after variable interpolation), or `./relative/path`. */
+    readonly uri: string;
+    /** Final URL after redirects, for remote resources. */
+    readonly resolvedUrl?: string;
+    /** `sha256:<hex>`: file bytes, tree digest, or the raw bytes a value was parsed from. */
+    readonly digest: string;
+    /** Git imports: the commit the content was read from (40 hex). */
+    readonly gitCommit?: string;
+}
+export interface FileResource {
+    readonly kind: 'file';
+    readonly bytes: Uint8Array;
+    readonly mode: number;
+    /** Suggested basename when copied to a directory destination. */
+    readonly basename: string;
+    readonly provenance: Provenance;
+}
+export interface TreeResource {
+    readonly kind: 'tree';
+    readonly tree: Tree;
+    readonly provenance: Provenance;
+}
+export interface ValueResource {
+    readonly kind: 'value';
+    /** `markdown`: one document object, or a list of them for a directory. */
+    /** `html`: the text of an `IMPORT … AS html` fragment. */
+    readonly format: 'text' | 'json' | 'markdown' | 'yaml' | 'csv' | 'wbn' | 'html';
+    readonly value: unknown;
+    readonly provenance: Provenance;
+}
+export type Resource = FileResource | TreeResource | ValueResource;
+/** Network policy for remote resources. Defaults are secure. */
+export interface FetchPolicy {
+    /** Permit plain `http:` (default false). */
+    readonly allowHttp: boolean;
+    /** Permit loopback, private, link-local and other non-public addresses (default false). */
+    readonly allowPrivateNetwork: boolean;
+    /** Maximum response body size in bytes (default 50 MiB). */
+    readonly maxBytes: number;
+    /** Total time budget per resource including redirects, ms (default 30 000). */
+    readonly timeoutMs: number;
+    /** Maximum redirects followed (default 5). */
+    readonly maxRedirects: number;
+    /**
+     * Extra PEM-encoded CA certificate(s) to trust for https, in addition to
+     * Node's built-in roots (never instead of them). For tests and enterprise
+     * private CAs; certificate and hostname verification stay on.
+     */
+    readonly ca?: string | Buffer | undefined;
+    /**
+     * Proxy, host rules and connect/read timeouts (see {@link NetworkSettings}). Unset: direct
+     * connections, every public host, only the total `timeoutMs`.
+     */
+    readonly network?: NetworkSettings | undefined;
+}
+export declare const DEFAULT_FETCH_POLICY: FetchPolicy;
+/** Limits applied when an archive is extracted with `IMPORT … AS tree`. Defaults are secure. */
+export interface ArchiveLimits {
+    /** Maximum number of entries (default 10 000). */
+    readonly maxEntries: number;
+    /** Maximum total uncompressed bytes (default 500 MiB). */
+    readonly maxTotalBytes: number;
+    /** Maximum uncompressed:compressed ratio of the gzip/zip data (default 100). */
+    readonly maxRatio: number;
+}
+export declare const DEFAULT_ARCHIVE_LIMITS: ArchiveLimits;

package/lib/src/resources/types.js

@@ -0,0 +1,13 @@
+export const DEFAULT_FETCH_POLICY = {
+    allowHttp: false,
+    allowPrivateNetwork: false,
+    maxBytes: 50 * 1024 * 1024,
+    timeoutMs: 30_000,
+    maxRedirects: 5,
+};
+export const DEFAULT_ARCHIVE_LIMITS = {
+    maxEntries: 10_000,
+    maxTotalBytes: 500 * 1024 * 1024,
+    maxRatio: 100,
+};
+//# sourceMappingURL=types.js.map

package/lib/src/resources/vendor.d.ts

@@ -0,0 +1,94 @@
+import { type SourceSpan } from '../errors.js';
+import type { Store } from '../store.js';
+import type { LocalContext } from './local.js';
+import type { GitSelection } from './git.js';
+import type { ArchiveLimits } from './types.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 declare const DEFAULT_VENDOR_DIR = "vendor/sitefile";
+export declare const VENDOR_MANIFEST = "manifest.json";
+export interface VendoredResource {
+    /** `sha256:<hex>` of the body: also its blob name. */
+    readonly integrity: string;
+    readonly size: number;
+    /** Final URL after redirects, as the lockfile records it. */
+    readonly resolved: string;
+}
+export interface VendoredImage {
+    /** What the reference resolved to (an index for multi-platform images, else the manifest). */
+    readonly digest: string;
+    /** The platform that was vendored (`os/arch`). */
+    readonly platform: string;
+    /** That platform's manifest digest (the image ID). */
+    readonly manifest: string;
+}
+/** A Git IMPORT: the commit it was read from and its content (a file's bytes, or a tree as a tar). */
+export interface VendoredGit {
+    readonly commit: string;
+    readonly kind: 'tree' | 'file';
+    /** `sha256:<hex>` of the stored bytes: also their blob name. */
+    readonly integrity: string;
+    readonly size: number;
+    /** Files only: `644` or `755`. */
+    readonly mode?: string;
+}
+export interface VendorManifest {
+    readonly version: 1;
+    readonly resources: Readonly<Record<string, VendoredResource>>;
+    readonly images: Readonly<Record<string, VendoredImage>>;
+    /** Written only when non-empty. */
+    readonly git?: Readonly<Record<string, VendoredGit>>;
+}
+/** Validate a vendor directory: a relative path inside the build context. Returns it normalized (POSIX, no trailing slash). */
+export declare function vendorDirRel(input: string): string;
+/**
+ * The vendor directory a build uses: `explicit` (which must have a manifest), else the default one if
+ * its manifest exists, else none.
+ */
+export declare function findVendorDir(contextReal: string, explicit: string | undefined): Promise<string | undefined>;
+/** Parse and check a vendor manifest. Errors are E_VALIDATION naming the file. */
+export declare function parseVendorManifest(bytes: Uint8Array, shown: string): VendorManifest;
+/** The manifest as `sitefile vendor` writes it: sorted keys, two-space indent, trailing newline. */
+export declare function serializeVendorManifest(m: VendorManifest): string;
+/** A vendor directory opened through the build's sandboxed context reader. */
+export declare class Vendor {
+    /** Context-relative directory. */
+    readonly dir: string;
+    private readonly local;
+    readonly manifest: VendorManifest;
+    private constructor();
+    static open(local: LocalContext, dir: string): Promise<Vendor>;
+    resource(url: string): VendoredResource | undefined;
+    image(ref: string): VendoredImage | undefined;
+    git(url: string): VendoredGit | undefined;
+    /** The vendored content of a Git IMPORT, verified against its digest. */
+    readGit(url: string, e: VendoredGit, basename: string, limits: ArchiveLimits, span?: SourceSpan): Promise<GitSelection>;
+    /** The vendored body of `url`, verified against its digest. */
+    readResource(url: string, e: VendoredResource, span?: SourceSpan): Promise<{
+        bytes: Uint8Array;
+        finalUrl: string;
+    }>;
+    private readBlob;
+    private hasBlob;
+    /**
+     * 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.
+     */
+    seedStore(store: Store, rootDigest: string, platform: string): Promise<void>;
+}
+/**
+ * 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 declare function writeVendorDir(contextReal: string, dir: string, manifestText: string, blobs: ReadonlyMap<string, Uint8Array>): Promise<string>;