page-harness 0.1.11 → 0.1.13

package/AGENTS.md

@@ -0,0 +1,43 @@
+# 给改这个仓库的代理
+
+用户文档在 [README.md](./README.md) 和 [README.zh-CN.md](./README.zh-CN.md)。目录、命令和开发约定在 [docs/development.md](./docs/development.md)。这里只写改代码时容易踩错的约束。
+
+## 先跑什么
+
+Node 20.11+。根目录 `npm ci` 之后：
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+```
+
+改了 `dsh-plugin/` 还要在该目录跑 `npm run check` 和 `npm test`。改了页面上能看见的行为，再 `npm run build && npm run test:e2e`。`dist/` 被 gitignore，不要提交构建产物。
+
+## 两个包，两条运行路径
+
+- 根包 `page-harness` 是 CLI。它代理用户的页面，注入 overlay，并用本机的 agent CLI 改源码。
+- `dsh-plugin/` 是 DeepSeek Harness 插件 `page-harness-dsh`。预览由 DSH 调 CLI，参数带 `--no-agent`。候选由 DSH 模型调用 `page_harness_propose`，不要在插件里启动 page-harness 自己的 agent，也不要把几版同时写进源码。
+
+插件装进 DSH profile 后是文件副本，不是源码目录的符号链接。改 `dsh-plugin/lib/` 不会自动出现在正在跑的 DSH 里。
+
+## 不要改的行为
+
+- 预览端口保持独立。DSH 用自己的端口（常见 3080）。页面预览默认 `17994`，面板和 `/__ph/ws` 用下一个端口。不要把这两个端口反代进 3080，也不要加路径前缀。
+- 回环或 HTTPS 上的面板 cookie 是 `SameSite=None; Secure; Partitioned`。公网 HTTP 保持 `SameSite=Strict`。无 cookie 的 WebSocket 必须继续 403。
+- `POST /__ph/api/review/resolve` 只给本机 curl / 复制出的提示词。带 `Origin`、跨站 `Sec-Fetch-Site` 或面板 session cookie 的请求返回 403。面板改意见走 WebSocket，不走这个地址。
+- DSH 里采用某一版时，输入框里的 `<page-element>` 不带内部 HTML。选择器、标签和文本放在属性上，具体改动写在后面的句子里。
+
+## 插件客户端
+
+`dsh-plugin/lib/client.js` 是一个没有 import 的浏览器脚本。和它对应的纯函数在 `propose.js`、`preview-bar.js`、`share-bar.js`。改其中一份时，另一份必须保持函数体一致；`dsh-plugin/test/` 会比对。`npm test` 不会执行 `client.js`，所以还要过 `npm run check`。
+
+## 提交
+
+功能 PR 不要改 `package.json` 的 `version`。提交说明用英文祈使句，说明为什么改。没有明确要求就不要 push，也不要开新的发布 tag。
+
+## 发版
+
+只发布根包 `page-harness`。tag 必须是 `v` 加 `package.json` 里的版本，例如 `v0.1.12`。不要给 `page-harness-dsh` 单独发版，也不要改它的版本号。
+
+DSH 直接安装 npm 上的 `page-harness@<该版本>`。插件源码留在 `dsh-plugin/`，运行时用这个 CLI 包。以后每次发版都这样。

package/README.md

@@ -273,7 +273,7 @@ There is no login: it is a local developer tool and binds to `127.0.0.1` by defa
 - **Two origins.** Your app (and any script on it) runs on the app port; the panel, API and agent endpoints are on the control port, so page scripts cannot read them.
 - **Owner and reviewers.** Without `--share` only this machine can connect and everything behaves as one user. With `--share`, the owner session is only issued to loopback requests; other machines need the invite link, which sets signed (HMAC) reviewer cookies for the panel and the app port; without them both ports answer `403`. Reviewers are limited to the review actions on the WebSocket and to reading artifacts; everything else returns `403`. Name the owner in Settings → Team.
 - **Session cookie.** The panel gets an `HttpOnly`, `SameSite=Strict` cookie scoped to `/__ph`; the cookie is stripped before requests are forwarded to your dev server.
-- **API.** Reads require a same-origin `Sec-Fetch-Site`; writes require a matching `Origin` plus a custom `X-PH` header. The WebSocket checks the cookie and `Origin`. The bookmarklet is the exception: cross-origin review reads and writes need the per-run `X-PH-Token`, and the response reflects that page's `Origin` (never `*`). `GET /__ph/api/review` stays callable from curl without CORS headers.
+- **API.** Reads require a same-origin `Sec-Fetch-Site`; writes require a matching `Origin` plus a custom `X-PH` header. The WebSocket checks the cookie and `Origin`. The bookmarklet is the exception: cross-origin review reads and writes need the per-run `X-PH-Token`, and the response reflects that page's `Origin` (never `*`). `GET /__ph/api/review` stays callable from curl without CORS headers. `POST /__ph/api/review/resolve` is the local agent's endpoint, so it takes no cookie and no token: it accepts only requests without an `Origin` (curl, the copied prompt), and refuses browsers, cross-site requests and session cookies with `403`.
 - **MCP.** Every agent turn gets its own bearer token (passed through an environment variable or a private temp file, never on the command line) that is revoked when the turn ends. Browser requests to the MCP endpoint are rejected.
 - **Host allow-list.** Requests with unexpected `Host` headers get `421` (DNS rebinding). Add names with `--allow-host` if you expose it on a LAN.
 - **Framing.** The panel may only be framed by the app origin; the history page cannot be framed at all.
@@ -328,11 +328,14 @@ Delete `<project>/.page-harness/`.
 | [Security model](#security-model) | What is locked down and how |
 | [Data](#data) | What is stored in `.page-harness/` |
 | [FAQ](#faq) | Common questions |
+| [Development](./docs/development.md) | Repository map, commands, and conventions |
 | [Homepage](https://cocofhu.github.io/page-harness-site/) | Product tour and install |
 | [npm package](https://www.npmjs.com/package/page-harness) | Released versions |
 
 ## Development
 
+Contributor guide: [docs/development.md](./docs/development.md). Agent notes: [AGENTS.md](./AGENTS.md).
+
 ```bash
 npm install
 npm run dev            # rebuild client bundles and the CLI on change

