@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

package/lib/src/export/pdfEngine.js

@@ -0,0 +1,195 @@
+/**
+ * The HTML → PDF engine (#1974): the options and the error every provider
+ * shares, and the child process the `local-chrome` provider renders in
+ * (headless Chromium, driven by `playwright-core`, both optional at run time).
+ *
+ * - `resolveChromium` finds a Chromium to run: the configured path, then the
+ *   one Playwright installed (`npx playwright install chromium`), then the
+ *   usual system locations. Nothing is downloaded at `npm install`.
+ * - `renderPdfInChild` renders one document in a child process
+ *   (`pdfRenderWorker.ts`), killed at the timeout, so the site never waits on
+ *   Chromium or on PDF parsing.
+ * - `normalizePdfInChild` gives a PDF a PDF service made (the
+ *   `chrome-service` provider) the same metadata pass, in the same kind of
+ *   child, so parsing it never runs on the thread that answers requests.
+ *
+ * `ExportManager.htmlToPdf` is the door, through its providers
+ * (`PdfProvider.ts`); nothing else calls these.
+ */
+import { fork } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/** Page sizes Chromium knows by name. */
+export const PDF_PAGE_SIZES = ['Letter', 'Legal', 'Tabloid', 'Ledger', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6'];
+/** A CSS length Chromium's PDF margins accept: a number and px, in, cm or mm. */
+const MARGIN = /^\d+(\.\d+)?(px|in|cm|mm)$/;
+/**
+ * No PDF engine: `playwright-core` is not installed, no Chromium was found, or
+ * it could not start. An add-on catches it by `code` (it cannot import core
+ * values) and falls back to HTML.
+ */
+export class PdfUnavailableError extends Error {
+    code = 'PDF_UNAVAILABLE';
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PdfUnavailableError';
+    }
+}
+/**
+ * Validate a caller's options and fill the defaults. Throws on anything
+ * Chromium would misread, so a typo is an error rather than a different page.
+ *
+ * @param options - The caller's options
+ * @param defaultFormat - `ngdpbase.export.pdf.page-size`
+ */
+export function resolvePdfOptions(options, defaultFormat) {
+    const opts = options ?? {};
+    if (typeof opts !== 'object')
+        throw new TypeError('htmlToPdf: options must be an object');
+    const format = opts.format ?? defaultFormat;
+    if (!PDF_PAGE_SIZES.includes(format)) {
+        throw new TypeError(`htmlToPdf: format must be one of ${PDF_PAGE_SIZES.join(', ')} (got ${JSON.stringify(format)})`);
+    }
+    const margin = {};
+    for (const side of ['top', 'right', 'bottom', 'left']) {
+        const value = opts.margin?.[side];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string' || !MARGIN.test(value)) {
+            throw new TypeError(`htmlToPdf: margin.${side} must be a length such as '20mm' or '0.5in' (got ${JSON.stringify(value)})`);
+        }
+        margin[side] = value;
+    }
+    const printBackground = opts.printBackground ?? true;
+    if (typeof printBackground !== 'boolean')
+        throw new TypeError('htmlToPdf: printBackground must be a boolean');
+    return { format: format, margin, printBackground };
+}
+/** Where Chromium or Chrome usually is, per platform. Checked after the configured path and Playwright's own. */
+export const SYSTEM_CHROMIUM_PATHS = {
+    linux: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/lib/chromium/chromium', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/snap/bin/chromium'],
+    darwin: ['/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],
+    win32: ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe']
+};
+const requireHere = createRequire(import.meta.url);
+/** Whether `playwright-core` is installed (it is an optional dependency). */
+export function playwrightInstalled() {
+    try {
+        requireHere.resolve('playwright-core');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function playwrightChromiumPath() {
+    try {
+        const { chromium } = await import('playwright-core');
+        return chromium.executablePath() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find a Chromium to render with. Read on every call, so installing Chromium
+ * or setting the path takes effect without a restart.
+ *
+ * @param configuredPath - `ngdpbase.export.pdf.provider.local-chrome.chromium-path` ('' = find one)
+ */
+export async function resolveChromium(configuredPath, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    if (!(deps.playwrightInstalled ?? playwrightInstalled)()) {
+        return { ok: false, reason: 'playwright-core is not installed (it is an optional dependency; npm install without --omit=optional)' };
+    }
+    if (configuredPath) {
+        return exists(configuredPath)
+            ? { ok: true, executablePath: configuredPath, source: 'configured' }
+            : { ok: false, reason: `ngdpbase.export.pdf.provider.local-chrome.chromium-path is set, but nothing is there: ${configuredPath}` };
+    }
+    const bundled = await (deps.playwrightChromium ?? playwrightChromiumPath)();
+    if (bundled && exists(bundled))
+        return { ok: true, executablePath: bundled, source: 'playwright' };
+    for (const candidate of SYSTEM_CHROMIUM_PATHS[deps.platform ?? process.platform] ?? []) {
+        if (exists(candidate))
+            return { ok: true, executablePath: candidate, source: 'system' };
+    }
+    return { ok: false, reason: 'no Chromium found: install Chromium, or set ngdpbase.export.pdf.provider.local-chrome.chromium-path' };
+}
+/**
+ * The environment the child gets: enough to find a home, a temp folder and
+ * fonts, and none of the site's secrets (the session secret, keys and
+ * passwords the site holds in its environment).
+ */
+const CHILD_ENV_KEYS = [
+    'PATH', 'HOME', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'PLAYWRIGHT_BROWSERS_PATH',
+    'FONTCONFIG_PATH', 'FONTCONFIG_FILE', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR',
+    'SystemRoot', 'LOCALAPPDATA', 'USERPROFILE', 'APPDATA', 'ProgramFiles', 'ProgramFiles(x86)'
+];
+export function childEnv(env = process.env) {
+    const out = {};
+    for (const key of CHILD_ENV_KEYS)
+        if (env[key] !== undefined)
+            out[key] = env[key];
+    return out;
+}
+/**
+ * Render one job in a child process. Resolves with the child's answer; rejects
+ * only when the child timed out, crashed or never answered.
+ *
+ * @param job - The render
+ */
+export function renderPdfInChild(job) {
+    return runPdfChild(job);
+}
+/**
+ * Normalise a PDF in a child process (`normalizePdf`, the same pass a local
+ * render gets). Rejects when the bytes are not a PDF pdf-lib can read, or the
+ * child times out.
+ *
+ * @param pdf - A PDF a PDF service returned
+ * @param timeoutMs - The child is killed after this
+ */
+export async function normalizePdfInChild(pdf, timeoutMs) {
+    const result = await runPdfChild({ kind: 'normalize', pdf, timeoutMs });
+    if (!result.ok)
+        throw new Error(`the PDF could not be read: ${result.error}`);
+    return result.pdf;
+}
+function runPdfChild(job) {
+    // Compiled, the worker is the .js beside this file. From source (vitest,
+    // tsx) it is the .ts, which needs tsx's loader.
+    const fromSource = import.meta.url.endsWith('.ts');
+    const entry = new URL(fromSource ? './pdfRenderWorker.ts' : './pdfRenderWorker.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const child = fork(entry, [], {
+            execArgv: fromSource ? ['--import', 'tsx'] : [],
+            env: childEnv(),
+            serialization: 'advanced',
+            stdio: ['ignore', 'ignore', 'pipe', 'ipc']
+        });
+        let settled = false;
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { if (stderr.length < 2000)
+            stderr += chunk.toString(); });
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`PDF render timed out after ${job.timeoutMs} ms`)));
+            child.kill('SIGKILL');
+        }, job.timeoutMs);
+        child.once('message', (result) => {
+            settle(() => resolve(result.ok ? { ok: true, pdf: Buffer.from(result.pdf) } : result));
+        });
+        child.once('error', (err) => settle(() => reject(err)));
+        child.once('exit', (code, signal) => {
+            settle(() => reject(new Error(`PDF render process exited (${signal ?? code}) without an answer${stderr ? `: ${stderr.trim().split('\n')[0]}` : ''}`)));
+        });
+        child.send(job);
+    });
+}

