@auth-link/web 0.0.3 → 0.0.5

package/docs/README.zh-CN.md

@@ -2,474 +2,281 @@
 
 [English](../README.md) | **简体中文** | [日本語](./README.ja.md)
 
-**AuthLink 官方前端组件包**，帮助网站接入手机绑定与 App 确认流程，支持 React 18/19、Vue 3.3+、TypeScript 和 ESM。
+用于手机绑定与 App 确认的前端组件，支持 Vue 3、React 18/19 和原生 JavaScript。本文按前端接入顺序说明安装、登录状态读取、客户端初始化、弹窗和事件处理。
 
-## Go + Vue 完整接入
-
-按实际 CMS 流程接入，推荐先读 [Go + Vue：从登录、绑定到确认发布](./go-vue.zh-CN.md)，完整组件见 [Vue CMS 示例](../examples/vue-cms.vue)。
-
-顺序是：网站登录 → Go `/api/session` 返回 `authenticated` 与 `csrf` → Vue 通过 `csrfToken: () => session.csrf` 配置跨域客户端 → 创建 bind/confirm → Go 验证并消费结果后落库 → Vue 清理弹窗 → 独立业务接口再校验已保存回执并发布。`baseUrl` 是 Go 业务 API，`authLinkOrigin` 是 AuthLink API；租户密钥始终留在 Go 后台。带文章 ID/版本的确认通过网站自己的 fetch 创建并用 `validateTicket` 校验，SDK 的 `create` 只发送 purpose。
-
-
-## 功能
-
-- **扫码绑定**：网站显示二维码，用户使用 AuthLink App 扫码并确认绑定。
-- **手机确认**：电脑与 App 显示同步变化的六位数字，每 30 秒更新，用户核对后在 App 内批准。
-- **结果通知**：提供确认成功、拒绝、过期和错误事件，方便网站更新界面。
-- **框架支持**：React 组件与 hook、Vue 组件与 composable，以及无框架客户端。
-- **多语言与主题**：支持下表中的 13 种语言，默认简体中文；独立 CSS 和可覆盖的主题变量。
-- **生命周期管理**：请求切换或组件卸载时取消轮询，数字过期后自动隐藏。
-
-此包是 AuthLink 的网页接入层，需要配套应用后台、AuthLink 服务和手机 App。完整 AuthLink 流程校验原手机硬件密钥证明及 App 内批准，不要求系统通行密钥、指纹或锁屏；安装此包本身不会建立鉴权服务。
-
-## 接入步骤
-
-1. 在应用后台完成站点租户配置，并实现本文的创建请求、查询结果两个业务后台接口（同源或显式配置的跨域后台）。
-2. 安装包、导入样式，创建指向应用后台的客户端。
-3. 用户点击绑定或验证时创建请求，将返回的 ticket 交给 React/Vue 组件。
-4. 用户在 App 确认后，应用后台验证并消费结果，组件收到可信确认事件。
-
-租户密钥只保存在应用服务端。用户是否能够继续调用受保护接口，也必须由应用后台判断。
-
-## 流程
-
-应用后台根据当前登录用户创建 `bind` 或 `confirm` 请求，前端拿到 ticket 后交给组件。组件只轮询应用后台。应用后台在验证归属、state、双重认证策略并消费一次性结果后，才返回 `confirmed`。
-
-定时数字用于电脑与手机核对；用户仍在 AuthLink App 内完成 原手机硬件密钥校验和 App 内批准。它不是用户输入网站的 TOTP 登录密码，不能单独授权。请求最长 120 秒；数字变化不延长请求有效期。前端不生成数字、不接收生成 seed，不在数字更新时新建请求。
-
-需要配套更新后的 Go 服务和客户端协议 7。服务端与 App 必须使用当前单一协议，不能只升级网页。
-
-## 安装
-
-在应用项目中安装：
+## 1. 安装并区分两个 API 地址
 
 ```sh
-npm install @auth-link/web
+npm install @auth-link/web@latest
+# 另行安装你的项目使用的 vue，或 react / react-dom。
 ```
 
-## 创建应用客户端（默认同源 Cookie 模式）
-
-`readCsrfTokenFromYourCms` 是接入方函数，不是包里的导出；名称不要求与你的网站框架一致，也不要求使用 CMS。它只读取**你的网站后台提供的 CSRF token**，用于保护携带登录 cookie 的请求，不是 AuthLink 租户 API key、登录 cookie 或手机核对码。
-
-下面采用页面 meta 标签的方式。后台需要先准备 token：
+| 地址 | 前端配置 | 用途 |
+| --- | --- | --- |
+| 你的网站业务后台，如 `https://cms-api.example.com` | `baseUrl`、`allowedBackendOrigins` | 登录状态、创建请求和查询结果 |
+| AuthLink 生产 API：`https://api.getauthlink.com` | `authLinkOrigin` | 核对 ticket 中的 AuthLink 服务来源 |
 
-1. 优先复用网站框架现有的 CSRF 机制；没有现成机制时，在服务端为当前登录 session 生成并保存密码学安全随机 token，例如 Node 的 `randomBytes(32).toString('base64url')`。不要在浏览器随机生成一个值，也不要使用所有用户共用的固定字符串。
-2. 服务端使用当前 session 的 token 渲染下面的标签，正确转义 HTML 属性；`{{ csrfToken }}` 表示服务器模板变量，不是可直接照抄的 token。包含会话 token 的页面不能被公开缓存。
-3. 创建和查询接口都读取 `X-CSRF-Token`，与同一登录 session 保存的 token 校验；缺失、不匹配或请求来源不符合网站要求时拒绝请求。仅让前端发送这个头，并不会自动启用后台校验。
-4. 登录、退出或会话/token 更新后，让页面重新取得当前 token。SPA 也可以由网站实现同源会话初始化接口返回 token，再通过 `csrfToken` 回调提供；这不是 SDK 自带接口。
+`baseUrl` 不是 AuthLink API，也不是 AuthLink 官网。接入方的网站和业务 API 仍使用自己的域名。需要已有的网站登录状态和下文的请求接口；Web SDK 不提供登录或会话接口。租户密钥不能放到浏览器。
 
