npm - @auth-link/web - Versions diffs - 0.0.4 → 0.0.5 - Mend

@auth-link/web 0.0.4 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/CHANGELOG.md +6 -0
package/README.md +588 -1796
package/docs/README.en.md +200 -323
package/docs/README.ja.md +200 -323
package/docs/README.zh-CN.md +201 -394
package/examples/react-client.tsx +42 -0
package/examples/vue-client.vue +55 -0
package/package.json +6 -3
package/docs/go-vue.en.md +0 -256
package/docs/go-vue.ja.md +0 -256
package/docs/go-vue.zh-CN.md +0 -260
package/examples/vue-cms.vue +0 -109

package/docs/README.ja.md CHANGED Viewed

@@ -2,404 +2,281 @@
 [English](../README.md) | [简体中文](./README.zh-CN.md) | **日本語**
-**AuthLink のスマートフォン登録とアプリでの確認**を Web サイトに組み込む React / Vue コンポーネントです。登録用 QR コード、同期する 6 桁の照合コード、カウントダウン、確認結果を表示します。特定のサイト基盤には依存しません。
+スマートフォン登録とアプリ内確認のフロントエンド用ダイアログです。Vue 3、React 18/19、通常の JavaScript に対応します。インストール、session 取得、client 初期化、表示、イベントと後処理の順に接続します。
-## Go + Vue の接続手順
-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 のみ送ります。
-## 主な機能
-- ブラウザー内で生成するスマートフォン登録用 QR コード。
-- アプリと同期し、30 秒ごとに更新される照合コード。
-- 承認・拒否・期限切れ・エラーのイベント。
-- React コンポーネントと hook、Vue コンポーネントと composable、フレームワーク非依存の API。
-- **簡体字中国語を既定とする 13 言語**。コンポーネントごとに指定可能。
-- TypeScript、独立した CSS、任意の React / Vue peer dependency。
-本パッケージはブラウザー用の接続ライブラリです。サイトのバックエンド、AuthLink サービス、モバイルアプリと併用します。AuthLink はアプリ内の承認と元の端末のハードウェア証明を検証します。システムのパスキー、指紋認証、画面ロックは要求しません。
-## インストール
+## 1. インストールと 2 つの API
 ```sh
-npm install @auth-link/web
+npm install @auth-link/web@latest
+# 利用する vue、または react / react-dom もインストールします。
 ```
-対応環境：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 }}` はサーバーテンプレートの変数です。このページを公開キャッシュしないでください。
+| origin | フロントエンド設定 | 用途 |
+| --- | --- | --- |
+| 自サイトの API（例 https://cms-api.example.com） | baseUrl、allowedBackendOrigins | session、要求作成、結果 |
+| AuthLink 本番 API https://api.getauthlink.com | authLinkOrigin | ticket 内のサービス origin の照合 |
-```html
-<meta name="csrf-token" content="{{ csrfToken }}">
-```
+baseUrl は自サイトの業務 API であり、AuthLink API や公式サイトではありません。既存のログイン/session と下記要求 API を利用します。SDK 自体はログイン/session API を提供しません。テナントキーはブラウザーに渡しません。
-SDK は各リクエストで token を読み取り、`X-CSRF-Token` と同一オリジンのセッション cookie を送信します。作成 API と結果 API の両方で、バックエンドが同じセッションの token と照合し、欠落・不一致や不正なリクエスト元を拒否する必要があります。ログインやセッション変更後は最新 token を取得してください。SPA ではサイト独自の同一オリジン初期化 API から取得する方法も使えます。別のヘッダー名を使うフレームワークでは`csrfHeaderName` または独自 `AuthLinkClient` で適合します。
+ルート import は client と型、/vue と /react はコンポーネントと useAuthLink、/styles.css は明示 import です。ESM、TypeScript、ツール環境 Node 22.13+、React 18.2+/19 または Vue 3.3+。利用するフレームワークのみ導入します。
-`authlink-client.ts` を作成します：
+## 2. 現在の session と 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,
-  // AuthLink production API origin.
-  authLinkOrigin: 'https://api.getauthlink.com',
-});
-```
-AuthLink の本番 API は `https://api.getauthlink.com` です。baseUrl は自サイトの業務バックエンドを指し、AuthLink 公式サイトのドメインは API に使いません。独自に配置したサービスへ接続する場合は、その設定済み origin を使用します。リクエストは下記の 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',
+// 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` を既存コンポーネントに渡します。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 は作成・ポーリングのたびに最新値を読み取ります。
+サイトのログイン後に既存 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.
 ```
-これはサイト利用者のログイン token であり、AuthLink のテナント API キーではありません。SDK が `Authorization: Bearer ...` を付加します。`accessToken` 指定時は既定で `credentials: 'omit'` となり、Cookie にフォールバックせず Bearer のみで認証するバックエンドでは CSRF を省略できます。`include` / `same-origin` を明示して Cookie を併用する場合は CSRF の提供・検証も必要です。
-### バックエンドの CORS
+GET /api/session はサイト側の既存ルートの例です。同 origin は相対 URL と same-origin Cookie、別 origin の Cookie は include を使い、業務 API が現在のフロントエンド origin を許可している必要があります。Cookie 制限も適用されます。HttpOnly Cookie を読んだり、CSRF をブラウザーで生成したり、照合数字で代用したりしません。
-`OPTIONS` プリフライトを処理し、実リクエスト・エラー応答・session 初期化 API にも必要な CORS ヘッダーを返します。フロントエンドが `https://www.example.com` の例：
+Bearer/JWT を使う場合、auth は既存ログイン状態です。更新された accessToken を毎回読みます。これはテナントキーではありません。credentials=omit の Bearer のみ CSRF を省略でき、Cookie 併用なら csrfToken が必要です。
-```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',
+});
 ```
