Skip to content

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

feat(server): SOCKS proxy addresses and offline admin password reset (#315)

Yaowei Zhenge709e7cde3b2
diff --git a/changelog/unreleased/2026-08-18-admin-password-reset.md b/changelog/unreleased/2026-08-18-admin-password-reset.md
new file mode 100644
index 00000000..7428360b
--- /dev/null
+++ b/changelog/unreleased/2026-08-18-admin-password-reset.md
@@ -0,0 +1,13 @@
+# Offline admin password reset: `penguin server reset-admin-password`
+
+The admin resets every other user's password from the user-management page, but a forgotten **admin** password had no recovery path once it was changed from the initial one (the plaintext file in the data root only survives while the password is still initial). A new CLI subcommand closes the gap from the machine that owns the data root:
+
+```bash
+penguin server reset-admin-password
+```
+
+- Refuses while a live server owns the root (`web.db` is single-writer) and points at the running instance; with the server stopped it resets the built-in `admin` to a fresh random `penguin-<4 digits>` initial password and prints it in the same framed notice the server shows on startup.
+- The whole initial-password machinery is re-armed: `password_is_initial` set, the plaintext stored owner-only in the data root, the framed reminder re-printed on every server start until the password is changed — and all of admin's sign-in sessions are cleared, matching an admin-initiated reset.
+- Nothing-to-reset roots are reported without side effects: a missing `web.db` is never created by the command, and an unseeded database is called out as such.
+- Implementation: a side-effect-free `@prismshadow/penguin-server/reset-admin-password` subpath export (like `./lock`), so the CLI runs the reset without importing the server entry, which starts listening. Authorization is local filesystem access — whoever can run it already owns the SQLite database next to the file it writes.
+- Discoverability: `penguin server` starts the service directly, so nobody browses its subcommand help — the login page's footer gains a second hint line naming the command (the one place a locked-out admin is guaranteed to be looking), and the `server` command description mentions the subcommand so it shows in top-level `penguin --help`.
diff --git a/changelog/unreleased/2026-08-18-proxy-socks.md b/changelog/unreleased/2026-08-18-proxy-socks.md
new file mode 100644
index 00000000..9131bf2d
--- /dev/null
+++ b/changelog/unreleased/2026-08-18-proxy-socks.md
@@ -0,0 +1,8 @@
+# Proxy options: SOCKS proxy addresses
+
+The admin proxy address (the "Proxy options" dialog, `PUT /api/admin/settings`) now accepts any proxy URL undici's dispatcher takes — `http://`, `https://` and the (experimental in undici 7.29) `socks5://` / `socks://` schemes, credentials allowed — alongside the unchanged bare `host[:port]` shorthand (still normalized to `http://…`).
+
+- The write-time gate is a probe ProxyAgent construction rather than a scheme list: what undici refuses (`socks4://`, `ftp://`, …) is `400 invalid_proxy_url` instead of a stored value that would crash every later startup — the dispatcher is rebuilt from the stored address on every boot, and undici throws at construction time on schemes it cannot speak.
+- The canonical stored form moves from `url.origin` to `url.href` minus the parser's bare `/`: origin drops credentials and reads `"null"` for non-special schemes like socks.
+- The agent-environment switch injects a `socks5://` address verbatim into `HTTP_PROXY` / `HTTPS_PROXY`; tools vary in accepting SOCKS URLs there. Desktop OS-proxy resolution still skips PAC SOCKS results for the same reason — OS-level SOCKS is opted into explicitly through the dialog instead.
+- A new end-to-end test tunnels a fetch through a fake SOCKS5 server; the loopback NO_PROXY exemption applies to SOCKS addresses exactly as before.
diff --git a/changelog/unreleased/README.md b/changelog/unreleased/README.md
index 3bf17a28..2b8fe135 100644
--- a/changelog/unreleased/README.md
+++ b/changelog/unreleased/README.md
@@ -1,5 +1,7 @@
# Unreleased
+- [2026-08-18] Web App: the admin proxy address accepts `socks5://` / `socks://` URLs (undici's experimental SOCKS5 tunnel) alongside `http(s)://`, credentials allowed; validation becomes "whatever undici's dispatcher constructs", so schemes it refuses (`socks4://`, …) stay `400 invalid_proxy_url` instead of bricking the next server start. ([details](2026-08-18-proxy-socks.md))
+- [2026-08-18] CLI: `penguin server reset-admin-password` — offline rescue for a forgotten Web admin password: with the server stopped, resets `admin` to a fresh initial password (framed notice, re-printed on every start until changed; the login-page footer and top-level `penguin --help` now point at the command) and clears its sign-in sessions. ([details](2026-08-18-admin-password-reset.md))
- [2026-08-18] Core & Web App: an official `MiniMax-M3` preset (1M context, vision) pins AgentHub's `minimax-m3` Responses client and direct endpoint, uses `MINIMAX_*` credential fallback, prices at the standard pay-as-you-go tier (≤512K input), and adds the MiniMax provider glyph plus bilingual docs (requires AgentHub >= 0.4.2). ([details](2026-08-18-minimax-m3-preset.md))
- [2026-08-18] The running harness — desktop app included — can be updated over HTTP without a restart: one atomic push replaces the backend platform, the CLI's commands (`penguin-hmr`), and the Web App together; pushed code can add or replace API endpoints; live terminals survive the swap. Admin session required, loopback-only without HTTPS. ([details](2026-08-18-hot-update.md))
- [2026-08-18] Web App: code highlighting is assembled from `shiki/core` with an explicit language list and the pure-JavaScript regex engine instead of Shiki's full bundle — the first code block of a conversation costs ~69 KB gzip instead of ~308 KB (the oniguruma WASM engine and the 332-grammar registry are gone; every bundled grammar was verified to translate to JavaScript regexes with byte-identical tokens), at the cost of languages outside the carried list rendering unhighlighted (#300). ([details](2026-08-18-web-code-highlight-bundle.md))
diff --git a/packages/cli/src/commands/reset-password.ts b/packages/cli/src/commands/reset-password.ts
new file mode 100644
index 00000000..182b38f3
--- /dev/null
+++ b/packages/cli/src/commands/reset-password.ts
@@ -0,0 +1,51 @@
+/**
+ * `penguin server reset-admin-password` — offline rescue when the Web admin password is
+ * lost.
+ *
+ * The admin resets every other user from the user-management page, but nothing can
+ * 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.
+ * Docs: /docs/cli § "penguin server / penguin web".
+ */
+import path from "node:path";
+import { resolveRoot } from "@prismshadow/penguin-core";
+import { renderInitialPasswordNotice } from "@prismshadow/penguin-server/initial-password";
+import { resetAdminPassword } from "@prismshadow/penguin-server/reset-admin-password";
+import type { Command } from "commander";
+import type { Messages } from "../i18n.js";
+
+/** Attaches the subcommand to the `penguin server` command (see registerServeCommands). */
+export function registerResetPasswordCommand(server: Command, t: Messages): void {
+ server
+ .command("reset-admin-password")
+ .description(t.resetPassword.desc)
+ .action(async () => {
+ const root = process.env.PENGUIN_HOME ?? resolveRoot();
+ const dbPath = process.env.PENGUIN_WEB_DB ?? path.join(root, "web.db");
+ const result = await resetAdminPassword(root, dbPath);
+ switch (result.outcome) {
+ case "server_running":
+ process.stderr.write(
+ t.resetPassword.serverRunning(`http://localhost:${result.lock.port}/`) + "\n",
+ );
+ process.exitCode = 1;
+ return;
+ case "no_database":
+ process.stderr.write(t.resetPassword.noDatabase(result.dbPath) + "\n");
+ process.exitCode = 1;
+ return;
+ case "no_admin":
+ process.stderr.write(t.resetPassword.noAdmin() + "\n");
+ process.exitCode = 1;
+ return;
+ case "reset":
+ process.stdout.write(t.resetPassword.done(root) + "\n");
+ process.stdout.write(renderInitialPasswordNotice("admin", result.password) + "\n");
+ process.stdout.write(t.resetPassword.next() + "\n");
+ }
+ });
+}
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
index 141915fb..b0606fb1 100644
--- a/packages/cli/src/commands/serve.ts
+++ b/packages/cli/src/commands/serve.ts
@@ -2,6 +2,7 @@
* `penguin server` / `penguin web` — starts the Web service.
*
* penguin server [--port <port>] [--host <host>]
+ * penguin server reset-admin-password (subcommand, see reset-password.ts)
* penguin web [--port <port>] [--host <host>] [--no-open]
*
* Both are entry points into the same service process: after setting PORT / HOST, it
@@ -24,6 +25,7 @@ import {
import { liveServerLock } from "@prismshadow/penguin-server/lock";
import type { Command } from "commander";
import type { Messages, WebProbeFailureKind } from "../i18n.js";
+import { registerResetPasswordCommand } from "./reset-password.js";
/** Why the readiness poll gave up: failure class plus a one-line diagnostic from the last probe. */
export interface ReadinessFailure {
@@ -255,7 +257,7 @@ function openBrowser(url: string): void {
}
export function registerServeCommands(program: Command, t: Messages): void {
- program
+ const server = program
.command("server")
.description(t.serve.serverDesc)
.option("--port <port>", t.serve.port)
@@ -269,6 +271,9 @@ export function registerServeCommands(program: Command, t: Messages): void {
}
await startServer(opts);
});
+ // Bare `penguin server` still starts the service (commander runs the action when no
+ // subcommand is named); the subcommand only dispatches on an exact name match.
+ registerResetPasswordCommand(server, t);
program
.command("web")
diff --git a/packages/cli/src/i18n.ts b/packages/cli/src/i18n.ts
index 5515f33c..3c5e2b6b 100644
--- a/packages/cli/src/i18n.ts
+++ b/packages/cli/src/i18n.ts
@@ -85,6 +85,20 @@ export interface Messages {
host: string;
noOpen: string;
};
+ /** `penguin server reset-admin-password`: help text and every line the command can print. */
+ resetPassword: {
+ desc: string;
+ /** Refusal while a live server owns the data root (stop it first, then retry). */
+ serverRunning(url: string): string;
+ /** The root has no Web database: nothing to reset. */
+ noDatabase(dbPath: string): string;
+ /** The database exists but the admin was never seeded. */
+ noAdmin(): string;
+ /** Success header, printed above the framed credentials notice. */
+ done(root: string): string;
+ /** Hint printed below the notice. */
+ next(): string;
+ };
/** `penguin update`: help text and every line the command can print. */
update: {
desc: string;
@@ -348,12 +362,28 @@ const en: Messages = {
"Resume an existing Session (defaults to the agent's most recent one); workspace and model follow the original Session",
},
serve: {
- serverDesc: "Start the Web service (HTTP API and the built-in frontend, same process)",
+ serverDesc:
+ "Start the Web service (HTTP API and the built-in frontend, same process); subcommand reset-admin-password resets a forgotten admin password",
webDesc: "Start the Web service and open the UI in a browser once it is ready",
port: "Listen port (falls back to the PORT env var, default 7364)",
host: "Listen address (falls back to the HOST env var, default 127.0.0.1)",
noOpen: "Do not open a browser automatically",
},
+ resetPassword: {
+ desc: "Reset the Web admin password to a fresh initial password (the server must be stopped)",
+ serverRunning: (url) =>
+ `A PenguinHarness server is running on this data root: ${url}\n` +
+ `Stop it first, then run \`penguin server reset-admin-password\` again.`,
+ noDatabase: (dbPath) =>
+ `No Web database at ${dbPath} — nothing to reset. ` +
+ `Start the service once (\`penguin web\`) to create the admin account.`,
+ noAdmin: () =>
+ "The Web database has no admin account yet — nothing to reset. " +
+ "Start the service once (`penguin web`) to seed it.",
+ done: (root) =>
+ `Admin password reset for data root ${root}. All admin sign-in sessions were cleared.`,
+ next: () => "Start the service (`penguin web`) and sign in with the password above.",
+ },
update: {
desc: "Upgrade this PenguinHarness install in place",
check: "Only report the current and latest versions; change nothing",
@@ -590,12 +620,25 @@ const zh: Messages = {
"恢复既有 Session 继续对话(缺省恢复当前 Agent 最近一次);Workspace 与模型沿用原 Session",
},
serve: {
- serverDesc: "启动 Web 服务(HTTP API 与内置前端,同一进程)",
+ serverDesc:
+ "启动 Web 服务(HTTP API 与内置前端,同一进程);子命令 reset-admin-password 重置忘记的管理员密码",
webDesc: "启动 Web 服务,就绪后用浏览器打开界面",
port: "监听端口(其次取环境变量 PORT,缺省 7364)",
host: "监听地址(其次取环境变量 HOST,缺省 127.0.0.1)",
noOpen: "不自动打开浏览器",
},
+ resetPassword: {
+ desc: "把 Web 管理员密码重置为新的初始密码(须先停止服务)",
+ serverRunning: (url) =>
+ `该数据根目录已有 PenguinHarness 服务在运行:${url}\n` +
+ `请先停止它,再重新执行 \`penguin server reset-admin-password\`。`,
+ noDatabase: (dbPath) =>
+ `${dbPath} 处没有 Web 数据库,无可重置。请先执行 \`penguin web\` 启动一次服务以创建管理员账号。`,
+ noAdmin: () =>
+ "Web 数据库中尚无管理员账号,无可重置。请先执行 `penguin web` 启动一次服务完成种子创建。",
+ done: (root) => `已重置数据根目录 ${root} 的管理员密码,并清空其全部登录会话。`,
+ next: () => "启动服务(`penguin web`)后用上方密码登录。",
+ },
update: {
desc: "原地升级当前的 PenguinHarness 安装",
check: "只报告当前版本与最新版本,不做任何修改",
diff --git a/packages/desktop/src/os-proxy.ts b/packages/desktop/src/os-proxy.ts
index a0734ffe..b164b6f6 100644
--- a/packages/desktop/src/os-proxy.ts
+++ b/packages/desktop/src/os-proxy.ts
@@ -32,8 +32,10 @@ export function unsetProxyVars(env: NodeJS.ProcessEnv): readonly ProxyVar[] {
* Maps one PAC-style resolveProxy result to a proxy URL, or null for "connect
* directly". The result is a `;`-separated fallback list ("PROXY host:port; DIRECT");
* the first usable entry wins: `PROXY` → http://, `HTTPS` (a proxy reached over TLS) →
- * https://. `DIRECT` and the SOCKS flavors yield nothing — undici's dispatcher speaks
- * only HTTP(S) proxies, and injecting a socks:// URL would break every server fetch.
+ * https://. `DIRECT` and the SOCKS flavors yield nothing: the injected variables also
+ * reach agent command subprocesses, where a socks:// value in HTTP(S)_PROXY is not
+ * universally understood, and undici's SOCKS support is still experimental — an admin
+ * who wants SOCKS sets it explicitly in the proxy options instead of via OS lookup.
*/
export function proxyUrlFromPacResult(result: string): string | null {
for (const entry of result.split(";")) {
diff --git a/packages/docs/content/cli.en.md b/packages/docs/content/cli.en.md
index f57388d3..434a2b2b 100644
--- a/packages/docs/content/cli.en.md
+++ b/packages/docs/content/cli.en.md
@@ -147,6 +147,16 @@ penguin web
Port / host priority: command-line option > the `PORT` / `HOST` env vars (including `.env`) > defaults.
+### penguin server reset-admin-password
+
+Offline rescue when the Web admin password is forgotten. Run it with the server stopped — it refuses while one is running on the data root:
+
+```bash
+penguin server reset-admin-password
+```
+
+The built-in `admin` gets a fresh initial password of the usual `penguin-1234` form, printed in the framed notice — and re-printed on every server start until it is changed — and all of admin's sign-in sessions are cleared. Other accounts are reset by the admin on the user-management page; this command only touches `admin`. The data root is selected by `PENGUIN_HOME` as usual.
+
## penguin update
Upgrades this install in place, using the mechanism it was installed with. The install kind is detected from the real path of the running CLI, never guessed.
diff --git a/packages/docs/content/cli.zh.md b/packages/docs/content/cli.zh.md
index 58fda457..1bdb479d 100644
--- a/packages/docs/content/cli.zh.md
+++ b/packages/docs/content/cli.zh.md
@@ -147,6 +147,16 @@ penguin web
端口 / 地址优先级:命令行选项 > 环境变量 `PORT` / `HOST`(含 `.env`)> 默认值。
+### penguin server reset-admin-password
+
+忘记 Web 管理员密码时的离线救援。须在服务停止后执行——数据根目录上有服务在运行时会拒绝:
+
+```bash
+penguin server reset-admin-password
+```
+
+内置 `admin` 会得到一个新的初始密码(形如 `penguin-1234`),以边框提示打印——此后每次启动服务端都会重印,直到密码被修改——并清空 admin 的全部登录会话。其他账号由管理员在用户管理页重置,本命令只作用于 `admin`。数据根目录照常由 `PENGUIN_HOME` 决定。
+
## penguin update
原地升级当前安装,并沿用它当初的安装方式。安装方式由运行中 CLI 的真实路径判定,不做猜测。
diff --git a/packages/docs/content/server-api.en.md b/packages/docs/content/server-api.en.md
index d48082bb..1a5a2f05 100644
--- a/packages/docs/content/server-api.en.md
+++ b/packages/docs/content/server-api.en.md
@@ -79,8 +79,8 @@ In desktop mode (the server spawned by the desktop app) the whole surface answer
The proxy settings are two independent switches sharing one optional explicit address; changes take effect for newly initiated connections/spawns immediately — no restart:
- `proxyForApp` ("application uses the proxy", default on) governs the server's own outbound traffic (LLM requests, the update check, image fetches): on with `proxyUrl` set → that address for both http and https, **taking precedence over the proxy environment variables** — no environment variable needs to be configured; on without an address → the environment variables HTTP_PROXY / HTTPS_PROXY / NO_PROXY (both spellings); off → always direct.
-- `proxyForAgent` ("agent environment uses the proxy", default on) governs agent command subprocess environments: on with `proxyUrl` set → `HTTP_PROXY` / `HTTPS_PROXY` (plus lowercase twins) are injected as that address together with the merged NO_PROXY, overriding inherited values; on without an address → the host environment passes through unchanged; off → the proxy variables are stripped (NO_PROXY is kept).
-- `proxyUrl` (default null = follow the environment variables) is the shared explicit address. Validation on PUT: the value is trimmed; empty or null clears the address; accepted forms are `http://host[:port]`, `https://host[:port]`, and bare `host[:port]` (normalized to `http://host[:port]` — only normalized values are stored, and the response echoes the stored form); anything else is `400` with code `invalid_proxy_url`, and the rejected PUT writes nothing.
+- `proxyForAgent` ("agent environment uses the proxy", default on) governs agent command subprocess environments: on with `proxyUrl` set → `HTTP_PROXY` / `HTTPS_PROXY` (plus lowercase twins) are injected as that address together with the merged NO_PROXY, overriding inherited values (a `socks5://` address is injected verbatim — tools vary in accepting SOCKS URLs in these variables); on without an address → the host environment passes through unchanged; off → the proxy variables are stripped (NO_PROXY is kept).
+- `proxyUrl` (default null = follow the environment variables) is the shared explicit address. Validation on PUT: the value is trimmed; empty or null clears the address; accepted are the proxy URLs undici's dispatcher takes — `http://`, `https://` and (experimental in undici) `socks5://` / `socks://` addresses, credentials allowed — plus bare `host[:port]` (normalized to `http://host[:port]`); only normalized values are stored, and the response echoes the stored form. Anything else — unparseable, or a scheme undici refuses, such as `socks4://` — is `400` with code `invalid_proxy_url`, and the rejected PUT writes nothing.
In every on-state the effective NO_PROXY always includes `localhost,127.0.0.1,::1` (loopback is never proxied).
diff --git a/packages/docs/content/server-api.zh.md b/packages/docs/content/server-api.zh.md
index c96a0b37..f6b5868b 100644
--- a/packages/docs/content/server-api.zh.md
+++ b/packages/docs/content/server-api.zh.md
@@ -79,8 +79,8 @@ curl -c cookies.txt -H "Content-Type: application/json" \
代理设置为两个独立开关共享一个可选的显式地址;修改即时生效(对新发起的连接与新派生的子进程),无需重启:
- `proxyForApp`(「应用程序使用代理」,默认开)治理服务端自身出网(LLM 请求、更新检查、图片抓取):开且填写了 `proxyUrl` → http 与 https 流量都走该地址,**优先于代理环境变量**——无需配置任何环境变量;开但未填地址 → 遵循 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 环境变量(大小写并存);关 → 一律直连。
-- `proxyForAgent`(「Agent 环境使用代理」,默认开)治理 Agent 命令子进程环境:开且填写了 `proxyUrl` → 注入 `HTTP_PROXY` / `HTTPS_PROXY`(含小写拼写)为该地址并附合并后的 NO_PROXY,覆盖继承值;开但未填地址 → 宿主环境原样透传;关 → 剥除代理变量(NO_PROXY 保留)。
-- `proxyUrl`(默认 null = 跟随环境变量)即两者共享的显式地址。PUT 校验:先 trim;空串或 null 即清除地址;接受 `http://主机[:端口]`、`https://主机[:端口]` 与裸 `主机[:端口]`(规范化为 `http://主机[:端口]`——只存储规范化后的值,响应回显存储形态);其余一律 `400`,错误码 `invalid_proxy_url`,且被拒绝的 PUT 不写入任何字段。
+- `proxyForAgent`(「Agent 环境使用代理」,默认开)治理 Agent 命令子进程环境:开且填写了 `proxyUrl` → 注入 `HTTP_PROXY` / `HTTPS_PROXY`(含小写拼写)为该地址并附合并后的 NO_PROXY,覆盖继承值(`socks5://` 地址原样注入——各工具对这些变量中的 SOCKS URL 支持程度不一);开但未填地址 → 宿主环境原样透传;关 → 剥除代理变量(NO_PROXY 保留)。
+- `proxyUrl`(默认 null = 跟随环境变量)即两者共享的显式地址。PUT 校验:先 trim;空串或 null 即清除地址;接受 undici dispatcher 认可的代理 URL——`http://`、`https://` 与(undici 实验性支持的)`socks5://`/`socks://` 地址,允许携带凭据——以及裸 `主机[:端口]`(规范化为 `http://主机[:端口]`);只存储规范化后的值,响应回显存储形态。其余(无法解析,或 undici 拒绝的协议如 `socks4://`)一律 `400`,错误码 `invalid_proxy_url`,且被拒绝的 PUT 不写入任何字段。
任一开启状态下生效的 NO_PROXY 恒包含 `localhost,127.0.0.1,::1`(回环不代理)。
diff --git a/packages/docs/content/web-app.en.md b/packages/docs/content/web-app.en.md
index 02542533..1d293ef2 100644
--- a/packages/docs/content/web-app.en.md
+++ b/packages/docs/content/web-app.en.md
@@ -23,7 +23,7 @@ penguin web
# open http://127.0.0.1:7364
```
-The initial account is `admin`; its initial password (of the form `penguin-1234`) is printed in the server startup output — as a framed notice on every start — until it is changed. There is no self-registration: accounts are created by an admin on the user-management page, and every new user automatically gets an independent initial Project named `<userId>-default_project`. While the initial password is still in use, a banner prompts the user to change it.
+The initial account is `admin`; its initial password (of the form `penguin-1234`) is printed in the server startup output — as a framed notice on every start — until it is changed. There is no self-registration: accounts are created by an admin on the user-management page, and every new user automatically gets an independent initial Project named `<userId>-default_project`. While the initial password is still in use, a banner prompts the user to change it. A forgotten password is reset by the admin on the user-management page; a forgotten **admin** password is reset offline with `penguin server reset-admin-password` (server stopped), which issues a fresh initial password.
Logins persist for 7 days with sliding renewal; an admin password reset invalidates all of that user's login sessions.
diff --git a/packages/docs/content/web-app.zh.md b/packages/docs/content/web-app.zh.md
index 0b1baedd..086c2870 100644
--- a/packages/docs/content/web-app.zh.md
+++ b/packages/docs/content/web-app.zh.md
@@ -23,7 +23,7 @@ penguin web
# 打开 http://127.0.0.1:7364
```
-初始账号为 `admin`,初始密码(形如 `penguin-1234`)在改掉之前每次启动服务端都会以边框提示打印。系统不开放自助注册:账号由管理员在用户管理页创建;每个新用户会自动获得一个独立的初始 Project,命名为 `<userId>-default_project`。仍在使用初始密码时,页面会以横幅提示尽快修改。
+初始账号为 `admin`,初始密码(形如 `penguin-1234`)在改掉之前每次启动服务端都会以边框提示打印。系统不开放自助注册:账号由管理员在用户管理页创建;每个新用户会自动获得一个独立的初始 Project,命名为 `<userId>-default_project`。仍在使用初始密码时,页面会以横幅提示尽快修改。用户忘记密码由管理员在用户管理页重置;**管理员**自己忘记密码时,停止服务后执行 `penguin server reset-admin-password` 离线重置为新的初始密码。
登录状态保持 7 天(滑动续期);管理员重置密码会使该用户的全部登录会话失效。
diff --git a/packages/server/package.json b/packages/server/package.json
index ff034fe3..6dd2a540 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -26,6 +26,10 @@
"types": "./dist/initial-password.d.ts",
"import": "./dist/initial-password.js"
},
+ "./reset-admin-password": {
+ "types": "./dist/reset-admin-password.d.ts",
+ "import": "./dist/reset-admin-password.js"
+ },
"./hmr/manifest": {
"types": "./dist/hmr/manifest.d.ts",
"import": "./dist/hmr/manifest.js"
diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.ts
index 6ad5f1cb..1b421e38 100644
--- a/packages/server/src/api/types.ts
+++ b/packages/server/src/api/types.ts
@@ -144,9 +144,9 @@ export interface ServerSettings {
*/
proxyForAgent: boolean;
/**
- * The shared explicit proxy address (canonical `http(s)://host[:port]`), or null =
- * follow the proxy environment variables. When set it takes precedence over
- * HTTP_PROXY / HTTPS_PROXY wherever the owning switch is on.
+ * The shared explicit proxy address (a canonical URL — http(s):// or socks5:// /
+ * socks://), or null = follow the proxy environment variables. When set it takes
+ * precedence over HTTP_PROXY / HTTPS_PROXY wherever the owning switch is on.
*/
proxyUrl: string | null;
}
@@ -160,10 +160,11 @@ export interface ServerSettingsUpdateRequest {
proxyForApp?: boolean;
proxyForAgent?: boolean;
/**
- * New proxy address. Accepted forms: `http://host[:port]`, `https://host[:port]`, or
- * bare `host[:port]` (normalized to `http://…` — only normalized values are stored,
- * and the response echoes the stored form). Empty/whitespace-only or null clears the
- * address (follow the environment variables); anything else is 400 `invalid_proxy_url`.
+ * New proxy address. Accepted forms: any proxy URL undici's dispatcher takes —
+ * `http://`, `https://`, `socks5://` / `socks://`, credentials allowed — or bare
+ * `host[:port]` (normalized to `http://…`; only normalized values are stored, and the
+ * response echoes the stored form). Empty/whitespace-only or null clears the address
+ * (follow the environment variables); anything else is 400 `invalid_proxy_url`.
*/
proxyUrl?: string | null;
}
diff --git a/packages/server/src/http/routes/admin-settings.ts b/packages/server/src/http/routes/admin-settings.ts
index e8941092..1a0916a6 100644
--- a/packages/server/src/http/routes/admin-settings.ts
+++ b/packages/server/src/http/routes/admin-settings.ts
@@ -32,7 +32,7 @@ function parseProxyUrl(value: unknown): string | null {
throw new HttpError(
400,
"invalid_proxy_url",
- "proxyUrl must be http://host[:port], https://host[:port], or host[:port] (empty or null clears it).",
+ "proxyUrl must be a proxy URL undici supports — http(s)://host[:port] or socks5://host[:port] — or bare host[:port] (empty or null clears it).",
);
}
diff --git a/packages/server/src/net/proxy.ts b/packages/server/src/net/proxy.ts
index 75fca263..f5fa4003 100644
--- a/packages/server/src/net/proxy.ts
+++ b/packages/server/src/net/proxy.ts
@@ -20,7 +20,10 @@
* BEFORE the environment (verified against undici 7.29's constructor:
* `httpProxy ?? process.env.http_proxy ?? process.env.HTTP_PROXY`), so the explicit
* address governs both http and https traffic regardless of ambient env, while the
- * merged NO_PROXY keeps working through the same `noProxy` option.
+ * merged NO_PROXY keeps working through the same `noProxy` option. The pinned
+ * address may be a socks5:// / socks:// URL: undici's ProxyAgent (which
+ * EnvHttpProxyAgent builds per address) tunnels through SOCKS5 since 7.29
+ * (experimental; the startup script disables the ExperimentalWarning).
*
* The loopback merge is load-bearing in every state: the CLI's readiness probe
* (`penguin web` imports the server in-process and polls its own root path), SSE, and
@@ -35,7 +38,13 @@
* in core (CommandSessionManager, threaded through the session loader as a
* ProxyEnvPolicy getter), not here.
*/
-import { Agent, EnvHttpProxyAgent, fetch as undiciFetch, setGlobalDispatcher } from "undici";
+import {
+ Agent,
+ EnvHttpProxyAgent,
+ ProxyAgent,
+ fetch as undiciFetch,
+ setGlobalDispatcher,
+} from "undici";
import type { Dispatcher } from "undici";
/** Loopback names every effective NO_PROXY must contain (see module doc). */
@@ -68,11 +77,14 @@ export function mergedNoProxy(env: NodeJS.ProcessEnv = process.env): string {
/**
* Normalizes a proxy address to its canonical URL, or null when it is not acceptable.
- * Accepted forms: `http://host[:port]`, `https://host[:port]`, and the bare
- * `host[:port]` / `host` shorthand (normalized to `http://…`). Anything else — other
- * schemes (the dispatcher speaks only HTTP(S) proxies; a socks:// URL would break every
- * server fetch, see os-proxy.ts for the same rule), credentials, paths, queries — is
- * rejected rather than stored: server_settings only ever holds normalized values.
+ * Accepted forms: any proxy URL undici's dispatcher takes — `http://`, `https://` and
+ * the (experimental in undici) `socks5://` / `socks://` schemes, credentials included —
+ * plus the bare `host[:port]` / `host` shorthand (normalized to `http://…`). Beyond
+ * URL-parseability the gate is acceptance by undici itself rather than a scheme list
+ * duplicated here, and it is load-bearing: buildProxyDispatcher constructs a ProxyAgent
+ * from the stored value at every startup, and undici throws synchronously on schemes it
+ * cannot speak (socks4, ftp, …) — persisting such a value would keep the server from
+ * ever booting again. server_settings only ever holds normalized values.
*/
export function normalizeProxyUrl(raw: string): string | null {
const trimmed = raw.trim();
@@ -86,15 +98,21 @@ export function normalizeProxyUrl(raw: string): string | null {
} catch {
return null;
}
- if (url.protocol !== "http:" && url.protocol !== "https:") return null;
- if (url.hostname === "" || url.username !== "" || url.password !== "") return null;
- // A proxy address is host-only; the parser's bare "/" (its normal form for an absent
- // path) is tolerated, an actual path/query/fragment means this was not a proxy address.
- if ((url.pathname !== "/" && url.pathname !== "") || url.search !== "" || url.hash !== "") {
+ if (url.hostname === "") return null;
+ // href is the canonical form (lowercased scheme, default ports dropped) that — unlike
+ // origin, which drops credentials and reads "null" for non-special schemes like
+ // socks — keeps the whole address intact; only the parser's bare "/" (its normal form
+ // for an absent path) is trimmed off.
+ const normalized =
+ url.pathname === "/" && url.search === "" && url.hash === "" ? url.href.slice(0, -1) : url.href;
+ try {
+ // Acceptance probe: the same constructor EnvHttpProxyAgent runs per pinned address.
+ // An idle agent's close resolves immediately; nothing was connected.
+ void new ProxyAgent({ uri: normalized }).close();
+ } catch {
return null;
}
- // origin is the canonical form: lowercased scheme/host, default ports dropped.
- return url.origin;
+ return normalized;
}
/** The EnvHttpProxyAgent option subset this module assembles (undici's Options type is not re-exported cleanly). */
diff --git a/packages/server/src/reset-admin-password.ts b/packages/server/src/reset-admin-password.ts
new file mode 100644
index 00000000..b23271a2
--- /dev/null
+++ b/packages/server/src/reset-admin-password.ts
@@ -0,0 +1,69 @@
+/**
+ * Offline admin-password reset — the rescue path when the Web admin password is
+ * forgotten (`penguin server reset-admin-password`).
+ *
+ * The admin can reset every OTHER user from the user-management page, but nobody can
+ * reset the admin itself once its password is lost: the plaintext file in the data root
+ * only survives while the password is still the initial one. This module closes that
+ * gap from the machine that owns the data root: it re-arms the whole initial-password
+ * machinery — a fresh `penguin-<4 digits>` password flagged password_is_initial, the
+ * plaintext stored via initial-password.ts so every server start re-prints the framed
+ * reminder until the password is changed, and all of the admin's login sessions
+ * cleared (matching an admin-initiated reset).
+ *
+ * web.db is single-process / single-writer (see db/database.ts and lock.ts), so the
+ * reset refuses while a live server owns the root: the caller tells the user to stop it
+ * first. Requiring local filesystem access is the authorization model — whoever can run
+ * this already owns the SQLite database sitting next to the file it writes.
+ *
+ * Published as `@prismshadow/penguin-server/reset-admin-password` (side-effect-free,
+ * like ./lock) so the CLI can run the reset without importing the package entry, which
+ * starts listening.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { hashPassword } from "./auth/password.js";
+import { ADMIN_USER_ID, generateInitialAdminPassword } from "./auth/service.js";
+import { openDatabase } from "./db/database.js";
+import { AuthSessionsRepo } from "./db/repos/auth-sessions.js";
+import { UsersRepo } from "./db/repos/users.js";
+import { storeInitialAdminPassword } from "./initial-password.js";
+import { liveServerLock } from "./lock.js";
+import type { ServerLock } from "./lock.js";
+
+export type ResetAdminPasswordResult =
+ /** Refused: a live server owns this data root (stop it first — web.db is single-writer). */
+ | { outcome: "server_running"; lock: ServerLock }
+ /** Nothing to reset: the root has no Web database (the server has never run here). */
+ | { outcome: "no_database"; dbPath: string }
+ /** Nothing to reset: the database exists but the admin was never seeded. */
+ | { outcome: "no_admin" }
+ | { outcome: "reset"; password: string };
+
+/**
+ * Resets the built-in admin to a fresh initial password. `dbPath` defaults to the
+ * root's `web.db`; callers honoring PENGUIN_WEB_DB pass the resolved path (the
+ * plaintext reminder file always lives in `root`, matching the server's own layout).
+ */
+export async function resetAdminPassword(
+ root: string,
+ dbPath: string = path.join(root, "web.db"),
+): Promise<ResetAdminPasswordResult> {
+ const lock = await liveServerLock(root);
+ if (lock !== null) return { outcome: "server_running", lock };
+ // Existence check before openDatabase, which would otherwise CREATE an empty database
+ // (and the root directory) on a root the server has never used.
+ if (!fs.existsSync(dbPath)) return { outcome: "no_database", dbPath };
+ const db = openDatabase(dbPath);
+ try {
+ const users = new UsersRepo(db);
+ if (users.findById(ADMIN_USER_ID) === null) return { outcome: "no_admin" };
+ const password = generateInitialAdminPassword();
+ users.updatePassword(ADMIN_USER_ID, await hashPassword(password), true);
+ new AuthSessionsRepo(db).deleteByUser(ADMIN_USER_ID);
+ storeInitialAdminPassword(root, password);
+ return { outcome: "reset", password };
+ } finally {
+ db.close();
+ }
+}
diff --git a/packages/server/test/admin-settings.test.ts b/packages/server/test/admin-settings.test.ts
index 9ae3f616..51b65ab0 100644
--- a/packages/server/test/admin-settings.test.ts
+++ b/packages/server/test/admin-settings.test.ts
@@ -112,11 +112,18 @@ describe("admin server settings", () => {
expect(((await https.json()) as ServerSettingsResponse).settings.proxyUrl).toBe(
"https://proxy.corp.example:3128",
);
+ // socks5 rides through to undici's dispatcher untouched.
+ const socks = await putProxyUrl("socks5://proxy.corp.example:1080");
+ expect(socks.status).toBe(200);
+ expect(((await socks.json()) as ServerSettingsResponse).settings.proxyUrl).toBe(
+ "socks5://proxy.corp.example:1080",
+ );
});
it("PUT rejects a bad proxy address with invalid_proxy_url and stores nothing", async () => {
await putProxyUrl("http://proxy.corp.example:8080");
- for (const bad of ["socks5://proxy.corp.example:1080", "not a proxy", 42]) {
+ // socks4 parses as a URL but undici's dispatcher refuses to construct from it.
+ for (const bad of ["socks4://proxy.corp.example:1080", "not a proxy", 42]) {
const res = await putProxyUrl(bad);
expect(res.status).toBe(400);
const body = (await res.json()) as { error: { code: string } };
diff --git a/packages/server/test/proxy.test.ts b/packages/server/test/proxy.test.ts
index b34461ef..37bef008 100644
--- a/packages/server/test/proxy.test.ts
+++ b/packages/server/test/proxy.test.ts
@@ -6,6 +6,7 @@
* replacement) runs only in the production entry.
*/
import http from "node:http";
+import net from "node:net";
import type { AddressInfo } from "node:net";
import { describe, expect, it } from "vitest";
import { Agent, EnvHttpProxyAgent, fetch as undiciFetch } from "undici";
@@ -79,17 +80,33 @@ describe("normalizeProxyUrl", () => {
expect(normalizeProxyUrl("http://[::1]:8080")).toBe("http://[::1]:8080");
});
- it("rejects everything that is not an http(s) host[:port]", () => {
- // Other schemes: the dispatcher speaks only HTTP(S) proxies.
- expect(normalizeProxyUrl("socks5://proxy.corp.example:1080")).toBeNull();
+ it("passes socks5/socks addresses through to undici", () => {
+ expect(normalizeProxyUrl("socks5://proxy.corp.example:1080")).toBe(
+ "socks5://proxy.corp.example:1080",
+ );
+ expect(normalizeProxyUrl("socks://127.0.0.1:1080")).toBe("socks://127.0.0.1:1080");
+ // The parser's bare "/" is trimmed for non-special schemes too.
+ expect(normalizeProxyUrl("socks5://proxy.corp.example:1080/")).toBe(
+ "socks5://proxy.corp.example:1080",
+ );
+ });
+
+ it("keeps credentials intact (SOCKS and proxy-authorization auth ride the URL)", () => {
+ expect(normalizeProxyUrl("socks5://user:[email protected]:1080")).toBe(
+ "socks5://user:[email protected]:1080",
+ );
+ expect(normalizeProxyUrl("http://user:[email protected]:8080")).toBe(
+ "http://user:[email protected]:8080",
+ );
+ });
+
+ it("rejects what undici's dispatcher cannot construct, and unparseable shapes", () => {
+ // Schemes undici's ProxyAgent throws on — storing one would crash the next startup.
+ expect(normalizeProxyUrl("socks4://proxy.corp.example:1080")).toBeNull();
expect(normalizeProxyUrl("ftp://proxy.corp.example")).toBeNull();
- // Credentials, paths, queries, fragments: a proxy address is host-only.
- expect(normalizeProxyUrl("http://user:[email protected]:8080")).toBeNull();
- expect(normalizeProxyUrl("http://proxy.corp.example:8080/path")).toBeNull();
- expect(normalizeProxyUrl("http://proxy.corp.example:8080?x=1")).toBeNull();
- expect(normalizeProxyUrl("http://proxy.corp.example:8080#frag")).toBeNull();
// Unparseable shapes.
expect(normalizeProxyUrl("http://")).toBeNull();
+ expect(normalizeProxyUrl("socks5://")).toBeNull();
expect(normalizeProxyUrl("not a proxy")).toBeNull();
expect(normalizeProxyUrl("proxy.corp.example:port")).toBeNull();
expect(normalizeProxyUrl("")).toBeNull();
@@ -187,4 +204,53 @@ describe("buildProxyDispatcher", () => {
direct.close();
}
});
+
+ it("explicit socks5 address: traffic tunnels through the SOCKS proxy", async () => {
+ // A minimal no-auth SOCKS5 server that accepts CONNECT and then plays the tunneled
+ // origin itself — a request to an unresolvable name can only succeed through it.
+ const targets: string[] = [];
+ const proxy = net.createServer((socket) => {
+ let stage: "greeting" | "request" | "tunnel" = "greeting";
+ let buffered = Buffer.alloc(0);
+ socket.on("data", (chunk: Buffer) => {
+ buffered = Buffer.concat([buffered, chunk]);
+ if (stage === "greeting" && buffered.length >= 2 && buffered.length >= 2 + buffered[1]!) {
+ buffered = buffered.subarray(2 + buffered[1]!);
+ stage = "request";
+ socket.write(Buffer.from([0x05, 0x00])); // no-auth accepted
+ }
+ if (stage === "request" && buffered.length >= 5 && buffered[3] === 0x03) {
+ const nameLen = buffered[4]!;
+ if (buffered.length < 5 + nameLen + 2) return;
+ const name = buffered.subarray(5, 5 + nameLen).toString("utf8");
+ const port = buffered.readUInt16BE(5 + nameLen);
+ targets.push(`${name}:${port}`);
+ buffered = buffered.subarray(5 + nameLen + 2);
+ stage = "tunnel";
+ // Success reply, bound address 0.0.0.0:0.
+ socket.write(Buffer.from([0x05, 0x00, 0x00, 0x01, 0, 0, 0, 0, 0, 0]));
+ }
+ if (stage === "tunnel" && buffered.toString("utf8").includes("\r\n\r\n")) {
+ socket.end(
+ "HTTP/1.1 200 OK\r\ncontent-type: text/plain\r\ncontent-length: 9\r\nconnection: close\r\n\r\nvia-socks",
+ );
+ }
+ });
+ });
+ const proxyPort = await new Promise<number>((resolve) => {
+ proxy.listen(0, "127.0.0.1", () => resolve((proxy.address() as AddressInfo).port));
+ });
+ const dispatcher = buildProxyDispatcher(
+ { proxyForApp: true, proxyUrl: `socks5://127.0.0.1:${proxyPort}` },
+ {},
+ );
+ try {
+ const res = await undiciFetch("http://proxied.invalid/x", { dispatcher });
+ expect(await res.text()).toBe("via-socks");
+ expect(targets).toEqual(["proxied.invalid:80"]);
+ } finally {
+ await dispatcher.close();
+ proxy.close();
+ }
+ });
});
diff --git a/packages/server/test/reset-admin-password.test.ts b/packages/server/test/reset-admin-password.test.ts
new file mode 100644
index 00000000..c4f2e38a
--- /dev/null
+++ b/packages/server/test/reset-admin-password.test.ts
@@ -0,0 +1,141 @@
+/**
+ * Offline admin-password reset: the full rescue round-trip (fresh initial password,
+ * re-armed flag, cleared admin sessions, stored plaintext), the live-server refusal,
+ * and the nothing-to-reset outcomes (no database — none created as a side effect —
+ * and an unseeded database).
+ */
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { hashPassword, verifyPassword } from "../src/auth/password.js";
+import { ADMIN_USER_ID } from "../src/auth/service.js";
+import { openDatabase } from "../src/db/database.js";
+import { AuthSessionsRepo } from "../src/db/repos/auth-sessions.js";
+import { UsersRepo } from "../src/db/repos/users.js";
+import { readInitialAdminPassword } from "../src/initial-password.js";
+import { acquireServerLock } from "../src/lock.js";
+import { resetAdminPassword } from "../src/reset-admin-password.js";
+import { makeTempRoot } from "./helpers.js";
+
+describe("resetAdminPassword", () => {
+ const roots: string[] = [];
+ afterEach(async () => {
+ for (const root of roots.splice(0)) {
+ await fs.promises.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ async function tempRoot(): Promise<string> {
+ const root = await makeTempRoot();
+ roots.push(root);
+ return root;
+ }
+
+ /** Seeds a web.db with the admin (password "old-password-1", already changed) plus a bystander user, each holding one login session. */
+ async function seedDatabase(root: string): Promise<string> {
+ const dbPath = path.join(root, "web.db");
+ const db = openDatabase(dbPath);
+ const users = new UsersRepo(db);
+ const sessions = new AuthSessionsRepo(db);
+ const createdAt = "2026-01-01T00:00:00.000Z";
+ const expiresAt = "2100-01-01T00:00:00.000Z";
+ users.insert({
+ userId: ADMIN_USER_ID,
+ passwordHash: await hashPassword("old-password-1"),
+ isAdmin: true,
+ passwordIsInitial: false,
+ createdAt,
+ });
+ users.insert({
+ userId: "alice",
+ passwordHash: await hashPassword("alice-password-1"),
+ isAdmin: false,
+ passwordIsInitial: false,
+ createdAt,
+ });
+ sessions.insert({
+ tokenHash: "admin-token",
+ userId: ADMIN_USER_ID,
+ createdAt,
+ expiresAt,
+ via: "password",
+ });
+ sessions.insert({
+ tokenHash: "alice-token",
+ userId: "alice",
+ createdAt,
+ expiresAt,
+ via: "password",
+ });
+ db.close();
+ return dbPath;
+ }
+
+ it("re-arms the initial-password machinery: fresh password, flag, cleared sessions, stored plaintext", async () => {
+ const root = await tempRoot();
+ const dbPath = await seedDatabase(root);
+
+ const result = await resetAdminPassword(root);
+ expect(result.outcome).toBe("reset");
+ const password = (result as { outcome: "reset"; password: string }).password;
+ expect(password).toMatch(/^penguin-\d{4}$/);
+ // The plaintext lands in the data root, so every server start re-prints the notice.
+ expect(readInitialAdminPassword(root)).toBe(password);
+
+ const db = openDatabase(dbPath);
+ try {
+ const admin = new UsersRepo(db).findById(ADMIN_USER_ID);
+ expect(admin?.passwordIsInitial).toBe(true);
+ expect(await verifyPassword(password, admin!.passwordHash)).toBe(true);
+ expect(await verifyPassword("old-password-1", admin!.passwordHash)).toBe(false);
+ // Admin sessions cleared (as an admin-initiated reset would); bystanders keep theirs.
+ const sessions = new AuthSessionsRepo(db);
+ expect(sessions.findByTokenHash("admin-token")).toBeNull();
+ expect(sessions.findByTokenHash("alice-token")).not.toBeNull();
+ const alice = new UsersRepo(db).findById("alice");
+ expect(await verifyPassword("alice-password-1", alice!.passwordHash)).toBe(true);
+ } finally {
+ db.close();
+ }
+ });
+
+ it("refuses while a live server owns the data root and changes nothing", async () => {
+ const root = await tempRoot();
+ const dbPath = await seedDatabase(root);
+ const srv = net.createServer();
+ const port = await new Promise<number>((resolve) => {
+ srv.listen(0, "127.0.0.1", () => resolve((srv.address() as net.AddressInfo).port));
+ });
+ try {
+ acquireServerLock(root, { pid: process.pid, port, startedAt: "2026-01-01T00:00:00Z" });
+ const result = await resetAdminPassword(root);
+ expect(result).toMatchObject({ outcome: "server_running", lock: { port } });
+ const db = openDatabase(dbPath);
+ try {
+ const admin = new UsersRepo(db).findById(ADMIN_USER_ID);
+ expect(await verifyPassword("old-password-1", admin!.passwordHash)).toBe(true);
+ } finally {
+ db.close();
+ }
+ expect(readInitialAdminPassword(root)).toBeNull();
+ } finally {
+ await new Promise<void>((resolve) => srv.close(() => resolve()));
+ }
+ });
+
+ it("reports a missing database without creating one", async () => {
+ const root = await tempRoot();
+ const dbPath = path.join(root, "web.db");
+ const result = await resetAdminPassword(root);
+ expect(result).toEqual({ outcome: "no_database", dbPath });
+ expect(fs.existsSync(dbPath)).toBe(false);
+ });
+
+ it("reports an unseeded database (admin never created)", async () => {
+ const root = await tempRoot();
+ const db = openDatabase(path.join(root, "web.db"));
+ db.close();
+ expect(await resetAdminPassword(root)).toEqual({ outcome: "no_admin" });
+ });
+});
diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.ts
index cc042c37..ead83e94 100644
--- a/packages/server/tsup.config.ts
+++ b/packages/server/tsup.config.ts
@@ -2,9 +2,10 @@ import { defineConfig } from "tsup";
export default defineConfig({
// Explicitly name entries to preserve subpath exports: "./api", "./lock",
- // "./initial-password" (lock and initial-password are side-effect-free for CLI
- // pre-checks); "./hmr/manifest" is the host-less harness.json reader the CLI's thin
- // loader resolves the current cli bundle through. There is deliberately no
+ // "./initial-password" and "./reset-admin-password" (lock, initial-password and
+ // reset-admin-password are side-effect-free for CLI pre-checks and the offline
+ // admin-password rescue); "./hmr/manifest" is the host-less harness.json reader the
+ // CLI's thin loader resolves the current cli bundle through. There is deliberately no
// "./platform" subpath: src/platform/entry.ts (this package's platform artifact
// compile target — see its own module doc) is compiled straight from source by
// esbuild in scripts/deploy.mjs, never through this package's published dist,
@@ -14,6 +15,7 @@ export default defineConfig({
"api/types": "src/api/types.ts",
lock: "src/lock.ts",
"initial-password": "src/initial-password.ts",
+ "reset-admin-password": "src/reset-admin-password.ts",
"hmr/manifest": "src/hmr/manifest.ts",
},
format: ["esm"],
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 16071fff..6d9e863e 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -147,6 +147,9 @@ export const en: Strings = {
admin: "Admin",
defaultAdminNote:
"First run: sign in as the built-in admin “admin” with the initial password printed in the server startup output (looks like penguin-1234), then change it soon",
+ /** Login footer line 2: the offline rescue for a forgotten admin password (other users ask the admin instead). */
+ forgotAdminNote:
+ "Forgot the admin password? Stop the server and run penguin server reset-admin-password to issue a fresh initial one",
},
account: {
@@ -1475,7 +1478,7 @@ Scenarios:
version_conflict: "The snapshot's version is not newer than the current one.",
invalid_title: "The title is invalid.",
invalid_proxy_url:
- "Invalid proxy address — use http://host[:port], https://host[:port], or host[:port].",
+ "Invalid proxy address — use an http(s):// or socks5:// proxy URL, or host[:port].",
invalid_trace: "This file is not a valid Trace file.",
trace_session_exists:
"This agent already has a Session with that id; a duplicate Trace cannot be imported.",
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index e501fc92..c41b75fe 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -147,6 +147,9 @@ export const zh = {
admin: "管理员",
defaultAdminNote:
"首次使用请以内置管理员 admin 登录,初始密码在服务端首次启动时打印(形如 penguin-1234),登录后请尽快修改密码",
+ /** Login footer line 2: the offline rescue for a forgotten admin password (other users ask the admin instead). */
+ forgotAdminNote:
+ "忘记管理员密码时,停止服务后执行 penguin server reset-admin-password 重置为新的初始密码",
},
account: {
@@ -1425,8 +1428,7 @@ Benchmark:
task_in_progress: "该 Session 已有任务在运行。",
version_conflict: "快照版本不高于当前版本。",
invalid_title: "标题无效。",
- invalid_proxy_url:
- "代理地址无效:应为 http://主机[:端口]、https://主机[:端口] 或 主机[:端口]。",
+ invalid_proxy_url: "代理地址无效:应为 http(s):// 或 socks5:// 代理 URL,或 主机[:端口]。",
invalid_trace: "该文件不是有效的 Trace 文件。",
trace_session_exists: "该 Agent 已存在同名 Session,无法导入重复的 Trace。",
},
diff --git a/packages/web/src/pages/login.tsx b/packages/web/src/pages/login.tsx
index 81c9098e..a0147dfe 100644
--- a/packages/web/src/pages/login.tsx
+++ b/packages/web/src/pages/login.tsx
@@ -135,6 +135,9 @@ export function LoginPage() {
<p className="mt-4 text-center text-xs text-gray-400 dark:text-gray-500">
{S.auth.defaultAdminNote}
</p>
+ <p className="mt-1.5 text-center text-xs text-gray-400 dark:text-gray-500">
+ {S.auth.forgotAdminNote}
+ </p>
</div>
</div>
</div>