-```html
-<!-- 由你的网站后台渲染到当前用户的页面 head 中 -->
-<meta name="csrf-token" content="{{ csrfToken }}">
-```
+导入入口：根入口提供客户端和类型；`/vue`、`/react` 提供组件及 useAuthLink；`/styles.css` 必须显式导入。ESM、TypeScript，工具环境 Node 22.13+；React 18.2+/19、Vue 3.3+，只安装所用框架。
 
-新建 `authlink-client.ts`：
+## 2. 读取当前登录状态并创建客户端
 
 ```ts
-// authlink-client.ts
 import { createAuthLinkClient } from '@auth-link/web';
 import '@auth-link/web/styles.css';
 
-// The application server renders this meta element using the current session's
-// CSRF token. This function only reads that token; it does not generate one.
-export function readCsrfTokenFromYourCms(): string {
-  const token = document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content;
-  if (!token) throw new Error('Missing CSRF token; load the authenticated application page first.');
-  return token;
-}
-
-export const client = createAuthLinkClient({
-  baseUrl: '/api/authlink',
-  csrfToken: readCsrfTokenFromYourCms,
-  // Replace this example with the configured AuthLink service origin.
-  authLinkOrigin: 'https://auth.example.com',
-});
-```
-
-把 `https://auth.example.com` 换成实际 AuthLink 服务来源。SDK 会在每次请求时调用读取函数，自动把值放入 `X-CSRF-Token`，并携带同源登录 cookie；前端不需要读取 HttpOnly 登录 cookie。若网站框架默认使用其他 CSRF 头名，可用 `csrfHeaderName` 配成后台期望的头名，或者实现自定义 `AuthLinkClient`。
-
-`create` 只传用途，网站账号由后台登录 session 决定。客户端通常只初始化一次；用户点击按钮时才创建请求。完整调用见下方 React 示例，不要把 `client.create()` 放在模块加载、React effect 或 Vue watch 中。
-
-## 前后端分离与跨域后台（0.0.2 起）
-
-默认仍使用同源 `/api/authlink`。直接访问另一个后台来源时，同时配置完整 `baseUrl` 和 `allowedBackendOrigins`，例如网页在 `https://www.example.com`，业务后台在 `https://api.example.com`。来源是协议、主机和端口的组合；同一主域名下不同子域名也属于跨域。
-
-`allowedBackendOrigins` 是前端明确授权的**业务后台来源**，不能带路径、通配符、用户名或密码，不能来自用户输入。生产环境使用 HTTPS；HTTP 仅允许 localhost / 127.0.0.1 / [::1] 开发环境，端口必须匹配。SDK 会先校验目标再读取凭据，并拒绝 HTTP 重定向。`authLinkOrigin` 则用于校验二维码中的 AuthLink 服务来源，两者作用不同，可按需要同时配置。
-
-### 跨域 Cookie / session
-
-下面给出完整的初始化函数。`GET /api/session` 是接入网站自己实现的示例会话接口，不是包或 AuthLink 服务自带的接口；它应根据现有登录 cookie 返回 `{ "csrfToken": "当前会话的真实CSRF token" }`，设置 `Cache-Control: no-store` 并配置下文的 CORS。部署时将路径换成网站实际的会话初始化接口。
-
-这里的 `csrfToken` 是通用示例选定的 JSON 字段名。Go CMS 实例实际返回 `{ authenticated: true, csrf: '…' }`；读取 `session.csrf` 并交给同名 SDK 配置回调即可，无须改动后台响应。完整映射见上方 Go + Vue 指南。
-
-```ts
-import { createAuthLinkClient } from '@auth-link/web';
-
-/** /api/session is an example endpoint implemented by your application backend. */
-export async function createSessionBackendClient(backendOrigin: string) {
-  const response = await fetch(`${backendOrigin}/api/session`, {
-    credentials: 'include', cache: 'no-store', redirect: 'error',
+// getCsrf reads your website's CURRENT session token on every request.
+export function createWebsiteClient(getCsrf: () => string, backendOrigin?: string) {
+  return createAuthLinkClient({
+    baseUrl: backendOrigin ? `${backendOrigin}/api/authlink` : '/api/authlink',
+    allowedBackendOrigins: backendOrigin ? [backendOrigin] : [],
+    credentials: backendOrigin ? 'include' : 'same-origin',
+    csrfToken: getCsrf,
+    authLinkOrigin: 'https://api.getauthlink.com',
   });
-  if (!response.ok) throw new Error('Session initialization failed');
-  const session: unknown = await response.json();
-  if (!session || typeof session !== 'object' || !('csrfToken' in session) ||
-      typeof session.csrfToken !== 'string' || !session.csrfToken) {
-    throw new Error('The session endpoint must return { csrfToken: string }');
-  }
-  let currentCsrfToken = session.csrfToken;
-  return {
-    client: createAuthLinkClient({
-      baseUrl: `${backendOrigin}/api/authlink`,
-      allowedBackendOrigins: [backendOrigin],
-      credentials: 'include',
-      csrfToken: () => currentCsrfToken,
-    }),
-    // Call after your application's session/token refresh; recreate on account changes.
-    updateCsrfToken(value: string) { currentCsrfToken = value; },
-  };
 }
 ```
 
