@hraness/sponge 0.5.3 → 0.6.1

package/dist/src/acquisition/runtime.js

@@ -1,273 +0,0 @@
-import { mkdir, mkdtemp, writeFile, rename, rm, chmod, statfs, lstat, readdir, readlink, realpath, } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import { runOwned, isolatedEnvironment } from './process.js';
-import { privateRoot, readConfined, physicalBytes } from './files.js';
-import { sha256 as hash } from '../util/hash.js';
-import { SpongeError } from '../errors.js';
-// Retained inventory excludes the isolated Bun cache and temporary Bun zip.
-const budget = 1024 ** 3;
-const stagingBudget = 2 * budget;
-// The frozen dependency install measured 460 s on a slow link; 300 s aborted valid setups.
-const installDeadlineMs = 30 * 60 * 1000;
-function checkPins(pins) {
-    if (!/^[a-z0-9][a-z0-9.-]{0,99}$/.test(pins.id) || hash(pins.lockfile) !== pins.lockSha256)
-        throw new SpongeError('invalid-input');
-    for (const pin of [pins.bun, pins.wordcell]) {
-        let url;
-        try {
-            url = new URL(pin.url);
-        }
-        catch {
-            throw new SpongeError('invalid-input');
-        }
-        if (!/^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.-]+)?$/.test(pin.version) ||
-            !/^[a-f0-9]{64}$/.test(pin.sha256) ||
-            !Number.isSafeInteger(pin.bytes) ||
-            pin.bytes < 1 ||
-            pin.bytes > budget ||
-            url.protocol !== 'https:' ||
-            url.username ||
-            url.password)
-            throw new SpongeError('invalid-input');
-    }
-    if (!/^[a-z0-9][a-z0-9.-]*\/bun$/.test(pins.bun.archiveExecutable) ||
-        !/^[a-f0-9]{64}$/.test(pins.bun.executableSha256))
-        throw new SpongeError('invalid-input');
-}
-export function captureSetupPlan(pins) {
-    checkPins(pins);
-    const artifacts = [pins.bun, pins.wordcell], downloadBytes = artifacts.reduce((n, a) => n + a.bytes, 0);
-    return {
-        artifacts,
-        downloadBytes,
-        installationBudgetBytes: budget,
-        stagingBudgetBytes: stagingBudget,
-        installationBudgetKind: 'monitored',
-        installationDeadlineMs: installDeadlineMs,
-        dependencyDownloads: 'frozen-lock',
-        requiredFreeBytes: 2 * 1024 ** 3 + budget + stagingBudget + downloadBytes,
-        capabilities: ['article-http', 'selected-attached-browser', 'verified-offline-images'],
-    };
-}
-async function download(pin, path, signal) {
-    const boundedSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(120000)]) : AbortSignal.timeout(120000);
-    const response = await fetch(pin.url, { signal: boundedSignal });
-    if (!response.ok || !response.body || new URL(response.url).protocol !== 'https:')
-        throw new SpongeError('unavailable');
-    const declared = response.headers.get('content-length');
-    if (declared !== null && Number(declared) !== pin.bytes) {
-        await response.body.cancel();
-        throw new SpongeError('integrity');
-    }
-    // Primary release artifacts are small, fixed byte records. Never write an unchecked chunk.
-    const chunks = [];
-    let bytes = 0;
-    for await (const chunk of response.body) {
-        bytes += chunk.length;
-        if (bytes > pin.bytes)
-            throw new SpongeError('integrity');
-        chunks.push(chunk);
-    }
-    const data = Buffer.concat(chunks);
-    if (bytes !== pin.bytes || hash(data) !== pin.sha256)
-        throw new SpongeError('integrity');
-    await writeFile(path, data, { mode: 0o600, flag: 'wx' });
-}
-/** Hashes every retained byte when `full`; always records a stat line per entry (ctime cannot be set from user space). */
-async function inventory(root, full = true) {
-    const entries = [], stats = [];
-    let total = 0, count = 0;
-    async function visit(dir) {
-        for (const name of (await readdir(dir)).sort()) {
-            const path = join(dir, name), rel = relative(root, path);
-            if (rel === 'runtime-receipt.json')
-                continue;
-            if (++count > 60000)
-                throw new SpongeError('limit-exceeded');
-            const stat = await lstat(path, { bigint: true });
-            stats.push(statLine(rel, stat));
-            total += Number(stat.size);
-            if (total > budget)
-                throw new SpongeError('limit-exceeded');
-            if (stat.isDirectory())
-                await visit(path);
-            else if (!full)
-                continue;
-            else if (stat.isSymbolicLink()) {
-                const target = await realpath(path);
-                if (!target.startsWith(root + '/'))
-                    throw new SpongeError('integrity');
-                entries.push(`${rel}\0link\0${await readlink(path)}`);
-            }
-            else if (stat.isFile())
-                entries.push(`${rel}\0${hash(await readConfined(root, rel, budget - total + Number(stat.size)))}`);
-            else
-                throw new SpongeError('integrity');
-        }
-    }
-    await visit(root);
-    return { sha256: hash(entries.join('\n')), stats };
-}
-const statLine = (rel, s) => `${rel}\0${s.dev}\0${s.ino}\0${s.mode}\0${s.uid}\0${s.size}\0${s.mtimeNs}\0${s.ctimeNs}`;
-// One full verify per process and runtime; later uses compare only the stat receipt and fall back to a full verify on any difference.
-const verified = new Map();
-/** Full inventory walks performed by this process (observability for tests). */
-export const runtimeVerification = { fullWalks: 0 };
-async function inspectRuntime(root, pins) {
-    checkPins(pins);
-    await privateRoot(root);
-    const key = JSON.stringify([root, pins.id, pins.lockSha256, pins.bun.archiveExecutable, pins.bun.executableSha256]), bun = join(root, pins.bun.archiveExecutable);
-    // Stat receipt of the root, its receipt file and every inventoried entry. Each stat precedes any read of its entry, so a later change always shows.
-    const head = [
-        statLine('.', await lstat(root, { bigint: true })),
-        statLine('runtime-receipt.json', await lstat(join(root, 'runtime-receipt.json'), { bigint: true })),
-    ];
-    const cached = verified.get(key);
-    if (cached !== undefined && cached === hash([...head, ...(await inventory(root, false)).stats].join('\n')))
-        return { root, bun, pins };
-    verified.delete(key);
-    runtimeVerification.fullWalks++;
-    const receipt = JSON.parse((await readConfined(root, 'runtime-receipt.json', 4096)).toString()), walked = await inventory(root);
-    if (receipt.schemaVersion !== 1 ||
-        receipt.pinId !== pins.id ||
-        receipt.lockSha256 !== pins.lockSha256 ||
-        receipt.inventorySha256 !== walked.sha256)
-        throw new SpongeError('integrity');
-    if (hash(await readConfined(root, pins.bun.archiveExecutable, 128 * 1024 ** 2)) !== pins.bun.executableSha256)
-        throw new SpongeError('integrity');
-    verified.set(key, hash([...head, ...walked.stats].join('\n')));
-    return { root, bun, pins };
-}
-async function provisionRuntime(options) {
-    const { pins, signal } = options, plan = captureSetupPlan(pins);
-    options.onPlan?.(plan);
-    if (process.platform !== 'darwin' || process.arch !== 'arm64')
-        throw new SpongeError('unsupported');
-    await mkdir(options.runtimeRoot, { recursive: true, mode: 0o700 });
-    const base = await privateRoot(await realpath(options.runtimeRoot));
-    const destination = join(base, pins.id);
-    try {
-        await lstat(destination);
-        return await inspectCaptureRuntime(destination, pins);
-    }
-    catch (e) {
-        if (e.code !== 'ENOENT')
-            throw e;
-    }
-    const disk = await statfs(base);
-    if (disk.bavail * disk.bsize < plan.requiredFreeBytes)
-        throw new SpongeError('limit-exceeded');
-    const stage = await mkdtemp(join(base, '.install-'));
-    await chmod(stage, 0o700);
-    const home = join(stage, 'home');
-    await mkdir(home, { mode: 0o700 });
-    const controller = new AbortController();
-    const abort = () => controller.abort();
-    signal?.addEventListener('abort', abort, { once: true });
-    if (signal?.aborted)
-        abort();
-    let cleanup = 'settled', checking = false, limitExceeded = false;
-    const monitor = setInterval(async () => {
-        if (checking)
-            return;
-        checking = true;
-        try {
-            if ((await physicalBytes(stage)) > stagingBudget) {
-                limitExceeded = true;
-                controller.abort();
-            }
-        }
-        catch {
-            controller.abort();
-        }
-        finally {
-            checking = false;
-        }
-    }, 100);
-    try {
-        await download(pins.bun, join(stage, 'bun.zip'), controller.signal);
-        const unpack = await runOwned('/usr/bin/unzip', ['-q', join(stage, 'bun.zip'), '-d', stage], {
-            cwd: stage,
-            env: isolatedEnvironment(home, home),
-            signal: controller.signal,
-            deadlineMs: 30000,
-            maxOutputBytes: 65536,
-        });
-        cleanup = unpack.cleanup;
-        if (unpack.code !== 0 || unpack.stopped || cleanup !== 'settled')
-            throw new SpongeError(limitExceeded ? 'limit-exceeded' : (unpack.stopped ?? 'unavailable'));
-        const bun = join(stage, pins.bun.archiveExecutable);
-        if (hash(await readConfined(stage, pins.bun.archiveExecutable, 128 * 1024 ** 2)) !== pins.bun.executableSha256)
-            throw new SpongeError('integrity');
-        await chmod(bun, 0o700);
-        await download(pins.wordcell, join(stage, `hraness-wordcell-${pins.wordcell.version}.tgz`), controller.signal);
-        await writeFile(join(stage, 'package.json'), JSON.stringify({
-            private: true,
-            dependencies: { '@hraness/wordcell': `./hraness-wordcell-${pins.wordcell.version}.tgz` },
-        }), { mode: 0o600 });
-        await writeFile(join(stage, 'bun.lock'), pins.lockfile, { mode: 0o600 });
-        const install = await runOwned(bun, ['install', '--frozen-lockfile', '--ignore-scripts'], {
-            cwd: stage,
-            env: isolatedEnvironment(home, home),
-            signal: controller.signal,
-            deadlineMs: installDeadlineMs,
-            maxOutputBytes: 65536,
-        });
-        cleanup = install.cleanup;
-        if (install.code !== 0 || install.stopped || cleanup !== 'settled')
-            throw new SpongeError(limitExceeded ? 'limit-exceeded' : (install.stopped ?? 'unavailable'));
-        await rm(home, { recursive: true, force: true });
-        await rm(join(stage, 'bun.zip'));
-        const pkg = JSON.parse((await readConfined(stage, 'node_modules/@hraness/wordcell/package.json', 65536)).toString());
-        if (pkg.version !== pins.wordcell.version)
-            throw new SpongeError('integrity');
-        await writeFile(join(stage, 'runtime-receipt.json'), JSON.stringify({
-            schemaVersion: 1,
-            pinId: pins.id,
-            lockSha256: pins.lockSha256,
-            inventorySha256: (await inventory(stage)).sha256,
-        }), { mode: 0o600 });
-        if (controller.signal.aborted)
-            throw new SpongeError('cancelled');
-        await rename(stage, destination);
-        return await inspectCaptureRuntime(destination, pins);
-    }
-    finally {
-        clearInterval(monitor);
-        while (checking)
-            await new Promise((r) => setTimeout(r, 5));
-        signal?.removeEventListener('abort', abort);
-        if (cleanup === 'settled') {
-            try {
-                await rm(stage, { recursive: true, force: true });
-            }
-            catch {
-                throw new SpongeError('cleanup-required', { detail: { stage } });
-            }
-        }
-        else
-            throw new SpongeError('cleanup-required', { detail: { stage } });
-    }
-}
-export async function inspectCaptureRuntime(root, pins) {
-    try {
-        return await inspectRuntime(root, pins);
-    }
-    catch (error) {
-        if (error instanceof SpongeError)
-            throw error;
-        throw new SpongeError('runtime-missing');
-    }
-}
-export async function provisionCapture(options) {
-    try {
-        return await provisionRuntime(options);
-    }
-    catch (error) {
-        if (error instanceof SpongeError)
-            throw error;
-        if (options.signal?.aborted)
-            throw new SpongeError('cancelled');
-        throw new SpongeError('unavailable');
-    }
-}

