@auth-link/web 0.0.5 → 2.0.0

package/README.md

@@ -4,847 +4,199 @@
 
 ## English
 
-Frontend dialogs for phone binding and in-app confirmation, with Vue 3, React 18/19 and plain JavaScript. Follow installation, session loading, client initialization, dialogs and event cleanup in this order.
+### Upgrading from 1.x
 
-### 1. Install and distinguish the two API origins
+All dialogs now use the minimal layout. Remove the variant option/prop, modal.setVariant() calls and DialogVariant type imports. Language switching and verification callbacks are unchanged.
 
-```sh
-npm install @auth-link/web@latest
-# Also install the framework your project uses: vue, or react / react-dom.
-```
-
-| Origin | Frontend option | Purpose |
-| --- | --- | --- |
-| Your application API, e.g. `https://cms-api.example.com` | baseUrl, allowedBackendOrigins | Session, request creation and results |
-| AuthLink production API `https://api.getauthlink.com` | authLinkOrigin | Validate the AuthLink origin in the ticket |
-
-baseUrl is your own application API, not the AuthLink API or marketing site. The SDK requires your existing website login/session and the request routes below; it does not provide login/session endpoints. Never put tenant keys in browser code.
-
-The root import provides clients and types; /vue and /react provide components and useAuthLink; explicitly import /styles.css. ESM and TypeScript, Node 22.13+ tooling; React 18.2+/19 or Vue 3.3+. Install only your framework.
+### Direct rotating-code verification
 
-### 2. Load the current session and initialize a client
+The app directly displays a six-digit rotating code. No per-action approval, authorization requestId, businessId or polling is required. First-time enrollment still scans a QR and verifies the phone; entering its current code on the website completes binding.
 
-```ts
-import { createAuthLinkClient } from '@auth-link/web';
-import '@auth-link/web/styles.css';
+The CMS backend must reserve one immutable pending action per session before opening the prompt. Another tab cannot replace it. Obtain the user from the server session and check CSRF and business permissions. Verify the passcode on the server and atomically commit verificationId with the saved operation before returning success. onVerified only updates the UI.
 
-// 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',
-  });
-}
+```sh
+npm install @auth-link/web@^2.0.0
 ```
 
-After website login, read your existing session endpoint. This example uses the CMS response authenticated/csrf. If your response field is csrfToken, read that field instead and supply it to the SDK csrfToken callback.
-
 ```ts
-// 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',
+import { openPasscode, createPasscodeClient } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+const client = createPasscodeClient({ baseUrl: '/api', csrfToken: () => csrfToken });
+const modal = openPasscode({
+  client, expiresAt: pending.expiresAt, locale: 'zh-CN',
+  // First-time enrollment only:
+  // bindingQr: pending.bindingQr, authLinkOrigin: 'https://api.getauthlink.com',
+  onVerified: result => updateUI(result.verificationId),
 });
-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.
+// modal.setLocale('en'); modal.destroy();
 ```
 
-GET /api/session is your application's example route; adapt it. Same-origin uses relative URLs and same-origin cookies. Cross-origin cookies need include and an application API that already allows your frontend origin; browser cookie policy still applies. Do not read HttpOnly cookies, generate your own CSRF token, or substitute a matching number.
+The default client posts only {passcode} to POST /api/auth with current CMS credentials and CSRF. To submit a form at the same time, supply your own client.verify callback and send {form,passcode} to your CMS. The CMS checks the form against its saved snapshot; never send tenant keys or passcode seeds to the browser.
 
-For existing Bearer/JWT login, auth below is your website's mutable login state. Read its refreshed accessToken on every request. This is not an AuthLink tenant key. CSRF may be omitted only for Bearer with credentials=omit; sending cookies still requires csrfToken.
+### Options and callbacks
 
-```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',
-});
-```
+Required: client.verify(passcode, signal) and expiresAt (the pending CMS action deadline). Optional: locale, bindingQr and authLinkOrigin for first enrollment only, onVerified, onError, onClose, onExpired. Success contains status, verificationId, authenticationPolicy and expiresAt; it has no requestId or businessId.
 
-### 3. Vue: create on click, display and clean up
+Cookie authentication requires CSRF. Bearer authentication uses accessToken with credentials=omit. For a cross-origin CMS explicitly set allowedBackendOrigins. Bare HTTPS origins are required outside loopback development.
 
-The package includes `examples/vue-client.vue`; copy it as AuthLinkPanel.vue. After login pass the current session.csrf, and backendOrigin for cross-origin calls. Unmount on logout/account/session changes and mount a new instance. Update the csrf prop after token refresh.
+### React and Vue
 
-```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';
+The React component takes the same options. Vue emits verified, error, close and expired. Keep client references stable. Thirteen languages remain supported; Simplified Chinese is the default. All dialogs use one responsive minimal layout.
 
