@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/resources/local.js

@@ -0,0 +1,248 @@
+import { promises as fs } from 'node:fs';
+import { join, sep, relative, posix } from 'node:path';
+import { SitefileError } from '../errors.js';
+import { sha256 } from '../digest.js';
+import { Tree, makeFile } from '../tree.js';
+import { nfc } from '../paths.js';
+import { IgnoreRules } from './ignore.js';
+export const SITEFILEIGNORE = '.sitefileignore';
+const NON_ASCII = /[^\x00-\x7f]/;
+function normalizationCollision(rel, span) {
+    return new SitefileError('E_PATH_COLLISION', `'${display(rel)}' names more than one file in the build context: their names differ only in Unicode normalization (NFC/NFD); rename one`, span);
+}
+function errCode(e) {
+    return e?.code;
+}
+async function exists(p) {
+    return fs.lstat(p).then(() => true, () => false);
+}
+function display(rel) {
+    return rel === '' ? '.' : './' + rel;
+}
+/**
+ * The local build context. Every read is confined to `root`: real paths are
+ * resolved and must stay inside it.
+ */
+export class LocalContext {
+    root;
+    rules;
+    allowHardlinks;
+    ignore;
+    constructor(root, ignore, rules, allowHardlinks) {
+        this.root = root;
+        this.rules = rules;
+        this.allowHardlinks = allowHardlinks;
+        this.ignore = ignore.map((p) => posix.normalize(nfc(p)).replace(/^\.\/+/, '').replace(/\/+$/, '')).filter((p) => p !== '' && p !== '.');
+    }
+    static async open(dir, options) {
+        let root;
+        try {
+            root = await fs.realpath(dir);
+        }
+        catch (e) {
+            if (errCode(e) === 'ENOENT')
+                throw new SitefileError('E_NOT_FOUND', `build context '${dir}' does not exist`, undefined, { cause: e });
+            throw e;
+        }
+        const st = await fs.stat(root);
+        if (!st.isDirectory())
+            throw new SitefileError('E_UNSUPPORTED_FILE', `build context '${dir}' is not a directory`);
+        let rules = IgnoreRules.empty;
+        if (options?.sitefileignore !== false && (await exists(join(root, SITEFILEIGNORE)))) {
+            // Read through the sandbox: a symlinked .sitefileignore must stay inside the context.
+            const probe = new LocalContext(root, [], IgnoreRules.empty, true);
+            // A broken ignore file fails the build: skipping it could publish files it was meant to exclude.
+            const { real, st } = await probe.resolve(SITEFILEIGNORE).catch((e) => {
+                if (!(e instanceof SitefileError) || e.code !== 'E_NOT_FOUND')
+                    throw e;
+                throw new SitefileError('E_NOT_FOUND', `'${SITEFILEIGNORE}' is a symlink to a missing file; fix or remove it (its rules would otherwise be skipped)`, undefined, { cause: e });
+            });
+            if (!st.isFile())
+                throw new SitefileError('E_UNSUPPORTED_FILE', `'${SITEFILEIGNORE}' is not a regular file`);
+            rules = IgnoreRules.parse(nfc(await fs.readFile(real, 'utf8')));
+        }
+        return new LocalContext(root, options?.ignore ?? ['.git'], rules, options?.allowHardlinks ?? false);
+    }
+    inside(real) {
+        return real === this.root || real.startsWith(this.root.endsWith(sep) ? this.root : this.root + sep);
+    }
+    isIgnored(rel) {
+        return this.ignore.some((ig) => rel === ig || rel.startsWith(ig + '/'));
+    }
+    /** Hard-linked files may alias files outside the context, which realpath cannot detect. */
+    checkHardlink(st, rel, span) {
+        if (this.allowHardlinks || !st.isFile() || st.nlink <= 1)
+            return;
+        throw new SitefileError('E_HARDLINK', `'${display(rel)}' has ${st.nlink} hard links and may alias a file outside the build context (--allow-hardlinks permits this)`, span);
+    }
+    /** Context-relative POSIX path of a real path inside root. */
+    relOfReal(real) {
+        return relative(this.root, real).split(sep).join('/');
+    }
+    /** Resolve a context-relative path to its real path and stats, enforcing the sandbox. */
+    /** A context file's real path and bytes, with the usual sandbox, symlink and hard-link rules. */
+    async realFile(rel, span) {
+        const { real } = await this.resolve(rel, span);
+        const f = await this.readFile(rel, span);
+        return { real, bytes: f.bytes };
+    }
+    /**
+     * The host path of the context-relative (NFC) path `rel`. A non-ASCII
+     * segment is matched by NFC form against its directory listing, so a file
+     * is found whichever normalization its on-disk name uses (macOS stores what
+     * it was given, often NFD; Linux compares bytes). Two names in one
+     * directory with the same NFC form are E_PATH_COLLISION. A segment with no
+     * match is joined as is, so the caller sees the usual ENOENT.
+     */
+    async hostPath(rel, span) {
+        if (rel === '')
+            return this.root;
+        if (!NON_ASCII.test(rel))
+            return join(this.root, ...rel.split('/'));
+        let cur = this.root;
+        let done = '';
+        for (const seg of rel.split('/')) {
+            done = done === '' ? seg : `${done}/${seg}`;
+            if (!NON_ASCII.test(seg)) {
+                cur = join(cur, seg);
+                continue;
+            }
+            const names = await fs.readdir(cur).catch(() => []);
+            const matches = names.filter((n) => nfc(n) === seg);
+            if (matches.length > 1)
+                throw normalizationCollision(done, span);
+            cur = join(cur, matches[0] ?? seg);
+        }
+        return cur;
+    }
+    async resolve(rel, span, linkName) {
+        let real;
+        try {
+            real = await fs.realpath(await this.hostPath(rel, span));
+        }
+        catch (e) {
+            if (e instanceof SitefileError)
+                throw e;
+            const code = errCode(e);
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                throw new SitefileError('E_NOT_FOUND', linkName ? `symlink '${linkName}' is dangling` : `'${display(rel)}' does not exist in the build context`, span, { cause: e });
+            }
+            if (code === 'ELOOP') {
+                throw new SitefileError('E_UNSUPPORTED_FILE', `'${display(rel)}' is a symlink loop`, span, { cause: e });
+            }
+            throw new SitefileError('E_NOT_FOUND', `cannot resolve '${display(rel)}': ${e.message}`, span, { cause: e });
+        }
+        if (!this.inside(real)) {
+            throw new SitefileError('E_PATH_ESCAPE', linkName
+                ? `symlink '${linkName}' points outside the build context`
+                : `'${display(rel)}' resolves outside the build context`, span);
+        }
+        const st = await fs.stat(real);
+        return { real, st };
+    }
+    static kindOf(st, rel, span) {
+        if (st.isFile())
+            return 'file';
+        if (st.isDirectory())
+            return 'directory';
+        throw new SitefileError('E_UNSUPPORTED_FILE', `'${display(rel)}' is not a regular file or directory (sockets, fifos and devices are not supported)`, span);
+    }
+    async stat(rel, span) {
+        const { st } = await this.resolve(rel, span);
+        return LocalContext.kindOf(st, rel, span);
+    }
+    /** The real path of a context-relative path, with the sandbox checks of every read (an imported Sitefile's context). */
+    async realPath(rel, span) {
+        return (await this.resolve(rel, span)).real;
+    }
+    async readFile(rel, span) {
+        const { real, st } = await this.resolve(rel, span);
+        if (LocalContext.kindOf(st, rel, span) !== 'file') {
+            throw new SitefileError('E_UNSUPPORTED_FILE', `'${display(rel)}' is a directory, not a file`, span);
+        }
+        this.checkHardlink(st, rel, span);
+        const bytes = new Uint8Array(await fs.readFile(real));
+        return {
+            kind: 'file',
+            bytes,
+            mode: st.mode & 0o111 ? 0o755 : 0o644,
+            basename: posix.basename(rel),
+            provenance: { uri: './' + rel, digest: sha256(bytes) },
+        };
+    }
+    /** `exclude` (COPY --exclude) skips paths relative to `rel`, like `.sitefileignore` rules (excluded directories are not read). */
+    async readTree(rel, origin, span, exclude) {
+        const { real, st } = await this.resolve(rel, span);
+        if (LocalContext.kindOf(st, rel, span) !== 'directory') {
+            throw new SitefileError('E_UNSUPPORTED_FILE', `'${display(rel)}' is a file, not a directory`, span);
+        }
+        const files = [];
+        await this.walk(real, rel, '', origin, new Set([real]), files, span, exclude);
+        // With the instruction's span: two names that differ only in case (possible on a
+        // case-sensitive file system) fail at the line that read the directory.
+        const tree = Tree.empty.withFiles(files, 'error', span);
+        return { kind: 'tree', tree, provenance: { uri: rel === '' ? './' : './' + rel, digest: tree.digest() } };
+    }
+    /**
+     * @param realDir   real path of the directory being walked
+     * @param ctxRel    logical context-relative path of that directory
+     * @param treeRel   path of that directory inside the resulting tree ('' = root)
+     * @param ancestors real paths of directories on the current walk path (cycle detection)
+     */
+    async walk(realDir, ctxRel, treeRel, origin, ancestors, out, span, exclude) {
+        const entries = await fs.readdir(realDir, { withFileTypes: true });
+        const names = entries.map((d) => d.name).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const byName = new Map(entries.map((d) => [d.name, d]));
+        // Tree paths are NFC, so two names that differ only in normalization (possible
+        // on Linux, not on macOS) would be one path: refuse rather than pick one.
+        const seen = new Set();
+        for (const raw of names) {
+            const dirent = byName.get(raw);
+            const name = nfc(raw);
+            if (seen.has(name))
+                throw normalizationCollision(ctxRel === '' ? name : `${ctxRel}/${name}`, span);
+            seen.add(name);
+            const childCtx = ctxRel === '' ? name : `${ctxRel}/${name}`;
+            const childTree = treeRel === '' ? name : `${treeRel}/${name}`;
+            if (this.isIgnored(childCtx))
+                continue;
+            let childReal = join(realDir, raw);
+            let st;
+            if (dirent.isSymbolicLink()) {
+                const r = await this.resolve(childCtx, span, display(childCtx));
+                childReal = r.real;
+                st = r.st;
+                // A link to an ignored location (e.g. .git) is skipped too.
+                if (this.isIgnored(this.relOfReal(childReal)))
+                    continue;
+            }
+            else {
+                st = await fs.lstat(childReal);
+            }
+            if (this.rules.ignores(childCtx, st.isDirectory()))
+                continue;
+            if (exclude?.ignores(childTree, st.isDirectory()))
+                continue;
+            if (st.isFile()) {
+                this.checkHardlink(st, childCtx, span);
+                const bytes = new Uint8Array(await fs.readFile(childReal));
+                out.push(['/' + childTree, makeFile(bytes, origin, st.mode)]);
+            }
+            else if (st.isDirectory()) {
+                if (ancestors.has(childReal))
+                    continue; // directory symlink cycle
+                ancestors.add(childReal);
+                try {
+                    await this.walk(childReal, childCtx, childTree, origin, ancestors, out, span, exclude);
+                }
+                finally {
+                    ancestors.delete(childReal);
+                }
+            }
+            else {
+                throw new SitefileError('E_UNSUPPORTED_FILE', `'${display(childCtx)}' is not a regular file or directory (sockets, fifos and devices are not supported)`, span);
+            }
+        }
+    }
+}
+//# sourceMappingURL=local.js.map

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

