@auth-link/web 0.0.3 → 0.0.5

package/README.md

@@ -4,2049 +4,847 @@
 
 ## English
 
-Responsive dialogs for **AuthLink phone binding and mobile confirmation**, with direct function calls and React / Vue components. Display binding QR codes, synchronized six-digit matching codes, countdowns and confirmation results in any web application. No particular site platform is required.
+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.
 
-### Go backend + Vue walkthrough
-
-Start with [Go + Vue: login, binding and confirmed publication](#go-vue-cms-en) and the `examples/vue-cms.vue`.
-
-The flow is site login → Go `/api/session` returns authenticated/csrf → configure the cross-origin client with `csrfToken: () => session.csrf` → create bind/confirm → Go consumes, validates and commits the receipt → Vue dismisses the dialog → a separate business API checks the saved receipt and publishes. `baseUrl` targets Go; `authLinkOrigin` identifies AuthLink. Tenant keys stay in Go. Use your own fetch plus `validateTicket` for post/version fields; SDK create() sends purpose only.
-
-### Features
-
-- Phone-binding QR codes generated locally in the browser.
-- Matching numbers that update every 30 seconds, synchronized with the AuthLink app.
-- Confirmation, rejection, expiry and error callbacks.
-- React components and hook, Vue components and composable, and framework-independent tools.
-- 13 interface languages, **Simplified Chinese by default**, with per-component language selection.
-- TypeScript declarations, separate CSS and optional React/Vue peer dependencies.
-
-This is a browser integration library. It works with your application backend, the AuthLink service and the mobile app. The service verifies the original phone’s hardware-backed proof after the user approves in the app. Screen-lock checks and system passkeys are not required. Installing the library alone does not create an authentication service.
-
-### Install
+### 1. Install and distinguish the two API origins
 
 ```sh
-npm install @auth-link/web
+npm install @auth-link/web@latest
+# Also install the framework your project uses: vue, or react / react-dom.
 ```
 
-Compatibility: React 18.2+ / 19, Vue 3.3+, TypeScript, ESM. Install only the framework you use. The package declares Node 22.13+ for tooling.
-
-### Browser integration
-
-1. Configure your backend's AuthLink tenant credentials.
-2. Implement the two application backend endpoints below (same-origin or explicitly allowed cross-origin), authenticated to the current website user.
-3. Create a request on a user action and pass its ticket to a component.
-4. Your backend verifies and consumes the result before returning a confirmed response.
-
-The browser can call this library directly. Tenant credentials and result consumption belong on your backend; never embed a tenant API key in frontend code. The supplied client defaults to same-origin and also supports explicitly allowed cross-origin backends. You can supply a custom `AuthLinkClient` to integrate another transport while preserving server-side credential handling and verification.
-
-### Create a client (default same-origin session mode)
-
-`readCsrfTokenFromYourCms` is application code, not an SDK export. It reads a CSRF token issued by your own backend for the current logged-in session; it must not generate one in the browser or return an AuthLink API key. The name does not require a CMS.
-
-Reuse your framework's existing CSRF mechanism. Otherwise, generate a cryptographically random token on the server (for example, Node's `randomBytes(32).toString('base64url')`), persist it in the session, and render it into the authenticated page with HTML attribute escaping. `{{ csrfToken }}` below is a server-template variable, not a literal value. Do not publicly cache pages containing session tokens.
+| 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 |
 
-```html
-<meta name="csrf-token" content="{{ csrfToken }}">
-```
+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 SDK reads the token for every request, sends it as `X-CSRF-Token`, and includes same-origin session cookies. Your backend must validate that header against the token in the same session on both creation and result routes, reject missing/mismatched tokens, and check the expected request origin. Sending a header alone does not provide CSRF protection. Obtain a fresh token after login/session changes; a SPA may supply a token returned by its own same-origin session bootstrap endpoint. If your framework expects another header name, set `csrfHeaderName` or provide a custom `AuthLinkClient`.
+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.
 
-Create `authlink-client.ts`:
+### 2. Load the current session and initialize a client
 
 ```ts
-// authlink-client.ts
 import { createAuthLinkClient } from '@auth-link/web';
 import '@auth-link/web/styles.css';
 
-// The application server renders this meta element using the current session's
-// CSRF token. This function only reads that token; it does not generate one.
-export function readCsrfTokenFromYourCms(): string {
-  const token = document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content;
-  if (!token) throw new Error('Missing CSRF token; load the authenticated application page first.');
-  return token;
-}
-
-export const client = createAuthLinkClient({
-  baseUrl: '/api/authlink',
-  csrfToken: readCsrfTokenFromYourCms,
-  // Replace this example with the configured AuthLink service origin.
-  authLinkOrigin: 'https://auth.example.com',
-});
-```
-
-Replace `https://auth.example.com` with the configured AuthLink origin. Create requests only in user event handlers, as in the React example below.
-
-### Separate frontend and backend origins (since 0.0.2)
-
-The default is still same-origin `/api/authlink`. For direct cross-origin requests, configure an absolute `baseUrl` and exact `allowedBackendOrigins`, for example frontend `https://www.example.com` and application API `https://api.example.com`. Subdomains and different ports are different origins. Entries must be origins only, without paths, wildcards or embedded credentials, and must come from trusted configuration. HTTPS is required except for explicitly allowed HTTP loopback development origins (localhost, 127.0.0.1, [::1]).
-
-The SDK validates the destination before evaluating credentials and refuses redirects. `authLinkOrigin` separately validates the AuthLink service origin encoded in the QR; it is not the application API allowlist.
-
-#### Cross-origin session cookies
-
-This complete initialization function uses an example `GET /api/session` endpoint that **your application implements**, returning `{ "csrfToken": "current-session-token" }` for the authenticated session with `Cache-Control: no-store` and CORS enabled. Replace that path with your existing session endpoint.
-
-`csrfToken` is the JSON property chosen for this generic example. The Go CMS walkthrough uses `{ authenticated: true, csrf: '…' }` instead; map session.csrf to the SDK csrfToken callback without renaming your backend response.
-
-```ts
-import { createAuthLinkClient } from '@auth-link/web';
-
-/** /api/session is an example endpoint implemented by your application backend. */
-export async function createSessionBackendClient(backendOrigin: string) {
-  const response = await fetch(`${backendOrigin}/api/session`, {
-    credentials: 'include', cache: 'no-store', redirect: 'error',
+// getCsrf reads your website's CURRENT session token on every request.
+export function createWebsiteClient(getCsrf: () => string, backendOrigin?: string) {
+  return createAuthLinkClient({
+    baseUrl: backendOrigin ? `${backendOrigin}/api/authlink` : '/api/authlink',
+    allowedBackendOrigins: backendOrigin ? [backendOrigin] : [],
+    credentials: backendOrigin ? 'include' : 'same-origin',
+    csrfToken: getCsrf,
+    authLinkOrigin: 'https://api.getauthlink.com',
   });
-  if (!response.ok) throw new Error('Session initialization failed');
-  const session: unknown = await response.json();
-  if (!session || typeof session !== 'object' || !('csrfToken' in session) ||
-      typeof session.csrfToken !== 'string' || !session.csrfToken) {
-    throw new Error('The session endpoint must return { csrfToken: string }');
-  }
-  let currentCsrfToken = session.csrfToken;
-  return {
-    client: createAuthLinkClient({
-      baseUrl: `${backendOrigin}/api/authlink`,
-      allowedBackendOrigins: [backendOrigin],
-      credentials: 'include',
-      csrfToken: () => currentCsrfToken,
-    }),
-    // Call after your application's session/token refresh; recreate on account changes.
-    updateCsrfToken(value: string) { currentCsrfToken = value; },
-  };
 }
 ```
 
