loginbase 1.3.0 → 1.5.0

package/README.md

@@ -17,12 +17,14 @@
 loginbase/                   # 本仓：TS 服务端库 + 协议契约
 ├── src/                     # TS 服务端库（Hono sub-app 工厂），从 Tono-Server 平移
 ├── test/                    # vitest
+├── queries/                 # 登录统计取数 SQL（人肉执行；口径见 docs/stats-design.md）
 ├── docs/
 │   ├── design.md            # 路线与仓库设计决策
 │   ├── server-design.md     # 服务端技术方案（公共 API/协议草案/会话模型/平移策略）
 │   ├── plan.md              # 实施计划（五步任务清单/验收点/版本线）
 │   ├── naming.md            # 命名讨论记录
 │   ├── protocol.md          # API 契约（唯一权威）——代码平移时落笔
+│   ├── email-identity.md    # 邮箱与身份锚点：**接入方必读**（GitHub 邮箱模型 / 为何不该拿邮箱找号 / 业界做法）
 │   └── logto-替换方案-调研.md # 背景调研（自 TrendingProjects 迁入）
 └── README.md
 
@@ -53,5 +55,10 @@ Kotlin 包    wang.harlon.loginbase
 
 ## 设计红线
 
-- 依赖最小集：服务端 hono + jose（+ zod-validator），客户端 ktor-client-core + kotlinx-serialization-json + kotlinx-coroutines-core。auth 库是供应链攻击的最高价值目标，每加一个依赖都要过一遍这个念头
+- 依赖准入（2026-08-18 由「依赖最小集」改判）：auth 库是供应链攻击的最高价值目标，所以**审查来源，而不是一味压数量**。放行三类，其余一律先停下来问值不值：
+  1. 现有基座——服务端 hono + jose（+ zod-validator），客户端 ktor-client-core + kotlinx-serialization-json + kotlinx-coroutines-core；
+  2. 业界权威库——四条判据全满足：① 生态事实标准，组织或多人维护、发布节奏稳定；② 发布带 provenance / trusted publishing（npm）或签名（Maven Central）；③ 传递依赖 ≤ 2 且同样满足 ①；④ 无安装脚本；
+  3. 自己的库（`HarlonWang/*`）——同样走 trusted publishing 发布，在库里优先声明为 peerDependency，由消费方定版本
+
+  仍然拒绝：为省几十行代码的工具包、单人维护的新包或小众包、运行时联网或带安装脚本的包、为一个功能拖进整个框架的包。版本钉死 + lockfile + provenance 不变
 - 协议变更：服务端实现 + `docs/protocol.md` 同一个 commit，并在 `loginbase-kt` 仓开跟进 issue，客户端版本落地前不关（2026-08-13 由 monorepo 三位一体改判，理由见 design.md）

package/dist/config.d.ts

@@ -100,6 +100,33 @@ 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;
+    };
+    /**
+     * 应用商店审核用的演示账号（Play 与 App Store 共用一个）：命中该邮箱时
+     * `/code/send` 不真实发信、验证码恒为该固定值；其余一切（限流、存码、
+     * verify、建会话）与常规账号完全一致。动因：无密码登录交不出商店要的
+     * 静态凭据，TrendingAI 1.4.1 因此被 Play 拒过。**未配置即完全不存在这条路径。**
+     *
+     * 该码等同这个账号的永久密码：**必须走 secret、不得入库**，且**不能用真实
+     * 用户的邮箱**（否则谁拿到码就能登进那个真人的账号）。
+     */
+    demoAccount?: {
+        /** 比对时 trim + 转小写 */
+        email: string;
+        /** 与真码同形（6 位数字），客户端才无需特判；trim 后非 6 位数字视同未配置 */
+        code: string;
+    };
     onVerified: OnVerified;
     /** 提供后才启用 link 端点（未提供 → 404 not_configured，默认关闭、显式启用） */
     onLinked?: OnLinked;

package/dist/demo_account.d.ts

@@ -0,0 +1,6 @@
+import type { LoginConfig } from "./config.js";
+/** 解析该邮箱是否命中演示账号：命中返回解析结果，否则 null。
+ *  email 须已 trim+小写。未配置恒 null。 */
+export declare function matchDemoAccount(config: LoginConfig, email: string): {
+    code: string;
+} | null;

package/dist/demo_account.js

@@ -0,0 +1,11 @@
+/** 解析该邮箱是否命中演示账号：命中返回解析结果，否则 null。
+ *  email 须已 trim+小写。未配置恒 null。 */
+export function matchDemoAccount(config, email) {
+    const demo = config.demoAccount;
+    if (!demo || demo.email.trim().toLowerCase() !== email)
+        return null;
+    const code = demo.code.trim();
+    // 配错的码（空串/非 6 位数字）视同未配置：verify 把缺失的 code 字段读成
+    // 空串，空演示码等于免凭据登录——宁可演示账号登不进，也不能开这个口
+    return /^\d{6}$/.test(code) ? { code } : null;
+}