package/dist/src/acquisition/verify-helper.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/acquisition/verify-helper.js

@@ -1,26 +0,0 @@
-import { SpongeError } from '../errors.js';
-// Executed only by the pinned Bun runtime. The import is Wordcell's public API.
-const runtime = process.argv[2], bundle = process.argv[3];
-try {
-    const { verifyCaptureBundle } = await import(import.meta.resolve('@hraness/wordcell/clip/bundle-reader', `${runtime}/package.json`));
-    const result = await verifyCaptureBundle(bundle, {
-        verifyAssets: true,
-        maxDocumentBytes: 16 * 1024 ** 2,
-        maxVerifiedAssets: 200,
-        maxAssetBytes: 20 * 1024 ** 2,
-        maxTotalAssetBytes: 500 * 1024 ** 2,
-        maxAssetVerificationMs: 30000,
-    });
-    // The document travels via the verified file, never a giant protocol frame.
-    const { markdown: _, ...document } = result.inspection.document;
-    // Metadata is validated upstream and read from the confined manifest by the parent.
-    const { metadata: _metadata, ...inspection } = result.inspection;
-    const output = JSON.stringify({ ...result, inspection: { ...inspection, document } });
-    if (Buffer.byteLength(output) > 65536)
-        throw new SpongeError('limit-exceeded');
-    process.stdout.write(output);
-}
-catch {
-    process.stdout.write(JSON.stringify({ ok: false }));
-    process.exitCode = 1;
-}