-After login, call `await createSessionBackendClient('https://api.example.com')` and pass the returned `client` to the existing components. Call the returned `updateCsrfToken(newToken)` when your session refreshes its CSRF token. Close old dialogs and recreate session state on logout/account changes. Cross-origin cookies require `credentials: 'include'`, but their SameSite, Secure, domain/path and browser third-party cookie restrictions still apply. Cross-origin does not necessarily mean cross-site. Truly cross-site cookies typically require `SameSite=None; Secure`, and browser policy may still block them.
-
-#### Cross-origin Bearer / JWT
-
-Pass your website's existing mutable login state. Its login/refresh flow updates `auth.accessToken`; the callback reads it on every creation and poll.
+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
-import { createAuthLinkClient } from '@auth-link/web';
-
-/** auth is your website's existing login state, updated by its login/refresh flow. */
-export function createBearerBackendClient(backendOrigin: string, auth: { accessToken: string }) {
-  return createAuthLinkClient({
-    baseUrl: `${backendOrigin}/api/authlink`,
-    allowedBackendOrigins: [backendOrigin],
-    credentials: 'omit',
-    accessToken: () => auth.accessToken,
-  });
+// Run in your website's existing authenticated browser flow.
+const backendOrigin = 'https://cms-api.example.com'; // YOUR application backend
+const response = await fetch(`${backendOrigin}/api/session`, {
+  credentials: 'include', cache: 'no-store', redirect: 'error',
+});
+if (!response.ok) throw new Error('Session unavailable');
+let session = await response.json();
+if (session.authenticated !== true || typeof session.csrf !== 'string' || !session.csrf) {
+  throw new Error('Log in to your website first');
 }
+const client = createWebsiteClient(() => session.csrf, backendOrigin);
+// Same origin: createWebsiteClient(() => session.csrf)
+// After token refresh, replace session or update session.csrf.
+// On logout/account/session change, close/unmount old dialogs and recreate client state.
 ```
 
-This must be the website user's login token, never an AuthLink tenant API key. The SDK adds `Authorization: Bearer ...`. With `accessToken`, credentials default to `omit` and CSRF can be omitted for a backend that exclusively authenticates Bearer tokens without cookie fallback. Explicit `include` or `same-origin` credentials require a CSRF provider even with Bearer authentication.
+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.
 
-#### Backend CORS
+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.
 
-Handle `OPTIONS` preflight and return appropriate CORS headers on preflight, actual responses and errors, including the session bootstrap endpoint. For a frontend at `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
+```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',
+});
 ```
 
-Credentialed CORS cannot use `Access-Control-Allow-Origin: *`. Match a server-side origin allowlist before returning the current allowed origin; do not reflect arbitrary origins. Preflight generally has no login credentials: validate its origin/method/headers, then authenticate the actual request and validate CSRF for cookies and request ownership. Add custom CSRF/extra headers to `Access-Control-Allow-Headers`. The SDK cannot enable backend CORS or read results using `no-cors`. See [MDN CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS).
-
-#### Transport options
-
-| Option | Behavior |
-| --- | --- |
-| `baseUrl` | Application API prefix, defaults to `/api/authlink`; absolute for cross-origin |
-| `allowedBackendOrigins` | Additional exact application backend origins; same-origin remains allowed |
-| `credentials` | Defaults to `same-origin`, or `omit` with `accessToken`; use `include` for cross-origin cookies |
-| `csrfToken` | Per-request sync/async token callback, required for cookie/session mode |
-| `csrfHeaderName` | Defaults to `X-CSRF-Token`, configurable for framework integration |
-| `accessToken` | Per-request sync/async website login token callback, without the `Bearer ` prefix |
-| `headers` | Extra `HeadersInit`, or sync/async callback returning it |
-| `authLinkOrigin` | Trusted QR service origin, independent of the application API origin |
-| `fetch` | Optional implementation; destination validation still applies |
-
-Custom headers cannot override SDK-managed `Accept`, `Content-Type`, `Authorization`, `Idempotency-Key` or the configured CSRF header (`RESERVED_HEADER`). Use `accessToken` for Bearer auth and `csrfHeaderName` to adapt framework CSRF validation. Import `ClientOptions` from the root entry for configuration types.
-
-Unlisted origins produce `BACKEND_ORIGIN_NOT_ALLOWED` (replacing `CMS_ORIGIN_REQUIRED`); invalid allowlist entries or URLs produce `INVALID_BACKEND_ORIGIN` / `INVALID_BASE_URL`. Missing login/CSRF tokens produce `ACCESS_TOKEN_REQUIRED` / `CSRF_REQUIRED`. Cancellation and the 10-second timeout also cover async credential providers. Browser CORS failures normally surface as `NETWORK_ERROR`; inspect browser developer tools for details.
+### 3. Vue: create on click, display and clean up
 
-### Open a dialog directly (React, Vue or plain JavaScript)
+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.
 
-```ts
-import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import { client } from './authlink-client';
+```vue
+<script setup lang="ts">
+import { markRaw, onUnmounted, ref, shallowRef } from 'vue';
+import { createAuthLinkClient, requestKey } from '@auth-link/web';
+import type { Confirmation, Mode, Ticket } from '@auth-link/web';
+import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
 import '@auth-link/web/styles.css';
 
-// Call in your button handler, after your backend creates the request.
-const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
-const modal = openAuthLinkConfirm({
-  ticket, client, locale: 'en',
-  onConfirmed: result => console.log('Confirmed:', result.requestId),
-  onRejected: result => console.log(result.code), // REJECTED; dialog already closed
-  onClose: () => console.log('Dialog closed'),
-});
-// Bind instead: openAuthLinkBind({ ticket: bindingTicket, client }).
-// modal.close(); modal.setLocale('ja');
+// csrf comes from your website's current authenticated session.
+const props = defineProps<{ csrf: string; backendOrigin?: string }>();
+const ticket = shallowRef<Ticket | null>(null);
+const busy = ref(false), message = ref('');
+const lifetime = new AbortController();
+let creationKey: string | null = null;
+let creationMode: Mode | null = null;
+const client = markRaw(createAuthLinkClient({
+  baseUrl: props.backendOrigin ? `${props.backendOrigin}/api/authlink` : '/api/authlink',
+  allowedBackendOrigins: props.backendOrigin ? [props.backendOrigin] : [],
+  credentials: props.backendOrigin ? 'include' : 'same-origin',
+  csrfToken: () => props.csrf,
+  authLinkOrigin: 'https://api.getauthlink.com',
+}));
+function finish(text: string) { ticket.value = null; message.value = text; }
+function confirmed(result: Confirmation) {
+  finish(`${result.purpose}: ${result.requestId}`);
+  // Reload your website's account/status API if the page needs fresh state.
+}
+function showError(error: Error) { message.value = error.message; }
+async function start(mode: Mode) {
+  if (busy.value || ticket.value) return;
+  busy.value = true; message.value = '';
+  try {
+    if (creationMode !== mode) { creationKey = null; creationMode = mode; }
+    creationKey ??= requestKey();
+    const value = await client.create(mode, { idempotencyKey: creationKey, signal: lifetime.signal });
+    if (lifetime.signal.aborted) return;
+    ticket.value = value; creationKey = null;
+  } catch (error) {
+    if (!lifetime.signal.aborted) showError(error as Error);
+    // Keep the same key when retrying an uncertain creation of the same mode.
+  } finally { busy.value = false; }
+}
+onUnmounted(() => { lifetime.abort(); ticket.value = null; creationKey = null; });
+</script>
+
+<template>
+  <button :disabled="busy || !!ticket" @click="start('bind')">Bind phone</button>
+  <button :disabled="busy || !!ticket" @click="start('confirm')">Confirm</button>
+  <AuthLinkBind v-if="ticket?.purpose === 'bind'" :ticket="ticket" :client="client" variant="B"
+    @confirmed="confirmed" @close="finish('Closed')" @rejected="finish('Rejected')"
+    @expired="finish('Expired; start again')" @error="showError" />
+  <AuthLinkConfirm v-else-if="ticket?.purpose === 'confirm'" :ticket="ticket" :client="client" variant="B"
+    @confirmed="confirmed" @close="finish('Closed')" @rejected="finish('Rejected')"
+    @expired="finish('Expired; start again')" @error="showError" />
+  <p role="status">{{ message }}</p>
+</template>
 ```
 
-The dialog adapts to mobile widths, has a scrollable height, keyboard Escape and an accessible close button. Native `<dialog>` provides modal focus handling; a browser with `showModal()` is required. Closing aborts browser observation and restores focus/scroll. It does not reject, delete or undo the server request. Its original expiry still applies. Confirmation and rejection automatically close the dialog before delivering `onConfirmed` or `onRejected`; it does not emit a user-close callback. Always call `modal.destroy()` when the owning page/component unmounts; this cleans up without emitting `onClose`.
+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.
 
-### React
+### 4. React
 
-`showBound(requestId)` is application UI code: it sets a message and clears the ticket to unmount the dialog. The example also defines all rejection, expiry and close handlers. Use `<AuthLinkPanel mode="bind" />` or `<AuthLinkPanel mode="confirm" />`.
+Pass a stable client created as above and mode=bind or confirm. Unmount the instance on logout/account/session changes.
 
 ```tsx
 "use client";
-import { useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { requestKey } from '@auth-link/web';
-import type { Mode, Ticket } from '@auth-link/web';
+import type { AuthLinkClient, Mode, Ticket } from '@auth-link/web';
 import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-import { client } from './authlink-client';
+// Import '@auth-link/web/styles.css' once in your application entry.
 
-export function AuthLinkPanel({ mode }: { mode: Mode }) {
+export function AuthLinkPanel({ client, mode }: { client: AuthLinkClient; mode: Mode }) {
   const [ticket, setTicket] = useState<Ticket | null>(null);
   const [busy, setBusy] = useState(false);
   const [message, setMessage] = useState('');
-  const key = useRef<string | null>(null);
-  const creating = useRef(false);
-  function finish(message: string) {
-    setTicket(null);
-    setMessage(message);
-  }
-  function showBound(requestId: string) {
-    // UI feedback only. The backend has already verified and saved the binding.
-    finish(`Phone bound (request ${requestId})`);
-  }
-  function showConfirmed(requestId: string) {
-    finish(`Confirmed (request ${requestId})`);
-  }
-  const start = async () => {
-    if (creating.current || ticket) return;
-    creating.current = true;
-    setBusy(true);
-    setMessage('');
+  const creation = useRef<{ mode: Mode; key: string } | null>(null);
+  const inFlight = useRef(false);
+  const controller = useRef<AbortController | null>(null);
+  useEffect(() => () => { controller.current?.abort(); }, []);
+  function finish(text: string) { setTicket(null); setMessage(text); }
+  async function start() {
+    if (inFlight.current || ticket) return;
+    inFlight.current = true; setBusy(true); setMessage('');
+    const attempt = new AbortController(); controller.current = attempt;
     try {
-      key.current ??= requestKey();
-      setTicket(await client.create(mode, { idempotencyKey: key.current }));
-      key.current = null;
-    } catch { setMessage('Request failed; retry the same creation.'); }
-    finally { creating.current = false; setBusy(false); }
-  };
+      if (creation.current?.mode !== mode) creation.current = { mode, key: requestKey() };
+      const value = await client.create(mode, { idempotencyKey: creation.current.key, signal: attempt.signal });
+      if (attempt.signal.aborted) return;
+      setTicket(value); creation.current = null;
+    } catch (error) { if (!attempt.signal.aborted) setMessage((error as Error).message); }
+    finally {
+      inFlight.current = false;
+      if (!attempt.signal.aborted) setBusy(false);
+    }
+  }
   const Component = mode === 'bind' ? AuthLinkBind : AuthLinkConfirm;
   return <>
-    {!ticket && <button type="button" disabled={busy} onClick={() => void start()}>Start verification</button>}
-    {ticket && <Component ticket={ticket} client={client}
-      onConfirmed={result => result.purpose === 'bind' ? showBound(result.requestId) : showConfirmed(result.requestId)}
-      onClose={() => finish('Closed')}
-      onRejected={() => finish('Request rejected on the phone')}
-      onExpired={() => finish('Request expired; start again')}
+    {!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>
   </>;
 }
 ```
 
-The backend must verify, consume and persist the binding/confirmation before returning `confirmed`. `showBound` does not grant access or save a binding. You can instead show a toast, reload your own account-status API or navigate to a management page. Reload real binding state from the backend after a page refresh; never treat a callback, local state or localStorage as authorization. The example retains the same creation idempotency key after a failed request.
-
-
-Mounting either component opens a dialog; unmount it in `onClose` (for example, clear the selected ticket). SSR renders no dialog and makes no requests. Omit `locale` for Simplified Chinese. Use `locale="zh-CN"` for Simplified Chinese or another code from the language table. Keep `client` and `ticket` stable between renders. The React entry preserves `"use client"`; SSR rendering does not create requests.
-
-### Vue
-
-```vue
-<script setup lang="ts">
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
-import type { Ticket, Confirmation } from '@auth-link/web';
-import { client } from './authlink-client';
-
-defineProps<{ ticket: Ticket }>();
-function confirmed(result: Confirmation) {
-  console.log('Confirmed request:', result.requestId);
-}
-</script>
-
-<template>
-  <AuthLinkBind v-if="ticket.purpose === 'bind'" :ticket="ticket" :client="client"
-    @confirmed="confirmed" />
-  <AuthLinkConfirm v-else :ticket="ticket" :client="client" locale="ja"
-    @confirmed="confirmed" />
-</template>
-```
-
-Use `:locale="selectedLanguage"` to switch languages without creating a new verification request. Mounting opens the dialog. Use `@close` to clear the selected ticket. Vue exposes `confirmed`, `rejected`, `expired`, `error` and `close` events.
-
-### Choose a layout
-
-Set `variant` when opening a dialog or mounting a component. Omit it for **A**.
-
-| Value | Desktop | Mobile |
-| --- | --- | --- |
-| `A` (default) | Minimal centered card with a thin code-refresh progress bar | Centered card |
-| `B` | QR and matching code in two columns | Vertical layout |
-| `C` | Compact card with footer cancellation | Bottom sheet with safe-area padding |
+### 5. Plain JavaScript / direct dialogs
 
 ```ts
-openAuthLinkBind({ ticket, client }); // A, Simplified Chinese by default
-openAuthLinkConfirm({ ticket, client, variant: 'B' });
-// modal.setVariant('C'); // Presentation only; preserves the request and polling.
-```
-
-```tsx
-<AuthLinkBind ticket={ticket} client={client} variant="C" />
-```
+import { openAuthLinkConfirm, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
 
-```vue
-<AuthLinkConfirm :ticket="ticket" :client="client" variant="B" />
+// Inside a click handler; client is the stable instance created above.
+const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
+const modal = openAuthLinkConfirm({
+  ticket, client, variant: 'B', locale: 'zh-CN',
+  onConfirmed: result => console.log(result.requestId),
+  onRejected: result => console.log(result.code),
+  onExpired: () => console.log('Expired'),
+  onError: error => console.log(error.message),
+  onClose: () => console.log('Closed'),
+});
+// Route/component cleanup: modal.destroy();
+// Optional: modal.close(); modal.retry(); modal.setLocale('ja'); modal.setVariant('C');
 ```
 
-All layouts show a thin progress bar and a static “Code updates automatically every 30 seconds” caption. The footer normally says “Waiting for your phone”; only in the last 30 seconds does it switch to an amber “Request expiring soon · 00:29” warning. Code changes fade in briefly, respect reduced-motion preferences, and never extend the request expiry.
+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.
 
-All variants use the same verification, expiry and callbacks. `variant` changes can be reactive in React and Vue without restarting observation. Invalid runtime values fall back to A. The footer Cancel control in B/C has the same behavior as the close icon: it closes observation, without rejecting the server request. Confirmation still dismisses the dialog automatically. A uses a subtle close icon; all close controls retain a 44px hit target and keyboard focus indication.
+### 6. API shapes the frontend needs
 
-### Component options
-
-| Option | Type | Meaning |
-| --- | --- | --- |
-| `ticket` | `Ticket`, required | Existing request returned by your backend |
-| `client` | `AuthLinkClient`, required | Client that queries your backend |
-| `locale` | `Locale` | Interface language; defaults to `zh-CN` |
-| `variant` | `DialogVariant` | `A` (default), `B` or `C`; changes layout only |
-| `showQr` | `boolean` | Optional QR on confirmation panels; binding panels always show it |
-| `intervalMs` | `number` | Polling interval, 250–10000 ms; default 1500 ms |
-| `onRefresh` | `() => void` | Create a new request from the expiry panel and replace the ticket |
-
-| React callback / Vue event | Argument | Meaning |
+| Application route | Frontend sends | Frontend reads |
 | --- | --- | --- |
-| `onConfirmed` / `confirmed` | `Confirmation` | Backend has verified and consumed the result |
-| `onRejected` / `rejected` | `Rejection` | Phone rejected; dialog closes automatically |
-| `onExpired` / `expired` | None | Request expired |
-| `onClose` / `close` | None | Dialog closed; unmount the component / clear its ticket |
-| `onError` / `error` | `Error` | Network, response validation or callback failure |
+| 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 |
 
-Rejection returns `{ status: 'rejected', code: 'REJECTED', requestId, purpose }`. `REJECTED` is an SDK business status, not an HTTP status code or an authorization receipt. The SDK closes the dialog without showing a rejection/retry panel or firing `onClose`. Handle any message or new request in your website's callback. In React/Vue, clear the selected ticket in `onRejected` / `@rejected` to unmount the component. Headless hooks retain `snapshot.status === 'rejected'` for custom UI.
+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.
 
-`useAuthLink(options)` for React and `useAuthLink(() => options)` for Vue expose `snapshot` and `retry` for custom interfaces. Vue's snapshot is a shallow ref. Retry resumes the same request; `onRefresh` creates a new one through your code.
-
-### Backend contract
-
-The default prefix is `/api/authlink`. Both endpoints authenticate the website user using session cookies plus the configured CSRF header, or Bearer authentication. Creation also sends a stable `Idempotency-Key`. Derive the account from the validated session/token rather than a browser-supplied account ID.
+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 type { Ticket, Result } from '@auth-link/web';
-
-// POST /api/authlink/requests
-// Body: { purpose: 'bind' | 'confirm' }
-// Response: Ticket
-
-// POST /api/authlink/requests/{requestId}/result
-// Body: {}
-// Response: Result
-```
-
-```json
-{
-  "status": "confirmed",
-  "requestId": "<request-id>",
-  "verificationId": "<verification-id>",
-  "purpose": "confirm",
-  "authenticationPolicy": "device-presence.v1",
-  "expiresAt": "<same-expiry-as-ticket>"
-}
+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.
 ```
 
-Creation returns the public ticket from AuthLink: `requestId`, `purpose`, `qr`, `pairingCode`, `expiresAt` and the current `displayCode`. The display frame contains `value`, `serverTime`, `validUntil`, `periodSeconds: 30`. A confirmation ticket requires a display frame.
+### 7. Props, events and presentation
 
-The result endpoint verifies the authenticated user and request ownership (plus CSRF for cookie mode) and forwards pending states and the current display frame. States `new`, `pending`, `approved` and `consumed` alone do not trigger success. Before returning `confirmed`, your backend must consume the AuthLink result with its saved state and stable consume idempotency key, check the complete receipt and persist confirmation for the correct session. Persist idempotence using request/verification IDs.
-
-### Languages
-
-| 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 |
+| 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 |
 
-Missing or unsupported locale codes fall back to Simplified Chinese. The panel sets its root `lang` attribute. Import `supportedLocales` from the root entry to get the supported codes. Language selection changes display text only, never the verification request or matching numbers. Documentation is available in English, Chinese and Japanese through the links above.
+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.
 
-### Styles and entry points
+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.
 
-Explicitly import `@auth-link/web/styles.css`. Override `--authlink-foreground`, `--authlink-background`, `--authlink-accent` and `--authlink-muted` on `:root` or `.authlink-dialog`; dialogs are mounted under `document.body`. All component classes use the `authlink-` prefix.
+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.
 
-React and Vue accept `className` for the dialog. Vue also accepts standard string, array or object `class` attributes, combined with `className`. Refresh buttons use the latest `onRefresh` callback supplied by the parent.
+### 8. Transport options and troubleshooting
 
-| Import | Contents |
+| Option | Purpose |
 | --- | --- |
-| `@auth-link/web` | Client, request key, supported locales, types and core tools |
-| `@auth-link/web/react` | React components and hook |
-| `@auth-link/web/vue` | Vue components and composable |
-| `@auth-link/web/styles.css` | Component styles |
+| `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 |
 
-### Security and timing
+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.
 
-- Matching numbers are for visual comparison with the app, not standalone passwords or authorization proofs.
-- The browser receives only public tickets and current display frames, never generation seeds, device keys or tenant secrets.
-- A request lasts at most 120 seconds; rotating the code does not extend it. Backend and app must support AuthLink mobile protocol 7.
-- Countdown uses server time and a monotonic clock. Expired numbers are hidden even if a network call stalls; a short update gap at rotation is expected.
-- Component unmount/request changes abort polling. Confirmation is deduplicated per mounted instance; your backend still needs persistent idempotence.
-- Frontend callbacks update UI. Protected APIs must rely on trusted backend records, never a JavaScript callback or a browser-supplied success flag.
-- QR generation is local; backend SVG is not injected and no third-party QR service receives the ticket. Allow `img-src 'self' data:` in your CSP.
+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` for the full license text and `THIRD_PARTY_NOTICES.md` for bundled third-party attribution.
-
-### Go Vue CMS: en
+MIT. See LICENSE and THIRD_PARTY_NOTICES.md.
 
-This walkthrough follows a working Go CMS and Vue 3 integration. Example origins replace local deployment details; no test users, passwords or tenant credentials are required by these examples. Your website implements login, persistence and business routes. The web package displays and observes requests; the Go SDK calls AuthLink and validates receipts.
+---
 
-#### 1. Install and separate the three origins
+## 简体中文
 
-| Role | Example origin | Configuration |
-| --- | --- | --- |
-| Vue | `https://cms.example.com` | `apiOrigin` is the Go backend below |
-| Go CMS API | `https://cms-api.example.com` | `baseUrl=https://cms-api.example.com/api/authlink` |
-| AuthLink API | `https://auth.example.com` | Go SDK `Origin`; browser `authLinkOrigin` |
+用于手机绑定与 App 确认的前端组件，支持 Vue 3、React 18/19 和原生 JavaScript。本文按前端接入顺序说明安装、登录状态读取、客户端初始化、弹窗和事件处理。
 
-Register the Vue site's origin for the tenant. The Go SDK `Origin` and the API origin in an exported credential JSON identify the AuthLink API. Browser `baseUrl` targets your Go application API. Keep TenantID/APIKey in private backend configuration; public runtime configuration contains origins only.
+### 1. 安装并区分两个 API 地址
 
 ```sh
-npm install @auth-link/web@latest vue
-# In your Go backend module, after unpacking the supplied Go SDK:
-go mod edit -replace=authlink.local/sdk=./third_party/authlink-go
-go mod edit -require=authlink.local/sdk@v0.0.0
-go mod tidy
-```
-
-The Go SDK is supplied as source or a Go SDK archive from your AuthLink website, not a public Go module or an npm backend. Preserve its own go.mod and import `authlink "authlink.local/sdk"`. Initialize it with trusted `authlink.Config{Origin: authOrigin, TenantID: tenantID, APIKey: apiKey}` through `authlink.New`.
-
-#### 2. Log in to the website and load its session
-
-Your login route (the reference CMS uses `POST /api/login`) issues a Secure, HttpOnly session cookie. Fetch Go's `GET /api/session` with `credentials:'include'`; require `authenticated:true` and the current `csrf` value before opening requests. Otherwise return to your own login flow.
-
-Here the JSON property is **csrf**, while the SDK option is **csrfToken**: use `csrfToken: () => session.value?.csrf ?? ''`. A backend is free to name the response property differently. Go generates and saves the token for that session and validates X-CSRF-Token on creation AND result polling. Never substitute a tenant key or matching number.
-
-Two HTTPS subdomains under the same site are cross-origin but same-site. The reference API sets a host-only cookie with `SameSite=Strict; Secure; HttpOnly; Path=/`, without Domain. Requests still target the API host. For a truly cross-site setup, account for browser cookie policy as well as CORS.
-
-#### 3. Configure Go CORS and application routes
-
-```http
-Access-Control-Allow-Origin: https://cms.example.com
-Access-Control-Allow-Credentials: true
-Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
-Access-Control-Allow-Headers: Content-Type, X-CSRF-Token, Idempotency-Key
-Vary: Origin
-Cache-Control: no-store
+npm install @auth-link/web@latest
+# 另行安装你的项目使用的 vue，或 react / react-dom。
 ```
 
-Return these headers only for an exact allowed Vue origin, including allowed-origin error responses. Validate the origin/method/headers of OPTIONS and return 204 before requiring login or CSRF; authenticate and check CSRF/ownership on actual requests. Do not reflect arbitrary origins or use `*`. PUT is for CMS draft editing; narrow it to the routes you implement.
-
-| Application route | Input | Output |
+| 地址 | 前端配置 | 用途 |
 | --- | --- | --- |
-| `GET /api/session` | — | `{authenticated:true, csrf:"…", subject:"…", username:"…"}`; logged out: `{authenticated:false}` |
-| `POST /api/authlink/requests` | `{purpose:"bind"}` or `{purpose:"confirm",postId,version}`; `Idempotency-Key` | Public `Ticket` |
-| `POST /api/authlink/requests/{id}/result` | `{}`; current session + CSRF | Pending status/displayCode or verified `confirmed` receipt |
-| `POST /api/posts/{id}/publish` | `{requestId,version}`; current session + CSRF | `{ok:true}` after checking the saved confirmation and intent |
-
-Your Go application implements all four routes. postId/version and the publication route are application-specific conventions, not AuthLink fields.
-
-#### 4. Persist before creation; commit verification before confirmed
+| 你的网站业务后台，如 `https://cms-api.example.com` | `baseUrl`、`allowedBackendOrigins` | 登录状态、创建请求和查询结果 |
+| AuthLink 生产 API：`https://api.getauthlink.com` | `authLinkOrigin` | 核对 ticket 中的 AuthLink 服务来源 |
 
-```text
-Vue → Go /api/session → current session + csrf
-Vue → Go /api/authlink/requests → Go SDK CreateRequest → public ticket
-Vue dialog → Go /api/authlink/requests/{id}/result → Status + Consume
-Go commits verified receipt → Vue confirmed event
-Vue → Go /api/posts/{id}/publish → validate saved intent/receipt → publish
-```
+`baseUrl` 不是 AuthLink API，也不是 AuthLink 官网。接入方的网站和业务 API 仍使用自己的域名。需要已有的网站登录状态和下文的请求接口；Web SDK 不提供登录或会话接口。租户密钥不能放到浏览器。
 
-Derive the stable user ID from the authenticated session. Before an upstream call, validate purpose/idempotency and optional post ownership/version; independently generate state and a consume key, then persist CreateInput, the browser creation key, session/user and publication intent. A network retry loads the same record and keys. Enforce unique (session, creation key) and reject reuse for a different purpose/post/version.
+导入入口：根入口提供客户端和类型；`/vue`、`/react` 提供组件及 useAuthLink；`/styles.css` 必须显式导入。ESM、TypeScript，工具环境 Node 22.13+；React 18.2+/19、Vue 3.3+，只安装所用框架。
 
-Save the returned ticket, requestId and original expiresAt; omit optional qrSvg before returning public data. The result route locks the request owned by the current session and reuses any saved receipt. Call Status, then Consume only for approved/consumed using Expected reconstructed from saved data. Persist the verified public receipt, session confirmation and audit transactionally with unique requestId/verificationId constraints; commit before returning confirmed. Pending results preserve displayCode without caching beyond its validity.
+### 2. 读取当前登录状态并创建客户端
 
-This is the SDK-call layer, **not a complete HTTP server**. Your application must implement the database/transaction and ownership steps described above and in the comments.
+```ts
+import { createAuthLinkClient } from '@auth-link/web';
+import '@auth-link/web/styles.css';
 
-```go
-package cmsauth
+// 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',
+  });
+}
+```
 
-import (
-    "context"
-    authlink "authlink.local/sdk"
-)
+先完成你的网站登录，再读取应用已有的会话接口。下面使用与 CMS 一致的 `{authenticated, csrf}` 响应；如果你的后台字段名为 csrfToken，读取它再交给 SDK 的 csrfToken 回调即可。
 
-// Load this record from your database for the authenticated user/session.
-// Save Input (including State), CreateKey and ConsumeKey BEFORE calling Create.
-// Intent (post ID/version), ownership and unique constraints belong in your DB.
-type StoredRequest struct {
-    Input authlink.CreateInput
-    CreateKey string
-    ConsumeKey string
-    Ticket authlink.Ticket
+```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',
+});
+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.
+```
 
-// On network retries, load the SAME record; do not regenerate State or keys.
-func Create(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (authlink.Ticket, error) {
-    return sdk.CreateRequest(ctx, saved.Input, saved.CreateKey)
-}
+`GET /api/session` 是网站已有接口的示例，请按实际路径替换。同源可以使用相对路径和 same-origin Cookie；跨域 Cookie 使用 include，并要求当前前端来源已被业务后台允许。Cookie 策略仍可能限制请求。浏览器无法读取 HttpOnly Cookie，只需要传回当前会话的 CSRF token；不能用手机核对码或浏览器随机值代替。
 
-type PublicConfirmation struct {
-    Status string `json:"status"`
-    RequestID string `json:"requestId"`
-    VerificationID string `json:"verificationId"`
-    Purpose string `json:"purpose"`
-    ExpiresAt string `json:"expiresAt"`
-    AuthenticationPolicy string `json:"authenticationPolicy"`
-}
+已有 Bearer / JWT 登录的项目可用下列配置，auth 是你的网站登录状态，刷新流程更新 auth.accessToken。此 token 不是 AuthLink 租户密钥。仅在 credentials=omit 的 Bearer 模式可以不传 CSRF；若同时发送 Cookie，仍需 csrfToken。
 
-// Caller checks session/CSRF/ownership, locks the saved record and first returns
-// any already-saved receipt. For a new confirmed result, caller must persist
-// the receipt and confirmation in a DB transaction BEFORE returning HTTP 200.
-func Poll(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (any, error) {
-    status, err := sdk.Status(ctx, saved.Ticket.RequestID)
-    if err != nil { return nil, err }
-    if status.Status != "approved" && status.Status != "consumed" { return status, nil }
-    result, err := sdk.Consume(ctx, authlink.Expected{
-        RequestID: saved.Ticket.RequestID,
-        ExternalUserID: saved.Input.ExternalUserID,
-        Purpose: saved.Input.Purpose,
-        State: saved.Input.State,
-        ExpiresAt: saved.Ticket.ExpiresAt,
-    }, saved.ConsumeKey)
-    if err != nil { return nil, err }
-    return PublicConfirmation{
-        Status: "confirmed", RequestID: result.RequestID,
-        VerificationID: result.VerificationID, Purpose: result.Purpose,
-        ExpiresAt: saved.Ticket.ExpiresAt, AuthenticationPolicy: result.AuthenticationPolicy,
-    }, nil
-}
+```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',
+});
 ```
 
-#### 5. Vue lifecycle and business-bound requests
+### 3. Vue：点击创建、展示和清理
 
-The complete file is also shipped as `examples/vue-cms.vue`. Mount after site login with trusted apiOrigin/authLinkOrigin and an optional saved draft `post={id,version}`. Key the parent component by the current authenticated session identity. Unmount on logout, login rotation or account change; clear old tickets, creation keys and pending publication before mounting a new instance.
+完整文件随包提供为 `examples/vue-client.vue`，可复制为 AuthLinkPanel.vue。父组件在登录后传入当前 session.csrf；跨域时额外传 backendOrigin。退出或切换账号/session 时卸载旧组件，重新挂载新实例；CSRF 刷新可更新 csrf prop。
 
 ```vue
 <script setup lang="ts">
