@homurajs/auth 26.10.13 → 26.10.15

package/README.md

@@ -1,31 +1,134 @@
 # @homurajs/auth
 
-认证：通用标准 OAuth2 (Authorization Code Flow) 客户端 + 自管 session（HS256 短 JWT + opaque refresh rotate + 族吊销）。
+多凭证身份认证：OAuth2 客户端 + TextPassword（scrypt）+ WebAuthn（可选）+ 自管 session（HS256 短 JWT + opaque refresh rotate + 族吊销）。
+
+## 架构
+
+**身份模型（ADR-022）**：`users` 表是本地身份锚点，三种凭证都通过 `user_id` 关联：
+
+- `passwords`：1:1 users，scrypt 哈希（Node 内置 crypto，零依赖，ADR-023）
+- `oauth2_identity_links`：1:N users，UNIQUE(provider, provider_sub)
+- `webauthn_credentials`：1:N users，PK = credentialId base64url
+
+**session.sub = local user ID**（Breaking：不再是 IdP subject）。Identity Resolver 在 OAuth2 callback 时桥接 IdP sub → local user，JIT 默认开启（首次登录自动建户），可配 false 拒绝未知身份。
+
+**SDK 不渲染 HTML**：所有路由只返回 JSON + cookies，登录 UI 由 App 自行实现。
+
+## 存储实现
+
+所有 store 都有双版本，接口语义严格对齐，按数据方言选：
+
+| 实现                                | 用于               | 说明                                                                                                            |
+| ----------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `createDrizzleSessionStore(db)`     | `sqlite` / `pg`    | 原生 SQL，`UPDATE...WHERE used_at IS NULL RETURNING` 做原子抢占                                                 |
+| `createRestSessionStore(rest)`      | `rest`（qw-pages） | PostgREST：`PATCH ?token_hash=eq&expires_at=gt&used_at=is.null` + `return=representation`，返回空数组即抢占失败 |
+| `createDrizzleUserStore(db)`        | `sqlite` / `pg`    | users 表 CRUD                                                                                                   |
+| `createRestUserStore(rest)`         | `rest`             | PostgREST                                                                                                       |
+| `createDrizzleOAuth2LinkStore(db)`  | `sqlite` / `pg`    | oauth2_identity_links 表 CRUD                                                                                   |
+| `createRestOAuth2LinkStore(rest)`   | `rest`             | PostgREST                                                                                                       |
+| `createDrizzlePasswordStore(db)`    | `sqlite` / `pg`    | passwords 表 CRUD                                                                                               |
+| `createRestPasswordStore(rest)`     | `rest`             | PostgREST                                                                                                       |
+| `createDrizzleWebauthnCredentialStore(db)` | `sqlite` / `pg` | webauthn_credentials 表 CRUD                                                                                |
+| `createRestWebauthnCredentialStore(rest)`  | `rest`          | PostgREST                                                                                                       |
+
+## 使用示例
+
+### OAuth2 + Identity Resolver
 
 ```ts
-// OAuth 预设来自 @homurajs/3p（结构化契约，鸭子类型互操作）
 import { dingtalkOAuth } from '@homurajs/3p/dingtalk'
-import { OAuth2Client, SessionManager } from '@homurajs/auth'
-import { createMemoryTtlKv } from '@homurajs/core'
+import {
+  OAuth2Client,
+  SessionManager,
+  createDrizzleSessionStore,
+  createDrizzleUserStore,
+  createDrizzleOAuth2LinkStore,
+  createDefaultIdentityResolver,
+  createMemoryTtlKv,
+} from '@homurajs/auth'
+import { createAuthRoutes, sessionMiddleware } from '@homurajs/auth/hono'
 
-const preset = dingtalkOAuth({ orgId: 'my_org' }) // 对接 ../oauth2-dingtalk
+const preset = dingtalkOAuth({ orgId: 'my_org' })
 const client = new OAuth2Client({
-  clientId: '...', clientSecret: '...', redirectUri: 'https://app.example/auth/callback',
-  stateKv: createMemoryTtlKv(), // 多实例部署换 createDbTtlKv
-  ...preset,                    // endpoints + mapUser
+  clientId: '...',
+  clientSecret: '...',
+  redirectUri: 'https://app.example/auth/oauth2/callback',
+  stateKv: createMemoryTtlKv(),
+  ...preset,
+})
+
+const userStore = createDrizzleUserStore(db)
+const linkStore = createDrizzleOAuth2LinkStore(db)
+const identityResolver = createDefaultIdentityResolver(userStore, linkStore, { jit: true })
+
+const sessions = new SessionManager({ secret: SESSION_SECRET }, createDrizzleSessionStore(db))
+
+app.use('*', sessionMiddleware(sessions, { secure }))
+app.route('/', createAuthRoutes({
+  sessions,
+  oauth2: { client, identityResolver, provider: 'dingtalk' },
+}))
+```
+
+### TextPassword
+
+```ts
+import { PasswordProvider, createDrizzlePasswordStore } from '@homurajs/auth'
+
+const passwordProvider = new PasswordProvider({
+  userStore,
+  passwordStore: createDrizzlePasswordStore(db),
 })
 
-const sessions = new SessionManager(
-  { secret: SESSION_SECRET /*>=32B*/, accessTokenTtlSec: 7200, refreshTokenTtlSec: 30*24*3600 },
-  createDrizzleSessionStore(db),
-)
-
-// Hono 集成
-import { createAuthRoutes, sessionMiddleware, requireAuth } from '@homurajs/auth/hono'
-app.use('*', sessionMiddleware(sessions))
-app.route('/', createAuthRoutes({ client, sessions }))
-app.use('/api/*', requireAuth)
-app.get('/api/me', (c) => c.json(c.get('auth')))
+app.route('/', createAuthRoutes({
+  sessions,
+  password: passwordProvider,
+  allowRegister: true, // 默认 true，可配 false 禁止自助注册
+}))
 ```
 
