@secure-exec/browser 0.0.0-agentos-dylib-base.edaa4a4

package/dist/converged-sync-bridge-handler.js

@@ -0,0 +1,140 @@
+// Converged sync-bridge handler.
+//
+// Replaces the legacy `runtime-driver.ts` `handleSyncBridgeOperation` (which
+// serviced guest syscalls against an in-process TypeScript kernel) with one
+// that routes every guest syscall to the wasm sidecar (`crates/sidecar-browser`)
+// over the wire protocol. The kernel becomes the single enforcement point for
+// both native and browser; the legacy fail-open TS executor is retired once this
+// is the live path.
+//
+// The handler is synchronous: it encodes a wire frame, calls the injected
+// synchronous `pushFrame` (the wasm `BrowserSidecarWasm.pushFrame`), decodes the
+// response frame, and returns the sync-bridge response the worker writes back to
+// the SAB. It is unit-tested with a fake synchronous `pushFrame`, no wasm needed.
+import { decodeProtocolFramePayload, encodeProtocolFramePayload, HostProtocolFrameFactory, } from "@secure-exec/core/protocol-frames";
+import { convergedFilesystemRequestPayload, convergedFilesystemSyncResponse, isSingleCallFilesystemOperation, wireStatToDirEntry, } from "./converged-fs-bridge.js";
+import { convergedNetRequestPayload, convergedNetSyncResponse, isConvergedNetBridgeOperation, } from "./converged-net-bridge.js";
+import { convergedDgramInlineResponse, convergedDgramRequestPayload, convergedDgramSyncResponse, dgramOperationUsesKernel, isConvergedDgramBridgeOperation, } from "./converged-dgram-bridge.js";
+import { SYNC_BRIDGE_KIND_JSON } from "./sync-bridge.js";
+/**
+ * Production transport: encodes a request frame, calls the synchronous wasm
+ * `pushFrame`, and decodes the response frame.
+ */
+export class PushFrameSidecarTransport {
+    frames = new HostProtocolFrameFactory();
+    pushFrame;
+    ownership;
+    codec;
+    constructor(options) {
+        this.pushFrame = options.pushFrame;
+        this.ownership = options.ownership;
+        this.codec = options.codec ?? "bare";
+    }
+    sendRequest(payload) {
+        const frame = this.frames.createRequestFrame({
+            ownership: this.ownership,
+            payload,
+        });
+        const responseBytes = this.pushFrame(encodeProtocolFramePayload(frame, this.codec));
+        const decoded = decodeProtocolFramePayload(responseBytes, this.codec);
+        if (decoded.frame_type !== "response") {
+            throw new Error(`converged sync bridge expected a response frame, got ${decoded.frame_type}`);
+        }
+        if (decoded.payload.type === "rejected") {
+            const message = decoded.payload.message;
+            const error = new Error(message);
+            // Kernel failures carry a leading POSIX errno ("EACCES: ...") in the
+            // message; surface that as the guest-visible error code (Node/POSIX
+            // semantics) rather than the generic wire rejection code.
+            const errno = /^(E[A-Z0-9_]+):/.exec(message);
+            error.code = errno
+                ? errno[1]
+                : decoded.payload.code;
+            throw error;
+        }
+        return decoded.payload;
+    }
+}
+export class ConvergedSyncBridgeHandler {
+    transport;
+    executionId;
+    constructor(options) {
+        this.transport = options.transport;
+        this.executionId = options.executionId;
+    }
+    /** True if this handler services `operation` against the wasm sidecar. */
+    handles(operation) {
+        return (operation === "fs.readDir" ||
+            isSingleCallFilesystemOperation(operation) ||
+            isConvergedNetBridgeOperation(operation) ||
+            isConvergedDgramBridgeOperation(operation));
+    }
+    handle(operation, args) {
+        if (operation === "fs.readDir") {
+            return this.readDir(String(args[0]));
+        }
+        if (isSingleCallFilesystemOperation(operation)) {
+            const result = this.callFilesystem(convergedFilesystemRequestPayload(operation, args));
+            return convergedFilesystemSyncResponse(operation, result);
+        }
+        if (isConvergedNetBridgeOperation(operation)) {
+            const result = this.callKernel(convergedNetRequestPayload(operation, args, this.executionId));
+            return convergedNetSyncResponse(result);
+        }
+        if (isConvergedDgramBridgeOperation(operation)) {
+            if (!dgramOperationUsesKernel(operation)) {
+                return convergedDgramInlineResponse(operation);
+            }
+            const result = this.callKernel(convergedDgramRequestPayload(operation, args, this.executionId));
+            return convergedDgramSyncResponse(operation, decodeKernelJson(result));
+        }
+        throw new Error(`converged sync bridge handler does not service ${operation}`);
+    }
+    readDir(path) {
+        // The wire `read_dir` returns names only; recover Dirent types with a
+        // per-entry `lstat` so `readdir(withFileTypes)` stays faithful.
+        const listing = this.callFilesystem({
+            type: "guest_filesystem_call",
+            operation: "read_dir",
+            path,
+        });
+        const entries = (listing.entries ?? []).map((name) => {
+            const child = this.callFilesystem({
+                type: "guest_filesystem_call",
+                operation: "lstat",
+                path: joinPath(path, name),
+            });
+            if (!child.stat) {
+                throw new Error(`lstat for ${name} returned no stat`);
+            }
+            return wireStatToDirEntry(name, child.stat);
+        });
+        return { kind: SYNC_BRIDGE_KIND_JSON, value: entries };
+    }
+    callFilesystem(payload) {
+        const response = this.transport.sendRequest(payload);
+        if (response.type !== "guest_filesystem_result") {
+            throw new Error(`expected guest_filesystem_result, got ${response.type}`);
+        }
+        return response;
+    }
+    callKernel(payload) {
+        const response = this.transport.sendRequest(payload);
+        if (response.type !== "guest_kernel_result") {
+            throw new Error(`expected guest_kernel_result, got ${response.type}`);
+        }
+        return response;
+    }
+}
+function joinPath(parent, child) {
+    if (parent.endsWith("/")) {
+        return `${parent}${child}`;
+    }
+    return `${parent}/${child}`;
+}
+function decodeKernelJson(result) {
+    if (result.payload.byteLength === 0) {
+        return null;
+    }
+    return JSON.parse(new TextDecoder().decode(new Uint8Array(result.payload)));
+}