@@ -0,0 +1,52 @@
+export interface LockEntry {
+    /** `sha256:<hex>` of the response body. */
+    readonly integrity: string;
+    /** Body size in bytes. */
+    readonly size: number;
+    /** Final URL after redirects. */
+    readonly resolved: string;
+}
+/** A container image reference (`BASE`) pinned to the digest its tag resolved to. */
+export interface ImageLockEntry {
+    /** `sha256:<hex>` of what the tag pointed at: an image index or a manifest. */
+    readonly digest: string;
+}
+/** A Git IMPORT (`git+https://…#ref:path`, keyed by the URI as written) pinned to the commit its ref resolved to. */
+export interface GitLockEntry {
+    /** 40 lowercase hex digits. */
+    readonly commit: string;
+}
+/** `Sitefile.lock`: pinned digests of remote resources. */
+export declare class Lockfile {
+    readonly path: string;
+    private existed;
+    private originalText;
+    private readonly entries;
+    private readonly used;
+    private readonly images;
+    private readonly usedImages;
+    private readonly gits;
+    private readonly usedGits;
+    private constructor();
+    static load(path: string): Promise<Lockfile>;
+    /** The commit a Git IMPORT URI was locked to. */
+    getGit(url: string): GitLockEntry | undefined;
+    recordGit(url: string, entry: GitLockEntry): void;
+    /** The pinned digest for a canonical image reference (`docker.io/library/nginx:alpine`). */
+    getImage(ref: string): ImageLockEntry | undefined;
+    recordImage(ref: string, entry: ImageLockEntry): void;
+    markImageUsed(ref: string): void;
+    get(url: string): LockEntry | undefined;
+    /** Add or replace an entry and mark it used in this build. */
+    record(url: string, entry: LockEntry): void;
+    /** Keep an existing entry in the saved lockfile. */
+    markUsed(url: string): void;
+    /** The JSON text `save()` would write. */
+    serialize(): string;
+    /**
+     * Write the entries used in this build. Returns true if the file was
+     * written. Does nothing when the content is unchanged, and never creates
+     * a lockfile that would have no entries.
+     */
+    save(): Promise<boolean>;
+}