-上游契约与 state 语义见 `docs/specs/module-oauth2`；session 状态机见 `module-session`。使用示范见模板 `src/server/app.ts`（buildAuth）与 `src/server/routes/api.ts`（c.get('auth')）。
+路由：
+- `POST /auth/password/register` → session cookies + 200 JSON
+- `POST /auth/password/login` → session cookies + 200 JSON
+- `POST /auth/password/change` → 需已登录 → 200 JSON
+- `POST /auth/password/delete` → 需已登录 → 200 JSON
+
+### WebAuthn（可选）
+
+```ts
+import { WebAuthProvider, createDrizzleWebauthnCredentialStore } from '@homurajs/auth/webauthn'
+import { createWebAuthnRoutes } from '@homurajs/auth/webauthn'
+
+const webauthn = new WebAuthProvider({
+  rpName: 'My App',
+  rpID: 'app.example.com',
+  origin: 'https://app.example.com',
+  userStore,
+  credentialStore: createDrizzleWebauthnCredentialStore(db),
+  challengeKv: createMemoryTtlKv(),
+})
+
+app.route('/', createWebAuthnRoutes({ webauthn, sessions }))
+```
+
+`@simplewebauthn/server` 是 optional peer dep，不用 WebAuthn 的 App 无需安装。
+
+## 子路径导出
+
+- `@homurajs/auth`：核心（OAuth2Client, SessionManager, PasswordProvider, IdentityResolver, 各 store 工厂）
+- `@homurajs/auth/hono`：Hono 路由（createAuthRoutes, createPasswordRoutes, sessionMiddleware, requireAuth）
+- `@homurajs/auth/tables`：表定义（pgAuthTables, sqliteAuthTables，含 5 张表）
+- `@homurajs/auth/webauthn`：WebAuthn（WebAuthProvider, createWebAuthnRoutes, credential store 工厂）
+
+## 注意事项
+
+**`secure` 必须按形态传**：qw-pages 在平台网关后、对外是 https，`secure` 应为 `true`，否则 cookie 不带 `Secure`。模板里由 `adapter.trustProxy()` 接线。
+
+**qw-pages 前置条件**：所有 auth 表（users / passwords / oauth2_identity_links / webauthn_credentials / refresh_tokens）与 anon RLS policy 必须在部署期用平台受控迁移建好（App 无 DDL 权限）。缺 policy 时 PostgREST 是静默失败。
+
+**Breaking（2026-10-14）**：
+- session.sub 从 IdP subject 改为 local user ID（现有 refresh token 全部失效，重登即恢复）
+- OAuth2 路径从 `/auth/login` + `/auth/callback` 迁移到 `/auth/oauth2/authorize` + `/auth/oauth2/callback`
+- `createAuthRoutes` 签名变更：`client` → `oauth2: { client, identityResolver, provider }`
+
+`consume` 的原子抢占语义已在真实 PostgREST 上验证。详见 `docs/specs/module-oauth2`、`module-session`、`module-password`、`module-webauthn`、ADR-022、ADR-023。使用示范见模板 `src/server/app.ts`（buildAuth）。