package/dist/converged-sync-bridge-router.d.ts

@@ -0,0 +1,33 @@
+import type { ConvergedSyncResponse } from "./converged-fs-bridge.js";
+import type { ConvergedSyncBridgeHandler } from "./converged-sync-bridge-handler.js";
+/** Services a sync-bridge operation not yet handled by the converged path. */
+export type LegacySyncBridgeServicer = (operation: string, args: readonly unknown[]) => Promise<ConvergedSyncResponse>;
+/**
+ * An async converged servicer (e.g. module resolution) that routes its
+ * operations to the kernel but cannot be synchronous because it walks the
+ * filesystem. Tried after the sync handler, before the legacy fallback.
+ */
+export interface AsyncConvergedServicer {
+    handles(operation: string): boolean;
+    handle(operation: string, args: readonly unknown[]): Promise<ConvergedSyncResponse>;
+}
+export interface ConvergedSyncBridgeRouterOptions {
+    handler: ConvergedSyncBridgeHandler;
+    legacy: LegacySyncBridgeServicer;
+    asyncServicers?: readonly AsyncConvergedServicer[];
+}
+export declare class ConvergedSyncBridgeRouter {
+    private readonly handler;
+    private readonly legacy;
+    private readonly asyncServicers;
+    constructor(options: ConvergedSyncBridgeRouterOptions);
+    /**
+     * Route one sync-bridge operation: sync converged handler (fs/net/dns) first,
+     * then any async converged servicers (module resolution), then the legacy
+     * fallback for families not yet converged. Returns a promise either way so
+     * callers have a single await point.
+     */
+    route(operation: string, args: readonly unknown[]): Promise<ConvergedSyncResponse>;
+    /** True once every sync-bridge operation routes to a converged servicer. */
+    static isFullyConverged(handler: ConvergedSyncBridgeHandler, operations: readonly string[], asyncServicers?: readonly AsyncConvergedServicer[]): boolean;
+}

package/dist/converged-sync-bridge-router.js

