From 35f0b700b1ebf9237b65b1bb8114bca1489233ab Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 6 Aug 2026 06:39:49 +0000 Subject: [PATCH] =?UTF-8?q?docs(plugin-auth,client):=20=E4=B8=A4=E5=A4=84?= =?UTF-8?q?=E4=BB=93=E5=86=85=E6=96=87=E6=A1=A3=E4=B8=8D=E5=86=8D=E6=8A=8A?= =?UTF-8?q?=E5=9B=9B=E6=9D=A1=E4=B8=8D=E5=AD=98=E5=9C=A8=E7=9A=84=20auth?= =?UTF-8?q?=20=E7=AB=AF=E7=82=B9=E5=86=99=E6=88=90=E5=B7=B2=E6=B3=A8?= =?UTF-8?q?=E5=86=8C=E8=B7=AF=E7=94=B1=20(#5772)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `IMPLEMENTATION_SUMMARY.md` 的 "API Routes Registered" 节列的 `POST /api/v1/auth/login` / `register` / `logout` / `GET .../session` 四条端点 一条都不存在:auth 插件用单条 catch-all 把 `/api/v1/auth/*` 整体转发给 better-auth,真实路由表由 `src/auth-route-ledger.ts`(#3656)逐条枚举并由 conformance 测试对活的 `auth.api` 校验。该节改为指向台账这一单一事实源,只保 留四条核心路由的真名作最小示例(与 `content/docs/api/plugin-endpoints.mdx` 一致),并写明这四个名字不存在、唯一让 `/auth/login` 看起来可达的遗留显式挂载 已在 #5085 删除。同文件 "Core Plugin Implementation" 里同一处虚假声明一并改正。 `CLIENT_SERVER_INTEGRATION_TESTS.md` 的 MSW 示例改用真实端点 `POST /api/v1/auth/sign-in/email`,并注明四个 SDK 方法各自打到哪条路由、台账 在哪 —— 照抄旧示例写出的测试会打在一个 404 上。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01JwwiU9bjhwy2SWj13ho8uv --- .../client/CLIENT_SERVER_INTEGRATION_TESTS.md | 7 +++- .../plugin-auth/IMPLEMENTATION_SUMMARY.md | 38 +++++++++++++++---- 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md b/packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md index 4b66de012e..2fe2e4d081 100644 --- a/packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md +++ b/packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md @@ -638,8 +638,11 @@ export function createMockServer() { })); }), - // Auth - rest.post('/api/v1/auth/login', (req, res, ctx) => { + // Auth — better-auth route names, not `/auth/login`: `client.auth.login` + // calls POST /auth/sign-in/email, `register` /auth/sign-up/email, `logout` + // /auth/sign-out, `me` GET /auth/get-session. The audited route table is + // packages/plugins/plugin-auth/src/auth-route-ledger.ts. + rest.post('/api/v1/auth/sign-in/email', (req, res, ctx) => { return res(ctx.json({ success: true, data: { diff --git a/packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md b/packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md index b47ca789f5..11b629f433 100644 --- a/packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md +++ b/packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md @@ -32,7 +32,7 @@ Successfully integrated the Better-Auth library (v1.4.18) into `@objectstack/plu - **AuthPlugin class** - Full plugin lifecycle (init, start, destroy) - **AuthManager class** - Real implementation with better-auth integration - **Lazy initialization** - Better-auth instance created only when needed -- **Route registration** - HTTP endpoints for login, register, logout, session +- **Route registration** - the auth base path (`/api/v1/auth/*`) forwarded to better-auth; see [API Routes](#api-routes) - **Service registration** - Registers 'auth' service in ObjectKernel - **Configuration support** - Uses AuthConfig schema from @objectstack/spec/system - **TypeScript types** - Proper typing for IHttpRequest and IHttpResponse @@ -86,12 +86,36 @@ packages/plugins/plugin-auth/ 6. **Plugin Pattern**: Follows established ObjectStack plugin conventions 7. **TypeScript-First**: Full type safety with proper interface definitions -## API Routes Registered - -- `POST /api/v1/auth/login` - User login (stub) -- `POST /api/v1/auth/register` - User registration (stub) -- `POST /api/v1/auth/logout` - User logout (stub) -- `GET /api/v1/auth/session` - Get current session (stub) +## API Routes + +The plugin does **not** hand-register a `login` / `register` / `logout` / `session` route +set. Everything under the auth base path (`/api/v1/auth` by default, `basePath` in the +plugin options) is forwarded to better-auth through a single catch-all mount, so +**better-auth's own route table is the route table** — plus a handful of ObjectStack-owned +routes (`/config`, `/bootstrap-status`, `/admin/*`, …) mounted ahead of it. + +**The single source of truth is [`src/auth-route-ledger.ts`](./src/auth-route-ledger.ts)** +(#3656): the reviewed `AUTH_ROUTE_LEDGER` rows — every route the SDK actually calls, each +naming its client method — plus the full `BETTER_AUTH_MOUNTED_SURFACE` inventory, both +verified against the live `auth.api` table by `auth-route-ledger.conformance.test.ts`. +Read the ledger instead of a copy: a list transcribed into this file drifts the next time +better-auth is upgraded, and this section is the proof (it advertised four routes that +never existed). + +The core routes, spelled the way better-auth actually serves them — same names as +[`content/docs/api/plugin-endpoints.mdx`](../../../content/docs/api/plugin-endpoints.mdx): + +| Route | SDK method | +|:------|:-----------| +| `POST /api/v1/auth/sign-in/email` | `auth.login` | +| `POST /api/v1/auth/sign-up/email` | `auth.register` | +| `POST /api/v1/auth/sign-out` | `auth.logout` | +| `GET /api/v1/auth/get-session` | `auth.me` | + +There is no `/auth/login`, `/auth/register`, `/auth/logout` or `/auth/session` route. The +one legacy explicit `POST /api/v1/auth/login` mount that made the first of them look +reachable lived in the runtime dispatcher, answered HTTP 500 to every caller, and was +deleted in #5085. ## Dependencies