@ricsam/r5d-browser 0.0.136 → 0.0.138

package/dist/types/personal-main.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserCliOptions } from "./cli-options";
+export declare function personalBrowserConnection(options: BrowserCliOptions): {
+    origin: string;
+    token: string;
+};
+/** Keep Chrome's OS environment intact while isolating r5d state per origin. */
+export declare function personalBrowserStateDirectory(origin: string, rootPath?: string): string;
+/** The locally retained keeper, profile and ledger outlive every web reconnect. */
+export declare function startPersonalBrowser(options: BrowserCliOptions, version: string): Promise<void>;

package/dist/types/personal-port-forward.d.ts

@@ -0,0 +1,45 @@
+import type { PersonalBrowserObserver } from "./personal-diagnostics";
+export type ForwardRequest = {
+    forwardId: string;
+    streamId: string;
+    requestId: string;
+    command: {
+        method: "connect" | "write" | "read" | "close";
+        offset?: number;
+        after?: number;
+        base64?: string;
+        end?: boolean;
+    };
+};
+export type ForwardCall = (request: ForwardRequest) => Promise<any>;
+export declare class PersonalForwardResponseError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+/** Local loopback sockets outlive every HTTP relay/web connection. Each byte
+ * operation waits for its immutable acknowledgement before advancing offsets. */
+export declare class PersonalPortForwardManager {
+    private readonly call;
+    private readonly observer?;
+    private active;
+    private failures;
+    private queue;
+    private stopping;
+    constructor(call: ForwardCall, observer?: PersonalBrowserObserver | undefined);
+    private observe;
+    list(): {
+        forwardId: string;
+        ready: boolean;
+        activeConnections: number;
+        lastError: {
+            error: string;
+            at: string;
+        } | null;
+    }[];
+    reconcile(raw: unknown): Promise<void>;
+    private start;
+    private stop;
+    private accept;
+    close(): Promise<void>;
+}

package/dist/types/personal-relay-client.d.ts

