codex-webapp 0.1.6 → 0.1.8

package/docs/architecture.md

@@ -0,0 +1,85 @@
+# Architecture
+
+Codex WebApp is a small, local adapter for people who already have the macOS
+Codex App installed on their Mac. It does not replace Codex App and it does not ship a
+separate Codex runtime. The package prepares the renderer that is already on
+the user's machine, serves it on a local web address, and bridges browser
+requests to the local Codex command-line tools.
+
+## What The Package Includes
+
+The npm package includes the adapter code:
+
+- a command-line wrapper for `doctor`, `start`, and `smoke`
+- local server code that serves static renderer files from the user's cache
+- a small browser preload and bridge layer for local app-server communication
+- tests, docs, and public support files
+
+The package does not bundle or publish user or vendor runtime artifacts:
+
+- no Codex/OpenAI binaries
+- no `app.asar`
+- no pre-extracted `webview/` directory
+- no tokens, cookies, session IDs, or private keys
+- no signed URLs
+- no private session database
+- no repository contents, prompts, customer data, or other user data
+
+In short: the npm package is the adapter. The renderer source remains the Codex
+App that the user installed locally.
+
+## Runtime Flow
+
+When a user runs `codex-webapp start`, the adapter does this on the local
+machine:
+
+1. Locates Codex App.
+   By default it expects `/Applications/Codex.app`. Users can override this
+   with `CODEX_APP_PATH` or point directly at a local archive with
+   `CODEX_WEBAPP_CODEX_ASAR`.
+2. Reads the local Codex App renderer archive.
+   The expected archive is `Contents/Resources/app.asar` inside the app bundle.
+3. Extracts only the `webview/` tree.
+   The files are copied into `~/.cache/codex-webapp/<fingerprint>/webview/`.
+   Other archive contents are not served.
+4. Serves the prepared renderer.
+   The local HTTP server defaults to `http://127.0.0.1:8214/` and serves the
+   cached static files with normal cache headers.
+5. Bridges browser calls to the local Codex app server.
+   The adapter starts `codex app-server --listen stdio://` when browser IPC
+   needs it, speaks JSON over stdio, and keeps that process local to the host.
+
+The extraction cache is local machine state. It is not included in the npm
+package and is not uploaded by this project. Users can remove it by deleting
+`~/.cache/codex-webapp/`; the adapter will prepare it again on the next start.
+
+## Adapter Responsibilities
+
+Codex WebApp owns these public, package-level responsibilities:
+
+| Area | Responsibility |
+| --- | --- |
+| Codex App discovery | Find the user's local Codex App or accept explicit local paths through environment variables. |
+| Local extraction | Read the local `app.asar`, extract only `webview/`, transform the local `index.html` enough to load the browser bridge, and cache the result under the user's home directory. |
+| Static UI serving | Serve the prepared renderer on a localhost-first HTTP server and block unsafe path traversal requests. |
+| App-server bridge | Start and communicate with the local `codex app-server` process over stdio for browser-side app calls. |
+| `doctor` | Check that Codex CLI is installed, new enough, and exposes the expected local commands. |
+| `start` | Confirm the binding, prepare the renderer, and start the local server. |
+| `smoke` | Verify that the local URL responds, and optionally capture browser evidence. |
+
+## Local-First Boundary
+
+The default binding is `127.0.0.1`. A non-loopback host requires an explicit
+`--allow-non-loopback` flag because anyone who can reach the UI may be able to
+operate Codex on that machine.
+
+For phone or remote access, keep the raw UI behind a trusted access boundary
+such as Tailscale, Cloudflare Access, WireGuard, or SSH tunneling. Codex WebApp
+does not provide hosted access, identity, or account management.
+
+## Public Documentation Boundary
+
+This repository should describe the adapter in practical terms: what it starts,
+what it reads locally, what it caches locally, and how users can verify it. Keep
+the wording friendly and concrete. Avoid implying that the package contains
+Codex App, OpenAI binaries, private session material, or customer data.

package/docs/clean-release-verification.md