package/lib/src/http/egressPolicy.js

@@ -0,0 +1,61 @@
+/**
+ * Configuration to policy (#1133).
+ *
+ * The operator sets two CIDR lists; this turns them into the `EgressPolicy`
+ * the guard enforces, and reconciles them at BOOT so a contradiction is a
+ * startup message rather than one dropped image months later — which would
+ * surface as a `fetch` warning indistinguishable from the remote host being
+ * down.
+ *
+ * Contradictions resolve by FIREWALL CONVENTION and none of them stops the
+ * boot (#1144, D8). #1133 chose longest-prefix match — the routing rule,
+ * because the values are routes — so a general overlap is not a conflict at
+ * all. The cases longest prefix cannot decide are settled here: an allow entry
+ * reaching the mechanism is unsatisfiable and dropped, and a range in both
+ * lists is a prefix-length tie the DENY wins.
+ *
+ * `ngdpbase.security.profile` used to decide whether a contradiction stopped
+ * the boot. That was the profile looking for a job: `iptables` rejects a bad
+ * rule and keeps the chain, and the Kubernetes API server rejects an invalid
+ * NetworkPolicy while the others keep applying. Neither takes the workload
+ * down. The one case with no safe silent resolution — a malformed range, where
+ * dropping a DENY fails open — is reported separately for #1152.
+ */
+import { reconcilePolicy } from './ssrf.js';
+export const DENIED_RANGES_KEY = 'ngdpbase.security.egress.denied-ranges';
+export const ALLOWED_RANGES_KEY = 'ngdpbase.security.egress.allowed-ranges';
+/** Only strings can be CIDRs; anything else in the list is discarded, not coerced. */
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/**
+ * Read the configured ranges, reconcile them, and report what could not be
+ * resolved.
+ *
+ * A contradiction never widens access. Where the two lists disagree the
+ * stricter reading wins, which is the only direction a security control should
+ * fail when nobody can be asked.
+ */
+export function resolveEgressPolicy(read) {
+    const deniedRanges = stringList(read(DENIED_RANGES_KEY, []));
+    const allowedRanges = stringList(read(ALLOWED_RANGES_KEY, []));
+    const { conflicts, malformed, duplicates } = reconcilePolicy(deniedRanges, allowedRanges);
+    const unusable = new Set(malformed);
+    // An allow entry is dropped when it cannot be parsed, when it reaches the
+    // mechanism, or when the same range is also denied. The last is D8's tie
+    // break: equal prefix lengths give longest-prefix nothing to work with, so
+    // the deny wins.
+    const safeAllowed = allowedRanges.filter((range) => !unusable.has(range)
+        && !duplicates.includes(range)
+        && !conflicts.some((c) => c.startsWith('allowed-ranges:') && c.includes(`'${range}'`)));
+    // A denied range is dropped ONLY when it cannot be parsed. Previously a
+    // range appearing in both lists was removed from here too, so the operator's
+    // stricter statement was discarded along with the looser one and the range
+    // fell back to the built-in defaults.
+    const safeDenied = deniedRanges.filter((range) => !unusable.has(range));
+    return {
+        policy: { deniedRanges: safeDenied, allowedRanges: safeAllowed },
+        conflicts,
+        malformed
+    };
+}

