loginbase 0.1.0 → 1.0.0

package/README.md

@@ -39,7 +39,7 @@ Kotlin 包    wang.harlon.loginbase
 
 ## 状态与路线
 
-当前进行到**落地第 1 步**（服务端平移：库侧完成，48 测试全绿；待发 0.1.0 + Tono-Server 切换）。落地顺序：
+**落地第 1 步已完成**（2026-08-12）：`loginbase@0.1.1` 上线 npm（trusted publishing + provenance），Tono-Server 已切换依赖并部署生产（其 67 测试全绿即抽取验收）。下一步 = 第 2 步钩子化。落地顺序：
 
 1. 从 Tono-Server 平移服务端代码与测试，Tono-Server 改为依赖本包（其现有测试即抽取验收）
 2. 钩子化（`onVerified` 用户回调）+ zh/en 邮件模板 + github-oauth 可选插件

package/dist/config.d.ts

@@ -1,11 +1,49 @@
-import type { EmailConfig } from "./email";
+import type { EmailConfig } from "./email.js";
+export interface VerifiedIdentity {
+    email: string;
+    provider: "email" | "github";
+    providerUserId?: string;
+    requestMeta: {
+        ip?: string;
+        userAgent?: string;
+    };
+}
+export interface VerifiedResult {
+    userId: string;
+    isNewUser?: boolean;
+    user?: unknown;
+}
+export type OnVerified = (identity: VerifiedIdentity) => Promise<VerifiedResult> | VerifiedResult;
+export type OnEvent = (event: Record<string, unknown>) => void;
+export interface GithubSocialConfig {
+    clientId: string;
+    clientSecret: string;
+    /**
+     * OAuth 回跳 deepLink 白名单，如 ["trendingai://auth"]。
+     * 结构化匹配：scheme + host 精确一致，path 允许前缀扩展（防开放重定向）。
+     */
+    allowedRedirects: string[];
+    /** GitHub OAuth App 注册的回调地址；缺省由请求 origin + basePath 推导 */
+    callbackUrl?: string;
+}
 export interface LoginConfig {
     db: D1Database;
     kv: KVNamespace;
     jwt: {
         secret: string;
+        /** access token TTL，默认 3600s */
+        accessTtlSeconds?: number;
     };
     email: EmailConfig;
+    session?: {
+        /** refresh 会话滑动过期（每次轮换重新起算）；null/缺省 = 不过期 */
+        refreshTtlMs?: number | null;
+    };
+    onVerified: OnVerified;
+    onEvent?: OnEvent;
+    socials?: {
+        github?: GithubSocialConfig;
+    };
 }
 export interface CreateLoginOptions {
     /** 路由前缀，默认 "/auth"。静态选项（Hono app 构建期即需要），不进 env-依赖的 config。 */

package/dist/email.d.ts

@@ -1,5 +1,17 @@
+export interface EmailTemplates {
+    subject(code: string): string;
+    html(code: string): string;
+    text(code: string): string;
+}
 export interface EmailConfig {
     resendApiKey: string;
     from: string;
+    /** 品牌名，注入内置模板的标题与正文；不影响 templates 整体覆盖 */
+    brand?: string;
+    /** 内置模板语言，默认 "en" */
+    locale?: "en" | "zh";
+    /** 整体覆盖模板；提供时 brand/locale 不生效 */
+    templates?: EmailTemplates;
 }
+export declare function resolveTemplates(config: EmailConfig): EmailTemplates;
 export declare function sendCodeEmail(config: EmailConfig, email: string, code: string): Promise<void>;

package/dist/email.js

@@ -1,11 +1,19 @@
+import { enTemplates } from "./templates/en.js";
+import { zhTemplates } from "./templates/zh.js";
 const RESEND_ENDPOINT = "https://api.resend.com/emails";
+export function resolveTemplates(config) {
+    if (config.templates)
+        return config.templates;
+    return config.locale === "zh" ? zhTemplates(config.brand) : enTemplates(config.brand);
+}
 export async function sendCodeEmail(config, email, code) {
+    const templates = resolveTemplates(config);
     const body = {
         from: config.from,
         to: [email],
-        subject: `Your Tono verification code: ${code}`,
-        html: renderHtml(code),
-        text: renderText(code),
+        subject: templates.subject(code),
+        html: templates.html(code),
+        text: templates.text(code),
     };
     const res = await fetch(RESEND_ENDPOINT, {
         method: "POST",
@@ -20,15 +28,3 @@ export async function sendCodeEmail(config, email, code) {
         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

@@ -1,5 +1,5 @@
-import { type AuthVariables } from "./middleware";
-import type { LoginConfig } from "./config";
+import { type AuthVariables } from "./middleware.js";
+import type { LoginConfig } from "./config.js";
 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

@@ -1,21 +1,26 @@
-// 从 Tono-Server src/auth/handler.ts 原样平移（落地第 1 步，铁律 3）。
-// 仅两类机械改动：c.env.X 读取改为 config 注入、import 路径调整。
-// 内联的用户 upsert / 90 天试用 / /me 端点为 Tono 业务语义，暂留库内，
-// 第 2 步钩子化（onVerified）时移回 Tono。
+// 母本为 Tono-Server src/auth/handler.ts（第 1 步平移）；第 2 步钩子化：
+// 用户语义（users upsert / 试用 / /me）经 onVerified 移回 App 侧，
+// 事件出口接 onEvent，refreshTtlMs / accessTtlSeconds 可配生效。
 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;
+import { generateCode, storeCode, readCode, deleteCode, incrementAttempts, MAX_ATTEMPTS, } from "./code.js";
+import { sendCodeEmail } from "./email.js";
+import { checkSendRateLimit, recordSend } from "./rate_limit.js";
+import { createSession, hashRefreshToken, findSession, rotateSession, revokeFamily, tryRescueSession, revokeSession, revokeAllForUser, } from "./session.js";
+import { signAccessToken, ACCESS_TTL_SECONDS } from "./token.js";
+import { createAuthMiddleware } from "./middleware.js";
+import { logEvent } from "./log.js";
+import { registerGithubOauth } from "./plugins/github.js";
 export function createAuthApp(getConfig, basePath) {
     const authMiddleware = createAuthMiddleware(getConfig);
     const auth = new Hono().basePath(basePath);
     const cfg = (c) => getConfig(c.env);
+    const emit = (c) => cfg(c).onEvent ?? logEvent;
+    const accessTtl = (c) => cfg(c).jwt.accessTtlSeconds ?? ACCESS_TTL_SECONDS;
+    const sessionExpiry = (c) => {
+        const ttl = cfg(c).session?.refreshTtlMs ?? null;
+        // == null 而非 truthiness：0 是数值语义的「立即过期」，不是「不过期」
+        return ttl == null ? null : Date.now() + ttl;
+    };
     auth.post("/code/send", async (c) => {
         const body = await c.req
             .json()
@@ -58,41 +63,33 @@ export function createAuthApp(getConfig, basePath) {
             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") ?? undefined;
+        const ip = c.req.header("CF-Connecting-IP") ?? undefined;
+        // 用户语义（建号/试用/档案）全部在 App 侧钩子内完成；
+        // 钩子失败 → 500（码已焚，重新发码），会话在钩子成功后才创建。
+        let verified;
+        try {
+            verified = await cfg(c).onVerified({
+                email,
+                provider: "email",
+                requestMeta: { ip, userAgent },
+            });
+        }
+        catch {
+            return c.json({ error: "internal" }, 500);
         }
-        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,
+            userId: verified.userId,
+            userAgent,
+            ip,
+            expiresAt: sessionExpiry(c),
         });
-        const accessToken = await signAccessToken(cfg(c).jwt.secret, user.id, sessionId);
+        const accessToken = await signAccessToken(cfg(c).jwt.secret, verified.userId, sessionId, accessTtl(c));
         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,
+            ...(verified.user !== undefined ? { user: verified.user } : {}),
+            ...(verified.isNewUser !== undefined ? { isNewUser: verified.isNewUser } : {}),
         });
     });
     auth.post("/refresh", async (c) => {
@@ -112,21 +109,21 @@ export function createAuthApp(getConfig, basePath) {
             // 已轮换的 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 });
+            const rescue = await tryRescueSession(cfg(c).db, row, { userAgent, ip }, sessionExpiry(c));
             if (rescue.status === "rescued") {
-                logEvent({
+                emit(c)({
                     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);
+                const accessToken = await signAccessToken(cfg(c).jwt.secret, row.user_id, rescue.session.sessionId, accessTtl(c));
                 return c.json({ accessToken, refreshToken: rescue.session.refreshToken });
             }
             // 救活不成立 → 判定真重用，撤销整条会话链。guardrail 与 not_eligible 分开记录。
             await revokeFamily(cfg(c).db, row.family_id);
-            logEvent({
+            emit(c)({
                 event: "refresh",
                 outcome: rescue.status === "guardrail" ? "guardrail_revoked" : "reuse_revoked",
                 userId: row.user_id,
@@ -140,32 +137,13 @@ export function createAuthApp(getConfig, basePath) {
         }
         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 });
+        const next = await rotateSession(cfg(c).db, sessionId, { userAgent, ip }, sessionExpiry(c));
         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);
+        const accessToken = await signAccessToken(cfg(c).jwt.secret, row.user_id, next.sessionId, accessTtl(c));
         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)
@@ -178,5 +156,6 @@ export function createAuthApp(getConfig, basePath) {
         await revokeAllForUser(cfg(c).db, userId);
         return c.body(null, 204);
     });
+    registerGithubOauth(auth, getConfig, basePath);
     return auth;
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { Hono } from "hono";
 import type { MiddlewareHandler } from "hono";
-import { type CreateLoginOptions, type LoginConfig } from "./config";
-import { type AuthVariables } from "./middleware";
+import { type CreateLoginOptions, type LoginConfig } from "./config.js";
+import { type AuthVariables } from "./middleware.js";
 export interface Login<TEnv> {
     /** Hono 实例（已含 basePath）。Hono 消费方：app.route("/", login.app) */
     app: Hono<{
@@ -15,12 +15,12 @@ export interface Login<TEnv> {
     }>;
 }
 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";
+export type { LoginConfig, CreateLoginOptions, VerifiedIdentity, VerifiedResult, OnVerified, OnEvent, GithubSocialConfig, } from "./config.js";
+export type { AuthVariables } from "./middleware.js";
+export { createAuthMiddleware } from "./middleware.js";
+export * from "./code.js";
+export * from "./email.js";
+export * from "./rate_limit.js";
+export * from "./session.js";
+export * from "./token.js";
+export { logEvent } from "./log.js";

package/dist/index.js

@@ -1,6 +1,6 @@
-import { memoizeResolver } from "./config";
-import { createAuthApp } from "./handler";
-import { createAuthMiddleware } from "./middleware";
+import { memoizeResolver } from "./config.js";
+import { createAuthApp } from "./handler.js";
+import { createAuthMiddleware } from "./middleware.js";
 export function createLogin(resolve, options = {}) {
     const getConfig = memoizeResolver(resolve);
     const app = createAuthApp(getConfig, options.basePath ?? "/auth");
@@ -10,12 +10,12 @@ export function createLogin(resolve, options = {}) {
         middleware: createAuthMiddleware(getConfig),
     };
 }
-export { createAuthMiddleware } from "./middleware";
+export { createAuthMiddleware } from "./middleware.js";
 // 底层模块出口：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";
+export * from "./code.js";
+export * from "./email.js";
+export * from "./rate_limit.js";
+export * from "./session.js";
+export * from "./token.js";
+export { logEvent } from "./log.js";

package/dist/middleware.d.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import type { LoginConfig } from "./config";
+import type { LoginConfig } from "./config.js";
 export interface AuthVariables {
     userId: string;
     sessionId?: string;

package/dist/plugins/github.d.ts

@@ -0,0 +1,6 @@
+import type { Hono } from "hono";
+import type { LoginConfig } from "../config.js";
+import type { AuthVariables } from "../middleware.js";
+export declare function registerGithubOauth<TEnv>(auth: Hono<{
+    Variables: AuthVariables;
+}>, getConfig: (env: TEnv) => LoginConfig, basePath: string): void;

package/dist/plugins/github.js

@@ -0,0 +1,159 @@
+import { generateRefreshToken as randomToken } from "../session.js";
+import { createSession } from "../session.js";
+import { signAccessToken, ACCESS_TTL_SECONDS } from "../token.js";
+const GITHUB_AUTHORIZE = "https://github.com/login/oauth/authorize";
+const GITHUB_TOKEN = "https://github.com/login/oauth/access_token";
+const GITHUB_API_USER = "https://api.github.com/user";
+const GITHUB_API_EMAILS = "https://api.github.com/user/emails";
+const STATE_TTL_SECONDS = 600;
+const OTC_TTL_SECONDS = 60;
+// 结构化校验而非字符串前缀：startsWith("https://example.com") 会被
+// https://example.com.evil.com 绕过（开放重定向 → otc 泄露给攻击者域）。
+// scheme + host 精确匹配，path 只允许白名单条目的前缀扩展。
+function redirectAllowed(redirect, github) {
+    let target;
+    try {
+        target = new URL(redirect);
+    }
+    catch {
+        return false;
+    }
+    return github.allowedRedirects.some((allowed) => {
+        let base;
+        try {
+            base = new URL(allowed);
+        }
+        catch {
+            return false;
+        }
+        return (target.protocol === base.protocol &&
+            target.host === base.host &&
+            target.pathname.startsWith(base.pathname));
+    });
+}
+function withParam(url, key, value) {
+    return `${url}${url.includes("?") ? "&" : "?"}${key}=${encodeURIComponent(value)}`;
+}
+export function registerGithubOauth(auth, getConfig, basePath) {
+    const cfg = (c) => getConfig(c.env);
+    const github = (c) => cfg(c).socials?.github;
+    auth.get("/oauth/github/start", async (c) => {
+        const gh = github(c);
+        if (!gh)
+            return c.json({ error: "not_configured" }, 404);
+        const redirect = c.req.query("redirect") ?? "";
+        if (!redirect || !redirectAllowed(redirect, gh)) {
+            return c.json({ error: "invalid_redirect" }, 400);
+        }
+        const state = randomToken();
+        const record = { redirect };
+        await cfg(c).kv.put(`oauth:state:${state}`, JSON.stringify(record), {
+            expirationTtl: STATE_TTL_SECONDS,
+        });
+        const callbackUrl = gh.callbackUrl ??
+            `${new URL(c.req.url).origin}${basePath}/oauth/github/callback`;
+        const url = new URL(GITHUB_AUTHORIZE);
+        url.searchParams.set("client_id", gh.clientId);
+        url.searchParams.set("redirect_uri", callbackUrl);
+        url.searchParams.set("scope", "user:email");
+        url.searchParams.set("state", state);
+        return c.redirect(url.toString(), 302);
+    });
+    auth.get("/oauth/github/callback", async (c) => {
+        const gh = github(c);
+        if (!gh)
+            return c.json({ error: "not_configured" }, 404);
+        const code = c.req.query("code") ?? "";
+        const state = c.req.query("state") ?? "";
+        const stateKey = `oauth:state:${state}`;
+        const rawState = state ? await cfg(c).kv.get(stateKey) : null;
+        if (!code || !rawState) {
+            // state 无效即回跳地址不可信，只能就地报错
+            return c.json({ error: "invalid_state" }, 400);
+        }
+        await cfg(c).kv.delete(stateKey); // 单次使用，验证即焚
+        const { redirect } = JSON.parse(rawState);
+        // server-side 换 token：client_secret 只在此出现，客户端不可见
+        const tokenRes = await fetch(GITHUB_TOKEN, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({
+                client_id: gh.clientId,
+                client_secret: gh.clientSecret,
+                code,
+            }),
+        });
+        const tokenBody = tokenRes.ok
+            ? (await tokenRes.json().catch(() => null))
+            : null;
+        const ghToken = tokenBody?.access_token;
+        if (!ghToken)
+            return c.redirect(withParam(redirect, "error", "oauth_failed"), 302);
+        // GitHub API 要求 User-Agent
+        const ghHeaders = {
+            Authorization: `Bearer ${ghToken}`,
+            Accept: "application/vnd.github+json",
+            "User-Agent": "loginbase",
+        };
+        const userRes = await fetch(GITHUB_API_USER, { headers: ghHeaders });
+        if (!userRes.ok)
+            return c.redirect(withParam(redirect, "error", "oauth_failed"), 302);
+        const ghUser = (await userRes.json());
+        const emailsRes = await fetch(GITHUB_API_EMAILS, { headers: ghHeaders });
+        const emails = emailsRes.ok
+            ? (await emailsRes.json())
+            : [];
+        const email = emails.find((e) => e.primary && e.verified)?.email ??
+            emails.find((e) => e.verified)?.email;
+        if (!email)
+            return c.redirect(withParam(redirect, "error", "oauth_no_email"), 302);
+        const userAgent = c.req.header("User-Agent") ?? undefined;
+        const ip = c.req.header("CF-Connecting-IP") ?? undefined;
+        let verified;
+        try {
+            verified = await cfg(c).onVerified({
+                email: email.trim().toLowerCase(),
+                provider: "github",
+                providerUserId: String(ghUser.id),
+                requestMeta: { ip, userAgent },
+            });
+        }
+        catch {
+            return c.redirect(withParam(redirect, "error", "internal"), 302);
+        }
+        const refreshTtlMs = cfg(c).session?.refreshTtlMs ?? null;
+        const { sessionId, refreshToken } = await createSession(cfg(c).db, {
+            userId: verified.userId,
+            userAgent,
+            ip,
+            expiresAt: refreshTtlMs == null ? null : Date.now() + refreshTtlMs,
+        });
+        const accessToken = await signAccessToken(cfg(c).jwt.secret, verified.userId, sessionId, cfg(c).jwt.accessTtlSeconds ?? ACCESS_TTL_SECONDS);
+        const otc = randomToken();
+        const payload = {
+            accessToken,
+            refreshToken,
+            ...(verified.isNewUser !== undefined ? { isNewUser: verified.isNewUser } : {}),
+            ...(verified.user !== undefined ? { user: verified.user } : {}),
+        };
+        await cfg(c).kv.put(`oauth:otc:${otc}`, JSON.stringify(payload), {
+            expirationTtl: OTC_TTL_SECONDS,
+        });
+        return c.redirect(withParam(redirect, "otc", otc), 302);
+    });
+    auth.post("/oauth/exchange", async (c) => {
+        const gh = github(c);
+        if (!gh)
+            return c.json({ error: "not_configured" }, 404);
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const otc = (body.otc ?? "").trim();
+        const key = `oauth:otc:${otc}`;
+        const raw = otc ? await cfg(c).kv.get(key) : null;
+        if (!raw)
+            return c.json({ error: "invalid_otc" }, 400);
+        await cfg(c).kv.delete(key); // 单次使用，兑换即焚
+        return c.json(JSON.parse(raw), 200);
+    });
+}

package/dist/session.d.ts

@@ -16,6 +16,8 @@ export interface CreateSessionInput {
     userId: string;
     userAgent?: string;
     ip?: string;
+    /** 会话过期时刻（epoch ms）；缺省/null = 不过期 */
+    expiresAt?: number | null;
 }
 export interface CreateSessionOutput {
     sessionId: string;
@@ -29,7 +31,7 @@ export declare function findSession(db: D1Database, sessionId: string): Promise<
 export declare function rotateSession(db: D1Database, oldSessionId: string, meta: {
     userAgent?: string;
     ip?: string;
-}): Promise<CreateSessionOutput | null>;
+}, expiresAt?: number | null): Promise<CreateSessionOutput | null>;
 export declare const RESCUE_WINDOW_MS: number;
 export declare const RESCUE_LIMIT = 3;
 export type RescueResult = {
@@ -43,7 +45,7 @@ export type RescueResult = {
 export declare function tryRescueSession(db: D1Database, revoked: SessionRow, meta: {
     userAgent?: string;
     ip?: string;
-}): Promise<RescueResult>;
+}, expiresAt?: number | null): 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

@@ -21,8 +21,8 @@ export async function createSession(db, input) {
     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)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL)`)
+        .bind(sessionId, input.userId, familyId, input.expiresAt ?? null, now, now, input.userAgent ?? null, input.ip ?? null)
         .run();
     return { sessionId, refreshToken, familyId };
 }
@@ -32,7 +32,7 @@ export async function findSession(db, sessionId) {
         .bind(sessionId)
         .first();
 }
-export async function rotateSession(db, oldSessionId, meta) {
+export async function rotateSession(db, oldSessionId, meta, expiresAt = null) {
     const old = await findSession(db, oldSessionId);
     if (!old)
         return null;
@@ -42,8 +42,8 @@ export async function rotateSession(db, oldSessionId, meta) {
     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),
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL)`)
+            .bind(newId, old.user_id, old.family_id, expiresAt, 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),
@@ -65,7 +65,7 @@ async function recentRescueCount(db, familyId, since) {
 // 丢回执诚实重试的救活：presented 的 token 已被轮换（revoked），但它的直接后继
 // 仍 active（会话链未被第二方推进）—— 说明客户端没收到上次轮换的回执、手里只剩旧
 // token。此时从后继再轮换一次、发一套可用的新证，避免误把整条链当成 token 重用杀掉。
-export async function tryRescueSession(db, revoked, meta) {
+export async function tryRescueSession(db, revoked, meta, expiresAt = null) {
     if (revoked.replaced_by_id === null)
         return { status: "not_eligible" };
     const successor = await findSession(db, revoked.replaced_by_id);
@@ -80,8 +80,8 @@ export async function tryRescueSession(db, revoked, meta) {
     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),
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?)`)
+            .bind(newId, successor.user_id, successor.family_id, expiresAt, 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),

package/dist/templates/en.d.ts

@@ -0,0 +1,2 @@
+import type { EmailTemplates } from "../email.js";
+export declare function enTemplates(brand?: string): EmailTemplates;

package/dist/templates/en.js

@@ -0,0 +1,15 @@
+// en 模板即 Tono 生产模板的 brand 参数化：brand="Tono" 时输出与平移前逐字节一致。
+export function enTemplates(brand) {
+    const title = brand ? `Your ${brand} verification code` : "Your verification code";
+    return {
+        subject: (code) => `${title}: ${code}`,
+        html: (code) => `
+    <div style="font-family:-apple-system,BlinkMacSystemFont,sans-serif;padding:24px;">
+      <h2 style="margin:0 0 16px 0;">${title}</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>
+  `,
+        text: (code) => `${title} is ${code}. It expires in 10 minutes.`,
+    };
+}

package/dist/templates/zh.d.ts

@@ -0,0 +1,2 @@
+import type { EmailTemplates } from "../email.js";
+export declare function zhTemplates(brand?: string): EmailTemplates;

package/dist/templates/zh.js

@@ -0,0 +1,14 @@
+export function zhTemplates(brand) {
+    const title = brand ? `${brand} 登录验证码` : "登录验证码";
+    return {
+        subject: (code) => `${title}：${code}`,
+        html: (code) => `
+    <div style="font-family:-apple-system,BlinkMacSystemFont,'PingFang SC','Microsoft YaHei',sans-serif;padding:24px;">
+      <h2 style="margin:0 0 16px 0;">${title}</h2>
+      <p style="font-size:32px;letter-spacing:8px;font-weight:700;margin:16px 0;">${code}</p>
+      <p style="color:#666;font-size:14px;">验证码 10 分钟内有效。如果这不是你的操作，请忽略这封邮件。</p>
+    </div>
+  `,
+        text: (code) => `你的${title}是 ${code}，10 分钟内有效。`,
+    };
+}

package/dist/token.d.ts

@@ -4,5 +4,5 @@ export interface AccessPayload extends JWTPayload {
     sub: string;
     sid: string;
 }
-export declare function signAccessToken(secret: string, userId: string, sessionId: string): Promise<string>;
+export declare function signAccessToken(secret: string, userId: string, sessionId: string, ttlSeconds?: number): Promise<string>;
 export declare function verifyAccessToken(secret: string, token: string): Promise<AccessPayload>;

package/dist/token.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loginbase",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Shared login foundation for Cloudflare Workers: email OTP + social OAuth + session management, as a Hono sub-app factory.",
   "type": "module",
   "license": "MIT",