@@ -0,0 +1,41 @@
+// Converged sync-bridge router.
+//
+// The migration seam between the legacy in-process TS-kernel sync-bridge
+// servicer (`runtime-driver.ts` `handleSyncBridgeOperation`) and the converged
+// wasm-kernel handler (`ConvergedSyncBridgeHandler`). Operations the converged
+// handler services (fs.* / net.* / dns.*) go to the wasm sidecar; everything not
+// yet converged (module.* / child_process.* / dgram.* / process.signal_state)
+// falls back to the legacy servicer. As each family is converged the fallback
+// shrinks; when it is empty the legacy servicer is deleted (spec slice 5).
+export class ConvergedSyncBridgeRouter {
+    handler;
+    legacy;
+    asyncServicers;
+    constructor(options) {
+        this.handler = options.handler;
+        this.legacy = options.legacy;
+        this.asyncServicers = options.asyncServicers ?? [];
+    }
+    /**
+     * Route one sync-bridge operation: sync converged handler (fs/net/dns) first,
+     * then any async converged servicers (module resolution), then the legacy
+     * fallback for families not yet converged. Returns a promise either way so
+     * callers have a single await point.
+     */
+    async route(operation, args) {
+        if (this.handler.handles(operation)) {
+            return this.handler.handle(operation, args);
+        }
+        for (const servicer of this.asyncServicers) {
+            if (servicer.handles(operation)) {
+                return servicer.handle(operation, args);
+            }
+        }
+        return this.legacy(operation, args);
+    }
+    /** True once every sync-bridge operation routes to a converged servicer. */
+    static isFullyConverged(handler, operations, asyncServicers = []) {
+        return operations.every((operation) => handler.handles(operation) ||
+            asyncServicers.some((servicer) => servicer.handles(operation)));
+    }
+}

package/dist/driver.d.ts