package/lib/src/http/guardedElasticsearch.d.ts

@@ -0,0 +1,27 @@
+import { Client, type ClientOptions } from '@elastic/elasticsearch';
+import { type Resolver } from './guardedLookup.js';
+import { type ConfigReader } from './egressPolicy.js';
+import { type EgressPolicy } from './ssrf.js';
+export interface GuardedElasticsearchOptions {
+    /** Per-request timeout in ms; the SDK's default when omitted. */
+    requestTimeout?: number;
+    /**
+     * The resolution step, for tests only — the same single seam `guardedLookup`
+     * exposes. Production leaves it unset and `node:dns` answers.
+     */
+    resolver?: Resolver;
+}
+/**
+ * The options that make a client guarded. Exported so a test can assert the
+ * wiring — that the connection class is the `http` one and that its agents
+ * carry the guarded lookup and the guarded connect — without opening a socket.
+ */
+export declare function guardedClientOptions(node: string, policy: EgressPolicy, options?: GuardedElasticsearchOptions): ClientOptions;
+/** An Elasticsearch client whose every connection is subject to the instance's egress policy. */
+export declare function createGuardedElasticsearchClient(node: string, read: ConfigReader, options?: GuardedElasticsearchOptions): Client;
+/**
+ * The boot-time line both call sites log when the configured node would be
+ * refused — one sentence, the same shape as sist2's (#1186), so the operator
+ * is sent to the egress configuration and not to the Elasticsearch host.
+ */
+export declare function refusedNodeMessage(who: string, node: string, reason: string): string;

