@hraness/sponge 0.6.7 → 0.6.9

package/dist/contracts/index.d.ts

@@ -60,6 +60,8 @@ export interface CaptureResult extends Envelope {
         text: 'complete' | 'partial';
         images: 'complete' | 'partial' | 'not-requested';
     };
+    /** The page came through the reader's own browser and sign-ins. */
+    browser?: true;
 }
 export interface Transcript extends Envelope {
     source: 'human-captions' | 'automatic-captions' | 'local-asr';

package/dist/src/acquisition/capture.d.ts

@@ -11,6 +11,10 @@ export interface CaptureRequest {
     sourceUrl: string;
     requestId: string;
     connection?: CaptureConnection;
+    browser?: {
+        socket: string;
+        mode: 'always' | 'fallback';
+    };
     signal?: AbortSignal;
     deadlineMs?: number;
     allowPrivateNetwork?: boolean;

package/dist/src/acquisition/capture.js

@@ -12,10 +12,15 @@ function validSource(sourceUrl) {
     }
 }
 export function captureArticle(request) {
-    const endpoint = request.connection?.endpoint;
+    const endpoint = request.connection?.endpoint, browser = request.browser;
     return superviseChild({
         ...request,
-        valid: validSource(request.sourceUrl) && (endpoint === undefined || loopbackEndpoint.test(endpoint)),
+        valid: validSource(request.sourceUrl) &&
+            (endpoint === undefined || loopbackEndpoint.test(endpoint)) &&
+            (browser === undefined ||
+                (browser.socket.startsWith('/') &&
+                    browser.socket.length < 104 &&
+                    ['always', 'fallback'].includes(browser.mode))),
         prepare: async ({ output, deadline }) => ({
             schemaVersion: 1,
             kind: 'article',
@@ -28,6 +33,7 @@ export function captureArticle(request) {
             maxTotalAssetBytes: 500 * 1024 ** 2,
             allowPrivateNetwork: request.allowPrivateNetwork === true,
             ...(endpoint === undefined ? {} : { cdp: endpoint }),
+            ...(browser === undefined ? {} : { browser: { socket: browser.socket, mode: browser.mode } }),
         }),
         verify: (bundleRoot) => normalizeBundle({ bundleRoot, requestId: request.requestId, sourceUrl: request.sourceUrl }),
     });

package/dist/src/acquisition/child-request.d.ts

@@ -14,6 +14,11 @@ export interface ArticleChildRequest extends ChildRequestBase {
     maxHtmlBytes: number;
     /** A loopback DevTools endpoint of the user's attached signed-in browser. */
     cdp?: string;
+    /** The Sponge browser bridge socket: `always` captures only through it, `fallback` when the public page is thin. */
+    browser?: {
+        socket: string;
+        mode: 'always' | 'fallback';
+    };
 }
 export interface PdfChildRequest extends ChildRequestBase {
     kind: 'pdf';

package/dist/src/acquisition/normalize.js

@@ -93,6 +93,9 @@ export async function normalizeBundle(input) {
         extractor: { ...captureExtractor },
         manifestSha256: hash(manifestBytes),
         completeness: { text, images: imageStatus },
+        ...(/^browser-(?:fetch|render)$/.test(String(manifest.acquisition?.method))
+            ? { browser: true }
+            : {}),
     };
     validateCapture(capture);
     return capture;

package/dist/src/app/archive.d.ts

@@ -0,0 +1,15 @@
+import type { ErrorEnvelope } from '../../contracts/index.js';
+import { type SafeFetchOptions, type SafeFetchResult } from '../capture/network.js';
+type Fetch = (url: URL, options: SafeFetchOptions) => Promise<SafeFetchResult>;
+/** A saved copy of a page: the raw bytes the archive stored (`id_`), without its replay toolbar or rewritten links. */
+export interface Snapshot {
+    url: string;
+    timestamp: string;
+}
+/**
+ * The newest Internet Archive copy of `url` that the archive saw answer 200, found through its CDX index. This
+ * sends the URL to archive.org, so only an explicit `--archive` asks. No copy is `unavailable`; a busy index is
+ * `rate-limited` and retryable.
+ */
+export declare function waybackSnapshot(url: string, requestId: string, fetch?: Fetch): Promise<Snapshot | ErrorEnvelope>;
+export {};

package/dist/src/app/archive.js

@@ -0,0 +1,51 @@
+import { failure } from '../acquisition/errors.js';
+import { FetchFailure, safeFetch } from '../capture/network.js';
+import { DEFAULT_USER_AGENT } from '../capture/types.js';
+/**
+ * The newest Internet Archive copy of `url` that the archive saw answer 200, found through its CDX index. This
+ * sends the URL to archive.org, so only an explicit `--archive` asks. No copy is `unavailable`; a busy index is
+ * `rate-limited` and retryable.
+ */
+export async function waybackSnapshot(url, requestId, fetch = safeFetch) {
+    const query = new URL('https://web.archive.org/cdx/search/cdx');
+    for (const [key, value] of Object.entries({
+        url,
+        output: 'json',
+        filter: 'statuscode:200',
+        limit: '-1',
+        fl: 'timestamp,original',
+    }))
+        query.searchParams.set(key, value);
+    let rows;
+    try {
+        const response = await fetch(query, {
+            timeoutMs: 30_000,
+            maxBytes: 64 * 1024,
+            allowPrivateNetwork: false,
+            userAgent: DEFAULT_USER_AGENT,
+            accept: 'application/json',
+            retries: 2,
+        });
+        const text = new TextDecoder().decode(response.bytes).trim();
+        rows = text ? JSON.parse(text) : [];
+    }
+    catch (error) {
+        if (error instanceof FetchFailure && error.status === 429)
+            return failure(requestId, 'rate-limited', 'acquisition', true);
+        return failure(requestId, 'unavailable', 'acquisition', true);
+    }
+    // The first row names the fields; the last is the newest capture.
+    const row = Array.isArray(rows) && rows.length > 1 ? rows.at(-1) : undefined;
+    const [timestamp, original] = Array.isArray(row) ? row : [];
+    if (typeof timestamp !== 'string' || !/^\d{14}$/.test(timestamp) || typeof original !== 'string')
+        return failure(requestId, 'unavailable');
+    try {
+        const page = new URL(original);
+        if (!['http:', 'https:'].includes(page.protocol))
+            return failure(requestId, 'unavailable');
+        return { url: `https://web.archive.org/web/${timestamp}id_/${page.href}`, timestamp };
+    }
+    catch {
+        return failure(requestId, 'unavailable');
+    }
+}

package/dist/src/app/article.d.ts

@@ -2,6 +2,7 @@ import type { ErrorEnvelope, JobCheckpoint } from '../../contracts/index.js';
 import { type CaptureRequest, type CaptureOutcome, type CaptureConnection } from '../acquisition/index.js';
 import type { LibraryStore, AttemptToken } from '../store/index.js';
 import { type PdfCaptureRequest, type CaptureOutcome as PdfCaptureOutcome } from '../pdf/capture.js';
+import { waybackSnapshot } from './archive.js';
 interface ArticleResult {
     ok: true;
     itemId: string;
@@ -15,10 +16,13 @@ export interface ArticleOptions {
     checkpoint?: (stage: JobCheckpoint['stage']) => Promise<void>;
     runProcess?: CaptureRequest['runProcess'];
     connection?: CaptureConnection;
+    /** The Sponge browser bridge socket: a thin public page is retried there, and `--browser` sources only use it. */
+    browser?: string;
     signal?: AbortSignal;
     allowPrivateNetwork?: boolean;
     capture?: (request: CaptureRequest) => Promise<CaptureOutcome>;
     capturePdf?: (request: PdfCaptureRequest) => Promise<PdfCaptureOutcome>;
+    snapshot?: typeof waybackSnapshot;
 }
 /** One attempt. Durable queue policy and process recovery live above this function. */
 export declare function ingestArticle(store: LibraryStore, token: AttemptToken, options: ArticleOptions): Promise<ArticleOutcome>;

package/dist/src/app/article.js

@@ -5,10 +5,11 @@ import { runAttempt, classifyErrors } from '../ingest/attempt.js';
 import { sha256 } from '../util/hash.js';
 import { bundleBytes, bundleText } from './bundle-files.js';
 import { selectedMetadata } from '../metadata/article.js';
-import { localizeMarkdown } from './markdown.js';
+import { localizeMarkdown, proseWords } from './markdown.js';
 import { SpongeError } from '../errors.js';
 import { capturePdf } from '../pdf/capture.js';
 import { storePdfCapture } from '../pdf/handler.js';
+import { waybackSnapshot } from './archive.js';
 const classify = classifyErrors([
     'integrity',
     'limit-exceeded',
@@ -23,12 +24,21 @@ export function ingestArticle(store, token, options) {
         const source = store.queue.source(token.jobId);
         if (!source || source.kind !== 'article')
             throw new SpongeError('invalid-input');
+        // An archived copy is public: it is fetched directly, never through a signed-in browser.
+        const snapshot = source.via === 'archive' ? await (options.snapshot ?? waybackSnapshot)(source.locator, token.attemptId) : null;
+        if (snapshot && 'ok' in snapshot)
+            return snapshot;
+        const fetched = snapshot?.url ?? source.locator;
         const result = await (options.capture ?? captureArticle)({
             runProcess: options.runProcess,
             stagingRoot: join(store.root, 'staging'),
-            sourceUrl: source.locator,
+            sourceUrl: fetched,
             requestId: token.attemptId,
-            connection: options.connection,
+            connection: snapshot ? undefined : options.connection,
+            // An archived copy or an attached connection already names its route; the browser is never asked for it.
+            ...(snapshot || options.connection || !options.browser
+                ? {}
+                : { browser: { socket: options.browser, mode: source.via === 'browser' ? 'always' : 'fallback' } }),
             signal: options.signal,
             allowPrivateNetwork: options.allowPrivateNetwork,
         });
@@ -41,12 +51,12 @@ export function ingestArticle(store, token, options) {
         await options.checkpoint?.('extracting');
         const capture = result.capture;
         validateCapture(capture);
-        if (capture.kind !== 'article' || capture.requestId !== token.attemptId || capture.sourceUrl !== source.locator)
+        if (capture.kind !== 'article' || capture.requestId !== token.attemptId || capture.sourceUrl !== fetched)
             throw new SpongeError('integrity');
         const original = await bundleText(result.bundleRoot, capture.markdown);
         const selectedTitle = selectedMetadata(capture.metadata, 'title')?.value;
         const title = typeof selectedTitle === 'string' ? selectedTitle : undefined;
-        const paperUrl = proseWords(original) < landingPageWords ? fullTextPdf(capture.metadata, source.locator) : undefined;
+        const paperUrl = proseWords(original) < landingPageWords ? fullTextPdf(capture.metadata, fetched) : undefined;
         if (paperUrl) {
             const paper = await (options.capturePdf ?? capturePdf)({
                 runProcess: options.runProcess,
@@ -75,6 +85,8 @@ export function ingestArticle(store, token, options) {
                     assets: pdf.assets,
                     warnings: pdf.warnings,
                 });
+                if (capture.browser)
+                    keepPrivate(store, source.itemId);
                 return { ok: true, itemId: source.itemId, revisionId: revision.revisionId, status: pdf.status };
             }
             // Without the paper, the landing page is still what the reader saved.
@@ -110,16 +122,18 @@ export function ingestArticle(store, token, options) {
             assets,
             warnings: [...new Set([...capture.warnings, ...(localized.missingImages ? ['partial'] : [])])],
         });
+        if (capture.browser)
+            keepPrivate(store, source.itemId);
         return { ok: true, itemId: source.itemId, revisionId: revision.revisionId, status };
     });
 }
+/** A page read with the reader's sign-ins starts private; `sponge visibility ITEM public` shares it deliberately. */
+function keepPrivate(store, itemId) {
+    if (store.identity(itemId).visibility.override === null)
+        store.setVisibility(itemId, 'private');
+}
 /** Prose words under which a page that names its paper's PDF is only a landing page: a title, authors and abstract. */
 const landingPageWords = 1000;
-function proseWords(markdown) {
-    const body = markdown.startsWith('---\n') ? markdown.slice(Math.max(0, markdown.indexOf('\n---', 4))) : markdown;
-    const prose = body.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
-    return (prose.match(/\p{L}[\p{L}\p{M}'’-]*/gu) ?? []).length;
-}
 /**
  * The full text a scholarly landing page declares in `citation_pdf_url` (arXiv, NBER, OSF and most journals), when
  * it is served from the page's own site or a subdomain relation of it; other sites are never fetched on its word.

package/dist/src/app/markdown.d.ts

@@ -4,3 +4,5 @@ export declare function localizeMarkdown(markdown: string, assets: Asset[]): {
     markdown: string;
     missingImages: boolean;
 };
+/** Words with letters past the frontmatter, images dropped and link text kept: how much a capture says. */
+export declare function proseWords(markdown: string): number;

package/dist/src/app/markdown.js

@@ -100,3 +100,9 @@ export function localizeMarkdown(markdown, assets) {
         markdown = markdown.slice(0, patch.start) + patch.value + markdown.slice(patch.end);
     return { markdown, missingImages };
 }
+/** Words with letters past the frontmatter, images dropped and link text kept: how much a capture says. */
+export function proseWords(markdown) {
+    const body = markdown.startsWith('---\n') ? markdown.slice(Math.max(0, markdown.indexOf('\n---', 4))) : markdown;
+    const prose = body.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+    return (prose.match(/\p{L}[\p{L}\p{M}'’-]*/gu) ?? []).length;
+}

package/dist/src/browser/bridge.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The Sponge browser bridge. The Sponge extension in the reader's own browser opens a native-messaging port; the
+ * browser starts `host.ts`, which listens on a private local socket. A capture asks over that socket, and the
+ * extension loads the page with the reader's own sign-ins. Cookies and passwords never leave the browser: Sponge
+ * receives only the page.
+ */
+export declare const hostName = "com.hraness.sponge";
+/** Derived from the public key in extension/manifest.json, so an unpacked or store install keeps one identity. */
+export declare const extensionId = "pcekakbinokokbcfdpgdljpeoiceoejf";
+/** `fetch` asks with the reader's cookies and reads the HTML; `render` loads the page in a background window. */
+export type BrowserOperation = 'fetch' | 'render';
+export interface BrowserPage {
+    ok: true;
+    html: string;
+    finalUrl: string;
+    title?: string;
+}
+/** `disabled`: the reader turned background captures off. `offline`: no browser has the extension running. */
+export interface BrowserRefusal {
+    ok: false;
+    code: 'disabled' | 'offline' | 'failed' | 'timeout' | 'not-html' | 'too-large';
+    status?: number;
+}
+export interface BrowserStatus {
+    ok: true;
+    extension: string;
+    background: boolean;
+}
+/** One bridge per library: a short path, because a Unix socket path is limited to 104 bytes on macOS. */
+export declare function bridgeSocket(libraryRoot: string, home?: string): string;
+/** Native messaging frames: a 32-bit length in the host's byte order (little-endian on every supported Mac), then JSON. */
+export declare function encodeFrame(message: unknown): Buffer;
+/** Splits complete frames off `buffer`; the rest waits for more bytes. A frame over `maxBytes` is refused. */
+export declare function decodeFrames(buffer: Buffer, maxBytes: number): {
+    messages: unknown[];
+    rest: Buffer;
+};
+/** Requests over the socket are one JSON line each way; the bridge closes after its answer. */
+export declare function askBridge(socket: string, request: {
+    op: 'status';
+} | {
+    op: BrowserOperation;
+    url: string;
+    timeoutMs: number;
+}, options: {
+    timeoutMs: number;
+    maxBytes: number;
+}): Promise<BrowserPage | BrowserRefusal | BrowserStatus>;

package/dist/src/browser/bridge.js

@@ -0,0 +1,90 @@
+import { createConnection } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { sha256 } from '../util/hash.js';
+/**
+ * The Sponge browser bridge. The Sponge extension in the reader's own browser opens a native-messaging port; the
+ * browser starts `host.ts`, which listens on a private local socket. A capture asks over that socket, and the
+ * extension loads the page with the reader's own sign-ins. Cookies and passwords never leave the browser: Sponge
+ * receives only the page.
+ */
+export const hostName = 'com.hraness.sponge';
+/** Derived from the public key in extension/manifest.json, so an unpacked or store install keeps one identity. */
+export const extensionId = 'pcekakbinokokbcfdpgdljpeoiceoejf';
+/** One bridge per library: a short path, because a Unix socket path is limited to 104 bytes on macOS. */
+export function bridgeSocket(libraryRoot, home = homedir()) {
+    return join(home, '.local', 'state', 'sponge', sha256(libraryRoot).slice(0, 16) + '.sock');
+}
+/** Native messaging frames: a 32-bit length in the host's byte order (little-endian on every supported Mac), then JSON. */
+export function encodeFrame(message) {
+    const body = Buffer.from(JSON.stringify(message), 'utf8'), frame = Buffer.alloc(4 + body.length);
+    frame.writeUInt32LE(body.length, 0);
+    body.copy(frame, 4);
+    return frame;
+}
+/** Splits complete frames off `buffer`; the rest waits for more bytes. A frame over `maxBytes` is refused. */
+export function decodeFrames(buffer, maxBytes) {
+    const messages = [];
+    let offset = 0;
+    while (buffer.length - offset >= 4) {
+        const length = buffer.readUInt32LE(offset);
+        if (length > maxBytes)
+            throw new Error('native message exceeds its limit');
+        if (buffer.length - offset - 4 < length)
+            break;
+        messages.push(JSON.parse(buffer.subarray(offset + 4, offset + 4 + length).toString('utf8')));
+        offset += 4 + length;
+    }
+    return { messages, rest: buffer.subarray(offset) };
+}
+/** Requests over the socket are one JSON line each way; the bridge closes after its answer. */
+export function askBridge(socket, request, options) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let bytes = 0, settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            connection.destroy();
+            resolve(value);
+        };
+        const connection = createConnection(socket);
+        const timer = setTimeout(() => done({ ok: false, code: 'timeout' }), options.timeoutMs);
+        connection.on('connect', () => connection.write(JSON.stringify(request) + '\n'));
+        connection.on('data', (chunk) => {
+            bytes += chunk.length;
+            if (bytes > options.maxBytes)
+                return done({ ok: false, code: 'too-large' });
+            chunks.push(chunk);
+            const text = Buffer.concat(chunks).toString('utf8'), end = text.indexOf('\n');
+            if (end < 0)
+                return;
+            try {
+                done(answer(JSON.parse(text.slice(0, end))));
+            }
+            catch {
+                done({ ok: false, code: 'failed' });
+            }
+        });
+        connection.on('error', () => done({ ok: false, code: 'offline' }));
+        connection.on('close', () => done({ ok: false, code: 'failed' }));
+    });
+}
+const refusals = new Set(['disabled', 'offline', 'failed', 'timeout', 'not-html', 'too-large']);
+/** The bridge relays what the extension says; only these shapes pass. */
+function answer(value) {
+    if (value?.ok === true && typeof value.html === 'string' && typeof value.finalUrl === 'string')
+        return {
+            ok: true,
+            html: value.html,
+            finalUrl: value.finalUrl,
+            ...(typeof value.title === 'string' ? { title: value.title } : {}),
+        };
+    if (value?.ok === true && typeof value.extension === 'string' && typeof value.background === 'boolean')
+        return { ok: true, extension: value.extension, background: value.background };
+    if (value?.ok === false && refusals.has(value.code))
+        return { ok: false, code: value.code, ...(Number.isInteger(value.status) ? { status: value.status } : {}) };
+    return { ok: false, code: 'failed' };
+}

package/dist/src/browser/host.d.ts

@@ -0,0 +1,10 @@
+export interface HostOptions {
+    library: string;
+    socket: string;
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+    /** The caller's origin, as the browser passes it; anything but the Sponge extension is refused. */
+    origin?: string;
+}
+/** Relays capture requests from the socket to the extension and saves the pages the reader sends. */
+export declare function runHost(options: HostOptions): Promise<void>;

package/dist/src/browser/host.js

@@ -0,0 +1,147 @@
+// The native-messaging host the browser starts for the Sponge extension. stdout carries only frames to the extension.
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, realpathSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { decodeFrames, encodeFrame, extensionId } from './bridge.js';
+import { inferKind, articleSource } from '../app/source.js';
+import { pdfSource } from '../pdf/source.js';
+import { openLibrary } from '../store/open.js';
+/** Chrome accepts messages to the extension up to 1 MB and sends up to 64 MiB; Sponge caps a page lower. */
+const maxInboundBytes = 32 * 1024 ** 2;
+/** Relays capture requests from the socket to the extension and saves the pages the reader sends. */
+export function runHost(options) {
+    if (options.origin !== undefined && options.origin !== `chrome-extension://${extensionId}/`)
+        return Promise.reject(new Error('unexpected caller'));
+    const pending = new Map();
+    let hello;
+    const send = (message) => options.output.write(encodeFrame(message));
+    mkdirSync(dirname(options.socket), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(options.socket), 0o700);
+    // The newest browser to start the host serves the library; a stale socket from a crash is replaced.
+    rmSync(options.socket, { force: true });
+    const server = createServer((client) => serve(client));
+    server.listen(options.socket, () => chmodSync(options.socket, 0o600));
+    function serve(client) {
+        let buffered = '';
+        const reply = (value) => client.end(JSON.stringify(value) + '\n');
+        client.setEncoding('utf8');
+        client.on('error', () => undefined);
+        client.on('data', (chunk) => {
+            buffered += chunk;
+            if (buffered.length > 64 * 1024)
+                return client.destroy();
+            const end = buffered.indexOf('\n');
+            if (end < 0)
+                return;
+            let request;
+            try {
+                request = JSON.parse(buffered.slice(0, end));
+            }
+            catch {
+                return reply({ ok: false, code: 'failed' });
+            }
+            if (request?.op === 'status')
+                return reply(hello ? { ok: true, ...hello } : { ok: false, code: 'offline' });
+            const op = request?.op;
+            if ((op !== 'fetch' && op !== 'render') || !web(request.url) || !Number.isInteger(request.timeoutMs))
+                return reply({ ok: false, code: 'failed' });
+            if (!hello)
+                return reply({ ok: false, code: 'offline' });
+            if (!hello.background)
+                return reply({ ok: false, code: 'disabled' });
+            const id = randomUUID(), timeoutMs = Math.min(Math.max(request.timeoutMs, 1000), 120_000), timer = setTimeout(() => finish({ ok: false, code: 'timeout' }), timeoutMs + 5000);
+            const finish = (value) => {
+                clearTimeout(timer);
+                pending.delete(id);
+                reply(value);
+            };
+            pending.set(id, { reply: finish });
+            send({ id, op, url: request.url, timeoutMs });
+        });
+    }
+    async function save(requestId, url) {
+        if (typeof requestId !== 'string' || requestId.length > 64)
+            return;
+        const kind = typeof url === 'string' && web(url) ? inferKind(url) : 'media';
+        if (kind === 'media')
+            return send({ type: 'saved', requestId, ok: false, code: 'unsupported' });
+        try {
+            const store = await openLibrary(options.library);
+            try {
+                const source = (kind === 'pdf' ? pdfSource : articleSource)(url);
+                // A page saved from the browser captures through it: the reader is looking at the page they want kept.
+                const submission = store.queue.submit({
+                    kind,
+                    ...source,
+                    intent: kind === 'article' ? 'browser' : 'save',
+                    idempotencyKey: randomUUID(),
+                });
+                send({ type: 'saved', requestId, ok: true, itemId: submission.itemId });
+            }
+            finally {
+                store.close();
+            }
+        }
+        catch {
+            send({ type: 'saved', requestId, ok: false, code: 'failed' });
+        }
+    }
+    return new Promise((resolve) => {
+        let buffer = Buffer.alloc(0);
+        options.input.on('data', (chunk) => {
+            let decoded;
+            try {
+                decoded = decodeFrames(Buffer.concat([buffer, chunk]), maxInboundBytes);
+            }
+            catch {
+                return stop();
+            }
+            buffer = decoded.rest;
+            for (const message of decoded.messages) {
+                if (message?.type === 'hello' || message?.type === 'settings')
+                    hello = {
+                        extension: String(message.version ?? hello?.extension ?? ''),
+                        background: message.background !== false,
+                    };
+                else if (message?.type === 'save')
+                    void save(message.requestId, message.url);
+                else if (typeof message?.id === 'string')
+                    pending.get(message.id)?.reply(message.ok ? message : refusal(message));
+            }
+        });
+        const stop = () => {
+            for (const { reply } of pending.values())
+                reply({ ok: false, code: 'offline' });
+            server.close();
+            rmSync(options.socket, { force: true });
+            resolve();
+        };
+        options.input.on('end', stop);
+        options.input.on('error', stop);
+    });
+}
+const web = (value) => {
+    if (typeof value !== 'string' || value.length > 16384)
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'https:' || url.protocol === 'http:') && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+};
+const refusal = (message) => ({
+    ok: false,
+    code: message.code,
+    ...(Number.isInteger(message.status) ? { status: message.status } : {}),
+});
+// Started by the wrapper `sponge browser setup` writes: --library ROOT --socket PATH, then the browser's own arguments.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    const [, , flag1, library, flag2, socket, origin] = process.argv;
+    if (flag1 !== '--library' || flag2 !== '--socket' || !library || !socket)
+        process.exit(2);
+    runHost({ library, socket, origin, input: process.stdin, output: process.stdout }).then(() => process.exit(0), () => process.exit(1));
+}

package/dist/src/browser/setup.d.ts

@@ -0,0 +1,26 @@
+export interface BrowserSetupOptions {
+    home?: string;
+    /** Extra NativeMessagingHosts directories, such as a custom `--user-data-dir`'s. */
+    hostsDirs?: string[];
+}
+/**
+ * Registers the native host with each installed browser for one library. The host is a wrapper script, since a
+ * manifest names one executable and takes no arguments; it runs this Node and this Sponge's host.
+ */
+export declare function setupBrowser(libraryRoot: string, options?: BrowserSetupOptions): Promise<{
+    registered: string[];
+    extension: string;
+    extensionId: string;
+}>;
+/** Which browsers have the host registered, and whether an extension is connected for this library now. */
+export declare function browserStatus(libraryRoot: string, options?: BrowserSetupOptions): Promise<{
+    extension?: string | undefined;
+    background?: boolean | undefined;
+    registered: string[];
+    bound: boolean;
+    connected: boolean;
+}>;
+/** Removes the registrations that point at Sponge's host; another program's manifest is left alone. */
+export declare function removeBrowser(options?: BrowserSetupOptions): Promise<{
+    removed: string[];
+}>;