Merge pull request 'Implement U4 one-time login keys and OpenExisting (Backend pin)' (#428) from feature/svc-deploy-u4-login-key into main

Reviewed-on: https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/428

docs/svc-deploy/u1-instance-account-binding.md

@@ -0,0 +1,78 @@
+# U1 实例—账户绑定补齐（规格 v0.1）
+
+状态：设计候选，随主提案 r1 评审。主记录：`modules/documents/docs/proposals/2026-10-12-svc-unified-deploy-and-login-key.md` §7 U1。  
+前置：恢复方案 recovery U1 已合入 main（Dev #415）——`docs/recovery/u1-identity-manifest.md`、`scripts/svc_manifest.py`、启动身份校验与 `svc init`。  
+本增量**不重做** manifest 层；只补齐账户操作与安装入口对既有身份合同的消费缺口。
+
+基线（写作时 SELF）：Dev `af9c2de`（含 recovery U1）。实施前以任务 `task-sync` 后 SHA 为准。业务实施 **NOT_RUN**。
+
+## 1. 目标与非目标
+
+**目标：** 同一实例的启停、升级、开户、签发/撤销登录 Key 始终命中同一存储与数据根；缺失、不符或锁不可用时拒绝；为后续 `install` / doctor 提供稳定的实例解析入口。
+
+非目标：不实现二进制下载（U2）、不实现 doctor/env prepare 全量（U3）、不实现一次性 Key 语义（U4）、不改登录页（U5）。
+
+## 2. 不变量（相对 recovery U1）
+
+| ID | 不变量 | 相对 #415 |
+|---|---|---|
+| B1 | 账户 CLI 只接受「实例名 → manifest 解析出的 data_root / db / secrets 引用」 | 新增消费方 |
+| B2 | 禁止回落默认 `./data` 或未声明 DSN | 新增硬拒绝 |
+| B3 | OpenExisting：目标不存在则失败；可选禁止自动 migrate | Backend 新增打开模式 |
+| B4 | 无 `flock` / 锁获取失败 → 拒绝冲突操作（deploy/start/stop/user/*） | 收紧现状「直通」 |
+| B5 | `install` / 兼容 `--from` 写入同一 manifest 身份字段，不另起配置根 | 入口骨架 |
+
+## 3. 触点与文件
+
+| 文件 | 变更 |
+|---|---|
+| `scripts/svc.sh` | `user` 子命令骨架：解析 `ENV_NAME` → 读 manifest/`svc_manifest.py` → 组装 `--data`/`AGENT_SYSTEM_DSN`/`--open-existing` 调 `$ENV_BIN`；锁检查收紧；`install` 可先做 dry-run 计划打印（完整 binary/source 属 U2） |
+| `scripts/svc_manifest.py` | 如需：导出「账户操作所需最小字段」查询（data_root、db mode/ref、auth）；不改 schema=1 语义 |
+| `modules/backend/cmd/agent-system/main.go` | `user` 子命令增加 `--open-existing`（或全局 store 打开标志）；缺库/缺目录失败 |
+| `modules/backend/internal/store/store.go` | `OpenExistingSQLite` / PG 等价：不 `MkdirAll` 创建新数据根；可选 `MigrateMode=requireCompatible\|forbid` |
+| `tests/test_svc_identity.py` 或新 `tests/test_svc_user_binding.py` | 错误 data、缺 manifest、无 flock 拒绝；正确绑定命中 |
+
+## 4. OpenExisting 合同
+
+```
+OpenExisting(path|dsn, opts):
+  if storage path/parent missing → error (do not create)
+  if SQLite file missing → error
+  open DB
+  if opts.migrate == forbid → read schema version only; mismatch → error
+  if opts.migrate == requireCompatible → existing migrate(); reject unknown newer schema (keep current migrate gate)
+  never create empty business DB as side effect of account recovery
+```
+
+CLI 默认：账户运维命令使用 `OpenExisting` + `requireCompatible`。  
+`svc init` / 首次服务启动仍走现有 Open（可创建）路径，与 recovery U1 一致。
+
+## 5. 锁合同
+
+- 复用 `runtime/<name>/.start.lock`。
+- `flock` 不可用或超时：退出非 0，写 hist_event，**不得**执行 deploy/start/stop/user。
+- 账户操作与生命周期互斥（同一锁）。
+
+## 6. 验收用例（U1）
+
+| # | 场景 | 判据 |
+|---|---|---|
+| T1 | 实例有合法 manifest；`svc <name> user list` | 使用 manifest data_root/DSN；列表与该库一致 |
+| T2 | 故意传错误 `--data` 或未绑定实例 | 拒绝；不创建目录；不写默认 `./data` |
+| T3 | 删除 data 根后再 user create | OpenExisting 失败；无新空库 |
+| T4 | 隐藏 `flock`（PATH 去掉）后 deploy/user | 拒绝；旧服务若在跑则仍在 |
+| T5 | recovery U1 既有 T1–T6 回归 | 全绿（不破坏 identity） |
+
+真实 PG：绑定 dbref 与 marker 一致才允许 user 操作；缺环境标 NOT_RUN。
+
+## 7. 完成门槛与依赖
+
+- 完成条件见主提案 §7 U1 行。
+- 依赖：main 已含 recovery U1（#415）。
+- 被依赖：U4 CLI 签发、U5 `svc user` 接线、U2 `install` 写身份。
+
+## 8. 任务卡建议（待授权后 `task-start`）
+
+- 分支名：`feature/svc-deploy-u1-account-binding`
+- R0：与本提案合入后的 `origin/main`（或与 U4 兄弟共享批准时的同一 R0）
+- 交付模式：manual；实施需主提案阶段批准后再授权

docs/svc-deploy/u1-task-card-draft.md

@@ -0,0 +1,20 @@
+# 草稿：feature/svc-deploy-u1-account-binding 任务卡
+
+状态：**待授权**。主提案批准并获实施授权后，在共享主检出执行：
+
+```bash
+RECEIPT=/tmp/precheck-svc-deploy-u1.json CMD="make precheck" make evidence
+make task-start NAME=feature/svc-deploy-u1-account-binding PRECHECK_RECEIPT=/tmp/precheck-svc-deploy-u1.json
+```
+
+将本草稿字段拷入新卡并删除本文件或改为「已启动」链接。
+
+## 建议填写
+
+- 主记录：`modules/documents/docs/proposals/2026-10-12-svc-unified-deploy-and-login-key.md` r1 §7 U1
+- 规格：`docs/svc-deploy/u1-instance-account-binding.md` v0.1
+- 目标：账户 CLI 绑定实例 manifest；OpenExisting；无 flock 拒绝冲突操作；不破坏 recovery U1
+- 非目标：U2 下载、U3 doctor、U4 Key 语义、U5 页面
+- 兄弟任务：可与 `feature/svc-deploy-u4-login-key` 共用同一 R0
+- 验收：规格 §6 T1–T5；治理回归；真实 PG 缺环境 NOT_RUN
+- 启动授权：未授权（须主提案阶段批准 + 明确实施授权）

docs/svc-deploy/u4-one-time-login-key.md

@@ -0,0 +1,160 @@
+# U4 一次性登录凭据与认证限制（规格 v0.1）
+
+状态：已启动实施（Backend/Dev 分支 `feature/svc-deploy-u4-login-key`）。主记录：`modules/documents/docs/proposals/2026-10-12-svc-unified-deploy-and-login-key.md` §7 U4 / §8。  
+本增量在 **Backend**（及必要迁移/CLI）落地；Frontend 兑换与设密页属 **U5**，但 U4 须提供稳定 HTTP 合同供 U5 接线。
+
+基线：任务卡 R0；Backend 实现提交见 gitlink。真实 PG 缺环境标 NOT_RUN。
+
+## 1. 目标与非目标
+
+**目标：** 无初始密码开户与已有账户恢复均通过一次性登录 Key；Key 只能经专用接口原子兑换为「仅可设密」的短期会话；服务端拒绝受限会话与待改密会话访问业务 API；设密在同一事务内完成且成功后强制重新密码登录。
+
+非目标：不改长期 `api_keys` 的集成语义（除失陷显式撤销）；不实现 svc 接线与登录页（U5）；不做 doctor/部署（U1–U3）。
+
+## 2. 现状锚点（必须改掉的行为）
+
+| 现状 | 出处 | U4 动作 |
+|---|---|---|
+| CLI 省略密码 → `RandomPassword()` + 明文打印 | `app.CreateUserAccount` | 默认无密码 + 签发 activate Key；随机密码可保留为显式 `--password` / `--generate-password` |
+| `api_keys` 可重复使用、无 TTL | `store/auth.go` | **不改**长期 Key；新增独立表 |
+| Middleware 不看 `must_change` | `server/auth.go` | 统一拦截 |
+| `changePassword` 强制 `current` | `server/accounts.go` | 分型：受限会话走 set-initial / set-recovered |
+| `SetUserPassword` 总置 `must_change=1` | `store/auth.go` | 设密成功路径一次写清，避免半完成 |
+| Open 必 MkdirAll + migrate | `store/store.go` | 账户运维走 OpenExisting（与 U1 合同一致；可本增量先做 Backend API） |
+
+## 3. 数据模型
+
+### 3.1 `login_keys`（名称可微调，勿混入 `api_keys`）
+
+| 列 | 说明 |
+|---|---|
+| `id` | 稳定凭据编号（对外审计/撤销用，非明文） |
+| `owner` | 目标用户 |
+| `purpose` | `activate` \| `recover` |
+| `key_hash` | SHA-256（或更强）；明文前缀建议 `alk_`（activation/login key） |
+| `status` | `unused` \| `consumed` \| `revoked` \| `expired` |
+| `expires_at` | 默认 now+30m；签发时可配置（夹紧 5–120m） |
+| `consumed_at` | 可空 |
+| `created_at` / `created_by` | 审计（CLI 操作者或 `system`） |
+| `instance_id` | 可选；与部署身份关联时填写 |
+
+唯一性：同一明文只能对应一行；未使用 Key 可按 (owner, purpose) 允许多条，但签发新 Key 时建议撤销同 purpose 的未使用旧 Key（规格默认：**签发即撤销同 owner+purpose 的 unused**）。
+
+### 3.2 `users` 变更
+
+- `password_hash`：允许 NULL / 空，表示未设置。
+- 保留 `must_change_password`：用于「已有随机密码首登」迁移路径；无密码账户用「无 hash」+ activate 流，不依赖假密码。
+- 角色：首期仍映射 `is_admin`；API 可收 `role=admin|user`，未知角色 **拒绝**（不静默降级）。
+
+### 3.3 `sessions` 变更
+
+增加 `scope`（或等价）：`full` \| `set_password_only`。  
+受限会话 TTL 默认 10 分钟。  
+`CreateSession(owner, scope, ttl)`。
+
+## 4. CLI 合同
+
+```
+agent-system user create --owner <id> --role user|admin [--open-existing]
+  → 无 --password：password 未设置 + 同事务签发 activate Key；stdout 明文一次
+  → --password / --generate-password：兼容旧路径（must_change=1）
+
+agent-system user issue-login-key --owner <id> --purpose activate|recover [--ttl 30m] [--open-existing]
+  → 精确命中已有用户；不改 password_hash；不吊销 full 会话；不改业务数据
+  → recover 不删除重建
+
+agent-system user revoke-login-key --id <id> [--open-existing]
+agent-system user list   # 含是否已设密、未使用登录 Key 计数（无明文）
+```
+
+首次管理员：
+
+```
+agent-system user bootstrap-admin --owner <id> [--open-existing]
+```
+
+仅当：库已存在且 **无任何 users 行** 且 **无历史业务标记**（规格：至少 `projects`/`messages` 等核心表为空或实例 init marker 声明 fresh）。并发用事务/`UNIQUE` 保证单胜。有数据却无管理员 → **拒绝自动接管**，要求显式运维流程（本增量可只返回明确错误）。
+
+失陷恢复：
+
+```
+... issue-login-key --purpose recover --revoke-all-credentials
+```
+
+默认 **不**撤销长期 `api_keys`；加旗标才撤销全部 api_keys + 可选吊销 full 会话。
+
+## 5. HTTP 合同
+
+| 方法 | 路径 | 认证 | 行为 |
+|---|---|---|---|
+| POST | `/api/auth/login-key/redeem` | 无（body: `{ "key": "alk_..." }`） | 事务：校验 unused+未过期 → 条件更新 consumed → 建 `set_password_only` 会话 → 设 cookie → 提交 |
+| POST | `/api/auth/password` | session | `scope=full`：要求 `current`（现行为）；`scope=set_password_only`：忽略 current，要求 `next`+确认由客户端做，服务端校验强度 |
+| POST | `/api/auth/logout` | session | 允许受限会话 |
+| GET | `/api/me` | session | 允许受限会话；响应含 `sessionScope`、`mustChangePassword`、`passwordSet` |
+| 其他 `/api/*` | — | — | `set_password_only` **或** (`must_change` 且非上述白名单) → **403** |
+
+禁止：用 Bearer / `?key=` 提交一次性登录 Key；redeem 外任何路径接受 `alk_`。
+
+兑换并发：`UPDATE ... WHERE id=? AND status='unused' AND expires_at>now` 影响行数必须为 1；否则失败。消费后建会话失败 → **整事务回滚**（Key 仍为 unused）。
+
+设密成功事务（受限或兼容 must_change）：
+
+1. 写 password_hash  
+2. 清 must_change；标记已设密  
+3. 作废该 owner 全部 unused/本 purpose 登录 Key  
+4. 删除该 owner 全部会话（含当前受限会话）  
+5. 清 cookie / 不发新 full 会话  
+6. 响应指示 `reloginRequired: true`
+
+半完成态禁止：密码已变但旧 Key 仍 unused；或 Key 已 consumed 但无会话且密码未变（兑换回滚已覆盖后者）。
+
+## 6. 中间件伪代码
+
+```
+after AuthOwner/SessionOwner:
+  if session.scope == set_password_only:
+    if path not in {GET /api/me, POST /api/auth/password, POST /api/auth/logout}:
+      403
+  else if user.must_change_password or not user.password_set:
+    if path not in same allowlist:
+      403
+  // API key (long-lived): if must_change or not password_set → 403 on business routes
+  // (key cannot complete password change)
+```
+
+## 7. 测试计划（Backend）
+
+| # | 场景 | 判据 |
+|---|---|---|
+| T1 | create 无密码 | DB hash 空；一条 unused activate Key；stdout 有明文一次 |
+| T2 | 同名 create | 冲突；原账户与 Key 不变 |
+| T3 | redeem 成功 | Key consumed；cookie 为 set_password_only；/api/me 200；/api/projects 403 |
+| T4 | 同 Key 并发 100 次 redeem | 恰好 1 成功 |
+| T5 | 过期 / 撤销 / 重放 | 均失败 |
+| T6 | 设密成功 | hash 在；Key 作废；会话全删；再带旧 cookie → 401；密码登录 success 且 scope=full |
+| T7 | 设密中途 DB 失败（注入） | 无「已改密但仍 unused Key」 |
+| T8 | redeem 后 CreateSession 失败 | Key 仍 unused |
+| T9 | recover 签发 | 不改 hash；不删业务行；可选保留 api_keys |
+| T10 | must_change 旧路径 + 中间件 | 业务 API 403；设密后可访问 |
+| T11 | OpenExisting 缺库 | CLI 失败不建目录 |
+
+SQLite 与真实 PG 双跑；缺 PG 环境标 NOT_RUN。
+
+## 8. 安全与交付
+
+- 明文只在签发时交付；日志/evidence 只记 `id`/purpose/结果。
+- 不把 Key 放 URL、命令行参数名以外的 argv 常驻、或 localStorage（U5 约束）。
+- 对齐 OWASP Forgot Password / Session Management；保留现有 CSRF。
+
+## 9. 完成门槛与依赖
+
+- 完成条件见主提案 §7 U4 行。
+- 依赖：U1 OpenExisting 可并行由 Backend 先实现最小集，再与 svc 接线合并。
+- 被依赖：U5 登录页兑换与设密分型。
+
+## 10. 任务卡建议（待授权后 `task-start`）
+
+- 分支名：`feature/svc-deploy-u4-login-key`
+- 组件：Backend feature 分支 + Dev gitlink；Frontend 不在本增量强制改动（契约测试可用 httptest）
+- R0：与 U1 兄弟共享批准时的同一 `origin/main`
+- 交付模式：manual

docs/svc-deploy/u4-task-card-draft.md

@@ -0,0 +1,4 @@
+# 草稿：feature/svc-deploy-u4-login-key
+
+状态：**已启动** → 任务卡 `.task/feature-svc-deploy-u4-login-key.md`；工作区
+`/home/weichen/projects/Agent-System-Dev-wt-feature-svc-deploy-u4-login-key`。