@auth-link/web 0.0.4 → 1.1.0

package/docs/README.ja.md

@@ -1,405 +1,62 @@
-# AuthLink Web
+# AuthLink Web 1.1
 
-[English](../README.md) | [简体中文](./README.zh-CN.md) | **日本語**
+[English](README.en.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
 
-**AuthLink のスマートフォン登録とアプリでの確認**を Web サイトに組み込む React / Vue コンポーネントです。登録用 QR コード、同期する 6 桁の照合コード、カウントダウン、確認結果を表示します。特定のサイト基盤には依存しません。
+## 認証コードを直接検証
 
-## Go + Vue の接続手順
+アプリに6桁の認証コードを直接表示します。通常の検証では、毎回の承認、認証用requestId、businessId、ポーリングは不要です。初回はQRで端末を確認し、サイトで現在のコードを検証して連携を完了します。
 
-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 はアプリ内の承認と元の端末のハードウェア証明を検証します。システムのパスキー、指紋認証、画面ロックは要求しません。
-
-## インストール
+画面を開く前にCMSサーバーでセッションの唯一の保留中操作を原子的に確保します。別タブから上書きさせません。ユーザーはサーバーのセッションから取得し、CSRF、業務権限、元のフォームを確認します。コードを検証し、verificationIdと元の操作を原子的に確定してから成功を返します。onVerifiedは表示更新専用です。
 
 ```sh
-npm install @auth-link/web
+npm install @auth-link/web@^1.1.0
 ```
 
-対応環境：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 { openPasscode, createPasscodeClient } 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',
+const client = createPasscodeClient({ baseUrl: '/api', csrfToken: () => csrfToken });
+const modal = openPasscode({
+  client, expiresAt: pending.expiresAt, locale: 'zh-CN', variant: 'B',
+  // First-time enrollment only:
+  // bindingQr: pending.bindingQr, authLinkOrigin: 'https://api.getauthlink.com',
+  onVerified: result => updateUI(result.verificationId),
 });
+// modal.setLocale('en'); modal.setVariant('C'); modal.destroy();
 ```
 
-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',
-  });
-  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` になります。
-
-## 関数でダイアログを開く（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');
-```
+標準クライアントは現在の認証情報とCSRFを付け、CMSのPOST /api/authへ{passcode}を送信します。フォームも送る場合はclient.verifyで{form,passcode}をCMSへ送信し、サーバーで保存済み内容と照合します。テナントキーやコード生成用秘密はブラウザーへ渡しません。
 
-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() はリクエストを作り直さずに言語を切り替えます。
+必須はclient.verify(passcode, signal)とexpiresAt（CMS操作の期限）です。任意でlocale、variant A/B/C、初回用bindingQrとauthLinkOrigin、onVerified、onError、onClose、onExpiredを指定します。成功結果はstatus、verificationId、authenticationPolicy、expiresAtを含み、requestIdやbusinessIdは含みません。
 
+Cookie認証ではCSRFが必須です。Bearer認証はaccessTokenとcredentials=omitを使います。別オリジンのCMSはallowedBackendOriginsを明示し、ループバック開発以外ではHTTPSを使います。
 
-## React
+## ReactとVue
 
-`showBound(requestId)` はサイトの表示更新用関数です。メッセージを更新し、ticket を消去してダイアログをアンマウントします。下記には拒否・期限切れ・閉じる処理も含まれます。`<AuthLinkPanel mode="bind" />` または `<AuthLinkPanel mode="confirm" />` で使います。
+Reactは同じオプションを使い、Vueはverified、error、close、expiredイベントを発行します。clientの参照を安定させてください。13言語に対応し、既定は簡体字中国語です。Aはシンプル、Bは分割、Cはコンパクト表示です。
 
 ```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(`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); }
-  };
-  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>
-  </>;
-}
+import { AuthLinkPasscode } from '@auth-link/web/react';
+// Keep client stable (for example with useMemo).
+<AuthLinkPasscode client={client} expiresAt={pending.expiresAt}
+  locale="zh-CN" variant="B" onVerified={updateUI} />
 ```
-
-バックエンドは結果を検証・消費・保存してから `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 setup>
+import { AuthLinkPasscode } from '@auth-link/web/vue';
 </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" />
+  <AuthLinkPasscode :client="client" :expires-at="pending.expiresAt"
+    locale="zh-CN" variant="B" @verified="updateUI" />
 </template>
 ```
 
-`:locale="selectedLanguage"` で表示言語を切り替えられます。言語切り替えによって新しい認証リクエストは作成されません。
-
-## レイアウトの選択
-
-初期化時の `variant` で選択します。省略時は **A** です。
-
-| 値 | デスクトップ | モバイル |
-| --- | --- | --- |
-| `A`（既定） | ミニマルなカードと細いコード更新バー | 中央のカード |
-| `B` | QR と照合コードの二列表示 | 縦並び |
-| `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 では表示中にも変更でき、リクエストやポーリングは再作成されません。未対応の値は A に戻ります。B / C のキャンセル操作は閉じるアイコンと同じく表示の監視を停止し、サーバーのリクエストは拒否しません。確認成功時は自動で閉じます。閉じる操作のタッチ領域は 44px で、キーボードのフォーカス表示も維持します。
-
-## コンポーネントの設定
-
-| 設定 | 型 | 説明 |
-| --- | --- | --- |
-| `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 はサイト側のコードで新規作成します。
-
-## バックエンド API
-
-既定の接頭辞は `/api/authlink` です。両 API で Cookie + 設定した CSRF ヘッダー、または Bearer token による本人確認とリクエスト所有者を検証してください。作成時は `Idempotency-Key` も送信されます。サイトのユーザー ID は検証済みセッション/token から決定します。
-
-```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>"
-}
-```
-
-作成 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` を呼び出します。
-
-| エントリー | 内容 |
-| --- | --- |
-| `@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:` を許可してください。
+使用済みコードは別操作や別セッションに使えません。ログインや初回連携直後は次のコードを待ちます。PASSCODE_INVALID、PASSCODE_USED、PASSCODE_LOCKEDを成功として扱わないでください。通信結果不明時は元の冪等キーとコードを保持して再試行し、業務を二重実行しません。
 
-## ライセンス
+destroy()はブラウザー要求を中止してタイマーを解除し、終了コールバックを呼びません。close()はonCloseも呼びます。画面を閉じてもサーバー処理は元に戻らず、キャンセルと保留中操作はCMS側で管理します。待機やローカル期限判定はポーリングしません。
 
-MIT。ライセンス全文は `LICENSE`、同梱ライブラリの帰属表示は `THIRD_PARTY_NOTICES.md` を参照してください。
+旧openAuthLink / Ticket / Consumeは以前のプロトコル向けに残ります。新アプリはopenPasscode / AuthLinkPasscodeとサーバーのAuthenticate / authenticateを使います。旧連携の移行機能は提供しません。