package/dist/src/importers/verify-helper.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/importers/verify-helper.js

@@ -1,41 +0,0 @@
-import { SpongeError } from '../errors.js';
-/** Only released Wordcell public verifiers, with no source or document text in output. */
-const runtime = process.argv[2], bundle = process.argv[3], kind = process.argv[4];
-try {
-    let result;
-    if (kind === 'pdf') {
-        const { verifyPdfCaptureBundle } = await import(import.meta.resolve('@hraness/wordcell/pdf', `${runtime}/package.json`));
-        result = await verifyPdfCaptureBundle(bundle, {
-            maxDocumentBytes: 16 * 1024 ** 2,
-            maxSourceBytes: 100 * 1024 ** 2,
-            maxVerifiedAssets: 200,
-            maxAssetBytes: 20 * 1024 ** 2,
-            maxTotalAssetBytes: 500 * 1024 ** 2,
-            maxVerificationMs: 30000,
-        });
-        const { markdown, ...document } = result.inspection.markdown;
-        result = { ...result, inspection: { ...result.inspection, markdown: document } };
-    }
-    else {
-        const { verifyCaptureBundle } = await import(import.meta.resolve('@hraness/wordcell/clip/bundle-reader', `${runtime}/package.json`));
-        result = await verifyCaptureBundle(bundle, {
-            verifyAssets: true,
-            maxDocumentBytes: 16 * 1024 ** 2,
-            maxVerifiedAssets: 200,
-            maxAssetBytes: 20 * 1024 ** 2,
-            maxTotalAssetBytes: 500 * 1024 ** 2,
-            maxAssetVerificationMs: 30000,
-        });
-        const { markdown, ...document } = result.inspection.document;
-        const { metadata, ...inspection } = result.inspection;
-        result = { ...result, inspection: { ...inspection, document } };
-    }
-    const output = JSON.stringify(result);
-    if (Buffer.byteLength(output) > 65536)
-        throw new SpongeError('limit-exceeded');
-    process.stdout.write(output);
-}
-catch {
-    process.stdout.write(JSON.stringify({ ok: false, code: 'unsupported' }));
-    process.exitCode = 1;
-}