-// 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; });
+```tsx
+import { AuthLinkPasscode } from '@auth-link/web/react';
+// Keep client stable (for example with useMemo).
+<AuthLinkPasscode client={client} expiresAt={pending.expiresAt}
+  locale="zh-CN" onVerified={updateUI} />
+```
+```vue
+<script setup>
+import { AuthLinkPasscode } from '@auth-link/web/vue';
 </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>
+  <AuthLinkPasscode :client="client" :expires-at="pending.expiresAt"
+    locale="zh-CN" @verified="updateUI" />
 </template>
 ```
 
-Keep ticket in shallowRef and client in markRaw. Retain a failed creation's key when retrying the same mode; clear it only after success. Create only in user handlers, never mounted/watch. Confirmation, rejection, expiry and close clear the ticket and unmount the dialog. Keep the dialog on network errors and use its retry control for the current request. Reload actual account state from your own API when needed.
-
-### 4. React
-
-Pass a stable client created as above and mode=bind or confirm. Unmount the instance on logout/account/session changes.
-
-```tsx
-"use client";
-import { useEffect, useRef, useState } from 'react';
-import { requestKey } from '@auth-link/web';
-import type { AuthLinkClient, Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-// Import '@auth-link/web/styles.css' once in your application entry.
-
-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 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 {
-      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 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>
-  </>;
-}
-```
-
-### 5. Plain JavaScript / direct dialogs
-
-```ts
-import { openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import '@auth-link/web/styles.css';
-
-// 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');
-```
-
-For binding use client.create('bind', ...) and openAuthLinkBind(...). Confirmation/rejection dismiss before their callbacks and do not emit onClose. Close stops frontend observation; call destroy when leaving the page/component. Success is delivered once per request per instance. Callbacks update UI; protected actions still call your application's API.
-
-### 6. API shapes the frontend needs
-
-| Application route | Frontend sends | Frontend reads |
-| --- | --- | --- |
-| POST /api/authlink/requests | purpose=bind or confirm; Idempotency-Key | Ticket |
-| POST /api/authlink/requests/{requestId}/result | empty object; current login credentials | Result; polled automatically |
-
-Both send the current CSRF header in cookie mode. Ticket contains requestId, purpose, qr, pairingCode and expiresAt; confirm also requires displayCode. Import Ticket/Result/Confirmation rather than inventing QR data or matching numbers. Only status=confirmed triggers success. new/pending/approved/consumed are waiting states; rejected/expired trigger their events.
-
-SDK create() sends purpose only. If your application expects additional fields, create via your own fetch, validate the returned ticket and pass it to the same component. post, session and backendOrigin below are your frontend state; retain the creation key across retries of the same payload.
-
-```ts
-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.
-```
-
-### 7. Props, events and presentation
-
-| Prop | Type | Meaning |
-| --- | --- | --- |
-| `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 callback / Vue event | Value | Behavior |
-| --- | --- | --- |
-| `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 is a centered card (default), B splits on desktop and stacks on narrow screens, and C is compact with a mobile bottom sheet. Changing locale/variant does not create a request. Browser support for native dialog.showModal() is required.
-
-Import CSS explicitly. Dialogs mount under document.body; set --authlink-foreground, --authlink-background, --authlink-accent and --authlink-muted on :root or .authlink-dialog. Vue class accepts strings/arrays/objects alongside className. SSR renders no dialog and creates no requests.
-
-Locales: `zh-CN` (default), `zh-TW`, `en`, `ja`, `bn`, `es`, `fil`, `hi`, `id`, `ms`, `pt`, `th`, `vi`. Missing/unsupported values fall back to Simplified Chinese. Import supportedLocales for the list.
-
-### 8. Transport options and troubleshooting
+### Errors and cleanup
 
