@homurajs/auth 26.10.13 → 26.10.14

package/README.md

@@ -2,30 +2,56 @@
 
 认证：通用标准 OAuth2 (Authorization Code Flow) 客户端 + 自管 session（HS256 短 JWT + opaque refresh rotate + 族吊销）。
 
+session 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`，返回空数组即抢占失败 |
+
 ```ts
 // OAuth 预设来自 @homurajs/3p（结构化契约，鸭子类型互操作）
 import { dingtalkOAuth } from '@homurajs/3p/dingtalk'
-import { OAuth2Client, SessionManager } from '@homurajs/auth'
+import {
+  OAuth2Client,
+  SessionManager,
+  createDrizzleSessionStore,
+  createRestSessionStore,
+} from '@homurajs/auth'
 import { createMemoryTtlKv } from '@homurajs/core'
 
 const preset = dingtalkOAuth({ orgId: 'my_org' }) // 对接 ../oauth2-dingtalk
 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/callback',
+  stateKv: createMemoryTtlKv(), // SQL 单机够用；多实例换 createDbTtlKv；qw-pages 换 createRestTtlKv
+  ...preset, // endpoints + mapUser
 })
 
+const store = isRest
+  ? createRestSessionStore(rest) // qw-pages
+  : createDrizzleSessionStore(db) // standalone
 const sessions = new SessionManager(
-  { secret: SESSION_SECRET /*>=32B*/, accessTokenTtlSec: 7200, refreshTokenTtlSec: 30*24*3600 },
-  createDrizzleSessionStore(db),
+  { secret: SESSION_SECRET /*>=32B*/, accessTokenTtlSec: 7200, refreshTokenTtlSec: 30 * 24 * 3600 },
+  store,
 )
 
 // Hono 集成
 import { createAuthRoutes, sessionMiddleware, requireAuth } from '@homurajs/auth/hono'
-app.use('*', sessionMiddleware(sessions))
-app.route('/', createAuthRoutes({ client, sessions }))
+app.use('*', sessionMiddleware(sessions, { secure }))
+app.route('/', createAuthRoutes({ client, sessions, secure }))
 app.use('/api/*', requireAuth)
 app.get('/api/me', (c) => c.json(c.get('auth')))
 ```
 
-上游契约与 state 语义见 `docs/specs/module-oauth2`；session 状态机见 `module-session`。使用示范见模板 `src/server/app.ts`（buildAuth）与 `src/server/routes/api.ts`（c.get('auth')）。
+**`secure` 必须按形态传**：qw-pages 在平台网关后、对外是 https，`secure` 应为 `true`，否则 cookie 不带 `Secure`。模板里由 `adapter.trustProxy()` 接线（standalone 由 `TRUST_PROXY=1` 控制）。
+
+**qw-pages 上的两个前置条件**：
+
+1. `refresh_tokens` 表与 anon RLS policy 必须在部署期用平台受控迁移建好（App 无 DDL 权限）。缺 policy 时 PostgREST 是静默失败——`SELECT` 返回 `200 []`、`INSERT` 返回 401 + `42501`。
+2. `SESSION_SECRET` 不能用仓库里的公开缺省值（模板 `loadConfig` 会在 Pages/生产形态下直接拒绝启动）。密钥经 `config/homura.config.env` 随产物携带——实测产物不可被公网读取。
+
+`consume` 的原子抢占语义已在真实 PostgREST 上验证：三路并发抢占恰好一个赢家、过期 token 不会被误报为复用、族吊销只命中未消费行。
+
+上游契约与 state 语义见 `docs/specs/module-oauth2`；session 状态机见 `module-session`。使用示范见模板 `src/server/app.ts`（buildAuth）与 `src/server/routes/api.ts`（`c.get('auth')`）。

package/dist/hono.d.ts

@@ -1,4 +1,4 @@
-import { n as SessionManager, s as OAuth2Client, t as SessionClaims } from "./manager-DUAs-ASy.js";
+import { l as OAuth2Client, n as SessionManager, t as SessionClaims } from "./manager-_5q5sluE.js";
 import { Hono, MiddlewareHandler } from "hono";
 //#region src/hono/routes.d.ts
 interface AuthPaths {

package/dist/index.d.ts

@@ -1,2 +1,11 @@
-import { a as RefreshTokenStore, c as OAuth2ClientConfig, d as TokenResponse, i as SessionTokens, l as AuthUser, n as SessionManager, o as createDrizzleSessionStore, r as SessionManagerConfig, s as OAuth2Client, t as SessionClaims, u as OAuth2Endpoints } from "./manager-DUAs-ASy.js";
-export { type AuthUser, OAuth2Client, type OAuth2ClientConfig, type OAuth2Endpoints, type RefreshTokenStore, type SessionClaims, SessionManager, type SessionManagerConfig, type SessionTokens, type TokenResponse, createDrizzleSessionStore };
+import { a as RefreshTokenStore, c as RefreshTokenRecord, d as AuthUser, f as OAuth2Endpoints, i as SessionTokens, l as OAuth2Client, n as SessionManager, o as createDrizzleSessionStore, p as TokenResponse, r as SessionManagerConfig, s as ConsumedToken, t as SessionClaims, u as OAuth2ClientConfig } from "./manager-_5q5sluE.js";
+import { RestDb } from "@homurajs/db";
+//#region src/session/rest-store.d.ts
+export declare const REFRESH_TOKENS_TABLE = "refresh_tokens";
+interface RestSessionStoreOptions {
+  table?: string;
+  now?: () => number;
+}
+export declare function createRestSessionStore(rest: RestDb, opts?: RestSessionStoreOptions): RefreshTokenStore;
+//#endregion
+export { type AuthUser, type ConsumedToken, OAuth2Client, type OAuth2ClientConfig, type OAuth2Endpoints, type RefreshTokenRecord, type RefreshTokenStore, type RestSessionStoreOptions, type SessionClaims, SessionManager, type SessionManagerConfig, type SessionTokens, type TokenResponse, createDrizzleSessionStore };

package/dist/index.js

@@ -243,4 +243,67 @@ RETURNING family_id, sid, sub, profile`))[0];
 	};
 }
 //#endregion
