loginbase 1.6.0 → 1.6.1

package/README.md

@@ -1,64 +1,131 @@
 # loginbase
 
-> The shared login foundation for my apps — email OTP + social OAuth + session management.
-> Cloudflare Workers server library + Kotlin Multiplatform client.
+> Email OTP, social sign-in and session management for Cloudflare Workers.
 
-多 App 共用的登录底座：邮箱验证码登录、社交 OAuth（GitHub 等）、会话管理（refresh 轮换 + 重用检测 + 丢回执救活）。服务端库跑在各 App 自己的 Cloudflare Worker 里（数据在各自 D1，不做中心化账号），客户端库以 Kotlin Multiplatform 提供，住在姊妹仓 [HarlonWang/loginbase-kt](https://github.com/HarlonWang/loginbase-kt)（第 4 步新建）。**协议契约 [docs/protocol.md](docs/protocol.md) 只住本仓，是两端的唯一权威。**
+**English** | [简体中文](README.zh-CN.md)
 
-## 由来
+[![npm](https://img.shields.io/npm/v/loginbase)](https://www.npmjs.com/package/loginbase)
+[![license](https://img.shields.io/npm/l/loginbase)](LICENSE)
 
-- 起点是 TrendingAI 替换 Logto 的调研（邮箱登录被迫走托管 web 页、CN 链路差），结论选定自建，见 [docs/logto-替换方案-调研.md](docs/logto-替换方案-调研.md)
-- 服务端实现的母本是 Tono-Server 已在生产验证的邮箱验证码登录（含全套测试），本仓库是它的抽取 + 泛化
-- 路线选择（公共库而非中心化服务）与仓库设计见 [docs/design.md](docs/design.md)，命名记录见 [docs/naming.md](docs/naming.md)
+loginbase mounts into a Worker you already run. Users, sessions and login events live in **your** D1 database — there is no central account server, no vendor dashboard, and nothing extra to deploy. An official Kotlin Multiplatform client, [loginbase-kt](https://github.com/HarlonWang/loginbase-kt), implements the other half.
 
-## 结构（两个仓库：一份协议，两个产物）
+## Why
 
+**Hosted auth costs you the experience and the data.** Email sign-in gets redirected to someone else's web page, latency depends on someone else's edge, and your users' identities sit in someone else's database — which turns into a migration project the day pricing or policy changes.
+
+**Rolling your own is harder than it looks.** Refresh rotation, replay detection, the race between a dropped refresh response and the client's retry, a dozen in-flight requests all refreshing at once. Get any of these wrong and it fails *silently*: nothing breaks in testing, and you find out when users are logged out for no reason — or you never find out at all.
+
+loginbase is the middle path. The session model of a real auth product, shipped as a dependency you own, running inside the Worker you already have.
+
+## What you get
+
+- **Passwordless sign-in, more than one way.** Six-digit email codes with enumeration-safe responses and three layers of rate limiting, GitHub OAuth, and account linking — so a signed-in user claims a second identity instead of ending up with a duplicate account. Code emails ship in English and Chinese.
+- **Token theft is detected; bad networks aren't punished.** Refresh tokens rotate on every use, and a replayed token kills the session on the spot. A refresh response lost to a flaky connection is *not* theft, and gets recovered rather than punished.
+- **Passes app-store review.** Passwordless login can't produce the static credentials Google Play and App Store Connect ask for. An optional demo account can, without opening an authentication bypass.
+- **Login analytics built in.** Every send, verify, refresh and revoke lands in your own `auth_events` table, with geography from `request.cf` — no external dependency, no data leaving your account.
+- **A client that hides tokens entirely.** With [loginbase-kt](https://github.com/HarlonWang/loginbase-kt), your app code never contains a token, a refresh call, or a 401 handler.
+
+## Quick start
+
+**1. Install.** Hono comes along as a peer dependency — if your Worker already uses it, that stays the single copy and the version is yours to pick.
+
+```bash
+npm install loginbase
 ```
-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
-
-loginbase-kt/                # 姊妹仓：KMP 客户端库（独立 gradle 工程、独立 CI 与版本线）
+
+**2. Apply the migrations.** The package ships its own DDL (`sessions`, `auth_events`).
+
+```toml
+# wrangler.toml — for a D1 database dedicated to auth
+[[d1_databases]]
+binding = "DB"
+database_name = "my-app"
+database_id = "..."
+migrations_dir = "node_modules/loginbase/migrations"
 ```
 
-## 产物坐标
+```bash
+npx wrangler d1 migrations apply my-app --remote
+```
 
+Sharing a D1 that already has migrations of its own? Copy the two files from `node_modules/loginbase/migrations/` into your own migrations directory instead. **Skipping `0002_auth_events.sql` is silent** — login keeps working, analytics just never land.
+
+**3. Create and mount.** The only thing loginbase asks of you is how to turn a verified identity into a user id. Everything about your user table stays yours.
+
+```ts
+import { Hono } from "hono";
+import { createLogin } from "loginbase";
+
+const login = createLogin<Env>((env) => ({
+  db: env.DB,
+  kv: env.EMAIL_CODES,
+  jwt: { secret: env.JWT_SECRET },
+  email: {
+    resendApiKey: env.RESEND_API_KEY,
+    from: "Acme <login@acme.com>",
+    brand: "Acme",
+  },
+  async onVerified({ email }) {
+    const user = await findOrCreateUser(env.DB, email);
+    return { userId: user.id, isNewUser: user.isNew };
+  },
+}));
+
+const app = new Hono<{ Bindings: Env }>();
+app.route("/", login.app);                        // serves /auth/*
+app.get("/api/me", login.middleware, (c) =>       // Bearer verification
+  c.json({ userId: c.get("userId") })
+);
+
+export default app;
 ```
-服务端仓     HarlonWang/loginbase          （含 protocol.md，协议唯一权威）
-客户端仓     HarlonWang/loginbase-kt
-npm         loginbase                     （npm registry，本仓 tag 触发 CI 发布）
-Maven       wang.harlon:loginbase-kt      （Maven Central，客户端仓 tag 触发 CI 发布）
-Kotlin 包    wang.harlon.loginbase
+
+Not using Hono for your own routes? `login.fetch(request, env, ctx)` behind one `pathname.startsWith("/auth")` works the same.
+
+**4. Add GitHub sign-in** (optional) by giving loginbase your OAuth app and the deep links it's allowed to return to:
+
+```ts
+socials: {
+  github: {
+    clientId: env.GITHUB_CLIENT_ID,
+    clientSecret: env.GITHUB_CLIENT_SECRET,
+    allowedRedirects: ["acme://auth"],
+  },
+},
 ```
 
-两仓各自独立版本线，tag 为裸版本号；协议兼容关系由 `protocol.md` 版本历史 + 客户端仓 README 的对齐声明表达，不靠版本号相等表达。
+**5. Connect your app.** Point [loginbase-kt](https://github.com/HarlonWang/loginbase-kt) at `https://your-worker.example.com/auth` and you're done — it owns storage, refresh and the OAuth browser round trip from there.
+
+## How the two halves line up
+
+One redirect value has to match in three places, or social sign-in fails in ways that are tedious to diagnose:
+
+| Where | What |
+|---|---|
+| Server | `socials.github.allowedRedirects` |
+| Android app | `manifestPlaceholders["loginbaseRedirectScheme"]` |
+| Client runtime | derived from that same placeholder |
+
+The client can print exactly what to whitelist — call `Loginbase.redirectUri(context)` and paste the result into `allowedRedirects`.
+
+## Requirements
+
+Cloudflare Workers with D1 and KV bindings · `hono` ^4.12.8 · a [Resend](https://resend.com) account for delivery.
 
-## 状态与路线
+## Not included
 
-**落地第 1~3 步已完成**（2026-08-13）：`loginbase@1.1.0` 上线 npm；Tono-Server（钩子化）与 github-ai-trending-api（双轨迁移：loginbase 优先 + Logto fallback）均已部署生产并通过分层验收。下一步 = 第 4 步 KMP 客户端。落地顺序：
+loginbase deliberately stops at authentication and sessions. It has no password login, no OIDC or SAML, no multi-tenancy, no admin UI, and no user profile storage — your `onVerified` owns the user table. Sign-in providers are email and GitHub; email delivery is Resend; the runtime is Cloudflare Workers. If you need an identity provider rather than a login foundation, use one.
 
-1. 从 Tono-Server 平移服务端代码与测试，Tono-Server 改为依赖本包（其现有测试即抽取验收）
-2. 钩子化（`onVerified` 用户回调）+ zh/en 邮件模板 + github-oauth 可选插件
-3. TrendingAI 后端接入（`/auth` 挂载 + requireAuth 双轨 + Logto 存量迁移）
-4. KMP 客户端库 + TrendingAI 登录 UI（commonMain）
-5. Tono-Android 择机换用 loginbase-kt 的 android target
+## Documentation
 
-## 设计红线
+| | |
+|---|---|
+| [Protocol contract](docs/protocol.md) | The wire API — single source of truth for both halves |
+| [Server design](docs/server-design.md) | Configuration surface, session model, hooks |
+| [Email and identity](docs/email-identity.md) | **Read before integrating** — why an email address is a poor identity anchor |
+| [Login analytics](docs/stats-design.md) | Event schema and metric definitions |
+| [Design decisions](docs/design.md) | Why a library instead of a service, and other roads not taken |
 
-- 依赖准入（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，由消费方定版本
+## License
 
-  仍然拒绝：为省几十行代码的工具包、单人维护的新包或小众包、运行时联网或带安装脚本的包、为一个功能拖进整个框架的包。版本钉死 + lockfile + provenance 不变
-- 协议变更：服务端实现 + `docs/protocol.md` 同一个 commit，并在 `loginbase-kt` 仓开跟进 issue，客户端版本落地前不关（2026-08-13 由 monorepo 三位一体改判，理由见 design.md）
+MIT

package/README.zh-CN.md

@@ -0,0 +1,131 @@
+# loginbase
+
+> 为 Cloudflare Workers 而生的邮箱验证码登录、社交登录与会话管理。
+
+[English](README.md) | **简体中文**
+
+[![npm](https://img.shields.io/npm/v/loginbase)](https://www.npmjs.com/package/loginbase)
+[![license](https://img.shields.io/npm/l/loginbase)](LICENSE)
+
+loginbase 挂进你已经在跑的 Worker。用户、会话、登录事件全部落在**你自己的** D1 里——没有中心化账号服务，没有厂商后台，也不需要额外部署任何东西。官方 Kotlin Multiplatform 客户端 [loginbase-kt](https://github.com/HarlonWang/loginbase-kt) 负责另一半。
+
+## 为什么
+
+**托管方案要你交出体验和数据。** 邮箱登录被迫跳去别人的 web 页，延迟取决于别人的边缘节点，用户身份存在别人的数据库里——等哪天定价或政策一变，这就是一个迁移项目。
+
+**自己写又比看上去难。** refresh 轮换、重放检测、回执丢包与客户端重试之间的竞态、十几个在飞请求同时刷新……任何一条写错都是**静默失败**：测试期间什么都不会坏，等到用户莫名其妙被登出你才发现，或者根本发现不了。
+
+loginbase 是中间那条路：一套成熟认证产品该有的会话模型，以你自己持有的依赖形态交付，跑在你已经有的那个 Worker 里。
+
+## 能力
+
+- **不止一种无密码登录。** 六位邮箱验证码（防账号枚举的响应 + 三层限流）、GitHub OAuth，以及身份绑定——已登录用户认领第二身份，而不是稀里糊涂多出一个重复账号。验证码邮件内置中英文。
+- **盗用会被发现，弱网不会被误伤。** refresh token 每次使用即轮换，重放即当场终止会话；而弱网丢掉的那次回执**不算**盗用，会被救活而不是被惩罚。
+- **过得了应用商店审核。** 无密码登录交不出 Google Play 与 App Store Connect 要的静态凭据，可选的演示账号能——且不开任何鉴权旁路。
+- **内建登录统计。** 发码、验证、刷新、注销逐条落进你自己的 `auth_events` 表，地理信息取自 `request.cf`——零外部依赖，数据不出你的账号。
+- **一个把 token 彻底藏起来的客户端。** 用 [loginbase-kt](https://github.com/HarlonWang/loginbase-kt)，你的 App 代码里不会出现 token、刷新调用或 401 处理。
+
+## 快速开始
+
+**1. 安装。** Hono 作为 peer dependency 自动带上——你的 Worker 若已经在用它，那就是同一份，版本由你定。
+
+```bash
+npm install loginbase
+```
+
+**2. 执行迁移。** DDL（`sessions`、`auth_events`）随包分发。
+
+```toml
+# wrangler.toml —— 用一个专供认证的 D1 时
+[[d1_databases]]
+binding = "DB"
+database_name = "my-app"
+database_id = "..."
+migrations_dir = "node_modules/loginbase/migrations"
+```
+
+```bash
+npx wrangler d1 migrations apply my-app --remote
+```
+
+如果共用一个已有自己迁移的 D1，改为把 `node_modules/loginbase/migrations/` 下的两个文件复制进你自己的迁移目录。**漏掉 `0002_auth_events.sql` 是静默的**——登录照常工作，只是统计永远不落库。
+
+**3. 建实例并挂载。** loginbase 只要求你一件事：把一个已验证的身份换成 userId。用户表的一切仍然归你。
+
+```ts
+import { Hono } from "hono";
+import { createLogin } from "loginbase";
+
+const login = createLogin<Env>((env) => ({
+  db: env.DB,
+  kv: env.EMAIL_CODES,
+  jwt: { secret: env.JWT_SECRET },
+  email: {
+    resendApiKey: env.RESEND_API_KEY,
+    from: "Acme <login@acme.com>",
+    brand: "Acme",
+  },
+  async onVerified({ email }) {
+    const user = await findOrCreateUser(env.DB, email);
+    return { userId: user.id, isNewUser: user.isNew };
+  },
+}));
+
+const app = new Hono<{ Bindings: Env }>();
+app.route("/", login.app);                        // 提供 /auth/*
+app.get("/api/me", login.middleware, (c) =>       // Bearer 校验
+  c.json({ userId: c.get("userId") })
+);
+
+export default app;
+```
+
+自己的路由没用 Hono？把 `login.fetch(request, env, ctx)` 放在一个 `pathname.startsWith("/auth")` 后面，效果相同。
+
+**4. 加上 GitHub 登录**（可选）——把 OAuth 应用凭据和允许回跳的 deep link 交给 loginbase：
+
+```ts
+socials: {
+  github: {
+    clientId: env.GITHUB_CLIENT_ID,
+    clientSecret: env.GITHUB_CLIENT_SECRET,
+    allowedRedirects: ["acme://auth"],
+  },
+},
+```
+
+**5. 接上你的 App。** 把 [loginbase-kt](https://github.com/HarlonWang/loginbase-kt) 指向 `https://your-worker.example.com/auth` 就完事了——存储、刷新、OAuth 的浏览器往返都归它。
+
+## 两端如何对上
+
+同一个 redirect 要在三处保持一致，否则社交登录会以很难查的方式失败：
+
+| 位置 | 取值 |
+|---|---|
+| 服务端 | `socials.github.allowedRedirects` |
+| Android App | `manifestPlaceholders["loginbaseRedirectScheme"]` |
+| 客户端运行时 | 由同一个占位符推导 |
+
+客户端能直接打印该填什么——调 `Loginbase.redirectUri(context)`，把结果粘进 `allowedRedirects`。
+
+## 运行要求
+
+Cloudflare Workers，带 D1 与 KV binding · `hono` ^4.12.8 · 一个用于投递的 [Resend](https://resend.com) 账号。
+
+## 不包含什么
+
+loginbase 刻意止步于认证与会话：没有密码登录，没有 OIDC / SAML，没有多租户，没有管理后台，也不存用户档案——用户表归你的 `onVerified` 管。登录方式只有邮箱与 GitHub，邮件只走 Resend，运行时只有 Cloudflare Workers。如果你要的是一个身份提供商而不是一个登录底座，请去用身份提供商。
+
+## 文档
+
+| | |
+|---|---|
+| [协议契约](docs/protocol.md) | wire API——两端的唯一权威 |
+| [服务端设计](docs/server-design.md) | 配置面、会话模型、钩子 |
+| [邮箱与身份](docs/email-identity.md) | **接入前必读**——为什么邮箱不适合当身份锚点 |
+| [登录统计](docs/stats-design.md) | 事件模型与指标口径 |
+| [设计决策](docs/design.md) | 为什么是库而不是服务，以及那些没走的路 |
+
+## License
+
+MIT

package/dist/plugins/github.js

@@ -13,6 +13,20 @@ const OTC_TTL_SECONDS = 60;
 const DEFAULT_SCOPE = "user:email";
 // App 自定义的冲突 reason 会进回跳 URL，限制字符集防畸形/敏感内容外泄
 const REASON_PATTERN = /^[A-Za-z0-9_]{1,64}$/;
+// start/callback 是浏览器发出的请求，UA 即浏览器身份——「issued 后回跳丢失」（D11）
+// 定位靠它；exchange 来自 App 网络栈、UA 无信息量，不记。sec-ch-ua 必须一并记：
+// Brave 等套壳浏览器的 UA 与 Chrome 一字不差，只有品牌列表分得出。截断防超长头污染统计表
+const UA_MAX = 256;
+function browserMeta(c) {
+    const out = {};
+    const ua = c.req.header("User-Agent");
+    if (ua)
+        out.ua = ua.slice(0, UA_MAX);
+    const brands = c.req.header("sec-ch-ua");
+    if (brands)
+        out.secChUa = brands.slice(0, UA_MAX);
+    return out;
+}
 // 结构化校验而非字符串前缀：startsWith("https://example.com") 会被
 // https://example.com.evil.com 绕过（开放重定向 → otc 泄露给攻击者域）。
 // scheme + host 精确匹配，path 只允许白名单条目的前缀扩展。
@@ -134,12 +148,14 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         const gh = github(c);
         if (!gh)
             return c.json({ error: "not_configured" }, 404);
+        const ua = browserMeta(c);
         const redirect = c.req.query("redirect") ?? "";
         if (!redirect || !redirectAllowed(redirect, gh)) {
             track(c, {
                 event: "oauth_start",
                 outcome: "invalid_redirect",
                 provider: "github",
+                ...(Object.keys(ua).length ? { meta: ua } : {}),
             });
             return c.json({ error: "invalid_redirect" }, 400);
         }
@@ -149,7 +165,13 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         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 });
+        track(c, {
+            event: "oauth_start",
+            outcome: "ok",
+            provider: "github",
+            flowId,
+            ...(Object.keys(ua).length ? { meta: ua } : {}),
+        });
         return c.redirect(buildAuthorizeUrl(gh, callbackUrlFor(c, gh), state), 302);
     });
     // 已登录用户绑定第二身份。**必须是 POST**：浏览器导航带不了 Authorization 头，
@@ -197,6 +219,7 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         const gh = github(c);
         if (!gh)
             return c.json({ error: "not_configured" }, 404);
+        const ua = browserMeta(c);
         const code = c.req.query("code") ?? "";
         const providerError = c.req.query("error") ?? "";
         const state = c.req.query("state") ?? "";
@@ -209,6 +232,7 @@ export function registerGithubOauth(auth, getConfig, basePath) {
                 event: "oauth_callback",
                 outcome: "invalid_state",
                 provider: "github",
+                ...(Object.keys(ua).length ? { meta: ua } : {}),
             });
             return c.json({ error: "invalid_state" }, 400);
         }
@@ -220,7 +244,7 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             provider: "github",
             ...(flowId ? { flowId } : {}),
             ...(userId ? { userId } : {}),
-            meta: { mode: mode ?? "login", ...meta },
+            meta: { mode: mode ?? "login", ...ua, ...meta },
         });
         // GitHub 用 ?error= 回报用户拒绝授权，此时没有 code；state 已验过，回跳地址可信
         if (!code) {
@@ -311,7 +335,7 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             userId: verified.userId,
             ...(flowId ? { flowId } : {}),
             ...(verified.isNewUser !== undefined ? { isNewUser: verified.isNewUser } : {}),
-            meta: { mode: "login" },
+            meta: { mode: "login", ...ua },
         });
         return c.redirect(withParam(redirect, "otc", otc), 302);
     });

package/package.json

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