-| Option | Purpose |
-| --- | --- |
-| `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 |
+A used code cannot authorize a second action, even in another session. After sign-in or first enrollment, wait for the next code. PASSCODE_INVALID/PASSCODE_USED/PASSCODE_LOCKED are validation errors, not success. Retain the same backend idempotency key and original code when a result is unknown; retries must not repeat the business action.
 
-Custom headers cannot replace Accept, Content-Type, Authorization, Idempotency-Key or the configured CSRF header. Read error.message: CSRF_REQUIRED means check the session token; ACCESS_TOKEN_REQUIRED means check login state; BACKEND_ORIGIN_NOT_ALLOWED means check exact allowed origins; NETWORK_ERROR means inspect browser Network, connectivity and CORS. Requests time out after 10 seconds; closing/unmounting cancels observation.
+destroy() aborts browser work and clears timers without a close callback. close() also calls onClose. Closing a dialog does not roll back server work: your CMS must manage cancellation and its pending slot. Waiting and local expiry never poll.
 
-Expired digits are hidden; do not generate or cache new ones in the frontend. QR generation is local; allow data: images if your page uses CSP. A callback, localStorage or a browser-supplied status is not authorization.
-
-### License
-
-MIT. See LICENSE and THIRD_PARTY_NOTICES.md.
+The older openAuthLink / Ticket / Consume workflow remains available for the earlier protocol; new apps use openPasscode / AuthLinkPasscode and the backend Authenticate/authenticate method. No old-binding migration is provided.
 
 ---
 
 ## 简体中文
 
-用于手机绑定与 App 确认的前端组件，支持 Vue 3、React 18/19 和原生 JavaScript。本文按前端接入顺序说明安装、登录状态读取、客户端初始化、弹窗和事件处理。
-
-### 1. 安装并区分两个 API 地址
+### 从 1.x 升级
 
-```sh
-npm install @auth-link/web@latest
-# 另行安装你的项目使用的 vue，或 react / react-dom。
-```
+所有弹窗统一使用极简布局。请删除 variant 参数或组件属性、modal.setVariant() 调用和 DialogVariant 类型导入。语言切换与验证回调保持不变。
 
-| 地址 | 前端配置 | 用途 |
-| --- | --- | --- |
-| 你的网站业务后台，如 `https://cms-api.example.com` | `baseUrl`、`allowedBackendOrigins` | 登录状态、创建请求和查询结果 |
-| AuthLink 生产 API：`https://api.getauthlink.com` | `authLinkOrigin` | 核对 ticket 中的 AuthLink 服务来源 |
+### 直接验证动态码
 
-`baseUrl` 不是 AuthLink API，也不是 AuthLink 官网。接入方的网站和业务 API 仍使用自己的域名。需要已有的网站登录状态和下文的请求接口；Web SDK 不提供登录或会话接口。租户密钥不能放到浏览器。
+App 直接显示六位动态码。日常验证不需要逐次批准、授权 requestId、businessId 或轮询。首次绑定仍需扫码验证设备，在网站输入 App 当前动态码后才完成绑定。
 
-导入入口：根入口提供客户端和类型；`/vue`、`/react` 提供组件及 useAuthLink；`/styles.css` 必须显式导入。ESM、TypeScript，工具环境 Node 22.13+；React 18.2+/19、Vue 3.3+，只安装所用框架。
-
-### 2. 读取当前登录状态并创建客户端
-
-```ts
-import { createAuthLinkClient } from '@auth-link/web';
-import '@auth-link/web/styles.css';
+打开弹窗前，CMS 后台必须为会话原子保留唯一且不可变的待办。其他标签页不能覆盖它。用户来自服务端会话，后台检查 CSRF、业务权限和原表单，验证动态码后将 verificationId 与原操作原子提交，再返回成功。onVerified 只更新界面。
 
-// 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',
-  });
-}
+```sh
+npm install @auth-link/web@^2.0.0
 ```
 
-先完成你的网站登录，再读取应用已有的会话接口。下面使用与 CMS 一致的 `{authenticated, csrf}` 响应；如果你的后台字段名为 csrfToken，读取它再交给 SDK 的 csrfToken 回调即可。
-
 ```ts
-// 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',
+import { openPasscode, createPasscodeClient } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+const client = createPasscodeClient({ baseUrl: '/api', csrfToken: () => csrfToken });
+const modal = openPasscode({
+  client, expiresAt: pending.expiresAt, locale: 'zh-CN',
+  // First-time enrollment only:
+  // bindingQr: pending.bindingQr, authLinkOrigin: 'https://api.getauthlink.com',
+  onVerified: result => updateUI(result.verificationId),
 });
