loginbase 1.2.0 → 1.4.0

package/README.md

@@ -53,5 +53,5 @@ Kotlin 包    wang.harlon.loginbase
 
 ## 设计红线
 
-- 依赖最小集：服务端 hono + jose（+ zod-validator），客户端 ktor + kotlinx-serialization + multiplatform-settings。auth 库是供应链攻击的最高价值目标，每加一个依赖都要过一遍这个念头
+- 依赖最小集：服务端 hono + jose（+ zod-validator），客户端 ktor-client-core + kotlinx-serialization-json + kotlinx-coroutines-core。auth 库是供应链攻击的最高价值目标，每加一个依赖都要过一遍这个念头
 - 协议变更：服务端实现 + `docs/protocol.md` 同一个 commit，并在 `loginbase-kt` 仓开跟进 issue，客户端版本落地前不关（2026-08-13 由 monorepo 三位一体改判，理由见 design.md）

package/dist/config.d.ts

@@ -100,6 +100,18 @@ export interface LoginConfig {
         /** refresh 会话滑动过期（每次轮换重新起算）；null/缺省 = 不过期 */
         refreshTtlMs?: number | null;
     };
+    /**
+     * 登录统计（方案见 docs/stats-design.md）。事件写入 `db` 的 `auth_events` 表，
+     * 不引入新 binding、不加依赖。
+     *
+     * **默认开启**——数据不能补录，忘配开关就是白丢一段时期的数据；代价（升级后
+     * 未跑 migration 0002）由 stats.ts 的三条 fail-safe 兜住：异常吞掉、异步写、
+     * 首次失败告警一次。
+     */
+    stats?: {
+        /** 默认 true；置 false 则一条统计都不写 */
+        enabled?: boolean;
+    };
     onVerified: OnVerified;
     /** 提供后才启用 link 端点（未提供 → 404 not_configured，默认关闭、显式启用） */
     onLinked?: OnLinked;

package/dist/email.d.ts

@@ -1,17 +1,70 @@
-export interface EmailTemplates {
-    subject(code: string): string;
-    html(code: string): string;
-    text(code: string): string;
+/** 模板渲染上下文（2.0.0：由裸 code 参数改为 ctx 对象） */
+export interface TemplateContext {
+    code: string;
+    brand?: string;
+    /** 本封邮件的「选中语言」——已归一化的 BCP 47 标签 */
+    locale: string;
+    /** 收件地址（已归一化小写） */
+    email: string;
+    /** 验证码有效期，解开「10 分钟」写死在文案里的约定耦合 */
+    ttlMinutes: number;
+}
+export type TemplatePart = (ctx: TemplateContext) => string;
+/** 三件皆可选：内置已有的语言可以只覆盖其中一件，其余由内置同语言补齐 */
+export interface EmailTemplate {
+    subject?: TemplatePart;
+    html?: TemplatePart;
+    text?: TemplatePart;
 }
 export interface EmailConfig {
     resendApiKey: string;
     from: string;
-    /** 品牌名，注入内置模板的标题与正文；不影响 templates 整体覆盖 */
+    /** 品牌名，经 ctx.brand 送达内置模板与消费方模板 */
     brand?: string;
-    /** 内置模板语言，默认 "en" */
-    locale?: "en" | "zh";
-    /** 整体覆盖模板；提供时 brand/locale 不生效 */
-    templates?: EmailTemplates;
+    /**
+     * 客户端没说时用哪个语言（2.0.0：原 `locale`，语义由「本 App 邮件语言」正名为
+     * 「兜底语言」）。默认 "en"；配了库不支持的语言则回落 "en" 并告警。
+     */
+    fallbackLocale?: string;
+    /** 按 locale 键：覆盖内置语言的任意部件，或新增内置没有的语言（须三件齐全） */
+    templates?: Record<string, EmailTemplate>;
+}
+/**
+ * BCP 47 标签归一化：`_`→`-`（Android `Locale.toString()` 给的是 `zh_CN`，
+ * 只有 `toLanguageTag()` 才是 BCP 47）、转小写（大小写不敏感）、截断 64。
+ *
+ * 非字符串、空串、含 `[a-z0-9-]` 以外字符者一律返回 null＝「视为未传」：
+ * 这类值本就匹配不到任何语言，行为与未传等价，顺便把垃圾挡在事件日志之外。
+ *
+ * `und`（BCP 47 的「未确定语言」）同样归为未传——客户端取不到平台语言时可能传它，
+ * 若当成普通标签处理，它会匹配失败并留下 `fallback: true`，把「取不到语言」伪装成
+ * 「要了一门不支持的语言」，污染观测（见 plan.md 的哨兵口径）。
+ */
+export declare function normalizeLocale(value: unknown): string | null;
+export interface LocaleResolution {
+    /** 选中语言 */
+    locale: string;
+    /** 客户端传来并通过归一化的值（未传/非法时缺省） */
+    requested?: string;
+    /** true = 客户端要的语言没给到（未传不算回落） */
+    fallback: boolean;
 }
-export declare function resolveTemplates(config: EmailConfig): EmailTemplates;
-export declare function sendCodeEmail(config: EmailConfig, email: string, code: string): Promise<void>;
+/**
+ * 规则 ①：语言只解析一次——请求 → fallbackLocale → 库内置 en，第一个命中者胜。
+ * **静默回落，永不 4xx**：语言是展示偏好不是凭据，一个 4xx 会让用户登不进去。
+ */
+export declare function resolveEmailLocale(config: EmailConfig, requested: unknown): LocaleResolution;
+/**
+ * 规则 ②：模板在选中语言内部合并——内置打底，消费方逐部件覆盖，永不跨语言。
+ * （末尾的内置兜底只为防御式直调；走 resolveEmailLocale 的路径上取不到它。）
+ */
+export declare function resolveTemplate(config: EmailConfig, locale: string): Required<EmailTemplate>;
+/**
+ * 配置层面的问题清单（纯函数，便于测试）：
+ * - `incomplete`：给了内置没有的语言却没写全三件——他的模板一次都不会被用上，
+ *   而配置语法完全合法、从代码里看不出来，不报就只能靠用户投诉发现；
+ * - `unsupported_fallback`：兜底语言自己都不在支持集里，实际会用库内置 en。
+ */
+export declare function emailConfigWarnings(config: EmailConfig): Record<string, unknown>[];
+export declare function warnEmailConfigOnce(config: EmailConfig, emit: (event: Record<string, unknown>) => void): void;
+export declare function sendCodeEmail(config: EmailConfig, email: string, code: string, locale?: string): Promise<void>;

package/dist/email.js

@@ -1,19 +1,178 @@
-import { enTemplates } from "./templates/en.js";
-import { zhTemplates } from "./templates/zh.js";
+import { CODE_TTL_SECONDS } from "./code.js";
+import { enTemplate } from "./templates/en.js";
+import { zhTemplate } 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);
+const BUILTIN = {
+    en: enTemplate,
+    zh: zhTemplate,
+};
+const BUILTIN_FALLBACK_LOCALE = "en";
+const MAX_LOCALE_LENGTH = 64;
+const PARTS = ["subject", "html", "text"];
+/**
+ * BCP 47 标签归一化：`_`→`-`（Android `Locale.toString()` 给的是 `zh_CN`，
+ * 只有 `toLanguageTag()` 才是 BCP 47）、转小写（大小写不敏感）、截断 64。
+ *
+ * 非字符串、空串、含 `[a-z0-9-]` 以外字符者一律返回 null＝「视为未传」：
+ * 这类值本就匹配不到任何语言，行为与未传等价，顺便把垃圾挡在事件日志之外。
+ *
+ * `und`（BCP 47 的「未确定语言」）同样归为未传——客户端取不到平台语言时可能传它，
+ * 若当成普通标签处理，它会匹配失败并留下 `fallback: true`，把「取不到语言」伪装成
+ * 「要了一门不支持的语言」，污染观测（见 plan.md 的哨兵口径）。
+ */
+export function normalizeLocale(value) {
+    if (typeof value !== "string")
+        return null;
+    const tag = value.trim().slice(0, MAX_LOCALE_LENGTH).replace(/_/g, "-").toLowerCase();
+    if (tag === "" || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(tag))
+        return null;
+    if (tag === "und" || tag.startsWith("und-"))
+        return null;
+    return tag;
 }