package/lib/src/http/guardedElasticsearch.js

@@ -0,0 +1,99 @@
+/**
+ * The Elasticsearch client, built inside the boundary (#1188).
+ *
+ * `@elastic/elasticsearch` opens sockets the same way `fetch` does, and until
+ * #1188 it did so from two places outside `src/http/` — the search provider
+ * and the elasticsearch addon — with `new Client({ node })` and no policy at
+ * all. The boundary check (#1139) could not see it because the SDK was not in
+ * its list of client modules, so the guard read green while the process
+ * connected to whatever `es-url` said, loopback and RFC1918 included.
+ *
+ * This is the only place the SDK is constructed. It hands the client Node's
+ * `http` connection class with agents whose `lookup` is the guarded one, so
+ * every socket the client opens — the first request, a retry, a sniffed node —
+ * is judged against the instance's egress policy at connect time, exactly as
+ * `guardedFetch` does. There is no ungated constructor to reach for: the
+ * scanner now names the SDK, so an `import { Client }` outside this directory
+ * fails `lint:http`.
+ *
+ * What this means for an operator: an Elasticsearch node on `localhost` is
+ * refused — loopback is mechanism, not policy (#1186), and no allow entry
+ * opens it. A node on the LAN needs its prefix in
+ * `ngdpbase.security.egress.allowed-ranges`, the same as sist2. Both call
+ * sites say so at boot when the configured address would be refused.
+ */
+import { Agent as HttpAgent } from 'node:http';
+import { Agent as HttpsAgent } from 'node:https';
+import { isIP } from 'node:net';
+import { Client, HttpConnection } from '@elastic/elasticsearch';
+import { ESSRF_BLOCKED, guardedLookup } from './guardedLookup.js';
+import { resolveEgressPolicy } from './egressPolicy.js';
+import { isAddressAllowed, REFUSAL } from './ssrf.js';
+/**
+ * The connect step, guarding the case the lookup never sees.
+ *
+ * Node calls an agent's `lookup` only for a NAME. A URL whose host is an IP
+ * literal — `http://192.168.0.10:9200`, `http://127.0.0.1:9200` — goes
+ * straight to the socket, so a guard that lives only in `lookup` waves every
+ * literal address through. Found by pointing the first version of this at
+ * jimstest's LAN node under an empty policy and watching `ping` return true.
+ * `guardedFetch` covers the same hole with `validateUrl` before each hop;
+ * here the judgement sits in `createConnection`, which every socket passes
+ * through, literal or resolved.
+ */
+function guardedCreateConnection(policy, connect) {
+    return function guarded(options, callback) {
+        const host = String(options.host ?? options.hostname ?? 'localhost');
+        if (isIP(host) && !isAddressAllowed(host, policy)) {
+            const err = Object.assign(new Error(`${REFUSAL}: ${host}`), { code: ESSRF_BLOCKED });
+            if (callback) {
+                process.nextTick(callback, err);
+                return undefined;
+            }
+            throw err;
+        }
+        // Node's own connect for this agent — `net.createConnection` for http,
+        // the TLS one for https. The agent has merged its options in, so `lookup`
+        // (the guarded one) rides along for a host that is a name.
+        return connect.call(this, options, callback);
+    };
+}
+/**
+ * The options that make a client guarded. Exported so a test can assert the
+ * wiring — that the connection class is the `http` one and that its agents
+ * carry the guarded lookup and the guarded connect — without opening a socket.
+ */
+export function guardedClientOptions(node, policy, options = {}) {
+    // keepAlive stays on, as the SDK's own default agent has it: a kept socket
+    // was judged when it was opened, and both guards run again for every new one.
+    const lookup = guardedLookup(policy, options.resolver);
+    const agents = { http: new HttpAgent({ lookup, keepAlive: true }), https: new HttpsAgent({ lookup, keepAlive: true }) };
+    // `createConnection` is a method of the agent, not an option it accepts:
+    // Node reads `this.createConnection` when it opens a socket. Replaced on the
+    // instance, wrapping the prototype's own so TLS setup stays Node's.
+    const method = (agent) => Object.getPrototypeOf(agent).createConnection;
+    agents.http.createConnection =
+        guardedCreateConnection(policy, method(agents.http));
+    agents.https.createConnection =
+        guardedCreateConnection(policy, method(agents.https));
+    return {
+        node,
+        ...(options.requestTimeout !== undefined ? { requestTimeout: options.requestTimeout } : {}),
+        Connection: HttpConnection,
+        agent: (connection) => (connection.url.protocol === 'https:' ? agents.https : agents.http)
+    };
+}
+/** An Elasticsearch client whose every connection is subject to the instance's egress policy. */
+export function createGuardedElasticsearchClient(node, read, options = {}) {
+    return new Client(guardedClientOptions(node, resolveEgressPolicy(read).policy, options));
+}
+/**
+ * The boot-time line both call sites log when the configured node would be
+ * refused — one sentence, the same shape as sist2's (#1186), so the operator
+ * is sent to the egress configuration and not to the Elasticsearch host.
+ */
+export function refusedNodeMessage(who, node, reason) {
+    return (`[${who}] Elasticsearch node ${node} is refused by the egress policy (${reason}). ` +
+        'Loopback and link-local can never be opened; a LAN address needs its prefix in ' +
+        'ngdpbase.security.egress.allowed-ranges. Every request to it will fail. (#1188)');
+}