@@ -0,0 +1,51 @@
+import { BrowserKeeper } from "./runtime/keeper";
+import { type BrowserReceipt } from "./runtime/protocol";
+import { z } from "zod";
+export declare const PersonalBrowserAction: z.ZodObject<{
+    id: z.ZodString;
+    requestHash: z.ZodString;
+    request: z.ZodObject<{
+        action: z.ZodEnum<{
+            list_tabs: "list_tabs";
+            list_downloads: "list_downloads";
+            get_download: "get_download";
+            open_tab: "open_tab";
+            close_tab: "close_tab";
+            navigate: "navigate";
+            set_viewport: "set_viewport";
+            read_page: "read_page";
+            screenshot: "screenshot";
+            move_mouse: "move_mouse";
+            mouse_click: "mouse_click";
+            scroll: "scroll";
+            wait_for: "wait_for";
+            form_input: "form_input";
+            keyboard: "keyboard";
+            keyboard_type: "keyboard_type";
+            run_js: "run_js";
+            upload_begin: "upload_begin";
+            upload_chunk: "upload_chunk";
+            upload_attach: "upload_attach";
+            upload_abort: "upload_abort";
+        }>;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Network replacement never disposes this keeper. Its ledger decides whether an
+ * action ran; polling the same server queue item cannot replay a browser effect. */
+export declare class PersonalBrowserProcessor {
+    private readonly keeper;
+    readonly identity: {
+        installationId: string;
+        userId: string;
+        instanceId: string;
+    };
+    private readonly nextEpoch?;
+    private epoch;
+    constructor(keeper: BrowserKeeper, identity: {
+        installationId: string;
+        userId: string;
+        instanceId: string;
+    }, nextEpoch?: (() => number) | undefined);
+    execute(raw: unknown): Promise<BrowserReceipt>;
+}

package/dist/types/personal-relay-shutdown.d.ts

@@ -0,0 +1,19 @@
+type RelayAction = {
+    id: string;
+    requestHash: string;
+};
+export type PersonalBrowserAcknowledgement = {
+    id: string;
+    requestHash: string;
+    state: "completed" | "unknown";
+    result: unknown;
+};
+/** Shutdown cancels queue observation, never an admitted browser effect or its receipt. */
+export declare class PersonalBrowserRelayShutdown {
+    private readonly polls;
+    get stopping(): boolean;
+    get pollSignal(): AbortSignal;
+    stop(): void;
+    dispatch<T extends RelayAction>(actions: readonly T[], execute: (action: T) => Promise<unknown>, acknowledge: (receipt: PersonalBrowserAcknowledgement) => Promise<unknown>): Promise<void>;
+}
+export {};

package/dist/types/runtime/browser-executor.d.ts

@@ -0,0 +1,8 @@
+import type { BrowserRuntime } from "../browser-runtime";
+import type { BrowserExecutor } from "./keeper";
+/**
+ * The supplied runtime must be constructed/retained by the independently supervised keeper.
+ * It is not recreated on adapter replacement. This uses the existing action implementation,
+ * including its retained tab IDs, cursor, CDP sessions and upload store, without profile copies.
+ */
+export declare function browserRuntimeExecutor(runtime: Pick<BrowserRuntime, "execute">): BrowserExecutor;

package/dist/types/runtime/chromium-factory.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { BrowserExecutor } from "./keeper";
+/** Declarative built-in factory approval, NOT an arbitrary JS module or Chromium argument escape hatch. */
+export declare const ChromiumFactoryApproval: z.ZodObject<{
+    kind: z.ZodLiteral<"isolated-chromium-v1">;
+    executablePath: z.ZodString;
+    allowedOrigins: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ChromiumFactoryApproval = z.infer<typeof ChromiumFactoryApproval>;
+export declare function loadApprovedChromiumFactory(filename: string, sha256: string): ChromiumFactoryApproval;
+export type ChromiumKeeperIdentity = {
+    runId: string;
+    browserPid: number;
+    keeperPid: number;
+    profile: string;
+    downloads: string;
+    uploads: string;
+};
+export declare function createIsolatedChromiumRuntime(input: {
+    runs: string;
+    approval: ChromiumFactoryApproval;
+}): Promise<{
+    executor: BrowserExecutor;
+    identity: ChromiumKeeperIdentity;
+}>;

package/dist/types/runtime/fixtures/counter-main.d.ts

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

package/dist/types/runtime/fixtures/counter-runtime.d.ts

@@ -0,0 +1,7 @@
+import type { BrowserExecutor } from "../keeper";
+/** Offline subprocess proof. No Chrome, network, profiles or user resources. */
+export declare const createBrowserKeeperRuntime: ({ directory }: {
+    directory: string;
+}) => Promise<{
+    executor: BrowserExecutor;
+}>;

package/dist/types/runtime/ipc.d.ts

@@ -0,0 +1,23 @@
+import { BrowserKeeper, type BrowserAdapterPrincipal } from "./keeper";
+import { type BrowserKeeperMessage } from "./protocol";
+export type BrowserKeeperIpcOptions = {
+    keeper: BrowserKeeper;
+    socketPath: string;
+    /** Authentication must bind installation + user + owner; an unverified hello is NOT authority. */
+    authenticate: (token: string) => BrowserAdapterPrincipal | null;
+    maxFrameBytes?: number;
+    maxConnections?: number;
+};
+export type BrowserKeeperIpc = {
+    close(): Promise<void>;
+};
+/** One bounded JSON request/reply per private Unix connection. No raw requests/errors are logged. */
+export declare function serveBrowserKeeper(options: BrowserKeeperIpcOptions): Promise<BrowserKeeperIpc>;
+/** No automatic retries: caller resubmits the SAME operation ID to reconcile a lost response. */
+export declare function callBrowserKeeper(options: {
+    socketPath: string;
+    token: string;
+    message: BrowserKeeperMessage;
+    timeoutMs?: number;
+    maxReplyBytes?: number;
+}): Promise<unknown>;

package/dist/types/runtime/isolated-root.d.ts

@@ -0,0 +1,12 @@
+export declare function isolatedBrowserRoot(root: string, installationId: string, userId: string): {
+    ledger: string;
+    runs: string;
+};
+export declare function freshBrowserRun(runs: string): {
+    id: string;
+    directory: string;
+    profile: string;
+    downloads: string;
+    uploads: string;
+    home: string;
+};

package/dist/types/runtime/keeper.d.ts

@@ -0,0 +1,44 @@
+import { RuntimeHello } from "@ricsam/r5d-api/runtime-protocol";
+import { type LedgerOptions } from "./ledger";
+import { BrowserOperation, type BrowserReceipt } from "./protocol";
+/** Granted by the authenticated transport, NEVER inferred from hello or request fields. */
+export type BrowserAdapterPrincipal = {
+    installationId: string;
+    userId: string;
+    ownerId: string;
+};
+/** This object and its browser handles live in the keeper, not in a replaceable socket adapter. */
+export interface BrowserExecutor {
+    execute(operation: BrowserOperation): Promise<unknown>;
+    /** Keeper maintenance only; called after drain while still holding the exclusive ledger lock. */
+    dispose?(): Promise<void>;
+}
+export type BrowserKeeperOptions = LedgerOptions & {
+    executor: BrowserExecutor;
+    instanceId: string;
+    releaseId: string;
+    maxInFlight?: number;
+    maxPayloadBytes?: number;
+};
+export declare class BrowserKeeper {
+    readonly hello: RuntimeHello;
+    private readonly ledger;
+    private readonly executor;
+    private readonly inFlight;
+    private readonly queues;
+    private readonly maxInFlight;
+    private readonly maxPayloadBytes;
+    private readonly pruneTimer;
+    private closing;
+    private closePromise;
+    private storageFailed;
+    constructor(options: BrowserKeeperOptions);
+    /** Callable versioned boundary. Transport disconnect is deliberately not an AbortSignal. */
+    handle(input: unknown, principal: BrowserAdapterPrincipal): Promise<BrowserReceipt | {
+        ok: true;
+    } | null>;
+    private handleRequest;
+    private perform;
+    /** Maintenance only: adapter disconnection must NOT invoke close or executor disposal. */
+    close(): Promise<void>;
+}

package/dist/types/runtime/ledger.d.ts

@@ -0,0 +1,41 @@
+import { type OwnershipFence } from "@ricsam/r5d-api/runtime-protocol";
+import { type BrowserOperation, type BrowserReceipt } from "./protocol";
+export type LedgerOptions = {
+    directory: string;
+    installationId: string;
+    userId: string;
+    now?: () => number;
+    retentionMs?: number;
+    maxReceiptBytes?: number;
+    maxTotalReceiptBytes?: number;
+    maxOperations?: number;
+    maxClaims?: number;
+    maxLeaseMs?: number;
+};
+/** Local single-process authority. The exclusive SQLite lock is retained until close/crash. */
+export declare class BrowserLedger {
+    private readonly db;
+    private readonly now;
+    readonly installationId: string;
+    readonly userId: string;
+    private readonly retentionMs;
+    private readonly maxReceiptBytes;
+    private readonly maxTotalReceiptBytes;
+    private readonly maxOperations;
+    private readonly maxClaims;
+    private readonly maxLeaseMs;
+    constructor(options: LedgerOptions);
+    assertIdentity(installationId: string, userId: string): void;
+    private claimRow;
+    assertFence(fence: OwnershipFence): void;
+    claim(fence: OwnershipFence, expiresAt: number, renew?: boolean): void;
+    release(fence: OwnershipFence): void;
+    private count;
+    find(operation: BrowserOperation, hash: string): BrowserReceipt | null;
+    admit(operation: BrowserOperation, hash: string): void;
+    running(operationId: string): void;
+    finish(operationId: string, state: "completed" | "cancelled" | "unknown", resultJson: string | null, reason?: BrowserReceipt["reason"]): void;
+    prune(): void;
+    private receipt;
+    close(): void;
+}

package/dist/types/runtime/main.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { type ChromiumKeeperIdentity } from "./chromium-factory";
+export declare const BrowserKeeperConfig: z.ZodObject<{
+    installationId: z.ZodString;
+    userId: z.ZodString;
+    instanceId: z.ZodString;
+    releaseId: z.ZodString;
+    root: z.ZodString;
+    factory: z.ZodObject<{
+        approvalPath: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>;
+    adapters: z.ZodArray<z.ZodObject<{
+        ownerId: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Only the built-in isolated REAL Chromium factory is reachable from this startup boundary. */
+export declare function startConfiguredBrowserKeeper(configPath: string): Promise<{
+    socketPath: string;
+    identity: ChromiumKeeperIdentity;
+    close(): Promise<void>;
+}>;

package/dist/types/runtime/private-paths.d.ts

@@ -0,0 +1,4 @@
+/** Reject symlink ancestors, non-canonical paths and writable-by-other-user ancestors. */
+export declare function assertPrivatePath(filename: string, kind: "directory" | "file", immutable?: boolean): void;
+export declare function readPrivateFile(filename: string, maximumBytes: number, immutable?: boolean): Buffer;
+export declare function makePrivateDirectory(directory: string): void;

package/dist/types/runtime/protocol.d.ts

@@ -0,0 +1,228 @@
+import { z } from "zod";
+import { RUNTIME_PROTOCOL } from "@ricsam/r5d-api/runtime-protocol";
+export declare const BROWSER_KEEPER_CAPABILITY = "browser-operations.v1";
+export declare const BrowserAction: z.ZodEnum<{
+    list_tabs: "list_tabs";
+    list_downloads: "list_downloads";
+    get_download: "get_download";
+    open_tab: "open_tab";
+    close_tab: "close_tab";
+    navigate: "navigate";
+    set_viewport: "set_viewport";
+    read_page: "read_page";
+    screenshot: "screenshot";
+    move_mouse: "move_mouse";
+    mouse_click: "mouse_click";
+    scroll: "scroll";
+    wait_for: "wait_for";
+    form_input: "form_input";
+    keyboard: "keyboard";
+    keyboard_type: "keyboard_type";
+    run_js: "run_js";
+    upload_begin: "upload_begin";
+    upload_chunk: "upload_chunk";
+    upload_attach: "upload_attach";
+    upload_abort: "upload_abort";
+}>;
+export declare const BrowserFence: z.ZodObject<{
+    installationId: z.ZodString;
+    resourceType: z.ZodString;
+    resourceId: z.ZodString;
+    ownerId: z.ZodString;
+    epoch: z.ZodNumber;
+}, z.core.$strict>;
+export declare const BrowserOperation: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    installationId: z.ZodString;
+    operationId: z.ZodString;
+    userId: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodString;
+    fence: z.ZodObject<{
+        installationId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        ownerId: z.ZodString;
+        epoch: z.ZodNumber;
+    }, z.core.$strict>;
+    payload: z.ZodUnknown;
+}, z.core.$strict>;
+export type BrowserOperation = z.infer<typeof BrowserOperation>;
+export declare const BrowserKeeperRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    method: z.ZodLiteral<"claim">;
+    userId: z.ZodString;
+    fence: z.ZodObject<{
+        installationId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        ownerId: z.ZodString;
+        epoch: z.ZodNumber;
+    }, z.core.$strict>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"renew">;
+    userId: z.ZodString;
+    fence: z.ZodObject<{
+        installationId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        ownerId: z.ZodString;
+        epoch: z.ZodNumber;
+    }, z.core.$strict>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"release">;
+    userId: z.ZodString;
+    fence: z.ZodObject<{
+        installationId: z.ZodString;
+        resourceType: z.ZodString;
+        resourceId: z.ZodString;
+        ownerId: z.ZodString;
+        epoch: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"execute">;
+    operation: z.ZodObject<{
+        protocol: z.ZodLiteral<1>;
+        installationId: z.ZodString;
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodString;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+        payload: z.ZodUnknown;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"inspect">;
+    operation: z.ZodObject<{
+        protocol: z.ZodLiteral<1>;
+        installationId: z.ZodString;
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodString;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+        payload: z.ZodUnknown;
+    }, z.core.$strict>;
+}, z.core.$strict>], "method">;
+export type BrowserKeeperRequest = z.infer<typeof BrowserKeeperRequest>;
+export declare const BrowserKeeperMessage: z.ZodObject<{
+    hello: z.ZodObject<{
+        installationId: z.ZodString;
+        instanceId: z.ZodString;
+        releaseId: z.ZodString;
+        role: z.ZodEnum<{
+            web: "web";
+            scheduler: "scheduler";
+            runner: "runner";
+            gateway: "gateway";
+            "worker-adapter": "worker-adapter";
+            "browser-adapter": "browser-adapter";
+            executor: "executor";
+            keeper: "keeper";
+            storage: "storage";
+        }>;
+        protocol: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, z.core.$strict>;
+        capabilities: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    request: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        method: z.ZodLiteral<"claim">;
+        userId: z.ZodString;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"renew">;
+        userId: z.ZodString;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"release">;
+        userId: z.ZodString;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"execute">;
+        operation: z.ZodObject<{
+            protocol: z.ZodLiteral<1>;
+            installationId: z.ZodString;
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            kind: z.ZodString;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+            payload: z.ZodUnknown;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"inspect">;
+        operation: z.ZodObject<{
+            protocol: z.ZodLiteral<1>;
+            installationId: z.ZodString;
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            kind: z.ZodString;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+            payload: z.ZodUnknown;
+        }, z.core.$strict>;
+    }, z.core.$strict>], "method">;
+}, z.core.$strict>;
+export type BrowserKeeperMessage = z.infer<typeof BrowserKeeperMessage>;
+export type BrowserReceipt = {
+    protocol: typeof RUNTIME_PROTOCOL;
+    installationId: string;
+    userId: string;
+    operationId: string;
+    payloadHash: string;
+    state: "accepted" | "running" | "completed" | "cancelled" | "unknown";
+    resultAvailable: boolean;
+    result?: unknown;
+    reason?: "keeper_restarted" | "executor_uncertain" | "stale_before_start" | "receipt_too_large";
+};
+export declare class BrowserKeeperError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.136",
+  "version": "0.0.138",
   "type": "module",
-  "main": "./dist/cjs/main.cjs",
+  "main": "./dist/mjs/main.mjs",
   "module": "./dist/mjs/main.mjs",
   "types": "./dist/types/main.d.ts",
   "exports": {
     ".": {
       "types": "./dist/types/main.d.ts",
       "import": "./dist/mjs/main.mjs",
-      "require": "./dist/cjs/main.cjs"
+      "default": "./dist/mjs/main.mjs"
     }
   },
   "repository": {
@@ -18,11 +18,12 @@
     "directory": "packages/r5d-browser"
   },
   "bin": {
-    "r5d-browser": "dist/cjs/main.cjs"
+    "r5d-browser": "dist/mjs/main.mjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.136",
+    "@ricsam/r5d-api": "^0.0.138",
     "playwright-core": "1.62.1",
+    "zod": "^4.1.13",
     "ws": "^8.18.3"
   },
   "files": [