package/dist/handler.js

@@ -9,13 +9,17 @@ import { createSession, hashRefreshToken, findSession, rotateSession, revokeFami
 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 { matchDemoAccount } from "./demo_account.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;
+    // 统计事件统一出口：内部先喂 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;
@@ -30,28 +34,46 @@ export function createAuthApp(getConfig, basePath) {
         if (!/^\S+@\S+\.\S+$/.test(raw)) {
             return c.json({ error: "invalid_email" }, 400);
         }
+        // 演示账号（见 demo_account.ts）：码为固定值且不真实发信，其余与常规一致。
+        // 解析放在限流之前，撞限流的演示流量才带得上 demo 标
+        const demo = matchDemoAccount(cfg(c), raw);
         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", ...(demo ? { demo: true } : {}) },
+            });
             return c.json({ error: "too_many_requests", retryAfterSeconds: rl.retryAfterSeconds }, 429);
         }
-        const code = generateCode();
+        const code = demo?.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, locale.locale);
-        }
-        catch {
-            return c.json({ error: "internal" }, 500);
+        if (demo === null) {
+            try {
+                await sendCodeEmail(cfg(c).email, raw, code, locale.locale);
+            }
+            catch (err) {
+                // 发信失败此前不留任何痕迹；邮件是邮箱登录的命脉，断了整条链就没了。
+                // Resend 的 HTTP 码在错误串里，聚合时再解析（不为此改造 email.ts 的抛错形态）。
+                track(c, { event: "code_send_failed", meta: { message: String(err) } });
+                return c.json({ error: "internal" }, 500);
+            }
         }
         // 静默回落意味着「为什么收到英文邮件」在别处查不出来，故选中语言必须留痕
-        emitEvent({
+        track(c, {
             event: "code_sent",
-            locale: {
-                resolved: locale.locale,
-                ...(locale.requested ? { requested: locale.requested } : {}),
-                ...(locale.fallback ? { fallback: true } : {}),
+            meta: {
+                ...(demo ? { demo: true } : {}),
+                locale: {
+                    resolved: locale.locale,
+                    ...(locale.requested ? { requested: locale.requested } : {}),
+                    ...(locale.fallback ? { fallback: true } : {}),
+                },
             },
         });
         await storeCode(cfg(c).kv, raw, code);
@@ -64,15 +86,24 @@ export function createAuthApp(getConfig, basePath) {
             .catch(() => ({}));
         const email = trimmedField(body.email).toLowerCase();
         const code = trimmedField(body.code);
+        // 演示账号在 verify 无任何行为分叉；仅给事件补 meta.demo，
+        // 否则审核员的登录会混进真实登录漏斗（code_verify 不带 userId，事后剔不掉）
+        const isDemo = matchDemoAccount(cfg(c), email) !== null;
+        const t = (e) => track(c, isDemo ? { ...e, meta: { ...e.meta, demo: true } } : e);
         const stored = await readCode(cfg(c).kv, email);
-        if (!stored)
+        if (!stored) {
+            // 过期、已焚、从未发过、已用过——在 KV 层都表现为读不到，无法再分（C3 口径）
+            t({ 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);
+                t({ event: "code_verify", outcome: "too_many_attempts" });
                 return c.json({ error: "too_many_attempts" }, 429);
             }
+            t({ event: "code_verify", outcome: "invalid_code" });
             return c.json({ error: "invalid_code" }, 400);
         }
         await deleteCode(cfg(c).kv, email);
@@ -89,6 +120,7 @@ export function createAuthApp(getConfig, basePath) {
             });
         }
         catch {
+            t({ event: "code_verify", outcome: "internal" });
             return c.json({ error: "internal" }, 500);
         }
         const { sessionId, refreshToken } = await createSession(cfg(c).db, {
@@ -98,6 +130,15 @@ export function createAuthApp(getConfig, basePath) {
             expiresAt: sessionExpiry(c),
         });
         const accessToken = await signAccessToken(cfg(c).jwt.secret, verified.userId, sessionId, accessTtl(c));
+        t({ event: "code_verify", outcome: "ok" });
+        // 「登录成功」的唯一口径落点：客户端拿到 token 对。GitHub 轨的同名事件在
+        // /oauth/exchange 发（那里才是客户端真正拿到 token 的时刻）。
+        t({
+            event: "login",
+            provider: "email",
+            userId: verified.userId,
+            ...(verified.isNewUser !== undefined ? { isNewUser: verified.isNewUser } : {}),
+        });
         return c.json({
             accessToken,
             refreshToken,
@@ -111,11 +152,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) {
@@ -124,37 +171,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) => {
@@ -162,11 +228,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/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.3.0",
+  "version": "1.5.0",
   "description": "Shared login foundation for Cloudflare Workers: email OTP + social OAuth + session management, as a Hono sub-app factory.",
   "type": "module",
   "license": "MIT",