-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.
+// modal.setLocale('en'); modal.destroy();
 ```
 
-`GET /api/session` 是网站已有接口的示例，请按实际路径替换。同源可以使用相对路径和 same-origin Cookie；跨域 Cookie 使用 include，并要求当前前端来源已被业务后台允许。Cookie 策略仍可能限制请求。浏览器无法读取 HttpOnly Cookie，只需要传回当前会话的 CSRF token；不能用手机核对码或浏览器随机值代替。
+默认客户端向 CMS 的 POST /api/auth 提交 {passcode}，携带当前会话与 CSRF。要随表单提交，可自行实现 client.verify，向 CMS 发送 {form,passcode}；后台核对原保存快照。租户密钥与动态码密钥不能进入浏览器。
 
-已有 Bearer / JWT 登录的项目可用下列配置，auth 是你的网站登录状态，刷新流程更新 auth.accessToken。此 token 不是 AuthLink 租户密钥。仅在 credentials=omit 的 Bearer 模式可以不传 CSRF；若同时发送 Cookie，仍需 csrfToken。
+### 选项与回调
 
-```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',
-});
-```
+必填：client.verify(passcode, signal)、expiresAt（CMS 待办截止时间）。可选：locale、仅首次绑定使用的 bindingQr 与 authLinkOrigin、onVerified、onError、onClose、onExpired。成功结果含 status、verificationId、authenticationPolicy、expiresAt，不含 requestId 或 businessId。
 
-### 3. Vue：点击创建、展示和清理
+Cookie 模式必须配置 CSRF。Bearer 模式配置 accessToken 且 credentials=omit。跨域 CMS 必须显式配置 allowedBackendOrigins；回环开发之外使用 HTTPS。
 
-完整文件随包提供为 `examples/vue-client.vue`，可复制为 AuthLinkPanel.vue。父组件在登录后传入当前 session.csrf；跨域时额外传 backendOrigin。退出或切换账号/session 时卸载旧组件，重新挂载新实例；CSRF 刷新可更新 csrf prop。
+### React 与 Vue
 
-```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';
+React 组件使用相同选项，Vue 发出 verified、error、close、expired 事件。client 引用需保持稳定。支持 13 种语言，默认简体中文；统一使用响应式极简布局。
 
-// 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; });
+```tsx
+import { AuthLinkPasscode } from '@auth-link/web/react';
+// Keep client stable (for example with useMemo).
+<AuthLinkPasscode client={client} expiresAt={pending.expiresAt}
+  locale="zh-CN" onVerified={updateUI} />
+```
+```vue
+<script setup>
+import { AuthLinkPasscode } from '@auth-link/web/vue';
 </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>
+  <AuthLinkPasscode :client="client" :expires-at="pending.expiresAt"
+    locale="zh-CN" @verified="updateUI" />
 </template>
 ```
 
-示例使用 shallowRef 保存 ticket、markRaw 保存 client。创建失败保留同一用途的原幂等键；成功后才清空。创建只发生在点击事件中，mounted/watch 不创建请求。确认、拒绝、过期或用户关闭时清空 ticket，卸载组件；网络错误保留弹窗，使用弹窗的重试按钮继续当前请求。需要真实账号状态时重新查询你的网站状态接口。
+### 失败与清理
 
-### 4. React
+已使用的码不能用于另一个操作或会话；刚登录或首次绑定后需等待下一组数字。PASSCODE_INVALID / PASSCODE_USED / PASSCODE_LOCKED 是验证失败，不能当成成功。网络结果不明时，后台保留原幂等键和原码重试，业务不能重复执行。
 
-使用上面的初始化方式创建稳定 client，再传给此组件；mode 为 bind 或 confirm。退出或切换账号/session 时卸载旧实例。
+destroy() 中止浏览器请求并清理计时器，不触发关闭回调；close() 还调用 onClose。关闭弹窗不会回滚服务端操作，取消与会话待办由 CMS 管理。等待和本地过期均不轮询。
 
