@auth-link/web 0.0.5 → 1.1.0

package/docs/README.ja.md

@@ -1,282 +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)
 
-スマートフォン登録とアプリ内確認のフロントエンド用ダイアログです。Vue 3、React 18/19、通常の JavaScript に対応します。インストール、session 取得、client 初期化、表示、イベントと後処理の順に接続します。
+## 認証コードを直接検証
 
-## 1. インストールと 2 つの API
+アプリに6桁の認証コードを直接表示します。通常の検証では、毎回の承認、認証用requestId、businessId、ポーリングは不要です。初回はQRで端末を確認し、サイトで現在のコードを検証して連携を完了します。
+
+画面を開く前にCMSサーバーでセッションの唯一の保留中操作を原子的に確保します。別タブから上書きさせません。ユーザーはサーバーのセッションから取得し、CSRF、業務権限、元のフォームを確認します。コードを検証し、verificationIdと元の操作を原子的に確定してから成功を返します。onVerifiedは表示更新専用です。
 
 ```sh
-npm install @auth-link/web@latest
-# 利用する vue、または react / react-dom もインストールします。
+npm install @auth-link/web@^1.1.0
 ```
 
-| origin | フロントエンド設定 | 用途 |
-| --- | --- | --- |
-| 自サイトの API（例 https://cms-api.example.com） | baseUrl、allowedBackendOrigins | session、要求作成、結果 |
-| AuthLink 本番 API https://api.getauthlink.com | authLinkOrigin | ticket 内のサービス origin の照合 |
-
-baseUrl は自サイトの業務 API であり、AuthLink API や公式サイトではありません。既存のログイン/session と下記要求 API を利用します。SDK 自体はログイン/session API を提供しません。テナントキーはブラウザーに渡しません。
-
-ルート import は client と型、/vue と /react はコンポーネントと useAuthLink、/styles.css は明示 import です。ESM、TypeScript、ツール環境 Node 22.13+、React 18.2+/19 または Vue 3.3+。利用するフレームワークのみ導入します。
-
-## 2. 現在の session と client
-
 ```ts
-import { createAuthLinkClient } from '@auth-link/web';
+import { openPasscode, createPasscodeClient } from '@auth-link/web';
 import '@auth-link/web/styles.css';
-
-// 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',
-  });
-}
-```
-
-サイトのログイン後に既存 session API を読みます。例は CMS の authenticated/csrf です。フィールド名が csrfToken ならその値を SDK の csrfToken コールバックへ渡します。
-
-```ts
-// Run in your website's existing authenticated browser flow.
-const backendOrigin = 'https://cms-api.example.com'; // YOUR application backend
-const response = await fetch(`${backendOrigin}/api/session`, {
-  credentials: 'include', cache: 'no-store', redirect: 'error',
+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),
 });
-if (!response.ok) throw new Error('Session unavailable');
-let session = await response.json();
-if (session.authenticated !== true || typeof session.csrf !== 'string' || !session.csrf) {
-  throw new Error('Log in to your website first');
-}
-const client = createWebsiteClient(() => session.csrf, backendOrigin);
-// Same origin: createWebsiteClient(() => session.csrf)
-// After token refresh, replace session or update session.csrf.
-// On logout/account/session change, close/unmount old dialogs and recreate client state.
+// modal.setLocale('en'); modal.setVariant('C'); modal.destroy();
 ```
 
-GET /api/session はサイト側の既存ルートの例です。同 origin は相対 URL と same-origin Cookie、別 origin の Cookie は include を使い、業務 API が現在のフロントエンド origin を許可している必要があります。Cookie 制限も適用されます。HttpOnly Cookie を読んだり、CSRF をブラウザーで生成したり、照合数字で代用したりしません。
+標準クライアントは現在の認証情報とCSRFを付け、CMSのPOST /api/authへ{passcode}を送信します。フォームも送る場合はclient.verifyで{form,passcode}をCMSへ送信し、サーバーで保存済み内容と照合します。テナントキーやコード生成用秘密はブラウザーへ渡しません。
 