-import { markRaw, onMounted, onUnmounted, ref, shallowRef } from 'vue';
-import { createAuthLinkClient, requestKey, validateTicket } from '@auth-link/web';
+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';
 
-type Post = { id: string; version: number };
-type Publication = Post & { requestId: string };
-// Supply trusted deployment configuration. Mount after site login and remount
-// with :key="session.subject" after login, logout or account/session changes.
-const props = defineProps<{ apiOrigin: string; authLinkOrigin: string; post?: Post }>();
-const session = ref<{ authenticated: boolean; csrf?: string } | null>(null);
+// csrf comes from your website's current authenticated session.
+const props = defineProps<{ csrf: string; backendOrigin?: string }>();
 const ticket = shallowRef<Ticket | null>(null);
-const publication = shallowRef<Post | null>(null);
-const retryPublish = shallowRef<Publication | null>(null);
 const busy = ref(false), message = ref('');
-let creation: { signature: string; key: string } | null = null;
 const lifetime = new AbortController();
+let creationKey: string | null = null;
+let creationMode: Mode | null = null;
 const client = markRaw(createAuthLinkClient({
-  baseUrl: `${props.apiOrigin}/api/authlink`,
-  allowedBackendOrigins: [props.apiOrigin],
-  credentials: 'include',
-  csrfToken: () => session.value?.csrf ?? '',
-  authLinkOrigin: props.authLinkOrigin,
+  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',
 }));