-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) を参照してください。
-### クライアント設定
+## 3. Vue：クリックで作成、表示、後処理
-| 設定 | 説明 |
-| --- | --- |
-| `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 実装；接続先検証は維持 |
+`examples/vue-client.vue` を AuthLinkPanel.vue としてコピーできます。ログイン後に現在の session.csrf を渡し、別 origin なら backendOrigin も渡します。ログアウト・アカウント/session 変更では旧コンポーネントをアンマウントして再作成します。token 更新時は csrf prop を更新します。
-追加ヘッダーは 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';
+```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';
-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 に設定します。
+// 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>
-閉じてもサーバーのリクエストを拒否・取消しません。元の有効期限は維持されます。承認・拒否時は自動で閉じ、onConfirmed または onRejected を通知します。ユーザー操作の onClose は通知しません。関数で開いた場合はページ破棄時に modal.destroy() を呼んで通信と UI を解除してください。destroy() は onClose を通知しません。modal.setLocale() はリクエストを作り直さずに言語を切り替えます。
+<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>
+```
+ticket は shallowRef、client は markRaw で保持します。同じ用途の作成失敗ではキーを保持し、成功後に消去します。mounted/watch で要求を作りません。確認・拒否・期限切れ・閉じる操作で ticket を消去します。通信エラーでは表示を維持して同じ要求を再試行します。必要なアカウント状態は自サイトの API から再取得します。
-## React
+## 4. 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` のままです。
+| POST /api/authlink/requests | purpose=bind/confirm、Idempotency-Key | Ticket |
+| POST /api/authlink/requests/{requestId}/result | 空オブジェクト、現在のログイン情報 | Result（自動監視） |
-独自 UI には React の `useAuthLink(options)`、Vue の `useAuthLink(() => options)` を利用できます。返される値は `snapshot` と `retry` です。Vue の snapshot は shallow ref です。retry は既存リクエストを再開し、onRefresh はサイト側のコードで新規作成します。
+Cookie モードでは両方に現在の CSRF ヘッダーを送ります。Ticket は requestId、purpose、qr、pairingCode、expiresAt、confirm 時は displayCode も必要です。Ticket/Result/Confirmation 型を import し、QR や数字を自作しません。confirmed のみ成功イベントを発火します。new/pending/approved/consumed は待機、rejected/expired は対応イベントです。
-## バックエンド API
-既定の接頭辞は `/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 による永続的な冪等処理が必要です。
-## 対応言語
+## 7. 設定・イベント・表示
-| 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 | 型 | 用途 |
+| --- | --- | --- |
+| `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 |
-未指定・未対応の言語コードは簡体字中国語にフォールバックします。ルート要素には `lang` が設定されます。ルートエントリーの `supportedLocales` で一覧を取得できます。言語変更は表示文言だけに作用し、数字やリクエストは変更しません。ドキュメントは英語・中国語・日本語で提供します。
+A は中央カード（既定）、B はデスクトップ分割・狭い画面で縦配置、C は小型・モバイルで下部シートです。locale/variant の変更では要求を作り直しません。ネイティブ dialog.showModal() 対応ブラウザーが必要です。
-## スタイルとエントリー
+CSS を明示 import します。ダイアログは document.body 配下なので :root または .authlink-dialog で --authlink-foreground、--authlink-background、--authlink-accent、--authlink-muted を指定します。Vue class は文字列・配列・オブジェクトを className と併用できます。SSR はダイアログや要求を作りません。
-`@auth-link/web/styles.css` を明示的に読み込みます。ダイアログは `document.body` に追加されるため、`:root` または `.authlink-dialog` で `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted` を上書きします。クラス名の接頭辞は `authlink-` です。
+言語：`zh-CN` (default), `zh-TW`, `en`, `ja`, `bn`, `es`, `fil`, `hi`, `id`, `ms`, `pt`, `th`, `vi`。未指定・未対応値は簡体字中国語へフォールバックします。supportedLocales で一覧を取得できます。
-React / Vue はダイアログの `className` に対応します。Vue は文字列・配列・オブジェクト形式の `class` も受け取り、`className` と結合します。再作成ボタンは親が渡した最新の `onRefresh` を呼び出します。
+## 8. 通信設定とエラー確認
-| エントリー | 内容 |
+| 設定 | 用途 |
 | --- | --- |
