codex-webstrapper 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codex-webstrap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# codex-webstrap
+
+![Frosted Sidebar Demo](assets/frosted-sidebar.gif)
+
+`codex-webstrap` is a macOS wrapper that lets you run the Codex desktop client UI in a browser while keeping backend execution local.
+
+This started as a personal project to remotely access the Codex desktop experience; it is open sourced so others can use and improve it.
+
+## What It Is
+
+
+https://github.com/user-attachments/assets/24e023ee-6a74-448c-892d-9fc1964bd10c
+
+
+Codex desktop is not a pure web app. The renderer expects Electron preload APIs, IPC, local process control, worker threads, and desktop-only integrations.
+
+`codex-webstrap` makes browser access possible by:
+
+1. Serving Codex's bundled web assets.
+2. Injecting a browser shim that emulates key `electronBridge` preload methods.
+3. Bridging renderer messages over WebSocket to local backend handlers.
+4. Forwarding app protocol traffic to local `codex app-server` and UDS IPC where available.
+
+Default endpoint: `http://127.0.0.1:8080`
+
+## Architecture
+
+### Core Components
+
+- `bin/codex-webstrap.sh`
+  - CLI entrypoint and env/arg normalization.
+- `src/server.mjs`
+  - HTTP + WS host, auth gating, startup orchestration.
+- `src/auth.mjs`
+  - Persistent token bootstrap + `cw_session` cookie sessions.
+- `src/assets.mjs`
+  - Discovers Codex app bundle, extracts/caches `app.asar` assets, patches `index.html`.
+- `src/bridge-shim.js`
+  - Browser-side Electron preload compatibility layer (`window.electronBridge`).
+- `src/ipc-uds.mjs`
+  - Framed UDS client (`length-prefix + JSON`) for `codex-ipc`.
+- `src/app-server.mjs`
+  - Local `codex app-server` process manager over stdio JSON-RPC.
+- `src/message-router.mjs`
+  - Message dispatch, terminal lifecycle, worker bridge, unsupported fallbacks.
+
+### Runtime Flow
+
+1. Wrapper starts Node server and loads config.
+2. Auth token is created/read from token file.
+3. Codex app assets are extracted to a versioned cache directory.
+4. Patched `index.html` is served with shim injection.
+5. Browser opens `/`, shim connects to `ws://<host>/__webstrapper/bridge`.
+6. Renderer messages are routed to:
+   - app-server JSON-RPC (`thread/*`, turns, config, etc.)
+   - UDS broadcast forwarding where relevant
+   - terminal sessions (`spawn`, `write`, `close`)
+   - git worker bridge path
+7. Results are sent back as bridge envelopes and posted to the renderer via `window.postMessage`.
+
+## Why This Is Not "Native Web"
+
+Codex desktop behavior depends on Electron/main-process features unavailable to normal browser JavaScript, including:
+
+- preload-only bridge APIs
+- local privileged process orchestration
+- desktop IPC channels
+- local worker/protocol assumptions
+
+This project provides near-parity by emulation/bridging, not by removing those dependencies.
+
+## API Surface
+
+### CLI
+
+```bash
+codex-webstrap [--port <n>] [--bind <ip>] [--open] [--token-file <path>] [--codex-app <path>]
+```
+
+### Environment Overrides
+
+- `CODEX_WEBSTRAP_PORT`
+- `CODEX_WEBSTRAP_BIND`
+- `CODEX_WEBSTRAP_TOKEN_FILE`
+- `CODEX_WEBSTRAP_CODEX_APP`
+- `CODEX_WEBSTRAP_INTERNAL_WS_PORT`
+
+### HTTP Endpoints
+
+- `GET /`
+- `GET /__webstrapper/shim.js`
+- `GET /__webstrapper/healthz`
+- `GET /__webstrapper/auth?token=...`
+
+### WebSocket Endpoint
+
+- `GET /__webstrapper/bridge`
+
+### Bridge Envelope Types
+
+- `view-message`
+- `main-message`
+- `worker-message`
+- `worker-event`
+- `bridge-error`
+- `bridge-ready`
+
+## Setup
+
+### Prerequisites
+
+- macOS
+- Node.js 20+
+- Installed Codex app bundle at `/Applications/Codex.app` (or pass `--codex-app`)
+- `codex` CLI available in `PATH` (or set `CODEX_CLI_PATH`)
+
+### Install
+
+```bash
+npm install
+```
+
+Global CLI install:
+
+```bash
+npm install -g codex-webstrapper
+```
+
+### Run
+
+With global install:
+
+```bash
+codex-webstrap --port 8080 --bind 127.0.0.1
+```
+
+From local checkout:
+
+```bash
+./bin/codex-webstrap.sh --port 8080 --bind 127.0.0.1
+```
+
+Optional auto-open:
+
+```bash
+codex-webstrap --open
+```
+
+## Authentication Model
+
+1. On first run, a random token is persisted at `~/.codex-webstrap/token` (default path).
+2. You authenticate once via:
+
+```bash
+open "http://127.0.0.1:8080/__webstrapper/auth?token=$(cat ~/.codex-webstrap/token)"
+```
+
+3. Server sets `cw_session` cookie (`HttpOnly`, `SameSite=Lax`, scoped to `/`).
+4. UI and bridge endpoints require a valid session cookie.
+
+## Security Risks and Recommendations
+
+This project can expose powerful local capabilities if misconfigured. Treat it as sensitive software.
+
+### Primary Risks
+
+- Remote users with valid session can operate Codex UI features and local workflows.
+- Token bootstrap URL can be leaked via shell history, logs, screenshots, or shared links.
+- Binding to non-local interfaces increases attack surface.
+- No built-in TLS termination. Plain HTTP should not be exposed directly to the public internet.
+
+### Recommended Safe Usage
+
+- Keep default bind: `127.0.0.1` unless remote access is required.
+- If remote access is needed, use a private overlay network (for example Tailscale/WireGuard) and not public port-forwarding.
+- Do not share token values in chat, screenshots, logs, issue reports, or commit history.
+- Rotate token file if exposure is suspected:
+
+```bash
+rm -f ~/.codex-webstrap/token
+```
+
+Then restart wrapper to generate a new token.
+
+- Consider external TLS/auth proxy if you must serve beyond localhost.
+
+## Functional Coverage Notes
+
+Implemented coverage includes:
+
+- core message routing (`ready`, `fetch`, `mcp-*`, `terminal-*`, `persisted-atom-*`, `shared-object-*`)
+- thread lifecycle actions including archive/unarchive pathing
+- worker message support (including git worker bridge)
+- browser equivalents for desktop-only UX events (open links, diff/plan summaries)
+- graceful unsupported handling for non-web-native desktop actions
+
+Unknown message types produce structured `bridge-error` responses and do not crash the session.
+
+## Development
+
+### Run Tests
+
+```bash
+npm test
+```
+
+### Worktree Bootstrap
+
+Bootstrap env/secrets from another worktree checkout:
+
+```bash
+./scripts/worktree-bootstrap.sh --dry-run
+./scripts/worktree-bootstrap.sh --mode symlink
+```
+
+Core paths are configured via:
+
+- `scripts/worktree-secrets.manifest`
+
+Codex setup-script compatible command:
+
+```bash
+./scripts/worktree-bootstrap.sh --mode symlink --overwrite backup --extras on --install on --checks on
+```
+
+### Typical Troubleshooting
+
+- `401 unauthorized`
+  - Authenticate first via `/__webstrapper/auth?token=...`.
+- UI loads but actions fail
+  - Check `GET /__webstrapper/healthz` for app-server/UDS readiness.
+- Codex app not found
+  - Pass `--codex-app /path/to/Codex.app`.
+- `codex` CLI spawn failures
+  - Ensure `codex` is on `PATH` or set `CODEX_CLI_PATH`.
+
+## License
+
+MIT. See `LICENSE.md`.

