@auth-link/web 0.0.0-stage → 0.0.1

package/docs/README.zh-CN.md

@@ -0,0 +1,282 @@
+# AuthLink Web
+
+[English](../README.md) | **简体中文** | [日本語](./README.ja.md)
+
+**AuthLink 官方前端组件包**，帮助网站接入手机绑定与 App 确认流程，支持 React 18/19、Vue 3.3+、TypeScript 和 ESM。
+
+
+## 直接调用弹窗（React、Vue 或原生 JavaScript）
+
+```ts
+import { openAuthLinkBind, openAuthLinkConfirm, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+
+// 在按钮事件中创建请求，再打开弹窗；client 为前文的同源客户端。
+const ticket = await client.create('confirm', { idempotencyKey: requestKey() });
+const modal = openAuthLinkConfirm({
+  ticket, client, locale: 'zh-CN',
+  onConfirmed: result => console.log(result.requestId),
+  onRejected: result => console.log(result.code), // REJECTED，此时弹窗已关闭
+  onClose: () => console.log('已关闭'),
+});
+// 绑定使用 openAuthLinkBind({ ticket: bindingTicket, client })。
+// modal.close(); modal.setLocale('ja');
+```
+
+React / Vue 的 AuthLinkBind、AuthLinkConfirm 挂载后也直接打开弹窗，不再内嵌在页面。React 用 onClose、Vue 用 @close 清空 ticket 并卸载组件。服务端渲染不创建弹窗或请求。支持手机窄屏、内容滚动、关闭按钮及 Escape；要求浏览器支持原生 dialog.showModal()。弹窗挂到 document.body，主题变量请配置在 :root 或 .authlink-dialog。
+
+关闭只停止前端查询，不拒绝或撤销服务端请求；请求仍按原有效期结束。确认成功或拒绝后弹窗自动关闭，分别回调 onConfirmed 或 onRejected，不触发用户关闭回调。直接调用时，页面卸载须执行 modal.destroy() 清理，它不触发用户关闭回调。切换语言用 modal.setLocale()，不会重建鉴权请求。
+
+
+## 功能
+
+- **扫码绑定**：网站显示二维码，用户使用 AuthLink App 扫码并确认绑定。
+- **手机确认**：电脑与 App 显示同步变化的六位数字，每 30 秒更新，用户核对后在 App 内批准。
+- **结果通知**：提供确认成功、拒绝、过期和错误事件，方便网站更新界面。
+- **框架支持**：React 组件与 hook、Vue 组件与 composable，以及无框架客户端。
+- **多语言与主题**：支持下表中的 13 种语言，默认简体中文；独立 CSS 和可覆盖的主题变量。
+- **生命周期管理**：请求切换或组件卸载时取消轮询，数字过期后自动隐藏。
+
+此包是 AuthLink 的网页接入层，需要配套应用后台、AuthLink 服务和手机 App。完整 AuthLink 流程校验原手机硬件密钥证明及 App 内批准，不要求系统通行密钥、指纹或锁屏；安装此包本身不会建立鉴权服务。
+
+## 接入步骤
+
+1. 在应用后台完成站点租户配置，并实现本文的创建请求、查询结果两个同源接口。
+2. 安装包、导入样式，创建指向应用后台的客户端。
+3. 用户点击绑定或验证时创建请求，将返回的 ticket 交给 React/Vue 组件。
+4. 用户在 App 确认后，应用后台验证并消费结果，组件收到可信确认事件。
+
+租户密钥只保存在应用服务端。用户是否能够继续调用受保护接口，也必须由应用后台判断。
+
+## 流程
+
+应用后台根据当前登录用户创建 `bind` 或 `confirm` 请求，前端拿到 ticket 后交给组件。组件只轮询应用后台。应用后台在验证归属、state、双重认证策略并消费一次性结果后，才返回 `confirmed`。
+
+定时数字用于电脑与手机核对；用户仍在 AuthLink App 内完成 原手机硬件密钥校验和 App 内批准。它不是用户输入网站的 TOTP 登录密码，不能单独授权。请求最长 120 秒；数字变化不延长请求有效期。前端不生成数字、不接收生成 seed，不在数字更新时新建请求。
+
+需要配套更新后的 Go 服务和客户端协议 7。服务端与 App 必须使用当前单一协议，不能只升级网页。
+
+## 安装
+
+在应用项目中安装：
+
+```sh
+npm install @auth-link/web
+```
+
+## 创建同源应用客户端
+
+```ts
+import { createAuthLinkClient, requestKey } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+
+// 不要传 AuthLink 租户 API key。此客户端只调用当前应用网站后台。
+export const client = createAuthLinkClient({
+  baseUrl: '/api/authlink',
+  csrfToken: () => readCsrfTokenFromYourCms(),
+  authLinkOrigin: 'https://你的-authlink-域名', // 公开来源，用于核对二维码
+});
+// 在用户点击“绑定”或“验证”时调用；不要在 React effect / Vue watch 中创建请求。
+const key = requestKey();
+const ticket = await client.create('bind', { idempotencyKey: key });
+// 创建响应丢失时复用 key 重试，不能每次重试都生成新 key。
+```
+
+`create` 只传用途；网站账号由应用后台的登录 session 决定。也可以自己请求后台，把 ticket 和自定义 `AuthLinkClient` 交给组件，适配 Axios、GraphQL 或其他认证方式。
+
+## React
+
+```tsx
+import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/react';
+import type { Ticket } from '@auth-link/web';
+import { client } from './authlink-client'; // 上文创建的客户端
+
+export function BindPanel({ ticket }: { ticket: Ticket }) {
+  return <AuthLinkBind ticket={ticket} client={client} locale="zh-CN"
+    onConfirmed={result => showBound(result.requestId)}
+    onRejected={() => showRejected()} onExpired={() => showExpired()}
+    onError={error => showNetworkError(error.message)} />;
+}
+
+export function ConfirmPanel({ ticket }: { ticket: Ticket }) {
+  return <AuthLinkConfirm ticket={ticket} client={client} locale="zh-CN"
+    onConfirmed={result => showConfirmed(result.requestId)} />;
+}
+```
+
+确认组件默认只显示动态数字；`showQr` 可额外显示扫码入口。绑定组件始终显示二维码。`onRefresh` 可提供重新创建请求的函数；仅过期后显示该按钮。组件自身的“重试”只恢复当前请求，不创建第二个请求。
+
+未指定 `locale` 时使用简体中文；不支持的语言代码也回退到简体中文。组件根元素设置对应的 `lang`，语言切换不会重新创建鉴权请求。
+
+React 入口保留 `"use client"`，可用于 Next.js 客户端组件。导入包和 SSR 渲染不会创建请求。将 client 与 ticket 保持为稳定对象，例如模块级 client 和 React state 中的 ticket。卸载/切换 ticket 会取消旧轮询；StrictMode 不会创建额外请求。
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { AuthLinkBind, AuthLinkConfirm } from '@auth-link/web/vue';
+import type { Ticket, Confirmation } from '@auth-link/web';
+import '@auth-link/web/styles.css';
+import { client } from './authlink-client'; // 上文创建的客户端
+defineProps<{ ticket: Ticket; mode: 'bind' | 'confirm' }>();
+function confirmed(result: Confirmation) { showConfirmed(result.requestId); }
+</script>
+
+<template>
+  <AuthLinkBind v-if="mode === 'bind'" :ticket="ticket" :client="client"
+    locale="zh-CN" @confirmed="confirmed" @expired="showExpired" />
+  <AuthLinkConfirm v-else :ticket="ticket" :client="client"
+    locale="zh-CN" @confirmed="confirmed" @rejected="showRejected" />
+</template>
+```
+
+拒绝时返回 `{ status: 'rejected', code: 'REJECTED', requestId, purpose }`。`REJECTED` 是 SDK 业务状态码，不是 HTTP 状态码或授权凭证。组件自动关闭，不再显示“已拒绝 / 重新发起”面板，也不触发 `onClose`；提示和重新发起由接入网站在回调中决定。React / Vue 请在 `onRejected` / `@rejected` 中清空 ticket、卸载组件。无 UI 的 hook 仍保留 `snapshot.status === 'rejected'`，供自定义界面使用。
+
+Vue 可通过 `:on-refresh="createNewRequest"` 提供重新创建操作。`useAuthLink(() => options)` composable 与 React 的 `useAuthLink(options)` hook 可用于自定义界面，返回 `snapshot` 和 `retry`；Vue 的 snapshot 是浅 ref。
+
+## 选择弹窗样式
+
+初始化时通过 `variant` 选择样式，**不传时默认 A**。
+
+| 参数值 | 电脑端 | 手机端 |
+| --- | --- | --- |
+| `A`（默认） | 极简居中卡片、细线数字更新进度条 | 居中卡片 |
+| `B` | 二维码和核对码左右分栏 | 自动纵向排列 |
+| `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 可响应式切换 `variant`，不会重新发起请求；无效的运行时值回退到 A。B / C 的底部“取消”和右上角关闭行为一致，仅停止前端观察，不会替用户拒绝服务端请求。确认成功仍自动关闭。关闭图标保留 44px 点击区域和键盘焦点提示。
+
+## 组件参数与事件
+
+`AuthLinkBind` 用于绑定二维码，`AuthLinkConfirm` 用于手机确认。两者使用相同的主要参数：
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `ticket` | `Ticket`，必填 |应用后台创建的当前请求；组件不会自行创建请求 |
+| `client` | `AuthLinkClient`，必填 | 查询应用后台结果的客户端 |
+| `locale` | `Locale`，见下表 | 界面语言，默认 `zh-CN` |
+| `variant` | `DialogVariant` | `A`（默认）、`B` 或 `C`；只改变布局 |
+| `showQr` | `boolean` | 确认组件是否额外显示二维码；绑定组件始终显示 |
+| `intervalMs` | `number` | 结果轮询间隔，默认 1500 毫秒 |
+| `onRefresh` | `() => void` | 过期后，由网站重新创建请求并更新 ticket |
+
+| React 回调 / Vue 事件 | 参数 | 触发时机 |
+| --- | --- | --- |
+| `onConfirmed` / `confirmed` | `Confirmation` |应用后台完成结果验证和消费后 |
+| `onRejected` / `rejected` | `Rejection` | 手机拒绝请求，弹窗自动关闭 |
+| `onExpired` / `expired` | 无 | 请求已过期 |
+| `onError` / `error` | `Error` | 网络错误、响应校验失败或成功回调执行失败等 |
+
+业务处理以 `requestId` / `verificationId` 做持久化幂等。前端成功事件用于展示状态，不能作为后台接口放行凭据。
+
+## 导入入口
+
+| 入口 | 用途 |
+| --- | --- |
+| `@auth-link/web` | `createAuthLinkClient`、`requestKey`、公开类型及无框架工具 |
+| `@auth-link/web/react` | React 组件和 `useAuthLink` |
+| `@auth-link/web/vue` | Vue 组件和 `useAuthLink` |
+| `@auth-link/web/styles.css` | 组件样式，需显式导入 |
+
+##应用后台接口约定
+
+默认前缀 `/api/authlink`；下面两个接口由接入方实现，**不是直接把浏览器请求转发到租户密钥 API**。
+
+### `POST /requests`
+
+浏览器携带自己的应用session、`X-CSRF-Token`、稳定的 `Idempotency-Key`，body：
+
+```json
+{"purpose":"bind"}
+```
+
+后台从 session 取得用户 ID，创建并持久保存 state、创建/消费幂等键、用户/session 关联，然后调用 AuthLink 服务端创建请求。返回其公开 ticket：
+
+```ts
+type Ticket = {
+  requestId: string;
+  purpose: 'bind' | 'confirm';
+  qr: string; // AuthLink 返回的 QR JSON，不是 HTML
+  pairingCode: string;
+  expiresAt: string;
+  displayCode: {
+    value: string; // 六位数字，保留前导零
+    serverTime: string; validUntil: string;
+    periodSeconds: 30;
+  };
+};
+```
+
+### `POST /requests/{requestId}/result`
+
+同样验证 session、CSRF 和请求归属。后台调用 AuthLink 状态接口，将 `displayCode` 原样返回，不能缓存跨过 `validUntil`。新代码由后台实时获取，不是前端自行生成。
+
+尚未完成时返回 `{requestId,status,displayCode?}`；状态可为 new / pending / approved / consumed / rejected / expired。`approved` 不能触发成功事件。
+
+收到 approved / consumed 后，后台使用保存的稳定消费幂等键调用 `/consume`，核对完整结果，在自己数据库事务中记录此次 session 的确认，再返回已验证的回执。组件确认所需最小字段：
+
+```json
+{
+  "status":"confirmed",
+  "requestId":"43字符请求ID",
+  "verificationId":"43字符结果ID",
+  "purpose":"confirm",
+  "authenticationPolicy":"device-presence.v1",
+  "expiresAt":"与创建请求完全一致的期限"
+}
+```
+
+服务端必须在同一事务内记录已验证的确认结果，并校验请求归属。网页事件只用于更新界面；受保护接口必须依赖后台的可信确认记录，不能依赖 JS 回调或浏览器传来的 confirmed。
+
+## 数字、时钟与安全
+
+- 每个请求独立派生数字生成 seed；seed 只通过 claim 发给手机，并纳入设备签名上下文。网页只得到当前数字、服务端时间和本步期限。
+- 倒计时使用服务端时间锚点和单调时钟；本机系统时钟错误不直接导致倒计时漂移。网络延迟仍有影响，跨步时可能短暂显示“正在更新数字”，稳定后再核对。
+- 旧数字一过本步期限就隐藏，即使网络请求仍未返回。整个请求过期、拒绝或失败会隐藏数字和二维码。
+- 组件按请求检查成功结果、用途、双重认证策略和有效期。取消、卸载和切换请求后，旧响应不能触发成功回调。
+- 每个组件实例对同一请求只发一次成功事件；刷新或重新挂载不替代网站持久化幂等。
+- 包不接收网站业务授权内容，不提供 apiKey 配置，不执行支付/授权等业务操作。
+- 二维码在浏览器内生成，忽略后台 qrSvg，不使用 innerHTML；不上传给第三方图片服务。应用 CSP 需允许 `img-src 'self' data:`。
+
+## 样式与语言
+
+CSS 单独导入，所有类使用 `authlink-` 前缀。可在宿主容器覆盖 `--authlink-foreground`、`--authlink-background`、`--authlink-accent`、`--authlink-muted`。面板语言见下表，默认简体中文。
+
+
+| 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 |
+
+可以从根入口导入 `supportedLocales` 获取支持列表。文档默认英文，另有中文与日文版本。
+
+## 兼容性
+
+React 18.2+ / 19、Vue 3.3+、TypeScript、ESM。React 和 Vue 是可选 peer，只安装所用框架。构建工具环境需 Node 22.13+。

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "@auth-link/web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "private": false,
+  "description": "Three responsive AuthLink dialog layouts for phone binding and mobile confirmation. Framework-neutral API, React and Vue, 13 languages, Simplified Chinese by default.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/types/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/types/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm test && npm run build",
+    "release": "npm publish --access public --registry=https://registry.npmjs.org",
+    "prepack": "npm run build",
+    "prepublishOnly": "node scripts/check-publish.mjs && npm run check",
+    "smoke": "node scripts/smoke-package.mjs"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "vue": "^3.3.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "esbuild": "0.28.2",
+    "jsdom": "29.1.1",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5",
+    "vue": "3.5.44",
+    "qrcode-generator": "2.0.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "authlink",
+    "authentication",
+    "mobile-authentication",
+    "device-binding",
+    "qr-code",
+    "react",
+    "vue",
+    "typescript",
+    "confirmation",
+    "i18n"
+  ],
+  "author": "auth-link"
+}