loginbase 1.2.0 → 1.3.0

package/README.md

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

package/dist/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,7 +3,7 @@
 // 事件出口接 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";
@@ -36,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);

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.2.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",