package/dist/hono.d.ts

@@ -1,29 +1,68 @@
-import { n as SessionManager, s as OAuth2Client, t as SessionClaims } from "./manager-DUAs-ASy.js";
+import { o as SessionClaims, s as SessionManager } from "./types-C-SlEMFJ.js";
+import { d as OAuth2Client, s as IdentityResolver, t as PasswordProvider } from "./provider-BkUYQ703.js";
 import { Hono, MiddlewareHandler } from "hono";
 //#region src/hono/routes.d.ts
-interface AuthPaths {
-  login?: string;
-  callback?: string;
-  refresh?: string;
-  logout?: string;
+interface OAuth2Inject {
+  client: OAuth2Client;
+  identityResolver: IdentityResolver;
+  /** OAuth2 provider 标识（如 'dingtalk'） */
+  provider: string;
 }
 interface AuthRoutesOptions {
-  client: OAuth2Client;
   sessions: SessionManager;
-  paths?: AuthPaths;
+  /** OAuth2 能力（不传则不挂载 OAuth2 路由） */
+  oauth2?: OAuth2Inject;
+  /** Password 能力（不传则不挂载 Password 路由） */
+  password?: PasswordProvider;
+  /** 是否允许自助注册（默认 true） */
+  allowRegister?: boolean;
   /** cookie Secure（qw-pages/https 传 true） */
   secure?: boolean;
-  /** 登录成功后的缺省跳转（returnTo 优先） */
+  /** 登录成功后的缺省跳转 */
   defaultReturnTo?: string;
 }
 /**
- * GET  /auth/login    → 302 authorize（returnTo via query）
- * GET  /auth/callback → 建 session 写双 cookie → 302 returnTo
- * POST /auth/refresh  → rotate（读 refresh cookie）
- * POST /auth/logout   → 吊销 session + 清 cookie
+ * 组合 auth 路由：OAuth2 + Password（按配置）+ refresh + logout。
  */
 export declare function createAuthRoutes(opts: AuthRoutesOptions): Hono;
 //#endregion
+//#region src/hono/oauth2-routes.d.ts
+interface OAuth2Paths {
+  authorize?: string;
+  callback?: string;
+}
+interface OAuth2RoutesOptions {
+  client: OAuth2Client;
+  sessions: SessionManager;
+  /** OAuth2 回调时调用：IdP sub → local user */
+  identityResolver: IdentityResolver;
+  /** OAuth2 provider 标识（如 'dingtalk'），用于 identity link */
+  provider: string;
+  paths?: OAuth2Paths;
+  /** cookie Secure（qw-pages/https 传 true） */
+  secure?: boolean;
+  /** 登录成功后的缺省跳转（returnTo 优先） */
+  defaultReturnTo?: string;
+}
+export declare function createOAuth2Routes(opts: OAuth2RoutesOptions): Hono;
+//#endregion
+//#region src/hono/password-routes.d.ts
+interface PasswordPaths {
+  register?: string;
+  login?: string;
+  change?: string;
+  delete?: string;
+}
+interface PasswordRoutesOptions {
+  password: PasswordProvider;
+  sessions: SessionManager;
+  /** 是否允许自助注册（默认 true） */
+  allowRegister?: boolean;
+  paths?: PasswordPaths;
+  secure?: boolean;
+}
+export declare function createPasswordRoutes(opts: PasswordRoutesOptions): Hono;
+//#endregion
 //#region src/hono/middleware.d.ts
 interface SessionMiddlewareOptions {
   /** 允许 Authorization: Bearer（默认 true） */
@@ -37,7 +76,14 @@ interface SessionMiddlewareOptions {
  * 无身份不报错（交给 requireAuth 决定 401/302）。
  */
 export declare function sessionMiddleware(sessions: SessionManager, opts?: SessionMiddlewareOptions): MiddlewareHandler;
-/** 无身份：/api 或 Accept:json → 401 JSON；页面请求 → 302 login */
+/**
+ * 无身份：/api 或 Accept:json → 401 JSON；页面请求 → 302 login。
+ *
+ * ⚠ loginPath 缺省 = OAuth2 授权入口 `/auth/oauth2/authorize`（旧 `/auth/login` 已废弃，
+ *   见 ADR-022）。SDK 不渲染登录页，故缺省指向唯一内置的 GET 登录入口；
+ *   纯密码认证或自带登录 UI 的 App 必须显式传 `loginPath` 指向自己的登录页，
+ *   否则页面请求会 302 到一个不存在的路径（被 SPA fallback 判成 404 JSON）。
+ */
 export declare function requireAuth(opts?: {
   loginPath?: string;
 }): MiddlewareHandler;
@@ -47,4 +93,4 @@ declare module 'hono' {
   }
 }
 //#endregion
-export type { AuthPaths, AuthRoutesOptions, SessionClaims, SessionMiddlewareOptions };
+export type { AuthRoutesOptions, OAuth2Inject, OAuth2Paths, OAuth2RoutesOptions, PasswordPaths, PasswordRoutesOptions, SessionClaims, SessionMiddlewareOptions };

package/dist/hono.js

@@ -1,24 +1,25 @@
+import { n as UsernameTakenError, r as IdentityNotLinkedError } from "./provider-DMtwLgGf.js";
 import { Hono } from "hono";
 import { getCookie, setCookie } from "hono/cookie";
-//#region src/hono/routes.ts
+//#region src/hono/oauth2-routes.ts
 /**
-* GET  /auth/login    → 302 authorize（returnTo via query）
-* GET  /auth/callback → 建 session 写双 cookie → 302 returnTo
-* POST /auth/refresh  → rotate（读 refresh cookie）
-* POST /auth/logout   → 吊销 session + 清 cookie
+* OAuth2 路由（新路径统一到 /auth/oauth2/*）。
+*
+* GET  /auth/oauth2/authorize → 302 到 IdP authorize URL
+* GET  /auth/oauth2/callback  → identity resolver → session → 302 returnTo
+*
+* 旧路径 /auth/login + /auth/callback 已废弃（Breaking change）。
 */
-function createAuthRoutes(opts) {
-	const { client, sessions } = opts;
+function createOAuth2Routes(opts) {
+	const { client, sessions, identityResolver, provider } = opts;
 	const paths = {
-		login: opts.paths?.login ?? "/auth/login",
-		callback: opts.paths?.callback ?? "/auth/callback",
-		refresh: opts.paths?.refresh ?? "/auth/refresh",
-		logout: opts.paths?.logout ?? "/auth/logout"
+		authorize: opts.paths?.authorize ?? "/auth/oauth2/authorize",
+		callback: opts.paths?.callback ?? "/auth/oauth2/callback"
 	};
 	const secure = opts.secure ?? false;
 	const names = sessions.cookies;
 	const app = new Hono();
-	app.get(paths.login, async (c) => {
+	app.get(paths.authorize, async (c) => {
 		const returnTo = c.req.query("returnTo");
 		const url = await client.authorizeUrl(returnTo);
 		return c.redirect(url);
@@ -28,11 +29,20 @@ function createAuthRoutes(opts) {
 		const state = c.req.query("state");
 		if (!code) return c.json({ error: "missing_code" }, 400);
 		try {
-			const { user, returnTo } = await client.callback({
+			const { user: idpUser, returnTo } = await client.callback({
 				code,
 				state: state ?? void 0
 			});
-			const tokens = await sessions.createSession(user);
+			const localUser = await identityResolver.resolve(provider, idpUser.sub, {
+				nickname: idpUser.nickname,
+				avatarUrl: idpUser.avatarUrl
+			});
+			const authUser = {
+				sub: localUser.id,
+				nickname: localUser.nickname ?? idpUser.nickname,
+				avatarUrl: localUser.avatarUrl ?? idpUser.avatarUrl
+			};
+			const tokens = await sessions.createSession(authUser);
 			setCookie(c, names.access, tokens.accessToken, {
 				httpOnly: true,
 				sameSite: "Lax",
@@ -49,13 +59,271 @@ function createAuthRoutes(opts) {
 			});
 			return c.redirect(returnTo || opts.defaultReturnTo || "/");
 		} catch (e) {
+			if (e instanceof IdentityNotLinkedError) return c.json({
+				error: "identity_not_linked",
+				message: e.message
+			}, 403);
 			return c.json({
 				error: "oauth_failed",
 				message: e.message
 			}, 401);
 		}
 	});
-	app.post(paths.refresh, async (c) => {
+	return app;
+}
+//#endregion
+//#region src/hono/password-routes.ts
+/**
+* 密码认证路由（JSON API，不渲染页面）。
+*
+* POST /auth/password/register → 注册（username + password）→ session cookies + 200 JSON
+* POST /auth/password/login    → 登录 → session cookies + 200 JSON
+* POST /auth/password/change   → 改密码（需已登录）→ 200 JSON
+* POST /auth/password/delete   → 删密码（需已登录）→ 200 JSON
+*/
+/**
+* 跨方言唯一约束冲突判定（username 并发注册的兜底）。
+*
+* ⚠ 必须走 cause 链：drizzle 把底层驱动错误包成 DrizzleQueryError，其顶层 message 是
+*   "Failed query: INSERT ..."，**不含** UNIQUE 字样——只看顶层 message 会漏判（曾导致
+*   重复用户名注册回落 400 而非 409）。真正的信号在 cause：
+*   - sqlite：cause.errcode === 2067（SQLITE_CONSTRAINT_UNIQUE），cause.message 含 "UNIQUE constraint failed"
+*   - pg：cause.code === '23505'（unique_violation），message 含 "duplicate key"
+*   逐层向下最多走 5 层，命中任一信号即判定为唯一冲突。
+*/
+function isUniqueViolation(e) {
+	let cur = e;
+	for (let depth = 0; cur && depth < 5; depth++) {
+		if (cur.errcode === 2067) return true;
+		if (cur.code === "23505") return true;
+		if (typeof cur.message === "string" && /unique constraint|duplicate key|unique violation/i.test(cur.message)) return true;
+		cur = cur.cause;
+	}
+	return false;
+}
+function createPasswordRoutes(opts) {
+	const { password, sessions } = opts;
+	const allowRegister = opts.allowRegister ?? true;
+	const paths = {
+		register: opts.paths?.register ?? "/auth/password/register",
+		login: opts.paths?.login ?? "/auth/password/login",
+		change: opts.paths?.change ?? "/auth/password/change",
+		delete: opts.paths?.delete ?? "/auth/password/delete"
+	};
+	const secure = opts.secure ?? false;
+	const names = sessions.cookies;
+	const app = new Hono();
+	app.post(paths.register, async (c) => {
+		if (!allowRegister) return c.json({
+			error: "registration_disabled",
+			message: "自助注册已关闭"
+		}, 403);
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({ error: "invalid_body" }, 400);
+		}
+		if (!body.username || !body.password) return c.json({
+			error: "missing_fields",
+			message: "需要 username 和 password"
+		}, 400);
+		if (body.password.length < 8) return c.json({
+			error: "weak_password",
+			message: "密码至少 8 位"
+		}, 400);
+		try {
+			const user = await password.register({
+				username: body.username,
+				password: body.password,
+				nickname: body.nickname
+			});
+			const authUser = {
+				sub: user.id,
+				nickname: user.nickname ?? void 0,
+				avatarUrl: user.avatarUrl ?? void 0
+			};
+			const tokens = await sessions.createSession(authUser);
+			setCookie(c, names.access, tokens.accessToken, {
+				httpOnly: true,
+				sameSite: "Lax",
+				secure,
+				path: "/",
+				maxAge: sessions.accessTokenTtlSec
+			});
+			setCookie(c, names.refresh, tokens.refreshToken, {
+				httpOnly: true,
+				sameSite: "Lax",
+				secure,
+				path: "/",
+				maxAge: sessions.refreshTokenTtlSec
+			});
+			return c.json({
+				ok: true,
+				user: {
+					id: user.id,
+					username: user.username,
+					nickname: user.nickname
+				}
+			});
+		} catch (e) {
+			if (e instanceof UsernameTakenError || isUniqueViolation(e)) return c.json({
+				error: "username_taken",
+				message: "用户名已被注册"
+			}, 409);
+			return c.json({
+				error: "register_failed",
+				message: e.message
+			}, 400);
+		}
+	});
+	app.post(paths.login, async (c) => {
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({ error: "invalid_body" }, 400);
+		}
+		if (!body.username || !body.password) return c.json({
+			error: "missing_fields",
+			message: "需要 username 和 password"
+		}, 400);
+		const user = await password.verify(body.username, body.password);
+		if (!user) return c.json({
+			error: "invalid_credentials",
+			message: "用户名或密码错误"
+		}, 401);
+		const authUser = {
+			sub: user.id,
+			nickname: user.nickname ?? void 0,
+			avatarUrl: user.avatarUrl ?? void 0
+		};
+		const tokens = await sessions.createSession(authUser);
+		setCookie(c, names.access, tokens.accessToken, {
+			httpOnly: true,
+			sameSite: "Lax",
+			secure,
+			path: "/",
+			maxAge: sessions.accessTokenTtlSec
+		});
+		setCookie(c, names.refresh, tokens.refreshToken, {
+			httpOnly: true,
+			sameSite: "Lax",
+			secure,
+			path: "/",
+			maxAge: sessions.refreshTokenTtlSec
+		});
+		return c.json({
+			ok: true,
+			user: {
+				id: user.id,
+				username: user.username,
+				nickname: user.nickname
+			}
+		});
+	});
+	app.post(paths.change, async (c) => {
+		const claims = c.get("auth");
+		if (!claims) return c.json({ error: "unauthorized" }, 401);
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({ error: "invalid_body" }, 400);
+		}
+		if (!body.oldPassword || !body.newPassword) return c.json({
+			error: "missing_fields",
+			message: "需要 oldPassword 和 newPassword"
+		}, 400);
+		if (body.newPassword.length < 8) return c.json({
+			error: "weak_password",
+			message: "密码至少 8 位"
+		}, 400);
+		try {
+			await password.changePassword(claims.sub, body.oldPassword, body.newPassword);
+			await sessions.revokeUser(claims.sub);
+			setCookie(c, names.access, "", {
+				httpOnly: true,
+				secure,
+				path: "/",
+				maxAge: 0
+			});
+			setCookie(c, names.refresh, "", {
+				httpOnly: true,
+				secure,
+				path: "/",
+				maxAge: 0
+			});
+			return c.json({
+				ok: true,
+				reloginRequired: true
+			});
+		} catch (e) {
+			return c.json({
+				error: "change_failed",
+				message: e.message
+			}, 400);
+		}
+	});
+	app.post(paths.delete, async (c) => {
+		const claims = c.get("auth");
+		if (!claims) return c.json({ error: "unauthorized" }, 401);
+		try {
+			await password.deletePassword(claims.sub);
+			return c.json({ ok: true });
+		} catch (e) {
+			return c.json({
+				error: "delete_failed",
+				message: e.message
+			}, 400);
+		}
+	});
+	return app;
+}
+//#endregion
+//#region src/hono/routes.ts
+/**
+* 主路由组合器 —— 按配置的能力（OAuth2 / Password）组装路由。
+*
+* createAuthRoutes(opts) 根据 opts 提供的 capability 自动组合：
+* - opts.oauth2（OAuth2Client + IdentityResolver + provider）→ /auth/oauth2/*
+* - opts.password（PasswordProvider）→ /auth/password/*
+* - 无条件挂载：/auth/refresh、/auth/logout
+*
+* WebAuthn 路由**不在**此组合器内——消费者从 @homurajs/auth/webauthn 取
+* createWebAuthnRoutes 自行挂载。
+*
+* ⚠ Breaking：旧 /auth/login + /auth/callback 路径已迁移到 /auth/oauth2/*。
+*/
+/**
+* 组合 auth 路由：OAuth2 + Password（按配置）+ refresh + logout。
+*/
+function createAuthRoutes(opts) {
+	const { sessions } = opts;
+	const secure = opts.secure ?? false;
+	const names = sessions.cookies;
+	const app = new Hono();
+	if (opts.oauth2) {
+		const oauth2App = createOAuth2Routes({
+			client: opts.oauth2.client,
+			sessions,
+			identityResolver: opts.oauth2.identityResolver,
+			provider: opts.oauth2.provider,
+			secure,
+			defaultReturnTo: opts.defaultReturnTo
+		});
+		app.route("/", oauth2App);
+	}
+	if (opts.password) {
+		const passwordApp = createPasswordRoutes({
+			password: opts.password,
+			sessions,
+			allowRegister: opts.allowRegister,
+			secure
+		});
+		app.route("/", passwordApp);
+	}
+	app.post("/auth/refresh", async (c) => {
 		const refreshToken = getCookie(c, names.refresh);
 		if (!refreshToken) return c.json({ error: "no_refresh_token" }, 401);
 		const rotated = await sessions.refresh(refreshToken);
@@ -76,7 +344,7 @@ function createAuthRoutes(opts) {
 		});
 		return c.json({ ok: true });
 	});
-	app.post(paths.logout, async (c) => {
+	app.post("/auth/logout", async (c) => {
 		const claims = c.get("auth");
 		if (claims?.sid) await sessions.revokeSession(claims.sid);
 		setCookie(c, names.access, "", {
@@ -140,9 +408,16 @@ function sessionMiddleware(sessions, opts) {
 		await next();
 	};
 }
-/** 无身份：/api 或 Accept:json → 401 JSON；页面请求 → 302 login */
+/**
+* 无身份：/api 或 Accept:json → 401 JSON；页面请求 → 302 login。
+*
+* ⚠ loginPath 缺省 = OAuth2 授权入口 `/auth/oauth2/authorize`（旧 `/auth/login` 已废弃，
+*   见 ADR-022）。SDK 不渲染登录页，故缺省指向唯一内置的 GET 登录入口；
+*   纯密码认证或自带登录 UI 的 App 必须显式传 `loginPath` 指向自己的登录页，
+*   否则页面请求会 302 到一个不存在的路径（被 SPA fallback 判成 404 JSON）。
+*/
 function requireAuth(opts) {
-	const loginPath = opts?.loginPath ?? "/auth/login";
+	const loginPath = opts?.loginPath ?? "/auth/oauth2/authorize";
 	return async (c, next) => {
 		if (c.get("auth")) {
 			await next();
@@ -154,4 +429,4 @@ function requireAuth(opts) {
 	};
 }
 //#endregion
-export { createAuthRoutes, requireAuth, sessionMiddleware };
+export { createAuthRoutes, createOAuth2Routes, createPasswordRoutes, requireAuth, sessionMiddleware };