@auth-link/web 0.0.1 → 0.0.3

package/docs/README.en.md

@@ -4,6 +4,12 @@
 
 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.
 
+## Go backend + Vue walkthrough
+
+Start with [Go + Vue: login, binding and confirmed publication](./go-vue.en.md) and the [complete Vue CMS example](../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.
@@ -26,41 +32,148 @@ Compatibility: React 18.2+ / 19, Vue 3.3+, TypeScript, ESM. Install only the fra
 ## Browser integration
 
 1. Configure your backend's AuthLink tenant credentials.
-2. Implement the two same-origin endpoints below, authenticated to the current website user.
+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 intentionally uses a same-origin backend. You can supply a custom `AuthLinkClient` to integrate another transport while preserving server-side credential handling and verification.
+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.
 
-## Create a client
+```html
+<meta name="csrf-token" content="{{ csrfToken }}">
+```
+
+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`.
+
+Create `authlink-client.ts`:
 
 ```ts
 // authlink-client.ts
-import { createAuthLinkClient, requestKey } from '@auth-link/web';
+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: () => {
-    const token = document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content;
-    if (!token) throw new Error('Missing CSRF token');
-    return token;
-  },
+  csrfToken: readCsrfTokenFromYourCms,
+  // Replace this example with the configured AuthLink service origin.
   authLinkOrigin: 'https://auth.example.com',
 });
+```
 
-// Call from a user action. Keep this key if you retry the same creation.
-const idempotencyKey = requestKey();
-const ticket = await client.create('bind', { idempotencyKey });
-// For a mobile confirmation, use client.create('confirm', { idempotencyKey }).
+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',
+  });
+  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; },
+  };
+}
 ```
 
-Provide a real CSRF token from your application's session in the meta element, and replace the example AuthLink origin with your configured HTTPS origin. Request creation belongs in a click handler, not a mount effect. Components only observe existing requests.
+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.
+
+```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,
+  });
+}
+```
+
+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.
+
+### Backend CORS
+
+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
+```
+
+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.
 
 ## Open a dialog directly (React, Vue or plain JavaScript)
 
 ```ts
 import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
+import { client } from './authlink-client';
 import '@auth-link/web/styles.css';
 
 // Call in your button handler, after your backend creates the request.
@@ -79,22 +192,62 @@ The dialog adapts to mobile widths, has a scrollable height, keyboard Escape and
 
 ## 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" />`.
+
 ```tsx
+"use client";
+import { useRef, useState } from 'react';
+import { requestKey } from '@auth-link/web';
+import type { Mode, Ticket } from '@auth-link/web';
 import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-import type { Ticket, Confirmation } from '@auth-link/web';
 import { client } from './authlink-client';
 
-export function VerificationPanel({ ticket }: { ticket: Ticket }) {
-  const onConfirmed = (result: Confirmation) => {
-    console.log('Confirmed request:', result.requestId);
+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(`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('');
+    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); }
   };
-  return ticket.purpose === 'bind'
-    ? <AuthLinkBind ticket={ticket} client={client} onConfirmed={onConfirmed} />
-    : <AuthLinkConfirm ticket={ticket} client={client} locale="en"
-        onConfirmed={onConfirmed} onExpired={() => console.log('Expired')} />;
+  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')}
+      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
@@ -175,7 +328,7 @@ Rejection returns `{ status: 'rejected', code: 'REJECTED', requestId, purpose }`
 
 ## Backend contract
 
-The default prefix is `/api/authlink`. Both endpoints use your website session and `X-CSRF-Token`. Creation also sends a stable `Idempotency-Key`. Your backend derives the website account from the session rather than a browser-supplied account ID.
+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.
 
 ```ts
 import type { Ticket, Result } from '@auth-link/web';
@@ -202,7 +355,7 @@ import type { Ticket, Result } from '@auth-link/web';
 
 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.
 
-The result endpoint verifies session/request ownership 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.
+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
 
@@ -228,6 +381,8 @@ Missing or unsupported locale codes fall back to Simplified Chinese. The panel s
 
 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.
 
+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.
+
 | Import | Contents |
 | --- | --- |
 | `@auth-link/web` | Client, request key, supported locales, types and core tools |
@@ -247,4 +402,4 @@ Explicitly import `@auth-link/web/styles.css`. Override `--authlink-foreground`,
 
 ## License
 
-UNLICENSED. Public availability of the package does not grant an open-source license. Bundled third-party attribution is in `THIRD_PARTY_NOTICES.md`.
+MIT. See `LICENSE` for the full license text and `THIRD_PARTY_NOTICES.md` for bundled third-party attribution.

package/docs/README.ja.md

@@ -4,26 +4,11 @@
 
 **AuthLink のスマートフォン登録とアプリでの確認**を Web サイトに組み込む React / Vue コンポーネントです。登録用 QR コード、同期する 6 桁の照合コード、カウントダウン、確認結果を表示します。特定のサイト基盤には依存しません。
 
-## 関数でダイアログを開く（React / Vue / JavaScript）
+## Go + Vue の接続手順
 
-```ts
-import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import '@auth-link/web/styles.css';
-
-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() はリクエストを作り直さずに言語を切り替えます。
+Go + Vue の実際の接続手順は [ログイン、端末登録、確認後の公開](./go-vue.ja.md)、完全なコンポーネントは [Vue CMS 例](../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 のみ送ります。
 
 ## 主な機能
 
@@ -47,55 +32,223 @@ npm install @auth-link/web
 ## 接続の流れ
 
 1. サイトのバックエンドに AuthLink のテナント資格情報を設定します。
-2. 下記の同一オリジンの作成・結果取得 API を実装します。
+2. 下記の業務バックエンド（同一オリジンまたは明示的に許可した別オリジン）の作成・結果取得 API を実装します。
 3. ユーザー操作でリクエストを作成し、取得した ticket をコンポーネントに渡します。
 4. バックエンドが結果を検証・消費した後に確認完了を返します。
 
-ブラウザーからこのライブラリを呼び出せますが、テナント API キーと結果の消費処理は必ずサーバー側に置きます。標準クライアントは同一オリジンのバックエンドに接続します。独自の通信方式では `AuthLinkClient` を実装できますが、資格情報と検証をブラウザーに移さないでください。
+ブラウザーからこのライブラリを呼び出せますが、テナント 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, requestKey } from '@auth-link/web';
+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: () => {
-    const token = document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content;
-    if (!token) throw new Error('Missing CSRF token');
-    return token;
-  },
+  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 の許可リストとは別です。
 