package/lib/src/ice/converterShim.d.ts

@@ -0,0 +1,5 @@
+import type { IContentConverter } from '../converters/IContentConverter.js';
+import type { IceShim } from './types.js';
+/** The receiver today's converters hand to. */
+export declare const PAGES_RECEIVER = "core.pages";
+export declare function converterShim(converter: IContentConverter, tableClasses: () => string[]): IceShim;

package/lib/src/ice/fileHandling.d.ts

@@ -0,0 +1,30 @@
+import { type ZipReadLimits } from '../utils/zipArchive.js';
+import type { IceUpload } from './types.js';
+/** A file's fingerprint: SHA-256 of its bytes, hex. */
+export declare function fingerprint(bytes: Buffer): string;
+/**
+ * Is this path noise — something an operating system or archiver adds that is
+ * nobody's data? Patterns (configuration, `ngdpbase.import.engine.noise`):
+ *
+ * - `name/` — any path with a directory segment of that name (`__MACOSX/`);
+ * - `prefix*` / `*suffix` — a file name starting or ending so (`._*`);
+ * - anything else — a file name exactly (`.DS_Store`), case-insensitive.
+ */
+export declare function isNoise(filePath: string, patterns: readonly string[]): boolean;
+/** Is this upload a zip archive the engine unpacks? By its name, or its media type. */
+export declare function isZip(upload: IceUpload): boolean;
+/**
+ * Unpack the zips among the uploads into the files they hold, named
+ * `archive.zip/inner/path`. A nested zip is unpacked too. Everything else is
+ * passed through. Limits are per archive (`ZipReadLimits`), so a small
+ * archive that expands enormously stops at the budget. An archive that cannot
+ * be read is returned in `unreadable`, with why; the rest go on.
+ */
+export declare function expandUploads(uploads: readonly IceUpload[], limits: ZipReadLimits, maxDepth: number, depth?: number): {
+    files: IceUpload[];
+    unreadable: Array<{
+        name: string;
+        size: number;
+        message: string;
+    }>;
+};

package/lib/src/ice/ledger.d.ts