@@ -0,0 +1,95 @@
+# Clean Release Verification
+
+Status: release operator checklist for public Codex WebApp package readiness.
+
+This gate gives release operators a repeatable public-repo check before publishing or handing off a release candidate. It is bounded evidence, not a guarantee of release safety.
+
+## Command
+
+From a clean checkout of this public repo:
+
+```bash
+npm ci
+npm run verify:clean-release
+```
+
+The command runs:
+
+- `npm test`
+- `npm run check:public-boundary`
+- `npm pack --dry-run`
+- `npm run start:dry-run` when the package exposes that script
+
+It also inspects package metadata, the dry-run pack file list, and source-tree paths for private engine package names, bundled Codex App artifacts, pre-extracted renderer payloads, credential-looking paths, session database-looking paths, customer-data-looking paths, and private dependency specs.
+
+The path scan intentionally allows public docs to name excluded artifacts so the boundary remains explainable. Do not add private implementation notes, patent-sensitive details, secrets, binary fixtures, `app.asar`, extracted renderer files, screenshots, private repo content, or private package dependencies to this repository.
+
+## Optional Private Engine Check
+
+If the private engine repository is available locally, include it without making this public package depend on it:
+
+```bash
+npm run verify:clean-release -- --private-engine-dir /private/tmp/penso-render-envelope
+```
+
+The same path can be provided with:
+
+```bash
+PENSO_RENDER_ENVELOPE_DIR=/private/tmp/penso-render-envelope npm run verify:clean-release
+```
+
+When the private repo path is absent, the gate reports a `SKIP` for private engine checks and still verifies the public package. That skip is expected for public contributors and clean npm install environments.
+
+The optional private check runs only the private repo's `npm test` and `npm pack --dry-run`. It does not copy private files into this repo or add a package dependency.
+
+## Empty Directory Package Check
+
+For a clean install-style proof, create a temporary directory outside this repo and install from the dry-run tarball or current public npm package:
+
+```bash
+tmpdir="$(mktemp -d)"
+npm pack --pack-destination "$tmpdir"
+cd "$tmpdir"
+npm init -y
+npm install ./codex-webapp-*.tgz
+npx codex-webapp start --dry-run
+```
+
+For the already-published package, use:
+
+```bash
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+npm init -y
+npx -y codex-webapp@latest doctor
+npx -y codex-webapp@latest start --dry-run
+```
+
+Keep outputs redacted. Do not attach credentials, local app archives, extracted renderer files, private repo listings, or user data.
+
+## Local Browser Smoke Evidence
+
+On a Mac with Codex App installed, release evidence may include a local browser smoke run:
+
+```bash
+npx -y codex-webapp start
+npx -y codex-webapp smoke --browser --url http://127.0.0.1:8214/
+```
+
+Screenshots are optional and should be attached only after review for tokens, cookies, prompts, private repository contents, customer data, internal URLs, or other sensitive material.
+
+## Evidence To Attach
+
+Attach concise, redacted evidence:
+
+- commit hash and branch
+- `npm ci`
+- `npm test`
+- `npm run check:public-boundary`
+- `npm run verify:clean-release`
+- optional private engine check result or the explicit `SKIP`
+- `npm pack --dry-run`
+- empty-directory install or public `npx` dry-run proof when performed
+- local Codex.app browser smoke result when performed
+
+The evidence should show whether each check passed, failed, or was skipped. Avoid claiming complete detection or absolute protection.

package/docs/codex-app-install.md

@@ -8,6 +8,11 @@ affiliated with or endorsed by OpenAI.
 This is a prompt-driven npm package path, not a native Codex App marketplace
 install. Codex App runs the setup commands for the user.
 
+The package is only the local adapter. It does not include Codex/OpenAI
+binaries, `app.asar`, a pre-extracted `webview/`, tokens, cookies, signed URLs,
+private session databases, private repository contents, or customer data. At
+runtime it uses the Codex App renderer already installed on the user's Mac.
+
 The intended experience is simple: paste one instruction into Codex App, let
 Codex check/install the companion, start the local Codex-style Web surface, and
 run a smoke test. For access from another PC or a phone, keep the machine behind

package/docs/distribution-boundary.md

