loginbase 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harlon Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# loginbase
+
+> The shared login foundation for my apps — email OTP + social OAuth + session management.
+> Cloudflare Workers server library + Kotlin Multiplatform client.
+
+多 App 共用的登录底座：邮箱验证码登录、社交 OAuth（GitHub 等）、会话管理（refresh 轮换 + 重用检测 + 丢回执救活）。服务端库跑在各 App 自己的 Cloudflare Worker 里（数据在各自 D1，不做中心化账号），客户端库以 Kotlin Multiplatform 提供。
+
+## 由来
+
+- 起点是 TrendingAI 替换 Logto 的调研（邮箱登录被迫走托管 web 页、CN 链路差），结论选定自建，见 [docs/logto-替换方案-调研.md](docs/logto-替换方案-调研.md)
+- 服务端实现的母本是 Tono-Server 已在生产验证的邮箱验证码登录（含全套测试），本仓库是它的抽取 + 泛化
+- 路线选择（公共库而非中心化服务）与仓库设计见 [docs/design.md](docs/design.md)，命名记录见 [docs/naming.md](docs/naming.md)
+
+## 结构（monorepo：一份协议，两个产物）
+
+```
+loginbase/
+├── src/                     # TS 服务端库（Hono sub-app 工厂），从 Tono-Server 平移
+├── test/                    # vitest
+├── kotlin/                  # KMP 客户端库（独立 gradle 工程）
+├── docs/
+│   ├── design.md            # 路线与仓库设计决策
+│   ├── server-design.md     # 服务端技术方案（公共 API/协议草案/会话模型/平移策略）
+│   ├── plan.md              # 实施计划（五步任务清单/验收点/版本线）
+│   ├── naming.md            # 命名讨论记录
+│   ├── protocol.md          # API 契约（唯一权威）——代码平移时落笔
+│   └── logto-替换方案-调研.md # 背景调研（自 TrendingProjects 迁入）
+└── README.md
+```
+
+## 产物坐标
+
+```
+仓库        HarlonWang/loginbase
+npm         loginbase        （npm registry，tag 触发 CI 发布）
+Maven       wang.harlon:loginbase-kt     （Maven Central，tag 触发 CI 发布）
+Kotlin 包    wang.harlon.loginbase
+```
+
+## 状态与路线
+
+当前进行到**落地第 1 步**（服务端平移：库侧完成，48 测试全绿；待发 0.1.0 + Tono-Server 切换）。落地顺序：
+
+1. 从 Tono-Server 平移服务端代码与测试，Tono-Server 改为依赖本包（其现有测试即抽取验收）
+2. 钩子化（`onVerified` 用户回调）+ zh/en 邮件模板 + github-oauth 可选插件
+3. TrendingAI 后端接入（`/auth` 挂载 + requireAuth 双轨 + Logto 存量迁移）
+4. KMP 客户端库 + TrendingAI 登录 UI（commonMain）
+5. Tono-Android 择机换用 loginbase-kt 的 android target
+
+## 设计红线
+
+- 依赖最小集：服务端 hono + jose（+ zod-validator），客户端 ktor + kotlinx-serialization + multiplatform-settings。auth 库是供应链攻击的最高价值目标，每加一个依赖都要过一遍这个念头
+- 协议变更必须服务端 + 客户端 + `docs/protocol.md` 同一个 commit；单一版本线，一个 tag 同时锁定两端

package/dist/code.d.ts

@@ -0,0 +1,12 @@
+export declare const CODE_TTL_SECONDS = 600;
+export declare const MAX_ATTEMPTS = 5;
+export interface StoredCode {
+    code: string;
+    attempts: number;
+    issuedAt: number;
+}
+export declare function generateCode(): string;
+export declare function storeCode(kv: KVNamespace, email: string, code: string): Promise<void>;
+export declare function readCode(kv: KVNamespace, email: string): Promise<StoredCode | null>;
+export declare function deleteCode(kv: KVNamespace, email: string): Promise<void>;
+export declare function incrementAttempts(kv: KVNamespace, email: string, stored: StoredCode): Promise<number>;

package/dist/code.js