package/lib/src/resources/lockfile.js

@@ -0,0 +1,172 @@
+import { promises as fs } from 'node:fs';
+import { SitefileError } from '../errors.js';
+import { INTEGRITY_RE } from '../digest.js';
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** `Sitefile.lock`: pinned digests of remote resources. */
+export class Lockfile {
+    path;
+    existed;
+    originalText;
+    entries;
+    used = new Set();
+    images = new Map();
+    usedImages = new Set();
+    gits = new Map();
+    usedGits = new Set();
+    constructor(path, entries, existed, originalText) {
+        this.path = path;
+        this.existed = existed;
+        this.originalText = originalText;
+        this.entries = entries;
+    }
+    static async load(path) {
+        let text;
+        try {
+            text = await fs.readFile(path, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return new Lockfile(path, new Map(), false, undefined);
+            throw e;
+        }
+        const bad = (why, cause) => new SitefileError('E_VALIDATION', `malformed lockfile ${path}: ${why}`, undefined, cause ? { cause } : undefined);
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch (e) {
+            throw bad(e.message, e);
+        }
+        if (!isObject(data))
+            throw bad('expected a JSON object');
+        if (data.version !== 1)
+            throw bad(`unsupported version ${JSON.stringify(data.version)} (expected 1)`);
+        const resources = data.resources ?? {};
+        if (!isObject(resources))
+            throw bad('"resources" must be an object');
+        const entries = new Map();
+        for (const [url, raw] of Object.entries(resources)) {
+            if (!isObject(raw))
+                throw bad(`entry for ${url} must be an object`);
+            const { integrity, size, resolved } = raw;
+            if (typeof integrity !== 'string' || !INTEGRITY_RE.test(integrity)) {
+                throw bad(`entry for ${url} has an invalid "integrity" (expected sha256:<64 hex>)`);
+            }
+            if (typeof size !== 'number' || !Number.isSafeInteger(size) || size < 0) {
+                throw bad(`entry for ${url} has an invalid "size"`);
+            }
+            if (typeof resolved !== 'string')
+                throw bad(`entry for ${url} has an invalid "resolved"`);
+            entries.set(url, { integrity, size, resolved });
+        }
+        const lock = new Lockfile(path, entries, true, text);
+        const images = data.images ?? {};
+        if (!isObject(images))
+            throw bad('"images" must be an object');
+        for (const [ref, raw] of Object.entries(images)) {
+            if (!isObject(raw) || typeof raw.digest !== 'string' || !INTEGRITY_RE.test(raw.digest)) {
+                throw bad(`image entry for ${ref} needs a "digest" (sha256:<64 hex>)`);
+            }
+            lock.images.set(ref, { digest: raw.digest });
+        }
+        const gits = data.git ?? {};
+        if (!isObject(gits))
+            throw bad('"git" must be an object');
+        for (const [url, raw] of Object.entries(gits)) {
+            if (!isObject(raw) || typeof raw.commit !== 'string' || !/^[0-9a-f]{40}$/.test(raw.commit)) {
+                throw bad(`git entry for ${url} needs a "commit" (40 lowercase hex digits)`);
+            }
+            lock.gits.set(url, { commit: raw.commit });
+        }
+        return lock;
+    }
+    /** The commit a Git IMPORT URI was locked to. */
+    getGit(url) {
+        return this.gits.get(url);
+    }
+    recordGit(url, entry) {
+        this.gits.set(url, { commit: entry.commit });
+        this.usedGits.add(url);
+    }
+    /** The pinned digest for a canonical image reference (`docker.io/library/nginx:alpine`). */
+    getImage(ref) {
+        return this.images.get(ref);
+    }
+    recordImage(ref, entry) {
+        this.images.set(ref, { digest: entry.digest });
+        this.usedImages.add(ref);
+    }
+    markImageUsed(ref) {
+        if (this.images.has(ref))
+            this.usedImages.add(ref);
+    }
+    get(url) {
+        return this.entries.get(url);
+    }
+    /** Add or replace an entry and mark it used in this build. */
+    record(url, entry) {
+        this.entries.set(url, { integrity: entry.integrity, size: entry.size, resolved: entry.resolved });
+        this.used.add(url);
+    }
+    /** Keep an existing entry in the saved lockfile. */
+    markUsed(url) {
+        if (this.entries.has(url))
+            this.used.add(url);
+    }
+    /** The JSON text `save()` would write. */
+    serialize() {
+        const resources = {};
+        for (const url of [...this.used].sort()) {
+            const e = this.entries.get(url);
+            if (e)
+                resources[url] = { integrity: e.integrity, size: e.size, resolved: e.resolved };
+        }
+        const data = { version: 1, resources };
+        if (this.usedImages.size > 0) {
+            const images = {};
+            for (const ref of [...this.usedImages].sort()) {
+                const e = this.images.get(ref);
+                if (e)
+                    images[ref] = { digest: e.digest };
+            }
+            data.images = images;
+        }
+        if (this.usedGits.size > 0) {
+            const gits = {};
+            for (const url of [...this.usedGits].sort()) {
+                const e = this.gits.get(url);
+                if (e)
+                    gits[url] = { commit: e.commit };
+            }
+            data.git = gits;
+        }
+        return JSON.stringify(data, null, 2) + '\n';
+    }
+    /**
+     * Write the entries used in this build. Returns true if the file was
+     * written. Does nothing when the content is unchanged, and never creates
+     * a lockfile that would have no entries.
+     */
+    async save() {
+        const text = this.serialize();
+        if (!this.existed && this.used.size === 0 && this.usedImages.size === 0 && this.usedGits.size === 0)
+            return false;
+        if (this.existed && text === this.originalText)
+            return false;
+        const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            await fs.writeFile(tmp, text);
+            await fs.rename(tmp, this.path);
+            this.existed = true;
+            this.originalText = text;
+        }
+        catch (e) {
+            await fs.rm(tmp, { force: true });
+            throw e;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=lockfile.js.map

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

@@ -0,0 +1,6 @@
+/**
+ * True when `address` is an IP literal that is publicly routable. Loopback,
+ * private, link-local, CGNAT, documentation, multicast, reserved and every
+ * IPv4-mapped IPv6 address are not public. Non-IP strings return false.
+ */
+export declare function isPublicAddress(address: string): boolean;

package/lib/src/resources/netpolicy.js

@@ -0,0 +1,82 @@
+import { BlockList, isIP } from 'node:net';
+// Separate lists: a BlockList checks IPv4 addresses against IPv4-mapped IPv6
+// rules too, so `::ffff:0:0/96` in a shared list would block every IPv4.
+const blocked4 = new BlockList();
+const blocked6 = new BlockList();
+const V4 = [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4], // includes 255.255.255.255
+];
+const V6 = [
+    ['::', 128],
+    ['::1', 128],
+    ['::ffff:0:0', 96], // all IPv4-mapped addresses
+    ['64:ff9b:1::', 48],
+    ['100::', 64],
+    ['2001:db8::', 32],
+    ['fc00::', 7],
+    ['fe80::', 10],
+    ['ff00::', 8],
+];
+for (const [net, prefix] of V4)
+    blocked4.addSubnet(net, prefix, 'ipv4');
+for (const [net, prefix] of V6)
+    blocked6.addSubnet(net, prefix, 'ipv6');
+/**
+ * True when `address` is an IP literal that is publicly routable. Loopback,
+ * private, link-local, CGNAT, documentation, multicast, reserved and every
+ * IPv4-mapped IPv6 address are not public. Non-IP strings return false.
+ */
+export function isPublicAddress(address) {
+    let a = address;
+    if (a.startsWith('[') && a.endsWith(']'))
+        a = a.slice(1, -1);
+    // Zone IDs (fe80::1%en0) are link-local by definition.
+    if (a.includes('%'))
+        return false;
+    const family = isIP(a);
+    if (family === 4)
+        return !blocked4.check(a, 'ipv4');
+    if (family === 6) {
+        if (blocked6.check(a, 'ipv6'))
+            return false;
+        // NAT64 well-known prefix 64:ff9b::/96 embeds an IPv4 address in the low
+        // 32 bits; judge it by that address (64:ff9b::7f00:1 is 127.0.0.1).
+        const groups = expandIPv6(a);
+        if (groups && groups[0] === 0x64 && groups[1] === 0xff9b && groups.slice(2, 6).every((g) => g === 0)) {
+            const hi = groups[6];
+            const lo = groups[7];
+            return !blocked4.check(`${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`, 'ipv4');
+        }
+        return true;
+    }
+    return false;
+}
+/** Eight 16-bit groups of a valid IPv6 literal (which may end in dotted IPv4). */
+function expandIPv6(a) {
+    let s = a.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 zeros = tail === undefined ? [] : new Array(8 - h.length - t.length).fill('0');
+    const all = [...h, ...zeros, ...t].map((g) => parseInt(g, 16));
+    return all.length === 8 ? all : undefined;
+}
+//# sourceMappingURL=netpolicy.js.map

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

@@ -0,0 +1,63 @@
+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;
+}
+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