@auth-link/web 0.0.2 → 0.0.4

package/docs/go-vue.zh-CN.md

@@ -0,0 +1,260 @@
+# Go + Vue：从登录、绑定到确认发布
+
+[English](./go-vue.en.md) | **简体中文** | [日本語](./go-vue.ja.md) · [SDK 参数](./README.zh-CN.md)
+
+本指南按实际 Go CMS + Vue 3 的接入顺序整理。下面使用可替换的示例域名，不依赖某台电脑的配置、测试账号、密码或租户密钥。网站负责登录、数据库和业务接口；Web SDK 负责展示和观察请求，Go SDK 负责后台调用与回执校验。
+
+## 1. 区分三个来源并安装 SDK
+
+| 角色 | 示例来源 | 配置位置 |
+| --- | --- | --- |
+| Vue | `https://cms.example.com` | `apiOrigin` 指向下方的 Go 后台 |
+| Go CMS API | `https://cms-api.example.com` | `baseUrl=https://cms-api.example.com/api/authlink` |
+| AuthLink API | `https://api.getauthlink.com` | Go SDK 的 `Origin`；浏览器的 `authLinkOrigin` |
+
+AuthLink API 使用生产地址 `https://api.getauthlink.com`；Vue 网站和 Go CMS 的域名仍是接入方自己的示例，不能替换成 AuthLink 官网域名。
+
+登记租户的站点 origin 是 Vue 网站来源；Go SDK 的 `Origin` 和凭据导出 JSON 中的 API origin 是 AuthLink API 来源。浏览器的 `baseUrl` 指向 Go 业务后台，不能指向 AuthLink 租户 API。公开运行配置只包含这三个 origin；`TenantID`、`APIKey` 保留在 Go 私密配置或环境变量中。
+
+```sh
+npm install @auth-link/web@latest vue
+# In your Go backend module, after unpacking the supplied Go SDK:
+go mod edit -replace=authlink.local/sdk=./third_party/authlink-go
+go mod edit -require=authlink.local/sdk@v0.0.0
+go mod tidy
+```
+
+Go SDK 当前随源码或官网的 Go SDK 源码包交付，保留 `third_party/authlink-go/go.mod`，导入 `authlink "authlink.local/sdk"`；这不是公共 `go get` 地址，也不是 npm 包内置的后台。用可信后台配置调用 `authlink.New(authlink.Config{Origin: authOrigin, TenantID: tenantID, APIKey: apiKey})`。
+
+## 2. 先完成网站登录，再读取会话
+
+本站现有登录接口（参考 CMS 为 `POST /api/login`）验证用户后签发 HttpOnly、Secure 的 session Cookie。Vue 用 `credentials:'include'` 调用 Go 的 `GET /api/session`。已登录时返回 `authenticated:true` 与 `csrf`；未登录时先回到网站登录流程。
+
+`csrf` 是本 CMS 的响应字段名；SDK 配置项仍叫 `csrfToken`，写成 `csrfToken: () => session.value?.csrf ?? ''` 即可。SDK 不要求你的后台一定返回名为 `csrfToken` 的字段。令牌由 Go 为当前 session 生成并保存，浏览器只读取，不能用租户密钥或手机核对码代替。创建和结果查询均需验证 `X-CSRF-Token` 与同一 session 的值一致。
+
+Vue 与 API 使用同一 HTTPS 主域名下的两个子域名时，是跨 origin、同 site。参考 CMS 的 host-only Cookie 不设置 `Domain`，使用 `SameSite=Strict; Secure; HttpOnly; Path=/`；请求目标仍为 API 域名。真正跨 site 时还需按浏览器 Cookie 策略配置，不能只依靠 CORS。
+
+## 3. Go 配置 CORS 与业务路由
+
+```http
+Access-Control-Allow-Origin: https://cms.example.com
+Access-Control-Allow-Credentials: true
+Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
+Access-Control-Allow-Headers: Content-Type, X-CSRF-Token, Idempotency-Key
+Vary: Origin
+Cache-Control: no-store
+```
+
+只为精确允许的 Vue origin 返回这些 CORS 头；允许来源的正常和错误响应都要携带。`OPTIONS` 先验证来源、方法和请求头，成功返回 204，不要求登录或 CSRF；随后实际请求才验证登录、来源、CSRF 和归属。不能用 `*` 或无条件反射来源。上面包含 CMS 草稿编辑所用的 PUT；只接入 SDK 的站点可按实际路由收窄。
+
+| 网站自己的路由 | 请求 | 返回 |
+| --- | --- | --- |
+| `GET /api/session` | — | `{authenticated:true, csrf:"…", subject:"…", username:"…"}`；未登录： `{authenticated:false}` |
+| `POST /api/authlink/requests` | `{purpose:"bind"}` 或 `{purpose:"confirm",postId,version}`; `Idempotency-Key` | 公开 `Ticket` |
+| `POST /api/authlink/requests/{id}/result` | `{}`；当前 session + CSRF | 待处理状态/displayCode 或已验证的 `confirmed` 回执 |
+| `POST /api/posts/{id}/publish` | `{requestId,version}`; 当前 session + CSRF | `{ok:true}` 校验已保存的确认记录和业务意图后返回 |
+
+上述路由由 Go CMS 实现，不是安装 Web SDK 后自动出现的接口。`postId` / `version` / `/publish` 是本例业务约定，不是 AuthLink 平台字段。
+
+## 4. 创建前落库，消费后再返回 confirmed
+
+```text
+Vue → Go /api/session → current session + csrf
+Vue → Go /api/authlink/requests → Go SDK CreateRequest → public ticket
+Vue dialog → Go /api/authlink/requests/{id}/result → Status + Consume
+Go commits verified receipt → Vue confirmed event
+Vue → Go /api/posts/{id}/publish → validate saved intent/receipt → publish
+```
+
+Go 从可信 session 取稳定用户 ID，不能接受浏览器自报的 `externalUserId`。创建顺序：
+
+1. 校验 purpose、创建幂等键，以及文章归属和当前版本（若有）。
+2. 生成独立随机 state 和消费幂等键；把原创建键、CreateInput、当前用户/session 和业务意图落库，再向 AuthLink 发请求。网络结果不明时从数据库恢复同一记录、输入和键。
+3. 调用 `CreateRequest`，保存返回的 requestId、原始 expiresAt 与 ticket，去掉可选 qrSvg 后返回公开 ticket。对同一 session + 创建键加唯一约束，键复用到其他 purpose / 文章 / 版本时返回冲突。
+4. 结果接口按 requestId + 当前 session 加锁读取记录；已保存回执直接复用。用 `Status` 查询，只有 approved / consumed 才以保存的 `Expected` 和消费键调用 `Consume`。SDK 校验失败不能返回成功。
+5. 在事务里保存回执、用户/session 确认记录和审计，requestId / verificationId 建唯一约束，提交成功后才返回 `confirmed`。待处理状态保留原 displayCode，不跨数字期限缓存。
+
+下面是 SDK 调用层代码，**不是包含登录、数据库和路由的完整 HTTP 服务**；注释中的落库与事务必须由你的 Go 后台实现。初始化客户端、构造 Input、所有权检查及请求记录的读写按上述步骤完成。
+
+```go
+package cmsauth
+
+import (
+    "context"
+    authlink "authlink.local/sdk"
+)
+
+// Load this record from your database for the authenticated user/session.
+// Save Input (including State), CreateKey and ConsumeKey BEFORE calling Create.
+// Intent (post ID/version), ownership and unique constraints belong in your DB.
+type StoredRequest struct {
+    Input authlink.CreateInput
+    CreateKey string
+    ConsumeKey string
+    Ticket authlink.Ticket
+}
+
+// On network retries, load the SAME record; do not regenerate State or keys.
+func Create(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (authlink.Ticket, error) {
+    return sdk.CreateRequest(ctx, saved.Input, saved.CreateKey)
+}
+
+type PublicConfirmation struct {
+    Status string `json:"status"`
+    RequestID string `json:"requestId"`
+    VerificationID string `json:"verificationId"`
+    Purpose string `json:"purpose"`
+    ExpiresAt string `json:"expiresAt"`
+    AuthenticationPolicy string `json:"authenticationPolicy"`
+}
+
+// Caller checks session/CSRF/ownership, locks the saved record and first returns
+// any already-saved receipt. For a new confirmed result, caller must persist
+// the receipt and confirmation in a DB transaction BEFORE returning HTTP 200.
+func Poll(ctx context.Context, sdk *authlink.Client, saved StoredRequest) (any, error) {
+    status, err := sdk.Status(ctx, saved.Ticket.RequestID)
+    if err != nil { return nil, err }
+    if status.Status != "approved" && status.Status != "consumed" { return status, nil }
+    result, err := sdk.Consume(ctx, authlink.Expected{
+        RequestID: saved.Ticket.RequestID,
+        ExternalUserID: saved.Input.ExternalUserID,
+        Purpose: saved.Input.Purpose,
+        State: saved.Input.State,
+        ExpiresAt: saved.Ticket.ExpiresAt,
+    }, saved.ConsumeKey)
+    if err != nil { return nil, err }
+    return PublicConfirmation{
+        Status: "confirmed", RequestID: result.RequestID,
+        VerificationID: result.VerificationID, Purpose: result.Purpose,
+        ExpiresAt: saved.Ticket.ExpiresAt, AuthenticationPolicy: result.AuthenticationPolicy,
+    }, nil
+}
+```
+
+## 5. Vue 组件：稳定 ticket、按业务绑定创建、清理与重试
+
+完整文件也包含在包内 [examples/vue-cms.vue](../examples/vue-cms.vue)。网站登录后挂载它，传入可信 `apiOrigin`、`authLinkOrigin`，可选传入后台加载的草稿 `post={id,version}`。父层用当前登录 session 的标识做组件 key，退出、重新登录或切换账号时先卸载旧组件并清空会话、旧 ticket、幂等键和待发布操作，再挂载新组件。不要只改用户名后继续使用旧 ticket。
+
+```vue
+<script setup lang="ts">
+import { markRaw, onMounted, onUnmounted, ref, shallowRef } from 'vue';
+import { createAuthLinkClient, requestKey, validateTicket } 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';
+
+type Post = { id: string; version: number };
+type Publication = Post & { requestId: string };
+// Supply trusted deployment configuration. Mount after site login and remount
+// with :key="session.subject" after login, logout or account/session changes.
+const props = defineProps<{ apiOrigin: string; authLinkOrigin: string; post?: Post }>();
+const session = ref<{ authenticated: boolean; csrf?: string } | null>(null);
+const ticket = shallowRef<Ticket | null>(null);
+const publication = shallowRef<Post | null>(null);
+const retryPublish = shallowRef<Publication | null>(null);
+const busy = ref(false), message = ref('');
+let creation: { signature: string; key: string } | null = null;
+const lifetime = new AbortController();
+const client = markRaw(createAuthLinkClient({
+  baseUrl: `${props.apiOrigin}/api/authlink`,
+  allowedBackendOrigins: [props.apiOrigin],
+  credentials: 'include',
+  csrfToken: () => session.value?.csrf ?? '',
+  authLinkOrigin: props.authLinkOrigin,
+}));
+
+async function api(path: string, body?: unknown, headers: Record<string, string> = {}) {
+  const response = await fetch(`${props.apiOrigin}${path}`, {
+    method: body === undefined ? 'GET' : 'POST',
+    credentials: 'include', cache: 'no-store', redirect: 'error',
+    signal: lifetime.signal,
+    headers: body === undefined ? {} : {
+      'Content-Type': 'application/json', 'X-CSRF-Token': session.value?.csrf ?? '', ...headers,
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const value = await response.json();
+  if (response.status === 401) {
+    session.value = null; closeTicket(); retryPublish.value = null; creation = null;
+  }
+  if (!response.ok) throw new Error(value.code ?? 'REQUEST_FAILED');
+  return value;
+}
+function closeTicket() { ticket.value = null; publication.value = null; }
+function showError(error: Error) { message.value = error.message; }
+function finish(text: string) { closeTicket(); message.value = text; }
+
+async function start(purpose: Mode, post?: Post) {
+  if (busy.value || ticket.value || !session.value?.authenticated) return;
+  busy.value = true; message.value = ''; retryPublish.value = null;
+  const intent = post ? { id: post.id, version: post.version } : null;
+  const signature = JSON.stringify({ purpose, postId: intent?.id, version: intent?.version });
+  try {
+    if (creation?.signature !== signature) creation = { signature, key: requestKey() };
+    // SDK create() sends only {purpose}. Business fields use your own API.
+    const value = intent
+      ? validateTicket(await api('/api/authlink/requests', {
+          purpose, postId: intent.id, version: intent.version,
+        }, { 'Idempotency-Key': creation.key }), purpose, props.authLinkOrigin)
+      : await client.create(purpose, { idempotencyKey: creation.key, signal: lifetime.signal });
+    if (lifetime.signal.aborted) return;
+    publication.value = intent; ticket.value = value; creation = null;
+  } catch (error) {
+    if (!lifetime.signal.aborted) showError(error as Error);
+    // Retain creation.key for a retry of the SAME purpose/post/version.
+  } finally { busy.value = false; }
+}
+async function publish() {
+  const intent = retryPublish.value;
+  if (!intent || busy.value) return;
+  busy.value = true;
+  try {
+    await api(`/api/posts/${intent.id}/publish`, { version: intent.version, requestId: intent.requestId });
+    retryPublish.value = null; message.value = 'Published. Reload your posts from the backend.';
+  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
+  finally { busy.value = false; }
+}
+async function confirmed(result: Confirmation) {
+  const intent = publication.value;
+  closeTicket();
+  if (intent) { retryPublish.value = { ...intent, requestId: result.requestId }; await publish(); }
+  else message.value = 'Verified. Reload account status from the backend.';
+}
+onMounted(async () => {
+  try {
+    const value = await api('/api/session');
+    if (value.authenticated !== true || typeof value.csrf !== 'string' || !value.csrf) {
+      throw new Error('LOGIN_REQUIRED');
+    }
+    session.value = value;
+  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
+});
+onUnmounted(() => { lifetime.abort(); closeTicket(); creation = null; retryPublish.value = null; });
+</script>
+
+<template>
+  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('bind')">Bind phone</button>
+  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm')">Confirm</button>
+  <button v-if="post" :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm', post)">Confirm publication</button>
+  <button v-if="retryPublish" :disabled="busy || !!ticket" @click="publish">Retry the same publication</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 a new request')" @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 a new request')" @error="showError" />
+  <p role="status">{{ message }}</p>
+</template>
+```
+
+普通绑定/确认使用 `client.create(purpose, {idempotencyKey})`。该方法只发送 purpose，**不能传入 postId/version 扩展请求体**。确认发布通过自己的 fetch 发送这些业务字段，再用 `validateTicket(response, 'confirm', authLinkOrigin)` 校验；后续弹窗查询仍复用官方 client。
+
+同一次创建失败保留同一个键；用途或文章版本改变才换新键。`shallowRef` 保存 ticket，`markRaw` 保存客户端。组件挂载只打开和观察已有请求；不在 mounted/watch 中创建请求。关闭、拒绝和过期清空 ticket；网络错误保留弹窗，允许重试原请求。确认成功先清空 ticket，再调用独立业务接口；失败保留同一个 requestId / 文章 / 版本用于重试，先从后台确认真实状态后再刷新页面。上例省略网站自己的登录表单、文章列表和错误码中文映射。
+
+## 6. 发布接口必须再做后台检查
+
+`confirmed` 回调只触发界面更新与下一次 API 请求，不是放行凭据。Go 的发布事务必须验证当前 session 对应的已落库回执，purpose=confirm、意图=publish、同一 postId、同一 version、文章归属和草稿状态，以及首次应用时尚未过期。成功时更新文章并标记请求 applied；重试已应用的同一操作返回原成功，不重复发布或写审计。请求不能用于另一文章或新版本，修改内容后须重新确认。前端不把文章内容、action 或 transactionHash 塞入 AuthLink 消费回执。
+
+## 验收顺序
+
+登录 → 读取 session → 查询后台真实账号状态（参考 CMS 通过 overview 调用 Go SDK `AccountStatus`）→ 未绑定时 bind → 手机扫码批准 → 后台消费并刷新账号状态 → 保存草稿 → 按 postId/version confirm → 手机批准 → 结果消费落库 → 独立发布接口 → 重复发布/错误版本/拒绝/过期验证。真实设备验收仍由用户在手机上完成；本地编译和模拟 HTTP 测试不能代替这一步。

