@homurajs/auth 0.0.0-stage → 26.10.13

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @homurajs/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+认证：通用标准 OAuth2 (Authorization Code Flow) 客户端 + 自管 session（HS256 短 JWT + opaque refresh rotate + 族吊销）。
+
+```ts
+// OAuth 预设来自 @homurajs/3p（结构化契约，鸭子类型互操作）
+import { dingtalkOAuth } from '@homurajs/3p/dingtalk'
+import { OAuth2Client, SessionManager } 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
+})
+
+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')))
+```
+
+上游契约与 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

@@ -0,0 +1,50 @@
+import { n as SessionManager, s as OAuth2Client, t as SessionClaims } from "./manager-DUAs-ASy.js";
+import { Hono, MiddlewareHandler } from "hono";
+//#region src/hono/routes.d.ts
+interface AuthPaths {
+  login?: string;
+  callback?: string;
+  refresh?: string;
+  logout?: string;
+}
+interface AuthRoutesOptions {
+  client: OAuth2Client;
+  sessions: SessionManager;
+  paths?: AuthPaths;
+  /** 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
+ */
+export declare function createAuthRoutes(opts: AuthRoutesOptions): Hono;
+//#endregion
+//#region src/hono/middleware.d.ts
+interface SessionMiddlewareOptions {
+  /** 允许 Authorization: Bearer（默认 true） */
+  bearer?: boolean;
+  /** cookie Secure 属性（qw-pages/https 传 true；本地 http dev 传 false） */
+  secure?: boolean;
+}
+/**
+ * cookie 优先、Authorization: Bearer 兼容；
+ * access 过期且 refresh cookie 有效 → 透明 rotate 续期；c.set('auth', claims)。
+ * 无身份不报错（交给 requireAuth 决定 401/302）。
+ */
+export declare function sessionMiddleware(sessions: SessionManager, opts?: SessionMiddlewareOptions): MiddlewareHandler;
+/** 无身份：/api 或 Accept:json → 401 JSON；页面请求 → 302 login */
+export declare function requireAuth(opts?: {
+  loginPath?: string;
+}): MiddlewareHandler;
+declare module 'hono' {
+  interface ContextVariableMap {
+    auth: SessionClaims;
+  }
+}
+//#endregion
+export type { AuthPaths, AuthRoutesOptions, SessionClaims, SessionMiddlewareOptions };

package/dist/hono.js

@@ -0,0 +1,157 @@
+import { Hono } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
+//#region src/hono/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
+*/
+function createAuthRoutes(opts) {
+	const { client, sessions } = 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"
+	};
+	const secure = opts.secure ?? false;
+	const names = sessions.cookies;
+	const app = new Hono();
+	app.get(paths.login, async (c) => {
+		const returnTo = c.req.query("returnTo");
+		const url = await client.authorizeUrl(returnTo);
+		return c.redirect(url);
+	});
+	app.get(paths.callback, async (c) => {
+		const code = c.req.query("code");
+		const state = c.req.query("state");
+		if (!code) return c.json({ error: "missing_code" }, 400);
+		try {
+			const { user, returnTo } = await client.callback({
+				code,
+				state: state ?? void 0
+			});
+			const tokens = await sessions.createSession(user);
+			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.redirect(returnTo || opts.defaultReturnTo || "/");
+		} catch (e) {
+			return c.json({
+				error: "oauth_failed",
+				message: e.message
+			}, 401);
+		}
+	});
+	app.post(paths.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);
+		if (!rotated) return c.json({ error: "invalid_refresh_token" }, 401);
+		setCookie(c, names.access, rotated.accessToken, {
+			httpOnly: true,
+			sameSite: "Lax",
+			secure,
+			path: "/",
+			maxAge: sessions.accessTokenTtlSec
+		});
+		setCookie(c, names.refresh, rotated.refreshToken, {
+			httpOnly: true,
+			sameSite: "Lax",
+			secure,
+			path: "/",
+			maxAge: sessions.refreshTokenTtlSec
+		});
+		return c.json({ ok: true });
+	});
+	app.post(paths.logout, async (c) => {
+		const claims = c.get("auth");
+		if (claims?.sid) await sessions.revokeSession(claims.sid);
+		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 });
+	});
+	return app;
+}
+//#endregion
+//#region src/hono/middleware.ts
+/**
+* cookie 优先、Authorization: Bearer 兼容；
+* access 过期且 refresh cookie 有效 → 透明 rotate 续期；c.set('auth', claims)。
+* 无身份不报错（交给 requireAuth 决定 401/302）。
+*/
+function sessionMiddleware(sessions, opts) {
+	const bearer = opts?.bearer ?? true;
+	const secure = opts?.secure ?? false;
+	const names = sessions.cookies;
+	return async (c, next) => {
+		let token = getCookie(c, names.access);
+		if (!token && bearer) {
+			const auth = c.req.header("authorization");
+			if (auth?.startsWith("Bearer ")) token = auth.slice(7);
+		}
+		let claims = token ? await sessions.verifyAccessToken(token) : null;
+		if (!claims) {
+			const refreshToken = getCookie(c, names.refresh);
+			if (refreshToken) {
+				const rotated = await sessions.refresh(refreshToken);
+				if (rotated) {
+					claims = await sessions.verifyAccessToken(rotated.accessToken);
+					setCookie(c, names.access, rotated.accessToken, {
+						httpOnly: true,
+						sameSite: "Lax",
+						secure,
+						path: "/",
+						maxAge: sessions.accessTokenTtlSec
+					});
+					setCookie(c, names.refresh, rotated.refreshToken, {
+						httpOnly: true,
+						sameSite: "Lax",
+						secure,
+						path: "/",
+						maxAge: sessions.refreshTokenTtlSec
+					});
+				}
+			}
+		}
+		if (claims) c.set("auth", claims);
+		await next();
+	};
+}
+/** 无身份：/api 或 Accept:json → 401 JSON；页面请求 → 302 login */
+function requireAuth(opts) {
+	const loginPath = opts?.loginPath ?? "/auth/login";
+	return async (c, next) => {
+		if (c.get("auth")) {
+			await next();
+			return;
+		}
+		if (c.req.path.startsWith("/api") || c.req.header("accept")?.includes("application/json")) return c.json({ error: "unauthorized" }, 401);
+		const returnTo = c.req.url;
+		return c.redirect(`${loginPath}?returnTo=${encodeURIComponent(returnTo)}`);
+	};
+}
+//#endregion
+export { createAuthRoutes, requireAuth, sessionMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+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 };