-
-async function api(path: string, body?: unknown, headers: Record<string, string> = {}) {
-  const response = await fetch(`${props.apiOrigin}${path}`, {
-    method: body === undefined ? 'GET' : 'POST',
-    credentials: 'include', cache: 'no-store', redirect: 'error',
-    signal: lifetime.signal,
-    headers: body === undefined ? {} : {
-      'Content-Type': 'application/json', 'X-CSRF-Token': session.value?.csrf ?? '', ...headers,
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  const value = await response.json();
-  if (response.status === 401) {
-    session.value = null; closeTicket(); retryPublish.value = null; creation = null;
-  }
-  if (!response.ok) throw new Error(value.code ?? 'REQUEST_FAILED');
-  return value;
+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 closeTicket() { ticket.value = null; publication.value = null; }
 function showError(error: Error) { message.value = error.message; }
-function finish(text: string) { closeTicket(); message.value = text; }
-
-async function start(purpose: Mode, post?: Post) {
-  if (busy.value || ticket.value || !session.value?.authenticated) return;
-  busy.value = true; message.value = ''; retryPublish.value = null;
-  const intent = post ? { id: post.id, version: post.version } : null;
-  const signature = JSON.stringify({ purpose, postId: intent?.id, version: intent?.version });
+async function start(mode: Mode) {
+  if (busy.value || ticket.value) return;
+  busy.value = true; message.value = '';
   try {
-    if (creation?.signature !== signature) creation = { signature, key: requestKey() };
-    // SDK create() sends only {purpose}. Business fields use your own API.
-    const value = intent
-      ? validateTicket(await api('/api/authlink/requests', {
-          purpose, postId: intent.id, version: intent.version,
-        }, { 'Idempotency-Key': creation.key }), purpose, props.authLinkOrigin)
-      : await client.create(purpose, { idempotencyKey: creation.key, signal: lifetime.signal });
+    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;
-    publication.value = intent; ticket.value = value; creation = null;
+    ticket.value = value; creationKey = null;
   } catch (error) {
     if (!lifetime.signal.aborted) showError(error as Error);
-    // Retain creation.key for a retry of the SAME purpose/post/version.
+    // Keep the same key when retrying an uncertain creation of the same mode.
   } finally { busy.value = false; }
 }
-async function publish() {
-  const intent = retryPublish.value;
-  if (!intent || busy.value) return;
-  busy.value = true;
-  try {
-    await api(`/api/posts/${intent.id}/publish`, { version: intent.version, requestId: intent.requestId });
-    retryPublish.value = null; message.value = 'Published. Reload your posts from the backend.';
-  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
-  finally { busy.value = false; }
-}
-async function confirmed(result: Confirmation) {
-  const intent = publication.value;
-  closeTicket();
-  if (intent) { retryPublish.value = { ...intent, requestId: result.requestId }; await publish(); }
-  else message.value = 'Verified. Reload account status from the backend.';
-}
-onMounted(async () => {
-  try {
-    const value = await api('/api/session');
-    if (value.authenticated !== true || typeof value.csrf !== 'string' || !value.csrf) {
-      throw new Error('LOGIN_REQUIRED');
-    }
-    session.value = value;
-  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
-});
-onUnmounted(() => { lifetime.abort(); closeTicket(); creation = null; retryPublish.value = null; });
+onUnmounted(() => { lifetime.abort(); ticket.value = null; creationKey = null; });
 </script>
 
 <template>
-  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('bind')">Bind phone</button>
-  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm')">Confirm</button>
-  <button v-if="post" :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm', post)">Confirm publication</button>
-  <button v-if="retryPublish" :disabled="busy || !!ticket" @click="publish">Retry the same publication</button>
+  <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 a new request')" @error="showError" />
+    @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 a new request')" @error="showError" />
+    @expired="finish('Expired; start again')" @error="showError" />
   <p role="status">{{ message }}</p>
 </template>
 ```
 
-`client.create(purpose, {idempotencyKey})` sends purpose only. To bind confirmation to a post/version, use your own fetch with those business fields, validate the result with `validateTicket(response, 'confirm', authLinkOrigin)`, and reuse the official client for observation. Keep the same creation key after an uncertain failure, and change it when purpose/post/version changes. Keep tickets in shallowRef and clients in markRaw.
-
-Mounting a dialog observes an existing request; never create from mounted/watch. Clear the ticket on close/rejection/expiry. Leave the dialog mounted on network errors to retry that request. On confirmation, dismiss it and call the independent publish route; preserve the same requestId/post/version if that call fails. Reload actual account/post state from the backend. The sample omits your login form, post list and application error translations.
-
-#### 6. Recheck confirmation in the publish transaction
-
-The browser confirmed event is not authorization. Go must load the verified receipt for the current session and check purpose=confirm, intent=publish, post ownership, the same postId/version, draft state and expiry on first application. Update the post and mark the intent applied atomically. A retry of that same applied operation returns success without duplicate publication/audit. Another post or edited version requires a new confirmation. Do not add action, transactionHash or document content to the AuthLink receipt.
-
-#### Acceptance sequence
+示例使用 shallowRef 保存 ticket、markRaw 保存 client。创建失败保留同一用途的原幂等键；成功后才清空。创建只发生在点击事件中，mounted/watch 不创建请求。确认、拒绝、过期或用户关闭时清空 ticket，卸载组件；网络错误保留弹窗，使用弹窗的重试按钮继续当前请求。需要真实账号状态时重新查询你的网站状态接口。
 
-Site login → session bootstrap → backend AccountStatus (the reference CMS exposes it through overview) → bind if unbound → phone approval → consume and refresh account status → save draft → confirm that post/version → phone approval → commit receipt → publish → verify duplicate retry, wrong version, rejection and expiry. Real phone approval remains a separate acceptance step; compilation and mock HTTP checks do not replace it.
+### 4. React
 
----
-
-## 简体中文
+使用上面的初始化方式创建稳定 client，再传给此组件；mode 为 bind 或 confirm。退出或切换账号/session 时卸载旧实例。
 
-**AuthLink 官方前端组件包**，帮助网站接入手机绑定与 App 确认流程，支持 React 18/19、Vue 3.3+、TypeScript 和 ESM。
+```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.
 
-### Go + Vue 完整接入
+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>
+  </>;
+}
+```
 
-按实际 CMS 流程接入，推荐先读 [Go + Vue：从登录、绑定到确认发布](#go-vue-cms-zh-cn)，完整组件见 `examples/vue-cms.vue`。
+### 5. 原生 JavaScript / 直接调用
 
-顺序是：网站登录 → 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。
+```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。
 
-- **扫码绑定**：网站显示二维码，用户使用 AuthLink App 扫码并确认绑定。
-- **手机确认**：电脑与 App 显示同步变化的六位数字，每 30 秒更新，用户核对后在 App 内批准。
-- **结果通知**：提供确认成功、拒绝、过期和错误事件，方便网站更新界面。
-- **框架支持**：React 组件与 hook、Vue 组件与 composable，以及无框架客户端。
-- **多语言与主题**：支持下表中的 13 种语言，默认简体中文；独立 CSS 和可覆盖的主题变量。
-- **生命周期管理**：请求切换或组件卸载时取消轮询，数字过期后自动隐藏。
+### 6. 前端需要的接口约定
 
-此包是 AuthLink 的网页接入层，需要配套应用后台、AuthLink 服务和手机 App。完整 AuthLink 流程校验原手机硬件密钥证明及 App 内批准，不要求系统通行密钥、指纹或锁屏；安装此包本身不会建立鉴权服务。
+| 网站接口 | 前端发送 | 前端读取 |
+| --- | --- | --- |
+| `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 分别触发对应事件。
 
-1. 在应用后台完成站点租户配置，并实现本文的创建请求、查询结果两个业务后台接口（同源或显式配置的跨域后台）。
-2. 安装包、导入样式，创建指向应用后台的客户端。
-3. 用户点击绑定或验证时创建请求，将返回的 ticket 交给 React/Vue 组件。
-4. 用户在 App 确认后，应用后台验证并消费结果，组件收到可信确认事件。
+若你的网站创建接口需要文章 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. 参数、事件与样式
 
-应用后台根据当前登录用户创建 `bind` 或 `confirm` 请求，前端拿到 ticket 后交给组件。组件只轮询应用后台。应用后台在验证归属、state、双重认证策略并消费一次性结果后，才返回 `confirmed`。
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| `ticket` | `Ticket` | Required; the current request |
+| `client` | `AuthLinkClient` | Required; keep the instance stable |
+| `locale` | `Locale` | Default `zh-CN` |
+| `variant` | `'A' / 'B' / 'C'` | Default `A` |
+| `showQr` | `boolean` | Optional QR for confirm; bind always shows QR |
+| `intervalMs` | `number` | Default 1500; range 250–10000 ms |
+| `onRefresh` | `() => void` | Optional user action after expiry; create a new ticket |
+| `className` | `string` | Custom dialog class; Vue also accepts `class` |
+
+| React 回调 / Vue 事件 | 参数 | 行为 |
+| --- | --- | --- |
+| `onConfirmed` / `confirmed` | `Confirmation` | Success; dialog closes automatically |
+| `onRejected` / `rejected` | `Rejection` | `{status:'rejected',code:'REJECTED',requestId,purpose}`; dialog closes |
+| `onExpired` / `expired` | — | Request expired |
+| `onClose` / `close` | — | User closes the dialog; clear ticket |
+| `onError` / `error` | `Error` | Read `error.message`; retain the dialog for retry |
 
-定时数字用于电脑与手机核对；用户仍在 AuthLink App 内完成 原手机硬件密钥校验和 App 内批准。它不是用户输入网站的 TOTP 登录密码，不能单独授权。请求最长 120 秒；数字变化不延长请求有效期。前端不生成数字、不接收生成 seed，不在数字更新时新建请求。
+A 为默认居中卡片；B 为桌面分栏、窄屏纵排；C 为紧凑卡片、手机底部弹层。切换 locale/variant 不重新创建请求。原生 dialog.showModal() 浏览器支持是必需的。
 
-需要配套更新后的 Go 服务和客户端协议 7。服务端与 App 必须使用当前单一协议，不能只升级网页。
+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. 传输配置与排错
 
-```sh
-npm install @auth-link/web
-```
+| 配置 | 用途 |
+| --- | --- |
+| `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 |
 
-### 创建应用客户端（默认同源 Cookie 模式）
+自定义 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 秒，关闭/卸载会取消观察。
 
-`readCsrfTokenFromYourCms` 是接入方函数，不是包里的导出；名称不要求与你的网站框架一致，也不要求使用 CMS。它只读取**你的网站后台提供的 CSRF token**，用于保护携带登录 cookie 的请求，不是 AuthLink 租户 API key、登录 cookie 或手机核对码。
+数字过期会隐藏，不在前端生成或缓存新数字；二维码在浏览器本地生成。若页面启用 CSP，图片来源需要允许 data:。确认回调、localStorage 或浏览器自报状态都不作为业务授权依据。
 
-下面采用页面 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 自带接口。
+MIT。完整文本见 LICENSE，第三方归属见 THIRD_PARTY_NOTICES.md。
 
-```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';
+スマートフォン登録とアプリ内確認のフロントエンド用ダイアログです。Vue 3、React 18/19、通常の JavaScript に対応します。インストール、session 取得、client 初期化、表示、イベントと後処理の順に接続します。
 
-// 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;
-}
+### 1. インストールと 2 つの API
 
-export const client = createAuthLinkClient({
-  baseUrl: '/api/authlink',
-  csrfToken: readCsrfTokenFromYourCms,
-  // Replace this example with the configured AuthLink service origin.
-  authLinkOrigin: 'https://auth.example.com',
-});
+```sh
+npm install @auth-link/web@latest
+# 利用する vue、または react / react-dom もインストールします。
 ```
 
-把 `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 服务来源，两者作用不同，可按需要同时配置。
+| origin | フロントエンド設定 | 用途 |
+| --- | --- | --- |
+| 自サイトの API（例 https://cms-api.example.com） | baseUrl、allowedBackendOrigins | session、要求作成、結果 |
+| AuthLink 本番 API https://api.getauthlink.com | authLinkOrigin | ticket 内のサービス origin の照合 |
 
-#### 跨域 Cookie / session
+baseUrl は自サイトの業務 API であり、AuthLink API や公式サイトではありません。既存のログイン/session と下記要求 API を利用します。SDK 自体はログイン/session API を提供しません。テナントキーはブラウザーに渡しません。
 
-下面给出完整的初始化函数。`GET /api/session` 是接入网站自己实现的示例会话接口，不是包或 AuthLink 服务自带的接口；它应根据现有登录 cookie 返回 `{ "csrfToken": "当前会话的真实CSRF token" }`，设置 `Cache-Control: no-store` 并配置下文的 CORS。部署时将路径换成网站实际的会话初始化接口。
+ルート import は client と型、/vue と /react はコンポーネントと useAuthLink、/styles.css は明示 import です。ESM、TypeScript、ツール環境 Node 22.13+、React 18.2+/19 または Vue 3.3+。利用するフレームワークのみ導入します。
 
-这里的 `csrfToken` 是通用示例选定的 JSON 字段名。Go CMS 实例实际返回 `{ authenticated: true, csrf: '…' }`；读取 `session.csrf` 并交给同名 SDK 配置回调即可，无须改动后台响应。完整映射见上方 Go + Vue 指南。
+### 2. 現在の session と client
 
 ```ts
 import { createAuthLinkClient } from '@auth-link/web';
+import '@auth-link/web/styles.css';
 
-/** /api/session is an example endpoint implemented by your application backend. */
-export async function createSessionBackendClient(backendOrigin: string) {
-  const response = await fetch(`${backendOrigin}/api/session`, {
-    credentials: 'include', cache: 'no-store', redirect: 'error',
+// getCsrf reads your website's CURRENT session token on every request.
+export function createWebsiteClient(getCsrf: () => string, backendOrigin?: string) {
+  return createAuthLinkClient({
+    baseUrl: backendOrigin ? `${backendOrigin}/api/authlink` : '/api/authlink',
+    allowedBackendOrigins: backendOrigin ? [backendOrigin] : [],
+    credentials: backendOrigin ? 'include' : 'same-origin',
+    csrfToken: getCsrf,
+    authLinkOrigin: 'https://api.getauthlink.com',
   });
-  if (!response.ok) throw new Error('Session initialization failed');
-  const session: unknown = await response.json();
-  if (!session || typeof session !== 'object' || !('csrfToken' in session) ||
-      typeof session.csrfToken !== 'string' || !session.csrfToken) {
-    throw new Error('The session endpoint must return { csrfToken: string }');
-  }
-  let currentCsrfToken = session.csrfToken;
-  return {
-    client: createAuthLinkClient({
-      baseUrl: `${backendOrigin}/api/authlink`,
-      allowedBackendOrigins: [backendOrigin],
-      credentials: 'include',
-      csrfToken: () => currentCsrfToken,
-    }),
-    // Call after your application's session/token refresh; recreate on account changes.
-    updateCsrfToken(value: string) { currentCsrfToken = value; },
-  };
 }
 ```
 
-登录后调用 `await createSessionBackendClient('https://api.example.com')`，把返回的 `client` 交给现有 React/Vue 组件。网站刷新 CSRF token 时调用返回的 `updateCsrfToken(newToken)`；退出或切换账号时关闭旧弹窗，清理旧状态并重新初始化。`credentials: 'include'` 才会让跨域请求携带后台 cookie，但仍受 cookie 的 SameSite、Secure、Domain/Path 及浏览器第三方 Cookie 策略约束；跨域不一定跨站。真正跨站的 cookie 通常需要 `SameSite=None; Secure`，浏览器仍可能阻止第三方 Cookie。不能把 `include` 当成绕过 Cookie 策略的开关。
-
-#### 跨域 Bearer token / JWT
-
-传入网站自己的登录状态对象；网站完成登录或刷新后更新这个对象的 `accessToken`。回调会在每次创建和轮询时重新读取最新 token，无需重建弹窗。
+サイトのログイン後に既存 session API を読みます。例は CMS の authenticated/csrf です。フィールド名が csrfToken ならその値を SDK の csrfToken コールバックへ渡します。
 
 ```ts
-import { createAuthLinkClient } from '@auth-link/web';
-
-/** auth is your website's existing login state, updated by its login/refresh flow. */
-export function createBearerBackendClient(backendOrigin: string, auth: { accessToken: string }) {
-  return createAuthLinkClient({
-    baseUrl: `${backendOrigin}/api/authlink`,
-    allowedBackendOrigins: [backendOrigin],
-    credentials: 'omit',
-    accessToken: () => auth.accessToken,
-  });
+// Run in your website's existing authenticated browser flow.
+const backendOrigin = 'https://cms-api.example.com'; // YOUR application backend
+const response = await fetch(`${backendOrigin}/api/session`, {
+  credentials: 'include', cache: 'no-store', redirect: 'error',
+});
+if (!response.ok) throw new Error('Session unavailable');
+let session = await response.json();
+if (session.authenticated !== true || typeof session.csrf !== 'string' || !session.csrf) {
+  throw new Error('Log in to your website first');
 }
+const client = createWebsiteClient(() => session.csrf, backendOrigin);
+// Same origin: createWebsiteClient(() => session.csrf)
+// After token refresh, replace session or update session.csrf.
+// On logout/account/session change, close/unmount old dialogs and recreate client state.
 ```
 
-`accessToken` 必须是接入网站的用户登录 token，不能是 AuthLink 租户 API key。SDK 自动添加 `Authorization: Bearer ...`。纯 Bearer 模式默认 `credentials: 'omit'`，可不传 `csrfToken`；后台应仅按 Bearer token 认证，不回退到 Cookie 登录。若显式设置 `credentials: 'include'` 或 `'same-origin'` 混用 Cookie，仍须提供并校验 `csrfToken`。
-
-#### 后台 CORS 配置
-
-后台需处理浏览器发出的 `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`，具体原因需查看浏览器开发者工具。
+GET /api/session はサイト側の既存ルートの例です。同 origin は相対 URL と same-origin Cookie、別 origin の Cookie は include を使い、業務 API が現在のフロントエンド origin を許可している必要があります。Cookie 制限も適用されます。HttpOnly Cookie を読んだり、CSRF をブラウザーで生成したり、照合数字で代用したりしません。
 
-### 直接调用弹窗（React、Vue 或原生 JavaScript）
+Bearer/JWT を使う場合、auth は既存ログイン状態です。更新された accessToken を毎回読みます。これはテナントキーではありません。credentials=omit の Bearer のみ CSRF を省略でき、Cookie 併用なら csrfToken が必要です。
 
 ```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('已关闭'),
+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',
 });
-// 绑定使用 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()，不会重建鉴权请求。
-
-
-### React
+### 3. Vue：クリックで作成、表示、後処理
 
-下面的 `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 { 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`，语言切换不会重新创建鉴权请求。
-
-React 入口保留 `"use client"`，可用于 Next.js 客户端组件。导入包和 SSR 渲染不会创建请求。将 client 与 ticket 保持为稳定对象，例如模块级 client 和 React state 中的 ticket。卸载/切换 ticket 会取消旧轮询；StrictMode 不会创建额外请求。
-
-### Vue
-
-```vue
-<script setup lang="ts">
-import { ref, shallowRef } from 'vue';
-import { requestKey } from '@auth-link/web';
-import type { Confirmation, Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
-import { client } from './authlink-client';
-const props = defineProps<{ mode: Mode }>();
-const ticket = shallowRef<Ticket | null>(null);
-const busy = ref(false);
-const message = ref('');
-let key: string | null = null;
-function finish(text: string) { ticket.value = null; message.value = text; }
-function confirmed(result: Confirmation) {
-  finish(`${result.purpose === 'bind' ? '已绑定' : '已确认'}（请求 ${result.requestId}）`);
-}
-async function start() {
-  if (busy.value) return;
-  busy.value = true;
-  key ??= requestKey();
-  try {
-    ticket.value = await client.create(props.mode, { idempotencyKey: key });
-    key = null;
-  } catch { message.value = '请求未完成，可重试同一次创建。'; }
-  finally { busy.value = false; }
-}
-</script>
-
-<template>
-  <button v-if="!ticket" type="button" :disabled="busy" @click="start">开始验证</button>
-  <AuthLinkBind v-else-if="mode === 'bind'" :ticket="ticket" :client="client"
-    @confirmed="confirmed" @close="finish('已关闭')" @rejected="finish('手机已拒绝本次请求')"
-    @expired="finish('请求已过期，请重新发起')" @error="message = '网络异常，请重试。'" />
-  <AuthLinkConfirm v-else :ticket="ticket" :client="client"
-    @confirmed="confirmed" @close="finish('已关闭')" @rejected="finish('手机已拒绝本次请求')"
-    @expired="finish('请求已过期，请重新发起')" @error="message = '网络异常，请重试。'" />
-  <p role="status">{{ message }}</p>
-</template>
-```
-
-拒绝时返回 `{ status: 'rejected', code: 'REJECTED', requestId, purpose }`。`REJECTED` 是 SDK 业务状态码，不是 HTTP 状态码或授权凭证。组件自动关闭，不再显示“已拒绝 / 重新发起”面板，也不触发 `onClose`；提示和重新发起由接入网站在回调中决定。React / Vue 请在 `onRejected` / `@rejected` 中清空 ticket、卸载组件。无 UI 的 hook 仍保留 `snapshot.status === 'rejected'`，供自定义界面使用。
-
-此示例在过期后清空 ticket，用户可再次点击按钮发起请求。如果需要在过期弹窗内提供重新发起按钮，可自行传入 `onRefresh`，在回调中创建新请求并更新 ticket。`useAuthLink(() => options)` composable 与 React 的 `useAuthLink(options)` hook 可用于自定义界面，返回 `snapshot` 和 `retry`；Vue 的 snapshot 是浅 ref。
-
-### 选择弹窗样式
-
-初始化时通过 `variant` 选择样式，**不传时默认 A**。
-
-| 参数值 | 电脑端 | 手机端 |
-| --- | --- | --- |
-| `A`（默认） | 极简居中卡片、细线数字更新进度条 | 居中卡片 |
-| `B` | 二维码和核对码左右分栏 | 自动纵向排列 |
-| `C` | 紧凑卡片、底部取消入口 | 底部弹层，适配安全区域 |
-
-```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+。
-
-### 许可证
-
-MIT。完整许可文本见 `LICENSE`，打包包含的第三方库归属说明见 `THIRD_PARTY_NOTICES.md`。
-
-### Go Vue CMS: zh-CN
-
-本指南按实际 Go CMS + Vue 3 的接入顺序整理。下面使用可替换的示例域名，不依赖某台电脑的配置、测试账号、密码或租户密钥。网站负责登录、数据库和业务接口；Web SDK 负责展示和观察请求，Go SDK 负责后台调用与回执校验。
-
-#### 1. 区分三个来源并安装 SDK
-
-| 角色 | 示例来源 | 配置位置 |
-| --- | --- | --- |
-| Vue | `https://cms.example.com` | `apiOrigin` 指向下方的 Go 后台 |
-| Go CMS API | `https://cms-api.example.com` | `baseUrl=https://cms-api.example.com/api/authlink` |
-| AuthLink API | `https://auth.example.com` | Go SDK 的 `Origin`；浏览器的 `authLinkOrigin` |
-
-登记租户的站点 origin 是 Vue 网站来源；Go SDK 的 `Origin` 和凭据导出 JSON 中的 API origin 是 AuthLink API 来源。浏览器的 `baseUrl` 指向 Go 业务后台，不能指向 AuthLink 租户 API。公开运行配置只包含这三个 origin；`TenantID`、`APIKey` 保留在 Go 私密配置或环境变量中。
-
-```sh
-npm install @auth-link/web@latest vue
-# In your Go backend module, after unpacking the supplied Go SDK:
-go mod edit -replace=authlink.local/sdk=./third_party/authlink-go
-go mod edit -require=authlink.local/sdk@v0.0.0
-go mod tidy
-```
-
-Go SDK 当前随源码或官网的 Go SDK 源码包交付，保留 `third_party/authlink-go/go.mod`，导入 `authlink "authlink.local/sdk"`；这不是公共 `go get` 地址，也不是 npm 包内置的后台。用可信后台配置调用 `authlink.New(authlink.Config{Origin: authOrigin, TenantID: tenantID, APIKey: apiKey})`。
-
-#### 2. 先完成网站登录，再读取会话
-
-本站现有登录接口（参考 CMS 为 `POST /api/login`）验证用户后签发 HttpOnly、Secure 的 session Cookie。Vue 用 `credentials:'include'` 调用 Go 的 `GET /api/session`。已登录时返回 `authenticated:true` 与 `csrf`；未登录时先回到网站登录流程。
-
-`csrf` 是本 CMS 的响应字段名；SDK 配置项仍叫 `csrfToken`，写成 `csrfToken: () => session.value?.csrf ?? ''` 即可。SDK 不要求你的后台一定返回名为 `csrfToken` 的字段。令牌由 Go 为当前 session 生成并保存，浏览器只读取，不能用租户密钥或手机核对码代替。创建和结果查询均需验证 `X-CSRF-Token` 与同一 session 的值一致。
-
-Vue 与 API 使用同一 HTTPS 主域名下的两个子域名时，是跨 origin、同 site。参考 CMS 的 host-only Cookie 不设置 `Domain`，使用 `SameSite=Strict; Secure; HttpOnly; Path=/`；请求目标仍为 API 域名。真正跨 site 时还需按浏览器 Cookie 策略配置，不能只依靠 CORS。
-
-#### 3. Go 配置 CORS 与业务路由
-
-```http
-Access-Control-Allow-Origin: https://cms.example.com
-Access-Control-Allow-Credentials: true
-Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
-Access-Control-Allow-Headers: Content-Type, X-CSRF-Token, Idempotency-Key
-Vary: Origin
-Cache-Control: no-store
-```
-
-只为精确允许的 Vue origin 返回这些 CORS 头；允许来源的正常和错误响应都要携带。`OPTIONS` 先验证来源、方法和请求头，成功返回 204，不要求登录或 CSRF；随后实际请求才验证登录、来源、CSRF 和归属。不能用 `*` 或无条件反射来源。上面包含 CMS 草稿编辑所用的 PUT；只接入 SDK 的站点可按实际路由收窄。
-
-| 网站自己的路由 | 请求 | 返回 |
-| --- | --- | --- |
-| `GET /api/session` | — | `{authenticated:true, csrf:"…", subject:"…", username:"…"}`；未登录： `{authenticated:false}` |
-| `POST /api/authlink/requests` | `{purpose:"bind"}` 或 `{purpose:"confirm",postId,version}`; `Idempotency-Key` | 公开 `Ticket` |
-| `POST /api/authlink/requests/{id}/result` | `{}`；当前 session + CSRF | 待处理状态/displayCode 或已验证的 `confirmed` 回执 |
-| `POST /api/posts/{id}/publish` | `{requestId,version}`; 当前 session + CSRF | `{ok:true}` 校验已保存的确认记录和业务意图后返回 |
-
-上述路由由 Go CMS 实现，不是安装 Web SDK 后自动出现的接口。`postId` / `version` / `/publish` 是本例业务约定，不是 AuthLink 平台字段。
-
-#### 4. 创建前落库，消费后再返回 confirmed
-
-```text
-Vue → Go /api/session → current session + csrf
-Vue → Go /api/authlink/requests → Go SDK CreateRequest → public ticket
-Vue dialog → Go /api/authlink/requests/{id}/result → Status + Consume
-Go commits verified receipt → Vue confirmed event
-Vue → Go /api/posts/{id}/publish → validate saved intent/receipt → publish
-```
-
-Go 从可信 session 取稳定用户 ID，不能接受浏览器自报的 `externalUserId`。创建顺序：
-
-1. 校验 purpose、创建幂等键，以及文章归属和当前版本（若有）。
-2. 生成独立随机 state 和消费幂等键；把原创建键、CreateInput、当前用户/session 和业务意图落库，再向 AuthLink 发请求。网络结果不明时从数据库恢复同一记录、输入和键。
-3. 调用 `CreateRequest`，保存返回的 requestId、原始 expiresAt 与 ticket，去掉可选 qrSvg 后返回公开 ticket。对同一 session + 创建键加唯一约束，键复用到其他 purpose / 文章 / 版本时返回冲突。
-4. 结果接口按 requestId + 当前 session 加锁读取记录；已保存回执直接复用。用 `Status` 查询，只有 approved / consumed 才以保存的 `Expected` 和消费键调用 `Consume`。SDK 校验失败不能返回成功。
-5. 在事务里保存回执、用户/session 确认记录和审计，requestId / verificationId 建唯一约束，提交成功后才返回 `confirmed`。待处理状态保留原 displayCode，不跨数字期限缓存。
-
-下面是 SDK 调用层代码，**不是包含登录、数据库和路由的完整 HTTP 服务**；注释中的落库与事务必须由你的 Go 后台实现。初始化客户端、构造 Input、所有权检查及请求记录的读写按上述步骤完成。
-
-```go
-package cmsauth
-
-import (
-    "context"
-    authlink "authlink.local/sdk"
-)
-
-// Load this record from your database for the authenticated user/session.
-// Save Input (including State), CreateKey and ConsumeKey BEFORE calling Create.
-// Intent (post ID/version), ownership and unique constraints belong in your DB.
-type StoredRequest struct {
-    Input authlink.CreateInput
-    CreateKey string
-    ConsumeKey string
-    Ticket authlink.Ticket
-}
-
-// On network retries, load the SAME record; do not regenerate State or keys.
-func Create(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (authlink.Ticket, error) {
-    return sdk.CreateRequest(ctx, saved.Input, saved.CreateKey)
-}
-
-type PublicConfirmation struct {
-    Status string `json:"status"`
-    RequestID string `json:"requestId"`
-    VerificationID string `json:"verificationId"`
-    Purpose string `json:"purpose"`
-    ExpiresAt string `json:"expiresAt"`
-    AuthenticationPolicy string `json:"authenticationPolicy"`
-}
-
-// Caller checks session/CSRF/ownership, locks the saved record and first returns
-// any already-saved receipt. For a new confirmed result, caller must persist
-// the receipt and confirmation in a DB transaction BEFORE returning HTTP 200.
-func Poll(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (any, error) {
-    status, err := sdk.Status(ctx, saved.Ticket.RequestID)
-    if err != nil { return nil, err }
-    if status.Status != "approved" && status.Status != "consumed" { return status, nil }
-    result, err := sdk.Consume(ctx, authlink.Expected{
-        RequestID: saved.Ticket.RequestID,
-        ExternalUserID: saved.Input.ExternalUserID,
-        Purpose: saved.Input.Purpose,
-        State: saved.Input.State,
-        ExpiresAt: saved.Ticket.ExpiresAt,
-    }, saved.ConsumeKey)
-    if err != nil { return nil, err }
-    return PublicConfirmation{
-        Status: "confirmed", RequestID: result.RequestID,
-        VerificationID: result.VerificationID, Purpose: result.Purpose,
-        ExpiresAt: saved.Ticket.ExpiresAt, AuthenticationPolicy: result.AuthenticationPolicy,
-    }, nil
-}
-```
-
-#### 5. Vue 组件：稳定 ticket、按业务绑定创建、清理与重试
-
-完整文件也包含在包内 `examples/vue-cms.vue`。网站登录后挂载它，传入可信 `apiOrigin`、`authLinkOrigin`，可选传入后台加载的草稿 `post={id,version}`。父层用当前登录 session 的标识做组件 key，退出、重新登录或切换账号时先卸载旧组件并清空会话、旧 ticket、幂等键和待发布操作，再挂载新组件。不要只改用户名后继续使用旧 ticket。
+`examples/vue-client.vue` を AuthLinkPanel.vue としてコピーできます。ログイン後に現在の session.csrf を渡し、別 origin なら backendOrigin も渡します。ログアウト・アカウント/session 変更では旧コンポーネントをアンマウントして再作成します。token 更新時は csrf prop を更新します。
 
 ```vue
 <script setup lang="ts">
-import { markRaw, onMounted, onUnmounted, ref, shallowRef } from 'vue';
-import { createAuthLinkClient, requestKey, validateTicket } from '@auth-link/web';
+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';
 
-type Post = { id: string; version: number };
-type Publication = Post & { requestId: string };
-// Supply trusted deployment configuration. Mount after site login and remount
-// with :key="session.subject" after login, logout or account/session changes.
-const props = defineProps<{ apiOrigin: string; authLinkOrigin: string; post?: Post }>();
-const session = ref<{ authenticated: boolean; csrf?: string } | null>(null);
+// csrf comes from your website's current authenticated session.
+const props = defineProps<{ csrf: string; backendOrigin?: string }>();
 const ticket = shallowRef<Ticket | null>(null);
-const publication = shallowRef<Post | null>(null);
-const retryPublish = shallowRef<Publication | null>(null);
 const busy = ref(false), message = ref('');
-let creation: { signature: string; key: string } | null = null;
 const lifetime = new AbortController();
+let creationKey: string | null = null;
+let creationMode: Mode | null = null;
 const client = markRaw(createAuthLinkClient({
-  baseUrl: `${props.apiOrigin}/api/authlink`,
-  allowedBackendOrigins: [props.apiOrigin],
-  credentials: 'include',
-  csrfToken: () => session.value?.csrf ?? '',
-  authLinkOrigin: props.authLinkOrigin,
+  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',
 }));
-
-async function api(path: string, body?: unknown, headers: Record<string, string> = {}) {
-  const response = await fetch(`${props.apiOrigin}${path}`, {
-    method: body === undefined ? 'GET' : 'POST',
-    credentials: 'include', cache: 'no-store', redirect: 'error',
-    signal: lifetime.signal,
-    headers: body === undefined ? {} : {
-      'Content-Type': 'application/json', 'X-CSRF-Token': session.value?.csrf ?? '', ...headers,
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  const value = await response.json();
-  if (response.status === 401) {
-    session.value = null; closeTicket(); retryPublish.value = null; creation = null;
-  }
-  if (!response.ok) throw new Error(value.code ?? 'REQUEST_FAILED');
-  return value;
+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 closeTicket() { ticket.value = null; publication.value = null; }
 function showError(error: Error) { message.value = error.message; }
-function finish(text: string) { closeTicket(); message.value = text; }
-
-async function start(purpose: Mode, post?: Post) {
-  if (busy.value || ticket.value || !session.value?.authenticated) return;
-  busy.value = true; message.value = ''; retryPublish.value = null;
-  const intent = post ? { id: post.id, version: post.version } : null;
-  const signature = JSON.stringify({ purpose, postId: intent?.id, version: intent?.version });
+async function start(mode: Mode) {
+  if (busy.value || ticket.value) return;
+  busy.value = true; message.value = '';
   try {
-    if (creation?.signature !== signature) creation = { signature, key: requestKey() };
-    // SDK create() sends only {purpose}. Business fields use your own API.
-    const value = intent
-      ? validateTicket(await api('/api/authlink/requests', {
-          purpose, postId: intent.id, version: intent.version,
-        }, { 'Idempotency-Key': creation.key }), purpose, props.authLinkOrigin)
-      : await client.create(purpose, { idempotencyKey: creation.key, signal: lifetime.signal });
+    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;
-    publication.value = intent; ticket.value = value; creation = null;
+    ticket.value = value; creationKey = null;
   } catch (error) {
     if (!lifetime.signal.aborted) showError(error as Error);
-    // Retain creation.key for a retry of the SAME purpose/post/version.
+    // Keep the same key when retrying an uncertain creation of the same mode.
   } finally { busy.value = false; }
 }
-async function publish() {
-  const intent = retryPublish.value;
-  if (!intent || busy.value) return;
-  busy.value = true;
-  try {
-    await api(`/api/posts/${intent.id}/publish`, { version: intent.version, requestId: intent.requestId });
-    retryPublish.value = null; message.value = 'Published. Reload your posts from the backend.';
-  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
-  finally { busy.value = false; }
-}
-async function confirmed(result: Confirmation) {
-  const intent = publication.value;
-  closeTicket();
-  if (intent) { retryPublish.value = { ...intent, requestId: result.requestId }; await publish(); }
-  else message.value = 'Verified. Reload account status from the backend.';
-}
-onMounted(async () => {
-  try {
-    const value = await api('/api/session');
-    if (value.authenticated !== true || typeof value.csrf !== 'string' || !value.csrf) {
-      throw new Error('LOGIN_REQUIRED');
-    }
-    session.value = value;
-  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
-});
-onUnmounted(() => { lifetime.abort(); closeTicket(); creation = null; retryPublish.value = null; });
+onUnmounted(() => { lifetime.abort(); ticket.value = null; creationKey = null; });
 </script>
 
 <template>
-  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('bind')">Bind phone</button>
-  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm')">Confirm</button>
-  <button v-if="post" :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm', post)">Confirm publication</button>
-  <button v-if="retryPublish" :disabled="busy || !!ticket" @click="publish">Retry the same publication</button>
+  <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 a new request')" @error="showError" />
+    @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 a new request')" @error="showError" />
+    @expired="finish('Expired; start again')" @error="showError" />
   <p role="status">{{ message }}</p>
 </template>
 ```
 
-普通绑定/确认使用 `client.create(purpose, {idempotencyKey})`。该方法只发送 purpose，**不能传入 postId/version 扩展请求体**。确认发布通过自己的 fetch 发送这些业务字段，再用 `validateTicket(response, 'confirm', authLinkOrigin)` 校验；后续弹窗查询仍复用官方 client。
-
-同一次创建失败保留同一个键；用途或文章版本改变才换新键。`shallowRef` 保存 ticket，`markRaw` 保存客户端。组件挂载只打开和观察已有请求；不在 mounted/watch 中创建请求。关闭、拒绝和过期清空 ticket；网络错误保留弹窗，允许重试原请求。确认成功先清空 ticket，再调用独立业务接口；失败保留同一个 requestId / 文章 / 版本用于重试，先从后台确认真实状态后再刷新页面。上例省略网站自己的登录表单、文章列表和错误码中文映射。
-
-#### 6. 发布接口必须再做后台检查
-
-`confirmed` 回调只触发界面更新与下一次 API 请求，不是放行凭据。Go 的发布事务必须验证当前 session 对应的已落库回执，purpose=confirm、意图=publish、同一 postId、同一 version、文章归属和草稿状态，以及首次应用时尚未过期。成功时更新文章并标记请求 applied；重试已应用的同一操作返回原成功，不重复发布或写审计。请求不能用于另一文章或新版本，修改内容后须重新确认。前端不把文章内容、action 或 transactionHash 塞入 AuthLink 消费回执。
-
-#### 验收顺序
-
-登录 → 读取 session → 查询后台真实账号状态（参考 CMS 通过 overview 调用 Go SDK `AccountStatus`）→ 未绑定时 bind → 手机扫码批准 → 后台消费并刷新账号状态 → 保存草稿 → 按 postId/version confirm → 手机批准 → 结果消费落库 → 独立发布接口 → 重复发布/错误版本/拒绝/过期验证。真实设备验收仍由用户在手机上完成；本地编译和模拟 HTTP 测试不能代替这一步。
-
----
-
-## 日本語
-
-**AuthLink のスマートフォン登録とアプリでの確認**を Web サイトに組み込む React / Vue コンポーネントです。登録用 QR コード、同期する 6 桁の照合コード、カウントダウン、確認結果を表示します。特定のサイト基盤には依存しません。
-
-### Go + Vue の接続手順
-
-Go + Vue の実際の接続手順は [ログイン、端末登録、確認後の公開](#go-vue-cms-ja)、完全なコンポーネントは `examples/vue-cms.vue` を参照してください。
-
-サイトのログイン → Go `/api/session` の authenticated/csrf → `csrfToken: () => session.csrf` で別 origin のクライアント設定 → bind/confirm 作成 → Go で消費・検証・DB コミット → ダイアログを閉じる → 独立した業務 API で保存済み確認結果を再検証して公開、という順序です。baseUrl は Go、authLinkOrigin は AuthLink を指し、テナントキーは Go に保持します。記事/版付き要求は独自 fetch と validateTicket を使い、SDK create は purpose のみ送ります。
-
-### 主な機能
-
-- ブラウザー内で生成するスマートフォン登録用 QR コード。
-- アプリと同期し、30 秒ごとに更新される照合コード。
-- 承認・拒否・期限切れ・エラーのイベント。
-- React コンポーネントと hook、Vue コンポーネントと composable、フレームワーク非依存の API。
-- **簡体字中国語を既定とする 13 言語**。コンポーネントごとに指定可能。
-- TypeScript、独立した CSS、任意の React / Vue peer dependency。
-
-本パッケージはブラウザー用の接続ライブラリです。サイトのバックエンド、AuthLink サービス、モバイルアプリと併用します。AuthLink はアプリ内の承認と元の端末のハードウェア証明を検証します。システムのパスキー、指紋認証、画面ロックは要求しません。
-
-### インストール
-
-```sh
-npm install @auth-link/web
-```
-
-対応環境：React 18.2+ / 19、Vue 3.3+、TypeScript、ESM。利用するフレームワークだけをインストールしてください。ツール環境には Node 22.13+ が必要です。
-
-### 接続の流れ
-
-1. サイトのバックエンドに AuthLink のテナント資格情報を設定します。
-2. 下記の業務バックエンド（同一オリジンまたは明示的に許可した別オリジン）の作成・結果取得 API を実装します。
-3. ユーザー操作でリクエストを作成し、取得した ticket をコンポーネントに渡します。
-4. バックエンドが結果を検証・消費した後に確認完了を返します。
-
-ブラウザーからこのライブラリを呼び出せますが、テナント API キーと結果の消費処理は必ずサーバー側に置きます。標準クライアントは既定の同一オリジンと、明示的に許可した別オリジンに対応します。独自の通信方式では `AuthLinkClient` を実装できますが、資格情報と検証をブラウザーに移さないでください。
-
-### クライアント作成（既定の同一オリジン Cookie モード）
-
-`readCsrfTokenFromYourCms` は SDK のエクスポートではなく、接続先サイトで実装する関数です。現在のログインセッションに対してバックエンドが発行した CSRF token を読み取ります。CMS は必須ではありません。ブラウザーで値を生成したり、AuthLink の API キーを返したりしないでください。
-
-既存フレームワークの CSRF 機構を優先してください。独自に実装する場合は、サーバーで暗号学的乱数（Node の `randomBytes(32).toString('base64url')` など）を生成し、セッションに保存して HTML 属性をエスケープしたうえでページに埋め込みます。下記の `{{ csrfToken }}` はサーバーテンプレートの変数です。このページを公開キャッシュしないでください。
-
-```html
-<meta name="csrf-token" content="{{ csrfToken }}">
-```
-
-SDK は各リクエストで token を読み取り、`X-CSRF-Token` と同一オリジンのセッション cookie を送信します。作成 API と結果 API の両方で、バックエンドが同じセッションの token と照合し、欠落・不一致や不正なリクエスト元を拒否する必要があります。ログインやセッション変更後は最新 token を取得してください。SPA ではサイト独自の同一オリジン初期化 API から取得する方法も使えます。別のヘッダー名を使うフレームワークでは`csrfHeaderName` または独自 `AuthLinkClient` で適合します。
-
-`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,
-  // Replace this example with the configured AuthLink service origin.
-  authLinkOrigin: 'https://auth.example.com',
-});
-```
-
-`https://auth.example.com` は実際の AuthLink オリジンに置き換えてください。リクエストは下記の React 例のようにユーザー操作で作成します。
-
-### フロントエンドとバックエンドの別オリジン対応（0.0.2 以降）
-
-既定は同一オリジンの `/api/authlink` です。別オリジンの業務 API に直接接続するには完全な `baseUrl` と `allowedBackendOrigins` を指定します。例：フロントエンド `https://www.example.com`、バックエンド `https://api.example.com`。サブドメインやポートが異なる場合も別オリジンです。許可リストにはパス、ワイルドカード、ユーザー名・パスワードを含めず、信頼する固定設定を使います。HTTPS が必須で、開発用 HTTP loopback（localhost / 127.0.0.1 / [::1]）のみ例外です。
-
-SDK は認証情報を読む前に接続先を検証し、リダイレクトを拒否します。`authLinkOrigin` は QR 内の AuthLink サービスオリジンの検証用で、業務 API の許可リストとは別です。
-
-#### 別オリジンの Cookie / session
-
-汎用例の JSON 名は csrfToken ですが、Go CMS の実際の応答は `{ authenticated: true, csrf: '…' }` です。session.csrf を SDK の csrfToken コールバックに渡せばよく、バックエンドのフィールド名を変更する必要はありません。
-
-下記の `GET /api/session` はサイトで実装する例示 API で、SDK が提供する API ではありません。ログイン session の `{ "csrfToken": "現在のtoken" }` を返し、`Cache-Control: no-store` と CORS を設定します。既存サイトの API パスに適合してください。
-
-```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` を既存コンポーネントに渡します。CSRF token 更新時は `updateCsrfToken(newToken)` を呼びます。ログアウトやアカウント切替時は古いダイアログを閉じ、状態を再初期化します。別オリジン Cookie には `credentials: 'include'` が必要ですが、SameSite、Secure、domain/path、ブラウザーの第三者 Cookie 制限も適用されます。別オリジンと cross-site は同じではありません。cross-site Cookie には通常 `SameSite=None; Secure` が必要で、ブラウザーによっては引き続き拒否されます。
-
-#### Bearer token / JWT
-
-サイトの既存ログイン状態を渡してください。ログイン・更新処理で `auth.accessToken` を更新すると、SDK は作成・ポーリングのたびに最新値を読み取ります。
-
-```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,
-  });
-}
-```
-
-これはサイト利用者のログイン token であり、AuthLink のテナント API キーではありません。SDK が `Authorization: Bearer ...` を付加します。`accessToken` 指定時は既定で `credentials: 'omit'` となり、Cookie にフォールバックせず Bearer のみで認証するバックエンドでは CSRF を省略できます。`include` / `same-origin` を明示して Cookie を併用する場合は CSRF の提供・検証も必要です。
-
-#### バックエンドの CORS
-
-`OPTIONS` プリフライトを処理し、実リクエスト・エラー応答・session 初期化 API にも必要な 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 の接頭辞、既定 `/api/authlink`；別オリジン時は完全 URL |
-| `allowedBackendOrigins` | 追加許可する正確な業務 API オリジンの配列 |
-| `credentials` | 既定 `same-origin`、`accessToken` 指定時 `omit`；別オリジン Cookie は `include` |
-| `csrfToken` | リクエストごとの同期/非同期取得関数；Cookie モードは必須 |
-| `csrfHeaderName` | 既定 `X-CSRF-Token`、フレームワークに合わせて変更可能 |
-| `accessToken` | サイトのログイン token 取得関数；`Bearer ` 接頭辞は付けない |
-| `headers` | 追加 `HeadersInit`、またはそれを返す同期/非同期関数 |
-| `authLinkOrigin` | QR 内の信頼するサービスオリジン。業務 API オリジンとは別 |
-| `fetch` | 任意の fetch 実装；接続先検証は維持 |
-
-追加ヘッダーは SDK 管理の `Accept`、`Content-Type`、`Authorization`、`Idempotency-Key`、設定済み CSRF ヘッダーを上書きできません（`RESERVED_HEADER`）。`accessToken` と `csrfHeaderName` を使用してください。設定型 `ClientOptions` はルートエントリーからインポートできます。
-
-未許可オリジンは `BACKEND_ORIGIN_NOT_ALLOWED`（旧 `CMS_ORIGIN_REQUIRED` に代わる）、不正な許可設定/URL は `INVALID_BACKEND_ORIGIN` / `INVALID_BASE_URL`、token 不足は `ACCESS_TOKEN_REQUIRED` / `CSRF_REQUIRED` となります。非同期の認証情報取得にも取消しと 10 秒タイムアウトが適用されます。CORS の詳細な失敗理由は開発者ツールで確認してください。SDK では通常 `NETWORK_ERROR` になります。
+ticket は shallowRef、client は markRaw で保持します。同じ用途の作成失敗ではキーを保持し、成功後に消去します。mounted/watch で要求を作りません。確認・拒否・期限切れ・閉じる操作で ticket を消去します。通信エラーでは表示を維持して同じ要求を再試行します。必要なアカウント状態は自サイトの API から再取得します。
 
-### 関数でダイアログを開く（React / Vue / JavaScript）
-
-```ts
-import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import { client } from './authlink-client';
-import '@auth-link/web/styles.css';
+### 4. React
 
-const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
-const modal = openAuthLinkConfirm({
-  ticket, client, locale: 'ja',
-  onConfirmed: result => console.log(result.requestId),
-  onClose: () => console.log('Closed'),
-});
-// 登録: openAuthLinkBind({ ticket: bindingTicket, client })
-// modal.close(); modal.setLocale('en');
-```
-
-React / Vue コンポーネントもマウント時にダイアログを開きます。React の onClose、Vue の @close で ticket を消去してアンマウントしてください。SSR はダイアログも通信も生成しません。スマートフォンの画面幅、スクロール、閉じるボタン、Escape に対応し、ネイティブ dialog.showModal() が必要です。body 直下に表示するため、テーマ変数は :root または .authlink-dialog に設定します。
-
-閉じてもサーバーのリクエストを拒否・取消しません。元の有効期限は維持されます。承認・拒否時は自動で閉じ、onConfirmed または onRejected を通知します。ユーザー操作の onClose は通知しません。関数で開いた場合はページ破棄時に modal.destroy() を呼んで通信と UI を解除してください。destroy() は onClose を通知しません。modal.setLocale() はリクエストを作り直さずに言語を切り替えます。
-
-
-### React
-
-`showBound(requestId)` はサイトの表示更新用関数です。メッセージを更新し、ticket を消去してダイアログをアンマウントします。下記には拒否・期限切れ・閉じる処理も含まれます。`<AuthLinkPanel mode="bind" />` または `<AuthLinkPanel mode="confirm" />` で使います。
+上記で初期化した安定した client と mode=bind/confirm を渡します。ログアウトやアカウント/session 変更ではアンマウントします。
 
 ```tsx
 "use client";
-import { useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { requestKey } from '@auth-link/web';
-import type { Mode, Ticket } from '@auth-link/web';
+import type { AuthLinkClient, Mode, Ticket } from '@auth-link/web';
 import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-import { client } from './authlink-client';
+// Import '@auth-link/web/styles.css' once in your application entry.
 
-export function AuthLinkPanel({ mode }: { mode: Mode }) {
+export function AuthLinkPanel({ client, mode }: { client: AuthLinkClient; mode: Mode }) {
   const [ticket, setTicket] = useState<Ticket | null>(null);
   const [busy, setBusy] = useState(false);
   const [message, setMessage] = useState('');
-  const key = useRef<string | null>(null);
-  const creating = useRef(false);
-  function finish(message: string) {
-    setTicket(null);
-    setMessage(message);
-  }
-  function showBound(requestId: string) {
-    // UI feedback only. The backend has already verified and saved the binding.
-    finish(`Phone bound (request ${requestId})`);
-  }
-  function showConfirmed(requestId: string) {
-    finish(`Confirmed (request ${requestId})`);
-  }
-  const start = async () => {
-    if (creating.current || ticket) return;
-    creating.current = true;
-    setBusy(true);
-    setMessage('');
+  const creation = useRef<{ mode: Mode; key: string } | null>(null);
+  const inFlight = useRef(false);
+  const controller = useRef<AbortController | null>(null);
+  useEffect(() => () => { controller.current?.abort(); }, []);
+  function finish(text: string) { setTicket(null); setMessage(text); }
+  async function start() {
+    if (inFlight.current || ticket) return;
+    inFlight.current = true; setBusy(true); setMessage('');
+    const attempt = new AbortController(); controller.current = attempt;
     try {
-      key.current ??= requestKey();
-      setTicket(await client.create(mode, { idempotencyKey: key.current }));
-      key.current = null;
-    } catch { setMessage('Request failed; retry the same creation.'); }
-    finally { creating.current = false; setBusy(false); }
-  };
+      if (creation.current?.mode !== mode) creation.current = { mode, key: requestKey() };
+      const value = await client.create(mode, { idempotencyKey: creation.current.key, signal: attempt.signal });
+      if (attempt.signal.aborted) return;
+      setTicket(value); creation.current = null;
+    } catch (error) { if (!attempt.signal.aborted) setMessage((error as Error).message); }
+    finally {
+      inFlight.current = false;
+      if (!attempt.signal.aborted) setBusy(false);
+    }
+  }
   const Component = mode === 'bind' ? AuthLinkBind : AuthLinkConfirm;
   return <>
-    {!ticket && <button type="button" disabled={busy} onClick={() => void start()}>Start verification</button>}
-    {ticket && <Component ticket={ticket} client={client}
-      onConfirmed={result => result.purpose === 'bind' ? showBound(result.requestId) : showConfirmed(result.requestId)}
-      onClose={() => finish('Closed')}
-      onRejected={() => finish('Request rejected on the phone')}
-      onExpired={() => finish('Request expired; start again')}
+    {!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>
   </>;
 }
 ```
 
-バックエンドは結果を検証・消費・保存してから `confirmed` を返します。`showBound` は権限付与や紐付け保存を行いません。通知、サイトのアカウント状態 API の再取得、管理ページへの移動などに置き換えられます。ページ再読み込み後はサーバーから状態を取得し、コールバックや localStorage を認可に使わないでください。作成失敗時には同じ冪等キーを再利用します。
-
-
-`locale` を省略すると簡体字中国語です。日本語は `locale="ja"`、簡体字中国語は `locale="zh-CN"` を指定します。client と ticket はレンダー間で安定したオブジェクトにしてください。React エントリーは `"use client"` を保持し、SSR ではリクエストを作成しません。
-
-### Vue
-
-```vue
-<script setup lang="ts">
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
-import type { Ticket, Confirmation } from '@auth-link/web';
-import { client } from './authlink-client';
-
-defineProps<{ ticket: Ticket }>();
-function confirmed(result: Confirmation) {
-  console.log('Confirmed request:', result.requestId);
-}
-</script>
-
-<template>
-  <AuthLinkBind v-if="ticket.purpose === 'bind'" :ticket="ticket" :client="client"
-    @confirmed="confirmed" />
-  <AuthLinkConfirm v-else :ticket="ticket" :client="client" locale="ja"
-    @confirmed="confirmed" />
-</template>
-```
-
-`:locale="selectedLanguage"` で表示言語を切り替えられます。言語切り替えによって新しい認証リクエストは作成されません。
-
-### レイアウトの選択
-
-初期化時の `variant` で選択します。省略時は **A** です。
-
-| 値 | デスクトップ | モバイル |
-| --- | --- | --- |
-| `A`（既定） | ミニマルなカードと細いコード更新バー | 中央のカード |
-| `B` | QR と照合コードの二列表示 | 縦並び |
-| `C` | コンパクトなカードとキャンセル操作 | セーフエリア対応のボトムシート |
+### 5. 通常の JavaScript / 直接表示
 
 ```ts
-openAuthLinkBind({ ticket, client }); // A、既定言語は簡体字中国語
-openAuthLinkConfirm({ ticket, client, variant: 'B' });
-// modal.setVariant('C');
-```
-
-```tsx
-<AuthLinkBind ticket={ticket} client={client} variant="C" />
-```
+import { openAuthLinkConfirm, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
 
-```vue
-<AuthLinkConfirm :ticket="ticket" :client="client" variant="B" />
+// Inside a click handler; client is the stable instance created above.
+const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
+const modal = openAuthLinkConfirm({
+  ticket, client, variant: 'B', locale: 'zh-CN',
+  onConfirmed: result => console.log(result.requestId),
+  onRejected: result => console.log(result.code),
+  onExpired: () => console.log('Expired'),
+  onError: error => console.log(error.message),
+  onClose: () => console.log('Closed'),
+});
+// Route/component cleanup: modal.destroy();
+// Optional: modal.close(); modal.retry(); modal.setLocale('ja'); modal.setVariant('C');
 ```
 
-すべてのレイアウトで細い進捗バーと「照合コードは30秒ごとに自動更新」を表示します。通常は「スマートフォンの確認待ち」を表示し、残り30秒になったときだけオレンジ色の期限警告と 00:29 形式に切り替わります。コード変更時の短いフェードはモーション低減設定に従い、リクエスト期限は延長されません。
-
-React / Vue では表示中にも変更でき、リクエストやポーリングは再作成されません。未対応の値は A に戻ります。B / C のキャンセル操作は閉じるアイコンと同じく表示の監視を停止し、サーバーのリクエストは拒否しません。確認成功時は自動で閉じます。閉じる操作のタッチ領域は 44px で、キーボードのフォーカス表示も維持します。
+登録時は client.create('bind', ...) と openAuthLinkBind(...) を使います。確認・拒否は自動で閉じてから通知し、onClose は発火しません。閉じる操作は監視を停止します。画面を離れる際は destroy を呼びます。同じ要求の成功はインスタンス内で一度だけ通知します。イベントは表示更新用で、保護操作は自サイトの業務 API を呼びます。
 
-### コンポーネントの設定
+### 6. フロントエンドが使う API の形式
 
-| 設定 | 型 | 説明 |
+| 自サイトのルート | 送信 | 受信 |
 | --- | --- | --- |
-| `ticket` | `Ticket`、必須 | バックエンドで作成したリクエスト |
-| `client` | `AuthLinkClient`、必須 | バックエンドの結果を取得するクライアント |
-| `locale` | `Locale` | 既定は `zh-CN` |
-| `variant` | `DialogVariant` | `A`（既定）、`B`、`C` |
-| `showQr` | `boolean` | 確認画面にも QR を表示。登録画面では常に表示 |
-| `intervalMs` | `number` | 250～10000 ミリ秒。既定は 1500 ミリ秒 |
-| `onRefresh` | `() => void` | 期限切れ後、新規作成して ticket を更新する処理 |
-
-| React コールバック / Vue イベント | 引数 | 意味 |
-| --- | --- | --- |
-| `onConfirmed` / `confirmed` | `Confirmation` | バックエンドによる検証と消費が完了 |
-| `onRejected` / `rejected` | `Rejection` | 拒否時はダイアログを自動で閉じる |
-| `onExpired` / `expired` | なし | 有効期限切れ |
-| `onError` / `error` | `Error` | 通信・応答検証・コールバックのエラー |
-
-拒否時は `{ status: 'rejected', code: 'REJECTED', requestId, purpose }` を返します。`REJECTED` は SDK の業務ステータスで、HTTP ステータスや承認証明ではありません。拒否・再試行画面は表示せず、`onClose` も通知しません。メッセージや新規作成はサイト側で処理してください。React / Vue では `onRejected` / `@rejected` で ticket を解除してコンポーネントを破棄します。ヘッドレス hook の `snapshot.status` は `rejected` のままです。
-
-独自 UI には React の `useAuthLink(options)`、Vue の `useAuthLink(() => options)` を利用できます。返される値は `snapshot` と `retry` です。Vue の snapshot は shallow ref です。retry は既存リクエストを再開し、onRefresh はサイト側のコードで新規作成します。
+| POST /api/authlink/requests | purpose=bind/confirm、Idempotency-Key | Ticket |
+| POST /api/authlink/requests/{requestId}/result | 空オブジェクト、現在のログイン情報 | Result（自動監視） |
 
-### バックエンド API
+Cookie モードでは両方に現在の CSRF ヘッダーを送ります。Ticket は requestId、purpose、qr、pairingCode、expiresAt、confirm 時は displayCode も必要です。Ticket/Result/Confirmation 型を import し、QR や数字を自作しません。confirmed のみ成功イベントを発火します。new/pending/approved/consumed は待機、rejected/expired は対応イベントです。
 
-既定の接頭辞は `/api/authlink` です。両 API で Cookie + 設定した CSRF ヘッダー、または Bearer token による本人確認とリクエスト所有者を検証してください。作成時は `Idempotency-Key` も送信されます。サイトのユーザー ID は検証済みセッション/token から決定します。
+create() は purpose のみ送ります。業務固有項目が必要なら独自 fetch で作成し、validateTicket で検証して同じコンポーネントへ渡します。post/session/backendOrigin は既存のフロントエンド状態で、同じ入力の再試行では同じキーを保持します。
 
 ```ts
-import type { Ticket, Result } from '@auth-link/web';
-
-// POST /api/authlink/requests
-// Body: { purpose: 'bind' | 'confirm' }
-// Response: Ticket
-
-// POST /api/authlink/requests/{requestId}/result
-// Body: {}
-// Response: Result
-```
-
-```json
-{
-  "status": "confirmed",
-  "requestId": "<request-id>",
-  "verificationId": "<verification-id>",
-  "purpose": "confirm",
-  "authenticationPolicy": "device-presence.v1",
-  "expiresAt": "<same-expiry-as-ticket>"
-}
+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.
 ```
 
-作成 API は AuthLink の公開 ticket（`requestId`、`purpose`、`qr`、`pairingCode`、`expiresAt`、現在の `displayCode`）を返します。displayCode は `value`、`serverTime`、`validUntil`、`periodSeconds: 30` を持ちます。確認用 ticket には displayCode が必要です。
-
-結果 API は未完了状態と最新の表示コードを返します。`new` / `pending` / `approved` / `consumed` だけでは成功イベントは発火しません。`confirmed` を返す前に、バックエンドは保存した state と消費用冪等キーで AuthLink の結果を消費し、完全な受領情報を検証して正しいセッションに記録します。requestId / verificationId による永続的な冪等処理が必要です。
-
-### 対応言語
-
-| 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 |
-
-未指定・未対応の言語コードは簡体字中国語にフォールバックします。ルート要素には `lang` が設定されます。ルートエントリーの `supportedLocales` で一覧を取得できます。言語変更は表示文言だけに作用し、数字やリクエストは変更しません。ドキュメントは英語・中国語・日本語で提供します。
-
-### スタイルとエントリー
-
-`@auth-link/web/styles.css` を明示的に読み込みます。ダイアログは `document.body` に追加されるため、`:root` または `.authlink-dialog` で `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted` を上書きします。クラス名の接頭辞は `authlink-` です。
-
-React / Vue はダイアログの `className` に対応します。Vue は文字列・配列・オブジェクト形式の `class` も受け取り、`className` と結合します。再作成ボタンは親が渡した最新の `onRefresh` を呼び出します。
+### 7. 設定・イベント・表示
 
-| エントリー | 内容 |
-| --- | --- |
-| `@auth-link/web` | クライアント、冪等キー、対応言語、型、基本 API |
-| `@auth-link/web/react` | React コンポーネントと hook |
-| `@auth-link/web/vue` | Vue コンポーネントと composable |
-| `@auth-link/web/styles.css` | スタイル |
-
-### セキュリティと有効期限
-
-- 数字はアプリとの目視照合用です。数字だけで認証や承認はできません。
-- ブラウザーに生成 seed、端末秘密鍵、テナント秘密情報を渡しません。
-- リクエストは最大 120 秒。コード更新で期限は延長されません。サービスとアプリはモバイルプロトコル 7 に対応する必要があります。
-- サーバー時刻と単調増加時計で残り時間を計算し、通信が止まっても期限切れの数字は隠します。更新境界で短い待ち時間が生じる場合があります。
-- アンマウントや ticket 変更で監視を中止します。インスタンス内のイベント重複防止とは別に、バックエンドで永続的な冪等処理が必要です。
-- フロントエンドのイベントは UI 更新用です。保護 API はバックエンドの信頼できる記録で判断します。
-- QR はローカル生成し、バックエンドの SVG を挿入しません。CSP は `img-src 'self' data:` を許可してください。
-
-### ライセンス
-
-MIT。ライセンス全文は `LICENSE`、同梱ライブラリの帰属表示は `THIRD_PARTY_NOTICES.md` を参照してください。
-
-### Go Vue CMS: ja
-
-実際の Go CMS + Vue 3 の接続順序を示します。例のドメインは置き換え用で、ローカル設定・テスト用パスワード・テナント資格情報は含めません。ログイン、DB、業務 API はサイト側で実装し、Web SDK は表示と監視、Go SDK は AuthLink 呼び出しと応答検証を担当します。
-
-#### 1. 3 つの origin と SDK
-
-| 役割 | 例 | 設定 |
+| prop | 型 | 用途 |
 | --- | --- | --- |
-| Vue | `https://cms.example.com` | `apiOrigin` は下記 Go バックエンド |
-| Go CMS API | `https://cms-api.example.com` | `baseUrl=https://cms-api.example.com/api/authlink` |
-| AuthLink API | `https://auth.example.com` | Go SDK の `Origin`；ブラウザーの `authLinkOrigin` |
-
-テナントに登録するサイト origin は Vue の origin です。Go SDK の Origin と資格情報 JSON の API origin は AuthLink API を指します。ブラウザーの baseUrl は Go の業務 API です。TenantID/APIKey はバックエンドの非公開設定にのみ保存します。
-
-```sh
-npm install @auth-link/web@latest vue
-# In your Go backend module, after unpacking the supplied Go SDK:
-go mod edit -replace=authlink.local/sdk=./third_party/authlink-go
-go mod edit -require=authlink.local/sdk@v0.0.0
-go mod tidy
-```
-
-Go SDK はソースまたは公式サイトの Go SDK アーカイブとして取得します。公開 Go module や npm 同梱サーバーではありません。SDK 自身の go.mod を保持し、`authlink "authlink.local/sdk"` を import します。信頼できる設定から `authlink.New(authlink.Config{Origin: authOrigin, TenantID: tenantID, APIKey: apiKey})` で初期化します。
-
-#### 2. サイトのログインと session
-
-サイトのログイン API（参照 CMS は POST /api/login）が Secure・HttpOnly の session Cookie を発行します。Vue は credentials=include で GET /api/session を読み、authenticated=true と csrf を確認してから要求を作成します。未ログインならサイト自身のログインへ戻します。
-
-この CMS の JSON フィールド名は **csrf**、SDK オプション名は **csrfToken** です。`csrfToken: () => session.value?.csrf ?? ''` で対応します。JSON の名前を SDK に合わせる必要はありません。Go が session ごとに生成・保存し、作成と結果照会の両方で X-CSRF-Token を検証します。テナントキーや照合数字を代用しません。
-
-同じサイトの HTTPS サブドメイン同士は別 origin・同 site です。参照 API の Cookie は Domain を指定しない host-only、SameSite=Strict; Secure; HttpOnly; Path=/ です。別 site の場合は CORS に加えてブラウザーの Cookie 制限も考慮します。
-
-#### 3. Go の CORS と業務ルート
-
-```http
-Access-Control-Allow-Origin: https://cms.example.com
-Access-Control-Allow-Credentials: true
-Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
-Access-Control-Allow-Headers: Content-Type, X-CSRF-Token, Idempotency-Key
-Vary: Origin
-Cache-Control: no-store
-```
-
-正確に許可した Vue origin にだけ返し、その origin のエラー応答にも付与します。OPTIONS は origin・method・headers を検証して 204 を返し、ログインや CSRF は要求しません。実リクエストでログイン、CSRF、所有者を検証します。任意 origin の反射や * は使いません。PUT は CMS の下書き編集用なので必要なルートに合わせて限定できます。
-
-| サイト自身のルート | 入力 | 出力 |
+| `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 イベント | 値 | 動作 |
 | --- | --- | --- |
-| `GET /api/session` | — | `{authenticated:true, csrf:"…", subject:"…", username:"…"}`；未ログイン： `{authenticated:false}` |
-| `POST /api/authlink/requests` | `{purpose:"bind"}` または `{purpose:"confirm",postId,version}`; `Idempotency-Key` | 公開 `Ticket` |
-| `POST /api/authlink/requests/{id}/result` | `{}`；現在の session + CSRF | 待機状態/displayCode または検証済み `confirmed` |
-| `POST /api/posts/{id}/publish` | `{requestId,version}`; 現在の session + CSRF | `{ok:true}` 保存済み確認結果と業務意図の検証後 |
+| `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 |
 
-これらのルートは Go CMS が実装します。postId/version と公開ルートはこの業務の契約で、AuthLink のプロトコル項目ではありません。
+A は中央カード（既定）、B はデスクトップ分割・狭い画面で縦配置、C は小型・モバイルで下部シートです。locale/variant の変更では要求を作り直しません。ネイティブ dialog.showModal() 対応ブラウザーが必要です。
 
-#### 4. 作成前に保存し、検証のコミット後に confirmed
+CSS を明示 import します。ダイアログは document.body 配下なので :root または .authlink-dialog で --authlink-foreground、--authlink-background、--authlink-accent、--authlink-muted を指定します。Vue class は文字列・配列・オブジェクトを className と併用できます。SSR はダイアログや要求を作りません。
 
-```text
-Vue → Go /api/session → current session + csrf
-Vue → Go /api/authlink/requests → Go SDK CreateRequest → public ticket
-Vue dialog → Go /api/authlink/requests/{id}/result → Status + Consume
-Go commits verified receipt → Vue confirmed event
-Vue → Go /api/posts/{id}/publish → validate saved intent/receipt → publish
-```
-
-安定したユーザー ID は認証済み session から取得します。用途、作成キー、記事の所有者と版を検証し、state と消費キーを別々に生成します。上流通信の前に CreateInput、ブラウザーの作成キー、ユーザー/session、記事公開の意図を保存します。通信失敗時は同一レコード・入力・キーを再利用します。session + 作成キーを一意にし、異なる用途・記事・版への再利用を拒否します。
-
-ticket、requestId、元の expiresAt を保存し、任意の qrSvg を除いて公開 ticket を返します。結果 API は現在の session が所有する記録をロックし、保存済み確認結果があれば再利用します。Status が approved/consumed のときだけ、DB の値から Expected を組み立て Consume を実行します。検証済み確認結果、session の確認記録、監査を requestId/verificationId の一意制約付きトランザクションで保存し、コミット後に confirmed を返します。待機中は displayCode を有効期限を越えてキャッシュしません。
-
-以下は SDK 呼び出し層であり、完全な HTTP サーバーではありません。DB、トランザクション、所有者検証は説明とコメントに従ってサイト側で実装します。
-
-```go
-package cmsauth
-
-import (
-    "context"
-    authlink "authlink.local/sdk"
-)
+言語：`zh-CN` (default), `zh-TW`, `en`, `ja`, `bn`, `es`, `fil`, `hi`, `id`, `ms`, `pt`, `th`, `vi`。未指定・未対応値は簡体字中国語へフォールバックします。supportedLocales で一覧を取得できます。
 
-// Load this record from your database for the authenticated user/session.
-// Save Input (including State), CreateKey and ConsumeKey BEFORE calling Create.
-// Intent (post ID/version), ownership and unique constraints belong in your DB.
-type StoredRequest struct {
-    Input authlink.CreateInput
-    CreateKey string
-    ConsumeKey string
-    Ticket authlink.Ticket
-}
-
-// On network retries, load the SAME record; do not regenerate State or keys.
-func Create(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (authlink.Ticket, error) {
-    return sdk.CreateRequest(ctx, saved.Input, saved.CreateKey)
-}
+### 8. 通信設定とエラー確認
 
-type PublicConfirmation struct {
-    Status string `json:"status"`
-    RequestID string `json:"requestId"`
-    VerificationID string `json:"verificationId"`
-    Purpose string `json:"purpose"`
-    ExpiresAt string `json:"expiresAt"`
-    AuthenticationPolicy string `json:"authenticationPolicy"`
-}
-
-// Caller checks session/CSRF/ownership, locks the saved record and first returns
-// any already-saved receipt. For a new confirmed result, caller must persist
-// the receipt and confirmation in a DB transaction BEFORE returning HTTP 200.
-func Poll(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (any, error) {
-    status, err := sdk.Status(ctx, saved.Ticket.RequestID)
-    if err != nil { return nil, err }
-    if status.Status != "approved" && status.Status != "consumed" { return status, nil }
-    result, err := sdk.Consume(ctx, authlink.Expected{
-        RequestID: saved.Ticket.RequestID,
-        ExternalUserID: saved.Input.ExternalUserID,
-        Purpose: saved.Input.Purpose,
-        State: saved.Input.State,
-        ExpiresAt: saved.Ticket.ExpiresAt,
-    }, saved.ConsumeKey)
-    if err != nil { return nil, err }
-    return PublicConfirmation{
-        Status: "confirmed", RequestID: result.RequestID,
-        VerificationID: result.VerificationID, Purpose: result.Purpose,
-        ExpiresAt: saved.Ticket.ExpiresAt, AuthenticationPolicy: result.AuthenticationPolicy,
-    }, nil
-}
-```
-
-#### 5. Vue のライフサイクルと業務データ付き要求
-
-完全なファイルは `examples/vue-cms.vue` にも同梱します。サイトのログイン後、信頼できる apiOrigin/authLinkOrigin と任意の保存済み下書き `post={id,version}` を渡してマウントします。親は認証 session の識別子を key に使います。ログアウト・再ログイン・アカウント切り替えでは先にアンマウントし、古い ticket・作成キー・未完了の公開処理を消去してから新規マウントします。
-
-```vue
-<script setup lang="ts">
-import { markRaw, onMounted, onUnmounted, ref, shallowRef } from 'vue';
-import { createAuthLinkClient, requestKey, validateTicket } 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';
-
-type Post = { id: string; version: number };
-type Publication = Post & { requestId: string };
-// Supply trusted deployment configuration. Mount after site login and remount
-// with :key="session.subject" after login, logout or account/session changes.
-const props = defineProps<{ apiOrigin: string; authLinkOrigin: string; post?: Post }>();
-const session = ref<{ authenticated: boolean; csrf?: string } | null>(null);
-const ticket = shallowRef<Ticket | null>(null);
-const publication = shallowRef<Post | null>(null);
-const retryPublish = shallowRef<Publication | null>(null);
-const busy = ref(false), message = ref('');
-let creation: { signature: string; key: string } | null = null;
-const lifetime = new AbortController();
-const client = markRaw(createAuthLinkClient({
-  baseUrl: `${props.apiOrigin}/api/authlink`,
-  allowedBackendOrigins: [props.apiOrigin],
-  credentials: 'include',
-  csrfToken: () => session.value?.csrf ?? '',
-  authLinkOrigin: props.authLinkOrigin,
-}));
-
-async function api(path: string, body?: unknown, headers: Record<string, string> = {}) {
-  const response = await fetch(`${props.apiOrigin}${path}`, {
-    method: body === undefined ? 'GET' : 'POST',
-    credentials: 'include', cache: 'no-store', redirect: 'error',
-    signal: lifetime.signal,
-    headers: body === undefined ? {} : {
-      'Content-Type': 'application/json', 'X-CSRF-Token': session.value?.csrf ?? '', ...headers,
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  const value = await response.json();
-  if (response.status === 401) {
-    session.value = null; closeTicket(); retryPublish.value = null; creation = null;
-  }
-  if (!response.ok) throw new Error(value.code ?? 'REQUEST_FAILED');
-  return value;
-}
-function closeTicket() { ticket.value = null; publication.value = null; }
-function showError(error: Error) { message.value = error.message; }
-function finish(text: string) { closeTicket(); message.value = text; }
-
-async function start(purpose: Mode, post?: Post) {
-  if (busy.value || ticket.value || !session.value?.authenticated) return;
-  busy.value = true; message.value = ''; retryPublish.value = null;
-  const intent = post ? { id: post.id, version: post.version } : null;
-  const signature = JSON.stringify({ purpose, postId: intent?.id, version: intent?.version });
-  try {
-    if (creation?.signature !== signature) creation = { signature, key: requestKey() };
-    // SDK create() sends only {purpose}. Business fields use your own API.
-    const value = intent
-      ? validateTicket(await api('/api/authlink/requests', {
-          purpose, postId: intent.id, version: intent.version,
-        }, { 'Idempotency-Key': creation.key }), purpose, props.authLinkOrigin)
-      : await client.create(purpose, { idempotencyKey: creation.key, signal: lifetime.signal });
-    if (lifetime.signal.aborted) return;
-    publication.value = intent; ticket.value = value; creation = null;
-  } catch (error) {
-    if (!lifetime.signal.aborted) showError(error as Error);
-    // Retain creation.key for a retry of the SAME purpose/post/version.
-  } finally { busy.value = false; }
-}
-async function publish() {
-  const intent = retryPublish.value;
-  if (!intent || busy.value) return;
-  busy.value = true;
-  try {
-    await api(`/api/posts/${intent.id}/publish`, { version: intent.version, requestId: intent.requestId });
-    retryPublish.value = null; message.value = 'Published. Reload your posts from the backend.';
-  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
-  finally { busy.value = false; }
-}
-async function confirmed(result: Confirmation) {
-  const intent = publication.value;
-  closeTicket();
-  if (intent) { retryPublish.value = { ...intent, requestId: result.requestId }; await publish(); }
-  else message.value = 'Verified. Reload account status from the backend.';
-}
-onMounted(async () => {
-  try {
-    const value = await api('/api/session');
-    if (value.authenticated !== true || typeof value.csrf !== 'string' || !value.csrf) {
-      throw new Error('LOGIN_REQUIRED');
-    }
-    session.value = value;
-  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
-});
-onUnmounted(() => { lifetime.abort(); closeTicket(); creation = null; retryPublish.value = null; });
-</script>
-
-<template>
-  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('bind')">Bind phone</button>
-  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm')">Confirm</button>
-  <button v-if="post" :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm', post)">Confirm publication</button>
-  <button v-if="retryPublish" :disabled="busy || !!ticket" @click="publish">Retry the same publication</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 a new request')" @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 a new request')" @error="showError" />
-  <p role="status">{{ message }}</p>
-</template>
-```
-
-client.create が送るのは purpose のみです。postId/version が必要なら業務 API に fetch で送り、`validateTicket(response, 'confirm', authLinkOrigin)` で検証した後、監視には公式 client を使います。同じ作成の失敗ではキーを保持し、用途・記事・版が変わったときだけ新規キーにします。ticket は shallowRef、client は markRaw で保持します。
-
-マウント時は既存要求を監視し、mounted/watch で新規作成しません。閉じる・拒否・期限切れでは ticket を消去し、通信エラーでは同じ要求を再試行できるよう表示を維持します。confirmed 後は表示を閉じ、独立した公開 API を呼びます。失敗時は同じ requestId/記事/版で再試行し、実状態をバックエンドから再取得します。サイト自身のログインフォーム・記事一覧・エラー翻訳は例から省略しています。
+| 設定 | 用途 |
+| --- | --- |
+| `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 |
 
-#### 6. 公開トランザクションで再検証
+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 秒、閉じる/アンマウントで監視を中止します。
 
-ブラウザーの confirmed イベントは許可証ではありません。Go は現在の session の保存済み確認結果を読み、purpose=confirm、intent=publish、記事の所有者、同一 postId/version、下書き状態、初回適用時の有効期限を検証します。記事更新と applied の記録を一括コミットします。同じ適用済み操作の再試行は重複更新・監査なしで成功を返します。別記事や編集後の版には新たな確認が必要です。AuthLink 確認結果に action、transactionHash、記事本文を追加しません。
+期限切れの数字は隠れます。数字をフロントエンドで生成・キャッシュしません。QR はローカル生成で、CSP 使用時は data: 画像を許可します。イベントや localStorage、ブラウザーからの状態値は業務上の許可証ではありません。
 
-#### 検証順序
+### ライセンス
 
-サイトログイン → session → バックエンド AccountStatus（参照 CMS は overview 経由）→ 未登録なら bind → スマートフォンで承認 → 消費と状態再取得 → 下書き保存 → 記事/版の confirm → 承認 → 確認結果保存 → 公開 → 再試行・異なる版・拒否・期限切れ。実端末での承認は利用者が行い、コンパイルや模擬 HTTP 検証とは区別します。
+MIT。LICENSE と THIRD_PARTY_NOTICES.md を参照してください。