@auth-link/web 0.0.1 → 0.0.3

package/docs/README.zh-CN.md

@@ -4,28 +4,11 @@
 
 **AuthLink 官方前端组件包**，帮助网站接入手机绑定与 App 确认流程，支持 React 18/19、Vue 3.3+、TypeScript 和 ESM。
 
+## Go + Vue 完整接入
 
-## 直接调用弹窗（React、Vue 或原生 JavaScript）
+按实际 CMS 流程接入，推荐先读 [Go + Vue：从登录、绑定到确认发布](./go-vue.zh-CN.md)，完整组件见 [Vue CMS 示例](../examples/vue-cms.vue)。
 
-```ts
-import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import '@auth-link/web/styles.css';
-
-// 在按钮事件中创建请求，再打开弹窗；client 为前文的同源客户端。
-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()，不会重建鉴权请求。
+顺序是：网站登录 → 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。
 
 
 ## 功能
@@ -41,7 +24,7 @@ React / Vue 的 AuthLinkBind、AuthLinkConfirm 挂载后也直接打开弹窗，
 
 ## 接入步骤
 
-1. 在应用后台完成站点租户配置，并实现本文的创建请求、查询结果两个同源接口。
+1. 在应用后台完成站点租户配置，并实现本文的创建请求、查询结果两个业务后台接口（同源或显式配置的跨域后台）。
 2. 安装包、导入样式，创建指向应用后台的客户端。
 3. 用户点击绑定或验证时创建请求，将返回的 ticket 交给 React/Vue 组件。
 4. 用户在 App 确认后，应用后台验证并消费结果，组件收到可信确认事件。
@@ -64,46 +47,228 @@ React / Vue 的 AuthLinkBind、AuthLinkConfirm 挂载后也直接打开弹窗，
 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
-import { createAuthLinkClient, requestKey } from '@auth-link/web';
+// authlink-client.ts
+import { createAuthLinkClient } from '@auth-link/web';
 import '@auth-link/web/styles.css';
 
-// 不要传 AuthLink 租户 API key。此客户端只调用当前应用网站后台。
+// 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(),
-  authLinkOrigin: 'https://你的-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',
+  });
+  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，无需重建弹窗。
+
+```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 '@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('已关闭'),
 });
-// 在用户点击“绑定”或“验证”时调用；不要在 React effect / Vue watch 中创建请求。
-const key = requestKey();
-const ticket = await client.create('bind', { idempotencyKey: key });
-// 创建响应丢失时复用 key 重试，不能每次重试都生成新 key。
+// 绑定使用 openAuthLinkBind({ ticket: bindingTicket, client })。
+// modal.close(); modal.setLocale('ja');
 ```
 
-`create` 只传用途；网站账号由应用后台的登录 session 决定。也可以自己请求后台，把 ticket 和自定义 `AuthLinkClient` 交给组件，适配 Axios、GraphQL 或其他认证方式。
+React / Vue 的 AuthLinkBind、AuthLinkConfirm 挂载后也直接打开弹窗，不再内嵌在页面。React 用 onClose、Vue 用 @close 清空 ticket 并卸载组件。服务端渲染不创建弹窗或请求。支持手机窄屏、内容滚动、关闭按钮及 Escape；要求浏览器支持原生 dialog.showModal()。弹窗挂到 document.body，主题变量请配置在 :root 或 .authlink-dialog。
+
+关闭只停止前端查询，不拒绝或撤销服务端请求；请求仍按原有效期结束。确认成功或拒绝后弹窗自动关闭，分别回调 onConfirmed 或 onRejected，不触发用户关闭回调。直接调用时，页面卸载须执行 modal.destroy() 清理，它不触发用户关闭回调。切换语言用 modal.setLocale()，不会重建鉴权请求。
+
 
 ## React
 
+下面的 `showBound` 也是接入方函数，负责更新页面提示和清空 `ticket`，从而卸载弹窗；它不向后台提交“绑定成功”，也不保存绑定。绑定及确认记录必须在后台查询结果接口验证、消费并保存后，才返回 `confirmed`。
+
+这个示例包含按钮、请求创建、结果提示和弹窗清理，不再依赖未定义的 `showBound`、`showRejected` 等函数。使用 `<AuthLinkPanel mode="bind" />` 绑定，使用 `<AuthLinkPanel mode="confirm" />` 请求手机确认。
+
 ```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 type { Ticket } from '@auth-link/web';
-import { client } from './authlink-client'; // 上文创建的客户端
-
-export function BindPanel({ ticket }: { ticket: Ticket }) {
-  return <AuthLinkBind ticket={ticket} client={client} locale="zh-CN"
-    onConfirmed={result => showBound(result.requestId)}
-    onRejected={() => showRejected()} onExpired={() => showExpired()}
-    onError={error => showNetworkError(error.message)} />;
-}
-
-export function ConfirmPanel({ ticket }: { ticket: Ticket }) {
-  return <AuthLinkConfirm ticket={ticket} client={client} locale="zh-CN"
-    onConfirmed={result => showConfirmed(result.requestId)} />;
+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>
+  </>;
 }
 ```
 
+`requestId` 用于展示或追踪本次请求，不是授权凭据。`showBound` 也可以按网站需求显示 toast、重新查询已有的账号状态接口或导航到绑定管理页。刷新页面后，应重新从后台读取真实绑定状态，不能只依赖 React state 或 localStorage。其他业务接口仍需在后台检查权限。
+
+创建失败时示例保留同一个幂等键；再次点击会重试同一次创建。创建成功后清空幂等键，新的用户操作才创建新请求。关闭、成功、拒绝和过期都会清空 ticket；网络错误保留弹窗，供其重试当前请求。
+
 确认组件默认只显示动态数字；`showQr` 可额外显示扫码入口。绑定组件始终显示二维码。`onRefresh` 可提供重新创建请求的函数；仅过期后显示该按钮。组件自身的“重试”只恢复当前请求，不创建第二个请求。
 
 未指定 `locale` 时使用简体中文；不支持的语言代码也回退到简体中文。组件根元素设置对应的 `lang`，语言切换不会重新创建鉴权请求。
@@ -114,25 +279,47 @@ React 入口保留 `"use client"`，可用于 Next.js 客户端组件。导入
 
 ```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 type { Ticket, Confirmation } from '@auth-link/web';