package/README.zh-CN.md

@@ -273,7 +273,7 @@ GET http://127.0.0.1:17991/__ph/api/review?scope=all&path=%2F&page=1&pageSize=20
 - **两个源。** 你的应用（以及其中任何脚本）在应用端口；面板、API、Agent 接口在控制端口，页面脚本读不到。
 - **所有者与评审者。** 不加 `--share` 时只有本机能连，一切按单用户处理。加了 `--share` 后，所有者会话只发给本机回环请求；其他机器必须通过邀请链接拿到带 HMAC 签名的评审者 Cookie（面板和应用端口各一个），没有就两个端口都返回 `403`。评审者在 WebSocket 上只能做评审操作，API 只能读产物，其余一律 `403`。所有者名字在设置 → 团队里修改。
 - **会话 Cookie。** 面板拿到 `HttpOnly`、`SameSite=Strict`、作用于 `/__ph` 的 Cookie；转发到你的开发服务器前会去掉它。
-- **API。** 读请求要求同源的 `Sec-Fetch-Site`；写请求要求匹配的 `Origin` 加自定义 `X-PH` 头。WebSocket 校验 Cookie 和 `Origin`。书签是例外：跨源读写意见必须带本次运行的 `X-PH-Token`，响应会反射该页面的 `Origin`（不会是 `*`）。`GET /__ph/api/review` 仍给 curl 用，不带 CORS 头。
+- **API。** 读请求要求同源的 `Sec-Fetch-Site`；写请求要求匹配的 `Origin` 加自定义 `X-PH` 头。WebSocket 校验 Cookie 和 `Origin`。书签是例外：跨源读写意见必须带本次运行的 `X-PH-Token`，响应会反射该页面的 `Origin`（不会是 `*`）。`GET /__ph/api/review` 仍给 curl 用，不带 CORS 头。`POST /__ph/api/review/resolve` 是本机 Agent 的接口，既不带 Cookie 也不带令牌：只接受不带 `Origin` 的请求（curl、复制出的提示词），浏览器、跨站请求和会话 Cookie 一律返回 `403`。
 - **MCP。** 每一轮 Agent 调用都发一个独立的 Bearer token（通过环境变量或私有临时文件传递，不出现在命令行），回合结束即作废。来自浏览器的 MCP 请求一律拒绝。
 - **Host 白名单。** `Host` 头不符的请求返回 `421`（防 DNS rebinding）。在局域网使用时用 `--allow-host` 添加。
 - **嵌入限制。** 面板只允许被应用源嵌入；聊天记录页不允许被任何页面嵌入。