-| `@auth-link/web` | クライアント、冪等キー、対応言語、型、基本 API |
-| `@auth-link/web/react` | React コンポーネントと hook |
-| `@auth-link/web/vue` | Vue コンポーネントと composable |
-| `@auth-link/web/styles.css` | スタイル |
+| `baseUrl` | Your application API prefix; default `/api/authlink` |
+| `allowedBackendOrigins` | Exact extra application API origins; no paths/wildcards |
+| `credentials` | Default `same-origin`; cross-origin cookies need `include` |
+| `csrfToken` | Sync/async getter for the current website CSRF token |
+| `csrfHeaderName` | Default `X-CSRF-Token` |
+| `accessToken` | Sync/async website Bearer token getter, without `Bearer ` |
+| `headers` | Extra headers or sync/async getter |
+| `authLinkOrigin` | `https://api.getauthlink.com` for production AuthLink |
+| `fetch` | Optional fetch implementation |
-## セキュリティと有効期限
+headers は Accept、Content-Type、Authorization、Idempotency-Key、設定済み CSRF ヘッダーを上書きできません。error.message を確認します。CSRF_REQUIRED は session token、ACCESS_TOKEN_REQUIRED はログイン状態、BACKEND_ORIGIN_NOT_ALLOWED は正確な許可 origin、NETWORK_ERROR は開発者ツールの Network・通信・CORS を確認します。タイムアウトは 10 秒、閉じる/アンマウントで監視を中止します。
-- 数字はアプリとの目視照合用です。数字だけで認証や承認はできません。
-- ブラウザーに生成 seed、端末秘密鍵、テナント秘密情報を渡しません。
-- リクエストは最大 120 秒。コード更新で期限は延長されません。サービスとアプリはモバイルプロトコル 7 に対応する必要があります。
-- サーバー時刻と単調増加時計で残り時間を計算し、通信が止まっても期限切れの数字は隠します。更新境界で短い待ち時間が生じる場合があります。
-- アンマウントや ticket 変更で監視を中止します。インスタンス内のイベント重複防止とは別に、バックエンドで永続的な冪等処理が必要です。
-- フロントエンドのイベントは UI 更新用です。保護 API はバックエンドの信頼できる記録で判断します。
-- QR はローカル生成し、バックエンドの SVG を挿入しません。CSP は `img-src 'self' data:` を許可してください。
+期限切れの数字は隠れます。数字をフロントエンドで生成・キャッシュしません。QR はローカル生成で、CSP 使用時は data: 画像を許可します。イベントや localStorage、ブラウザーからの状態値は業務上の許可証ではありません。
 ## ライセンス
-MIT。ライセンス全文は `LICENSE`、同梱ライブラリの帰属表示は `THIRD_PARTY_NOTICES.md` を参照してください。
+MIT。LICENSE と THIRD_PARTY_NOTICES.md を参照してください。