@@ -0,0 +1,37 @@
+# Codex WebApp Distribution Boundary Decision
+
+Status: accepted for PAN-1596.
+
+## Decision
+
+Codex WebApp remains a public-install-independent npm package. `npx codex-webapp` must work from the public npm registry without GitHub credentials, private package registry credentials, or access to a private engine repository.
+
+The package will not depend on `penso-render-envelope` or any other private engine package at runtime. The public package owns only the local Codex App renderer bridge, public docs, and public-safe checks needed to start and smoke-test the installed Codex App renderer.
+
+Future integration with private rendering work requires a new approval step and one of these public-safe paths:
+
+- a generated subset that contains only reviewed public-safe code and metadata
+- a separately licensed package that can be installed from a public or approved registry without private repository credentials
+
+An adapter or interface boundary is preferred over transforming private implementation into public code. A generated subset is allowed only after review because comments, metadata, control flow, or test fixtures can still reveal private engine mechanics even when direct secrets are removed.
+
+## Rejected Options
+
+- Direct private GitHub dependency in `package.json` or `package-lock.json`: rejected because public `npx` installs would require private credentials and would fail for normal npm users.
+- Runtime fetch from a private repository or private package registry: rejected because it turns first run into an authentication-dependent install path and can expose private infrastructure assumptions.
+- Vendoring private engine internals into this public package: rejected because it risks publishing private implementation detail and changes the licensing and IP surface without approval.
+- Embedding patent claim text or private engine design notes in public docs: rejected because the package only needs the distribution boundary, not protected claim language or private internals.
+
+## License And IP Notes
+
+This repository is public and distributed under its existing Apache-2.0 license. That license should apply only to the public code and docs intentionally shipped here. Private engine code, generated artifacts, or separately licensed packages need an explicit approval and compatibility review before being added to this package or its runtime path.
+
+This note is an engineering distribution decision, not legal advice. It avoids making ownership, patent scope, or licensing conclusions beyond the public package boundary.
+
+## Guardrail
+
+`npm test` includes a public package boundary guard. The guard fails if `package.json`, `package-lock.json`, or the `npm pack --dry-run --json` file list shows private package names, GitHub dependency specs, private registry URLs, local `file:` or `link:` dependency specs, workspace dependency specs, install lifecycle scripts, non-public npm `publishConfig.registry`, or private-boundary pack paths such as `.npmrc`, `.env`, secrets directories, or a bundled private engine directory.
+
+The guard intentionally checks dependency and package contents paths rather than every word in docs. Public documentation may name the boundary and the private package to explain what is not included, but package code should not dynamically import or fetch it, and docs must not expose private engine internals or patent claim text.
+
+Counterproof review for this decision specifically called out dependency confusion, lockfile `resolved` URL leakage, `optionalDependencies`, install lifecycle scripts, and IP bleed from generated subsets. The accepted follow-up was to keep all dependency collections under the guard, add install lifecycle and private registry checks, and document adapter-first future integration.

package/docs/i18n/README.ko.md

@@ -1,95 +1,41 @@
-> **Unofficial community project.** This project is not affiliated with,
-> endorsed by, sponsored by, or associated with OpenAI or the official Codex App.
-
 # Codex WebApp
 
 [English](../../README.md) / [日本語](../../README.ja.md) / 한국어 / [简体中文](./README.zh-CN.md)
 
-Codex App 사용자를 위한 브라우저 companion입니다.
-
-Codex App에 붙여 넣을 수 있는 프롬프트, `doctor`, 안전한 로컬 실행, 그리고 실제 Codex 스타일 브라우저 화면이 열리는지 확인하는 smoke test를 제공합니다.
+Codex WebApp은 Codex App 사용자를 위한 비공식 local-first renderer bridge입니다. 설치된 Codex App의 `webview/` renderer를 로컬 캐시에 준비하고, `127.0.0.1`에서 제공하며, smoke test로 실제 접근 가능 여부를 확인합니다.
 
 ![Codex WebApp overview](../assets/codex-webapp-overview.svg)
 
-> OpenAI와 제휴하거나 OpenAI가 보증한 공식 제품이 아닙니다.
->
-> 원본 UI 서버는 기본적으로 `localhost`에만 두세요. 휴대폰이나 다른 PC에서 접근하려면 Tailscale, Cloudflare Access, 또는 동등한 신뢰 경계를 먼저 설정하세요. 공개 IP에 직접 노출하지 마세요.
-
-Note: The software interface is currently available mainly in English. This
-Korean documentation has been translated for setup convenience.
-
-## 빠른 시작: Codex App
-
-아래 프롬프트를 Codex App에 붙여 넣으세요.
-
-```text
-Please set up Codex WebApp on this machine.
-
-Use this npm package:
-codex-webapp
-
-Please:
-1. Check my Codex version.
-2. Run the package doctor.
-3. Run start in dry-run mode first.
-4. Start the local browser UI only on localhost.
-5. Smoke-test the printed local URL.
-
-Keep everything on localhost unless I already have Tailscale, Cloudflare Access,
-or another trusted access boundary set up.
-
-Do not print tokens, cookies, private repo contents, customer data, or internal URLs.
-```
-
-Codex는 내부적으로 다음과 같은 명령을 실행합니다.
-
-```bash
-npx -y codex-webapp doctor
-npx -y codex-webapp start --dry-run
-npx -y codex-webapp start
-```
-
-`npx`는 npm에 공개된 패키지를 임시로 실행하는 도구입니다. 사용자가 직접 프로젝트를 만들거나 의존성을 관리할 필요를 줄여 줍니다.
-
-## 터미널로 실행
+## Quick Start
 
 ```bash
-codex --version
-codex remote-control --help
 npx -y codex-webapp doctor
 npx -y codex-webapp start --dry-run
 npx -y codex-webapp start
 ```
 