package/bin/codex-webstrap.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+PORT="${CODEX_WEBSTRAP_PORT:-8080}"
+BIND="${CODEX_WEBSTRAP_BIND:-127.0.0.1}"
+OPEN_FLAG="0"
+TOKEN_FILE="${CODEX_WEBSTRAP_TOKEN_FILE:-}"
+CODEX_APP="${CODEX_WEBSTRAP_CODEX_APP:-}"
+INTERNAL_WS_PORT="${CODEX_WEBSTRAP_INTERNAL_WS_PORT:-38080}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port)
+      PORT="$2"
+      shift 2
+      ;;
+    --bind)
+      BIND="$2"
+      shift 2
+      ;;
+    --open)
+      OPEN_FLAG="1"
+      shift
+      ;;
+    --token-file)
+      TOKEN_FILE="$2"
+      shift 2
+      ;;
+    --codex-app)
+      CODEX_APP="$2"
+      shift 2
+      ;;
+    --help|-h)
+      cat <<USAGE
+Usage: $(basename "$0") [--port <n>] [--bind <ip>] [--open] [--token-file <path>] [--codex-app <path>]
+
+Env overrides:
+  CODEX_WEBSTRAP_PORT
+  CODEX_WEBSTRAP_BIND
+  CODEX_WEBSTRAP_TOKEN_FILE
+  CODEX_WEBSTRAP_CODEX_APP
+  CODEX_WEBSTRAP_INTERNAL_WS_PORT
+USAGE
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+export CODEX_WEBSTRAP_PORT="$PORT"
+export CODEX_WEBSTRAP_BIND="$BIND"
+export CODEX_WEBSTRAP_TOKEN_FILE="$TOKEN_FILE"
+export CODEX_WEBSTRAP_CODEX_APP="$CODEX_APP"
+export CODEX_WEBSTRAP_INTERNAL_WS_PORT="$INTERNAL_WS_PORT"
+export CODEX_WEBSTRAP_OPEN="$OPEN_FLAG"
+
+exec node "${ROOT_DIR}/src/server.mjs"

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "codex-webstrapper",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Web wrapper for Codex desktop assets with bridge + token auth",
+  "license": "MIT",
+  "bin": {
+    "codex-webstrap": "./bin/codex-webstrap.sh"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/server.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@electron/asar": "^4.0.1",
+    "ws": "^8.18.0"
+  }
+}