@@ -0,0 +1,28 @@
+export const CODE_TTL_SECONDS = 600;
+export const MAX_ATTEMPTS = 5;
+export function generateCode() {
+    const array = new Uint32Array(1);
+    crypto.getRandomValues(array);
+    return (array[0] % 1_000_000).toString().padStart(6, "0");
+}
+export async function storeCode(kv, email, code) {
+    const payload = { code, attempts: 0, issuedAt: Date.now() };
+    await kv.put(`code:${email}`, JSON.stringify(payload), {
+        expirationTtl: CODE_TTL_SECONDS,
+    });
+}
+export async function readCode(kv, email) {
+    const raw = await kv.get(`code:${email}`);
+    return raw ? JSON.parse(raw) : null;
+}
+export async function deleteCode(kv, email) {
+    await kv.delete(`code:${email}`);
+}
+export async function incrementAttempts(kv, email, stored) {
+    stored.attempts += 1;
+    const remainingTtl = Math.max(1, CODE_TTL_SECONDS - Math.floor((Date.now() - stored.issuedAt) / 1000));
+    await kv.put(`code:${email}`, JSON.stringify(stored), {
+        expirationTtl: remainingTtl,
+    });
+    return stored.attempts;
+}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import type { EmailConfig } from "./email";
+export interface LoginConfig {
+    db: D1Database;
+    kv: KVNamespace;
+    jwt: {
+        secret: string;
+    };
+    email: EmailConfig;
+}
+export interface CreateLoginOptions {
+    /** 路由前缀，默认 "/auth"。静态选项（Hono app 构建期即需要），不进 env-依赖的 config。 */
+    basePath?: string;
+}
+export declare function memoizeResolver<TEnv>(resolve: (env: TEnv) => LoginConfig): (env: TEnv) => LoginConfig;

package/dist/config.js

@@ -0,0 +1,15 @@
+// Workers 的 binding 只在请求期以 env 出现，模块顶层拿不到；resolver 让库在
+// 请求时取配置，并按 env 对象记忆化（同一 isolate 内 env 恒定，WeakMap 即缓存）。
+export function memoizeResolver(resolve) {
+    const cache = new WeakMap();
+    return (env) => {
+        if (typeof env !== "object" || env === null)
+            return resolve(env);
+        const cached = cache.get(env);
+        if (cached)
+            return cached;
+        const cfg = resolve(env);
+        cache.set(env, cfg);
+        return cfg;
+    };
+}

package/dist/email.d.ts

@@ -0,0 +1,5 @@
+export interface EmailConfig {
+    resendApiKey: string;
+    from: string;
+}
+export declare function sendCodeEmail(config: EmailConfig, email: string, code: string): Promise<void>;

package/dist/email.js

@@ -0,0 +1,34 @@
+const RESEND_ENDPOINT = "https://api.resend.com/emails";
+export async function sendCodeEmail(config, email, code) {
+    const body = {
+        from: config.from,
+        to: [email],
+        subject: `Your Tono verification code: ${code}`,
+        html: renderHtml(code),
+        text: renderText(code),
+    };
+    const res = await fetch(RESEND_ENDPOINT, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.resendApiKey}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const msg = await res.text().catch(() => "");
+        throw new Error(`Resend failed: ${res.status} ${msg}`);
+    }
+}
+function renderHtml(code) {
+    return `
+    <div style="font-family:-apple-system,BlinkMacSystemFont,sans-serif;padding:24px;">
+      <h2 style="margin:0 0 16px 0;">Your Tono verification code</h2>
+      <p style="font-size:32px;letter-spacing:8px;font-weight:700;margin:16px 0;">${code}</p>
+      <p style="color:#666;font-size:14px;">This code expires in 10 minutes. If you didn't request it, you can ignore this email.</p>
+    </div>
+  `;
+}
+function renderText(code) {
+    return `Your Tono verification code is ${code}. It expires in 10 minutes.`;
+}

package/dist/handler.d.ts

@@ -0,0 +1,5 @@
+import { type AuthVariables } from "./middleware";
+import type { LoginConfig } from "./config";
+export declare function createAuthApp<TEnv>(getConfig: (env: TEnv) => LoginConfig, basePath: string): import("hono/hono-base").HonoBase<{
+    Variables: AuthVariables;
+}, import("hono/types").BlankSchema, string, string>;

package/dist/handler.js