package/dist/src/pdf/capture-helper.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/pdf/capture-helper.js

@@ -1,15 +0,0 @@
-// Pinned public Wordcell bridge. Native subprocesses inherit the supervisor's group.
-const runtime = process.argv[2], args = process.argv.slice(3);
-try {
-    const { runPdfCommand, runPdfToolCommand } = await import(import.meta.resolve('@hraness/wordcell/pdf', `${runtime}/package.json`));
-    process.exitCode = await runPdfCommand(args, process.env, { stdout: (value) => process.stdout.write(value), stderr: (value) => process.stderr.write(value) }, {
-        captureDependencies: {
-            runTool: (specification) => runPdfToolCommand({ ...specification, processGroup: 'inherit' }),
-        },
-    });
-}
-catch {
-    process.stdout.write(JSON.stringify({ ok: false, code: 'unknown' }));
-    process.exitCode = 1;
-}
-export {};

package/dist/src/pdf/errors.d.ts

@@ -1,2 +0,0 @@
-/** Wordcell's pinned PDF code field is authoritative; prose is never classified. */
-export declare function pdfFailure(value: unknown, requestId: string): import("../../contracts/index.js").ErrorEnvelope;

package/dist/src/pdf/errors.js

@@ -1,23 +0,0 @@
-import { failure } from '../acquisition/errors.js';
-/** Wordcell's pinned PDF code field is authoritative; prose is never classified. */
-export function pdfFailure(value, requestId) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return failure(requestId, 'unclassified');
-    const record = value;
-    if (record.ok !== false)
-        return failure(requestId, 'unclassified');
-    const codes = {
-        'invalid-input': 'invalid-input',
-        encrypted: 'unsupported',
-        'limit-exceeded': 'limit-exceeded',
-        'tool-unavailable': 'runtime-missing',
-        'extraction-failed': 'unavailable',
-        'fetch-failed': 'unavailable',
-        timeout: 'unavailable',
-        cancelled: 'cancelled',
-        integrity: 'integrity',
-        'unsupported-schema': 'schema-newer',
-        unknown: 'unclassified',
-    };
-    return failure(requestId, typeof record.code === 'string' && Object.hasOwn(codes, record.code) ? codes[record.code] : 'unclassified');
-}