-登录后调用 `await createSessionBackendClient('https://api.example.com')`，把返回的 `client` 交给现有 React/Vue 组件。网站刷新 CSRF token 时调用返回的 `updateCsrfToken(newToken)`；退出或切换账号时关闭旧弹窗，清理旧状态并重新初始化。`credentials: 'include'` 才会让跨域请求携带后台 cookie，但仍受 cookie 的 SameSite、Secure、Domain/Path 及浏览器第三方 Cookie 策略约束；跨域不一定跨站。真正跨站的 cookie 通常需要 `SameSite=None; Secure`，浏览器仍可能阻止第三方 Cookie。不能把 `include` 当成绕过 Cookie 策略的开关。
-
-### 跨域 Bearer token / JWT
-
-传入网站自己的登录状态对象；网站完成登录或刷新后更新这个对象的 `accessToken`。回调会在每次创建和轮询时重新读取最新 token，无需重建弹窗。
+先完成你的网站登录，再读取应用已有的会话接口。下面使用与 CMS 一致的 `{authenticated, csrf}` 响应；如果你的后台字段名为 csrfToken，读取它再交给 SDK 的 csrfToken 回调即可。
 
 ```ts
-import { createAuthLinkClient } from '@auth-link/web';
-
-/** auth is your website's existing login state, updated by its login/refresh flow. */
-export function createBearerBackendClient(backendOrigin: string, auth: { accessToken: string }) {
-  return createAuthLinkClient({
-    baseUrl: `${backendOrigin}/api/authlink`,
-    allowedBackendOrigins: [backendOrigin],
-    credentials: 'omit',
-    accessToken: () => auth.accessToken,
-  });
+// Run in your website's existing authenticated browser flow.
+const backendOrigin = 'https://cms-api.example.com'; // YOUR application backend
+const response = await fetch(`${backendOrigin}/api/session`, {
+  credentials: 'include', cache: 'no-store', redirect: 'error',
+});
+if (!response.ok) throw new Error('Session unavailable');
+let session = await response.json();
+if (session.authenticated !== true || typeof session.csrf !== 'string' || !session.csrf) {
+  throw new Error('Log in to your website first');
 }
+const client = createWebsiteClient(() => session.csrf, backendOrigin);
+// Same origin: createWebsiteClient(() => session.csrf)
+// After token refresh, replace session or update session.csrf.
+// On logout/account/session change, close/unmount old dialogs and recreate client state.
 ```
 
-`accessToken` 必须是接入网站的用户登录 token，不能是 AuthLink 租户 API key。SDK 自动添加 `Authorization: Bearer ...`。纯 Bearer 模式默认 `credentials: 'omit'`，可不传 `csrfToken`；后台应仅按 Bearer token 认证，不回退到 Cookie 登录。若显式设置 `credentials: 'include'` 或 `'same-origin'` 混用 Cookie，仍须提供并校验 `csrfToken`。
-
-### 后台 CORS 配置
+`GET /api/session` 是网站已有接口的示例，请按实际路径替换。同源可以使用相对路径和 same-origin Cookie；跨域 Cookie 使用 include，并要求当前前端来源已被业务后台允许。Cookie 策略仍可能限制请求。浏览器无法读取 HttpOnly Cookie，只需要传回当前会话的 CSRF token；不能用手机核对码或浏览器随机值代替。
 
-后台需处理浏览器发出的 `OPTIONS` 预检，并在预检、实际响应和错误响应中返回相应 CORS 头。会话初始化接口也需要这些设置。以下假设前端来源是 `https://www.example.com`：
+已有 Bearer / JWT 登录的项目可用下列配置，auth 是你的网站登录状态，刷新流程更新 auth.accessToken。此 token 不是 AuthLink 租户密钥。仅在 credentials=omit 的 Bearer 模式可以不传 CSRF；若同时发送 Cookie，仍需 csrfToken。
 
