loginbase 1.4.0 → 1.6.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

@@ -112,6 +112,21 @@ export interface LoginConfig {
         /** 默认 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

@@ -11,6 +11,7 @@ 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);
@@ -33,31 +34,41 @@ 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" } });
+            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 (err) {
-            // 发信失败此前不留任何痕迹；邮件是邮箱登录的命脉，断了整条链就没了。
-            // Resend 的 HTTP 码在错误串里，聚合时再解析（不为此改造 email.ts 的抛错形态）。
-            track(c, { event: "code_send_failed", meta: { message: String(err) } });
-            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);
+            }
         }
         // 静默回落意味着「为什么收到英文邮件」在别处查不出来，故选中语言必须留痕
         track(c, {
             event: "code_sent",
             meta: {
+                ...(demo ? { demo: true } : {}),
                 locale: {
                     resolved: locale.locale,
                     ...(locale.requested ? { requested: locale.requested } : {}),
@@ -75,20 +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) {
             // 过期、已焚、从未发过、已用过——在 KV 层都表现为读不到，无法再分（C3 口径）
-            track(c, { event: "code_verify", outcome: "code_not_found" });
+            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);
-                track(c, { event: "code_verify", outcome: "too_many_attempts" });
+                t({ event: "code_verify", outcome: "too_many_attempts" });
                 return c.json({ error: "too_many_attempts" }, 429);
             }
-            track(c, { event: "code_verify", outcome: "invalid_code" });
+            t({ event: "code_verify", outcome: "invalid_code" });
             return c.json({ error: "invalid_code" }, 400);
         }
         await deleteCode(cfg(c).kv, email);
@@ -105,7 +120,7 @@ export function createAuthApp(getConfig, basePath) {
             });
         }
         catch {
-            track(c, { event: "code_verify", outcome: "internal" });
+            t({ event: "code_verify", outcome: "internal" });
             return c.json({ error: "internal" }, 500);
         }
         const { sessionId, refreshToken } = await createSession(cfg(c).db, {
@@ -115,10 +130,10 @@ 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" });
+        t({ event: "code_verify", outcome: "ok" });
         // 「登录成功」的唯一口径落点：客户端拿到 token 对。GitHub 轨的同名事件在
         // /oauth/exchange 发（那里才是客户端真正拿到 token 的时刻）。
-        track(c, {
+        t({
             event: "login",
             provider: "email",
             userId: verified.userId,

package/dist/plugins/github.js

@@ -37,8 +37,12 @@ function redirectAllowed(redirect, github) {
             target.pathname.startsWith(base.pathname));
     });
 }
+// 回跳地址允许自带 query 与 fragment（redirectAllowed 只比对 protocol/host/pathname），
+// 文本拼接会把参数追加进 fragment、或让已有的同名键遮蔽新值，客户端 searchParams 取不到
 function withParam(url, key, value) {
-    return `${url}${url.includes("?") ? "&" : "?"}${key}=${encodeURIComponent(value)}`;
+    const target = new URL(url);
+    target.searchParams.set(key, value);
+    return target.toString();
 }
 // providerProfile 只透传建档需要的公开档案白名单——GET /user 的认证视图含
 // two_factor_authentication、私有仓库统计等敏感字段，不该流出库边界。
@@ -194,10 +198,11 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         if (!gh)
             return c.json({ error: "not_configured" }, 404);
         const code = c.req.query("code") ?? "";
+        const providerError = c.req.query("error") ?? "";
         const state = c.req.query("state") ?? "";
         const stateKey = `oauth:state:${state}`;
         const rawState = state ? await cfg(c).kv.get(stateKey) : null;
-        if (!code || !rawState) {
+        if (!rawState) {
             // state 无效即回跳地址不可信，只能就地报错。
             // 此分支拿不到 flowId——它就存在读不出来的那条 state 记录里。
             track(c, {
@@ -217,6 +222,12 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             ...(userId ? { userId } : {}),
             meta: { mode: mode ?? "login", ...meta },
         });
+        // GitHub 用 ?error= 回报用户拒绝授权，此时没有 code；state 已验过，回跳地址可信
+        if (!code) {
+            const reason = REASON_PATTERN.test(providerError) ? providerError : "no_code";
+            trackCallback(reason);
+            return c.redirect(withParam(redirect, "error", reason), 302);
+        }
         const identity = await fetchGithubIdentity(gh, code);
         if (!identity) {
             trackCallback("oauth_failed");

package/package.json

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