-```tsx
-"use client";
-import { useEffect, useRef, useState } from 'react';
-import { requestKey } from '@auth-link/web';
-import type { AuthLinkClient, Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-// Import '@auth-link/web/styles.css' once in your application entry.
-
-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 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 {
-      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 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>
-  </>;
-}
-```
-
-### 5. 原生 JavaScript / 直接调用
-
-```ts
-import { openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import '@auth-link/web/styles.css';
-
-// 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');
-```
-
-绑定改用 `client.create('bind', ...)` 和 `openAuthLinkBind(...)`。确认或拒绝会先自动关闭再触发对应回调，不触发 onClose。关闭只停止前端观察；页面或组件退出时必须调用 destroy。每个实例对同一请求只通知一次成功；回调用于界面更新，受保护操作仍请求你的网站业务 API。
-
-### 6. 前端需要的接口约定
-
-| 网站接口 | 前端发送 | 前端读取 |
-| --- | --- | --- |
-| `POST /api/authlink/requests` | `{purpose:'bind'}` 或 confirm；`Idempotency-Key` | `Ticket` |
-| `POST /api/authlink/requests/{requestId}/result` | `{}`；当前登录凭据 | `Result`，由 SDK 自动轮询 |
-
-Cookie 模式两者均发送当前 CSRF 头。Ticket 包含 requestId、purpose、qr、pairingCode、expiresAt；confirm 还需要 displayCode。直接导入包内 Ticket / Result / Confirmation 类型，不自行生成 QR 内容或动态数字。只有 status=confirmed 触发成功事件；new/pending/approved/consumed 是等待状态，rejected/expired 分别触发对应事件。
-
-若你的网站创建接口需要文章 ID、版本等额外参数，SDK create() 只发送 purpose，因此使用自己的 fetch 创建，然后校验 ticket 并交给同一组件。下面的 post、session、backendOrigin 均来自你自己的前端状态；幂等键应保存到重试状态，失败时不要重新生成。
-
-```ts
-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.
-```
-
-### 7. 参数、事件与样式
-
-| 参数 | 类型 | 含义 |
-| --- | --- | --- |
-| `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() 浏览器支持是必需的。
-
-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 获取列表。
-
-### 8. 传输配置与排错
-
-| 配置 | 用途 |
-| --- | --- |
-| `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 秒，关闭/卸载会取消观察。
-
-数字过期会隐藏，不在前端生成或缓存新数字；二维码在浏览器本地生成。若页面启用 CSP，图片来源需要允许 data:。确认回调、localStorage 或浏览器自报状态都不作为业务授权依据。
-
-### 许可证
-
-MIT。完整文本见 LICENSE，第三方归属见 THIRD_PARTY_NOTICES.md。
+旧 openAuthLink / Ticket / Consume 流程仍供此前协议使用；新 App 使用 openPasscode / AuthLinkPasscode 以及后台 Authenticate / authenticate。此次不提供旧绑定升级。
 
 ---
 
 ## 日本語
 
-スマートフォン登録とアプリ内確認のフロントエンド用ダイアログです。Vue 3、React 18/19、通常の JavaScript に対応します。インストール、session 取得、client 初期化、表示、イベントと後処理の順に接続します。
-
-### 1. インストールと 2 つの API
-
-```sh
-npm install @auth-link/web@latest
-# 利用する vue、または react / react-dom もインストールします。
-```
-
-| origin | フロントエンド設定 | 用途 |
-| --- | --- | --- |
-| 自サイトの API（例 https://cms-api.example.com） | baseUrl、allowedBackendOrigins | session、要求作成、結果 |
-| AuthLink 本番 API https://api.getauthlink.com | authLinkOrigin | ticket 内のサービス origin の照合 |
+### 1.x からの更新
 
-baseUrl は自サイトの業務 API であり、AuthLink API や公式サイトではありません。既存のログイン/session と下記要求 API を利用します。SDK 自体はログイン/session API を提供しません。テナントキーはブラウザーに渡しません。
+すべてのダイアログはシンプルレイアウトに統一されました。variant オプション・プロパティ、modal.setVariant() の呼び出し、DialogVariant 型のインポートを削除してください。言語切り替えと認証コールバックは変更ありません。
 
-ルート import は client と型、/vue と /react はコンポーネントと useAuthLink、/styles.css は明示 import です。ESM、TypeScript、ツール環境 Node 22.13+、React 18.2+/19 または Vue 3.3+。利用するフレームワークのみ導入します。
+### 認証コードを直接検証
 