package/src/app-server.mjs

@@ -0,0 +1,289 @@
+import { EventEmitter } from "node:events";
+import { spawn } from "node:child_process";
+
+import { createLogger, toErrorMessage } from "./util.mjs";
+
+export class AppServerManager extends EventEmitter {
+  constructor({
+    internalPort = 38080,
+    codexCliPath = process.env.CODEX_CLI_PATH || "codex",
+    logger
+  } = {}) {
+    super();
+    this.internalPort = internalPort;
+    this.codexCliPath = codexCliPath;
+    this.logger = logger || createLogger("app-server");
+
+    this.proc = null;
+    this.connected = false;
+    this.initialized = false;
+    this.transportKind = "stdio";
+
+    this.nextId = 1;
+    this.pending = new Map();
+    this.connectingPromise = null;
+    this.stopped = false;
+    this.stdoutBuffer = "";
+  }
+
+  getState() {
+    return {
+      connected: this.connected,
+      initialized: this.initialized,
+      transportKind: this.transportKind,
+      wsUrl: null
+    };
+  }
+
+  async start() {
+    this.stopped = false;
+
+    if (this.connected && this.initialized) {
+      return;
+    }
+
+    if (this.connectingPromise) {
+      return this.connectingPromise;
+    }
+
+    this.connectingPromise = this._startInternal().finally(() => {
+      this.connectingPromise = null;
+    });
+
+    return this.connectingPromise;
+  }
+
+  async _startInternal() {
+    if (this.proc && !this.proc.killed && this.connected) {
+      return;
+    }
+
+    await this._spawnStdioProcess();
+    await this._initializeProtocol();
+  }
+
+  stop() {
+    this.stopped = true;
+
+    this._rejectAllPending(new Error("App server stopped"));
+
+    if (this.proc && !this.proc.killed) {
+      this.proc.kill();
+    }
+
+    this.proc = null;
+    this.connected = false;
+    this.initialized = false;
+    this.stdoutBuffer = "";
+    this._emitConnectionChanged();
+  }
+
+  async sendRequest(method, params, options = {}) {
+    if (!options.skipReadyCheck) {
+      await this._ensureReady();
+    } else if (!(this.connected && this.proc && this.proc.stdin && !this.proc.stdin.destroyed)) {
+      throw new Error("App server stdio is not connected");
+    }
+
+    const id = options.id ?? this.nextId++;
+    const payload = { id, method, params };
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`app-server request timeout: ${method}`));
+      }, options.timeoutMs || 15000);
+
+      this.pending.set(id, { resolve, reject, timer, method });
+
+      try {
+        this._sendJson(payload);
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  async sendNotification(method, params) {
+    await this._ensureReady();
+    this._sendJson({ method, params });
+  }
+
+  async sendRaw(message) {
+    if (!message || typeof message !== "object") {
+      throw new Error("sendRaw expects an object");
+    }
+
+    if (Object.prototype.hasOwnProperty.call(message, "id") && message.method) {
+      return this.sendRequest(message.method, message.params, {
+        id: message.id,
+        timeoutMs: 15000
+      });
+    }
+
+    await this._ensureReady();
+    this._sendJson(message);
+    return null;
+  }
+
+  async _ensureReady() {
+    if (this.connected && this.initialized && this.proc && this.proc.stdin && !this.proc.stdin.destroyed) {
+      return;
+    }
+
+    await this.start();
+
+    if (!(this.connected && this.initialized)) {
+      throw new Error("App server is not connected");
+    }
+  }
+
+  async _spawnStdioProcess() {
+    if (this.proc && !this.proc.killed) {
+      return;
+    }
+
+    const args = ["app-server", "--analytics-default-enabled"];
+
+    this.logger.info("Starting codex app-server (stdio)", {
+      codexCliPath: this.codexCliPath,
+      args
+    });
+
+    const proc = spawn(this.codexCliPath, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env
+    });
+
+    proc.stderr?.on("data", (chunk) => {
+      const line = chunk.toString("utf8").trim();
+      if (line) {
+        this.logger.debug("app-server stderr", { line });
+      }
+    });
+
+    proc.stdout?.on("data", (chunk) => {
+      this._handleStdoutChunk(chunk.toString("utf8"));
+    });
+
+    proc.on("error", (error) => {
+      this.logger.error("app-server spawn failed", { error: toErrorMessage(error) });
+    });
+
+    proc.on("exit", (code, signal) => {
+      this.logger.warn("app-server exited", { code, signal });
+      this.proc = null;
+      this.connected = false;
+      this.initialized = false;
+      this.stdoutBuffer = "";
+      this._rejectAllPending(new Error("App server process exited"));
+      this._emitConnectionChanged();
+    });
+
+    this.proc = proc;
+    this.connected = true;
+    this.initialized = false;
+    this._emitConnectionChanged();
+  }
+
+  _handleStdoutChunk(chunk) {
+    this.stdoutBuffer += chunk;
+
+    for (;;) {
+      const newlineIndex = this.stdoutBuffer.indexOf("\n");
+      if (newlineIndex < 0) {
+        break;
+      }
+
+      const line = this.stdoutBuffer.slice(0, newlineIndex).trim();
+      this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+
+      if (!line) {
+        continue;
+      }
+
+      let payload;
+      try {
+        payload = JSON.parse(line);
+      } catch (error) {
+        this.logger.warn("Dropping non-JSON app-server line", {
+          line,
+          error: toErrorMessage(error)
+        });
+        continue;
+      }
+
+      this._handleIncoming(payload);
+    }
+  }
+
+  _handleIncoming(payload) {
+    this.emit("message", payload);
+
+    if (payload.id != null) {
+      const pending = this.pending.get(payload.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pending.delete(payload.id);
+        pending.resolve(payload);
+        return;
+      }
+    }
+
+    if (payload.method) {
+      if (payload.id != null) {
+        this.emit("request", payload);
+        return;
+      }
+      this.emit("notification", payload);
+    }
+  }
+
+  async _initializeProtocol() {
+    const initializeResponse = await this.sendRequest(
+      "initialize",
+      {
+        clientInfo: {
+          name: "codex_webstrapper",
+          title: "Codex Webstrapper",
+          version: "0.1.0"
+        },
+        capabilities: {
+          experimentalApi: true
+        }
+      },
+      { skipReadyCheck: true }
+    );
+
+    if (initializeResponse?.error) {
+      throw new Error(`App server initialize failed: ${JSON.stringify(initializeResponse.error)}`);
+    }
+
+    this._sendJson({ method: "initialized", params: {} });
+    this.initialized = true;
+    this._emitConnectionChanged();
+    this.emit("initialized");
+  }
+
+  _sendJson(payload) {
+    if (!this.proc || !this.proc.stdin || this.proc.stdin.destroyed) {
+      throw new Error("App server stdin is not writable");
+    }
+
+    this.proc.stdin.write(`${JSON.stringify(payload)}\n`);
+  }
+
+  _rejectAllPending(error) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  _emitConnectionChanged() {
+    this.emit("connection-changed", this.getState());
+  }
+}