-import '@auth-link/web/styles.css';
-import { client } from './authlink-client'; // 上文创建的客户端
-defineProps<{ ticket: Ticket; mode: 'bind' | 'confirm' }>();
-function confirmed(result: Confirmation) { showConfirmed(result.requestId); }
+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>
-  <AuthLinkBind v-if="mode === 'bind'" :ticket="ticket" :client="client"
-    locale="zh-CN" @confirmed="confirmed" @expired="showExpired" />
+  <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"
-    locale="zh-CN" @confirmed="confirmed" @rejected="showRejected" />
+    @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'`，供自定义界面使用。
 
-Vue 可通过 `:on-refresh="createNewRequest"` 提供重新创建操作。`useAuthLink(() => options)` composable 与 React 的 `useAuthLink(options)` hook 可用于自定义界面，返回 `snapshot` 和 `retry`；Vue 的 snapshot 是浅 ref。
+此示例在过期后清空 ticket，用户可再次点击按钮发起请求。如果需要在过期弹窗内提供重新发起按钮，可自行传入 `onRefresh`，在回调中创建新请求并更新 ticket。`useAuthLink(() => options)` composable 与 React 的 `useAuthLink(options)` hook 可用于自定义界面，返回 `snapshot` 和 `retry`；Vue 的 snapshot 是浅 ref。
 
 ## 选择弹窗样式
 
@@ -194,19 +381,19 @@ openAuthLinkConfirm({ ticket, client, variant: 'B' });
 | `@auth-link/web/vue` | Vue 组件和 `useAuthLink` |
 | `@auth-link/web/styles.css` | 组件样式，需显式导入 |
 
-##应用后台接口约定
+## 应用后台接口约定
 
 默认前缀 `/api/authlink`；下面两个接口由接入方实现，**不是直接把浏览器请求转发到租户密钥 API**。
 
 ### `POST /requests`
 
-浏览器携带自己的应用session、`X-CSRF-Token`、稳定的 `Idempotency-Key`，body：
+浏览器按所选模式携带网站登录凭据：Cookie 模式发送 session cookie 和配置的 CSRF 头，Bearer 模式发送 `Authorization`。创建还发送稳定的 `Idempotency-Key`，body：
 
 ```json
 {"purpose":"bind"}
 ```
 
-后台从 session 取得用户 ID，创建并持久保存 state、创建/消费幂等键、用户/session 关联，然后调用 AuthLink 服务端创建请求。返回其公开 ticket：
+后台从经过验证的 session 或 Bearer token 取得用户 ID，创建并持久保存 state、创建/消费幂等键、用户/session 关联，然后调用 AuthLink 服务端创建请求。返回其公开 ticket：
 
 ```ts
 type Ticket = {
@@ -225,7 +412,7 @@ type Ticket = {
 
 ### `POST /requests/{requestId}/result`
 
-同样验证 session、CSRF 和请求归属。后台调用 AuthLink 状态接口，将 `displayCode` 原样返回，不能缓存跨过 `validUntil`。新代码由后台实时获取，不是前端自行生成。
+同样验证登录身份（Cookie 模式还需 CSRF）和请求归属。后台调用 AuthLink 状态接口，将 `displayCode` 原样返回，不能缓存跨过 `validUntil`。新代码由后台实时获取，不是前端自行生成。
 
 尚未完成时返回 `{requestId,status,displayCode?}`；状态可为 new / pending / approved / consumed / rejected / expired。`approved` 不能触发成功事件。
 
@@ -256,7 +443,9 @@ type Ticket = {
 
 ## 样式与语言
 
-CSS 单独导入，所有类使用 `authlink-` 前缀。可在宿主容器覆盖 `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted`。面板语言见下表，默认简体中文。
+CSS 单独导入，所有类使用 `authlink-` 前缀。弹窗挂载到 `document.body`，可在 `:root` 或 `.authlink-dialog` 覆盖 `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted`。面板语言见下表，默认简体中文。
+
+React / Vue 均支持 `className`；Vue 还支持字符串、数组和对象形式的 `class`，与 `className` 合并。“重新发起”按钮使用父组件最新传入的 `onRefresh` 回调。
 
 
 | Code | Language |
@@ -280,3 +469,7 @@ CSS 单独导入，所有类使用 `authlink-` 前缀。可在宿主容器覆盖
 ## 兼容性
 
 React 18.2+ / 19、Vue 3.3+、TypeScript、ESM。React 和 Vue 是可选 peer，只安装所用框架。构建工具环境需 Node 22.13+。
+
+## 许可证
+
+MIT。完整许可文本见 `LICENSE`，打包包含的第三方库归属说明见 `THIRD_PARTY_NOTICES.md`。