package/dist/index.js

@@ -0,0 +1,246 @@
+import { randomToken } from "@homurajs/core";
+import { createHash, randomBytes } from "node:crypto";
+import { SignJWT, jwtVerify } from "jose";
+import { sql } from "drizzle-orm";
+import { isSqlite } from "@homurajs/db";
+//#region src/oauth2/client.ts
+const DEFAULT_STATE_TTL = 3e5;
+/**
+* 通用标准 OAuth2 (Authorization Code Flow) 客户端。
+* 服务端（如 ../oauth2-dingtalk）由 3p 预设注入，本类不感知具体 IdP。
+*/
+var OAuth2Client = class {
+	config;
+	fetchImpl;
+	stateTtl;
+	constructor(config) {
+		this.config = config;
+		this.fetchImpl = config.fetchImpl ?? fetch;
+		this.stateTtl = config.stateTtlMs ?? DEFAULT_STATE_TTL;
+	}
+	/** 生成 authorize URL（state 入 kv），returnTo 编码进 state 关联存储 */
+	async authorizeUrl(returnTo) {
+		const state = randomToken(16);
+		await this.config.stateKv.set(state, returnTo ?? "/", this.stateTtl);
+		const url = new URL(this.config.endpoints.authorizeUrl);
+		url.searchParams.append("client_id", this.config.clientId);
+		url.searchParams.append("redirect_uri", this.config.redirectUri);
+		url.searchParams.append("response_type", "code");
+		if (this.config.scopes?.length) url.searchParams.append("scope", this.config.scopes.join(" "));
+		url.searchParams.append("state", state);
+		for (const [k, v] of Object.entries(this.config.authorizeExtraParams ?? {})) url.searchParams.append(k, v);
+		return url.toString();
+	}
+	/**
+	* 回调：state 一次性消费校验 → code 换 token → 拉 userinfo → mapUser
+	* 返回 { user, returnTo }，供 hono 路由建 session 后跳转
+	*/
+	async callback(params) {
+		if (!params.code) throw new Error("缺少 code");
+		let returnTo = "/";
+		if (params.state) {
+			const stored = await this.config.stateKv.take(params.state);
+			if (stored === null) throw new Error("state 无效或已过期");
+			returnTo = stored;
+		} else if (!this.config.allowNoState) throw new Error("缺少 state（如需放行请显式 allowNoState: true，dev only）");
+		const token = await this.exchangeToken(params.code);
+		const raw = await this.fetchUserinfo(token.access_token);
+		return {
+			user: this.config.mapUser(raw),
+			returnTo
+		};
+	}
+	/** 内部：code 换 token（POST tokenUrl，form 编码） */
+	async exchangeToken(code) {
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			client_id: this.config.clientId,
+			client_secret: this.config.clientSecret,
+			redirect_uri: this.config.redirectUri
+		});
+		const res = await this.fetchImpl(this.config.endpoints.tokenUrl, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: body.toString()
+		});
+		if (!res.ok) throw new Error(`token 端点失败: ${res.status} ${await res.text()}`);
+		return await res.json();
+	}
+	/** 内部：Bearer 拉 userinfo */
+	async fetchUserinfo(accessToken) {
+		const res = await this.fetchImpl(this.config.endpoints.userinfoUrl, {
+			method: "GET",
+			headers: { authorization: `Bearer ${accessToken}` }
+		});
+		if (!res.ok) throw new Error(`userinfo 端点失败: ${res.status} ${await res.text()}`);
+		return await res.json();
+	}
+};
+//#endregion
+//#region src/session/manager.ts
+const DEFAULT_ACCESS_TTL = 7200;
+const DEFAULT_REFRESH_TTL = 2592e3;
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+/**
+* 自管 session：短 JWT（HS256）+ opaque refresh（rotate + familyId 复用检测整族吊销）。
+* 上游（oauth2-dingtalk）不支持 refresh token，生命周期完全自管。
+*/
+var SessionManager = class {
+	config;
+	store;
+	key;
+	accessTtl;
+	refreshTtl;
+	cookieNames;
+	nowFn;
+	constructor(config, store) {
+		this.config = config;
+		this.store = store;
+		if (config.secret.length < 32) throw new Error("session secret 必须 >= 32 字节（HS256 强度要求）");
+		this.key = new TextEncoder().encode(config.secret);
+		this.accessTtl = config.accessTokenTtlSec ?? DEFAULT_ACCESS_TTL;
+		this.refreshTtl = config.refreshTokenTtlSec ?? DEFAULT_REFRESH_TTL;
+		this.cookieNames = {
+			access: config.cookieNames?.access ?? "homura_at",
+			refresh: config.cookieNames?.refresh ?? "homura_rt"
+		};
+		this.nowFn = config.now ?? (() => /* @__PURE__ */ new Date());
+	}
+	get cookies() {
+		return this.cookieNames;
+	}
+	get accessTokenTtlSec() {
+		return this.accessTtl;
+	}
+	get refreshTokenTtlSec() {
+		return this.refreshTtl;
+	}
+	async createSession(user) {
+		const sid = randomToken(16);
+		return {
+			accessToken: await this.signAccess(user, sid),
+			refreshToken: await this.issueRefresh(sid, user, sid)
+		};
+	}
+	async verifyAccessToken(token) {
+		try {
+			const { payload } = await jwtVerify(token, this.key, {
+				algorithms: ["HS256"],
+				currentDate: this.nowFn()
+			});
+			return payload;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* rotate：旧 token 一次性消费；复用检出（同 family 二次使用）→ 吊销整族。
+	* 返回 null 表示 refresh 链终态（过期/已消费/复用检出）。
+	*/
+	async refresh(refreshToken) {
+		const consumed = await this.store.consume(sha256(refreshToken));
+		if (!consumed) return null;
+		if (consumed.revoked) {
+			await this.store.revokeFamily(consumed.familyId);
+			return null;
+		}
+		const profile = consumed.profile ? JSON.parse(consumed.profile) : {};
+		const user = {
+			sub: consumed.sub,
+			...profile
+		};
+		return {
+			accessToken: await this.signAccess(user, consumed.sid),
+			refreshToken: await this.issueRefresh(consumed.sid, user, consumed.familyId)
+		};
+	}
+	async revokeSession(sid) {
+		await this.store.revokeFamily(sid);
+	}
+	async revokeUser(sub) {
+		await this.store.revokeUser(sub);
+	}
+	async signAccess(user, sid) {
+		const now = this.nowFn();
+		const exp = new Date(now.getTime() + this.accessTtl * 1e3);
+		return new SignJWT({
+			sub: user.sub,
+			nickname: user.nickname,
+			avatarUrl: user.avatarUrl,
+			sid
+		}).setProtectedHeader({ alg: "HS256" }).setIssuedAt(now).setJti(randomToken(8)).setExpirationTime(exp).sign(this.key);
+	}
+	async issueRefresh(sid, user, familyId) {
+		const refreshToken = randomBytes(32).toString("base64url");
+		const expiresAt = this.nowFn().getTime() + this.refreshTtl * 1e3;
+		const profile = user.nickname || user.avatarUrl ? JSON.stringify({
+			nickname: user.nickname,
+			avatarUrl: user.avatarUrl
+		}) : null;
+		await this.store.create({
+			tokenHash: sha256(refreshToken),
+			familyId,
+			sid,
+			sub: user.sub,
+			expiresAt,
+			profile
+		});
+		return refreshToken;
+	}
+};
+//#endregion
+//#region src/session/store.ts
+async function exec(db, q) {
+	if (isSqlite(db)) await db.run(q);
+	else await db.execute(q);
+}
+async function query(db, q) {
+	if (isSqlite(db)) return await db.all(q);
+	return await db.execute(q) ?? [];
+}
+/**
+* drizzle 双方言实现（表定义见 @homurajs/auth/tables，App spread 进 schema 迁移）。
+* consume 用 UPDATE ... RETURNING 原子标记 used_at，已 used 的行返回 revoked:true。
+*/
+function createDrizzleSessionStore(db, opts) {
+	const now = opts?.now ?? (() => Date.now());
+	return {
+		async create(r) {
+			await exec(db, sql`INSERT INTO refresh_tokens (token_hash, family_id, sid, sub, expires_at, profile)
+VALUES (${r.tokenHash}, ${r.familyId}, ${r.sid}, ${r.sub}, ${r.expiresAt}, ${r.profile ?? null})`);
+		},
+		async consume(tokenHash) {
+			const ts = now();
+			const claimed = (await query(db, sql`UPDATE refresh_tokens
+SET used_at = ${ts}
+WHERE token_hash = ${tokenHash} AND expires_at > ${ts} AND used_at IS NULL
+RETURNING family_id, sid, sub, profile`))[0];
+			if (claimed) return {
+				familyId: claimed.family_id,
+				sid: claimed.sid,
+				sub: claimed.sub,
+				profile: claimed.profile,
+				revoked: false
+			};
+			const row = (await query(db, sql`SELECT family_id, used_at FROM refresh_tokens WHERE token_hash = ${tokenHash}`))[0];
+			if (!row) return null;
+			if (row.used_at !== null) return {
+				familyId: row.family_id,
+				sid: "",
+				sub: "",
+				profile: null,
+				revoked: true
+			};
+			return null;
+		},
+		async revokeFamily(familyId) {
+			await exec(db, sql`UPDATE refresh_tokens SET used_at = ${now()} WHERE family_id = ${familyId} AND used_at IS NULL`);
+		},
+		async revokeUser(sub) {
+			await exec(db, sql`UPDATE refresh_tokens SET used_at = ${now()} WHERE sub = ${sub} AND used_at IS NULL`);
+		}
+	};
+}
+//#endregion
+export { OAuth2Client, SessionManager, createDrizzleSessionStore };

package/dist/manager-DUAs-ASy.d.ts

@@ -0,0 +1,176 @@
+import { TtlKv } from "@homurajs/core";
+import { NodeSQLiteDatabase } from "drizzle-orm/node-sqlite";
+import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+//#region src/types.d.ts
+/**
+ * 上游契约唯一事实源。
+ * ⚠ 字段以实读 ../oauth2-dingtalk 源码为准（token/userinfo 端点见 specs/module-oauth2）。
+ *   钉钉特有的 userinfo 形状（Oauth2DingtalkUserInfo）在 @homurajs/3p/dingtalk/oauth.ts，
+ *   auth 包只认标准 OAuth2/OIDC 契约。
+ */
+/** 规范化用户身份（各 IdP 的 mapUser 归一结果） */
+interface AuthUser {
+  sub: string;
+  nickname?: string;
+  avatarUrl?: string;
+}
+interface OAuth2Endpoints {
+  authorizeUrl: string;
+  tokenUrl: string;
+  userinfoUrl: string;
+}
+/**
+ * 标准 OAuth2 token 响应。
+ * 实读核对：oauth2-dingtalk POST /:orgId/token 返回
+ *   { access_token, token_type: 'bearer', expires_in }（src/index.ts:91-95）。
+ */
+interface TokenResponse {
+  access_token: string;
+  token_type?: string;
+  expires_in?: number;
+}
+//#endregion
+//#region src/oauth2/client.d.ts
+interface OAuth2ClientConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes?: string[];
+  endpoints: OAuth2Endpoints;
+  /** 上游原始 userinfo → 规范身份（预设来自 @homurajs/3p/*） */
+  mapUser: (raw: unknown) => AuthUser;
+  /** state 存储（core 的内存或 db 实现），TTL 5min 一次性消费 */
+  stateKv: TtlKv;
+  /** 测试注入口；全程不 mock 全局 fetch */
+  fetchImpl?: typeof fetch;
+  authorizeExtraParams?: Record<string, string>;
+  /** dev 显式 opt-in 才允许无 state（修复 Suzuran 的 Redis 缺失放行后门） */
+  allowNoState?: boolean;
+  /** state TTL（默认 5min） */
+  stateTtlMs?: number;
+}
+/**
+ * 通用标准 OAuth2 (Authorization Code Flow) 客户端。
+ * 服务端（如 ../oauth2-dingtalk）由 3p 预设注入，本类不感知具体 IdP。
+ */
+declare class OAuth2Client {
+  private config;
+  private fetchImpl;
+  private stateTtl;
+  constructor(config: OAuth2ClientConfig);
+  /** 生成 authorize URL（state 入 kv），returnTo 编码进 state 关联存储 */
+  authorizeUrl(returnTo?: string): Promise<string>;
+  /**
+   * 回调：state 一次性消费校验 → code 换 token → 拉 userinfo → mapUser
+   * 返回 { user, returnTo }，供 hono 路由建 session 后跳转
+   */
+  callback(params: {
+    code: string;
+    state?: string;
+  }): Promise<{
+    user: AuthUser;
+    returnTo: string;
+  }>;
+  /** 内部：code 换 token（POST tokenUrl，form 编码） */
+  protected exchangeToken(code: string): Promise<TokenResponse>;
+  /** 内部：Bearer 拉 userinfo */
+  protected fetchUserinfo(accessToken: string): Promise<unknown>;
+}
+//#endregion
+//#region src/session/record.d.ts
+/** refresh_tokens 表记录（store 实现与迁移共用）；时间用 epoch 毫秒（原生 SQL 双方言一致） */
+interface RefreshTokenRecord {
+  /** SHA-256 hex */
+  tokenHash: string;
+  familyId: string;
+  sid: string;
+  sub: string;
+  /** epoch ms */
+  expiresAt: number;
+  /** JSON 字符串 { nickname?, avatarUrl? }，rotate 时回填 access token */
+  profile?: string | null;
+}
+/** consume 结果：revoked=true 表示该 token 此前已被消费（复用信号 → 触发族吊销） */
+interface ConsumedToken {
+  familyId: string;
+  sid: string;
+  sub: string;
+  profile?: string | null;
+  revoked: boolean;
+}
+//#endregion
+//#region src/session/store.d.ts
+/** 双方言数据库实例（与 @homurajs/db 的 Database 结构一致，但保持本包 peer 边界独立） */
+type DrizzleDb = PostgresJsDatabase | NodeSQLiteDatabase;
+interface RefreshTokenStore {
+  create(r: RefreshTokenRecord): Promise<void>;
+  /** 一次性消费：原子标记已用并返回记录；已消费过的返回 revoked:true（复用信号） */
+  consume(tokenHash: string): Promise<ConsumedToken | null>;
+  revokeFamily(familyId: string): Promise<void>;
+  revokeUser(sub: string): Promise<void>;
+}
+/**
+ * drizzle 双方言实现（表定义见 @homurajs/auth/tables，App spread 进 schema 迁移）。
+ * consume 用 UPDATE ... RETURNING 原子标记 used_at，已 used 的行返回 revoked:true。
+ */
+declare function createDrizzleSessionStore(db: DrizzleDb, opts?: {
+  now?: () => number;
+}): RefreshTokenStore;
+//#endregion
+//#region src/session/manager.d.ts
+interface SessionManagerConfig {
+  /** HS256 密钥（>=32 bytes，启动校验） */
+  secret: string;
+  accessTokenTtlSec?: number;
+  refreshTokenTtlSec?: number;
+  cookieNames?: {
+    access?: string;
+    refresh?: string;
+  };
+  /** 时间注入口（测试 fake timers） */
+  now?: () => Date;
+}
+interface SessionClaims {
+  sub: string;
+  nickname?: string;
+  avatarUrl?: string;
+  sid: string;
+  exp: number;
+}
+interface SessionTokens {
+  accessToken: string;
+  refreshToken: string;
+}
+/**
+ * 自管 session：短 JWT（HS256）+ opaque refresh（rotate + familyId 复用检测整族吊销）。
+ * 上游（oauth2-dingtalk）不支持 refresh token，生命周期完全自管。
+ */
+declare class SessionManager {
+  private readonly config;
+  private readonly store;
+  private readonly key;
+  private readonly accessTtl;
+  private readonly refreshTtl;
+  private readonly cookieNames;
+  private readonly nowFn;
+  constructor(config: SessionManagerConfig, store: RefreshTokenStore);
+  get cookies(): {
+    access: string;
+    refresh: string;
+  };
+  get accessTokenTtlSec(): number;
+  get refreshTokenTtlSec(): number;
+  createSession(user: AuthUser): Promise<SessionTokens>;
+  verifyAccessToken(token: string): Promise<SessionClaims | null>;
+  /**
+   * rotate：旧 token 一次性消费；复用检出（同 family 二次使用）→ 吊销整族。
+   * 返回 null 表示 refresh 链终态（过期/已消费/复用检出）。
+   */
+  refresh(refreshToken: string): Promise<SessionTokens | null>;
+  revokeSession(sid: string): Promise<void>;
+  revokeUser(sub: string): Promise<void>;
+  private signAccess;
+  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 };

package/dist/tables.d.ts

@@ -0,0 +1,237 @@
+//#region src/tables.d.ts
+export declare const pgAuthTables: {
+  refreshTokens: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "refresh_tokens";
+    schema: undefined;
+    columns: {
+      tokenHash: import("drizzle-orm/pg-core").PgBuildColumn<"refresh_tokens", import("drizzle-orm/pg-core").SetIsPrimaryKey<import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>>, {
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        identity: undefined;
+        generated: undefined;
+      }>;
+      familyId: import("drizzle-orm/pg-core").PgBuildColumn<"refresh_tokens", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>>, {
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        identity: undefined;
+        generated: undefined;
+      }>;
+      sid: import("drizzle-orm/pg-core").PgBuildColumn<"refresh_tokens", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>>, {
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        identity: undefined;
+        generated: undefined;
+      }>;
+      sub: import("drizzle-orm/pg-core").PgBuildColumn<"refresh_tokens", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>>, {
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        identity: undefined;
+        generated: undefined;
+      }>;
+      expiresAt: import("drizzle-orm/pg-core").PgBuildColumn<"refresh_tokens", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgBigInt53Builder>, {
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "number int53";
+        data: number;
+        driverParam: string | number;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        identity: undefined;
+        generated: undefined;
+      }>;
+      usedAt: import("drizzle-orm/pg-core").PgBuildColumn<"refresh_tokens", import("drizzle-orm/pg-core").PgBigInt53Builder, {
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "number int53";
+        data: number;
+        driverParam: string | number;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        identity: undefined;
+        generated: undefined;
+      }>;
+      profile: import("drizzle-orm/pg-core").PgBuildColumn<"refresh_tokens", import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>, {
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        identity: undefined;
+        generated: undefined;
+      }>;
+    };
+    dialect: "pg";
+  }>;
+};
+export declare const sqliteAuthTables: {
+  refreshTokens: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "refresh_tokens";
+    schema: undefined;
+    columns: {
+      tokenHash: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: true;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}>;
+      familyId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}>;
+      sid: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}>;
+      sub: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}>;
+      expiresAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "number int53";
+        data: number;
+        driverParam: number;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}>;
+      usedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "number int53";
+        data: number;
+        driverParam: number;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}>;
+      profile: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+        name: string;
+        tableName: "refresh_tokens";
+        dataType: "string";
+        data: string;
+        driverParam: string;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}>;
+    };
+    dialect: "sqlite";
+  }>;
+};
+//#endregion