package/examples/vue-cms.vue

@@ -0,0 +1,109 @@
+<script setup lang="ts">
+import { markRaw, onMounted, onUnmounted, ref, shallowRef } from 'vue';
+import { createAuthLinkClient, requestKey, validateTicket } 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';
+
+type Post = { id: string; version: number };
+type Publication = Post & { requestId: string };
+// Supply trusted deployment configuration. Mount after site login and remount
+// with :key="session.subject" after login, logout or account/session changes.
+const props = defineProps<{ apiOrigin: string; authLinkOrigin: string; post?: Post }>();
+const session = ref<{ authenticated: boolean; csrf?: string } | null>(null);
+const ticket = shallowRef<Ticket | null>(null);
+const publication = shallowRef<Post | null>(null);
+const retryPublish = shallowRef<Publication | null>(null);
+const busy = ref(false), message = ref('');
+let creation: { signature: string; key: string } | null = null;
+const lifetime = new AbortController();
+const client = markRaw(createAuthLinkClient({
+  baseUrl: `${props.apiOrigin}/api/authlink`,
+  allowedBackendOrigins: [props.apiOrigin],
+  credentials: 'include',
+  csrfToken: () => session.value?.csrf ?? '',
+  authLinkOrigin: props.authLinkOrigin,
+}));
+
+async function api(path: string, body?: unknown, headers: Record<string, string> = {}) {
+  const response = await fetch(`${props.apiOrigin}${path}`, {
+    method: body === undefined ? 'GET' : 'POST',
+    credentials: 'include', cache: 'no-store', redirect: 'error',
+    signal: lifetime.signal,
+    headers: body === undefined ? {} : {
+      'Content-Type': 'application/json', 'X-CSRF-Token': session.value?.csrf ?? '', ...headers,
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const value = await response.json();
+  if (response.status === 401) {
+    session.value = null; closeTicket(); retryPublish.value = null; creation = null;
+  }
+  if (!response.ok) throw new Error(value.code ?? 'REQUEST_FAILED');
+  return value;
+}
+function closeTicket() { ticket.value = null; publication.value = null; }
+function showError(error: Error) { message.value = error.message; }
+function finish(text: string) { closeTicket(); message.value = text; }
+
+async function start(purpose: Mode, post?: Post) {
+  if (busy.value || ticket.value || !session.value?.authenticated) return;
+  busy.value = true; message.value = ''; retryPublish.value = null;
+  const intent = post ? { id: post.id, version: post.version } : null;
+  const signature = JSON.stringify({ purpose, postId: intent?.id, version: intent?.version });
+  try {
+    if (creation?.signature !== signature) creation = { signature, key: requestKey() };
+    // SDK create() sends only {purpose}. Business fields use your own API.
+    const value = intent
+      ? validateTicket(await api('/api/authlink/requests', {
+          purpose, postId: intent.id, version: intent.version,
+        }, { 'Idempotency-Key': creation.key }), purpose, props.authLinkOrigin)
+      : await client.create(purpose, { idempotencyKey: creation.key, signal: lifetime.signal });
+    if (lifetime.signal.aborted) return;
+    publication.value = intent; ticket.value = value; creation = null;
+  } catch (error) {
+    if (!lifetime.signal.aborted) showError(error as Error);
+    // Retain creation.key for a retry of the SAME purpose/post/version.
+  } finally { busy.value = false; }
+}
+async function publish() {
+  const intent = retryPublish.value;
+  if (!intent || busy.value) return;
+  busy.value = true;
+  try {
+    await api(`/api/posts/${intent.id}/publish`, { version: intent.version, requestId: intent.requestId });
+    retryPublish.value = null; message.value = 'Published. Reload your posts from the backend.';
+  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
+  finally { busy.value = false; }
+}
+async function confirmed(result: Confirmation) {
+  const intent = publication.value;
+  closeTicket();
+  if (intent) { retryPublish.value = { ...intent, requestId: result.requestId }; await publish(); }
+  else message.value = 'Verified. Reload account status from the backend.';
+}
+onMounted(async () => {
+  try {
+    const value = await api('/api/session');
+    if (value.authenticated !== true || typeof value.csrf !== 'string' || !value.csrf) {
+      throw new Error('LOGIN_REQUIRED');
+    }
+    session.value = value;
+  } catch (error) { if (!lifetime.signal.aborted) showError(error as Error); }
+});
+onUnmounted(() => { lifetime.abort(); closeTicket(); creation = null; retryPublish.value = null; });
+</script>
+
+<template>
+  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('bind')">Bind phone</button>
+  <button :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm')">Confirm</button>
+  <button v-if="post" :disabled="busy || !!ticket || !session?.authenticated" @click="start('confirm', post)">Confirm publication</button>
+  <button v-if="retryPublish" :disabled="busy || !!ticket" @click="publish">Retry the same publication</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 a new request')" @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 a new request')" @error="showError" />
+  <p role="status">{{ message }}</p>
+</template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-link/web",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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",
@@ -11,7 +11,8 @@
     "docs",
     "CHANGELOG.md",
     "THIRD_PARTY_NOTICES.md",
-    "LICENSE"
+    "LICENSE",
+    "examples/vue-cms.vue"
   ],
   "sideEffects": [
     "**/*.css"