loginbase 1.1.0 → 1.3.0

package/README.md

@@ -3,7 +3,7 @@
 > The shared login foundation for my apps — email OTP + social OAuth + session management.
 > Cloudflare Workers server library + Kotlin Multiplatform client.
 
-多 App 共用的登录底座：邮箱验证码登录、社交 OAuth（GitHub 等）、会话管理（refresh 轮换 + 重用检测 + 丢回执救活）。服务端库跑在各 App 自己的 Cloudflare Worker 里（数据在各自 D1，不做中心化账号），客户端库以 Kotlin Multiplatform 提供。
+多 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) 只住本仓，是两端的唯一权威。**
 
 ## 由来
 
@@ -11,13 +11,12 @@
 - 服务端实现的母本是 Tono-Server 已在生产验证的邮箱验证码登录（含全套测试），本仓库是它的抽取 + 泛化
 - 路线选择（公共库而非中心化服务）与仓库设计见 [docs/design.md](docs/design.md)，命名记录见 [docs/naming.md](docs/naming.md)
 
-## 结构（monorepo：一份协议，两个产物）
+## 结构（两个仓库：一份协议，两个产物）
 
 ```
-loginbase/
+loginbase/                   # 本仓：TS 服务端库 + 协议契约
 ├── src/                     # TS 服务端库（Hono sub-app 工厂），从 Tono-Server 平移
 ├── test/                    # vitest
-├── kotlin/                  # KMP 客户端库（独立 gradle 工程）
 ├── docs/
 │   ├── design.md            # 路线与仓库设计决策
 │   ├── server-design.md     # 服务端技术方案（公共 API/协议草案/会话模型/平移策略）
@@ -26,20 +25,25 @@ loginbase/
 │   ├── protocol.md          # API 契约（唯一权威）——代码平移时落笔
 │   └── logto-替换方案-调研.md # 背景调研（自 TrendingProjects 迁入）
 └── README.md
+
+loginbase-kt/                # 姊妹仓：KMP 客户端库（独立 gradle 工程、独立 CI 与版本线）
 ```
 
 ## 产物坐标
 
 ```
-仓库        HarlonWang/loginbase
-npm         loginbase        （npm registry，tag 触发 CI 发布）
-Maven       wang.harlon:loginbase-kt     （Maven Central，tag 触发 CI 发布）
+服务端仓     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
 ```
 
+两仓各自独立版本线，tag 为裸版本号；协议兼容关系由 `protocol.md` 版本历史 + 客户端仓 README 的对齐声明表达，不靠版本号相等表达。
+
 ## 状态与路线
 
-**落地第 1、2 步已完成**（2026-08-12）：`loginbase@1.0.0` 上线 npm（钩子化 + zh/en 模板 + github-oauth + TTL 配置，协议契约见 docs/protocol.md），Tono-Server 已接 onVerified 钩子并部署生产。下一步 = 第 3 步 TrendingAI 接入。落地顺序：
+**落地第 1~3 步已完成**（2026-08-13）：`loginbase@1.1.0` 上线 npm；Tono-Server（钩子化）与 github-ai-trending-api（双轨迁移：loginbase 优先 + Logto fallback）均已部署生产并通过分层验收。下一步 = 第 4 步 KMP 客户端。落地顺序：
 
 1. 从 Tono-Server 平移服务端代码与测试，Tono-Server 改为依赖本包（其现有测试即抽取验收）
 2. 钩子化（`onVerified` 用户回调）+ zh/en 邮件模板 + github-oauth 可选插件
@@ -49,5 +53,5 @@ Kotlin 包    wang.harlon.loginbase
 
 ## 设计红线
 
-- 依赖最小集：服务端 hono + jose（+ zod-validator），客户端 ktor + kotlinx-serialization + multiplatform-settings。auth 库是供应链攻击的最高价值目标，每加一个依赖都要过一遍这个念头
-- 协议变更必须服务端 + 客户端 + `docs/protocol.md` 同一个 commit；单一版本线，一个 tag 同时锁定两端
+- 依赖最小集：服务端 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/body.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 请求体字段取字符串。
+ *
+ * JSON 里客户端可以塞任意类型，而 `(body.x ?? "").trim()` 遇到数字/对象/数组会抛
+ * TypeError——把一个本该 400 的坏请求变成 500：日志噪音，且给客户端「服务端故障、
+ * 可重试」的错误信号（实际重试多少次都一样）。TS 的字段类型只在编译期成立，
+ * 运行时边界必须自己兜（见 design.md 技术选型第 1 条）。
+ *
+ * 非字符串一律当空串，让各端点照常走自己的 400 分支。
+ */
+export declare function trimmedField(value: unknown): string;

