Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

docs: add a security model page in the reference section (#455)

Myriad-Dreamind73a3bdbac69
diff --git a/changelog/unreleased/2026-08-24-security-docs.md b/changelog/unreleased/2026-08-24-security-docs.md
new file mode 100644
index 00000000..16c3158f
--- /dev/null
+++ b/changelog/unreleased/2026-08-24-security-docs.md
@@ -0,0 +1,16 @@
+# A Security Model page in the docs
+
+- **Date:** 2026-08-24
+- **Type:** docs
+- **Scope:** `docs`
+
+[中文版](2026-08-24-security-docs.zh.md)
+
+The reference section gains a Security Model page, organized as scenarios in the order a user
+meets them: a feature inventory first, then first login (web and desktop), changing a password
+by each of its four paths, automation on the local machine, remote machines — where ssh access
+to a machine is stated plainly to equal CLI access on it — and taking access away, ending with
+the leak-response scenario the design is built around: a leaked data-root backup is a
+credential-rotation incident for the model keys it contains, not a forged-session incident. The
+mechanics (token format, disk inventory, network surface) are collected at the end for
+reference.
diff --git a/changelog/unreleased/2026-08-24-security-docs.zh.md b/changelog/unreleased/2026-08-24-security-docs.zh.md
new file mode 100644
index 00000000..eaf510aa
--- /dev/null
+++ b/changelog/unreleased/2026-08-24-security-docs.zh.md
@@ -0,0 +1,12 @@
+# 文档新增"安全模型"页面
+
+- **日期:** 2026-08-24
+- **类型:** docs
+- **范围:** `docs`
+
+[English](2026-08-24-security-docs.md)
+
+参考区新增"安全模型"页,按用户实际遇到的顺序以场景组织:先列功能清单,然后是首次登录(Web 与
+桌面)、修改密码的四条路径、本机自动化、远程机器——明说"对机器的 ssh 访问权等于其上的 CLI 权限"——
+以及收回访问权,收在这套设计围绕的泄露场景上:数据根备份泄露是一次针对其中模型 key 的凭据轮换事件,
+而不是会话伪造事件。底层机制(令牌格式、磁盘清单、网络暴露面)集中在文末备查。
diff --git a/packages/cli/src/commands/reset-password.ts b/packages/cli/src/commands/reset-password.ts
index ae4737e0..1f4793a4 100644
--- a/packages/cli/src/commands/reset-password.ts
+++ b/packages/cli/src/commands/reset-password.ts
@@ -6,9 +6,9 @@
* reset the admin itself once its password is forgotten. This subcommand of `penguin
* server` closes that gap from the machine owning the data root (PENGUIN_HOME or the
* default root, PENGUIN_WEB_DB honored for the database path): it refuses while a live
- * server owns the root (web.db is single-writer), otherwise the built-in admin gets a
- * fresh initial password, printed here in the same framed notice the server prints on
- * startup — and re-printed on every later start until the password is changed.
+ * server owns the root (web.db is single-writer), otherwise the built-in admin returns to
+ * the unclaimed state with its sessions revoked, and the next server start prints a fresh
+ * first-login link to claim it through (reset-admin-password.ts).
* Docs: /docs/cli § "penguin server / penguin web".
*/
import path from "node:path";
diff --git a/packages/docs/content/security.en.md b/packages/docs/content/security.en.md
new file mode 100644
index 00000000..dfc77f6a
--- /dev/null
+++ b/packages/docs/content/security.en.md
@@ -0,0 +1,107 @@
+---
+title: Security Model
+description: How access works, scenario by scenario — first login, passwords, automation, remote machines, revocation — and the mechanics underneath.
+---
+
+PenguinHarness runs agents with real credentials on real machines, so it is worth knowing exactly who can do what, on the strength of which proof. This page walks the model in the order you meet it: claiming a fresh server, managing passwords, automating on the local machine, managing remote machines, and taking access away. The mechanics — token format, what is on disk, the network surface — are collected at the end.
+
+One principle carries every scenario:
+
+> **Reading the data root is ownership.** The data root (`~/.penguin/data` by default) holds every model credential and every conversation. A secret stored beside them could not guard them from someone who can already read them — so the model never pretends otherwise, and instead makes that ownership safe to exercise: short-lived, revocable, and never requiring a password to be stored or transmitted.
+
+## 0. What you get
+
+| Capability | Where |
+| --- | --- |
+| Claim a fresh server through a printed sign-in link — no password exists yet, none is shown | The startup notice |
+| Sign in with a password; storage is scrypt hashes, attempts are throttled | Web login page, `penguin auth login` |
+| The desktop app signs its own window in, silently | One-shot token at window open |
+| Mint a session from local ownership — no password involved | `penguin auth token` |
+| Manage machines over ssh with no password on the wire | The Machines page |
+| Sessions are server-side rows: individually revocable, surviving a restart, 30-day sliding renewal | Everywhere |
+| Every session records how it was established | `via`: `password` (a typed password, or a session minted by `penguin auth token`) / `desktop` / `setup` / `token` (a request carrying the local API token as a Bearer header — no stored session) |
+| Revoke one session, or every session a user holds | Logout / admin password reset |
+| Recover a lost admin password from the machine itself | `penguin server reset-admin-password` |
+
+## 1. Claiming a fresh server
+
+**Web.** A fresh server has no usable password: the seeded value is generated, hashed, and discarded unseen. To let you in anyway, every start prints a sign-in link until a password is set:
+
+```
++--------------------------------------------------------------------+
+| This server has no admin password yet. Open this link to claim: |
+| |
+| http://localhost:7364/api/auth/claim?token=... |
+| |
+| The link works until a password is set, and changes on restart. |
++--------------------------------------------------------------------+
+```
+
+Open it, land signed in, set a password. The link is not one-shot — a mail client may fetch it before you do, and a second open must still work — so three other bounds make it printable into a console:
+
+- It works **only while the server is unclaimed**. Once a password exists it is refused, so a console scrollback is not a way in.
+- The value it is compared against lives **in memory and is re-minted on every restart**. A link from an earlier run is refused; if you miss the notice, restart and read the new one.
+- A wrong token and an already-claimed server answer **identically** — a stale link cannot even reveal which of the two it is.
+
+The session it grants carries `via: setup`. It has exactly one special allowance — setting a password without an old one, since no old one exists — and no more: in particular, none of the desktop-only routes.
+
+**Desktop.** The shell owns the server process it embeds, so its window is let in on that fact alone: the window's first navigation redeems a one-shot token minted by the shell, and lands signed in as `via: desktop`. The token dies on redemption — a leaked URL replays nothing.
+
+Password logins, wherever they come from, are throttled per username with exponential backoff — and unknown usernames are throttled identically, so timing does not reveal whether an account exists.
+
+## 2. Passwords
+
+A chosen password is stored one way only: as an scrypt hash (`N=16384`, per-password salt, parameters stored alongside so cost can rise later). Four ways to set one, each shaped by who is asking:
+
+- **You, knowing the current password** — user settings. The current password is verified first.
+- **You, in a session that never had one** — a `setup` session (§1), or the desktop shell's own window. Both belong to accounts whose password is a random value nobody has seen, so there is nothing to put in an "old password" field; the session's provenance is the authorization.
+- **An admin, for another user** — the account gets a fresh initial password, and every session that user holds is revoked (§5).
+- **Nobody remembers the admin password** — on the server's machine, with the server stopped: `penguin server reset-admin-password`. Local filesystem access is the authorization. The account returns to the unclaimed state with its sessions revoked, and the rescue produces nothing to write down — start the server and claim it through the link, as in §1.
+
+## 3. Automation on this machine
+
+Scripts and the CLI never need a password, because local ownership already outranks one. A session is a row in the data root's `web.db`, so the CLI writes one:
+
+```bash
+penguin auth token # no password, no prompt: inserts a session row
+```
+
+Being able to read and write that data root is the whole authorization, and it grants nothing new — the root already holds every credential the token could reach. It works whether or not a server is running, and safely alongside one — on a root a server has started at least once, since the account it mints for lives in that root's `web.db`. The token lives an hour by default (`--ttl-seconds` sets another lifetime) and acts as an ordinary password session, never the desktop kind.
+
+On a multi-user machine that scoping is the point: the data root belongs to the OS account running the server, so only that account can mint. Everyone else signs in with a password — `penguin auth login --server <url>`.
+
+## 4. Remote machines: ssh access is CLI access
+
+The Machines page manages other machines over ssh, and the identity everything runs under is the ssh account's:
+
+- To act on a machine's API, the controller runs `penguin auth token` **on that machine, over ssh**. The machine's own CLI writes a session row into the machine's own database. The only thing that crosses the wire is a one-hour session token.
+- **No password crosses the wire, ever.** A machine's admin password stays on that machine; ssh has already proven everything a password would.
+- The equation cuts both ways. ssh access to a machine can read its data root by hand, so the token grants nothing ssh had not already granted — and precisely for that reason, **your ssh key is the master credential for every machine it reaches**. Guard it at that level.
+- A Project that syncs model credentials to its machines puts those API keys in each machine's own Project config (mode 0600): a machine that runs your agents necessarily holds the keys they run with.
+
+## 5. Taking access away
+
+| To revoke | Do | Effect |
+| --- | --- | --- |
+| One session | `penguin auth logout`, or sign out in the UI | Immediate — the row is deleted, and a session is its row |
+| One user's sessions | Admin password reset for that user | Immediate — every row for that account is deleted |
+| The admin's own sessions | `penguin server reset-admin-password` (server stopped) | On the next start, which prints a fresh first-login link |
+| A model API key | Rotate it with the provider, update the Project config | Provider-side |
+
+The scenario the design is built around is the worst one — **a full data-root backup leaks**. The response is a credential rotation for the model API keys it contains, and nothing more: passwords in a backup are scrypt hashes, and the session table holds only the sha256 of each token, never a token. Nothing copied out of a backup can be presented to the live server as a session.
+
+## The mechanics underneath
+
+**Sessions.** The cookie carries a 32-byte random token; the `auth_sessions` row keyed by its sha256 is the session, and holds the account, the provenance (`via`) and the expiry. Because the row is the session, deleting it revokes immediately and a restart signs nobody out. Browser sessions run 30 days and renew **in place** as expiry nears — the row's expiry moves, the cookie value does not — so one in regular use never expires and there is never a second copy to chase. Only a session whose own term reaches the renewal window slides, so an hour-long minted token expires at its hour. Cookies are HttpOnly and SameSite=Lax, plus Secure when the request is really https or a **trusted** proxy says so (`PENGUIN_TRUST_PROXY=1`); the header is ignored by default.
+
+**On disk, and deliberately not.**
+
+| File | Contains | Lives |
+| --- | --- | --- |
+| `web.db` | Password **hashes**, session **hashes**, application data | Permanently |
+| `<project>/.project_config.toml` | Model API keys, inline, mode 0600 | Until edited |
+| `cli-session.json` | One live session token, mode 0600 | Until logout or expiry |
+
+Never on disk in usable form: session tokens (only their sha256) and every password — chosen ones exist as scrypt hashes, seeded ones are discarded at birth. Model API keys are the irreducible remainder: they must reach upstream providers verbatim, so they cannot be hashed. They are confined to the Project config, masked in every API response and UI surface, and read in plaintext only at the moment a request is made.
+
+**Network surface.** The server binds 127.0.0.1 by default; exposing it (`HOST=0.0.0.0`) is a deployment decision that belongs behind TLS termination, with the proxy setting `x-forwarded-proto`. The API answers only under its canonical application host, which keeps user-generated preview content in a separate browser origin from the application's cookies. Cross-site request forgery is blocked by two independent layers: the SameSite=Lax cookie, and a Content-Type gate that rejects any write request whose content type an HTML form could produce.
diff --git a/packages/docs/content/security.zh.md b/packages/docs/content/security.zh.md
new file mode 100644
index 00000000..bfdd9c28
--- /dev/null
+++ b/packages/docs/content/security.zh.md
@@ -0,0 +1,107 @@
+---
+title: 安全模型
+description: 按场景讲清访问是怎么运作的——首次登录、密码、自动化、远程机器、吊销——底层机制附于文末。
+---
+
+PenguinHarness 用真实凭据在真实机器上跑智能体,所以"谁凭什么证明、能做什么"值得确切地知道。本页按你遇到它们的顺序展开:认领新服务器、管理密码、本机自动化、管理远程机器、收回访问权。底层机制——令牌格式、磁盘内容、网络暴露面——集中在文末。
+
+一条原则贯穿所有场景:
+
+> **能读数据根即拥有服务器。** 数据根(默认 `~/.penguin/data`)装着全部模型凭据和全部对话。放在它们旁边的秘密防不住已经能读到它们的人——所以这套模型不假装能防,而是把这份所有权变得可以安全行使:短命、可吊销、永远不要求存储或传输密码。
+
+## 0. 你得到什么
+
+| 能力 | 在哪里 |
+| --- | --- |
+| 通过启动时打印的登录链接认领新服务器——密码尚不存在,也不会展示 | 启动提示 |
+| 密码登录;存储为 scrypt 哈希,尝试被节流 | Web 登录页、`penguin auth login` |
+| 桌面应用静默登入自己的窗口 | 窗口打开时的一次性令牌 |
+| 凭本机所有权铸造会话——全程不涉及密码 | `penguin auth token` |
+| 通过 ssh 管理机器,密码不过线 | Machines 页 |
+| 会话是服务端的行:可逐个吊销、跨重启存活、30 天滑动续期 | 所有场景 |
+| 每个会话记录自己的建立方式 | `via`:`password`(输入的密码,或 `penguin auth token` 铸造的会话)/ `desktop` / `setup` / `token`(以 Bearer 头携带本地 API token 的请求——不存储会话) |
+| 吊销一个会话,或一个用户的全部会话 | 登出 / 管理员重置密码 |
+| 在服务器所在机器上找回丢失的管理员密码 | `penguin server reset-admin-password` |
+
+## 1. 认领新服务器
+
+**Web。** 新服务器没有可用的密码:种子值生成后即哈希、丢弃,无人见过。为了仍然让你进来,在密码被设置之前,每次启动都会打印一条登录链接:
+
+```
++--------------------------------------------------------------------+
+| This server has no admin password yet. Open this link to claim: |
+| |
+| http://localhost:7364/api/auth/claim?token=... |
+| |
+| The link works until a password is set, and changes on restart. |
++--------------------------------------------------------------------+
+```
+
+打开、落地即已登录、设置密码。这条链接不是一次性的——邮件客户端可能先于你抓取它,第二次打开必须仍然有效——因此靠另外三重边界让它可以放心打印进控制台:
+
+- **只在服务器未被认领时有效。** 密码一旦存在即被拒绝,控制台回滚记录不构成入口。
+- 用来比对的那个值**只在内存里,每次重启重新铸造**。更早一次运行的链接会被拒绝;错过提示,重启再读新的即可。
+- 错误令牌与已认领的服务器返回**完全一致**——一条过期链接连"属于哪种情况"都无法透露。
+
+它授予的会话带 `via: setup`,恰好持有一项特殊豁免——免旧密码设置密码,因为旧密码并不存在——再无其他:尤其是,不含任何桌面专属路由。
+
+**桌面。** 客户端拥有它内嵌的服务进程,它的窗口凭这一事实被放行:窗口的首次导航兑换一枚由客户端铸造的一次性令牌,落地即以 `via: desktop` 登录。令牌在兑换的瞬间死亡——泄露的 URL 无法重放。
+
+无论来自哪里,密码登录都按用户名指数退避节流——不存在的用户名以完全相同的方式节流,时间上看不出账号是否存在。
+
+## 2. 密码
+
+选定的密码只以一种方式存储:scrypt 哈希(`N=16384`,每密码随机盐,参数随哈希保存,成本可日后提高)。设置密码有四条路,各由"谁在请求"决定形状:
+
+- **你,知道当前密码**——用户设置页。先验当前密码。
+- **你,处在一个从未有过密码的会话里**——`setup` 会话(§1),或桌面客户端自己的窗口。两者的账号密码都是无人见过的随机值,"旧密码"框里没有东西可填;会话的来历就是授权。
+- **管理员,为另一个用户**——该账号获得新的初始密码,其持有的所有会话被吊销(§5)。
+- **没人记得管理员密码**——在服务器所在机器上、停止服务后执行 `penguin server reset-admin-password`。本机文件系统访问就是授权。账号回到未认领状态、会话全部吊销,救援不产生任何需要抄写的东西——启动服务,按 §1 用链接认领。
+
+## 3. 本机自动化
+
+脚本和 CLI 永远不需要密码,因为本机所有权本就高于密码。会话就是数据根 `web.db` 里的一行,所以 CLI 直接写入一行:
+
+```bash
+penguin auth token # 无密码、无提问:插入一行会话
+```
+
+能读写那个数据根就是全部授权,而且它不带来任何新权限——数据根本就装着这枚令牌所能触及的一切凭据。服务在跑或不在跑都能用,在跑时也安全——前提是该数据根上服务至少启动过一次,因为它铸造的账号就在那个根的 `web.db` 里。令牌默认活一小时(`--ttl-seconds` 可另设),作为普通密码会话行事,永远不是桌面那种。
+
+在多用户机器上,这个界定正是要点:数据根属于运行服务的那个操作系统账号,因此只有该账号能铸造。其他人一律用密码登录——`penguin auth login --server <url>`。
+
+## 4. 远程机器:ssh 权限即 CLI 权限
+
+Machines 页通过 ssh 管理其他机器,一切都运行在 ssh 账户的身份之下:
+
+- 要操作某台机器的 API,控制端**通过 ssh 在那台机器上**执行 `penguin auth token`:那台机器自己的 CLI 往那台机器自己的数据库里写一行会话。过线的只有一枚一小时的会话令牌。
+- **密码永不过线。** 机器的管理员密码留在那台机器上;ssh 已经证明了密码所能证明的一切。
+- 这个等式两面成立。ssh 到一台机器就能徒手读它的数据根,令牌没有授予 ssh 未曾授予的任何东西——也正因如此,**你的 ssh 私钥是它所能到达的所有机器的主凭据**,请按这个等级保护。
+- 项目向机器同步模型凭据时,API key 进入各机器自己的项目配置(0600):替你跑智能体的机器,必然持有智能体运行所用的 key。
+
+## 5. 收回访问权
+
+| 要吊销 | 操作 | 效果 |
+| --- | --- | --- |
+| 一个会话 | `penguin auth logout`,或界面登出 | 立即——行被删除,而行即会话 |
+| 一个用户的会话 | 管理员重置该用户密码 | 立即——该账号的全部行被删除 |
+| 管理员自己的会话 | 停止服务后执行 `penguin server reset-admin-password` | 下次启动时生效,并打印新的首次登录链接 |
+| 模型 API key | 在服务商处轮换,更新项目配置 | 取决于服务商 |
+
+这套设计围绕的正是最坏的那个场景——**整个数据根备份泄露**。应对只是一次针对其中模型 API key 的凭据轮换,仅此而已:备份里的密码是 scrypt 哈希,会话表里只有每枚令牌的 sha256、从来没有令牌本身。从备份里抄出来的任何东西都无法作为会话呈递给线上服务器。
+
+## 底层机制
+
+**会话。** Cookie 里装的是 32 字节随机令牌;以其 sha256 为键的 `auth_sessions` 行才是会话,行里存账号、来历(`via`)和过期时间。因为行即会话,删除它即刻吊销,而重启不会登出任何人。浏览器会话 30 天,临近过期**原地**续期——移动的是行的过期时间,Cookie 的值不变——因此常规使用中的会话永不过期,也从不产生需要追杀的第二个副本。只有自身期限达到续期窗口的会话才滑动,所以一小时的铸造令牌就在一小时到期。Cookie 为 HttpOnly、SameSite=Lax;只有请求确实是 https、或**受信任的**代理这样声明时(`PENGUIN_TRUST_PROXY=1`)才加 Secure,该头默认被忽略。
+
+**磁盘上有的,和刻意没有的。**
+
+| 文件 | 内容 | 存续 |
+| --- | --- | --- |
+| `web.db` | 密码**哈希**、会话**哈希**、应用数据 | 永久 |
+| `<project>/.project_config.toml` | 模型 API key,内联,0600 | 直到被编辑 |
+| `cli-session.json` | 一枚活跃会话令牌,0600 | 到登出或过期 |
+
+从不以可用形式落盘的:会话令牌(只有其 sha256)、以及一切密码——选定的以 scrypt 哈希存在,种子在诞生时即被丢弃。模型 API key 是无法消除的剩余项:它们必须原样抵达上游服务商,无法哈希。它们被限制在项目配置里,在所有 API 响应和界面上被掩码,只在发出请求的那一刻以明文被读出。
+
+**网络暴露面。** 服务默认绑定 127.0.0.1;对外暴露(`HOST=0.0.0.0`)是部署决定,应置于 TLS 终结之后,由代理设置 `x-forwarded-proto`。API 只在规范应用主机名下应答,这让用户生成的预览内容与应用 cookie 处于不同的浏览器源。跨站请求伪造由两层独立防线阻断:SameSite=Lax cookie,加一道 Content-Type 闸——凡 HTML 表单能够产生的内容类型的写请求,一律拒绝。
diff --git a/packages/docs/src/lib/nav.ts b/packages/docs/src/lib/nav.ts
index b5e55436..f70defd6 100644
--- a/packages/docs/src/lib/nav.ts
+++ b/packages/docs/src/lib/nav.ts
@@ -56,7 +56,7 @@ export const DOCS_NAV: DocsSectionDef[] = [
"sessions-and-traces",
),
},
- { id: "reference", pages: pages("cli", "server-api", "configuration") },
+ { id: "reference", pages: pages("cli", "server-api", "configuration", "security") },
];
/** All slugs in display order — each parent immediately followed by its children. */