@@ -0,0 +1,91 @@
+import type { NetworkAdapter, Permissions, SystemDriver, VirtualFileSystem } from "./runtime.js";
+import { createCommandExecutorStub, createFsStub, createNetworkStub } from "./runtime.js";
+export interface BrowserRuntimeSystemOptions {
+    filesystem: "opfs" | "memory";
+    networkEnabled: boolean;
+}
+/**
+ * VFS backed by the Origin Private File System (OPFS) API. Falls back to
+ * InMemoryFileSystem when OPFS is unavailable. Rename is not supported
+ * (throws ENOSYS) since OPFS doesn't provide atomic rename.
+ */
+export declare class OpfsFileSystem implements VirtualFileSystem {
+    private rootPromise;
+    constructor();
+    private getDirHandle;
+    private getFileHandle;
+    readFile(path: string): Promise<Uint8Array>;
+    readTextFile(path: string): Promise<string>;
+    readDir(path: string): Promise<string[]>;
+    readDirWithTypes(path: string): Promise<Array<{
+        name: string;
+        isDirectory: boolean;
+    }>>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    createDir(path: string): Promise<void>;
+    mkdir(path: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<{
+        mode: number;
+        size: number;
+        blocks: number;
+        dev: number;
+        rdev: number;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+        atimeMs: number;
+        mtimeMs: number;
+        ctimeMs: number;
+        birthtimeMs: number;
+        ino: number;
+        nlink: number;
+        uid: number;
+        gid: number;
+    }>;
+    removeFile(path: string): Promise<void>;
+    removeDir(path: string): Promise<void>;
+    rename(_oldPath: string, _newPath: string): Promise<void>;
+    symlink(_target: string, _linkPath: string): Promise<void>;
+    readlink(_path: string): Promise<string>;
+    lstat(path: string): Promise<{
+        mode: number;
+        size: number;
+        blocks: number;
+        dev: number;
+        rdev: number;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+        atimeMs: number;
+        mtimeMs: number;
+        ctimeMs: number;
+        birthtimeMs: number;
+        ino: number;
+        nlink: number;
+        uid: number;
+        gid: number;
+    }>;
+    link(_oldPath: string, _newPath: string): Promise<void>;
+    chmod(_path: string, _mode: number): Promise<void>;
+    chown(_path: string, _uid: number, _gid: number): Promise<void>;
+    utimes(_path: string, _atime: number, _mtime: number): Promise<void>;
+    truncate(path: string, length: number): Promise<void>;
+    realpath(path: string): Promise<string>;
+    pread(path: string, offset: number, length: number): Promise<Uint8Array>;
+    pwrite(path: string, offset: number, data: Uint8Array): Promise<void>;
+}
+export interface BrowserDriverOptions {
+    filesystem?: "opfs" | "memory";
+    permissions?: Permissions;
+    useDefaultNetwork?: boolean;
+}
+/** Create an OPFS-backed filesystem, falling back to in-memory if OPFS is unavailable. */
+export declare function createOpfsFileSystem(): Promise<VirtualFileSystem>;
+/** Network adapter that delegates to the browser's native `fetch`. DNS and http2 are unsupported. */
+export declare function createBrowserNetworkAdapter(): NetworkAdapter;
+/** Recover runtime-driver options from a browser SystemDriver instance. */
+export declare function getBrowserSystemDriverOptions(systemDriver: SystemDriver): BrowserRuntimeSystemOptions;
+/** Assemble a browser-side SystemDriver with permission-wrapped adapters. */
+export declare function createBrowserDriver(options?: BrowserDriverOptions): Promise<SystemDriver>;
+export { createCommandExecutorStub, createFsStub, createNetworkStub };

package/dist/driver.js

@@ -0,0 +1,386 @@
+import { bytesToBase64 } from "./encoding.js";
+import { createCommandExecutorStub, createEnosysError, createFsStub, createInMemoryFileSystem, createNetworkStub, wrapFileSystem, wrapNetworkAdapter, } from "./runtime.js";
+const S_IFREG = 0o100000;
+const S_IFDIR = 0o040000;
+const BROWSER_SYSTEM_DRIVER_OPTIONS = Symbol.for("secure-exec.browserSystemDriverOptions");
+const LOOPBACK_DNS_NAMES = new Set([
+    "localhost",
+    "ip4-localhost",
+    "ip4-loopback",
+]);
+const LOOPBACK_IPV6_DNS_NAMES = new Set(["ip6-localhost", "ip6-loopback"]);
+function isIpv4Literal(hostname) {
+    const parts = hostname.split(".");
+    return (parts.length === 4 &&
+        parts.every((part) => {
+            if (!/^\d+$/.test(part))
+                return false;
+            const value = Number(part);
+            return value >= 0 && value <= 255 && String(value) === part;
+        }));
+}
+function isIpv6Literal(hostname) {
+    return hostname.includes(":") && /^[0-9a-fA-F:.]+$/.test(hostname);
+}
+function browserLocalDnsLookup(hostname) {
+    const normalized = hostname.trim().toLowerCase();
+    if (LOOPBACK_DNS_NAMES.has(normalized)) {
+        return { address: "127.0.0.1", family: 4 };
+    }
+    if (LOOPBACK_IPV6_DNS_NAMES.has(normalized)) {
+        return { address: "::1", family: 6 };
+    }
+    if (isIpv4Literal(normalized)) {
+        return { address: normalized, family: 4 };
+    }
+    if (isIpv6Literal(normalized)) {
+        return { address: normalized, family: 6 };
+    }
+    return { error: "DNS not supported in browser", code: "ENOSYS" };
+}
+function normalizePath(path) {
+    if (!path)
+        return "/";
+    let normalized = path.startsWith("/") ? path : `/${path}`;
+    normalized = normalized.replace(/\/+/g, "/");
+    if (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+function splitPath(path) {
+    const normalized = normalizePath(path);
+    return normalized === "/" ? [] : normalized.slice(1).split("/");
+}
+function dirname(path) {
+    const parts = splitPath(path);
+    if (parts.length <= 1)
+        return "/";
+    return `/${parts.slice(0, -1).join("/")}`;
+}
+async function getRootHandle() {
+    if (!("storage" in navigator) || !("getDirectory" in navigator.storage)) {
+        throw createEnosysError("opfs");
+    }
+    return navigator.storage.getDirectory();
+}
+/**
+ * VFS backed by the Origin Private File System (OPFS) API. Falls back to
+ * InMemoryFileSystem when OPFS is unavailable. Rename is not supported
+ * (throws ENOSYS) since OPFS doesn't provide atomic rename.
+ */
+export class OpfsFileSystem {
+    rootPromise;
+    constructor() {
+        this.rootPromise = getRootHandle();
+    }
+    async getDirHandle(path, create = false) {
+        const root = await this.rootPromise;
+        const parts = splitPath(path);
+        let current = root;
+        for (const part of parts) {
+            current = await current.getDirectoryHandle(part, { create });
+        }
+        return current;
+    }
+    async getFileHandle(path, create = false) {
+        const normalized = normalizePath(path);
+        const parent = dirname(normalized);
+        const name = normalized.split("/").pop() || "";
+        const dir = await this.getDirHandle(parent, create);
+        return dir.getFileHandle(name, { create });
+    }
+    async readFile(path) {
+        const handle = await this.getFileHandle(path);
+        const file = await handle.getFile();
+        const buffer = await file.arrayBuffer();
+        return new Uint8Array(buffer);
+    }
+    async readTextFile(path) {
+        const handle = await this.getFileHandle(path);
+        const file = await handle.getFile();
+        return file.text();
+    }
+    async readDir(path) {
+        const dir = await this.getDirHandle(path);
+        const entries = [];
+        for await (const [name] of dir.entries()) {
+            entries.push(name);
+        }
+        return entries;
+    }
+    async readDirWithTypes(path) {
+        const dir = await this.getDirHandle(path);
+        const entries = [];
+        for await (const [name, handle] of dir.entries()) {
+            entries.push({
+                name,
+                isDirectory: handle.kind === "directory",
+            });
+        }
+        return entries;
+    }
+    async writeFile(path, content) {
+        const normalized = normalizePath(path);
+        await this.mkdir(dirname(normalized));
+        const handle = await this.getFileHandle(normalized, true);
+        const writable = await handle.createWritable();
+        if (typeof content === "string") {
+            await writable.write(content);
+        }
+        else {
+            await writable.write(content);
+        }
+        await writable.close();
+    }
+    async createDir(path) {
+        const normalized = normalizePath(path);
+        const parent = dirname(normalized);
+        await this.getDirHandle(parent, false);
+        await this.getDirHandle(normalized, true);
+    }
+    async mkdir(path, _options) {
+        const parts = splitPath(path);
+        let current = "";
+        for (const part of parts) {
+            current += `/${part}`;
+            await this.getDirHandle(current, true);
+        }
+    }
+    async exists(path) {
+        try {
+            await this.getFileHandle(path);
+            return true;
+        }
+        catch {
+            try {
+                await this.getDirHandle(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    async stat(path) {
+        try {
+            const handle = await this.getFileHandle(path);
+            const file = await handle.getFile();
+            return {
+                mode: S_IFREG | 0o644,
+                size: file.size,
+                blocks: file.size === 0 ? 0 : Math.ceil(file.size / 512),
+                dev: 1,
+                rdev: 0,
+                isDirectory: false,
+                isSymbolicLink: false,
+                atimeMs: file.lastModified,
+                mtimeMs: file.lastModified,
+                ctimeMs: file.lastModified,
+                birthtimeMs: file.lastModified,
+                ino: 0,
+                nlink: 1,
+                uid: 0,
+                gid: 0,
+            };
+        }
+        catch {
+            const normalized = normalizePath(path);
+            try {
+                await this.getDirHandle(normalized);
+                const now = Date.now();
+                return {
+                    mode: S_IFDIR | 0o755,
+                    size: 4096,
+                    blocks: 8,
+                    dev: 1,
+                    rdev: 0,
+                    isDirectory: true,
+                    isSymbolicLink: false,
+                    atimeMs: now,
+                    mtimeMs: now,
+                    ctimeMs: now,
+                    birthtimeMs: now,
+                    ino: 0,
+                    nlink: 2,
+                    uid: 0,
+                    gid: 0,
+                };
+            }
+            catch {
+                throw new Error(`ENOENT: no such file or directory, stat '${normalized}'`);
+            }
+        }
+    }
+    async removeFile(path) {
+        const normalized = normalizePath(path);
+        const parent = dirname(normalized);
+        const name = normalized.split("/").pop() || "";
+        const dir = await this.getDirHandle(parent);
+        await dir.removeEntry(name);
+    }
+    async removeDir(path) {
+        const normalized = normalizePath(path);
+        if (normalized === "/") {
+            throw new Error("EPERM: operation not permitted, rmdir '/'");
+        }
+        const parent = dirname(normalized);
+        const name = normalized.split("/").pop() || "";
+        const dir = await this.getDirHandle(parent);
+        await dir.removeEntry(name);
+    }
+    async rename(_oldPath, _newPath) {
+        throw createEnosysError("rename");
+    }
+    async symlink(_target, _linkPath) {
+        throw createEnosysError("symlink");
+    }
+    async readlink(_path) {
+        throw createEnosysError("readlink");
+    }
+    async lstat(path) {
+        return this.stat(path);
+    }
+    async link(_oldPath, _newPath) {
+        throw createEnosysError("link");
+    }
+    async chmod(_path, _mode) {
+        // No-op: OPFS does not support POSIX permissions
+    }
+    async chown(_path, _uid, _gid) {
+        // No-op: OPFS does not support POSIX ownership
+    }
+    async utimes(_path, _atime, _mtime) {
+        // No-op: OPFS does not support timestamp manipulation
+    }
+    async truncate(path, length) {
+        const handle = await this.getFileHandle(path);
+        const writable = await handle.createWritable({ keepExistingData: true });
+        await writable.truncate(length);
+        await writable.close();
+    }
+    async realpath(path) {
+        const normalized = normalizePath(path);
+        if (await this.exists(normalized))
+            return normalized;
+        throw new Error(`ENOENT: no such file or directory, realpath '${normalized}'`);
+    }
+    async pread(path, offset, length) {
+        const data = await this.readFile(path);
+        return data.slice(offset, offset + length);
+    }
+    async pwrite(path, offset, data) {
+        const content = await this.readFile(path);
+        const endPos = offset + data.length;
+        const newContent = new Uint8Array(Math.max(content.length, endPos));
+        newContent.set(content);
+        newContent.set(data, offset);
+        await this.writeFile(path, newContent);
+    }
+}
+/** Create an OPFS-backed filesystem, falling back to in-memory if OPFS is unavailable. */
+export async function createOpfsFileSystem() {
+    if (!("storage" in navigator) ||
+        typeof navigator.storage.getDirectory !== "function") {
+        return createInMemoryFileSystem();
+    }
+    return new OpfsFileSystem();
+}
+/** Network adapter that delegates to the browser's native `fetch`. DNS and http2 are unsupported. */
+export function createBrowserNetworkAdapter() {
+    return {
+        async fetch(url, options) {
+            const response = await fetch(url, {
+                method: options?.method || "GET",
+                headers: options?.headers,
+                body: options?.body,
+            });
+            const headers = {};
+            response.headers.forEach((v, k) => {
+                headers[k] = v;
+            });
+            const contentType = response.headers.get("content-type") || "";
+            const isBinary = contentType.includes("octet-stream") ||
+                contentType.includes("gzip") ||
+                url.endsWith(".tgz");
+            let body;
+            if (isBinary) {
+                const buffer = await response.arrayBuffer();
+                body = bytesToBase64(new Uint8Array(buffer));
+                headers["x-body-encoding"] = "base64";
+            }
+            else {
+                body = await response.text();
+            }
+            return {
+                ok: response.ok,
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+                body,
+                url: response.url,
+                redirected: response.redirected,
+            };
+        },
+        async dnsLookup(hostname) {
+            return browserLocalDnsLookup(hostname);
+        },
+        async httpRequest(url, options) {
+            const response = await fetch(url, {
+                method: options?.method || "GET",
+                headers: options?.headers,
+                body: options?.body,
+            });
+            const headers = {};
+            response.headers.forEach((v, k) => {
+                headers[k] = v;
+            });
+            const body = await response.text();
+            return {
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+                body,
+                url: response.url,
+            };
+        },
+    };
+}
+/** Recover runtime-driver options from a browser SystemDriver instance. */
+export function getBrowserSystemDriverOptions(systemDriver) {
+    const options = systemDriver[BROWSER_SYSTEM_DRIVER_OPTIONS];
+    if (options) {
+        return options;
+    }
+    return {
+        filesystem: "opfs",
+        networkEnabled: Boolean(systemDriver.network),
+    };
+}
+/** Assemble a browser-side SystemDriver with permission-wrapped adapters. */
+export async function createBrowserDriver(options = {}) {
+    const permissions = options.permissions;
+    const filesystemMode = options.filesystem ?? "opfs";
+    const filesystem = filesystemMode === "memory"
+        ? createInMemoryFileSystem()
+        : await createOpfsFileSystem();
+    const networkAdapter = options.useDefaultNetwork
+        ? wrapNetworkAdapter(createBrowserNetworkAdapter(), permissions)
+        : undefined;
+    const systemDriver = {
+        filesystem: wrapFileSystem(filesystem, permissions),
+        network: networkAdapter,
+        commandExecutor: createCommandExecutorStub(),
+        permissions,
+        runtime: {
+            process: {},
+            os: {},
+        },
+    };
+    systemDriver[BROWSER_SYSTEM_DRIVER_OPTIONS] = {
+        filesystem: filesystemMode,
+        networkEnabled: Boolean(networkAdapter),
+    };
+    return systemDriver;
+}
+export { createCommandExecutorStub, createFsStub, createNetworkStub };