-```http
-Access-Control-Allow-Origin: https://www.example.com
-Access-Control-Allow-Credentials: true
-Access-Control-Allow-Methods: GET, POST, OPTIONS
-Access-Control-Allow-Headers: Content-Type, X-CSRF-Token, Idempotency-Key, Authorization
-Vary: Origin
+```ts
+const backendOrigin = 'https://cms-api.example.com'; // YOUR application backend
+const client = createAuthLinkClient({
+  baseUrl: `${backendOrigin}/api/authlink`, allowedBackendOrigins: [backendOrigin],
+  credentials: 'omit', accessToken: () => auth.accessToken,
+  authLinkOrigin: 'https://api.getauthlink.com',
+});
 ```
 
-携带 Cookie 时不能把 `Access-Control-Allow-Origin` 配为 `*`；多个允许来源应匹配白名单后返回当前来源，不能无条件反射任意 Origin。预检通常不携带登录凭据，因此先验证 Origin、请求方法和请求头，再对实际请求验证登录身份、CSRF（Cookie 模式）和归属。若改了 CSRF 头名或添加自定义头，也要加入 `Access-Control-Allow-Headers`。SDK 不能替后台开启 CORS，也不能用 `no-cors` 读取验证结果。见 [MDN CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS)。
-
-### 请求客户端配置
-
-| 配置 | 说明 |
-| --- | --- |
-| `baseUrl` | 业务后台前缀，默认 `/api/authlink`；跨域时填写完整地址 |
-| `allowedBackendOrigins` | 额外允许的精确后台来源数组，默认只允许当前网页同源 |
-| `credentials` | Cookie 模式默认 `same-origin`；提供 `accessToken` 时默认 `omit`；跨域 Cookie 显式设置 `include` |
-| `csrfToken` | 每次请求读取 CSRF token 的同步或异步函数；Cookie 模式必填 |
-| `csrfHeaderName` | CSRF 请求头名，默认 `X-CSRF-Token`，例如可设为 `X-XSRF-TOKEN` |
-| `accessToken` | 每次请求读取网站 Bearer token 的同步或异步函数；不要包含 `Bearer ` 前缀 |
-| `headers` | 额外的 `HeadersInit` 或返回它的同步/异步函数，可传工作区等自定义头 |
-| `authLinkOrigin` | 核对二维码中的 AuthLink 服务来源，与业务后台来源独立 |
-| `fetch` | 可选 fetch 实现；仍受目标来源和协议校验约束 |
+## 3. Vue：点击创建、展示和清理
 
-SDK 管理 `Accept`、`Content-Type`、`Authorization`、`Idempotency-Key` 和配置的 CSRF 头，`headers` 不能覆盖这些字段，否则报 `RESERVED_HEADER`。用 `accessToken` 设置 Bearer token，用 `csrfHeaderName` 适配后台框架。`ClientOptions` 可从根入口导入为 TypeScript 类型。
+完整文件随包提供为 `examples/vue-client.vue`，可复制为 AuthLinkPanel.vue。父组件在登录后传入当前 session.csrf；跨域时额外传 backendOrigin。退出或切换账号/session 时卸载旧组件，重新挂载新实例；CSRF 刷新可更新 csrf prop。
 
-未授权来源报 `BACKEND_ORIGIN_NOT_ALLOWED`（替代旧版的 `CMS_ORIGIN_REQUIRED`），非法来源/地址分别报 `INVALID_BACKEND_ORIGIN` / `INVALID_BASE_URL`；缺少当前登录 token 报 `ACCESS_TOKEN_REQUIRED`，缺少必要 CSRF 报 `CSRF_REQUIRED`。凭据读取也受请求取消和 10 秒超时控制。网络层的 CORS 错误由浏览器拦截，SDK 通常只能报告 `NETWORK_ERROR`，具体原因需查看浏览器开发者工具。
-
-## 直接调用弹窗（React、Vue 或原生 JavaScript）
-
-```ts
-import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import { client } from './authlink-client';
+```vue
+<script setup lang="ts">
+import { markRaw, onUnmounted, ref, shallowRef } from 'vue';
+import { createAuthLinkClient, requestKey } from '@auth-link/web';
+import type { Confirmation, Mode, Ticket } from '@auth-link/web';
+import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
 import '@auth-link/web/styles.css';
 
-// 在按钮事件中创建请求，再打开弹窗；client 为上文 authlink-client.ts 导出的同源客户端。
-const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
-const modal = openAuthLinkConfirm({
-  ticket, client, locale: 'zh-CN',
-  onConfirmed: result => console.log(result.requestId),
-  onRejected: result => console.log(result.code), // REJECTED，此时弹窗已关闭
-  onClose: () => console.log('已关闭'),
-});
-// 绑定使用 openAuthLinkBind({ ticket: bindingTicket, client })。
-// modal.close(); modal.setLocale('ja');
-```
-
-React / Vue 的 AuthLinkBind、AuthLinkConfirm 挂载后也直接打开弹窗，不再内嵌在页面。React 用 onClose、Vue 用 @close 清空 ticket 并卸载组件。服务端渲染不创建弹窗或请求。支持手机窄屏、内容滚动、关闭按钮及 Escape；要求浏览器支持原生 dialog.showModal()。弹窗挂到 document.body，主题变量请配置在 :root 或 .authlink-dialog。
-
-关闭只停止前端查询，不拒绝或撤销服务端请求；请求仍按原有效期结束。确认成功或拒绝后弹窗自动关闭，分别回调 onConfirmed 或 onRejected，不触发用户关闭回调。直接调用时，页面卸载须执行 modal.destroy() 清理，它不触发用户关闭回调。切换语言用 modal.setLocale()，不会重建鉴权请求。
+// csrf comes from your website's current authenticated session.
+const props = defineProps<{ csrf: string; backendOrigin?: string }>();
+const ticket = shallowRef<Ticket | null>(null);
+const busy = ref(false), message = ref('');
+const lifetime = new AbortController();
+let creationKey: string | null = null;
+let creationMode: Mode | null = null;
+const client = markRaw(createAuthLinkClient({
+  baseUrl: props.backendOrigin ? `${props.backendOrigin}/api/authlink` : '/api/authlink',
+  allowedBackendOrigins: props.backendOrigin ? [props.backendOrigin] : [],
+  credentials: props.backendOrigin ? 'include' : 'same-origin',
+  csrfToken: () => props.csrf,
+  authLinkOrigin: 'https://api.getauthlink.com',
+}));
+function finish(text: string) { ticket.value = null; message.value = text; }
+function confirmed(result: Confirmation) {
+  finish(`${result.purpose}: ${result.requestId}`);
+  // Reload your website's account/status API if the page needs fresh state.
+}
+function showError(error: Error) { message.value = error.message; }
+async function start(mode: Mode) {
+  if (busy.value || ticket.value) return;
+  busy.value = true; message.value = '';
+  try {
+    if (creationMode !== mode) { creationKey = null; creationMode = mode; }
+    creationKey ??= requestKey();
+    const value = await client.create(mode, { idempotencyKey: creationKey, signal: lifetime.signal });
+    if (lifetime.signal.aborted) return;
+    ticket.value = value; creationKey = null;
+  } catch (error) {
+    if (!lifetime.signal.aborted) showError(error as Error);
+    // Keep the same key when retrying an uncertain creation of the same mode.
+  } finally { busy.value = false; }
+}
+onUnmounted(() => { lifetime.abort(); ticket.value = null; creationKey = null; });
+</script>
 
+<template>
+  <button :disabled="busy || !!ticket" @click="start('bind')">Bind phone</button>
+  <button :disabled="busy || !!ticket" @click="start('confirm')">Confirm</button>
+  <AuthLinkBind v-if="ticket?.purpose === 'bind'" :ticket="ticket" :client="client" variant="B"
+    @confirmed="confirmed" @close="finish('Closed')" @rejected="finish('Rejected')"
+    @expired="finish('Expired; start again')" @error="showError" />
+  <AuthLinkConfirm v-else-if="ticket?.purpose === 'confirm'" :ticket="ticket" :client="client" variant="B"
+    @confirmed="confirmed" @close="finish('Closed')" @rejected="finish('Rejected')"
+    @expired="finish('Expired; start again')" @error="showError" />
+  <p role="status">{{ message }}</p>
+</template>
+```
 
-## React
+示例使用 shallowRef 保存 ticket、markRaw 保存 client。创建失败保留同一用途的原幂等键；成功后才清空。创建只发生在点击事件中，mounted/watch 不创建请求。确认、拒绝、过期或用户关闭时清空 ticket，卸载组件；网络错误保留弹窗，使用弹窗的重试按钮继续当前请求。需要真实账号状态时重新查询你的网站状态接口。
 
-下面的 `showBound` 也是接入方函数，负责更新页面提示和清空 `ticket`，从而卸载弹窗；它不向后台提交“绑定成功”，也不保存绑定。绑定及确认记录必须在后台查询结果接口验证、消费并保存后，才返回 `confirmed`。
+## 4. React
 
-这个示例包含按钮、请求创建、结果提示和弹窗清理，不再依赖未定义的 `showBound`、`showRejected` 等函数。使用 `<AuthLinkPanel mode="bind" />` 绑定，使用 `<AuthLinkPanel mode="confirm" />` 请求手机确认。
+使用上面的初始化方式创建稳定 client，再传给此组件；mode 为 bind 或 confirm。退出或切换账号/session 时卸载旧实例。
 
 ```tsx
 "use client";