-export async function sendCodeEmail(config, email, code) {
-    const templates = resolveTemplates(config);
+// 消费方模板的键同样要归一化（他可能写 "zh-Hant"），按 templates 对象记忆化
+const indexCache = new WeakMap();
+function customIndex(config) {
+    const src = config.templates;
+    if (!src)
+        return new Map();
+    const cached = indexCache.get(src);
+    if (cached)
+        return cached;
+    const index = new Map();
+    for (const [key, template] of Object.entries(src)) {
+        const tag = normalizeLocale(key);
+        if (tag && template)
+            index.set(tag, template);
+    }
+    indexCache.set(src, index);
+    return index;
+}
+function isComplete(template) {
+    return !!template && PARTS.every((p) => typeof template[p] === "function");
+}
+/**
+ * 支持集 = 库内置语言 ∪ { 消费方写全三件的语言 }。
+ *
+ * 判据不是「消费方写了几件」，而是「缺的几件能不能用**同一种语言**补上」：
+ * 内置已有的语言永远补得上，故部分覆盖合法；内置没有的语言只有消费方一个来源，
+ * 不写全就没人能补——此时判定该语言不成立，整封回落兜底语言（见 server-design.md
+ * 「为什么禁止跨语言混搭」）。
+ */
+function supports(config, locale) {
+    return locale in BUILTIN || isComplete(customIndex(config).get(locale));
+}
+/**
+ * RFC 4647 Lookup 简化版：逐级砍子标签（`zh-hans-cn`→`zh-hans`→`zh`），
+ * 不一步截到主语言——将来加繁体模板时 `zh-Hant` 才不会掉进简体。
+ */
+function lookup(tag, has) {
+    let current = tag;
+    for (;;) {
+        if (has(current))
+            return current;
+        const cut = current.lastIndexOf("-");
+        if (cut < 0)
+            return null;
+        current = current.slice(0, cut);
+    }
+}
+/**
+ * 规则 ①：语言只解析一次——请求 → fallbackLocale → 库内置 en，第一个命中者胜。
+ * **静默回落，永不 4xx**：语言是展示偏好不是凭据，一个 4xx 会让用户登不进去。
+ */
+export function resolveEmailLocale(config, requested) {
+    const has = (locale) => supports(config, locale);
+    const req = normalizeLocale(requested);
+    if (req) {
+        const hit = lookup(req, has);
+        if (hit)
+            return { locale: hit, requested: req, fallback: false };
+    }
+    const configured = normalizeLocale(config.fallbackLocale);
+    const locale = (configured ? lookup(configured, has) : null) ?? BUILTIN_FALLBACK_LOCALE;
+    return req
+        ? { locale, requested: req, fallback: true }
+        : { locale, fallback: false };
+}
+/**
+ * 规则 ②：模板在选中语言内部合并——内置打底，消费方逐部件覆盖，永不跨语言。
+ * （末尾的内置兜底只为防御式直调；走 resolveEmailLocale 的路径上取不到它。）
+ */
+export function resolveTemplate(config, locale) {
+    const custom = customIndex(config).get(locale);
+    const builtin = BUILTIN[locale];
+    const pick = (part) => custom?.[part] ?? builtin?.[part] ?? BUILTIN[BUILTIN_FALLBACK_LOCALE][part];
+    return { subject: pick("subject"), html: pick("html"), text: pick("text") };
+}
+/**
+ * 配置层面的问题清单（纯函数，便于测试）：
+ * - `incomplete`：给了内置没有的语言却没写全三件——他的模板一次都不会被用上，
+ *   而配置语法完全合法、从代码里看不出来，不报就只能靠用户投诉发现；
+ * - `unsupported_fallback`：兜底语言自己都不在支持集里，实际会用库内置 en。
+ */
+export function emailConfigWarnings(config) {
+    const warnings = [];
+    // 归一化认不出的键（如 "中文"、"zh Hant"）会被索引直接丢掉——语法合法、
+    // 却永远不会被任何请求命中，是彻底的死配置，不报就只能靠用户投诉发现
+    for (const key of Object.keys(config.templates ?? {})) {
+        if (normalizeLocale(key) === null) {
+            warnings.push({
+                event: "email_template_config",
+                status: "invalid_locale_key",
+                key,
+            });
+        }
+    }
+    for (const [locale, template] of customIndex(config)) {
+        if (locale in BUILTIN)
+            continue; // 内置能同语言补齐，部分覆盖合法
+        const missing = PARTS.filter((p) => typeof template[p] !== "function");
+        if (missing.length > 0) {
+            warnings.push({
+                event: "email_template_config",
+                status: "incomplete",
+                locale,
+                missing,
+            });
+        }
+    }
+    const configured = normalizeLocale(config.fallbackLocale);
+    if (configured && !lookup(configured, (l) => supports(config, l))) {
+        warnings.push({
+            event: "email_template_config",
+            status: "unsupported_fallback",
+            locale: configured,
+            resolved: BUILTIN_FALLBACK_LOCALE,
+        });
+    }
+    return warnings;
+}
+// 每个 config 对象只报一次（config 按 isolate 记忆化 → 等价于每实例一次）。
+// 不抛错、不阻断：模板配错不该让登录服务起不来，与「静默回落」同一取向。
+const warned = new WeakSet();
+export function warnEmailConfigOnce(config, emit) {
+    if (warned.has(config))
+        return;
+    warned.add(config);
+    for (const warning of emailConfigWarnings(config))
+        emit(warning);
+}
+export async function sendCodeEmail(config, email, code, locale = BUILTIN_FALLBACK_LOCALE) {
+    const template = resolveTemplate(config, locale);
+    const ctx = {
+        code,
+        brand: config.brand,
+        locale,
+        email,
+        ttlMinutes: Math.round(CODE_TTL_SECONDS / 60),
+    };
     const body = {
         from: config.from,
         to: [email],
-        subject: templates.subject(code),
-        html: templates.html(code),
-        text: templates.text(code),
+        subject: template.subject(ctx),
+        html: template.html(ctx),
+        text: template.text(ctx),
     };
     const res = await fetch(RESEND_ENDPOINT, {
         method: "POST",

package/dist/handler.js

@@ -3,12 +3,13 @@
 // 事件出口接 onEvent，refreshTtlMs / accessTtlSeconds 可配生效。
 import { Hono } from "hono";
 import { generateCode, storeCode, readCode, deleteCode, incrementAttempts, MAX_ATTEMPTS, } from "./code.js";
-import { sendCodeEmail } from "./email.js";
+import { sendCodeEmail, resolveEmailLocale, warnEmailConfigOnce, } 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 { createTracker } from "./stats.js";
 import { trimmedField } from "./body.js";
 import { registerGithubOauth } from "./plugins/github.js";
 export function createAuthApp(getConfig, basePath) {
@@ -16,6 +17,8 @@ export function createAuthApp(getConfig, basePath) {
     const auth = new Hono().basePath(basePath);
     const cfg = (c) => getConfig(c.env);
     const emit = (c) => cfg(c).onEvent ?? logEvent;
+    // 统计事件统一出口：内部先喂 onEvent（形态与 1.3.0 一致），再异步落 auth_events
+    const track = createTracker(getConfig);
     const accessTtl = (c) => cfg(c).jwt.accessTtlSeconds ?? ACCESS_TTL_SECONDS;
     const sessionExpiry = (c) => {
         const ttl = cfg(c).session?.refreshTtlMs ?? null;
@@ -33,15 +36,35 @@ export function createAuthApp(getConfig, basePath) {
         const ip = c.req.header("CF-Connecting-IP") ?? "unknown";
         const rl = await checkSendRateLimit(cfg(c).kv, raw, ip);
         if (!rl.allowed) {
+            // 命中限流不只是滥用信号，更是「用户发不出码」的体验问题——分层记录才知道
+            // 是自己手快（cooldown）还是真被挡住（email / ip 窗口）
+            track(c, { event: "rate_limited", outcome: rl.layer, meta: { endpoint: "code_send" } });
             return c.json({ error: "too_many_requests", retryAfterSeconds: rl.retryAfterSeconds }, 429);
         }
         const code = generateCode();
+        const emitEvent = emit(c);
+        warnEmailConfigOnce(cfg(c).email, emitEvent);
+        const locale = resolveEmailLocale(cfg(c).email, body.locale);
         try {
-            await sendCodeEmail(cfg(c).email, raw, code);
+            await sendCodeEmail(cfg(c).email, raw, code, locale.locale);
         }
-        catch {
+        catch (err) {
+            // 发信失败此前不留任何痕迹；邮件是邮箱登录的命脉，断了整条链就没了。
+            // Resend 的 HTTP 码在错误串里，聚合时再解析（不为此改造 email.ts 的抛错形态）。
+            track(c, { event: "code_send_failed", meta: { message: String(err) } });
             return c.json({ error: "internal" }, 500);
         }
+        // 静默回落意味着「为什么收到英文邮件」在别处查不出来，故选中语言必须留痕
+        track(c, {
+            event: "code_sent",
+            meta: {
+                locale: {
+                    resolved: locale.locale,
+                    ...(locale.requested ? { requested: locale.requested } : {}),
+                    ...(locale.fallback ? { fallback: true } : {}),
+                },
+            },
+        });
         await storeCode(cfg(c).kv, raw, code);
         await recordSend(cfg(c).kv, raw, ip);
         return c.json({ cooldownSeconds: 60 }, 200);
@@ -53,14 +76,19 @@ export function createAuthApp(getConfig, basePath) {
         const email = trimmedField(body.email).toLowerCase();
         const code = trimmedField(body.code);
         const stored = await readCode(cfg(c).kv, email);
-        if (!stored)
+        if (!stored) {
+            // 过期、已焚、从未发过、已用过——在 KV 层都表现为读不到，无法再分（C3 口径）
+            track(c, { event: "code_verify", outcome: "code_not_found" });
             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);
+                track(c, { event: "code_verify", outcome: "too_many_attempts" });
                 return c.json({ error: "too_many_attempts" }, 429);
             }
+            track(c, { event: "code_verify", outcome: "invalid_code" });
             return c.json({ error: "invalid_code" }, 400);
         }
         await deleteCode(cfg(c).kv, email);
@@ -77,6 +105,7 @@ export function createAuthApp(getConfig, basePath) {
             });
         }
         catch {
+            track(c, { event: "code_verify", outcome: "internal" });
             return c.json({ error: "internal" }, 500);
         }
         const { sessionId, refreshToken } = await createSession(cfg(c).db, {
@@ -86,6 +115,15 @@ export function createAuthApp(getConfig, basePath) {
             expiresAt: sessionExpiry(c),
         });
         const accessToken = await signAccessToken(cfg(c).jwt.secret, verified.userId, sessionId, accessTtl(c));
+        track(c, { event: "code_verify", outcome: "ok" });
+        // 「登录成功」的唯一口径落点：客户端拿到 token 对。GitHub 轨的同名事件在
+        // /oauth/exchange 发（那里才是客户端真正拿到 token 的时刻）。
+        track(c, {
+            event: "login",
+            provider: "email",
+            userId: verified.userId,
+            ...(verified.isNewUser !== undefined ? { isNewUser: verified.isNewUser } : {}),
+        });
         return c.json({
             accessToken,
             refreshToken,
@@ -99,11 +137,17 @@ export function createAuthApp(getConfig, basePath) {
             .catch(() => ({}));
         const token = trimmedField(body.refreshToken);
         if (!token) {
+            track(c, { event: "refresh", outcome: "invalid", meta: { reason: "missing_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) {
+            track(c, {
+                event: "refresh",
+                outcome: "invalid",
+                meta: { reason: "session_not_found" },
+            });
             return c.json({ error: "invalid_refresh_token", reason: "session_not_found" }, 401);
         }
         if (row.revoked_at !== null) {
@@ -112,37 +156,56 @@ export function createAuthApp(getConfig, basePath) {
             const ip = c.req.header("CF-Connecting-IP") ?? undefined;
             const rescue = await tryRescueSession(cfg(c).db, row, { userAgent, ip }, sessionExpiry(c));
             if (rescue.status === "rescued") {
-                emit(c)({
+                track(c, {
                     event: "refresh",
                     outcome: "rescued",
                     userId: row.user_id,
-                    familyId: row.family_id,
-                    ip: ip ?? null,
+                    meta: { familyId: row.family_id },
+                    hookOnly: { ip: ip ?? null },
                 });
                 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);
-            emit(c)({
+            track(c, {
                 event: "refresh",
                 outcome: rescue.status === "guardrail" ? "guardrail_revoked" : "reuse_revoked",
                 userId: row.user_id,
-                familyId: row.family_id,
-                ip: ip ?? null,
+                meta: { familyId: row.family_id },
+                hookOnly: { ip: ip ?? null },
             });
             return c.json({ error: "invalid_refresh_token", reason: "session_revoked" }, 401);
         }
         if (row.expires_at !== null && row.expires_at <= Date.now()) {
+            track(c, {
+                event: "refresh",
+                outcome: "invalid",
+                userId: row.user_id,
+                meta: { reason: "session_expired" },
+            });
             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 }, sessionExpiry(c));
         if (!next) {
+            track(c, {
+                event: "refresh",
+                outcome: "invalid",
+                userId: row.user_id,
+                meta: { reason: "rotate_failed" },
+            });
             return c.json({ error: "invalid_refresh_token", reason: "rotate_failed" }, 401);
         }
         const accessToken = await signAccessToken(cfg(c).jwt.secret, row.user_id, next.sessionId, accessTtl(c));
+        // 成功续期此前不发事件，救活率（F2）因此一直没有分母
+        track(c, {
+            event: "refresh",
+            outcome: "ok",
+            userId: row.user_id,
+            meta: { familyId: row.family_id },
+        });
         return c.json({ accessToken, refreshToken: next.refreshToken });
     });
     auth.delete("/sessions", authMiddleware, async (c) => {
@@ -150,11 +213,14 @@ export function createAuthApp(getConfig, basePath) {
         if (!sessionId)
             return c.json({ error: "unauthorized" }, 401);
         await revokeSession(cfg(c).db, sessionId);
+        // 主动登出与「被轮换而作废」在 sessions 表里长得很像，只有事件能干净区分
+        track(c, { event: "session_revoked", outcome: "current", userId: c.get("userId") });
         return c.body(null, 204);
     });
     auth.delete("/sessions/all", authMiddleware, async (c) => {
         const userId = c.get("userId");
         await revokeAllForUser(cfg(c).db, userId);
+        track(c, { event: "session_revoked", outcome: "all", userId });
         return c.body(null, 204);
     });
     registerGithubOauth(auth, getConfig, basePath);

package/dist/index.d.ts

@@ -24,3 +24,4 @@ export * from "./rate_limit.js";
 export * from "./session.js";
 export * from "./token.js";
 export { logEvent } from "./log.js";
+export { flushStats, type StatEvent } from "./stats.js";

package/dist/index.js

@@ -19,3 +19,5 @@ export * from "./rate_limit.js";
 export * from "./session.js";
 export * from "./token.js";
 export { logEvent } from "./log.js";
+// flushStats 供消费方测试等待异步写入落定；生产路径走 waitUntil，无需调用
+export { flushStats } from "./stats.js";

package/dist/plugins/github.js

@@ -2,6 +2,7 @@ import { trimmedField } from "../body.js";
 import { createAuthMiddleware } from "../middleware.js";
 import { generateRefreshToken as randomToken } from "../session.js";
 import { createSession } from "../session.js";
+import { createTracker } from "../stats.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";
@@ -122,6 +123,7 @@ export function registerGithubOauth(auth, getConfig, basePath) {
     const cfg = (c) => getConfig(c.env);
     const github = (c) => cfg(c).socials?.github;
     const authMiddleware = createAuthMiddleware(getConfig);
+    const track = createTracker(getConfig);
     const callbackUrlFor = (c, gh) => gh.callbackUrl ??
         `${new URL(c.req.url).origin}${basePath}/oauth/github/callback`;
     auth.get("/oauth/github/start", async (c) => {
@@ -130,13 +132,20 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             return c.json({ error: "not_configured" }, 404);
         const redirect = c.req.query("redirect") ?? "";
         if (!redirect || !redirectAllowed(redirect, gh)) {
+            track(c, {
+                event: "oauth_start",
+                outcome: "invalid_redirect",
+                provider: "github",
+            });
             return c.json({ error: "invalid_redirect" }, 400);
         }
         const state = randomToken();
-        const record = { redirect };
+        const flowId = crypto.randomUUID();
+        const record = { redirect, flowId };
         await cfg(c).kv.put(`oauth:state:${state}`, JSON.stringify(record), {
             expirationTtl: STATE_TTL_SECONDS,
         });
+        track(c, { event: "oauth_start", outcome: "ok", provider: "github", flowId });
         return c.redirect(buildAuthorizeUrl(gh, callbackUrlFor(c, gh), state), 302);
     });
     // 已登录用户绑定第二身份。**必须是 POST**：浏览器导航带不了 Authorization 头，
@@ -151,13 +160,33 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             .catch(() => ({}));
         const redirect = trimmedField(body.redirect);
         if (!redirect || !redirectAllowed(redirect, gh)) {
+            track(c, {
+                event: "oauth_start",
+                outcome: "invalid_redirect",
+                provider: "github",
+                meta: { mode: "link" },
+            });
             return c.json({ error: "invalid_redirect" }, 400);
         }
         const state = randomToken();
-        const record = { redirect, mode: "link", userId: c.get("userId") };
+        const flowId = crypto.randomUUID();
+        const record = {
+            redirect,
+            mode: "link",
+            userId: c.get("userId"),
+            flowId,
+        };
         await cfg(c).kv.put(`oauth:state:${state}`, JSON.stringify(record), {
             expirationTtl: STATE_TTL_SECONDS,
         });
+        track(c, {
+            event: "oauth_start",
+            outcome: "ok",
+            provider: "github",
+            userId: c.get("userId"),
+            flowId,
+            meta: { mode: "link" },
+        });
         return c.json({ authorizeUrl: buildAuthorizeUrl(gh, callbackUrlFor(c, gh), state) }, 200);
     });
     auth.get("/oauth/github/callback", async (c) => {
@@ -169,14 +198,30 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         const stateKey = `oauth:state:${state}`;
         const rawState = state ? await cfg(c).kv.get(stateKey) : null;
         if (!code || !rawState) {
-            // state 无效即回跳地址不可信，只能就地报错
+            // state 无效即回跳地址不可信，只能就地报错。
+            // 此分支拿不到 flowId——它就存在读不出来的那条 state 记录里。
+            track(c, {
+                event: "oauth_callback",
+                outcome: "invalid_state",
+                provider: "github",
+            });
             return c.json({ error: "invalid_state" }, 400);
         }
         await cfg(c).kv.delete(stateKey); // 单次使用，验证即焚
-        const { redirect, mode, userId } = JSON.parse(rawState);
+        const { redirect, mode, userId, flowId } = JSON.parse(rawState);
+        const trackCallback = (outcome, meta) => track(c, {
+            event: "oauth_callback",
+            outcome,
+            provider: "github",
+            ...(flowId ? { flowId } : {}),
+            ...(userId ? { userId } : {}),
+            meta: { mode: mode ?? "login", ...meta },
+        });
         const identity = await fetchGithubIdentity(gh, code);
-        if (!identity)
+        if (!identity) {
+            trackCallback("oauth_failed");
             return c.redirect(withParam(redirect, "error", "oauth_failed"), 302);
+        }
         const { ghUser, ghToken, email, verifiedEmails } = identity;
         const userAgent = c.req.header("User-Agent") ?? undefined;
         const ip = c.req.header("CF-Connecting-IP") ?? undefined;
@@ -193,6 +238,7 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             const onLinked = cfg(c).onLinked;
             // userId 由 link/start 写入，缺失只可能是载荷被篡改/降级，保守失败
             if (!onLinked || !userId) {
+                trackCallback("internal");
                 return c.redirect(withParam(redirect, "error", "internal"), 302);
             }
             let result;
@@ -201,22 +247,29 @@ export function registerGithubOauth(auth, getConfig, basePath) {
                 result = await onLinked({ userId, ...common, ...(email ? { email } : {}) });
             }
             catch {
+                trackCallback("internal");
                 return c.redirect(withParam(redirect, "error", "internal"), 302);
             }
             if (!result.ok) {
                 const reason = REASON_PATTERN.test(result.reason) ? result.reason : "internal";
+                // 冲突原因分布是消费方业务规则的体检表（E2）
+                trackCallback("link_conflict", { reason });
                 return c.redirect(withParam(redirect, "error", reason), 302);
             }
+            trackCallback("linked");
             return c.redirect(withParam(redirect, "linked", "github"), 302);
         }
         // ---- login 分支：email 是账号锚点，缺了就无法找号建号 ----
-        if (!email)
+        if (!email) {
+            trackCallback("no_email");
             return c.redirect(withParam(redirect, "error", "oauth_no_email"), 302);
+        }
         let verified;
         try {
             verified = await cfg(c).onVerified({ email, ...common });
         }
         catch {
+            trackCallback("internal");
             return c.redirect(withParam(redirect, "error", "internal"), 302);
         }
         const refreshTtlMs = cfg(c).session?.refreshTtlMs ?? null;
@@ -233,10 +286,22 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             refreshToken,
             ...(verified.isNewUser !== undefined ? { isNewUser: verified.isNewUser } : {}),
             ...(verified.user !== undefined ? { user: verified.user } : {}),
+            userId: verified.userId,
+            ...(flowId ? { flowId } : {}),
         };
         await cfg(c).kv.put(`oauth:otc:${otc}`, JSON.stringify(payload), {
             expirationTtl: OTC_TTL_SECONDS,
         });
+        // 服务端签发成功 ≠ 登录成功：客户端可能永远收不到这次回跳（回跳丢失 = D11）
+        track(c, {
+            event: "oauth_callback",
+            outcome: "issued",
+            provider: "github",
+            userId: verified.userId,
+            ...(flowId ? { flowId } : {}),
+            ...(verified.isNewUser !== undefined ? { isNewUser: verified.isNewUser } : {}),
+            meta: { mode: "login" },
+        });
         return c.redirect(withParam(redirect, "otc", otc), 302);
     });
     auth.post("/oauth/exchange", async (c) => {
@@ -249,9 +314,37 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         const otc = trimmedField(body.otc);
         const key = `oauth:otc:${otc}`;
         const raw = otc ? await cfg(c).kv.get(key) : null;
-        if (!raw)
+        if (!raw) {
+            // otc 过期（60s）或已被兑换；与「回跳压根没到达」是两回事，故分开记
+            track(c, {
+                event: "oauth_exchange",
+                outcome: "invalid_otc",
+                provider: "github",
+            });
             return c.json({ error: "invalid_otc" }, 400);
+        }
         await cfg(c).kv.delete(key); // 单次使用，兑换即焚
-        return c.json(JSON.parse(raw), 200);
+        // 解构即剥离：payload 的类型收窄回 OtcPayload，统计字段进不了响应体
+        const { userId, flowId, ...payload } = JSON.parse(raw);
+        const trace = {
+            ...(userId ? { userId } : {}),
+            ...(flowId ? { flowId } : {}),
+        };
+        track(c, {
+            event: "oauth_exchange",
+            outcome: "ok",
+            provider: "github",
+            ...trace,
+        });
+        // 「登录成功」的口径落点在此而非 callback：这里才是客户端真正拿到 token 对的时刻。
+        // 顺带一个好处：此处的 country 来自客户端自己的网络，而非浏览器（授权页往往
+        // 挂着代理），比 callback 的国家更接近用户真实位置。
+        track(c, {
+            event: "login",
+            provider: "github",
+            ...trace,
+            ...(payload.isNewUser !== undefined ? { isNewUser: payload.isNewUser } : {}),
+        });
+        return c.json(payload, 200);
     });
 }

package/dist/rate_limit.d.ts

@@ -1,6 +1,11 @@
 export interface RateLimitResult {
     allowed: boolean;
     retryAfterSeconds: number;
+    /**
+     * 被哪一层挡下（1.4.0 起，统计用）；allowed 时缺省。
+     * 显式给出而非由 retryAfterSeconds 反推——那三个值改一次，反推就错一次。
+     */
+    layer?: "cooldown" | "email" | "ip";
 }
 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

@@ -6,15 +6,15 @@ 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 };
+        return { allowed: false, retryAfterSeconds: COOLDOWN_SECONDS, layer: "cooldown" };
     }
     const emailCount = parseInt((await kv.get(`rl:email:${email}`)) ?? "0", 10);
     if (emailCount >= EMAIL_MAX_IN_WINDOW) {
-        return { allowed: false, retryAfterSeconds: EMAIL_WINDOW_SECONDS };
+        return { allowed: false, retryAfterSeconds: EMAIL_WINDOW_SECONDS, layer: "email" };
     }
     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: false, retryAfterSeconds: IP_WINDOW_SECONDS, layer: "ip" };
     }
     return { allowed: true, retryAfterSeconds: 0 };
 }

package/dist/stats.d.ts

@@ -0,0 +1,28 @@
+import type { LoginConfig } from "./config.js";
+export interface StatEvent {
+    event: string;
+    outcome?: string;
+    provider?: "email" | "github";
+    userId?: string;
+    /** 串联 OAuth 三段的标识；绝不可用 state / otc 充当（单次凭证不进长期表） */
+    flowId?: string;
+    isNewUser?: boolean;
+    /** 落 meta 列（JSON），并摊平进 onEvent */
+    meta?: Record<string, unknown>;
+    /** 只摊平进 onEvent，**不落表**（ip 等 v1 判定不入库的字段走这里） */
+    hookOnly?: Record<string, unknown>;
+}
+export declare function flushStats(): Promise<void>;
+export interface TrackContext {
+    env: unknown;
+    req: {
+        raw: Request;
+    };
+    /** Hono 在无 ExecutionContext 时访问此属性会抛，故所有读取都包在 try 内 */
+    executionCtx?: ExecutionContext;
+}
+/**
+ * 事件出口：先照原样喂 onEvent（消费方钩子，形态与 1.3.0 保持一致），
+ * 再异步写自己的表。两条路径并行——onEvent 是给消费方的，不被库劫持去写库表。
+ */
+export declare function createTracker<TEnv>(getConfig: (env: TEnv) => LoginConfig): (c: TrackContext, e: StatEvent) => void;

package/dist/stats.js

@@ -0,0 +1,94 @@
+import { logEvent } from "./log.js";
+/** 供测试等待异步写入完成；生产路径走 waitUntil，不依赖它 */
+const pending = new Set();
+export async function flushStats() {
+    await Promise.allSettled([...pending]);
+}
+// 按 config 对象记忆化（同 email.ts 的 warnEmailConfigOnce）：生产上 config 由
+// memoizeResolver 按 env 缓存，等价于每个 Worker 一次告警。
+const warnedConfigs = new WeakSet();
+const GEO_ABSENT = {
+    country: "unknown",
+    asn: null,
+    colo: null,
+    timezone: null,
+    city: null,
+    region: null,
+};
+/**
+ * 全部取自 Cloudflare 边缘的 `request.cf`——它在请求到达 Worker 前就已填好，
+ * 零外部依赖、无额外请求。本地 wrangler dev 与测试环境没有 cf，故整体兜底。
+ * 注意这是 **IP 归属地**，不是用户声明的位置：代理会显示出口所在地。
+ */
+function geoOf(c) {
+    try {
+        const cf = c.req.raw.cf;
+        if (!cf)
+            return GEO_ABSENT;
+        const str = (v) => (typeof v === "string" && v ? v : null);
+        return {
+            country: str(cf.country) ?? "unknown",
+            asn: typeof cf.asn === "number" ? cf.asn : null,
+            colo: str(cf.colo),
+            timezone: str(cf.timezone),
+            city: str(cf.city),
+            region: str(cf.region),
+        };
+    }
+    catch {
+        return GEO_ABSENT;
+    }
+}
+function defer(c, p) {
+    const tracked = p.finally(() => pending.delete(tracked));
+    pending.add(tracked);
+    try {
+        c.executionCtx?.waitUntil(tracked);
+    }
+    catch {
+        // 无 ExecutionContext（如 app.request() 直调）：写入照常进行，只是不被延长生命周期
+    }
+}
+async function writeEvent(db, e, geo, now) {
+    await db
+        .prepare(`INSERT INTO auth_events
+         (at, event, outcome, provider, user_id, flow_id, is_new_user,
+          country, asn, colo, timezone, city, region, source, meta)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'server', ?)`)
+        .bind(now, e.event, e.outcome ?? null, e.provider ?? null, e.userId ?? null, e.flowId ?? null, e.isNewUser === undefined ? null : e.isNewUser ? 1 : 0, geo.country, geo.asn, geo.colo, geo.timezone, geo.city, geo.region, e.meta ? JSON.stringify(e.meta) : null)
+        .run();
+}
+/**
+ * 事件出口：先照原样喂 onEvent（消费方钩子，形态与 1.3.0 保持一致），
+ * 再异步写自己的表。两条路径并行——onEvent 是给消费方的，不被库劫持去写库表。
+ */
+export function createTracker(getConfig) {
+    return (c, e) => {
+        const cfg = getConfig(c.env);
+        const onEvent = cfg.onEvent ?? logEvent;
+        onEvent({
+            event: e.event,
+            ...(e.outcome !== undefined ? { outcome: e.outcome } : {}),
+            ...(e.provider !== undefined ? { provider: e.provider } : {}),
+            ...(e.userId !== undefined ? { userId: e.userId } : {}),
+            ...(e.flowId !== undefined ? { flowId: e.flowId } : {}),
+            ...(e.isNewUser !== undefined ? { isNewUser: e.isNewUser } : {}),
+            ...e.meta,
+            ...e.hookOnly,
+        });
+        if (cfg.stats?.enabled === false)
+            return;
+        defer(c, writeEvent(cfg.db, e, geoOf(c), Date.now()).catch((err) => warnUnavailableOnce(cfg, onEvent, err)));
+    };
+}
+/** 最可能的原因是没执行 migration 0002。只告警一次，避免每请求刷屏。 */
+function warnUnavailableOnce(cfg, onEvent, err) {
+    if (warnedConfigs.has(cfg))
+        return;
+    warnedConfigs.add(cfg);
+    onEvent({
+        event: "stats_unavailable",
+        hint: "auth_events 写入失败，请执行 migration 0002；登录不受影响",
+        message: String(err),
+    });
+}

package/dist/templates/en.d.ts

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

package/dist/templates/en.js

@@ -1,15 +1,13 @@
 // 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) => `
+const title = (brand) => brand ? `Your ${brand} verification code` : "Your verification code";
+export const enTemplate = {
+    subject: (ctx) => `${title(ctx.brand)}: ${ctx.code}`,
+    html: (ctx) => `
     <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>
+      <h2 style="margin:0 0 16px 0;">${title(ctx.brand)}</h2>
+      <p style="font-size:32px;letter-spacing:8px;font-weight:700;margin:16px 0;">${ctx.code}</p>
+      <p style="color:#666;font-size:14px;">This code expires in ${ctx.ttlMinutes} minutes. If you didn't request it, you can ignore this email.</p>
     </div>
   `,
-        text: (code) => `${title} is ${code}. It expires in 10 minutes.`,
-    };
-}
+    text: (ctx) => `${title(ctx.brand)} is ${ctx.code}. It expires in ${ctx.ttlMinutes} minutes.`,
+};

package/dist/templates/zh.d.ts

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

package/dist/templates/zh.js

@@ -1,14 +1,12 @@
-export function zhTemplates(brand) {
-    const title = brand ? `${brand} 登录验证码` : "登录验证码";
-    return {
-        subject: (code) => `${title}：${code}`,
-        html: (code) => `
+const title = (brand) => (brand ? `${brand} 登录验证码` : "登录验证码");
+export const zhTemplate = {
+    subject: (ctx) => `${title(ctx.brand)}：${ctx.code}`,
+    html: (ctx) => `
     <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>
+      <h2 style="margin:0 0 16px 0;">${title(ctx.brand)}</h2>
+      <p style="font-size:32px;letter-spacing:8px;font-weight:700;margin:16px 0;">${ctx.code}</p>
+      <p style="color:#666;font-size:14px;">验证码 ${ctx.ttlMinutes} 分钟内有效。如果这不是你的操作，请忽略这封邮件。</p>
     </div>
   `,
-        text: (code) => `你的${title}是 ${code}，10 分钟内有效。`,
-    };
-}
+    text: (ctx) => `你的${title(ctx.brand)}是 ${ctx.code}，${ctx.ttlMinutes} 分钟内有效。`,
+};

package/migrations/0002_auth_events.sql

@@ -0,0 +1,26 @@
+-- 登录统计事件表（docs/stats-design.md v1）。归库所有，与 sessions 同库。
+-- 升级到 1.4.0 后必须执行本迁移：统计模块默认开启，表不存在时写入会失败
+-- （登录不受影响，会有一次 stats_unavailable 告警事件）。
+CREATE TABLE IF NOT EXISTS auth_events (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  at          INTEGER NOT NULL,               -- UTC 毫秒
+  event       TEXT    NOT NULL,
+  outcome     TEXT,
+  provider    TEXT,                           -- email | github
+  user_id     TEXT,
+  flow_id     TEXT,                           -- 串联 OAuth 三段，非凭证
+  is_new_user INTEGER,                        -- 0 | 1 | NULL
+  -- 地理字段：全部取自 Cloudflare 边缘的 request.cf，零外部依赖、无额外请求。
+  -- 是 IP 归属地而非用户声明位置，代理会显示出口所在地（见 stats-design.md K 组坑①）。
+  country     TEXT,                           -- ISO 3166-1 两位码，缺失落 'unknown'
+  asn         INTEGER,                        -- 自治域号，识别家宽 vs 云出口（K9）
+  colo        TEXT,                           -- Cloudflare 边缘节点码；与 country 不一致 = 流量绕道
+  timezone    TEXT,                           -- IANA 时区名
+  city        TEXT,                           -- 常为空；当前无指标使用（见 6.11）
+  region      TEXT,                           -- 同上
+  source      TEXT NOT NULL DEFAULT 'server', -- server | client（client 留给二期）
+  meta        TEXT                            -- JSON：familyId、locale、错误串等低频字段
+);
+CREATE INDEX IF NOT EXISTS idx_auth_events_at       ON auth_events(at);
+CREATE INDEX IF NOT EXISTS idx_auth_events_event_at ON auth_events(event, at);
+CREATE INDEX IF NOT EXISTS idx_auth_events_flow     ON auth_events(flow_id);

package/package.json

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