-export { OAuth2Client, SessionManager, createDrizzleSessionStore };
+//#region src/session/rest-store.ts
+const REFRESH_TOKENS_TABLE = "refresh_tokens";
+function createRestSessionStore(rest, opts = {}) {
+	const t = rest.table(opts.table ?? "refresh_tokens");
+	const now = opts.now ?? (() => Date.now());
+	const isUsed = (v) => v !== null && v !== void 0;
+	return {
+		async create(r) {
+			await t.insert({
+				token_hash: r.tokenHash,
+				family_id: r.familyId,
+				sid: r.sid,
+				sub: r.sub,
+				expires_at: r.expiresAt,
+				profile: r.profile ?? null
+			});
+		},
+		async consume(tokenHash) {
+			const ts = now();
+			const hit = (await t.update({ used_at: ts }, {
+				token_hash: tokenHash,
+				expires_at: {
+					op: "gt",
+					value: ts
+				},
+				used_at: null
+			}))[0];
+			if (hit) return {
+				familyId: hit.family_id,
+				sid: hit.sid,
+				sub: hit.sub,
+				profile: hit.profile,
+				revoked: false
+			};
+			const row = (await t.select({ token_hash: tokenHash }, {
+				columns: "family_id,used_at",
+				limit: 1
+			}))[0];
+			if (!row) return null;
+			if (isUsed(row.used_at)) return {
+				familyId: row.family_id,
+				sid: "",
+				sub: "",
+				profile: null,
+				revoked: true
+			};
+			return null;
+		},
+		async revokeFamily(familyId) {
+			await t.update({ used_at: now() }, {
+				family_id: familyId,
+				used_at: null
+			});
+		},
+		async revokeUser(sub) {
+			await t.update({ used_at: now() }, {
+				sub,
+				used_at: null
+			});
+		}
+	};
+}
+//#endregion
+export { OAuth2Client, REFRESH_TOKENS_TABLE, SessionManager, createDrizzleSessionStore, createRestSessionStore };

package/dist/{manager-DUAs-ASy.d.ts → manager-_5q5sluE.d.ts}

@@ -173,4 +173,4 @@ declare class SessionManager {
   private issueRefresh;
 }
 //#endregion
-export { RefreshTokenStore as a, OAuth2ClientConfig as c, TokenResponse as d, SessionTokens as i, AuthUser as l, SessionManager as n, createDrizzleSessionStore as o, SessionManagerConfig as r, OAuth2Client as s, SessionClaims as t, OAuth2Endpoints as u };
+export { RefreshTokenStore as a, RefreshTokenRecord as c, AuthUser as d, OAuth2Endpoints as f, SessionTokens as i, OAuth2Client as l, SessionManager as n, createDrizzleSessionStore as o, TokenResponse as p, SessionManagerConfig as r, ConsumedToken as s, SessionClaims as t, OAuth2ClientConfig as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homurajs/auth",
-  "version": "26.10.13",
+  "version": "26.10.14",
   "type": "module",
   "description": "homura 认证：通用标准 OAuth2 (Authorization Code Flow) 客户端 + 自管 session（HS256 短 JWT + opaque refresh rotate）",
   "engines": {
@@ -28,8 +28,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@homurajs/core": "26.10.13",
-    "@homurajs/db": "26.10.13",
+    "@homurajs/core": "26.10.14",
+    "@homurajs/db": "26.10.14",
     "jose": "^6.0.0"
   },
   "peerDependencies": {