@pipobscure/bundle 0.0.1

package/src/oidc.ts

@@ -0,0 +1,372 @@
+import * as CRYPTO from 'node:crypto';
+import * as HTTP from 'node:http';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+
+// Getting an OIDC identity token to present to Fulcio — the "who are you"
+// half of sigstore signing. Fulcio does not care how the token was obtained,
+// only that it is a valid one from an issuer it recognises, so this module's
+// whole job is to produce one and then get out of the way.
+//
+// Three routes, tried in this order, because the right one is a property of
+// where the command is running rather than something a user should have to
+// pick:
+//
+//   * An ambient CI token. GitHub Actions exposes a token endpoint through
+//     `ACTIONS_ID_TOKEN_REQUEST_URL`/`ACTIONS_ID_TOKEN_REQUEST_TOKEN` (given
+//     `permissions: id-token: write`), and the resulting token names the
+//     repository and workflow rather than a person. That is the identity you
+//     actually want on a release artifact, so CI wins whenever it is present.
+//
+//   * A browser sign-in. Sigstore runs a Dex instance at oauth2.sigstore.dev
+//     that federates to GitHub, Google and Microsoft; naming one as
+//     `connector_id` skips its chooser and goes straight there. The
+//     redirect comes back to a loopback server this process opens on an
+//     ephemeral port, which is why no client secret is needed: the flow is a
+//     public-client authorization code exchange bound by PKCE.
+//
+//   * A device code. The same Dex, for machines with no browser to open — an
+//     SSH session, a container. The user is given a short code and a URL to
+//     open somewhere else, and this process polls until they finish.
+//
+// Nothing here is sigstore-specific beyond the default endpoints; pointing
+// `issuer` at another OIDC provider works, which is the point of Fulcio
+// accepting a token rather than a credential of its own.
+
+export const DEFAULT_ISSUER = 'https://oauth2.sigstore.dev/auth';
+export const DEFAULT_CLIENT_ID = 'sigstore';
+const DEFAULT_SCOPE = 'openid email';
+
+/** How an identity token was obtained. */
+export type IdentityFlow = 'supplied' | 'ci' | 'browser' | 'device';
+
+/** What the caller may ask for; 'auto' picks by looking at the environment. */
+export type RequestedFlow = 'auto' | 'ci' | 'browser' | 'device';
+
+export interface IdentityTokenOptions {
+    /** A token supplied by the caller; returned as-is. */
+    token?: string | undefined;
+    /** OIDC issuer base URL (default: sigstore's Dex). */
+    issuer?: string | undefined;
+    /** OAuth client id (default: 'sigstore'). */
+    clientID?: string | undefined;
+    /** Dex connector to jump straight to (default: 'github'). */
+    connector?: string | undefined;
+    flow?: RequestedFlow | undefined;
+    /** Audience to request for the CI token (default: 'sigstore'). */
+    audience?: string | undefined;
+    log?: ((line: string) => void) | undefined;
+}
+
+export interface IdentityTokenResult {
+    token: string;
+    flow: IdentityFlow;
+}
+
+// Dex identifies a connector by the upstream issuer's URL, not by a short name,
+// and rejects the request outright if handed something it does not recognise.
+// These are the three sigstore's instance offers; the short names are a
+// convenience this module translates, so `--connector github` works and an
+// unrecognised value is still passed through verbatim for another deployment.
+const CONNECTORS: Record<string, string> = {
+    github: 'https://github.com/login/oauth',
+    google: 'https://accounts.google.com',
+    microsoft: 'https://login.microsoftonline.com',
+};
+
+/**
+ * Resolve a connector name to what Dex expects. An empty value means "do not
+ * preselect", which lands the user on the provider chooser.
+ */
+export function connectorId(name: string | undefined): string | undefined {
+    if (!name || name === 'none') return undefined;
+    return CONNECTORS[name.toLowerCase()] ?? name;
+}
+
+/** The audience Fulcio expects to find in the token it is handed. */
+export const FULCIO_AUDIENCE = 'sigstore';
+
+/** Obtain an identity token, by whichever route fits where this is running. */
+export async function identityToken(options: IdentityTokenOptions = {}): Promise<IdentityTokenResult> {
+    const opts = {
+        issuer: options.issuer ?? DEFAULT_ISSUER,
+        clientID: options.clientID ?? DEFAULT_CLIENT_ID,
+        connector: connectorId(options.connector ?? 'github'),
+        audience: options.audience ?? FULCIO_AUDIENCE,
+        log: options.log ?? ((line: string) => { process.stderr.write(`${line}\n`); }),
+    };
+    const flow = options.flow ?? 'auto';
+
+    if (options.token) return { token: options.token, flow: 'supplied' };
+
+    if (flow === 'ci' || (flow === 'auto' && inCI())) {
+        if (!inCI()) throw new Error('no CI OIDC token endpoint in the environment');
+        return { token: await ciToken(opts.audience), flow: 'ci' };
+    }
+
+    const chosen: 'browser' | 'device' = flow === 'auto' ? (canOpenBrowser() ? 'browser' : 'device') : flow;
+    const config = await discover(opts.issuer);
+    const token = chosen === 'device' ? await deviceFlow(config, opts) : await browserFlow(config, opts);
+    return { token, flow: chosen };
+}
+
+/**
+ * Whether an ambient CI identity is available. Only GitHub's shape is
+ * implemented, since that is what the `--connector github` path mirrors, but
+ * this is the hook other providers would land on.
+ */
+export function inCI(): boolean {
+    return Boolean(process.env['ACTIONS_ID_TOKEN_REQUEST_URL'] && process.env['ACTIONS_ID_TOKEN_REQUEST_TOKEN']);
+}
+
+interface OIDCConfig {
+    authorization_endpoint: string;
+    token_endpoint: string;
+    device_authorization_endpoint?: string;
+}
+
+interface ResolvedOptions {
+    issuer: string;
+    clientID: string;
+    connector: string | undefined;
+    audience: string;
+    log: (line: string) => void;
+}
+
+// GitHub Actions' OIDC endpoint. The workflow must ask for it:
+//
+//   permissions:
+//     id-token: write
+//
+// Without that the variables are simply absent, which is what `inCI()` reads.
+async function ciToken(audience: string): Promise<string> {
+    const url = new URL(process.env['ACTIONS_ID_TOKEN_REQUEST_URL']!);
+    url.searchParams.set('audience', audience);
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${process.env['ACTIONS_ID_TOKEN_REQUEST_TOKEN']}` },
+    });
+    if (!res.ok) throw new Error(`CI OIDC token request failed: ${res.status} ${res.statusText}`);
+    const body = await res.json() as { value?: string };
+    if (!body.value) throw new Error('CI OIDC token response carried no token');
+    return body.value;
+}
+
+// The OIDC discovery document, so endpoints are read from the issuer rather
+// than hard-coded next to it.
+async function discover(issuer: string): Promise<OIDCConfig> {
+    const url = `${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`OIDC discovery failed for ${issuer}: ${res.status} ${res.statusText}`);
+    return await res.json() as OIDCConfig;
+}
+
+// Authorization code + PKCE against a loopback redirect. The server is bound
+// to 127.0.0.1 on an ephemeral port and lives exactly as long as the one
+// request it is waiting for.
+async function browserFlow(config: OIDCConfig, opts: ResolvedOptions): Promise<string> {
+    const verifier = base64url(CRYPTO.randomBytes(32));
+    const challenge = base64url(CRYPTO.createHash('sha256').update(verifier).digest());
+    const state = base64url(CRYPTO.randomBytes(16));
+    const nonce = base64url(CRYPTO.randomBytes(16));
+
+    const { server, port } = await listen();
+    const redirect = `http://localhost:${port}/auth/callback`;
+    try {
+        const authorize = new URL(config.authorization_endpoint);
+        authorize.search = new URLSearchParams({
+            response_type: 'code',
+            client_id: opts.clientID,
+            scope: DEFAULT_SCOPE,
+            redirect_uri: redirect,
+            code_challenge: challenge,
+            code_challenge_method: 'S256',
+            state,
+            nonce,
+            ...(opts.connector ? { connector_id: opts.connector } : {}),
+        }).toString();
+
+        opts.log(`  opening ${label(opts.connector)}sign-in in your browser`);
+        opts.log(`  if it does not open, visit:\n    ${authorize}`);
+        openBrowser(authorize.toString());
+
+        const code = await awaitCode(server, state);
+        return await exchange(config, {
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirect,
+            client_id: opts.clientID,
+            code_verifier: verifier,
+        });
+    } finally {
+        server.close();
+    }
+}
+
+// Resolves with the `code` from the single callback request, or rejects with
+// whatever the provider reported instead. `state` is checked before the code is
+// accepted, so a request that did not originate from this flow is rejected.
+function awaitCode(server: HTTP.Server, state: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error('timed out waiting for the browser sign-in to complete'));
+        }, 5 * 60_000);
+        timer.unref?.();
+
+        server.on('request', (req, res) => {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            if (url.pathname !== '/auth/callback') return respond(res, 404, 'Not found.');
+            clearTimeout(timer);
+
+            const error = url.searchParams.get('error');
+            if (error) {
+                respond(res, 400, `Sign-in failed: ${error}`);
+                return reject(new Error(`sign-in failed: ${url.searchParams.get('error_description') || error}`));
+            }
+            if (url.searchParams.get('state') !== state) {
+                respond(res, 400, 'Sign-in failed: state mismatch.');
+                return reject(new Error('sign-in failed: state parameter did not match'));
+            }
+            const code = url.searchParams.get('code');
+            if (!code) {
+                respond(res, 400, 'Sign-in failed: no authorization code.');
+                return reject(new Error('sign-in failed: no authorization code in the callback'));
+            }
+            respond(res, 200, 'Signed in. You can close this tab and return to the terminal.');
+            resolve(code);
+        });
+        server.on('error', reject);
+    });
+}
+
+// Device authorization: the user finishes the flow on another device while this
+// process polls. `interval` and the slow_down response are honoured, because
+// Dex will reject a client that ignores them.
+//
+// PKCE is required here as well as on the browser flow — Dex rejects a device
+// request without it — even though the device flow's own security does not
+// depend on it.
+async function deviceFlow(config: OIDCConfig, opts: ResolvedOptions): Promise<string> {
+    const endpoint = config.device_authorization_endpoint
+        ?? `${opts.issuer.replace(/\/+$/, '')}/device/code`;
+    const verifier = base64url(CRYPTO.randomBytes(32));
+    const challenge = base64url(CRYPTO.createHash('sha256').update(verifier).digest());
+
+    const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            client_id: opts.clientID,
+            scope: DEFAULT_SCOPE,
+            code_challenge: challenge,
+            code_challenge_method: 'S256',
+        }).toString(),
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => '');
+        throw new Error(`device authorization failed: ${res.status} ${detail || res.statusText}`);
+    }
+    const grant = await res.json() as {
+        device_code: string; user_code?: string; verification_uri?: string;
+        verification_uri_complete?: string; expires_in?: number; interval?: number;
+    };
+
+    opts.log(`  open ${grant.verification_uri_complete ?? grant.verification_uri}`);
+    if (grant.user_code) opts.log(`  and enter the code: ${grant.user_code}`);
+
+    const deadline = Date.now() + (grant.expires_in ?? 600) * 1000;
+    let interval = (grant.interval ?? 5) * 1000;
+    for (;;) {
+        await sleep(interval);
+        if (Date.now() > deadline) throw new Error('device sign-in expired before it was approved');
+        try {
+            return await exchange(config, {
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                device_code: grant.device_code,
+                client_id: opts.clientID,
+                code_verifier: verifier,
+            });
+        } catch (err) {
+            // These two are the flow working as designed: still waiting for the
+            // user, or told to back off. Anything else is a real failure.
+            const oauthError = (err as { oauthError?: string }).oauthError;
+            if (oauthError === 'authorization_pending') continue;
+            if (oauthError === 'slow_down') { interval += 5000; continue; }
+            throw err;
+        }
+    }
+}
+
+// Token endpoint exchange, shared by both interactive flows. Dex treats
+// `sigstore` as a public client, so the empty client_secret is what it expects
+// rather than an omission.
+async function exchange(config: OIDCConfig, params: Record<string, string>): Promise<string> {
+    const res = await fetch(config.token_endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ client_secret: '', ...params }).toString(),
+    });
+    const body = await res.json().catch(() => ({})) as { id_token?: string; error?: string; error_description?: string };
+    if (!res.ok) {
+        throw Object.assign(new Error(`token exchange failed: ${body.error_description || body.error || res.statusText}`),
+            { oauthError: body.error });
+    }
+    if (!body.id_token) throw new Error('token exchange returned no id_token');
+    return body.id_token;
+}
+
+function listen(): Promise<{ server: HTTP.Server; port: number }> {
+    const server = HTTP.createServer();
+    server.listen(0, '127.0.0.1');
+    return once(server, 'listening').then(() => {
+        const address = server.address();
+        if (!address || typeof address === 'string') throw new Error('loopback server did not bind a port');
+        return { server, port: address.port };
+    });
+}
+
+function respond(res: HTTP.ServerResponse, status: number, message: string): void {
+    res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end(`${message}\n`);
+}
+
+// Whether launching a browser is plausible. A headless Linux box has no
+// DISPLAY, and an SSH session should not try to open one on the far end — in
+// both cases the device flow is the honest answer.
+function canOpenBrowser(): boolean {
+    if (process.env['BUNDLE_NO_BROWSER']) return false;
+    if (process.env['SSH_CONNECTION'] || process.env['SSH_TTY']) return false;
+    if (process.platform === 'darwin' || process.platform === 'win32') return true;
+    return Boolean(process.env['DISPLAY'] || process.env['WAYLAND_DISPLAY']);
+}
+
+// Best effort: if this fails the URL has already been printed, and the flow
+// still completes when the user opens it themselves.
+//
+// Windows goes through the URL protocol handler directly rather than
+// `cmd /c start`: cmd would read every `&` in the query string as a command
+// separator, run the pieces after it, and open a truncated URL.
+function openBrowser(url: string): void {
+    const [cmd, ...args] = process.platform === 'darwin' ? ['open', url]
+        : process.platform === 'win32' ? ['rundll32', 'url.dll,FileProtocolHandler', url]
+        : ['xdg-open', url];
+    try {
+        spawn(cmd!, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+    } catch {
+        // ignored — the URL is on screen
+    }
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+function base64url(buf: Buffer): string {
+    return buf.toString('base64url');
+}
+
+// A connector URL, said the way a person would.
+function label(connector: string | undefined): string {
+    if (!connector) return '';
+    const name = Object.keys(CONNECTORS).find((key) => CONNECTORS[key] === connector);
+    return name ? `${name} ` : '';
+}

package/src/preload.ts

@@ -0,0 +1,40 @@
+import { createRequire } from 'node:module';
+
+// Shared plumbing for the two `-r` preloads.
+//
+// A preload has to load synchronously — `node -r` uses the CommonJS loader, and
+// a module with a top-level `await` in it is rejected outright — so the sibling
+// it pulls in is `require()`d rather than imported. That also puts the load
+// inside a `try`, which is the point: both preloads want a missing `node:vfs`
+// to be said in words rather than raised as a builtin-module error from deep
+// inside node's startup.
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Load a sibling module of `from` by base name, with whichever extension the
+ * caller is currently running as — `.ts` straight from source (node strips the
+ * types), `.js` once compiled.
+ */
+export function sibling<T>(from: string, name: string): T {
+    return require(`./${name}${from.endsWith('.ts') ? '.ts' : '.js'}`) as T;
+}
+
+/**
+ * Run a preload's registration, translating the one failure worth explaining:
+ * `node:vfs` only exists under `--experimental-vfs`, and without it every one
+ * of these modules is unloadable for a reason the raw error does not make
+ * obvious.
+ */
+export function preload(register: () => void): void {
+    try {
+        register();
+    } catch (err) {
+        const code = (err as { code?: string } | null)?.code;
+        const text = err instanceof Error ? err.message : String(err);
+        if ((code === 'ERR_UNKNOWN_BUILTIN_MODULE' || code === 'MODULE_NOT_FOUND') && /node:vfs/.test(text)) {
+            throw new Error('bundle: node:vfs is unavailable — run node with --experimental-vfs', { cause: err });
+        }
+        throw err;
+    }
+}

package/src/provider.ts

@@ -0,0 +1,270 @@
+import * as VFS from 'node:vfs';
+import * as ZLIB from 'node:zlib';
+import * as CRYPTO from 'node:crypto';
+import * as PATH from 'node:path';
+import * as FS from 'node:fs';
+import { AUTHORITY, signatureOf, verifySync, type VerificationResult } from './manifest.ts';
+
+// A `node:vfs` file provider for signed archives — `.bundle` files — layered on
+// the built-in `ZipProvider`. It is what turns "this archive is signed" into
+// "this archive is what runs":
+//
+//   * At mount time (`open()` below) the whole-file hash is recomputed, the
+//     signature over it is checked against the leaf certificate in
+//     `AUTHORITY.PEM`, and that chain is anchored in the trust store. An
+//     archive that fails any of those never becomes a filesystem at all.
+//
+//   * At *fetch* time every member is hashed as it is read and compared with
+//     the digest recorded for it in the archive that was verified at mount.
+//     The mount-time hash already covers every member's bytes, but it covers
+//     them *as they were when the file was hashed* — a `ZipFile` reads members
+//     lazily from an open fd, so anything that rewrites the file underneath a
+//     running program would otherwise be served unchecked. Verified content is
+//     kept (members are an application's own files, not the runtime), so each
+//     member is read and hashed at most once and what later reads see is the
+//     copy that was verified, not a fresh read of the file.
+//
+// Registering this with `vfs.registerProvider()` puts it ahead of the built-in
+// ZIP provider, so `--vfs-load` hands it the source first. It claims files by
+// extension (`.bundle`) *and* by content — anything carrying our signature
+// marker — so renaming a signed archive cannot quietly downgrade it to the
+// unverified built-in provider.
+
+export const EXTENSION = '.bundle';
+
+const READ_FLAGS = FS.constants.O_WRONLY | FS.constants.O_RDWR | FS.constants.O_CREAT |
+    FS.constants.O_TRUNC | FS.constants.O_APPEND | FS.constants.O_EXCL;
+
+export interface ProviderOptions {
+    /** File suffixes claimed outright (default: ['.bundle']). */
+    extensions?: string[] | undefined;
+    /**
+     * Also claim any file carrying our signature marker, whatever it is named
+     * (default: true). This is what keeps a renamed archive from falling
+     * through to the built-in ZIP provider, which checks nothing.
+     */
+    claimSigned?: boolean | undefined;
+    /**
+     * Extra trusted roots, as PEM text or paths to PEM files (default: the
+     * `BUNDLE_ROOTS` environment variable, a path-delimiter-separated list).
+     */
+    roots?: string[] | undefined;
+    /**
+     * Accept a good signature whose chain is not anchored in the trust store
+     * (default: the `BUNDLE_ALLOW_UNTRUSTED` environment variable).
+     */
+    allowUntrusted?: boolean | undefined;
+    /**
+     * Recompute every member digest at mount instead of on fetch
+     * (default: false — fetches check them anyway).
+     */
+    deep?: boolean | undefined;
+    /** Require this sigstore signing identity (default: `BUNDLE_IDENTITY`). */
+    identity?: string | undefined;
+    /** Require this sigstore OIDC issuer (default: `BUNDLE_ISSUER`). */
+    issuer?: string | undefined;
+    /** Path to the sigstore trust root (default: `BUNDLE_SIGSTORE_ROOT`). */
+    trustedRoot?: string | undefined;
+    /** Identifier reported in diagnostics (default: 'bundle'). */
+    name?: string | undefined;
+}
+
+interface Settings {
+    [kSettings]: true;
+    name: string;
+    extensions: string[];
+    claimSigned: boolean;
+    extraRoots: string[];
+    allowUntrusted: boolean;
+    deep: boolean;
+    identity: string | undefined;
+    issuer: string | undefined;
+    trustedRoot: string | undefined;
+}
+
+/**
+ * Verify `path` and return a provider that serves it, or throw. `options` are
+ * the same as `register()`'s.
+ */
+export function open(path: string, options?: ProviderOptions | Settings): BundleProvider {
+    const opts = settings(options);
+    const resolved = PATH.resolve(path);
+
+    // One ZipFile is opened here and handed to both the verification and the
+    // provider: the central directory is read once, and the digests the
+    // provider checks against are the ones the verified hash covered.
+    const archive = ZLIB.ZipFile.openSync(resolved);
+    try {
+        const res = verifySync(resolved, {
+            archive, deep: opts.deep, extraRoots: opts.extraRoots,
+            trustedRoot: opts.trustedRoot, identity: opts.identity, issuer: opts.issuer,
+        });
+        const acceptable = res.state === 'valid' || (opts.allowUntrusted && res.state === 'valid-untrusted');
+        if (!acceptable) throw refusal(resolved, res);
+        return new BundleProvider(archive, { hashAlg: res.hashAlg, digests: res.digests });
+    } catch (err) {
+        archive.closeSync();
+        throw err;
+    }
+}
+
+/**
+ * Register this provider with `node:vfs` so the `--vfs-load` startup flag
+ * selects it for signed archives. Meant to be preloaded, before `--vfs-load`
+ * picks a provider:
+ *
+ *   node --experimental-vfs -r @pipobscure/bundle/register --vfs-load=app.bundle
+ */
+export function register(options?: ProviderOptions): Settings {
+    const opts = settings(options);
+    VFS.registerProvider({
+        name: opts.name,
+        canHandle: (resolvedPath, stats) => stats.isFile() && claims(resolvedPath, opts),
+        create: (resolvedPath) => open(resolvedPath, opts),
+    });
+    return opts;
+}
+
+/**
+ * A read-only `ZipProvider` that will not hand out a member's content until
+ * that content has been hashed and matched against the digest recorded for it.
+ */
+export class BundleProvider extends VFS.ZipProvider {
+    #archive: ZLIB.ZipFile;
+    #hashAlg: string;
+    #digests: Map<string, string>;
+    #verified: VFS.MemoryProvider;
+
+    /**
+     * `digests` is the member-name -> hex-digest map from a `verifySync()` of
+     * this very archive; `hashAlg` the algorithm those digests are in.
+     */
+    constructor(archive: ZLIB.ZipFile, { hashAlg = 'sha256', digests = new Map<string, string>() }: {
+        hashAlg?: string | undefined;
+        digests?: Map<string, string> | undefined;
+    } = {}) {
+        super(archive);
+        this.#archive = archive;
+        this.#hashAlg = hashAlg;
+        this.#digests = digests;
+        this.#verified = new VFS.MemoryProvider();
+
+        // The manifest itself carries no digest of its own — it is what names
+        // the algorithms — but its bytes were read during the mount-time check,
+        // which the whole-file hash covered. Keep that copy so every path the
+        // mount serves comes from verified bytes.
+        if (archive.has(AUTHORITY)) {
+            const entry = archive.getSync(AUTHORITY);
+            this.#keep(AUTHORITY, entry.contentSync(), entry.mode);
+        }
+    }
+
+    // A signed archive is a fixed artifact: any write would invalidate the
+    // signature it was mounted on, so the mount is read-only regardless of how
+    // the underlying archive was opened.
+    override get readonly(): boolean { return true; }
+
+    override async open(path: string, flags?: string | number, mode?: number) {
+        const name = normalize(path);
+        if (reads(flags) && this.#check(name)) return this.#verified.open(path, flags, mode);
+        return super.open(path, flags, mode);
+    }
+
+    override openSync(path: string, flags?: string | number, mode?: number) {
+        const name = normalize(path);
+        if (reads(flags) && this.#check(name)) return this.#verified.openSync(path, flags, mode);
+        return super.openSync(path, flags, mode);
+    }
+
+    // Whether `name` can be served from verified content, reading and checking
+    // it on first use. `false` means this is not a member with a recorded
+    // digest (a directory, or nothing at all) and the base provider should
+    // answer — including with the ENOENT/EISDIR it would normally raise.
+    #check(name: string): boolean {
+        if (this.#verified.existsSync(`/${name}`)) return true;
+        const recorded = this.#digests.get(name);
+        if (recorded === undefined) return false;
+
+        const entry = this.#archive.getSync(name);
+        const content = entry.contentSync();
+        const actual = CRYPTO.createHash(this.#hashAlg).update(content).digest('hex');
+        if (actual !== recorded) {
+            throw Object.assign(new Error(
+                `bundle: content of '${name}' does not match its signed digest ` +
+                `(expected ${recorded}, got ${actual})`), { code: 'ERR_BUNDLE_INTEGRITY', member: name });
+        }
+        this.#keep(name, content, entry.mode);
+        return true;
+    }
+
+    #keep(name: string, content: Buffer, mode: number): void {
+        const dir = PATH.posix.dirname(`/${name}`);
+        if (dir !== '/' && dir !== '.') this.#verified.mkdirSync(dir, { recursive: true });
+        this.#verified.writeFileSync(`/${name}`, content, { mode: mode || 0o444 });
+    }
+}
+
+// Whether this provider should back `resolvedPath` (already known to be a
+// file): by name for the extensions it owns, and by content for anything
+// carrying our signature marker.
+function claims(resolvedPath: string, opts: Settings): boolean {
+    const lower = resolvedPath.toLowerCase();
+    if (opts.extensions.some((ext) => lower.endsWith(ext))) return true;
+    return opts.claimSigned && signatureOf(resolvedPath) !== null;
+}
+
+function refusal(path: string, res: VerificationResult): Error {
+    const detail = res.subject ? `${res.reason} [${res.subject.replace(/\n/g, ', ')}]` : res.reason;
+    return Object.assign(new Error(`bundle: refusing to mount '${path}': ${res.state} — ${detail}`),
+        { code: 'ERR_BUNDLE_UNTRUSTED', state: res.state });
+}
+
+// VFS paths are normalized to `/`-rooted POSIX paths; ZIP member names
+// have no leading slash.
+function normalize(path: string): string {
+    return path.startsWith('/') ? path.slice(1) : path;
+}
+
+// Whether `flags` opens purely for reading — the only case verified content can
+// answer. Anything else goes to the base provider, which refuses it (EROFS)
+// because this provider is read-only. Mirrors how `node:fs` itself reads flags:
+// a string means what it says, a number is a bitmask, anything else is 'r'.
+function reads(flags: string | number | undefined): boolean {
+    if (typeof flags === 'string') return flags === 'r';
+    if (typeof flags !== 'number') return true;
+    return (flags & READ_FLAGS) === 0;
+}
+
+const kSettings: unique symbol = Symbol('bundle.settings');
+
+function settings(options: ProviderOptions | Settings = {}): Settings {
+    if ((options as Settings)[kSettings]) return options as Settings;
+    const opts = options as ProviderOptions;
+    return {
+        [kSettings]: true,
+        name: opts.name ?? 'bundle',
+        extensions: (opts.extensions ?? [EXTENSION]).map((ext) => ext.toLowerCase()),
+        claimSigned: opts.claimSigned ?? true,
+        extraRoots: pems(opts.roots ?? envList('BUNDLE_ROOTS')),
+        allowUntrusted: opts.allowUntrusted ?? envFlag('BUNDLE_ALLOW_UNTRUSTED'),
+        deep: opts.deep ?? false,
+        identity: opts.identity ?? (process.env['BUNDLE_IDENTITY'] || undefined),
+        issuer: opts.issuer ?? (process.env['BUNDLE_ISSUER'] || undefined),
+        trustedRoot: opts.trustedRoot ?? (process.env['BUNDLE_SIGSTORE_ROOT'] || undefined),
+    };
+}
+
+// Accepts roots as PEM text or as paths to PEM files, so a caller can pass
+// either and `BUNDLE_ROOTS` can name files.
+function pems(roots: string[] | undefined): string[] {
+    return (roots ?? []).map((root) => (root.includes('-----BEGIN') ? root : FS.readFileSync(root, 'utf-8')));
+}
+
+function envList(name: string): string[] {
+    return (process.env[name] ?? '').split(PATH.delimiter).filter(Boolean);
+}
+
+function envFlag(name: string): boolean {
+    const value = process.env[name];
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}