-Bearer/JWT を使う場合、auth は既存ログイン状態です。更新された accessToken を毎回読みます。これはテナントキーではありません。credentials=omit の Bearer のみ CSRF を省略でき、Cookie 併用なら csrfToken が必要です。
+## オプションとコールバック
 
-```ts
-const backendOrigin = 'https://cms-api.example.com'; // YOUR application backend
-const client = createAuthLinkClient({
-  baseUrl: `${backendOrigin}/api/authlink`, allowedBackendOrigins: [backendOrigin],
-  credentials: 'omit', accessToken: () => auth.accessToken,
-  authLinkOrigin: 'https://api.getauthlink.com',
-});
-```
+必須はclient.verify(passcode, signal)とexpiresAt（CMS操作の期限）です。任意でlocale、variant A/B/C、初回用bindingQrとauthLinkOrigin、onVerified、onError、onClose、onExpiredを指定します。成功結果はstatus、verificationId、authenticationPolicy、expiresAtを含み、requestIdやbusinessIdは含みません。
 
-## 3. Vue：クリックで作成、表示、後処理
+Cookie認証ではCSRFが必須です。Bearer認証はaccessTokenとcredentials=omitを使います。別オリジンのCMSはallowedBackendOriginsを明示し、ループバック開発以外ではHTTPSを使います。
 
-`examples/vue-client.vue` を AuthLinkPanel.vue としてコピーできます。ログイン後に現在の session.csrf を渡し、別 origin なら backendOrigin も渡します。ログアウト・アカウント/session 変更では旧コンポーネントをアンマウントして再作成します。token 更新時は csrf prop を更新します。
+## ReactとVue
 
-```vue
-<script setup lang="ts">
-import { markRaw, onUnmounted, ref, shallowRef } from 'vue';
-import { createAuthLinkClient, requestKey } from '@auth-link/web';
-import type { Confirmation, Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
-import '@auth-link/web/styles.css';
+Reactは同じオプションを使い、Vueはverified、error、close、expiredイベントを発行します。clientの参照を安定させてください。13言語に対応し、既定は簡体字中国語です。Aはシンプル、Bは分割、Cはコンパクト表示です。
 
-// csrf comes from your website's current authenticated session.
-const props = defineProps<{ csrf: string; backendOrigin?: string }>();
-const ticket = shallowRef<Ticket | null>(null);
-const busy = ref(false), message = ref('');
-const lifetime = new AbortController();
-let creationKey: string | null = null;
-let creationMode: Mode | null = null;
-const client = markRaw(createAuthLinkClient({
-  baseUrl: props.backendOrigin ? `${props.backendOrigin}/api/authlink` : '/api/authlink',
-  allowedBackendOrigins: props.backendOrigin ? [props.backendOrigin] : [],
-  credentials: props.backendOrigin ? 'include' : 'same-origin',
-  csrfToken: () => props.csrf,
-  authLinkOrigin: 'https://api.getauthlink.com',
-}));
-function finish(text: string) { ticket.value = null; message.value = text; }
-function confirmed(result: Confirmation) {
-  finish(`${result.purpose}: ${result.requestId}`);
-  // Reload your website's account/status API if the page needs fresh state.
-}
-function showError(error: Error) { message.value = error.message; }
-async function start(mode: Mode) {
-  if (busy.value || ticket.value) return;
-  busy.value = true; message.value = '';
-  try {
-    if (creationMode !== mode) { creationKey = null; creationMode = mode; }
-    creationKey ??= requestKey();
-    const value = await client.create(mode, { idempotencyKey: creationKey, signal: lifetime.signal });
-    if (lifetime.signal.aborted) return;
-    ticket.value = value; creationKey = null;
-  } catch (error) {
-    if (!lifetime.signal.aborted) showError(error as Error);
-    // Keep the same key when retrying an uncertain creation of the same mode.
-  } finally { busy.value = false; }
-}
-onUnmounted(() => { lifetime.abort(); ticket.value = null; creationKey = null; });
+```tsx
+import { AuthLinkPasscode } from '@auth-link/web/react';
+// Keep client stable (for example with useMemo).
+<AuthLinkPasscode client={client} expiresAt={pending.expiresAt}
+  locale="zh-CN" variant="B" onVerified={updateUI} />
+```
+```vue
+<script setup>
+import { AuthLinkPasscode } from '@auth-link/web/vue';
 </script>