package/dist/body.js

@@ -0,0 +1,13 @@
+/**
+ * 请求体字段取字符串。
+ *
+ * JSON 里客户端可以塞任意类型，而 `(body.x ?? "").trim()` 遇到数字/对象/数组会抛
+ * TypeError——把一个本该 400 的坏请求变成 500：日志噪音，且给客户端「服务端故障、
+ * 可重试」的错误信号（实际重试多少次都一样）。TS 的字段类型只在编译期成立，
+ * 运行时边界必须自己兜（见 design.md 技术选型第 1 条）。
+ *
+ * 非字符串一律当空串，让各端点照常走自己的 400 分支。
+ */
+export function trimmedField(value) {
+    return typeof value === "string" ? value.trim() : "";
+}

package/dist/config.d.ts

@@ -10,6 +10,18 @@ export interface VerifiedIdentity {
      * 认证视图的敏感字段（私有统计、2FA 状态等）在库边界内剔除。
      */
     providerProfile?: unknown;
+    /**
+     * OAuth provider 的 access token（1.2.0 起）。库**只透传、不存储、不再分发**——
+     * 第三方 API 凭据是各 App 的产品决策，不属登录底座（见 docs/design.md 定位边界）。
+     * GitHub OAuth App 的 token 不过期，用户撤销授权才失效。email provider 恒缺省。
+     */
+    providerAccessToken?: string;
+    /**
+     * provider 返回的全部**已验证**邮箱，归一化小写（1.2.0 起）。`email` 是其中
+     * 选定的主锚点（primary+verified 优先）；App 可用整个列表做账号对账——GitHub 上
+     * 挂了多个验证邮箱、其中之一才是 App 账号邮箱的用户，只比对 `email` 会被误判为新人。
+     */
+    verifiedEmails?: string[];
     requestMeta: {
         ip?: string;
         userAgent?: string;
@@ -21,6 +33,42 @@ export interface VerifiedResult {
     user?: unknown;
 }
 export type OnVerified = (identity: VerifiedIdentity) => Promise<VerifiedResult> | VerifiedResult;
+/**
+ * onLinked：**已登录用户绑定第二身份**的语义出口（1.2.0 起）。
+ * 与 onVerified 方向相反——onVerified **返回** userId（用外部身份换会话），
+ * onLinked **接收** userId（用已有会话认领外部身份）；不建会话、不发 token。
+ */
+export interface LinkedIdentity {
+    /** 当前登录用户，来自 link/start 的 Bearer 校验并存于 state；绝不接受客户端传入 */
+    userId: string;
+    provider: "github";
+    providerUserId: string;
+    /**
+     * link 时 userId 已确定，email 只是附加信息——provider 未给也**不构成失败**
+     * （与 onVerified 不同：那里 email 是账号锚点，缺了就无法找号建号）。
+     */
+    email?: string;
+    verifiedEmails?: string[];
+    providerProfile?: unknown;
+    providerAccessToken?: string;
+    requestMeta: {
+        ip?: string;
+        userAgent?: string;
+    };
+}
+/**
+ * 冲突用返回值而非抛错表达：「该外部身份已属他人」是预期业务结果，不是异常
+ * （抛错留给真异常 → `internal`）。库不裁决冲突——拒绝/换绑/重复绑定是否幂等
+ * 全由 App 决定，库只把 `reason` 映射成回跳参数。
+ * `reason` 须为 `[A-Za-z0-9_]{1,64}`，否则回落为 `internal`（回跳 URL 卫生）。
+ */
+export type LinkResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type OnLinked = (identity: LinkedIdentity) => Promise<LinkResult> | LinkResult;
 export type OnEvent = (event: Record<string, unknown>) => void;
 export interface GithubSocialConfig {
     clientId: string;
@@ -32,6 +80,12 @@ export interface GithubSocialConfig {
     allowedRedirects: string[];
     /** GitHub OAuth App 注册的回调地址；缺省由请求 origin + basePath 推导 */
     callbackUrl?: string;
+    /**
+     * authorize 的 scope，默认 `user:email`——取 primary+verified 邮箱的最小集。
+     * 需要额外能力的消费方自配，如 TrendingAI 的 `"user:email public_repo"`
+     * （star 写操作要求 public_repo）。scope 越大授权页越吓人，按需给。
+     */
+    scope?: string;
 }
 export interface LoginConfig {
     db: D1Database;
@@ -47,6 +101,8 @@ export interface LoginConfig {
         refreshTtlMs?: number | null;
     };
     onVerified: OnVerified;
+    /** 提供后才启用 link 端点（未提供 → 404 not_configured，默认关闭、显式启用） */
+    onLinked?: OnLinked;
     onEvent?: OnEvent;
     socials?: {
         github?: GithubSocialConfig;

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 { trimmedField } from "./body.js";
 import { registerGithubOauth } from "./plugins/github.js";
 export function createAuthApp(getConfig, basePath) {
     const authMiddleware = createAuthMiddleware(getConfig);
@@ -25,7 +26,7 @@ export function createAuthApp(getConfig, basePath) {
         const body = await c.req
             .json()
             .catch(() => ({}));
-        const raw = (body.email ?? "").trim().toLowerCase();
+        const raw = trimmedField(body.email).toLowerCase();
         if (!/^\S+@\S+\.\S+$/.test(raw)) {
             return c.json({ error: "invalid_email" }, 400);
         }
@@ -35,12 +36,24 @@ export function createAuthApp(getConfig, basePath) {
             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 {
             return c.json({ error: "internal" }, 500);
         }
+        // 静默回落意味着「为什么收到英文邮件」在别处查不出来，故选中语言必须留痕
+        emitEvent({
+            event: "code_sent",
+            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);
@@ -49,8 +62,8 @@ export function createAuthApp(getConfig, basePath) {
         const body = await c.req
             .json()
             .catch(() => ({}));
-        const email = (body.email ?? "").trim().toLowerCase();
-        const code = (body.code ?? "").trim();
+        const email = trimmedField(body.email).toLowerCase();
+        const code = trimmedField(body.code);
         const stored = await readCode(cfg(c).kv, email);
         if (!stored)
             return c.json({ error: "code_expired" }, 400);
@@ -96,7 +109,7 @@ export function createAuthApp(getConfig, basePath) {
         const body = await c.req
             .json()
             .catch(() => ({}));
-        const token = (body.refreshToken ?? "").trim();
+        const token = trimmedField(body.refreshToken);
         if (!token) {
             return c.json({ error: "invalid_refresh_token", reason: "missing_token" }, 401);
         }

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export interface Login<TEnv> {
     }>;
 }
 export declare function createLogin<TEnv = unknown>(resolve: (env: TEnv) => LoginConfig, options?: CreateLoginOptions): Login<TEnv>;
-export type { LoginConfig, CreateLoginOptions, VerifiedIdentity, VerifiedResult, OnVerified, OnEvent, GithubSocialConfig, } from "./config.js";
+export type { LoginConfig, CreateLoginOptions, VerifiedIdentity, VerifiedResult, OnVerified, LinkedIdentity, LinkResult, OnLinked, OnEvent, GithubSocialConfig, } from "./config.js";
 export type { AuthVariables } from "./middleware.js";
 export { createAuthMiddleware } from "./middleware.js";
 export * from "./code.js";

package/dist/plugins/github.d.ts

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

package/dist/plugins/github.js

@@ -1,3 +1,5 @@
+import { trimmedField } from "../body.js";
+import { createAuthMiddleware } from "../middleware.js";
 import { generateRefreshToken as randomToken } from "../session.js";
 import { createSession } from "../session.js";
 import { signAccessToken, ACCESS_TTL_SECONDS } from "../token.js";
@@ -7,6 +9,9 @@ const GITHUB_API_USER = "https://api.github.com/user";
 const GITHUB_API_EMAILS = "https://api.github.com/user/emails";
 const STATE_TTL_SECONDS = 600;
 const OTC_TTL_SECONDS = 60;
+const DEFAULT_SCOPE = "user:email";
+// App 自定义的冲突 reason 会进回跳 URL，限制字符集防畸形/敏感内容外泄
+const REASON_PATTERN = /^[A-Za-z0-9_]{1,64}$/;
 // 结构化校验而非字符串前缀：startsWith("https://example.com") 会被
 // https://example.com.evil.com 绕过（开放重定向 → otc 泄露给攻击者域）。
 // scheme + host 精确匹配，path 只允许白名单条目的前缀扩展。
@@ -58,9 +63,67 @@ function publicProfile(user) {
     }
     return out;
 }
+function buildAuthorizeUrl(gh, callbackUrl, state) {
+    const url = new URL(GITHUB_AUTHORIZE);
+    url.searchParams.set("client_id", gh.clientId);
+    url.searchParams.set("redirect_uri", callbackUrl);
+    url.searchParams.set("scope", gh.scope ?? DEFAULT_SCOPE);
+    url.searchParams.set("state", state);
+    return url.toString();
+}
+/**
+ * 换 token → 取用户 → 取邮箱。login 与 link 两条流程共用（callback 是同一个端点：
+ * GitHub OAuth App 的回调地址注册在 GitHub 侧，多一个即多一处配置漂移）。
+ * 返回 null = 换码或取用户失败，调用方回跳 oauth_failed。
+ */
+async function fetchGithubIdentity(gh, code) {
+    // server-side 换 token：client_secret 只在此出现，客户端不可见
+    const tokenRes = await fetch(GITHUB_TOKEN, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+            client_id: gh.clientId,
+            client_secret: gh.clientSecret,
+            code,
+        }),
+    });
+    const tokenBody = tokenRes.ok
+        ? (await tokenRes.json().catch(() => null))
+        : null;
+    const ghToken = tokenBody?.access_token;
+    if (!ghToken)
+        return null;
+    // GitHub API 要求 User-Agent
+    const ghHeaders = {
+        Authorization: `Bearer ${ghToken}`,
+        Accept: "application/vnd.github+json",
+        "User-Agent": "loginbase",
+    };
+    const userRes = await fetch(GITHUB_API_USER, { headers: ghHeaders });
+    if (!userRes.ok)
+        return null;
+    const ghUser = (await userRes.json());
+    const emailsRes = await fetch(GITHUB_API_EMAILS, { headers: ghHeaders });
+    const emails = emailsRes.ok
+        ? (await emailsRes.json())
+        : [];
+    const normalize = (e) => e.trim().toLowerCase();
+    const verifiedEmails = emails.filter((e) => e.verified).map((e) => normalize(e.email));
+    const email = emails.find((e) => e.primary && e.verified)?.email ??
+        emails.find((e) => e.verified)?.email;
+    return {
+        ghUser,
+        ghToken,
+        ...(email ? { email: normalize(email) } : {}),
+        verifiedEmails,
+    };
+}
 export function registerGithubOauth(auth, getConfig, basePath) {
     const cfg = (c) => getConfig(c.env);
     const github = (c) => cfg(c).socials?.github;
+    const authMiddleware = createAuthMiddleware(getConfig);
+    const callbackUrlFor = (c, gh) => gh.callbackUrl ??
+        `${new URL(c.req.url).origin}${basePath}/oauth/github/callback`;
     auth.get("/oauth/github/start", async (c) => {
         const gh = github(c);
         if (!gh)
@@ -74,14 +137,28 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         await cfg(c).kv.put(`oauth:state:${state}`, JSON.stringify(record), {
             expirationTtl: STATE_TTL_SECONDS,
         });
-        const callbackUrl = gh.callbackUrl ??
-            `${new URL(c.req.url).origin}${basePath}/oauth/github/callback`;
-        const url = new URL(GITHUB_AUTHORIZE);
-        url.searchParams.set("client_id", gh.clientId);
-        url.searchParams.set("redirect_uri", callbackUrl);
-        url.searchParams.set("scope", "user:email");
-        url.searchParams.set("state", state);
-        return c.redirect(url.toString(), 302);
+        return c.redirect(buildAuthorizeUrl(gh, callbackUrlFor(c, gh), state), 302);
+    });
+    // 已登录用户绑定第二身份。**必须是 POST**：浏览器导航带不了 Authorization 头，
+    // 故不能像 login 那样 GET 直接 302——客户端先换 authorizeUrl，再自己打开浏览器。
+    auth.post("/oauth/github/link/start", authMiddleware, async (c) => {
+        const gh = github(c);
+        // onLinked 未提供 = 该能力未启用（默认关闭、显式启用）
+        if (!gh || !cfg(c).onLinked)
+            return c.json({ error: "not_configured" }, 404);
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        const redirect = trimmedField(body.redirect);
+        if (!redirect || !redirectAllowed(redirect, gh)) {
+            return c.json({ error: "invalid_redirect" }, 400);
+        }
+        const state = randomToken();
+        const record = { redirect, mode: "link", userId: c.get("userId") };
+        await cfg(c).kv.put(`oauth:state:${state}`, JSON.stringify(record), {
+            expirationTtl: STATE_TTL_SECONDS,
+        });
+        return c.json({ authorizeUrl: buildAuthorizeUrl(gh, callbackUrlFor(c, gh), state) }, 200);
     });
     auth.get("/oauth/github/callback", async (c) => {
         const gh = github(c);
@@ -96,52 +173,48 @@ export function registerGithubOauth(auth, getConfig, basePath) {
             return c.json({ error: "invalid_state" }, 400);
         }
         await cfg(c).kv.delete(stateKey); // 单次使用，验证即焚
-        const { redirect } = JSON.parse(rawState);
-        // server-side 换 token：client_secret 只在此出现，客户端不可见
-        const tokenRes = await fetch(GITHUB_TOKEN, {
-            method: "POST",
-            headers: { "Content-Type": "application/json", Accept: "application/json" },
-            body: JSON.stringify({
-                client_id: gh.clientId,
-                client_secret: gh.clientSecret,
-                code,
-            }),
-        });
-        const tokenBody = tokenRes.ok
-            ? (await tokenRes.json().catch(() => null))
-            : null;
-        const ghToken = tokenBody?.access_token;
-        if (!ghToken)
+        const { redirect, mode, userId } = JSON.parse(rawState);
+        const identity = await fetchGithubIdentity(gh, code);
+        if (!identity)
             return c.redirect(withParam(redirect, "error", "oauth_failed"), 302);
-        // GitHub API 要求 User-Agent
-        const ghHeaders = {
-            Authorization: `Bearer ${ghToken}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "loginbase",
+        const { ghUser, ghToken, email, verifiedEmails } = identity;
+        const userAgent = c.req.header("User-Agent") ?? undefined;
+        const ip = c.req.header("CF-Connecting-IP") ?? undefined;
+        const common = {
+            provider: "github",
+            providerUserId: String(ghUser.id),
+            providerProfile: publicProfile(ghUser), // GitHub /user 公开档案白名单字段
+            providerAccessToken: ghToken,
+            verifiedEmails,
+            requestMeta: { ip, userAgent },
         };
-        const userRes = await fetch(GITHUB_API_USER, { headers: ghHeaders });
-        if (!userRes.ok)
-            return c.redirect(withParam(redirect, "error", "oauth_failed"), 302);
-        const ghUser = (await userRes.json());
-        const emailsRes = await fetch(GITHUB_API_EMAILS, { headers: ghHeaders });
-        const emails = emailsRes.ok
-            ? (await emailsRes.json())
-            : [];
-        const email = emails.find((e) => e.primary && e.verified)?.email ??
-            emails.find((e) => e.verified)?.email;
+        // ---- link 分支：认领身份，不建会话、不发 token ----
+        if (mode === "link") {
+            const onLinked = cfg(c).onLinked;
+            // userId 由 link/start 写入，缺失只可能是载荷被篡改/降级，保守失败
+            if (!onLinked || !userId) {
+                return c.redirect(withParam(redirect, "error", "internal"), 302);
+            }
+            let result;
+            try {
+                // email 在此可缺省：userId 已定，邮箱只是附加信息（与 login 分支的关键差别）
+                result = await onLinked({ userId, ...common, ...(email ? { email } : {}) });
+            }
+            catch {
+                return c.redirect(withParam(redirect, "error", "internal"), 302);
+            }
+            if (!result.ok) {
+                const reason = REASON_PATTERN.test(result.reason) ? result.reason : "internal";
+                return c.redirect(withParam(redirect, "error", reason), 302);
+            }
+            return c.redirect(withParam(redirect, "linked", "github"), 302);
+        }
+        // ---- login 分支：email 是账号锚点，缺了就无法找号建号 ----
         if (!email)
             return c.redirect(withParam(redirect, "error", "oauth_no_email"), 302);
-        const userAgent = c.req.header("User-Agent") ?? undefined;
-        const ip = c.req.header("CF-Connecting-IP") ?? undefined;
         let verified;
         try {
-            verified = await cfg(c).onVerified({
-                email: email.trim().toLowerCase(),
-                provider: "github",
-                providerUserId: String(ghUser.id),
-                providerProfile: publicProfile(ghUser), // GitHub /user 公开档案白名单字段
-                requestMeta: { ip, userAgent },
-            });
+            verified = await cfg(c).onVerified({ email, ...common });
         }
         catch {
             return c.redirect(withParam(redirect, "error", "internal"), 302);
@@ -173,7 +246,7 @@ export function registerGithubOauth(auth, getConfig, basePath) {
         const body = await c.req
             .json()
             .catch(() => ({}));
-        const otc = (body.otc ?? "").trim();
+        const otc = trimmedField(body.otc);
         const key = `oauth:otc:${otc}`;
         const raw = otc ? await cfg(c).kv.get(key) : null;
         if (!raw)

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/package.json

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