@auth-link/web 0.0.4 → 0.0.5

package/examples/react-client.tsx

@@ -0,0 +1,42 @@
+"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>
+  </>;
+}

package/examples/vue-client.vue

@@ -0,0 +1,55 @@
+<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';
+
+// 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; });
+</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>
+</template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-link/web",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "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",
@@ -8,11 +8,14 @@
   "files": [
     "dist",
     "README.md",
-    "docs",
+    "docs/README.en.md",
+    "docs/README.zh-CN.md",
+    "docs/README.ja.md",
     "CHANGELOG.md",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE",
-    "examples/vue-cms.vue"
+    "examples/vue-client.vue",
+    "examples/react-client.tsx"
   ],
   "sideEffects": [
     "**/*.css"

package/docs/go-vue.en.md

@@ -1,256 +0,0 @@
-# Go + Vue: login, binding and confirmed publication
-
-**English** | [简体中文](./go-vue.zh-CN.md) | [日本語](./go-vue.ja.md) · [SDK reference](./README.en.md)
-
-This walkthrough follows a working Go CMS and Vue 3 integration. Example origins replace local deployment details; no test users, passwords or tenant credentials are required by these examples. Your website implements login, persistence and business routes. The web package displays and observes requests; the Go SDK calls AuthLink and validates receipts.
-
-## 1. Install and separate the three origins
-
-| Role | Example origin | Configuration |
-| --- | --- | --- |
-| Vue | `https://cms.example.com` | `apiOrigin` is the Go backend below |
-| 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`; browser `authLinkOrigin` |
-
-The AuthLink API uses production origin `https://api.getauthlink.com`; the Vue and Go CMS origins remain examples for your own website, not the AuthLink marketing site.
-
-Register the Vue site's origin for the tenant. The Go SDK `Origin` and the API origin in an exported credential JSON identify the AuthLink API. Browser `baseUrl` targets your Go application API. Keep TenantID/APIKey in private backend configuration; public runtime configuration contains origins only.
-
-```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
-```
-
-The Go SDK is supplied as source or a Go SDK archive from your AuthLink website, not a public Go module or an npm backend. Preserve its own go.mod and import `authlink "authlink.local/sdk"`. Initialize it with trusted `authlink.Config{Origin: authOrigin, TenantID: tenantID, APIKey: apiKey}` through `authlink.New`.
-
-## 2. Log in to the website and load its session
-
-Your login route (the reference CMS uses `POST /api/login`) issues a Secure, HttpOnly session cookie. Fetch Go's `GET /api/session` with `credentials:'include'`; require `authenticated:true` and the current `csrf` value before opening requests. Otherwise return to your own login flow.
-
-Here the JSON property is **csrf**, while the SDK option is **csrfToken**: use `csrfToken: () => session.value?.csrf ?? ''`. A backend is free to name the response property differently. Go generates and saves the token for that session and validates X-CSRF-Token on creation AND result polling. Never substitute a tenant key or matching number.
-
-Two HTTPS subdomains under the same site are cross-origin but same-site. The reference API sets a host-only cookie with `SameSite=Strict; Secure; HttpOnly; Path=/`, without Domain. Requests still target the API host. For a truly cross-site setup, account for browser cookie policy as well as CORS.
-
-## 3. Configure Go CORS and application routes
-
-```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
-```
-
-Return these headers only for an exact allowed Vue origin, including allowed-origin error responses. Validate the origin/method/headers of OPTIONS and return 204 before requiring login or CSRF; authenticate and check CSRF/ownership on actual requests. Do not reflect arbitrary origins or use `*`. PUT is for CMS draft editing; narrow it to the routes you implement.
-
-| Application route | Input | Output |
-| --- | --- | --- |
-| `GET /api/session` | — | `{authenticated:true, csrf:"…", subject:"…", username:"…"}`; logged out: `{authenticated:false}` |
-| `POST /api/authlink/requests` | `{purpose:"bind"}` or `{purpose:"confirm",postId,version}`; `Idempotency-Key` | Public `Ticket` |
-| `POST /api/authlink/requests/{id}/result` | `{}`; current session + CSRF | Pending status/displayCode or verified `confirmed` receipt |
-| `POST /api/posts/{id}/publish` | `{requestId,version}`; current session + CSRF | `{ok:true}` after checking the saved confirmation and intent |
-
-Your Go application implements all four routes. postId/version and the publication route are application-specific conventions, not AuthLink fields.
-
-## 4. Persist before creation; commit verification before 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
-```
-
-Derive the stable user ID from the authenticated session. Before an upstream call, validate purpose/idempotency and optional post ownership/version; independently generate state and a consume key, then persist CreateInput, the browser creation key, session/user and publication intent. A network retry loads the same record and keys. Enforce unique (session, creation key) and reject reuse for a different purpose/post/version.
-
-Save the returned ticket, requestId and original expiresAt; omit optional qrSvg before returning public data. The result route locks the request owned by the current session and reuses any saved receipt. Call Status, then Consume only for approved/consumed using Expected reconstructed from saved data. Persist the verified public receipt, session confirmation and audit transactionally with unique requestId/verificationId constraints; commit before returning confirmed. Pending results preserve displayCode without caching beyond its validity.
-
-This is the SDK-call layer, **not a complete HTTP server**. Your application must implement the database/transaction and ownership steps described above and in the comments.
-
-```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 lifecycle and business-bound requests
-
-The complete file is also shipped as [examples/vue-cms.vue](../examples/vue-cms.vue). Mount after site login with trusted apiOrigin/authLinkOrigin and an optional saved draft `post={id,version}`. Key the parent component by the current authenticated session identity. Unmount on logout, login rotation or account change; clear old tickets, creation keys and pending publication before mounting a new instance.
-
-```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})` sends purpose only. To bind confirmation to a post/version, use your own fetch with those business fields, validate the result with `validateTicket(response, 'confirm', authLinkOrigin)`, and reuse the official client for observation. Keep the same creation key after an uncertain failure, and change it when purpose/post/version changes. Keep tickets in shallowRef and clients in markRaw.
-
-Mounting a dialog observes an existing request; never create from mounted/watch. Clear the ticket on close/rejection/expiry. Leave the dialog mounted on network errors to retry that request. On confirmation, dismiss it and call the independent publish route; preserve the same requestId/post/version if that call fails. Reload actual account/post state from the backend. The sample omits your login form, post list and application error translations.
-
-## 6. Recheck confirmation in the publish transaction
-
-The browser confirmed event is not authorization. Go must load the verified receipt for the current session and check purpose=confirm, intent=publish, post ownership, the same postId/version, draft state and expiry on first application. Update the post and mark the intent applied atomically. A retry of that same applied operation returns success without duplicate publication/audit. Another post or edited version requires a new confirmation. Do not add action, transactionHash or document content to the AuthLink receipt.
-
-## Acceptance sequence
-
-Site login → session bootstrap → backend AccountStatus (the reference CMS exposes it through overview) → bind if unbound → phone approval → consume and refresh account status → save draft → confirm that post/version → phone approval → commit receipt → publish → verify duplicate retry, wrong version, rejection and expiry. Real phone approval remains a separate acceptance step; compilation and mock HTTP checks do not replace it.

package/docs/go-vue.ja.md

@@ -1,256 +0,0 @@
-# Go + Vue：ログイン、端末登録、確認後の公開
-
-[English](./go-vue.en.md) | [简体中文](./go-vue.zh-CN.md) | **日本語** · [SDK リファレンス](./README.ja.md)
-
-実際の Go CMS + Vue 3 の接続順序を示します。例のドメインは置き換え用で、ローカル設定・テスト用パスワード・テナント資格情報は含めません。ログイン、DB、業務 API はサイト側で実装し、Web SDK は表示と監視、Go SDK は AuthLink 呼び出しと応答検証を担当します。
-
-## 1. 3 つの origin と 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 の origin は接続先サイト自身の例であり、AuthLink 公式サイトのドメインへ置き換えません。
-
-テナントに登録するサイト origin は Vue の origin です。Go SDK の Origin と資格情報 JSON の API origin は AuthLink API を指します。ブラウザーの baseUrl は Go の業務 API です。TenantID/APIKey はバックエンドの非公開設定にのみ保存します。
-
-```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 アーカイブとして取得します。公開 Go module や npm 同梱サーバーではありません。SDK 自身の go.mod を保持し、`authlink "authlink.local/sdk"` を import します。信頼できる設定から `authlink.New(authlink.Config{Origin: authOrigin, TenantID: tenantID, APIKey: apiKey})` で初期化します。
-
-## 2. サイトのログインと session
-
-サイトのログイン API（参照 CMS は POST /api/login）が Secure・HttpOnly の session Cookie を発行します。Vue は credentials=include で GET /api/session を読み、authenticated=true と csrf を確認してから要求を作成します。未ログインならサイト自身のログインへ戻します。
-
-この CMS の JSON フィールド名は **csrf**、SDK オプション名は **csrfToken** です。`csrfToken: () => session.value?.csrf ?? ''` で対応します。JSON の名前を SDK に合わせる必要はありません。Go が session ごとに生成・保存し、作成と結果照会の両方で X-CSRF-Token を検証します。テナントキーや照合数字を代用しません。
-
-同じサイトの HTTPS サブドメイン同士は別 origin・同 site です。参照 API の Cookie は Domain を指定しない host-only、SameSite=Strict; Secure; HttpOnly; Path=/ です。別 site の場合は CORS に加えてブラウザーの Cookie 制限も考慮します。
-
-## 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 にだけ返し、その origin のエラー応答にも付与します。OPTIONS は origin・method・headers を検証して 204 を返し、ログインや CSRF は要求しません。実リクエストでログイン、CSRF、所有者を検証します。任意 origin の反射や * は使いません。PUT は CMS の下書き編集用なので必要なルートに合わせて限定できます。
-
-| サイト自身のルート | 入力 | 出力 |
-| --- | --- | --- |
-| `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 が実装します。postId/version と公開ルートはこの業務の契約で、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
-```
-
-安定したユーザー ID は認証済み session から取得します。用途、作成キー、記事の所有者と版を検証し、state と消費キーを別々に生成します。上流通信の前に CreateInput、ブラウザーの作成キー、ユーザー/session、記事公開の意図を保存します。通信失敗時は同一レコード・入力・キーを再利用します。session + 作成キーを一意にし、異なる用途・記事・版への再利用を拒否します。
-
-ticket、requestId、元の expiresAt を保存し、任意の qrSvg を除いて公開 ticket を返します。結果 API は現在の session が所有する記録をロックし、保存済み確認結果があれば再利用します。Status が approved/consumed のときだけ、DB の値から Expected を組み立て Consume を実行します。検証済み確認結果、session の確認記録、監査を requestId/verificationId の一意制約付きトランザクションで保存し、コミット後に confirmed を返します。待機中は displayCode を有効期限を越えてキャッシュしません。
-
-以下は SDK 呼び出し層であり、完全な HTTP サーバーではありません。DB、トランザクション、所有者検証は説明とコメントに従ってサイト側で実装します。
-
-```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 のライフサイクルと業務データ付き要求
-
-完全なファイルは [examples/vue-cms.vue](../examples/vue-cms.vue) にも同梱します。サイトのログイン後、信頼できる apiOrigin/authLinkOrigin と任意の保存済み下書き `post={id,version}` を渡してマウントします。親は認証 session の識別子を key に使います。ログアウト・再ログイン・アカウント切り替えでは先にアンマウントし、古い 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 のみです。postId/version が必要なら業務 API に fetch で送り、`validateTicket(response, 'confirm', authLinkOrigin)` で検証した後、監視には公式 client を使います。同じ作成の失敗ではキーを保持し、用途・記事・版が変わったときだけ新規キーにします。ticket は shallowRef、client は markRaw で保持します。
-
-マウント時は既存要求を監視し、mounted/watch で新規作成しません。閉じる・拒否・期限切れでは ticket を消去し、通信エラーでは同じ要求を再試行できるよう表示を維持します。confirmed 後は表示を閉じ、独立した公開 API を呼びます。失敗時は同じ requestId/記事/版で再試行し、実状態をバックエンドから再取得します。サイト自身のログインフォーム・記事一覧・エラー翻訳は例から省略しています。
-
-## 6. 公開トランザクションで再検証
-
-ブラウザーの confirmed イベントは許可証ではありません。Go は現在の session の保存済み確認結果を読み、purpose=confirm、intent=publish、記事の所有者、同一 postId/version、下書き状態、初回適用時の有効期限を検証します。記事更新と applied の記録を一括コミットします。同じ適用済み操作の再試行は重複更新・監査なしで成功を返します。別記事や編集後の版には新たな確認が必要です。AuthLink 確認結果に action、transactionHash、記事本文を追加しません。
-
-## 検証順序
-
-サイトログイン → session → バックエンド AccountStatus（参照 CMS は overview 経由）→ 未登録なら bind → スマートフォンで承認 → 消費と状態再取得 → 下書き保存 → 記事/版の confirm → 承認 → 確認結果保存 → 公開 → 再試行・異なる版・拒否・期限切れ。実端末での承認は利用者が行い、コンパイルや模擬 HTTP 検証とは区別します。