@@ -328,11 +328,14 @@ team.json                   邀请 token、签名密钥和评审者名字（权
 | [安全模型](#安全模型) | 哪些地方锁住了，怎么锁的 |
 | [数据](#数据) | `.page-harness/` 里存了什么 |
 | [常见问题](#常见问题) | 大家常问的 |
+| [开发说明](./docs/development.md) | 仓库地图、命令和开发约定 |
 | [官网](https://cocofhu.github.io/page-harness-site/) | 产品演示与安装 |
 | [npm 包](https://www.npmjs.com/package/page-harness) | 已发布的版本 |
 
 ## 开发
 
+贡献说明见 [docs/development.md](./docs/development.md)，改代码时的约束见 [AGENTS.md](./AGENTS.md)。
+
 ```bash
 npm install
 npm run dev            # 监听并重建前端脚本与 CLI

package/dist/cli.js

@@ -2833,6 +2833,9 @@ function parseCookies(header) {
   return out;
 }
 var LOOPBACK = /* @__PURE__ */ new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+function isLoopbackBind(host) {
+  return host === "localhost" || LOOPBACK.has(host);
+}
 function isLoopback(req) {
   return LOOPBACK.has(req.socket.remoteAddress ?? "");
 }
@@ -2894,8 +2897,17 @@ var Auth = class {
   get sharing() {
     return !!this.opts.team?.enabled;
   }
+  /**
+   * Panel session. SameSite=Strict is discarded when DSH (127.0.0.1) frames the localhost
+   * panel, so the WebSocket never gets a session and the overlay stays on "Lost connection".
+   * Loopback and https use a partitioned cookie, which the browser keeps in that iframe.
+   * Plain HTTP on a public host stays Strict: a Secure cookie would not be stored there.
+   */
   setCookie(res, value) {
-    res.appendHeader("Set-Cookie", `${this.cookieName}=${value}; Path=/__ph; HttpOnly; SameSite=Strict${this.secureAttr}${value === this.uiSecret ? "" : "; Max-Age=31536000"}`);
+    const persistent = value === this.uiSecret ? "" : "; Max-Age=31536000";
+    const partitioned = this.scheme === "https" || isLoopbackBind(this.opts.host);
+    const sameSite = partitioned ? "; SameSite=None; Secure; Partitioned" : `; SameSite=Strict${this.secureAttr}`;
+    res.appendHeader("Set-Cookie", `${this.cookieName}=${value}; Path=/__ph; HttpOnly${sameSite}${persistent}`);
   }
   /**
    * Called when a panel page is served. Keeps an existing session; otherwise local requests get
@@ -2981,6 +2993,18 @@ var Auth = class {
   revokeMcpToken(token) {
     this.mcpTokens.delete(token);
   }
+  /**
+   * The local review API (`POST /__ph/api/review/resolve`) is the one write a coding agent makes with
+   * plain curl, so it can carry neither the session cookie nor a token. Browsers must not reach it:
+   * every browser POST carries `Origin`, and a page that could call this would mark the user's notes
+   * resolved with no session, no token and no prompt.
+   */
+  checkLocalAgent(req) {
+    if (req.headers.origin) return "browsers may not call the local agent API";
+    if (req.headers["sec-fetch-site"] === "cross-site") return "cross-site requests are not accepted here";
+    if (req.headers.cookie && parseCookies(req.headers.cookie)[this.cookieName]) return "session cookies are not accepted here";
+    return null;
+  }
   /** MCP endpoint: agent CLIs only. */
   checkMcp(req) {
     if (req.headers.origin) return { error: "browsers may not call the MCP endpoint" };
@@ -5026,7 +5050,7 @@ async function startServers(o) {
       if (!o.auth.allowEmbed(req)) return noAccess(res, "Open this preview from the embedding page.<br>\u8BF7\u4ECE\u5D4C\u5165\u9884\u89C8\u7684\u9875\u9762\u6253\u5F00\u3002");
       const url = new URL(req.url ?? "/", "http://x");
       const p = url.pathname;
-      if (req.method === "OPTIONS" && (p === "/__ph/overlay.js" || p.startsWith("/__ph/api/review"))) {
+      if (req.method === "OPTIONS" && p !== "/__ph/api/review/resolve" && (p === "/__ph/overlay.js" || p.startsWith("/__ph/api/review"))) {
         bookmarkletCors(req, res);
         res.writeHead(204, { "Cache-Control": "no-store" });
         return res.end();
@@ -5258,6 +5282,8 @@ async function serveReviewExtras(o, req, res, url) {
     return true;
   }
   if (m === "POST" && p === "/__ph/api/review/resolve") {
+    const err = o.auth.checkLocalAgent(req);
+    if (err) return json(res, { ok: false, error: err }, 403), true;
     await serveReviewResolve(o.gateway, req, res);
     return true;
   }