package/dist/tables.js

@@ -0,0 +1,33 @@
+import { pgCol, pgTable, sqliteCol, sqliteTable } from "@homurajs/db/schema-helpers";
+import { index } from "drizzle-orm/pg-core";
+import { index as index$1 } from "drizzle-orm/sqlite-core";
+//#region src/tables.ts
+/**
+* 双方言 auth 表定义：App 把 pgAuthTables/sqliteAuthTables spread 进
+* 自己的 schema 参与迁移（refresh_tokens 表）。
+*
+* ⚠ 列名显式 snake_case，必须与 session/store.ts 的原生 SQL 严格对齐
+*   （token_hash/family_id/sid/sub/expires_at/used_at/profile）。
+*   parity 测试只比对 pg↔sqlite 两侧一致，测不出与原生 SQL 的偏差——
+*   改列名务必同步 store.ts，并以 drizzle-kit generate 的产物为准复核。
+*/
+const pgAuthTables = { refreshTokens: pgTable("refresh_tokens", {
+	tokenHash: pgCol.text("token_hash").primaryKey(),
+	familyId: pgCol.text("family_id").notNull(),
+	sid: pgCol.text("sid").notNull(),
+	sub: pgCol.text("sub").notNull(),
+	expiresAt: pgCol.epochMs("expires_at").notNull(),
+	usedAt: pgCol.epochMs("used_at"),
+	profile: pgCol.text("profile")
+}, (t) => [index("refresh_tokens_family_idx").on(t.familyId), index("refresh_tokens_sub_idx").on(t.sub)]) };
+const sqliteAuthTables = { refreshTokens: sqliteTable("refresh_tokens", {
+	tokenHash: sqliteCol.text("token_hash").primaryKey(),
+	familyId: sqliteCol.text("family_id").notNull(),
+	sid: sqliteCol.text("sid").notNull(),
+	sub: sqliteCol.text("sub").notNull(),
+	expiresAt: sqliteCol.epochMs("expires_at").notNull(),
+	usedAt: sqliteCol.epochMs("used_at"),
+	profile: sqliteCol.text("profile")
+}, (t) => [index$1("refresh_tokens_family_idx").on(t.familyId), index$1("refresh_tokens_sub_idx").on(t.sub)]) };
+//#endregion
+export { pgAuthTables, sqliteAuthTables };

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@homurajs/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "26.10.13",
+  "type": "module",
+  "description": "homura 认证：通用标准 OAuth2 (Authorization Code Flow) 客户端 + 自管 session（HS256 短 JWT + opaque refresh rotate）",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "import": "./dist/hono.js"
+    },
+    "./tables": {
+      "types": "./dist/tables.d.ts",
+      "import": "./dist/tables.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@homurajs/core": "26.10.13",
+    "@homurajs/db": "26.10.13",
+    "jose": "^6.0.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "1.0.0-rc.4",
+    "hono": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }