@auth-link/web 0.0.4 → 1.1.0

package/docs/README.zh-CN.md

@@ -1,475 +1,62 @@
-# AuthLink Web
+# AuthLink Web 1.1
 
-[English](../README.md) | **简体中文** | [日本語](./README.ja.md)
+[English](README.en.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
 
-**AuthLink 官方前端组件包**，帮助网站接入手机绑定与 App 确认流程，支持 React 18/19、Vue 3.3+、TypeScript 和 ESM。
+## 直接验证动态码
 
-## Go + Vue 完整接入
+App 直接显示六位动态码。日常验证不需要逐次批准、授权 requestId、businessId 或轮询。首次绑定仍需扫码验证设备，在网站输入 App 当前动态码后才完成绑定。
 
-按实际 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 必须使用当前单一协议，不能只升级网页。
-
-## 安装
-
-在应用项目中安装：
+打开弹窗前，CMS 后台必须为会话原子保留唯一且不可变的待办。其他标签页不能覆盖它。用户来自服务端会话，后台检查 CSRF、业务权限和原表单，验证动态码后将 verificationId 与原操作原子提交，再返回成功。onVerified 只更新界面。
 
 ```sh
-npm install @auth-link/web
-```
-
-## 创建应用客户端（默认同源 Cookie 模式）
-
-`readCsrfTokenFromYourCms` 是接入方函数，不是包里的导出；名称不要求与你的网站框架一致，也不要求使用 CMS。它只读取**你的网站后台提供的 CSRF token**，用于保护携带登录 cookie 的请求，不是 AuthLink 租户 API key、登录 cookie 或手机核对码。
-
-下面采用页面 meta 标签的方式。后台需要先准备 token：
-
-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 自带接口。
-
-```html
-<!-- 由你的网站后台渲染到当前用户的页面 head 中 -->
-<meta name="csrf-token" content="{{ csrfToken }}">
-```
-
-新建 `authlink-client.ts`：
-
-```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,
-  // AuthLink production API origin.
-  authLinkOrigin: 'https://api.getauthlink.com',
-});
-```
-
-AuthLink 生产服务来源为 `https://api.getauthlink.com`。`baseUrl` 仍填写你自己的网站业务后台，官网域名不用于接口调用；连接独立部署的 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',
-  });
-  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; },
-  };
-}
+npm install @auth-link/web@^1.1.0
 ```
 
-登录后调用 `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，无需重建弹窗。
-
-```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,
-  });
-}
-```
-
-`accessToken` 必须是接入网站的用户登录 token，不能是 AuthLink 租户 API key。SDK 自动添加 `Authorization: Bearer ...`。纯 Bearer 模式默认 `credentials: 'omit'`，可不传 `csrfToken`；后台应仅按 Bearer token 认证，不回退到 Cookie 登录。若显式设置 `credentials: 'include'` 或 `'same-origin'` 混用 Cookie，仍须提供并校验 `csrfToken`。
-
-### 后台 CORS 配置
-
-后台需处理浏览器发出的 `OPTIONS` 预检，并在预检、实际响应和错误响应中返回相应 CORS 头。会话初始化接口也需要这些设置。以下假设前端来源是 `https://www.example.com`：
-
-```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
-```
-
-携带 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 实现；仍受目标来源和协议校验约束 |
-
-SDK 管理 `Accept`、`Content-Type`、`Authorization`、`Idempotency-Key` 和配置的 CSRF 头，`headers` 不能覆盖这些字段，否则报 `RESERVED_HEADER`。用 `accessToken` 设置 Bearer token，用 `csrfHeaderName` 适配后台框架。`ClientOptions` 可从根入口导入为 TypeScript 类型。
-
-未授权来源报 `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';
+import { openPasscode, createPasscodeClient } from '@auth-link/web';
 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('已关闭'),
+const client = createPasscodeClient({ baseUrl: '/api', csrfToken: () => csrfToken });
+const modal = openPasscode({
+  client, expiresAt: pending.expiresAt, locale: 'zh-CN', variant: 'B',
+  // First-time enrollment only:
+  // bindingQr: pending.bindingQr, authLinkOrigin: 'https://api.getauthlink.com',
+  onVerified: result => updateUI(result.verificationId),
 });
-// 绑定使用 openAuthLinkBind({ ticket: bindingTicket, client })。
-// modal.close(); modal.setLocale('ja');
+// modal.setLocale('en'); modal.setVariant('C'); modal.destroy();
 ```
 
-React / Vue 的 AuthLinkBind、AuthLinkConfirm 挂载后也直接打开弹窗，不再内嵌在页面。React 用 onClose、Vue 用 @close 清空 ticket 并卸载组件。服务端渲染不创建弹窗或请求。支持手机窄屏、内容滚动、关闭按钮及 Escape；要求浏览器支持原生 dialog.showModal()。弹窗挂到 document.body，主题变量请配置在 :root 或 .authlink-dialog。
+默认客户端向 CMS 的 POST /api/auth 提交 {passcode}，携带当前会话与 CSRF。要随表单提交，可自行实现 client.verify，向 CMS 发送 {form,passcode}；后台核对原保存快照。租户密钥与动态码密钥不能进入浏览器。
 
-关闭只停止前端查询，不拒绝或撤销服务端请求；请求仍按原有效期结束。确认成功或拒绝后弹窗自动关闭，分别回调 onConfirmed 或 onRejected，不触发用户关闭回调。直接调用时，页面卸载须执行 modal.destroy() 清理，它不触发用户关闭回调。切换语言用 modal.setLocale()，不会重建鉴权请求。
+## 选项与回调
 
+必填：client.verify(passcode, signal)、expiresAt（CMS 待办截止时间）。可选：locale、variant A/B/C、仅首次绑定使用的 bindingQr 与 authLinkOrigin、onVerified、onError、onClose、onExpired。成功结果含 status、verificationId、authenticationPolicy、expiresAt，不含 requestId 或 businessId。
 
-## React
+Cookie 模式必须配置 CSRF。Bearer 模式配置 accessToken 且 credentials=omit。跨域 CMS 必须显式配置 allowedBackendOrigins；回环开发之外使用 HTTPS。
 
-下面的 `showBound` 也是接入方函数，负责更新页面提示和清空 `ticket`，从而卸载弹窗；它不向后台提交“绑定成功”，也不保存绑定。绑定及确认记录必须在后台查询结果接口验证、消费并保存后，才返回 `confirmed`。
+## React 与 Vue
 
-这个示例包含按钮、请求创建、结果提示和弹窗清理，不再依赖未定义的 `showBound`、`showRejected` 等函数。使用 `<AuthLinkPanel mode="bind" />` 绑定，使用 `<AuthLinkPanel mode="confirm" />` 请求手机确认。
+React 组件使用相同选项，Vue 发出 verified、error、close、expired 事件。client 引用需保持稳定。支持 13 种语言，默认简体中文；A 极简、B 分栏、C 紧凑。
 
 ```tsx
-"use client";
-import { useRef, useState } from 'react';
-import { requestKey } from '@auth-link/web';
-import type { Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-import { client } from './authlink-client';
-
-export function AuthLinkPanel({ mode }: { 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('');
-    try {
-      key.current ??= requestKey();
-      setTicket(await client.create(mode, { idempotencyKey: key.current }));
-      key.current = null;
-    } catch { setMessage('请求未完成，可重试同一次创建。'); }
-    finally { creating.current = false; 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('请求已过期，请重新发起')}
-      onError={error => setMessage(error.message)} />}
-    <p role="status">{message}</p>
-  </>;
-}
+import { AuthLinkPasscode } from '@auth-link/web/react';
+// Keep client stable (for example with useMemo).
+<AuthLinkPasscode client={client} expiresAt={pending.expiresAt}
+  locale="zh-CN" variant="B" onVerified={updateUI} />
 ```
-
-`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 setup>
+import { AuthLinkPasscode } from '@auth-link/web/vue';
 </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>
+  <AuthLinkPasscode :client="client" :expires-at="pending.expiresAt"
+    locale="zh-CN" variant="B" @verified="updateUI" />
 </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` | 紧凑卡片、底部取消入口 | 底部弹层，适配安全区域 |