-### 2. 現在の session と client
+アプリに6桁の認証コードを直接表示します。通常の検証では、毎回の承認、認証用requestId、businessId、ポーリングは不要です。初回はQRで端末を確認し、サイトで現在のコードを検証して連携を完了します。
 
-```ts
-import { createAuthLinkClient } from '@auth-link/web';
-import '@auth-link/web/styles.css';
+画面を開く前にCMSサーバーでセッションの唯一の保留中操作を原子的に確保します。別タブから上書きさせません。ユーザーはサーバーのセッションから取得し、CSRF、業務権限、元のフォームを確認します。コードを検証し、verificationIdと元の操作を原子的に確定してから成功を返します。onVerifiedは表示更新専用です。
 
-// 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',
-  });
-}
+```sh
+npm install @auth-link/web@^2.0.0
 ```
 
-サイトのログイン後に既存 session API を読みます。例は CMS の authenticated/csrf です。フィールド名が csrfToken ならその値を SDK の csrfToken コールバックへ渡します。
-
 ```ts
-// 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',
+import { openPasscode, createPasscodeClient } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+const client = createPasscodeClient({ baseUrl: '/api', csrfToken: () => csrfToken });
+const modal = openPasscode({
+  client, expiresAt: pending.expiresAt, locale: 'zh-CN',
+  // First-time enrollment only:
+  // bindingQr: pending.bindingQr, authLinkOrigin: 'https://api.getauthlink.com',
+  onVerified: result => updateUI(result.verificationId),
 });
-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.
+// modal.setLocale('en'); modal.destroy();
 ```
 
-GET /api/session はサイト側の既存ルートの例です。同 origin は相対 URL と same-origin Cookie、別 origin の Cookie は include を使い、業務 API が現在のフロントエンド origin を許可している必要があります。Cookie 制限も適用されます。HttpOnly Cookie を読んだり、CSRF をブラウザーで生成したり、照合数字で代用したりしません。
+標準クライアントは現在の認証情報とCSRFを付け、CMSのPOST /api/authへ{passcode}を送信します。フォームも送る場合はclient.verifyで{form,passcode}をCMSへ送信し、サーバーで保存済み内容と照合します。テナントキーやコード生成用秘密はブラウザーへ渡しません。
 
-Bearer/JWT を使う場合、auth は既存ログイン状態です。更新された accessToken を毎回読みます。これはテナントキーではありません。credentials=omit の Bearer のみ CSRF を省略でき、Cookie 併用なら csrfToken が必要です。
+### オプションとコールバック
 
-```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',
-});
-```
+必須はclient.verify(passcode, signal)とexpiresAt（CMS操作の期限）です。任意でlocale、初回用bindingQrとauthLinkOrigin、onVerified、onError、onClose、onExpiredを指定します。成功結果はstatus、verificationId、authenticationPolicy、expiresAtを含み、requestIdやbusinessIdは含みません。
 
-### 3. Vue：クリックで作成、表示、後処理
+Cookie認証ではCSRFが必須です。Bearer認証はaccessTokenとcredentials=omitを使います。別オリジンのCMSはallowedBackendOriginsを明示し、ループバック開発以外ではHTTPSを使います。
 
-`examples/vue-client.vue` を AuthLinkPanel.vue としてコピーできます。ログイン後に現在の session.csrf を渡し、別 origin なら backendOrigin も渡します。ログアウト・アカウント/session 変更では旧コンポーネントをアンマウントして再作成します。token 更新時は csrf prop を更新します。
+### ReactとVue
 
-```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';
+Reactは同じオプションを使い、Vueはverified、error、close、expiredイベントを発行します。clientの参照を安定させてください。13言語に対応し、既定は簡体字中国語です。すべてのダイアログはレスポンシブなシンプルレイアウトを使用します。
 
-// 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; });
+```tsx
+import { AuthLinkPasscode } from '@auth-link/web/react';
+// Keep client stable (for example with useMemo).
+<AuthLinkPasscode client={client} expiresAt={pending.expiresAt}
+  locale="zh-CN" onVerified={updateUI} />
+```
+```vue
+<script setup>
+import { AuthLinkPasscode } from '@auth-link/web/vue';
 </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>
+  <AuthLinkPasscode :client="client" :expires-at="pending.expiresAt"
+    locale="zh-CN" @verified="updateUI" />
 </template>
 ```
 