package/dist/src/pdf/source-identity.d.ts

@@ -1,4 +0,0 @@
-/** Local PDFs are bound to copied bytes; only remote sources use Wordcell's URL sanitizer. */
-export declare function pdfSourceIdentity(sourceUrl: string, sanitize: (url: string) => string): {
-    expectedSourceUrl?: string;
-};

package/dist/src/pdf/source-identity.js

@@ -1,13 +0,0 @@
-import { SpongeError } from '../errors.js';
-/** Local PDFs are bound to copied bytes; only remote sources use Wordcell's URL sanitizer. */
-export function pdfSourceIdentity(sourceUrl, sanitize) {
-    const url = new URL(sourceUrl);
-    if (url.protocol === 'file:') {
-        if (url.host || url.username || url.password || url.search || url.hash)
-            throw new SpongeError('integrity');
-        return {};
-    }
-    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
-        throw new SpongeError('integrity');
-    return { expectedSourceUrl: sanitize(sourceUrl) };
-}

package/dist/src/pdf/verify-helper.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/pdf/verify-helper.js

@@ -1,29 +0,0 @@
-// Public PDF verifier, executed only by the integrity-checked pinned Bun runtime.
-import { pdfSourceIdentity } from './source-identity.js';
-import { SpongeError } from '../errors.js';
-const runtime = process.argv[2], bundle = process.argv[3];
-try {
-    const { sanitizeArtifactUrl } = await import(import.meta.resolve('@hraness/wordcell/clip/persist', `${runtime}/package.json`));
-    const { verifyPdfCaptureBundle } = await import(import.meta.resolve('@hraness/wordcell/pdf', `${runtime}/package.json`));
-    const result = await verifyPdfCaptureBundle(bundle, {
-        maxDocumentBytes: 16 * 1024 ** 2,
-        maxSourceBytes: 100 * 1024 ** 2,
-        maxVerifiedAssets: 200,
-        maxAssetBytes: 20 * 1024 ** 2,
-        maxTotalAssetBytes: 500 * 1024 ** 2,
-        maxVerificationMs: 30000,
-    });
-    const { markdown, ...document } = result.inspection.markdown;
-    const output = JSON.stringify({
-        ...result,
-        ...pdfSourceIdentity(process.argv[4], sanitizeArtifactUrl),
-        inspection: { ...result.inspection, markdown: document },
-    });
-    if (Buffer.byteLength(output) > 65536)
-        throw new SpongeError('limit-exceeded');
-    process.stdout.write(output);
-}
-catch {
-    process.stdout.write(JSON.stringify({ ok: false }));
-    process.exitCode = 1;
-}