@@ -0,0 +1,182 @@
+// 从 Tono-Server src/auth/handler.ts 原样平移（落地第 1 步，铁律 3）。
+// 仅两类机械改动：c.env.X 读取改为 config 注入、import 路径调整。
+// 内联的用户 upsert / 90 天试用 / /me 端点为 Tono 业务语义，暂留库内，
+// 第 2 步钩子化（onVerified）时移回 Tono。
+import { Hono } from "hono";
+import { generateCode, storeCode, readCode, deleteCode, incrementAttempts, MAX_ATTEMPTS, } from "./code";
+import { sendCodeEmail } from "./email";
+import { checkSendRateLimit, recordSend } from "./rate_limit";
+import { createSession, hashRefreshToken, findSession, rotateSession, revokeFamily, tryRescueSession, revokeSession, revokeAllForUser, } from "./session";
+import { signAccessToken } from "./token";
+import { createAuthMiddleware } from "./middleware";
+import { logEvent } from "./log";
+// 新用户注册赠送的 Pro 试用时长（3 个月）
+const TRIAL_PERIOD_MS = 90 * 24 * 60 * 60 * 1000;
+export function createAuthApp(getConfig, basePath) {
+    const authMiddleware = createAuthMiddleware(getConfig);
+    const auth = new Hono().basePath(basePath);
+    const cfg = (c) => getConfig(c.env);
+    auth.post("/code/send", async (c) => {
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const raw = (body.email ?? "").trim().toLowerCase();
+        if (!/^\S+@\S+\.\S+$/.test(raw)) {
+            return c.json({ error: "invalid_email" }, 400);
+        }
+        const ip = c.req.header("CF-Connecting-IP") ?? "unknown";
+        const rl = await checkSendRateLimit(cfg(c).kv, raw, ip);
+        if (!rl.allowed) {
+            return c.json({ error: "too_many_requests", retryAfterSeconds: rl.retryAfterSeconds }, 429);
+        }
+        const code = generateCode();
+        try {
+            await sendCodeEmail(cfg(c).email, raw, code);
+        }
+        catch {
+            return c.json({ error: "internal" }, 500);
+        }
+        await storeCode(cfg(c).kv, raw, code);
+        await recordSend(cfg(c).kv, raw, ip);
+        return c.json({ cooldownSeconds: 60 }, 200);
+    });
+    auth.post("/code/verify", async (c) => {
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const email = (body.email ?? "").trim().toLowerCase();
+        const code = (body.code ?? "").trim();
+        const stored = await readCode(cfg(c).kv, email);
+        if (!stored)
+            return c.json({ error: "code_expired" }, 400);
+        if (stored.code !== code) {
+            const attempts = await incrementAttempts(cfg(c).kv, email, stored);
+            if (attempts >= MAX_ATTEMPTS) {
+                await deleteCode(cfg(c).kv, email);
+                return c.json({ error: "too_many_attempts" }, 429);
+            }
+            return c.json({ error: "invalid_code" }, 400);
+        }
+        await deleteCode(cfg(c).kv, email);
+        const now = Date.now();
+        let user = await cfg(c)
+            .db.prepare("SELECT id, email, pro_expires_at, created_at FROM users WHERE email = ?")
+            .bind(email)
+            .first();
+        let isNewUser = false;
+        if (!user) {
+            const id = crypto.randomUUID();
+            const proExpiresAt = now + TRIAL_PERIOD_MS;
+            await cfg(c)
+                .db.prepare("INSERT INTO users (id, email, pro_expires_at, created_at) VALUES (?, ?, ?, ?)")
+                .bind(id, email, proExpiresAt, now)
+                .run();
+            user = { id, email, pro_expires_at: proExpiresAt, created_at: now };
+            isNewUser = true;
+        }
+        const userAgent = c.req.header("User-Agent") ?? null;
+        const ip = c.req.header("CF-Connecting-IP") ?? null;
+        const { sessionId, refreshToken } = await createSession(cfg(c).db, {
+            userId: user.id,
+            userAgent: userAgent ?? undefined,
+            ip: ip ?? undefined,
+        });
+        const accessToken = await signAccessToken(cfg(c).jwt.secret, user.id, sessionId);
+        return c.json({
+            accessToken,
+            refreshToken,
+            user: {
+                id: user.id,
+                email: user.email,
+                isPro: user.pro_expires_at != null && user.pro_expires_at > now,
+                proExpiresAt: user.pro_expires_at,
+                createdAt: user.created_at,
+            },
+            isNewUser,
+        });
+    });
+    auth.post("/refresh", async (c) => {
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const token = (body.refreshToken ?? "").trim();
+        if (!token) {
+            return c.json({ error: "invalid_refresh_token", reason: "missing_token" }, 401);
+        }
+        const sessionId = await hashRefreshToken(token);
+        const row = await findSession(cfg(c).db, sessionId);
+        if (!row) {
+            return c.json({ error: "invalid_refresh_token", reason: "session_not_found" }, 401);
+        }
+        if (row.revoked_at !== null) {
+            // 已轮换的 token 被再次提交：可能是"丢回执的诚实重试"，先尝试救活。
+            const userAgent = c.req.header("User-Agent") ?? undefined;
+            const ip = c.req.header("CF-Connecting-IP") ?? undefined;
+            const rescue = await tryRescueSession(cfg(c).db, row, { userAgent, ip });
+            if (rescue.status === "rescued") {
+                logEvent({
+                    event: "refresh",
+                    outcome: "rescued",
+                    userId: row.user_id,
+                    familyId: row.family_id,
+                    ip: ip ?? null,
+                });
+                const accessToken = await signAccessToken(cfg(c).jwt.secret, row.user_id, rescue.session.sessionId);
+                return c.json({ accessToken, refreshToken: rescue.session.refreshToken });
+            }
+            // 救活不成立 → 判定真重用，撤销整条会话链。guardrail 与 not_eligible 分开记录。
+            await revokeFamily(cfg(c).db, row.family_id);
+            logEvent({
+                event: "refresh",
+                outcome: rescue.status === "guardrail" ? "guardrail_revoked" : "reuse_revoked",
+                userId: row.user_id,
+                familyId: row.family_id,
+                ip: ip ?? null,
+            });
+            return c.json({ error: "invalid_refresh_token", reason: "session_revoked" }, 401);
+        }
+        if (row.expires_at !== null && row.expires_at <= Date.now()) {
+            return c.json({ error: "invalid_refresh_token", reason: "session_expired" }, 401);
+        }
+        const userAgent = c.req.header("User-Agent") ?? undefined;
+        const ip = c.req.header("CF-Connecting-IP") ?? undefined;
+        const next = await rotateSession(cfg(c).db, sessionId, { userAgent, ip });
+        if (!next) {
+            return c.json({ error: "invalid_refresh_token", reason: "rotate_failed" }, 401);
+        }
+        const accessToken = await signAccessToken(cfg(c).jwt.secret, row.user_id, next.sessionId);
+        return c.json({ accessToken, refreshToken: next.refreshToken });
+    });
+    // 返回当前登录用户的最新信息（含实时 Pro 状态），供客户端在前台/启动时刷新本地缓存，
+    // 无需重新登录即可感知服务端 pro_expires_at 的变化（续费 / 到期 / 手动赠送）。
+    auth.get("/me", authMiddleware, async (c) => {
+        const userId = c.get("userId");
+        const row = await cfg(c)
+            .db.prepare("SELECT id, email, pro_expires_at, created_at FROM users WHERE id = ?")
+            .bind(userId)
+            .first();
+        if (!row)
+            return c.json({ error: "user_not_found" }, 404);
+        const now = Date.now();
+        return c.json({
+            id: row.id,
+            email: row.email,
+            isPro: row.pro_expires_at != null && row.pro_expires_at > now,
+            proExpiresAt: row.pro_expires_at,
+            createdAt: row.created_at,
+        });
+    });
+    auth.delete("/sessions", authMiddleware, async (c) => {
+        const sessionId = c.get("sessionId");
+        if (!sessionId)
+            return c.json({ error: "unauthorized" }, 401);
+        await revokeSession(cfg(c).db, sessionId);
+        return c.body(null, 204);
+    });
+    auth.delete("/sessions/all", authMiddleware, async (c) => {
+        const userId = c.get("userId");
+        await revokeAllForUser(cfg(c).db, userId);
+        return c.body(null, 204);
+    });
+    return auth;
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { Hono } from "hono";
+import type { MiddlewareHandler } from "hono";
+import { type CreateLoginOptions, type LoginConfig } from "./config";
+import { type AuthVariables } from "./middleware";
+export interface Login<TEnv> {
+    /** Hono 实例（已含 basePath）。Hono 消费方：app.route("/", login.app) */
+    app: Hono<{
+        Variables: AuthVariables;
+    }>;
+    /** 裸 JS Worker 一行挂载：if (pathname.startsWith("/auth")) return login.fetch(req, env, ctx) */
+    fetch: (request: Request, env: TEnv, ctx?: ExecutionContext) => Response | Promise<Response>;
+    /** Hono 中间件：Bearer 校验，set userId / sessionId */
+    middleware: MiddlewareHandler<{
+        Variables: AuthVariables;
+    }>;
+}
+export declare function createLogin<TEnv = unknown>(resolve: (env: TEnv) => LoginConfig, options?: CreateLoginOptions): Login<TEnv>;
+export type { LoginConfig, CreateLoginOptions } from "./config";
+export type { AuthVariables } from "./middleware";
+export { createAuthMiddleware } from "./middleware";
+export * from "./code";
+export * from "./email";
+export * from "./rate_limit";
+export * from "./session";
+export * from "./token";
+export { logEvent } from "./log";

package/dist/index.js

@@ -0,0 +1,21 @@
+import { memoizeResolver } from "./config";
+import { createAuthApp } from "./handler";
+import { createAuthMiddleware } from "./middleware";
+export function createLogin(resolve, options = {}) {
+    const getConfig = memoizeResolver(resolve);
+    const app = createAuthApp(getConfig, options.basePath ?? "/auth");
+    return {
+        app,
+        fetch: (request, env, ctx) => app.fetch(request, env, ctx),
+        middleware: createAuthMiddleware(getConfig),
+    };
+}
+export { createAuthMiddleware } from "./middleware";
+// 底层模块出口：verifyAccessToken 供裸 Worker 的 requireAuth 双轨；
+// session/code 等出口供消费方测试工具（如 Tono test/helpers）复用。
+export * from "./code";
+export * from "./email";
+export * from "./rate_limit";
+export * from "./session";
+export * from "./token";
+export { logEvent } from "./log";

package/dist/log.d.ts

@@ -0,0 +1 @@
+export declare function logEvent(event: Record<string, unknown>): void;

package/dist/log.js

@@ -0,0 +1,5 @@
+// 结构化事件日志：输出一行 JSON，便于 Cloudflare Workers Logs 过滤与聚合。
+// observability 已在 wrangler.toml 开启（head_sampling_rate 1.0）。
+export function logEvent(event) {
+    console.log(JSON.stringify(event));
+}

package/dist/middleware.d.ts

@@ -0,0 +1,9 @@
+import type { MiddlewareHandler } from "hono";
+import type { LoginConfig } from "./config";
+export interface AuthVariables {
+    userId: string;
+    sessionId?: string;
+}
+export declare function createAuthMiddleware<TEnv>(getConfig: (env: TEnv) => LoginConfig): MiddlewareHandler<{
+    Variables: AuthVariables;
+}>;

package/dist/middleware.js

@@ -0,0 +1,22 @@
+import { jwtVerify } from "jose";
+export function createAuthMiddleware(getConfig) {
+    return async (c, next) => {
+        const header = c.req.header("Authorization");
+        if (!header?.startsWith("Bearer ")) {
+            return c.json({ error: "Unauthorized" }, 401);
+        }
+        const token = header.slice(7);
+        try {
+            const secret = new TextEncoder().encode(getConfig(c.env).jwt.secret);
+            const { payload } = await jwtVerify(token, secret);
+            c.set("userId", payload.sub);
+            if (typeof payload.sid === "string") {
+                c.set("sessionId", payload.sid);
+            }
+            await next();
+        }
+        catch {
+            return c.json({ error: "Invalid token" }, 401);
+        }
+    };
+}

package/dist/rate_limit.d.ts

@@ -0,0 +1,6 @@
+export interface RateLimitResult {
+    allowed: boolean;
+    retryAfterSeconds: number;
+}
+export declare function checkSendRateLimit(kv: KVNamespace, email: string, ip: string): Promise<RateLimitResult>;
+export declare function recordSend(kv: KVNamespace, email: string, ip: string): Promise<void>;

package/dist/rate_limit.js

@@ -0,0 +1,31 @@
+const COOLDOWN_SECONDS = 60;
+const EMAIL_WINDOW_SECONDS = 600;
+const EMAIL_MAX_IN_WINDOW = 3;
+const IP_WINDOW_SECONDS = 3600;
+const IP_MAX_IN_WINDOW = 10;
+export async function checkSendRateLimit(kv, email, ip) {
+    const cooldown = await kv.get(`cooldown:${email}`);
+    if (cooldown) {
+        return { allowed: false, retryAfterSeconds: COOLDOWN_SECONDS };
+    }
+    const emailCount = parseInt((await kv.get(`rl:email:${email}`)) ?? "0", 10);
+    if (emailCount >= EMAIL_MAX_IN_WINDOW) {
+        return { allowed: false, retryAfterSeconds: EMAIL_WINDOW_SECONDS };
+    }
+    const ipCount = parseInt((await kv.get(`rl:ip:${ip}`)) ?? "0", 10);
+    if (ipCount >= IP_MAX_IN_WINDOW) {
+        return { allowed: false, retryAfterSeconds: IP_WINDOW_SECONDS };
+    }
+    return { allowed: true, retryAfterSeconds: 0 };
+}
+export async function recordSend(kv, email, ip) {
+    await kv.put(`cooldown:${email}`, "1", { expirationTtl: COOLDOWN_SECONDS });
+    const emailKey = `rl:email:${email}`;
+    const emailCount = parseInt((await kv.get(emailKey)) ?? "0", 10);
+    await kv.put(emailKey, String(emailCount + 1), {
+        expirationTtl: EMAIL_WINDOW_SECONDS,
+    });
+    const ipKey = `rl:ip:${ip}`;
+    const ipCount = parseInt((await kv.get(ipKey)) ?? "0", 10);
+    await kv.put(ipKey, String(ipCount + 1), { expirationTtl: IP_WINDOW_SECONDS });
+}

package/dist/session.d.ts

@@ -0,0 +1,49 @@
+export declare const REFRESH_TOKEN_BYTES = 32;
+export interface SessionRow {
+    id: string;
+    user_id: string;
+    family_id: string;
+    expires_at: number | null;
+    created_at: number;
+    last_used_at: number;
+    user_agent: string | null;
+    ip: string | null;
+    revoked_at: number | null;
+    replaced_by_id: string | null;
+    rescued_at: number | null;
+}
+export interface CreateSessionInput {
+    userId: string;
+    userAgent?: string;
+    ip?: string;
+}
+export interface CreateSessionOutput {
+    sessionId: string;
+    refreshToken: string;
+    familyId: string;
+}
+export declare function generateRefreshToken(): string;
+export declare function hashRefreshToken(token: string): Promise<string>;
+export declare function createSession(db: D1Database, input: CreateSessionInput): Promise<CreateSessionOutput>;
+export declare function findSession(db: D1Database, sessionId: string): Promise<SessionRow | null>;
+export declare function rotateSession(db: D1Database, oldSessionId: string, meta: {
+    userAgent?: string;
+    ip?: string;
+}): Promise<CreateSessionOutput | null>;
+export declare const RESCUE_WINDOW_MS: number;
+export declare const RESCUE_LIMIT = 3;
+export type RescueResult = {
+    status: "rescued";
+    session: CreateSessionOutput;
+} | {
+    status: "not_eligible";
+} | {
+    status: "guardrail";
+};
+export declare function tryRescueSession(db: D1Database, revoked: SessionRow, meta: {
+    userAgent?: string;
+    ip?: string;
+}): Promise<RescueResult>;
+export declare function revokeFamily(db: D1Database, familyId: string): Promise<void>;
+export declare function revokeSession(db: D1Database, sessionId: string): Promise<void>;
+export declare function revokeAllForUser(db: D1Database, userId: string): Promise<void>;

package/dist/session.js

@@ -0,0 +1,111 @@
+export const REFRESH_TOKEN_BYTES = 32;
+export function generateRefreshToken() {
+    const bytes = new Uint8Array(REFRESH_TOKEN_BYTES);
+    crypto.getRandomValues(bytes);
+    return btoa(String.fromCharCode(...bytes))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+export async function hashRefreshToken(token) {
+    const data = new TextEncoder().encode(token);
+    const buf = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(buf))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+export async function createSession(db, input) {
+    const refreshToken = generateRefreshToken();
+    const sessionId = await hashRefreshToken(refreshToken);
+    const familyId = crypto.randomUUID();
+    const now = Date.now();
+    await db
+        .prepare(`INSERT INTO sessions (id, user_id, family_id, expires_at, created_at, last_used_at, user_agent, ip, revoked_at, replaced_by_id)
+       VALUES (?, ?, ?, NULL, ?, ?, ?, ?, NULL, NULL)`)
+        .bind(sessionId, input.userId, familyId, now, now, input.userAgent ?? null, input.ip ?? null)
+        .run();
+    return { sessionId, refreshToken, familyId };
+}
+export async function findSession(db, sessionId) {
+    return await db
+        .prepare("SELECT * FROM sessions WHERE id = ?")
+        .bind(sessionId)
+        .first();
+}
+export async function rotateSession(db, oldSessionId, meta) {
+    const old = await findSession(db, oldSessionId);
+    if (!old)
+        return null;
+    const refreshToken = generateRefreshToken();
+    const newId = await hashRefreshToken(refreshToken);
+    const now = Date.now();
+    await db.batch([
+        db
+            .prepare(`INSERT INTO sessions (id, user_id, family_id, expires_at, created_at, last_used_at, user_agent, ip, revoked_at, replaced_by_id)
+         VALUES (?, ?, ?, NULL, ?, ?, ?, ?, NULL, NULL)`)
+            .bind(newId, old.user_id, old.family_id, now, now, meta.userAgent ?? old.user_agent, meta.ip ?? old.ip),
+        db
+            .prepare("UPDATE sessions SET revoked_at = ?, replaced_by_id = ? WHERE id = ? AND revoked_at IS NULL")
+            .bind(now, newId, oldSessionId),
+    ]);
+    return { sessionId: newId, refreshToken, familyId: old.family_id };
+}
+// 救活护栏：同一 family 在窗口内允许的最大救活次数。
+// 正常的"丢回执诚实重试"每次最多触发 1 次救活（拿到新证后即不再用旧链）；
+// 持续超限只可能是 token 被盗后多方交替使用，超限即按真重用撤销整链。
+export const RESCUE_WINDOW_MS = 60 * 60 * 1000;
+export const RESCUE_LIMIT = 3;
+async function recentRescueCount(db, familyId, since) {
+    const row = await db
+        .prepare("SELECT COUNT(*) AS n FROM sessions WHERE family_id = ? AND rescued_at IS NOT NULL AND rescued_at > ?")
+        .bind(familyId, since)
+        .first();
+    return row?.n ?? 0;
+}
+// 丢回执诚实重试的救活：presented 的 token 已被轮换（revoked），但它的直接后继
+// 仍 active（会话链未被第二方推进）—— 说明客户端没收到上次轮换的回执、手里只剩旧
+// token。此时从后继再轮换一次、发一套可用的新证，避免误把整条链当成 token 重用杀掉。
+export async function tryRescueSession(db, revoked, meta) {
+    if (revoked.replaced_by_id === null)
+        return { status: "not_eligible" };
+    const successor = await findSession(db, revoked.replaced_by_id);
+    if (!successor || successor.revoked_at !== null)
+        return { status: "not_eligible" };
+    const now = Date.now();
+    if ((await recentRescueCount(db, revoked.family_id, now - RESCUE_WINDOW_MS)) >= RESCUE_LIMIT) {
+        return { status: "guardrail" };
+    }
+    const refreshToken = generateRefreshToken();
+    const newId = await hashRefreshToken(refreshToken);
+    await db.batch([
+        db
+            .prepare(`INSERT INTO sessions (id, user_id, family_id, expires_at, created_at, last_used_at, user_agent, ip, revoked_at, replaced_by_id, rescued_at)
+         VALUES (?, ?, ?, NULL, ?, ?, ?, ?, NULL, NULL, ?)`)
+            .bind(newId, successor.user_id, successor.family_id, now, now, meta.userAgent ?? successor.user_agent, meta.ip ?? successor.ip, now),
+        db
+            .prepare("UPDATE sessions SET revoked_at = ?, replaced_by_id = ? WHERE id = ? AND revoked_at IS NULL")
+            .bind(now, newId, successor.id),
+    ]);
+    return {
+        status: "rescued",
+        session: { sessionId: newId, refreshToken, familyId: successor.family_id },
+    };
+}
+export async function revokeFamily(db, familyId) {
+    await db
+        .prepare("UPDATE sessions SET revoked_at = ? WHERE family_id = ? AND revoked_at IS NULL")
+        .bind(Date.now(), familyId)
+        .run();
+}
+export async function revokeSession(db, sessionId) {
+    await db
+        .prepare("UPDATE sessions SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL")
+        .bind(Date.now(), sessionId)
+        .run();
+}
+export async function revokeAllForUser(db, userId) {
+    await db
+        .prepare("UPDATE sessions SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL")
+        .bind(Date.now(), userId)
+        .run();
+}

package/dist/token.d.ts

@@ -0,0 +1,8 @@
+import { type JWTPayload } from "jose";
+export declare const ACCESS_TTL_SECONDS = 3600;
+export interface AccessPayload extends JWTPayload {
+    sub: string;
+    sid: string;
+}
+export declare function signAccessToken(secret: string, userId: string, sessionId: string): Promise<string>;
+export declare function verifyAccessToken(secret: string, token: string): Promise<AccessPayload>;

package/dist/token.js

@@ -0,0 +1,15 @@
+import { SignJWT, jwtVerify } from "jose";
+export const ACCESS_TTL_SECONDS = 3600;
+export async function signAccessToken(secret, userId, sessionId) {
+    const key = new TextEncoder().encode(secret);
+    return new SignJWT({ sub: userId, sid: sessionId })
+        .setProtectedHeader({ alg: "HS256" })
+        .setIssuedAt()
+        .setExpirationTime(`${ACCESS_TTL_SECONDS}s`)
+        .sign(key);
+}
+export async function verifyAccessToken(secret, token) {
+    const key = new TextEncoder().encode(secret);
+    const { payload } = await jwtVerify(token, key);
+    return payload;
+}

package/migrations/0001_sessions.sql

@@ -0,0 +1,20 @@
+-- loginbase 会话表（Tono-Server migrations 0002_create_sessions + 0004_add_session_rescue 的合并端态）。
+-- id 即 refresh token 的 SHA-256 hex；user_id 由业务侧提供，库只存不读。
+-- rescued_at 非 NULL 表示该行由救活逻辑（从存活后继再轮换）产生，
+-- 用于统计同一 family 在时间窗口内的救活次数，超限即按真重用撤销整链。
+CREATE TABLE IF NOT EXISTS sessions (
+  id              TEXT PRIMARY KEY,
+  user_id         TEXT NOT NULL,
+  family_id       TEXT NOT NULL,
+  expires_at      INTEGER,
+  created_at      INTEGER NOT NULL,
+  last_used_at    INTEGER NOT NULL,
+  user_agent      TEXT,
+  ip              TEXT,
+  revoked_at      INTEGER,
+  replaced_by_id  TEXT,
+  rescued_at      INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_user_id   ON sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_family_id ON sessions(family_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_rescued   ON sessions(family_id, rescued_at);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "loginbase",
+  "version": "0.1.0",
+  "description": "Shared login foundation for Cloudflare Workers: email OTP + social OAuth + session management, as a Hono sub-app factory.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HarlonWang/loginbase.git"
+  },
+  "homepage": "https://github.com/HarlonWang/loginbase#readme",
+  "keywords": [
+    "auth",
+    "login",
+    "email-otp",
+    "session",
+    "cloudflare-workers",
+    "hono"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "hono": "^4.12.8"
+  },
+  "dependencies": {
+    "jose": "^6.2.1"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "~0.13.1",
+    "@cloudflare/workers-types": "~4.20260317.1",
+    "hono": "^4.12.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "wrangler": "~4.74.0"
+  },
+  "allowScripts": {
+    "workerd@1.20260317.1": true,
+    "workerd@1.20260312.1": true
+  }
+}