-// Call from a user action. Keep this key if you retry the same creation.
-const idempotencyKey = requestKey();
-const ticket = await client.create('bind', { idempotencyKey });
-// For a mobile confirmation, use client.create('confirm', { idempotencyKey }).
+### 別オリジンの 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; },
+  };
+}
 ```
 
-meta 要素にサイトのセッションに対応する CSRF トークンを設定し、AuthLink の HTTPS オリジンを実際の設定に置き換えてください。作成処理はクリックハンドラーで実行し、マウント時の effect では実行しません。コンポーネントは既存のリクエストを監視します。同じ作成操作を再試行する際は同じ冪等キーを使います。
+ログイン後に `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` になります。
+
+## 関数でダイアログを開く（React / Vue / JavaScript）
+
+```ts
+import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
+import { client } from './authlink-client';
+import '@auth-link/web/styles.css';
+
+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" />` で使います。
+
 ```tsx
+"use client";
+import { useRef, useState } from 'react';
+import { requestKey } from '@auth-link/web';
+import type { Mode, Ticket } from '@auth-link/web';
 import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-import type { Ticket, Confirmation } from '@auth-link/web';
 import { client } from './authlink-client';
 
-export function VerificationPanel({ ticket }: { ticket: Ticket }) {
-  const onConfirmed = (result: Confirmation) => {
-    console.log('Confirmed request:', result.requestId);
+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(`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('');
+    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); }
   };
-  return ticket.purpose === 'bind'
-    ? <AuthLinkBind ticket={ticket} client={client} onConfirmed={onConfirmed} />
-    : <AuthLinkConfirm ticket={ticket} client={client} locale="en"
-        onConfirmed={onConfirmed} onExpired={() => console.log('Expired')} />;
+  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')}
+      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
@@ -175,7 +328,7 @@ React / Vue では表示中にも変更でき、リクエストやポーリン
 
 ## バックエンド API
 
-既定の接頭辞は `/api/authlink` です。両 API でサイトのセッション、`X-CSRF-Token`、リクエストの所有者を検証してください。作成時は `Idempotency-Key` も送信されます。サイトのユーザー ID はセッションから決定します。
+既定の接頭辞は `/api/authlink` です。両 API で Cookie + 設定した CSRF ヘッダー、または Bearer token による本人確認とリクエスト所有者を検証してください。作成時は `Idempotency-Key` も送信されます。サイトのユーザー ID は検証済みセッション/token から決定します。
 
 ```ts
 import type { Ticket, Result } from '@auth-link/web';
@@ -226,7 +379,9 @@ import type { Ticket, Result } from '@auth-link/web';
 
 ## スタイルとエントリー
 
-`@auth-link/web/styles.css` を明示的に読み込みます。親要素で `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted` を上書きできます。クラス名の接頭辞は `authlink-` です。
+`@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` を呼び出します。
 
 | エントリー | 内容 |
 | --- | --- |
@@ -239,7 +394,7 @@ import type { Ticket, Result } from '@auth-link/web';
 
 - 数字はアプリとの目視照合用です。数字だけで認証や承認はできません。
 - ブラウザーに生成 seed、端末秘密鍵、テナント秘密情報を渡しません。
-- リクエストは最大 120 秒。コード更新で期限は延長されません。サービスとアプリはモバイルプロトコル 4 に対応する必要があります。
+- リクエストは最大 120 秒。コード更新で期限は延長されません。サービスとアプリはモバイルプロトコル 7 に対応する必要があります。
 - サーバー時刻と単調増加時計で残り時間を計算し、通信が止まっても期限切れの数字は隠します。更新境界で短い待ち時間が生じる場合があります。
 - アンマウントや ticket 変更で監視を中止します。インスタンス内のイベント重複防止とは別に、バックエンドで永続的な冪等処理が必要です。
 - フロントエンドのイベントは UI 更新用です。保護 API はバックエンドの信頼できる記録で判断します。
@@ -247,4 +402,4 @@ import type { Ticket, Result } from '@auth-link/web';
 
 ## ライセンス
 
-UNLICENSED。公開パッケージであってもオープンソース利用許諾は付与されません。同梱ライブラリの帰属表示は `THIRD_PARTY_NOTICES.md` を参照してください。
+MIT。ライセンス全文は `LICENSE`、同梱ライブラリの帰属表示は `THIRD_PARTY_NOTICES.md` を参照してください。