@auth-link/web 0.0.0-stage → 0.0.1

package/docs/README.en.md

@@ -0,0 +1,250 @@
+# AuthLink Web
+
+**English** | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+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.
+
+## Features
+
+- Phone-binding QR codes generated locally in the browser.
+- Matching numbers that update every 30 seconds, synchronized with the AuthLink app.
+- Confirmation, rejection, expiry and error callbacks.
+- React components and hook, Vue components and composable, and framework-independent tools.
+- 13 interface languages, **Simplified Chinese by default**, with per-component language selection.
+- TypeScript declarations, separate CSS and optional React/Vue peer dependencies.
+
+This is a browser integration library. It works with your application backend, the AuthLink service and the mobile app. The service verifies the original phone’s hardware-backed proof after the user approves in the app. Screen-lock checks and system passkeys are not required. Installing the library alone does not create an authentication service.
+
+## Install
+
+```sh
+npm install @auth-link/web
+```
+
+Compatibility: React 18.2+ / 19, Vue 3.3+, TypeScript, ESM. Install only the framework you use. The package declares Node 22.13+ for tooling.
+
+## Browser integration
+
+1. Configure your backend's AuthLink tenant credentials.
+2. Implement the two same-origin endpoints below, 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.
+
+## Create a client
+
+```ts
+// authlink-client.ts
+import { createAuthLinkClient, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+
+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;
+  },
+  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 }).
+```
+
+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.
+
+## Open a dialog directly (React, Vue or plain JavaScript)
+
+```ts
+import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+
+// Call in your button handler, after your backend creates the request.
+const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
+const modal = openAuthLinkConfirm({
+  ticket, client, locale: 'en',
+  onConfirmed: result => console.log('Confirmed:', result.requestId),
+  onRejected: result => console.log(result.code), // REJECTED; dialog already closed
+  onClose: () => console.log('Dialog closed'),
+});
+// Bind instead: openAuthLinkBind({ ticket: bindingTicket, client }).
+// modal.close(); modal.setLocale('ja');
+```
+
+The dialog adapts to mobile widths, has a scrollable height, keyboard Escape and an accessible close button. Native `<dialog>` provides modal focus handling; a browser with `showModal()` is required. Closing aborts browser observation and restores focus/scroll. It does not reject, delete or undo the server request. Its original expiry still applies. Confirmation and rejection automatically close the dialog before delivering `onConfirmed` or `onRejected`; it does not emit a user-close callback. Always call `modal.destroy()` when the owning page/component unmounts; this cleans up without emitting `onClose`.
+
+## React
+
+```tsx
+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);
+  };
+  return ticket.purpose === 'bind'
+    ? <AuthLinkBind ticket={ticket} client={client} onConfirmed={onConfirmed} />
+    : <AuthLinkConfirm ticket={ticket} client={client} locale="en"
+        onConfirmed={onConfirmed} onExpired={() => console.log('Expired')} />;
+}
+```
+
+Mounting either component opens a dialog; unmount it in `onClose` (for example, clear the selected ticket). SSR renders no dialog and makes no requests. Omit `locale` for Simplified Chinese. Use `locale="zh-CN"` for Simplified Chinese or another code from the language table. Keep `client` and `ticket` stable between renders. The React entry preserves `"use client"`; SSR rendering does not create requests.
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
+import type { Ticket, Confirmation } from '@auth-link/web';
+import { client } from './authlink-client';
+
+defineProps<{ ticket: Ticket }>();
+function confirmed(result: Confirmation) {
+  console.log('Confirmed request:', result.requestId);
+}
+</script>
+
+<template>
+  <AuthLinkBind v-if="ticket.purpose === 'bind'" :ticket="ticket" :client="client"
+    @confirmed="confirmed" />
+  <AuthLinkConfirm v-else :ticket="ticket" :client="client" locale="ja"
+    @confirmed="confirmed" />
+</template>
+```
+
+Use `:locale="selectedLanguage"` to switch languages without creating a new verification request. Mounting opens the dialog. Use `@close` to clear the selected ticket. Vue exposes `confirmed`, `rejected`, `expired`, `error` and `close` events.
+
+## Choose a layout
+
+Set `variant` when opening a dialog or mounting a component. Omit it for **A**.
+
+| Value | Desktop | Mobile |
+| --- | --- | --- |
+| `A` (default) | Minimal centered card with a thin code-refresh progress bar | Centered card |
+| `B` | QR and matching code in two columns | Vertical layout |
+| `C` | Compact card with footer cancellation | Bottom sheet with safe-area padding |
+
+```ts
+openAuthLinkBind({ ticket, client }); // A, Simplified Chinese by default
+openAuthLinkConfirm({ ticket, client, variant: 'B' });
+// modal.setVariant('C'); // Presentation only; preserves the request and polling.
+```
+
+```tsx
+<AuthLinkBind ticket={ticket} client={client} variant="C" />
+```
+
+```vue
+<AuthLinkConfirm :ticket="ticket" :client="client" variant="B" />
+```
+
+All layouts show a thin progress bar and a static “Code updates automatically every 30 seconds” caption. The footer normally says “Waiting for your phone”; only in the last 30 seconds does it switch to an amber “Request expiring soon · 00:29” warning. Code changes fade in briefly, respect reduced-motion preferences, and never extend the request expiry.
+
+All variants use the same verification, expiry and callbacks. `variant` changes can be reactive in React and Vue without restarting observation. Invalid runtime values fall back to A. The footer Cancel control in B/C has the same behavior as the close icon: it closes observation, without rejecting the server request. Confirmation still dismisses the dialog automatically. A uses a subtle close icon; all close controls retain a 44px hit target and keyboard focus indication.
+
+## Component options
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `ticket` | `Ticket`, required | Existing request returned by your backend |
+| `client` | `AuthLinkClient`, required | Client that queries your backend |
+| `locale` | `Locale` | Interface language; defaults to `zh-CN` |
+| `variant` | `DialogVariant` | `A` (default), `B` or `C`; changes layout only |
+| `showQr` | `boolean` | Optional QR on confirmation panels; binding panels always show it |
+| `intervalMs` | `number` | Polling interval, 250–10000 ms; default 1500 ms |
+| `onRefresh` | `() => void` | Create a new request from the expiry panel and replace the ticket |
+
+| React callback / Vue event | Argument | Meaning |
+| --- | --- | --- |
+| `onConfirmed` / `confirmed` | `Confirmation` | Backend has verified and consumed the result |
+| `onRejected` / `rejected` | `Rejection` | Phone rejected; dialog closes automatically |
+| `onExpired` / `expired` | None | Request expired |
+| `onClose` / `close` | None | Dialog closed; unmount the component / clear its ticket |
+| `onError` / `error` | `Error` | Network, response validation or callback failure |
+
+Rejection returns `{ status: 'rejected', code: 'REJECTED', requestId, purpose }`. `REJECTED` is an SDK business status, not an HTTP status code or an authorization receipt. The SDK closes the dialog without showing a rejection/retry panel or firing `onClose`. Handle any message or new request in your website's callback. In React/Vue, clear the selected ticket in `onRejected` / `@rejected` to unmount the component. Headless hooks retain `snapshot.status === 'rejected'` for custom UI.
+
+`useAuthLink(options)` for React and `useAuthLink(() => options)` for Vue expose `snapshot` and `retry` for custom interfaces. Vue's snapshot is a shallow ref. Retry resumes the same request; `onRefresh` creates a new one through your code.
+
+## Backend contract
+
+The default prefix is `/api/authlink`. Both endpoints 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.
+
+```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>"
+}
+```
+
+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.
+
+## Languages
+
+| Code | Language |
+| --- | --- |
+| `en` | English |
+| `zh-CN` | 简体中文 (default) |
+| `zh-TW` | 繁體中文 |
+| `ja` | 日本語 |
+| `bn` | বাংলা |
+| `es` | Español |
+| `fil` | Filipino |
+| `hi` | हिन्दी |
+| `id` | Bahasa Indonesia |
+| `ms` | Bahasa Melayu |
+| `pt` | Português |
+| `th` | ไทย |
+| `vi` | Tiếng Việt |
+
+Missing or unsupported locale codes fall back to Simplified Chinese. The panel sets its root `lang` attribute. Import `supportedLocales` from the root entry to get the supported codes. Language selection changes display text only, never the verification request or matching numbers. Documentation is available in English, Chinese and Japanese through the links above.
+
+## Styles and entry points
+
+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.
+
+| Import | Contents |
+| --- | --- |
+| `@auth-link/web` | Client, request key, supported locales, types and core tools |
+| `@auth-link/web/react` | React components and hook |
+| `@auth-link/web/vue` | Vue components and composable |
+| `@auth-link/web/styles.css` | Component styles |
+
+## Security and timing
+
+- Matching numbers are for visual comparison with the app, not standalone passwords or authorization proofs.
+- The browser receives only public tickets and current display frames, never generation seeds, device keys or tenant secrets.
+- A request lasts at most 120 seconds; rotating the code does not extend it. Backend and app must support AuthLink mobile protocol 7.
+- Countdown uses server time and a monotonic clock. Expired numbers are hidden even if a network call stalls; a short update gap at rotation is expected.
+- Component unmount/request changes abort polling. Confirmation is deduplicated per mounted instance; your backend still needs persistent idempotence.
+- Frontend callbacks update UI. Protected APIs must rely on trusted backend records, never a JavaScript callback or a browser-supplied success flag.
+- QR generation is local; backend SVG is not injected and no third-party QR service receives the ticket. Allow `img-src 'self' data:` in your CSP.
+
+## License
+
+UNLICENSED. Public availability of the package does not grant an open-source license. Bundled third-party attribution is in `THIRD_PARTY_NOTICES.md`.

package/docs/README.ja.md

@@ -0,0 +1,250 @@
+# AuthLink Web
+
+[English](../README.md) | [简体中文](./README.zh-CN.md) | **日本語**
+
+**AuthLink のスマートフォン登録とアプリでの確認**を Web サイトに組み込む React / Vue コンポーネントです。登録用 QR コード、同期する 6 桁の照合コード、カウントダウン、確認結果を表示します。特定のサイト基盤には依存しません。
+
+## 関数でダイアログを開く（React / Vue / JavaScript）
+
+```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() はリクエストを作り直さずに言語を切り替えます。
+
+
+## 主な機能
+
+- ブラウザー内で生成するスマートフォン登録用 QR コード。
+- アプリと同期し、30 秒ごとに更新される照合コード。
+- 承認・拒否・期限切れ・エラーのイベント。
+- React コンポーネントと hook、Vue コンポーネントと composable、フレームワーク非依存の API。
+- **簡体字中国語を既定とする 13 言語**。コンポーネントごとに指定可能。
+- TypeScript、独立した CSS、任意の React / Vue peer dependency。
+
+本パッケージはブラウザー用の接続ライブラリです。サイトのバックエンド、AuthLink サービス、モバイルアプリと併用します。AuthLink はアプリ内の承認と元の端末のハードウェア証明を検証します。システムのパスキー、指紋認証、画面ロックは要求しません。
+
+## インストール
+
+```sh
+npm install @auth-link/web
+```
+
+対応環境：React 18.2+ / 19、Vue 3.3+、TypeScript、ESM。利用するフレームワークだけをインストールしてください。ツール環境には Node 22.13+ が必要です。
+
+## 接続の流れ
+
+1. サイトのバックエンドに AuthLink のテナント資格情報を設定します。
+2. 下記の同一オリジンの作成・結果取得 API を実装します。
+3. ユーザー操作でリクエストを作成し、取得した ticket をコンポーネントに渡します。
+4. バックエンドが結果を検証・消費した後に確認完了を返します。
+
+ブラウザーからこのライブラリを呼び出せますが、テナント API キーと結果の消費処理は必ずサーバー側に置きます。標準クライアントは同一オリジンのバックエンドに接続します。独自の通信方式では `AuthLinkClient` を実装できますが、資格情報と検証をブラウザーに移さないでください。
+
+## クライアント作成
+
+```ts
+// authlink-client.ts
+import { createAuthLinkClient, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+
+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;
+  },
+  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 }).
+```
+
+meta 要素にサイトのセッションに対応する CSRF トークンを設定し、AuthLink の HTTPS オリジンを実際の設定に置き換えてください。作成処理はクリックハンドラーで実行し、マウント時の effect では実行しません。コンポーネントは既存のリクエストを監視します。同じ作成操作を再試行する際は同じ冪等キーを使います。
+
+## React
+
+```tsx
+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);
+  };
+  return ticket.purpose === 'bind'
+    ? <AuthLinkBind ticket={ticket} client={client} onConfirmed={onConfirmed} />
+    : <AuthLinkConfirm ticket={ticket} client={client} locale="en"
+        onConfirmed={onConfirmed} onExpired={() => console.log('Expired')} />;
+}
+```
+
+`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` | コンパクトなカードとキャンセル操作 | セーフエリア対応のボトムシート |
+
+```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 でサイトのセッション、`X-CSRF-Token`、リクエストの所有者を検証してください。作成時は `Idempotency-Key` も送信されます。サイトのユーザー ID はセッションから決定します。
+
+```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` を明示的に読み込みます。親要素で `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted` を上書きできます。クラス名の接頭辞は `authlink-` です。
+
+| エントリー | 内容 |
+| --- | --- |
+| `@auth-link/web` | クライアント、冪等キー、対応言語、型、基本 API |
+| `@auth-link/web/react` | React コンポーネントと hook |
+| `@auth-link/web/vue` | Vue コンポーネントと composable |
+| `@auth-link/web/styles.css` | スタイル |
+
+## セキュリティと有効期限
+
+- 数字はアプリとの目視照合用です。数字だけで認証や承認はできません。
+- ブラウザーに生成 seed、端末秘密鍵、テナント秘密情報を渡しません。
+- リクエストは最大 120 秒。コード更新で期限は延長されません。サービスとアプリはモバイルプロトコル 4 に対応する必要があります。
+- サーバー時刻と単調増加時計で残り時間を計算し、通信が止まっても期限切れの数字は隠します。更新境界で短い待ち時間が生じる場合があります。
+- アンマウントや ticket 変更で監視を中止します。インスタンス内のイベント重複防止とは別に、バックエンドで永続的な冪等処理が必要です。
+- フロントエンドのイベントは UI 更新用です。保護 API はバックエンドの信頼できる記録で判断します。
+- QR はローカル生成し、バックエンドの SVG を挿入しません。CSP は `img-src 'self' data:` を許可してください。
+
+## ライセンス
+
+UNLICENSED。公開パッケージであってもオープンソース利用許諾は付与されません。同梱ライブラリの帰属表示は `THIRD_PARTY_NOTICES.md` を参照してください。