-기본 로컬 URL:
+Open:
 
 ```text
 http://127.0.0.1:8214/
 ```
 
-## Smoke Test
+Verify:
 
 ```bash
-npx -y codex-webapp smoke \
-  --url http://127.0.0.1:8214/
+npx -y codex-webapp smoke --url http://127.0.0.1:8214/
 ```
 
-공개 이슈나 스크린샷에는 토큰, 쿠키, private repository, 고객 데이터, 내부 URL을 넣지 마세요.
-
-## 현재 범위
-
-이 패키지는 Codex App native marketplace plugin, browser extension, one-click installer, managed hosting service가 아닙니다. Codex App에 프롬프트를 붙여 넣고, Codex가 `npx`로 npm 패키지를 실행하는 방식입니다.
-
-현재 release는 `0.1.6`이며 early, compatibility-first입니다. 현재 `0xcaff/codex-web` commit `585613f5a3a355af5aefc388ca4e31b07a472cda`를 참조하는 Codex 스타일 browser runtime을 실행하고, 그 주변에 설치, 안전, 문서, 검증 evidence 계층을 더합니다.
+## Safety
 
-## Security And Privacy
+This project is not affiliated with or endorsed by OpenAI.
 
-이 CLI wrapper는 사용자의 prompt, repository, token, cookie, customer data를 이 프로젝트가 운영하는 third-party server로 전송하지 않습니다. 이 패키지는 browser extension을 설치하지 않으며 browser token을 `localStorage`, `chrome.storage`, extension profile에 저장하지 않습니다.
+Keep the raw UI server on localhost. For phone or remote access, use Tailscale, Cloudflare Access, WireGuard, SSH tunneling, or an equivalent trusted access boundary. Do not expose the raw UI server directly to a public IP.
 
-공개 issue나 screenshot에는 secret, private repository, customer data, internal URL을 포함하지 마세요.
+Do not share tokens, cookies, private repository contents, customer data, internal URLs, `.env` values, or anything containing SECRET, KEY, or TOKEN in public issues or screenshots.
 
-## Acknowledgements
+## Scope
 
-현재 release는 Codex 스타일 브라우저 화면을 제공하는 public project `0xcaff/codex-web`의 접근 방식을 사용하고 참조합니다. 이 프로젝트는 그 주변에 배포, doctor, 안전 경계, 문서, 검증 evidence 계층을 추가합니다.
+This package starts a local renderer bridge for the Codex App already installed on this computer. It is not a native Codex App marketplace plugin, browser extension, one-click installer, or managed hosting service.
 
 License: [Apache-2.0](../../LICENSE.md)

package/docs/i18n/README.zh-CN.md

@@ -1,95 +1,41 @@
-> **Unofficial community project.** This project is not affiliated with,
-> endorsed by, sponsored by, or associated with OpenAI or the official Codex App.
-
 # Codex WebApp
 
 [English](../../README.md) / [日本語](../../README.ja.md) / [한국어](./README.ko.md) / 简体中文
 
-这是面向 Codex App 用户的浏览器 companion。
-
-它提供可直接粘贴到 Codex App 的提示词、友好的 `doctor` 检查、安全的本地启动器，以及用于确认真实 Codex 风格浏览器界面是否可访问的 smoke test。
+Codex WebApp 是面向 Codex App 用户的非官方、local-first renderer bridge。它会从本机已安装的 Codex App 准备 `webview/` renderer，在 `127.0.0.1` 提供本地页面，并通过 smoke test 验证页面是否可访问。
 
 ![Codex WebApp overview](../assets/codex-webapp-overview.svg)
 
