fix(security): W4-E1 approvals admin-session only, shared redact table, TMDB key redaction, prod mock gate

- POST /approvals and PATCH /approvals/{id} require a console admin session
  (EndpointDef auth:"session"); API keys incl. admin scope get 403, so an
  organize.execute key can no longer approve its own plan (S1)
- tests for single-use approval checks: expired, revision/payload hash
  mismatch, consumed, revoked, pending/rejected, plan mismatch; re-approve
  after plan change succeeds once and cannot be replayed (S4)
- one redact key table in @umt/contracts shared by server logger and agent
  redactForModel: rsskey, torrent_pass, authkey, downhash, c_secure_pass,
  passkey variants, x-api-key, cookie headers, nested objects/arrays (S2)
- TMDB network errors: message and cause redacted via redactUrl (S3)
- web Agent ?mock=1 only in DEV builds or when pi.provider is fake (S7)
- EndpointDef auth annotations for /auth/*, asserted against
  PUBLIC_AUTH_PATHS (S10); doc drift fixes (S11)

Co-Authored-By: Claude Opus 5.5 <[email protected]>

apps/server/src/modules/auth-settings/auth-routes.ts

@@ -1,20 +1,7 @@
-import {
-  AdminSetupRequest,
-  CSRF_COOKIE,
-  LoginRequest,
-  LoginResult,
-  PasswordChangeRequest,
-  PasswordChangeResult,
-  SESSION_COOKIE,
-  SessionInfo,
-  TotpAction,
-  TotpActionResult,
-  TotpStatus,
-} from "@umt/contracts";
+import { Api, CSRF_COOKIE, SESSION_COOKIE } from "@umt/contracts";
 import type { Context } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
-import { z } from "zod";
-import { type AuthEnv, deriveCsrfToken, requireAdminSession } from "../../http/auth.ts";
+import { type AuthEnv, deriveCsrfToken } from "../../http/auth.ts";
 import { ApiException } from "../../http/errors.ts";
 import type { ModuleApp, ServerContext } from "../types.ts";
 import {
@@ -38,56 +25,18 @@ import { audit, type Def, endpoint } from "./endpoint.ts";
 // 其余需要已登录;改密与 TOTP 只接受控制台 cookie 会话。
 
 const tags = ["auth"];
-const OkResult = z.object({ ok: z.literal(true) });
 
+// 端点定义直接取 contracts 注册表(scope 与 auth 标注只维护一份):setup/login/session 为 auth:"public",
+// password/totp 为 auth:"session"(endpoint() 据此跳过 requireScope 或追加 requireAdminSession)。
 const D = {
-  setup: {
-    method: "post",
-    path: "/auth/setup",
-    scope: "read",
-    summary: "首次初始化管理员",
-    body: AdminSetupRequest,
-    response: SessionInfo,
-    tags,
-  },
-  login: {
-    method: "post",
-    path: "/auth/login",
-    scope: "read",
-    summary: "管理员登录",
-    body: LoginRequest,
-    response: LoginResult,
-    tags,
-  },
-  logout: { method: "post", path: "/auth/logout", scope: "read", summary: "注销当前会话", response: OkResult, tags },
-  session: {
-    method: "get",
-    path: "/auth/session",
-    scope: "read",
-    summary: "当前登录态(免鉴权)",
-    response: SessionInfo,
-    tags,
-  },
-  password: {
-    method: "post",
-    path: "/auth/password",
-    scope: "admin",
-    summary: "修改密码(吊销其它会话)",
-    body: PasswordChangeRequest,
-    response: PasswordChangeResult,
-    tags,
-  },
-  totpGet: { method: "get", path: "/auth/totp", scope: "admin", summary: "TOTP 状态", response: TotpStatus, tags },
-  totpPost: {
-    method: "post",
-    path: "/auth/totp",
-    scope: "admin",
-    summary: "TOTP 绑定/启用/停用",
-    body: TotpAction,
-    response: TotpActionResult,
-    tags,
-  },
-} as const satisfies Record<string, Def>;
+  setup: { ...Api.auth.setup, tags },
+  login: { ...Api.auth.login, tags },
+  logout: { ...Api.auth.logout, tags },
+  session: { ...Api.auth.session, tags },
+  password: { ...Api.auth.password, tags },
+  totpGet: { ...Api.auth.totpStatus, tags },
+  totpPost: { ...Api.auth.totp, tags },
+} satisfies Record<string, Def>;
 
 const PRIVATE_IP = /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|::1$|fc|fd|::ffff:(127|10|192\.168)\.)/i;
 
@@ -142,53 +91,38 @@ export function registerAuthRoutes(app: ModuleApp, ctx: ServerContext) {
     return s;
   };
 
-  endpoint(
-    app,
-    D.setup,
-    async ({ body, c }) => {
-      const admin = await setupAdmin(deps(), body, clientIp(c));
-      const s = await startSession(c, admin.id);
-      const actor = adminActor(admin);
-      await audit(ctx, actor, "admin.setup", { type: "admin_user", id: admin.id }, { username: admin.username });
-      ctx.logger.info({ username: admin.username }, "管理员已初始化");
-      return await sessionInfo(ctx.db, actor, s.expiresAt);
-    },
-    { public: true },
-  );
+  endpoint(app, D.setup, async ({ body, c }) => {
+    const admin = await setupAdmin(deps(), body, clientIp(c));
+    const s = await startSession(c, admin.id);
+    const actor = adminActor(admin);
+    await audit(ctx, actor, "admin.setup", { type: "admin_user", id: admin.id }, { username: admin.username });
+    ctx.logger.info({ username: admin.username }, "管理员已初始化");
+    return await sessionInfo(ctx.db, actor, s.expiresAt);
+  });
 
-  endpoint(
-    app,
-    D.login,
-    async ({ body, c }) => {
-      const r = await verifyLogin(deps(), body, clientIp(c));
-      if (r.status === "totp_required") return { status: "totp_required" as const };
-      const s = await startSession(c, r.admin.id);
-      const actor = adminActor(r.admin);
-      await audit(ctx, actor, "admin.login_success", { type: "admin_session", id: s.id }, { ip: clientIp(c) });
-      return { status: "ok" as const, session: await sessionInfo(ctx.db, actor, s.expiresAt) };
-    },
-    { public: true },
-  );
+  endpoint(app, D.login, async ({ body, c }) => {
+    const r = await verifyLogin(deps(), body, clientIp(c));
+    if (r.status === "totp_required") return { status: "totp_required" as const };
+    const s = await startSession(c, r.admin.id);
+    const actor = adminActor(r.admin);
+    await audit(ctx, actor, "admin.login_success", { type: "admin_session", id: s.id }, { ip: clientIp(c) });
+    return { status: "ok" as const, session: await sessionInfo(ctx.db, actor, s.expiresAt) };
+  });
 
-  endpoint(
-    app,
-    D.session,
-    async ({ c }) => {
-      const session = c.get("session");
-      // CSRF cookie 丢了(被清)时顺手补发
-      if (session) {
-        setCookie(c, CSRF_COOKIE, deriveCsrfToken(session.token), {
-          httpOnly: false,
-          sameSite: "Lax",
-          path: "/",
-          secure: isHttps(c),
-          expires: session.expiresAt,
-        });
-      }
-      return await sessionInfo(ctx.db, c.get("actor"), session?.expiresAt ?? null);
-    },
-    { public: true },
-  );
+  endpoint(app, D.session, async ({ c }) => {
+    const session = c.get("session");
+    // CSRF cookie 丢了(被清)时顺手补发
+    if (session) {
+      setCookie(c, CSRF_COOKIE, deriveCsrfToken(session.token), {
+        httpOnly: false,
+        sameSite: "Lax",
+        path: "/",
+        secure: isHttps(c),
+        expires: session.expiresAt,
+      });
+    }
+    return await sessionInfo(ctx.db, c.get("actor"), session?.expiresAt ?? null);
+  });
 
   endpoint(app, D.logout, async ({ c, actor }) => {
     const session = c.get("session");
@@ -200,44 +134,34 @@ export function registerAuthRoutes(app: ModuleApp, ctx: ServerContext) {
     return { ok: true as const };
   });
 
-  endpoint(
-    app,
-    D.password,
-    async ({ body, c, actor }) => {
-      const session = c.get("session");
-      if (!session) throw new ApiException("forbidden", "该操作只能在控制台登录后进行");
-      const revoked = await changePassword(deps(), body, {
-        adminUserId: session.adminUserId,
-        sessionId: session.id,
-        ip: clientIp(c),
-      });
-      await audit(ctx, actor, "admin.password_change", { type: "admin_user", id: session.adminUserId }, { revoked });
-      return { revokedSessions: revoked };
-    },
-    { middleware: [requireAdminSession()] },
-  );
+  endpoint(app, D.password, async ({ body, c, actor }) => {
+    const session = c.get("session");
+    if (!session) throw new ApiException("forbidden", "该操作只能在控制台登录后进行");
+    const revoked = await changePassword(deps(), body, {
+      adminUserId: session.adminUserId,
+      sessionId: session.id,
+      ip: clientIp(c),
+    });
+    await audit(ctx, actor, "admin.password_change", { type: "admin_user", id: session.adminUserId }, { revoked });
+    return { revokedSessions: revoked };
+  });
 
-  endpoint(app, D.totpGet, async () => totpStatus(await loadAdmin(ctx.db)), { middleware: [requireAdminSession()] });
+  endpoint(app, D.totpGet, async () => totpStatus(await loadAdmin(ctx.db)));
 
-  endpoint(
-    app,
-    D.totpPost,
-    async ({ body, actor }) => {
-      const admin = await loadAdmin(ctx.db);
-      if (!admin?.password_hash) throw new ApiException("precondition_failed", "管理员尚未初始化");
-      if (body.action === "begin") {
-        const r = await totpBegin(deps(), admin);
-        return { status: totpStatus(await loadAdmin(ctx.db)), otpauthUri: r.uri, secret: r.secret };
-      }
-      if (body.action === "enable") {
-        await totpEnable(deps(), admin, body.code);
-        await audit(ctx, actor, "admin.totp_enable", { type: "admin_user", id: admin.id });
-      } else {
-        await totpDisable(deps(), admin, body);
-        await audit(ctx, actor, "admin.totp_disable", { type: "admin_user", id: admin.id });
-      }
-      return { status: totpStatus(await loadAdmin(ctx.db)) };
-    },
-    { middleware: [requireAdminSession()] },
-  );
+  endpoint(app, D.totpPost, async ({ body, actor }) => {
+    const admin = await loadAdmin(ctx.db);
+    if (!admin?.password_hash) throw new ApiException("precondition_failed", "管理员尚未初始化");
+    if (body.action === "begin") {
+      const r = await totpBegin(deps(), admin);
+      return { status: totpStatus(await loadAdmin(ctx.db)), otpauthUri: r.uri, secret: r.secret };
+    }
+    if (body.action === "enable") {
+      await totpEnable(deps(), admin, body.code);
+      await audit(ctx, actor, "admin.totp_enable", { type: "admin_user", id: admin.id });
+    } else {
+      await totpDisable(deps(), admin, body);
+      await audit(ctx, actor, "admin.totp_disable", { type: "admin_user", id: admin.id });
+    }
+    return { status: totpStatus(await loadAdmin(ctx.db)) };
+  });
 }

apps/server/src/modules/auth-settings/endpoint.ts

@@ -13,7 +13,7 @@ import { type DB, type Kysely, sql } from "@umt/db";
 import type { Context, MiddlewareHandler } from "hono";
 import type { Logger } from "pino";
 import type { z } from "zod";
-import { type AuthEnv, requireScope } from "../../http/auth.ts";
+import { type AuthEnv, requireAdminSession, requireScope } from "../../http/auth.ts";
 import { ApiException } from "../../http/errors.ts";
 import type { ModuleApp } from "../types.ts";
 
@@ -39,7 +39,7 @@ export function endpoint<D extends Def>(
   extra: {
     middleware?: MiddlewareHandler<AuthEnv>[];
     status?: 200 | 201;
-    /** 免鉴权端点(必须同时列在 http/auth.ts 的 PUBLIC_AUTH_PATHS),不挂 requireScope */
+    /** 免鉴权端点(必须同时列在 http/auth.ts 的 PUBLIC_AUTH_PATHS),不挂 requireScope;等价于 def.auth = "public" */
     public?: boolean;
   } = {},
 ) {
@@ -53,7 +53,11 @@ export function endpoint<D extends Def>(
     path: def.path,
     summary: def.summary,
     tags: def.tags ?? ["auth-settings"],
-    middleware: [...(extra.public ? [] : [requireScope(def.scope)]), ...(extra.middleware ?? [])] as never,
+    middleware: [
+      ...(extra.public || def.auth === "public" ? [] : [requireScope(def.scope)]),
+      ...(def.auth === "session" ? [requireAdminSession()] : []),
+      ...(extra.middleware ?? []),
+    ] as never,
     request,
     responses: {
       [status]: {