-
 <template>
-  <button :disabled="busy || !!ticket" @click="start('bind')">Bind phone</button>
-  <button :disabled="busy || !!ticket" @click="start('confirm')">Confirm</button>
-  <AuthLinkBind v-if="ticket?.purpose === 'bind'" :ticket="ticket" :client="client" variant="B"
-    @confirmed="confirmed" @close="finish('Closed')" @rejected="finish('Rejected')"
-    @expired="finish('Expired; start again')" @error="showError" />
-  <AuthLinkConfirm v-else-if="ticket?.purpose === 'confirm'" :ticket="ticket" :client="client" variant="B"
-    @confirmed="confirmed" @close="finish('Closed')" @rejected="finish('Rejected')"
-    @expired="finish('Expired; start again')" @error="showError" />
-  <p role="status">{{ message }}</p>
+  <AuthLinkPasscode :client="client" :expires-at="pending.expiresAt"
+    locale="zh-CN" variant="B" @verified="updateUI" />
 </template>
 ```
 
-ticket は shallowRef、client は markRaw で保持します。同じ用途の作成失敗ではキーを保持し、成功後に消去します。mounted/watch で要求を作りません。確認・拒否・期限切れ・閉じる操作で ticket を消去します。通信エラーでは表示を維持して同じ要求を再試行します。必要なアカウント状態は自サイトの API から再取得します。
-
-## 4. React
-
-上記で初期化した安定した client と mode=bind/confirm を渡します。ログアウトやアカウント/session 変更ではアンマウントします。
-
-```tsx
-"use client";
-import { useEffect, useRef, useState } from 'react';
-import { requestKey } from '@auth-link/web';
-import type { AuthLinkClient, Mode, Ticket } from '@auth-link/web';
-import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
-// Import '@auth-link/web/styles.css' once in your application entry.
-
-export function AuthLinkPanel({ client, mode }: { client: AuthLinkClient; mode: Mode }) {
-  const [ticket, setTicket] = useState<Ticket | null>(null);
-  const [busy, setBusy] = useState(false);
-  const [message, setMessage] = useState('');
-  const creation = useRef<{ mode: Mode; key: string } | null>(null);
-  const inFlight = useRef(false);
-  const controller = useRef<AbortController | null>(null);
-  useEffect(() => () => { controller.current?.abort(); }, []);
-  function finish(text: string) { setTicket(null); setMessage(text); }
-  async function start() {
-    if (inFlight.current || ticket) return;
-    inFlight.current = true; setBusy(true); setMessage('');
-    const attempt = new AbortController(); controller.current = attempt;
-    try {
-      if (creation.current?.mode !== mode) creation.current = { mode, key: requestKey() };
-      const value = await client.create(mode, { idempotencyKey: creation.current.key, signal: attempt.signal });
-      if (attempt.signal.aborted) return;
-      setTicket(value); creation.current = null;
-    } catch (error) { if (!attempt.signal.aborted) setMessage((error as Error).message); }
-    finally {
-      inFlight.current = false;
-      if (!attempt.signal.aborted) setBusy(false);
-    }
-  }
-  const Component = mode === 'bind' ? AuthLinkBind : AuthLinkConfirm;
-  return <>
-    {!ticket && <button disabled={busy} onClick={() => void start()}>Start verification</button>}
-    {ticket && <Component ticket={ticket} client={client} variant="B"
-      onConfirmed={result => finish(`${result.purpose}: ${result.requestId}`)}
-      onClose={() => finish('Closed')} onRejected={() => finish('Rejected')}
-      onExpired={() => finish('Expired; start again')}
-      onError={error => setMessage(error.message)} />}
-    <p role="status">{message}</p>
-  </>;
-}
-```
-
-## 5. 通常の JavaScript / 直接表示
-
-```ts
-import { openAuthLinkConfirm, requestKey } from '@auth-link/web';
-import '@auth-link/web/styles.css';
-
-// Inside a click handler; client is the stable instance created above.
-const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
-const modal = openAuthLinkConfirm({
-  ticket, client, variant: 'B', locale: 'zh-CN',
-  onConfirmed: result => console.log(result.requestId),
-  onRejected: result => console.log(result.code),
-  onExpired: () => console.log('Expired'),
-  onError: error => console.log(error.message),
-  onClose: () => console.log('Closed'),
-});
-// Route/component cleanup: modal.destroy();
-// Optional: modal.close(); modal.retry(); modal.setLocale('ja'); modal.setVariant('C');
-```
-
-登録時は client.create('bind', ...) と openAuthLinkBind(...) を使います。確認・拒否は自動で閉じてから通知し、onClose は発火しません。閉じる操作は監視を停止します。画面を離れる際は destroy を呼びます。同じ要求の成功はインスタンス内で一度だけ通知します。イベントは表示更新用で、保護操作は自サイトの業務 API を呼びます。
-
-## 6. フロントエンドが使う API の形式
-
-| 自サイトのルート | 送信 | 受信 |
-| --- | --- | --- |
-| POST /api/authlink/requests | purpose=bind/confirm、Idempotency-Key | Ticket |
-| POST /api/authlink/requests/{requestId}/result | 空オブジェクト、現在のログイン情報 | Result（自動監視） |
-
-Cookie モードでは両方に現在の CSRF ヘッダーを送ります。Ticket は requestId、purpose、qr、pairingCode、expiresAt、confirm 時は displayCode も必要です。Ticket/Result/Confirmation 型を import し、QR や数字を自作しません。confirmed のみ成功イベントを発火します。new/pending/approved/consumed は待機、rejected/expired は対応イベントです。
-
-create() は purpose のみ送ります。業務固有項目が必要なら独自 fetch で作成し、validateTicket で検証して同じコンポーネントへ渡します。post/session/backendOrigin は既存のフロントエンド状態で、同じ入力の再試行では同じキーを保持します。
-
-```ts
-import { requestKey, validateTicket } from '@auth-link/web';
-
-// Keep this key across retries of the SAME operation and payload.
-const idempotencyKey = requestKey();
-const response = await fetch(`${backendOrigin}/api/authlink/requests`, {
-  method: 'POST', credentials: 'include', cache: 'no-store', redirect: 'error',
-  headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': session.csrf,
-    'Idempotency-Key': idempotencyKey },
-  body: JSON.stringify({ purpose: 'confirm', postId: post.id, version: post.version }),
-});
-if (!response.ok) throw new Error('Creation failed');
-const ticket = validateTicket(await response.json(), 'confirm', 'https://api.getauthlink.com');
-// Pass ticket and the same client to AuthLinkConfirm.
-```
-
-## 7. 設定・イベント・表示
-
-| prop | 型 | 用途 |
-| --- | --- | --- |
-| `ticket` | `Ticket` | Required; the current request |
-| `client` | `AuthLinkClient` | Required; keep the instance stable |
-| `locale` | `Locale` | Default `zh-CN` |
-| `variant` | `'A' / 'B' / 'C'` | Default `A` |
-| `showQr` | `boolean` | Optional QR for confirm; bind always shows QR |
-| `intervalMs` | `number` | Default 1500; range 250–10000 ms |
-| `onRefresh` | `() => void` | Optional user action after expiry; create a new ticket |
-| `className` | `string` | Custom dialog class; Vue also accepts `class` |
-
-| React コールバック / Vue イベント | 値 | 動作 |
-| --- | --- | --- |
-| `onConfirmed` / `confirmed` | `Confirmation` | Success; dialog closes automatically |
-| `onRejected` / `rejected` | `Rejection` | `{status:'rejected',code:'REJECTED',requestId,purpose}`; dialog closes |
-| `onExpired` / `expired` | — | Request expired |
-| `onClose` / `close` | — | User closes the dialog; clear ticket |
-| `onError` / `error` | `Error` | Read `error.message`; retain the dialog for retry |
-
-A は中央カード（既定）、B はデスクトップ分割・狭い画面で縦配置、C は小型・モバイルで下部シートです。locale/variant の変更では要求を作り直しません。ネイティブ dialog.showModal() 対応ブラウザーが必要です。
-
-CSS を明示 import します。ダイアログは document.body 配下なので :root または .authlink-dialog で --authlink-foreground、--authlink-background、--authlink-accent、--authlink-muted を指定します。Vue class は文字列・配列・オブジェクトを className と併用できます。SSR はダイアログや要求を作りません。
-
-言語：`zh-CN` (default), `zh-TW`, `en`, `ja`, `bn`, `es`, `fil`, `hi`, `id`, `ms`, `pt`, `th`, `vi`。未指定・未対応値は簡体字中国語へフォールバックします。supportedLocales で一覧を取得できます。
-
-## 8. 通信設定とエラー確認
-
-| 設定 | 用途 |
-| --- | --- |
-| `baseUrl` | Your application API prefix; default `/api/authlink` |
-| `allowedBackendOrigins` | Exact extra application API origins; no paths/wildcards |
-| `credentials` | Default `same-origin`; cross-origin cookies need `include` |
-| `csrfToken` | Sync/async getter for the current website CSRF token |
-| `csrfHeaderName` | Default `X-CSRF-Token` |
-| `accessToken` | Sync/async website Bearer token getter, without `Bearer ` |
-| `headers` | Extra headers or sync/async getter |
-| `authLinkOrigin` | `https://api.getauthlink.com` for production AuthLink |
-| `fetch` | Optional fetch implementation |
-
-headers は Accept、Content-Type、Authorization、Idempotency-Key、設定済み CSRF ヘッダーを上書きできません。error.message を確認します。CSRF_REQUIRED は session token、ACCESS_TOKEN_REQUIRED はログイン状態、BACKEND_ORIGIN_NOT_ALLOWED は正確な許可 origin、NETWORK_ERROR は開発者ツールの Network・通信・CORS を確認します。タイムアウトは 10 秒、閉じる/アンマウントで監視を中止します。
+## 失敗と終了処理
 
-期限切れの数字は隠れます。数字をフロントエンドで生成・キャッシュしません。QR はローカル生成で、CSP 使用時は data: 画像を許可します。イベントや localStorage、ブラウザーからの状態値は業務上の許可証ではありません。
+使用済みコードは別操作や別セッションに使えません。ログインや初回連携直後は次のコードを待ちます。PASSCODE_INVALID、PASSCODE_USED、PASSCODE_LOCKEDを成功として扱わないでください。通信結果不明時は元の冪等キーとコードを保持して再試行し、業務を二重実行しません。
 
-## ライセンス
+destroy()はブラウザー要求を中止してタイマーを解除し、終了コールバックを呼びません。close()はonCloseも呼びます。画面を閉じてもサーバー処理は元に戻らず、キャンセルと保留中操作はCMS側で管理します。待機やローカル期限判定はポーリングしません。
 
-MIT。LICENSE と THIRD_PARTY_NOTICES.md を参照してください。
+旧openAuthLink / Ticket / Consumeは以前のプロトコル向けに残ります。新アプリはopenPasscode / AuthLinkPasscodeとサーバーのAuthenticate / authenticateを使います。旧連携の移行機能は提供しません。