-import { useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { requestKey } from '@auth-link/web';
-import type { Mode, Ticket } from '@auth-link/web';
+import type { AuthLinkClient, Mode, Ticket } from '@auth-link/web';
 import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-import { client } from './authlink-client';
+// Import '@auth-link/web/styles.css' once in your application entry.
 
-export function AuthLinkPanel({ mode }: { mode: Mode }) {
+export function AuthLinkPanel({ client, mode }: { client: AuthLinkClient; mode: Mode }) {
   const [ticket, setTicket] = useState<Ticket | null>(null);
   const [busy, setBusy] = useState(false);
   const [message, setMessage] = useState('');
-  const key = useRef<string | null>(null);
-  const creating = useRef(false);
-  function finish(message: string) {
-    setTicket(null);
-    setMessage(message);
-  }
-  function showBound(requestId: string) {
-    // UI feedback only. The backend has already verified and saved the binding.
-    finish(`手机绑定成功（请求 ${requestId}）`);
-  }
-  function showConfirmed(requestId: string) {
-    finish(`手机确认成功（请求 ${requestId}）`);
-  }
-  const start = async () => {
-    if (creating.current || ticket) return;
-    creating.current = true;
-    setBusy(true);
-    setMessage('');
+  const creation = useRef<{ mode: Mode; key: string } | null>(null);
+  const inFlight = useRef(false);
+  const controller = useRef<AbortController | null>(null);
+  useEffect(() => () => { controller.current?.abort(); }, []);
+  function finish(text: string) { setTicket(null); setMessage(text); }
+  async function start() {
+    if (inFlight.current || ticket) return;
+    inFlight.current = true; setBusy(true); setMessage('');
+    const attempt = new AbortController(); controller.current = attempt;
     try {
-      key.current ??= requestKey();
-      setTicket(await client.create(mode, { idempotencyKey: key.current }));
-      key.current = null;
-    } catch { setMessage('请求未完成，可重试同一次创建。'); }
-    finally { creating.current = false; setBusy(false); }
-  };
+      if (creation.current?.mode !== mode) creation.current = { mode, key: requestKey() };
+      const value = await client.create(mode, { idempotencyKey: creation.current.key, signal: attempt.signal });
+      if (attempt.signal.aborted) return;
+      setTicket(value); creation.current = null;
+    } catch (error) { if (!attempt.signal.aborted) setMessage((error as Error).message); }
+    finally {
+      inFlight.current = false;
+      if (!attempt.signal.aborted) setBusy(false);
+    }
+  }
   const Component = mode === 'bind' ? AuthLinkBind : AuthLinkConfirm;
   return <>
-    {!ticket && <button type="button" disabled={busy} onClick={() => void start()}>开始验证</button>}
-    {ticket && <Component ticket={ticket} client={client}
-      onConfirmed={result => result.purpose === 'bind' ? showBound(result.requestId) : showConfirmed(result.requestId)}
-      onClose={() => finish('已关闭')}
-      onRejected={() => finish('手机已拒绝本次请求')}
-      onExpired={() => finish('请求已过期，请重新发起')}
+    {!ticket && <button disabled={busy} onClick={() => void start()}>Start verification</button>}
+    {ticket && <Component ticket={ticket} client={client} variant="B"
+      onConfirmed={result => finish(`${result.purpose}: ${result.requestId}`)}
+      onClose={() => finish('Closed')} onRejected={() => finish('Rejected')}
+      onExpired={() => finish('Expired; start again')}
       onError={error => setMessage(error.message)} />}
     <p role="status">{message}</p>
   </>;
 }
 ```
 
-`requestId` 用于展示或追踪本次请求，不是授权凭据。`showBound` 也可以按网站需求显示 toast、重新查询已有的账号状态接口或导航到绑定管理页。刷新页面后，应重新从后台读取真实绑定状态，不能只依赖 React state 或 localStorage。其他业务接口仍需在后台检查权限。
-
-创建失败时示例保留同一个幂等键；再次点击会重试同一次创建。创建成功后清空幂等键，新的用户操作才创建新请求。关闭、成功、拒绝和过期都会清空 ticket；网络错误保留弹窗，供其重试当前请求。
-
-确认组件默认只显示动态数字；`showQr` 可额外显示扫码入口。绑定组件始终显示二维码。`onRefresh` 可提供重新创建请求的函数；仅过期后显示该按钮。组件自身的“重试”只恢复当前请求，不创建第二个请求。
-
-未指定 `locale` 时使用简体中文；不支持的语言代码也回退到简体中文。组件根元素设置对应的 `lang`，语言切换不会重新创建鉴权请求。
-
-React 入口保留 `"use client"`，可用于 Next.js 客户端组件。导入包和 SSR 渲染不会创建请求。将 client 与 ticket 保持为稳定对象，例如模块级 client 和 React state 中的 ticket。卸载/切换 ticket 会取消旧轮询；StrictMode 不会创建额外请求。
-
-## Vue
-
-```vue
-<script setup lang="ts">
-import { ref, shallowRef } from 'vue';
-import { requestKey } from '@auth-link/web';
-import type { Confirmation, Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
-import { client } from './authlink-client';
-const props = defineProps<{ mode: Mode }>();
-const ticket = shallowRef<Ticket | null>(null);
-const busy = ref(false);
-const message = ref('');
-let key: string | null = null;
-function finish(text: string) { ticket.value = null; message.value = text; }
-function confirmed(result: Confirmation) {
-  finish(`${result.purpose === 'bind' ? '已绑定' : '已确认'}（请求 ${result.requestId}）`);
-}
-async function start() {
-  if (busy.value) return;
-  busy.value = true;
-  key ??= requestKey();
-  try {
-    ticket.value = await client.create(props.mode, { idempotencyKey: key });
-    key = null;
-  } catch { message.value = '请求未完成，可重试同一次创建。'; }
-  finally { busy.value = false; }
-}
-</script>
-
-<template>
-  <button v-if="!ticket" type="button" :disabled="busy" @click="start">开始验证</button>
-  <AuthLinkBind v-else-if="mode === 'bind'" :ticket="ticket" :client="client"
-    @confirmed="confirmed" @close="finish('已关闭')" @rejected="finish('手机已拒绝本次请求')"
-    @expired="finish('请求已过期，请重新发起')" @error="message = '网络异常，请重试。'" />
-  <AuthLinkConfirm v-else :ticket="ticket" :client="client"
-    @confirmed="confirmed" @close="finish('已关闭')" @rejected="finish('手机已拒绝本次请求')"
-    @expired="finish('请求已过期，请重新发起')" @error="message = '网络异常，请重试。'" />
-  <p role="status">{{ message }}</p>
-</template>
-```
-
-拒绝时返回 `{ status: 'rejected', code: 'REJECTED', requestId, purpose }`。`REJECTED` 是 SDK 业务状态码，不是 HTTP 状态码或授权凭证。组件自动关闭，不再显示“已拒绝 / 重新发起”面板，也不触发 `onClose`；提示和重新发起由接入网站在回调中决定。React / Vue 请在 `onRejected` / `@rejected` 中清空 ticket、卸载组件。无 UI 的 hook 仍保留 `snapshot.status === 'rejected'`，供自定义界面使用。
-
-此示例在过期后清空 ticket，用户可再次点击按钮发起请求。如果需要在过期弹窗内提供重新发起按钮，可自行传入 `onRefresh`，在回调中创建新请求并更新 ticket。`useAuthLink(() => options)` composable 与 React 的 `useAuthLink(options)` hook 可用于自定义界面，返回 `snapshot` 和 `retry`；Vue 的 snapshot 是浅 ref。
-
-## 选择弹窗样式
-
-初始化时通过 `variant` 选择样式，**不传时默认 A**。
-
-| 参数值 | 电脑端 | 手机端 |
-| --- | --- | --- |
-| `A`（默认） | 极简居中卡片、细线数字更新进度条 | 居中卡片 |
-| `B` | 二维码和核对码左右分栏 | 自动纵向排列 |
-| `C` | 紧凑卡片、底部取消入口 | 底部弹层，适配安全区域 |
+## 5. 原生 JavaScript / 直接调用
 
 ```ts
-openAuthLinkBind({ ticket, client }); // 默认 A、简体中文
-openAuthLinkConfirm({ ticket, client, variant: 'B' });
-// modal.setVariant('C'); // 只更新显示，不重建请求、不重启查询
-```
-
-```tsx
-<AuthLinkBind ticket={ticket} client={client} variant="C" />
-```
+import { openAuthLinkConfirm, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
 
-```vue
-<AuthLinkConfirm :ticket="ticket" :client="client" variant="B" />
+// Inside a click handler; client is the stable instance created above.
+const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
+const modal = openAuthLinkConfirm({
+  ticket, client, variant: 'B', locale: 'zh-CN',
+  onConfirmed: result => console.log(result.requestId),
+  onRejected: result => console.log(result.code),
+  onExpired: () => console.log('Expired'),
+  onError: error => console.log(error.message),
+  onClose: () => console.log('Closed'),
+});
+// Route/component cleanup: modal.destroy();
+// Optional: modal.close(); modal.retry(); modal.setLocale('ja'); modal.setVariant('C');
 ```
 
-三套样式统一使用细进度条和固定文案“核对码每 30 秒自动更新”，不显示数字更新秒数。底部通常显示“等待手机确认”；仅最后 30 秒改为柔和橙色“请求即将过期 · 00:29”。新核对码轻微淡入，遵守系统减少动态效果设置；数字刷新不延长请求有效期。
-
-三套样式使用相同的鉴权、过期和回调逻辑。React / Vue 可响应式切换 `variant`，不会重新发起请求；无效的运行时值回退到 A。B / C 的底部“取消”和右上角关闭行为一致，仅停止前端观察，不会替用户拒绝服务端请求。确认成功仍自动关闭。关闭图标保留 44px 点击区域和键盘焦点提示。
-
-## 组件参数与事件
+绑定改用 `client.create('bind', ...)` 和 `openAuthLinkBind(...)`。确认或拒绝会先自动关闭再触发对应回调，不触发 onClose。关闭只停止前端观察；页面或组件退出时必须调用 destroy。每个实例对同一请求只通知一次成功；回调用于界面更新，受保护操作仍请求你的网站业务 API。
 
-`AuthLinkBind` 用于绑定二维码，`AuthLinkConfirm` 用于手机确认。两者使用相同的主要参数：
+## 6. 前端需要的接口约定
 
-| 参数 | 类型 | 说明 |
+| 网站接口 | 前端发送 | 前端读取 |
 | --- | --- | --- |
-| `ticket` | `Ticket`，必填 |应用后台创建的当前请求；组件不会自行创建请求 |
-| `client` | `AuthLinkClient`，必填 | 查询应用后台结果的客户端 |
-| `locale` | `Locale`，见下表 | 界面语言，默认 `zh-CN` |
-| `variant` | `DialogVariant` | `A`（默认）、`B` 或 `C`；只改变布局 |
-| `showQr` | `boolean` | 确认组件是否额外显示二维码；绑定组件始终显示 |
-| `intervalMs` | `number` | 结果轮询间隔，默认 1500 毫秒 |
-| `onRefresh` | `() => void` | 过期后，由网站重新创建请求并更新 ticket |
-
-| React 回调 / Vue 事件 | 参数 | 触发时机 |
-| --- | --- | --- |
-| `onConfirmed` / `confirmed` | `Confirmation` |应用后台完成结果验证和消费后 |
-| `onRejected` / `rejected` | `Rejection` | 手机拒绝请求，弹窗自动关闭 |
-| `onExpired` / `expired` | 无 | 请求已过期 |
-| `onError` / `error` | `Error` | 网络错误、响应校验失败或成功回调执行失败等 |
-
-业务处理以 `requestId` / `verificationId` 做持久化幂等。前端成功事件用于展示状态，不能作为后台接口放行凭据。
+| `POST /api/authlink/requests` | `{purpose:'bind'}` 或 confirm；`Idempotency-Key` | `Ticket` |
+| `POST /api/authlink/requests/{requestId}/result` | `{}`；当前登录凭据 | `Result`，由 SDK 自动轮询 |
 
-## 导入入口
-
-| 入口 | 用途 |
-| --- | --- |
-| `@auth-link/web` | `createAuthLinkClient`、`requestKey`、公开类型及无框架工具 |
-| `@auth-link/web/react` | React 组件和 `useAuthLink` |
-| `@auth-link/web/vue` | Vue 组件和 `useAuthLink` |
-| `@auth-link/web/styles.css` | 组件样式，需显式导入 |
+Cookie 模式两者均发送当前 CSRF 头。Ticket 包含 requestId、purpose、qr、pairingCode、expiresAt；confirm 还需要 displayCode。直接导入包内 Ticket / Result / Confirmation 类型，不自行生成 QR 内容或动态数字。只有 status=confirmed 触发成功事件；new/pending/approved/consumed 是等待状态，rejected/expired 分别触发对应事件。
 
-## 应用后台接口约定
-
-默认前缀 `/api/authlink`；下面两个接口由接入方实现，**不是直接把浏览器请求转发到租户密钥 API**。
-
-### `POST /requests`
-
-浏览器按所选模式携带网站登录凭据：Cookie 模式发送 session cookie 和配置的 CSRF 头，Bearer 模式发送 `Authorization`。创建还发送稳定的 `Idempotency-Key`，body：
-
-```json
-{"purpose":"bind"}
-```
-
-后台从经过验证的 session 或 Bearer token 取得用户 ID，创建并持久保存 state、创建/消费幂等键、用户/session 关联，然后调用 AuthLink 服务端创建请求。返回其公开 ticket：
+若你的网站创建接口需要文章 ID、版本等额外参数，SDK create() 只发送 purpose，因此使用自己的 fetch 创建，然后校验 ticket 并交给同一组件。下面的 post、session、backendOrigin 均来自你自己的前端状态；幂等键应保存到重试状态，失败时不要重新生成。
 
 ```ts
-type Ticket = {
-  requestId: string;
-  purpose: 'bind' | 'confirm';
-  qr: string; // AuthLink 返回的 QR JSON，不是 HTML
-  pairingCode: string;
-  expiresAt: string;
-  displayCode: {
-    value: string; // 六位数字，保留前导零
-    serverTime: string; validUntil: string;
-    periodSeconds: 30;
-  };
-};
+import { requestKey, validateTicket } from '@auth-link/web';
+
+// Keep this key across retries of the SAME operation and payload.
+const idempotencyKey = requestKey();
+const response = await fetch(`${backendOrigin}/api/authlink/requests`, {
+  method: 'POST', credentials: 'include', cache: 'no-store', redirect: 'error',
+  headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': session.csrf,
+    'Idempotency-Key': idempotencyKey },
+  body: JSON.stringify({ purpose: 'confirm', postId: post.id, version: post.version }),
+});
+if (!response.ok) throw new Error('Creation failed');
+const ticket = validateTicket(await response.json(), 'confirm', 'https://api.getauthlink.com');
+// Pass ticket and the same client to AuthLinkConfirm.
 ```
 
-### `POST /requests/{requestId}/result`
-
-同样验证登录身份（Cookie 模式还需 CSRF）和请求归属。后台调用 AuthLink 状态接口，将 `displayCode` 原样返回，不能缓存跨过 `validUntil`。新代码由后台实时获取，不是前端自行生成。
-
-尚未完成时返回 `{requestId,status,displayCode?}`；状态可为 new / pending / approved / consumed / rejected / expired。`approved` 不能触发成功事件。
+## 7. 参数、事件与样式
 
-收到 approved / consumed 后，后台使用保存的稳定消费幂等键调用 `/consume`，核对完整结果，在自己数据库事务中记录此次 session 的确认，再返回已验证的回执。组件确认所需最小字段：
-
-```json
-{
-  "status":"confirmed",
-  "requestId":"43字符请求ID",
-  "verificationId":"43字符结果ID",
-  "purpose":"confirm",
-  "authenticationPolicy":"device-presence.v1",
-  "expiresAt":"与创建请求完全一致的期限"
-}
-```
-
-服务端必须在同一事务内记录已验证的确认结果，并校验请求归属。网页事件只用于更新界面；受保护接口必须依赖后台的可信确认记录，不能依赖 JS 回调或浏览器传来的 confirmed。
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| `ticket` | `Ticket` | Required; the current request |
+| `client` | `AuthLinkClient` | Required; keep the instance stable |
+| `locale` | `Locale` | Default `zh-CN` |
+| `variant` | `'A' / 'B' / 'C'` | Default `A` |
+| `showQr` | `boolean` | Optional QR for confirm; bind always shows QR |
+| `intervalMs` | `number` | Default 1500; range 250–10000 ms |
+| `onRefresh` | `() => void` | Optional user action after expiry; create a new ticket |
+| `className` | `string` | Custom dialog class; Vue also accepts `class` |
+
+| React 回调 / Vue 事件 | 参数 | 行为 |
+| --- | --- | --- |
+| `onConfirmed` / `confirmed` | `Confirmation` | Success; dialog closes automatically |
+| `onRejected` / `rejected` | `Rejection` | `{status:'rejected',code:'REJECTED',requestId,purpose}`; dialog closes |
+| `onExpired` / `expired` | — | Request expired |
+| `onClose` / `close` | — | User closes the dialog; clear ticket |
+| `onError` / `error` | `Error` | Read `error.message`; retain the dialog for retry |
 
-## 数字、时钟与安全
+A 为默认居中卡片；B 为桌面分栏、窄屏纵排；C 为紧凑卡片、手机底部弹层。切换 locale/variant 不重新创建请求。原生 dialog.showModal() 浏览器支持是必需的。
 
-- 每个请求独立派生数字生成 seed；seed 只通过 claim 发给手机，并纳入设备签名上下文。网页只得到当前数字、服务端时间和本步期限。
-- 倒计时使用服务端时间锚点和单调时钟；本机系统时钟错误不直接导致倒计时漂移。网络延迟仍有影响，跨步时可能短暂显示“正在更新数字”，稳定后再核对。
-- 旧数字一过本步期限就隐藏，即使网络请求仍未返回。整个请求过期、拒绝或失败会隐藏数字和二维码。
-- 组件按请求检查成功结果、用途、双重认证策略和有效期。取消、卸载和切换请求后，旧响应不能触发成功回调。
-- 每个组件实例对同一请求只发一次成功事件；刷新或重新挂载不替代网站持久化幂等。
-- 包不接收网站业务授权内容，不提供 apiKey 配置，不执行支付/授权等业务操作。
-- 二维码在浏览器内生成，忽略后台 qrSvg，不使用 innerHTML；不上传给第三方图片服务。应用 CSP 需允许 `img-src 'self' data:`。
+CSS 需单独导入。弹窗挂到 document.body，主题变量放在 :root 或 .authlink-dialog：`--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted`。Vue 的 class 支持字符串、数组和对象，并与 className 合并。SSR 不展示弹窗或创建请求。
 
-## 样式与语言
+语言：`zh-CN` (default), `zh-TW`, `en`, `ja`, `bn`, `es`, `fil`, `hi`, `id`, `ms`, `pt`, `th`, `vi`。未指定或不支持时回退简体中文，可导入 supportedLocales 获取列表。
 
-CSS 单独导入，所有类使用 `authlink-` 前缀。弹窗挂载到 `document.body`，可在 `:root` 或 `.authlink-dialog` 覆盖 `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted`。面板语言见下表，默认简体中文。
+## 8. 传输配置与排错
 
-React / Vue 均支持 `className`；Vue 还支持字符串、数组和对象形式的 `class`，与 `className` 合并。“重新发起”按钮使用父组件最新传入的 `onRefresh` 回调。
+| 配置 | 用途 |
+| --- | --- |
+| `baseUrl` | Your application API prefix; default `/api/authlink` |
+| `allowedBackendOrigins` | Exact extra application API origins; no paths/wildcards |
+| `credentials` | Default `same-origin`; cross-origin cookies need `include` |
+| `csrfToken` | Sync/async getter for the current website CSRF token |
+| `csrfHeaderName` | Default `X-CSRF-Token` |
+| `accessToken` | Sync/async website Bearer token getter, without `Bearer ` |
+| `headers` | Extra headers or sync/async getter |
+| `authLinkOrigin` | `https://api.getauthlink.com` for production AuthLink |
+| `fetch` | Optional fetch implementation |
 
+自定义 headers 不能覆盖 Accept、Content-Type、Authorization、Idempotency-Key 或配置的 CSRF 头。错误信息可从 error.message 读取：CSRF_REQUIRED 检查当前 token；ACCESS_TOKEN_REQUIRED 检查登录 token；BACKEND_ORIGIN_NOT_ALLOWED 检查完整来源允许列表；NETWORK_ERROR 检查浏览器 Network 面板、网络和 CORS。SDK 请求超时为 10 秒，关闭/卸载会取消观察。
 
-| Code | Language |
-| --- | --- |
-| `en` | English |
-| `zh-CN` | 简体中文 (default) |
-| `zh-TW` | 繁體中文 |
-| `ja` | 日本語 |
-| `bn` | বাংলা |
-| `es` | Español |
-| `fil` | Filipino |
-| `hi` | हिन्दी |
-| `id` | Bahasa Indonesia |
-| `ms` | Bahasa Melayu |
-| `pt` | Português |
-| `th` | ไทย |
-| `vi` | Tiếng Việt |
-
-可以从根入口导入 `supportedLocales` 获取支持列表。文档默认英文，另有中文与日文版本。
-
-## 兼容性
-
-React 18.2+ / 19、Vue 3.3+、TypeScript、ESM。React 和 Vue 是可选 peer，只安装所用框架。构建工具环境需 Node 22.13+。
+数字过期会隐藏，不在前端生成或缓存新数字；二维码在浏览器本地生成。若页面启用 CSP，图片来源需要允许 data:。确认回调、localStorage 或浏览器自报状态都不作为业务授权依据。
 
 ## 许可证
 
-MIT。完整许可文本见 `LICENSE`，打包包含的第三方库归属说明见 `THIRD_PARTY_NOTICES.md`。
+MIT。完整文本见 LICENSE，第三方归属见 THIRD_PARTY_NOTICES.md。