-
-```ts
-openAuthLinkBind({ ticket, client }); // 默认 A、简体中文
-openAuthLinkConfirm({ ticket, client, variant: 'B' });
-// modal.setVariant('C'); // 只更新显示，不重建请求、不重启查询
-```
-
-```tsx
-<AuthLinkBind ticket={ticket} client={client} variant="C" />
-```
-
-```vue
-<AuthLinkConfirm :ticket="ticket" :client="client" variant="B" />
-```
-
-三套样式统一使用细进度条和固定文案“核对码每 30 秒自动更新”，不显示数字更新秒数。底部通常显示“等待手机确认”；仅最后 30 秒改为柔和橙色“请求即将过期 · 00:29”。新核对码轻微淡入，遵守系统减少动态效果设置；数字刷新不延长请求有效期。
-
-三套样式使用相同的鉴权、过期和回调逻辑。React / Vue 可响应式切换 `variant`，不会重新发起请求；无效的运行时值回退到 A。B / C 的底部“取消”和右上角关闭行为一致，仅停止前端观察，不会替用户拒绝服务端请求。确认成功仍自动关闭。关闭图标保留 44px 点击区域和键盘焦点提示。
-
-## 组件参数与事件
-
-`AuthLinkBind` 用于绑定二维码，`AuthLinkConfirm` 用于手机确认。两者使用相同的主要参数：
-
-| 参数 | 类型 | 说明 |
-| --- | --- | --- |
-| `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` 做持久化幂等。前端成功事件用于展示状态，不能作为后台接口放行凭据。
-
-## 导入入口
-
-| 入口 | 用途 |
-| --- | --- |
-| `@auth-link/web` | `createAuthLinkClient`、`requestKey`、公开类型及无框架工具 |
-| `@auth-link/web/react` | React 组件和 `useAuthLink` |
-| `@auth-link/web/vue` | Vue 组件和 `useAuthLink` |
-| `@auth-link/web/styles.css` | 组件样式，需显式导入 |
-
-## 应用后台接口约定
-
-默认前缀 `/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：
-
-```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;
-  };
-};
-```
-
-### `POST /requests/{requestId}/result`
-
-同样验证登录身份（Cookie 模式还需 CSRF）和请求归属。后台调用 AuthLink 状态接口，将 `displayCode` 原样返回，不能缓存跨过 `validUntil`。新代码由后台实时获取，不是前端自行生成。
-
-尚未完成时返回 `{requestId,status,displayCode?}`；状态可为 new / pending / approved / consumed / rejected / expired。`approved` 不能触发成功事件。
-
-收到 approved / consumed 后，后台使用保存的稳定消费幂等键调用 `/consume`，核对完整结果，在自己数据库事务中记录此次 session 的确认，再返回已验证的回执。组件确认所需最小字段：
-
-```json
-{
-  "status":"confirmed",
-  "requestId":"43字符请求ID",
-  "verificationId":"43字符结果ID",
-  "purpose":"confirm",
-  "authenticationPolicy":"device-presence.v1",
-  "expiresAt":"与创建请求完全一致的期限"
-}
-```
-
-服务端必须在同一事务内记录已验证的确认结果，并校验请求归属。网页事件只用于更新界面；受保护接口必须依赖后台的可信确认记录，不能依赖 JS 回调或浏览器传来的 confirmed。
-
-## 数字、时钟与安全
-
-- 每个请求独立派生数字生成 seed；seed 只通过 claim 发给手机，并纳入设备签名上下文。网页只得到当前数字、服务端时间和本步期限。
-- 倒计时使用服务端时间锚点和单调时钟；本机系统时钟错误不直接导致倒计时漂移。网络延迟仍有影响，跨步时可能短暂显示“正在更新数字”，稳定后再核对。
-- 旧数字一过本步期限就隐藏，即使网络请求仍未返回。整个请求过期、拒绝或失败会隐藏数字和二维码。
-- 组件按请求检查成功结果、用途、双重认证策略和有效期。取消、卸载和切换请求后，旧响应不能触发成功回调。
-- 每个组件实例对同一请求只发一次成功事件；刷新或重新挂载不替代网站持久化幂等。
-- 包不接收网站业务授权内容，不提供 apiKey 配置，不执行支付/授权等业务操作。
-- 二维码在浏览器内生成，忽略后台 qrSvg，不使用 innerHTML；不上传给第三方图片服务。应用 CSP 需允许 `img-src 'self' data:`。
-
-## 样式与语言
-
-CSS 单独导入，所有类使用 `authlink-` 前缀。弹窗挂载到 `document.body`，可在 `:root` 或 `.authlink-dialog` 覆盖 `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted`。面板语言见下表，默认简体中文。
-
-React / Vue 均支持 `className`；Vue 还支持字符串、数组和对象形式的 `class`，与 `className` 合并。“重新发起”按钮使用父组件最新传入的 `onRefresh` 回调。
-
-
-| 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+。
+已使用的码不能用于另一个操作或会话；刚登录或首次绑定后需等待下一组数字。PASSCODE_INVALID / PASSCODE_USED / PASSCODE_LOCKED 是验证失败，不能当成成功。网络结果不明时，后台保留原幂等键和原码重试，业务不能重复执行。
 
-## 许可证
+destroy() 中止浏览器请求并清理计时器，不触发关闭回调；close() 还调用 onClose。关闭弹窗不会回滚服务端操作，取消与会话待办由 CMS 管理。等待和本地过期均不轮询。
 
-MIT。完整许可文本见 `LICENSE`，打包包含的第三方库归属说明见 `THIRD_PARTY_NOTICES.md`。
+旧 openAuthLink / Ticket / Consume 流程仍供此前协议使用；新 App 使用 openPasscode / AuthLinkPasscode 以及后台 Authenticate / authenticate。此次不提供旧绑定升级。

package/examples/react-client.tsx

@@ -0,0 +1,24 @@
+"use client";
+import { useState } from 'react';
+import type { OTPVerification, PasscodeClient } from '@auth-link/web';
+import { AuthLinkPasscode } from '@auth-link/web/react';
+// Import '@auth-link/web/styles.css' once in your application entry.
+
+// The parent reserves one pending CMS action first. Its close handler cancels
+// that backend slot before allowing another operation to start.
+export function AuthLinkPanel({ client, pending, onVerified, onClose }: {
+  client: PasscodeClient;
+  pending: { expiresAt: string; bindingQr?: string };
+  onVerified: (result: OTPVerification) => void;
+  onClose: () => void;
+}) {
+  const [message, setMessage] = useState('');
+  return <>
+    <AuthLinkPasscode client={client} expiresAt={pending.expiresAt}
+      bindingQr={pending.bindingQr} authLinkOrigin="https://api.getauthlink.com"
+      locale="en" variant="B" onVerified={onVerified} onClose={onClose}
+      onExpired={() => setMessage('Expired; start a new action')}
+      onError={error => setMessage(error.message)} />
+    <p role="status">{message}</p>
+  </>;
+}

package/examples/vue-client.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { markRaw, ref } from 'vue';
+import { createPasscodeClient } from '@auth-link/web';
+import type { OTPVerification } from '@auth-link/web';
+import { AuthLinkPasscode } from '@auth-link/web/vue';
+import '@auth-link/web/styles.css';
+
+// The CMS has already reserved this session's sole pending action. First
+// enrollment includes bindingQr; ordinary verification needs no QR.
+const props = defineProps<{
+  csrf: string;
+  pending: { expiresAt: string; bindingQr?: string };
+}>();
+const emit = defineEmits<{
+  verified: [result: OTPVerification];
+  close: [];
+}>();
+const message = ref('');
+const client = markRaw(createPasscodeClient({ baseUrl: '/api', csrfToken: () => props.csrf }));
+function verified(result: OTPVerification) { emit('verified', result); }
+function showError(error: Error) { message.value = error.message; }
+// The parent cancels its backend slot before preparing another action.
+</script>
+
+<template>
+  <AuthLinkPasscode :client="client" :expires-at="pending.expiresAt"
+    :binding-qr="pending.bindingQr" auth-link-origin="https://api.getauthlink.com"
+    locale="en" variant="B" @verified="verified" @close="emit('close')"
+    @expired="message = 'Expired; start a new action'" @error="showError" />
+  <p role="status">{{ message }}</p>
+</template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-link/web",
-  "version": "0.0.4",
+  "version": "1.1.0",
   "private": false,
   "description": "Three responsive AuthLink dialog layouts for phone binding and mobile confirmation. Framework-neutral API, React and Vue, 13 languages, Simplified Chinese by default.",
   "type": "module",
@@ -8,11 +8,14 @@
   "files": [
     "dist",
     "README.md",
-    "docs",
+    "docs/README.en.md",
+    "docs/README.zh-CN.md",
+    "docs/README.ja.md",
     "CHANGELOG.md",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE",
-    "examples/vue-cms.vue"
+    "examples/vue-client.vue",
+    "examples/react-client.tsx"
   ],
   "sideEffects": [
     "**/*.css"