refactor(server): 统一 C 端 client routes 到 header + middleware 认证 (#36)

把 21 个业务模块的 client-routes.ts 从 body/query 内嵌 endUserId + userHash
迁移到 header + middleware 认证,和 invite 模块保持一致。

做了什么
- 每个 client router 挂载 requireClientCredential + requireClientUser 两个
  中间件,由 middleware 验证 x-api-key / x-end-user-id / x-user-hash
- handler 内删除所有 clientCredentialService.verifyRequest() 调用
- 统一用 c.get("clientCredential")!.organizationId 取 orgId,c.var.endUserId!
  取调用者 id
- validators 移除 Client* schema 的 endUserId / userHash 字段;删除仅承载
  调用者身份的 param / query schema
- 删除 "/users/{endUserId}/..." 这类调用者自身的冗余路径段,如
  GET /check-in/users/{endUserId}/state → GET /check-in/state
- 把 11 处重复的 authHeaders OpenAPI schema 提取到
  middleware/client-auth-headers.ts,各模块 import 复用
- check-in 的 client-routes.test.ts 同步迁移到 header 版请求

为什么
- middleware 集中验证,handler 不再重复调用
- 身份走 header、业务载荷走 body,符合 REST 惯例(类比 Authorization)
- GET 请求不再把 endUserId 拼进 query → 不泄漏到日志/代理
- /users/{endUserId}/... 变成单点路径,语义更清晰

破坏性变更(产品未上线,无兼容层)
- 客户端必须改为通过 HTTP header 发起:x-api-key、x-end-user-id、
  x-user-hash(devMode 下可省略 x-user-hash)
- 若干路径去掉了 /users/{endUserId} 段,详见 spec 文档

顺手修了 invite 模块 3 处 pre-existing 类型错误,让 check-types 通过:
- z.record(z.unknown()) → z.record(z.string(), z.unknown())(Zod v4)
- client-routes.test.ts 4 处 body 类型收紧

验证
- pnpm --filter=server check-types 通过
- pnpm --filter=server test 通过(45 个文件 / 719 个用例,本地 pg)

设计文档:docs/superpowers/specs/2026-04-19-client-auth-middleware-migration.md

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dengzhaofun

apps/server/src/middleware/client-auth-headers.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared OpenAPI header schema for C-end client routes.
+ *
+ * Every client router uses the middleware pair `requireClientCredential`
+ * + `requireClientUser`, and therefore every route in such a router
+ * accepts the same three headers. Declaring them once here keeps the
+ * docs consistent and avoids drift across modules.
+ *
+ * Usage:
+ *
+ *   import { clientAuthHeaders } from "../../middleware/client-auth-headers";
+ *
+ *   router.openapi(
+ *     createRoute({
+ *       request: { headers: clientAuthHeaders, ... },
+ *       ...
+ *     }),
+ *     async (c) => { ... },
+ *   );
+ */
+
+import { z } from "@hono/zod-openapi";
+
+export const clientAuthHeaders = z.object({
+  "x-api-key": z.string().openapi({
+    description: "Publishable key (cpk_...)",
+  }),
+  "x-end-user-id": z.string().openapi({
+    description: "End user's opaque id",
+  }),
+  "x-user-hash": z.string().optional().openapi({
+    description:
+      "HMAC-SHA256(endUserId, clientSecret). Required unless dev mode is enabled.",
+  }),
+});

apps/server/src/modules/activity/client-routes.ts

@@ -1,29 +1,34 @@
 /**
  * C-end client routes for the activity module.
  *
- * The admin surface at `/api/activity` already exposes every operation;
- * this file exposes the subset that *end users* trigger directly (list,
- * view, join, claim milestone) protected by client credential + HMAC.
+ * Mounted at /api/client/activity. Auth pattern:
  *
- * Activity state is checked inside the service; these routes are a
- * thin auth + serialization layer.
+ *   requireClientCredential — validates x-api-key (cpk_...), populates c.var.clientCredential
+ *   requireClientUser       — reads x-end-user-id + x-user-hash headers, verifies HMAC,
+ *                             populates c.var.endUserId
+ *
+ * Handlers read orgId from c.get("clientCredential")!.organizationId and endUserId from
+ * c.var.endUserId!. No inline verifyRequest calls; no auth fields in body or query.
  */
 
 import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 
 import type { HonoEnv } from "../../env";
 import { requireClientCredential } from "../../middleware/require-client-credential";
-import { clientCredentialService } from "../client-credentials";
+import { requireClientUser } from "../../middleware/require-client-user";
 import { ModuleError } from "./errors";
 import { activityService } from "./index";
 import {
   ActivityConfigResponseSchema,
+  ClaimMilestoneClientBody,
   ErrorResponseSchema,
 } from "./validators";
 
 const TAG = "Activity (Client)";
 
+import { clientAuthHeaders as authHeaders } from "../../middleware/client-auth-headers";
+
 const errorResponses = {
   400: {
     description: "Bad request",
@@ -46,6 +51,7 @@ const errorResponses = {
 export const activityClientRouter = new OpenAPIHono<HonoEnv>();
 
 activityClientRouter.use("*", requireClientCredential);
+activityClientRouter.use("*", requireClientUser);
 
 activityClientRouter.onError((err, c) => {
   if (err instanceof ModuleError) {
@@ -61,27 +67,6 @@ const AliasParam = z.object({
   alias: z.string().min(1).openapi({ param: { name: "alias", in: "path" } }),
 });
 
-const ClientViewQuery = z.object({
-  endUserId: z
-    .string()
-    .min(1)
-    .max(256)
-    .openapi({ param: { name: "endUserId", in: "query" } }),
-  userHash: z
-    .string()
-    .optional()
-    .openapi({ param: { name: "userHash", in: "query" } }),
-});
-
-const ClientActionBody = z.object({
-  endUserId: z.string().min(1).max(256),
-  userHash: z.string().optional(),
-});
-
-const ClaimMilestoneClientBody = ClientActionBody.extend({
-  milestoneAlias: z.string().min(1).max(64),
-});
-
 // ─── List currently visible activities ─────────────────────────
 
 activityClientRouter.openapi(
@@ -91,7 +76,7 @@ activityClientRouter.openapi(
     tags: [TAG],
     summary:
       "List activities currently visible to the caller (teasing / active / settling / ended).",
-    request: { query: ClientViewQuery },
+    request: { headers: authHeaders },
     responses: {
       200: {
         description: "OK",
@@ -107,14 +92,7 @@ activityClientRouter.openapi(
     },
   }),
   async (c) => {
-    const publishableKey = c.req.header("x-api-key")!;
-    const { endUserId, userHash } = c.req.valid("query");
-    await clientCredentialService.verifyRequest(
-      publishableKey,
-      endUserId,
-      userHash,
-    );
-    const orgId = c.var.session!.activeOrganizationId!;
+    const orgId = c.get("clientCredential")!.organizationId;
     const now = new Date();
     const rows = await activityService.listActivities(orgId);
     // Only return things the player can see — anything past visible_at
@@ -176,7 +154,7 @@ activityClientRouter.openapi(
     path: "/{alias}",
     tags: [TAG],
     summary: "Single-round-trip view of an activity for the caller.",
-    request: { params: AliasParam, query: ClientViewQuery },
+    request: { headers: authHeaders, params: AliasParam },
     responses: {
       200: {
         description: "OK",
@@ -188,15 +166,9 @@ activityClientRouter.openapi(
     },
   }),
   async (c) => {
-    const publishableKey = c.req.header("x-api-key")!;
-    const { endUserId, userHash } = c.req.valid("query");
-    await clientCredentialService.verifyRequest(
-      publishableKey,
-      endUserId,
-      userHash,
-    );
+    const orgId = c.get("clientCredential")!.organizationId;
+    const endUserId = c.var.endUserId!;
     const { alias } = c.req.valid("param");
-    const orgId = c.var.session!.activeOrganizationId!;
     const view = await activityService.getActivityForUser({
       organizationId: orgId,
       activityIdOrAlias: alias,
@@ -215,8 +187,8 @@ activityClientRouter.openapi(
     tags: [TAG],
     summary: "Enrol in an activity.",
     request: {
+      headers: authHeaders,
       params: AliasParam,
-      body: { content: { "application/json": { schema: ClientActionBody } } },
     },
     responses: {
       200: {
@@ -229,15 +201,9 @@ activityClientRouter.openapi(
     },
   }),
   async (c) => {
-    const publishableKey = c.req.header("x-api-key")!;
-    const { endUserId, userHash } = c.req.valid("json");
-    await clientCredentialService.verifyRequest(
-      publishableKey,
-      endUserId,
-      userHash,
-    );
+    const orgId = c.get("clientCredential")!.organizationId;
+    const endUserId = c.var.endUserId!;
     const { alias } = c.req.valid("param");
-    const orgId = c.var.session!.activeOrganizationId!;
     const row = await activityService.join({
       organizationId: orgId,
       activityIdOrAlias: alias,
@@ -256,6 +222,7 @@ activityClientRouter.openapi(
     tags: [TAG],
     summary: "Claim an activity milestone reward.",
     request: {
+      headers: authHeaders,
       params: AliasParam,
       body: {
         content: {
@@ -274,15 +241,10 @@ activityClientRouter.openapi(
     },
   }),
   async (c) => {
-    const publishableKey = c.req.header("x-api-key")!;
-    const { endUserId, userHash, milestoneAlias } = c.req.valid("json");
-    await clientCredentialService.verifyRequest(
-      publishableKey,
-      endUserId,
-      userHash,
-    );
+    const orgId = c.get("clientCredential")!.organizationId;
+    const endUserId = c.var.endUserId!;
+    const { milestoneAlias } = c.req.valid("json");
     const { alias } = c.req.valid("param");
-    const orgId = c.var.session!.activeOrganizationId!;
     const result = await activityService.claimMilestone({
       organizationId: orgId,
       activityIdOrAlias: alias,

apps/server/src/modules/activity/validators.ts

@@ -185,6 +185,12 @@ export const ClaimMilestoneBody = z
   })
   .openapi("ActivityClaimMilestone");
 
+export const ClaimMilestoneClientBody = z
+  .object({
+    milestoneAlias: z.string().min(1).max(64),
+  })
+  .openapi("ActivityClaimMilestoneClient");
+
 const DurationSpecSchema = z.object({
   teaseSeconds: z.number().int().nonnegative(),
   activeSeconds: z.number().int().positive(),

apps/server/src/modules/announcement/client-routes.ts

@@ -1,34 +1,40 @@
 /**
  * C-end client routes for the announcement module.
  *
- * Protected by `requireClientCredential` (cpk_ publishable key in
- * x-api-key). HMAC verification of endUserId is done inline via the
- * client credential service — same pattern as banner/mail client routes.
+ * Mounted at /api/client/announcement. Auth pattern:
+ *
+ *   requireClientCredential — validates x-api-key (cpk_...), populates c.var.clientCredential
+ *   requireClientUser       — reads x-end-user-id + x-user-hash headers, verifies HMAC,
+ *                             populates c.var.endUserId
+ *
+ * Handlers read orgId from c.get("clientCredential")!.organizationId and endUserId from
+ * c.var.endUserId!. No inline verifyRequest calls; no auth fields in body or query.
  *
  * Surface:
- *   GET  /active?endUserId=...              → currently-visible list
- *   POST /{alias}/impression  { endUserId } → fire-and-forget event
- *   POST /{alias}/click       { endUserId } → fire-and-forget event
+ *   GET  /active              → currently-visible list
+ *   POST /{alias}/impression  → fire-and-forget event
+ *   POST /{alias}/click       → fire-and-forget event
  */
 
 import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { z } from "@hono/zod-openapi";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 
 import type { HonoEnv } from "../../env";
 import { ModuleError } from "../../lib/errors";
 import { requireClientCredential } from "../../middleware/require-client-credential";
-import { clientCredentialService } from "../client-credentials";
+import { requireClientUser } from "../../middleware/require-client-user";
 import { announcementService } from "./index";
 import {
   AliasParamSchema,
-  ClientAckBodySchema,
   ClientAnnouncementListResponseSchema,
-  ClientListQuerySchema,
   ErrorResponseSchema,
 } from "./validators";
 
 const TAG = "Announcement (Client)";
 
+import { clientAuthHeaders as authHeaders } from "../../middleware/client-auth-headers";
+
 const errorResponses = {
   400: {
     description: "Bad request",
@@ -47,6 +53,7 @@ const errorResponses = {
 export const announcementClientRouter = new OpenAPIHono<HonoEnv>();
 
 announcementClientRouter.use("*", requireClientCredential);
+announcementClientRouter.use("*", requireClientUser);
 
 announcementClientRouter.onError((err, c) => {
   if (err instanceof ModuleError) {
@@ -68,7 +75,9 @@ announcementClientRouter.openapi(
     path: "/active",
     tags: [TAG],
     summary: "List currently-visible announcements for an end user",
-    request: { query: ClientListQuerySchema },
+    request: {
+      headers: authHeaders,
+    },
     responses: {
       200: {
         description: "OK",
@@ -82,17 +91,8 @@ announcementClientRouter.openapi(
     },
   }),
   async (c) => {
-    const publishableKey = c.req.header("x-api-key")!;
-    const { endUserId } = c.req.valid("query");
-    const userHash = c.req.header("x-user-hash");
-
-    await clientCredentialService.verifyRequest(
-      publishableKey,
-      endUserId,
-      userHash,
-    );
-
-    const orgId = c.var.session!.activeOrganizationId!;
+    const orgId = c.get("clientCredential")!.organizationId;
+    const endUserId = c.var.endUserId!;
     const items = await announcementService.getActiveForClient(
       orgId,
       endUserId,
@@ -108,29 +108,18 @@ announcementClientRouter.openapi(
     tags: [TAG],
     summary: "Record an impression for an announcement",
     request: {
+      headers: authHeaders,
       params: AliasParamSchema,
-      body: {
-        content: { "application/json": { schema: ClientAckBodySchema } },
-      },
     },
     responses: {
       204: { description: "Recorded" },
       ...errorResponses,
     },
   }),
   async (c) => {
-    const publishableKey = c.req.header("x-api-key")!;
+    const orgId = c.get("clientCredential")!.organizationId;
+    const endUserId = c.var.endUserId!;
     const { alias } = c.req.valid("param");
-    const { endUserId } = c.req.valid("json");
-    const userHash = c.req.header("x-user-hash");
-
-    await clientCredentialService.verifyRequest(
-      publishableKey,
-      endUserId,
-      userHash,
-    );
-
-    const orgId = c.var.session!.activeOrganizationId!;
     await announcementService.recordImpression(orgId, alias, endUserId);
     return c.body(null, 204);
   },
@@ -143,29 +132,18 @@ announcementClientRouter.openapi(
     tags: [TAG],
     summary: "Record a CTA click for an announcement",
     request: {
+      headers: authHeaders,
       params: AliasParamSchema,
-      body: {
-        content: { "application/json": { schema: ClientAckBodySchema } },
-      },
     },
     responses: {
       204: { description: "Recorded" },
       ...errorResponses,
     },
   }),
   async (c) => {
-    const publishableKey = c.req.header("x-api-key")!;
+    const orgId = c.get("clientCredential")!.organizationId;
+    const endUserId = c.var.endUserId!;
     const { alias } = c.req.valid("param");
-    const { endUserId } = c.req.valid("json");
-    const userHash = c.req.header("x-user-hash");
-
-    await clientCredentialService.verifyRequest(
-      publishableKey,
-      endUserId,
-      userHash,
-    );
-
-    const orgId = c.var.session!.activeOrganizationId!;
     await announcementService.recordClick(orgId, alias, endUserId);
     return c.body(null, 204);
   },