@@ -0,0 +1,37 @@
+import type { IceLedger, LedgerFileEntry } from './types.js';
+interface ScopeFile {
+    scope: string;
+    files: LedgerFileEntry[];
+    items: string[];
+}
+/** Keeps the newest entry per fingerprint, at most `maxEntries` files and item keys per scope. */
+declare abstract class ScopedLedger implements IceLedger {
+    private readonly maxEntries;
+    constructor(maxEntries: number);
+    protected abstract load(scope: string): Promise<ScopeFile>;
+    protected abstract save(data: ScopeFile): Promise<void>;
+    /** One writer per scope at a time, so two runs in one scope cannot lose each other's entries. */
+    private readonly chains;
+    private serial;
+    lastFile(scope: string, sha256: string): Promise<LedgerFileEntry | null>;
+    recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
+    hasItem(scope: string, itemKey: string): Promise<boolean>;
+    recordItem(scope: string, itemKey: string): Promise<void>;
+    files(scope: string): Promise<LedgerFileEntry[]>;
+}
+/** The ledger in memory: for tests, and for a site that keeps no import history. */
+export declare class MemoryIceLedger extends ScopedLedger {
+    private readonly scopes;
+    constructor(maxEntries?: number);
+    protected load(scope: string): Promise<ScopeFile>;
+    protected save(data: ScopeFile): Promise<void>;
+}
+/** One JSON file per scope, named by the scope's hash (a scope holds a username). */
+export declare class FileIceLedger extends ScopedLedger {
+    private readonly dir;
+    constructor(dir: string, maxEntries: number);
+    private fileFor;
+    protected load(scope: string): Promise<ScopeFile>;
+    protected save(data: ScopeFile): Promise<void>;
+}
+export {};

package/lib/src/ice/runImport.d.ts

@@ -0,0 +1,51 @@
+import type { ActorContext } from '../context/ActorContext.js';
+import type { ZipReadLimits } from '../utils/zipArchive.js';
+import type { IceItem, IceLedger, IceRunReport, IceRunRequest, OriginalChoice, RegisteredReceiver, RegisteredShim, ShimTools } from './types.js';
+/** Configuration the engine reads (each a key under `ngdpbase.import.engine.`). */
+export interface IceEngineSettings {
+    noise: string[];
+    zip: ZipReadLimits;
+    maxZipDepth: number;
+    maxFileBytes: number;
+    maxChainDepth: number;
+    defaultOriginal: OriginalChoice;
+}
+export interface IceRunDeps {
+    /** Enabled shims, in registration order. */
+    shims: RegisteredShim[];
+    receivers: ReadonlyMap<string, RegisteredReceiver>;
+    ledger: IceLedger;
+    settings: IceEngineSettings;
+    tools(shim: RegisteredShim): ShimTools;
+    now?: () => Date;
+}
+/** The id of the receiver that keeps an original when the chosen receiver does not keep its own (D11). */
+export declare const FILES_RECEIVER = "core.files";
+/** The scope a run's fingerprints are checked in, unless the caller names one. */
+export declare function defaultScope(receiverId: string, ctx: ActorContext): string;
+export interface ChainLeaf {
+    item: IceItem;
+    chain: string[];
+}
+/** What a chain needs: the shims it may continue through, and where it stops. */
+export interface ChainSpec {
+    shims: RegisteredShim[];
+    tools(shim: RegisteredShim): ShimTools;
+    maxChainDepth: number;
+    /** Does this item, from this shim, stop here? */
+    done(shim: RegisteredShim, item: IceItem): boolean;
+    /** Named in the error when nothing takes an item further. */
+    target: string;
+}
+/**
+ * Run a shim, then the shims after it (D9), until each item is done. What
+ * came before travels with each item: earlier metadata under later, earlier
+ * warnings first. Partial notes are collected into `partial`.
+ */
+export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[]): Promise<ChainLeaf[]>;
+/**
+ * Run one import. Fills and returns `report`, which the caller may be
+ * showing while it runs. Never throws for one file's failure; that file's
+ * status says why.
+ */
+export declare function runImport(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, report: IceRunReport): Promise<IceRunReport>;