-ticket は shallowRef、client は markRaw で保持します。同じ用途の作成失敗ではキーを保持し、成功後に消去します。mounted/watch で要求を作りません。確認・拒否・期限切れ・閉じる操作で ticket を消去します。通信エラーでは表示を維持して同じ要求を再試行します。必要なアカウント状態は自サイトの API から再取得します。
-
-### 4. React
-
-上記で初期化した安定した client と mode=bind/confirm を渡します。ログアウトやアカウント/session 変更ではアンマウントします。
-
-```tsx
-"use client";
-import { useEffect, useRef, useState } from 'react';
-import { requestKey } from '@auth-link/web';
-import type { AuthLinkClient, Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-// Import '@auth-link/web/styles.css' once in your application entry.
-
-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 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 {
-      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 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>
-  </>;
-}
-```
-
-### 5. 通常の JavaScript / 直接表示
-
-```ts
-import { openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import '@auth-link/web/styles.css';
-
-// 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');
-```
-
-登録時は client.create('bind', ...) と openAuthLinkBind(...) を使います。確認・拒否は自動で閉じてから通知し、onClose は発火しません。閉じる操作は監視を停止します。画面を離れる際は destroy を呼びます。同じ要求の成功はインスタンス内で一度だけ通知します。イベントは表示更新用で、保護操作は自サイトの業務 API を呼びます。
-
-### 6. フロントエンドが使う API の形式
-
-| 自サイトのルート | 送信 | 受信 |
-| --- | --- | --- |
-| POST /api/authlink/requests | purpose=bind/confirm、Idempotency-Key | Ticket |
-| POST /api/authlink/requests/{requestId}/result | 空オブジェクト、現在のログイン情報 | Result（自動監視） |
-
-Cookie モードでは両方に現在の CSRF ヘッダーを送ります。Ticket は requestId、purpose、qr、pairingCode、expiresAt、confirm 時は displayCode も必要です。Ticket/Result/Confirmation 型を import し、QR や数字を自作しません。confirmed のみ成功イベントを発火します。new/pending/approved/consumed は待機、rejected/expired は対応イベントです。
-
-create() は purpose のみ送ります。業務固有項目が必要なら独自 fetch で作成し、validateTicket で検証して同じコンポーネントへ渡します。post/session/backendOrigin は既存のフロントエンド状態で、同じ入力の再試行では同じキーを保持します。
-
-```ts
-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.
-```
-
-### 7. 設定・イベント・表示
-
-| prop | 型 | 用途 |
-| --- | --- | --- |
-| `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() 対応ブラウザーが必要です。
-
-CSS を明示 import します。ダイアログは 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 で一覧を取得できます。
-
-### 8. 通信設定とエラー確認
-
-| 設定 | 用途 |
-| --- | --- |
-| `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 は session token、ACCESS_TOKEN_REQUIRED はログイン状態、BACKEND_ORIGIN_NOT_ALLOWED は正確な許可 origin、NETWORK_ERROR は開発者ツールの Network・通信・CORS を確認します。タイムアウトは 10 秒、閉じる/アンマウントで監視を中止します。
+### 失敗と終了処理
 
-期限切れの数字は隠れます。数字をフロントエンドで生成・キャッシュしません。QR はローカル生成で、CSP 使用時は data: 画像を許可します。イベントや localStorage、ブラウザーからの状態値は業務上の許可証ではありません。
+使用済みコードは別操作や別セッションに使えません。ログインや初回連携直後は次のコードを待ちます。PASSCODE_INVALID、PASSCODE_USED、PASSCODE_LOCKEDを成功として扱わないでください。通信結果不明時は元の冪等キーとコードを保持して再試行し、業務を二重実行しません。
 
-### ライセンス
+destroy()はブラウザー要求を中止してタイマーを解除し、終了コールバックを呼びません。close()はonCloseも呼びます。画面を閉じてもサーバー処理は元に戻らず、キャンセルと保留中操作はCMS側で管理します。待機やローカル期限判定はポーリングしません。
 
-MIT。LICENSE と THIRD_PARTY_NOTICES.md を参照してください。
+旧openAuthLink / Ticket / Consumeは以前のプロトコル向けに残ります。新アプリはopenPasscode / AuthLinkPasscodeとサーバーのAuthenticate / authenticateを使います。旧連携の移行機能は提供しません。