-> 本项目不隶属于 OpenAI，也未获得 OpenAI 的官方认可或背书。
->
-> 原始 UI 服务器默认应只监听 `localhost`。如果需要从手机或另一台电脑访问，请先使用 Tailscale、Cloudflare Access，或同等的可信访问边界。不要把原始服务器直接暴露到公网 IP。
-
-Note: The software interface is currently available mainly in English. This
-Simplified Chinese documentation has been translated for setup convenience.
-
-## Codex App 快速开始
-
-把下面的提示词粘贴到 Codex App：
-
-```text
-Please set up Codex WebApp on this machine.
-
-Use this npm package:
-codex-webapp
-
-Please:
-1. Check my Codex version.
-2. Run the package doctor.
-3. Run start in dry-run mode first.
-4. Start the local browser UI only on localhost.
-5. Smoke-test the printed local URL.
-
-Keep everything on localhost unless I already have Tailscale, Cloudflare Access,
-or another trusted access boundary set up.
-
-Do not print tokens, cookies, private repo contents, customer data, or internal URLs.
-```
-
-Codex 通常会为你执行类似命令：
-
-```bash
-npx -y codex-webapp doctor
-npx -y codex-webapp start --dry-run
-npx -y codex-webapp start
-```
-
-`npx` 的简单解释：它会临时运行一个已经发布到 npm 的包，减少手动安装和管理项目依赖的麻烦。
-
-## 终端快速开始
+## Quick Start
 
 ```bash
-codex --version
-codex remote-control --help
 npx -y codex-webapp doctor
 npx -y codex-webapp start --dry-run
 npx -y codex-webapp start
 ```
 
-默认本地地址：
+Open:
 
 ```text
 http://127.0.0.1:8214/
 ```
 
-## Smoke Test
+Verify:
 
 ```bash
-npx -y codex-webapp smoke \
-  --url http://127.0.0.1:8214/
+npx -y codex-webapp smoke --url http://127.0.0.1:8214/
 ```
 
-公开 issue 或截图时，请不要包含 token、cookie、私有仓库、客户数据或内部 URL。
-
-## 当前范围
-
-这不是 Codex App native marketplace plugin、browser extension、one-click installer 或 managed hosting service。它的使用方式是：把提示词粘贴到 Codex App，让 Codex 通过 `npx` 执行 npm 包。
-
-当前 release 为 `0.1.6`，仍处于 early 阶段，并采用 compatibility-first 方针。它目前运行一个引用 `0xcaff/codex-web` commit `585613f5a3a355af5aefc388ca4e31b07a472cda` 的 Codex 风格 browser runtime，并在其周围增加安装、安全、文档和验证证据层。
+## Safety
 
-## Security And Privacy
+This project is not affiliated with or endorsed by OpenAI.
 
-此 CLI wrapper 不会把你的 prompt、repository、token、cookie 或 customer data 发送到由本项目运营的 third-party server。本包不会安装 browser extension，也不会把 browser token 写入 `localStorage`、`chrome.storage` 或 extension profile。
+Keep the raw UI server on localhost. For phone or remote access, use Tailscale, Cloudflare Access, WireGuard, SSH tunneling, or an equivalent trusted access boundary. Do not expose the raw UI server directly to a public IP.
 
-公开 issue 或截图时，请不要包含 secret、私有仓库、客户数据或内部 URL。
+Do not share tokens, cookies, private repository contents, customer data, internal URLs, `.env` values, or anything containing SECRET, KEY, or TOKEN in public issues or screenshots.
 
-## Acknowledgements
+## Scope
 
-当前 release 使用并感谢 public project `0xcaff/codex-web` 提供的 Codex 风格浏览器界面思路。本项目在此基础上增加分发、doctor、安全边界、文档和验证证据层。
+This package starts a local renderer bridge for the Codex App already installed on this computer. It is not a native Codex App marketplace plugin, browser extension, one-click installer, or managed hosting service.
 
 License: [Apache-2.0](../../LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-webapp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Unofficial. Respectful web app surface, doctor, and safety wrapper for Codex App users.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,17 +23,24 @@
     "codex-webapp": "bin/codex-webapp.mjs"
   },
   "scripts": {
+    "check:public-boundary": "node ./scripts/check-public-package-boundary.mjs",
     "doctor": "node ./bin/codex-webapp.mjs doctor",
     "smoke": "node ./bin/codex-webapp.mjs smoke",
     "test": "node --test",
+    "verify:clean-release": "node ./scripts/verify-clean-release.mjs",
     "start:dry-run": "node ./bin/codex-webapp.mjs start --dry-run"
   },
+  "dependencies": {
+    "@electron/asar": "^3.4.1",
+    "ws": "^8.18.3"
+  },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.11"
   },
   "files": [
     "bin",
     "docs",
+    "scripts",
     "src",
     "ACKNOWLEDGEMENTS.md",
     "README.md",