@auth-link/web 0.0.5 → 1.1.0

package/docs/README.en.md

@@ -1,282 +1,62 @@
-# AuthLink Web
+# AuthLink Web 1.1
 
-**English** | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+[English](README.en.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
 
-Frontend dialogs for phone binding and in-app confirmation, with Vue 3, React 18/19 and plain JavaScript. Follow installation, session loading, client initialization, dialogs and event cleanup in this order.
+## Direct rotating-code verification
 
-## 1. Install and distinguish the two API origins
+The app directly displays a six-digit rotating code. No per-action approval, authorization requestId, businessId or polling is required. First-time enrollment still scans a QR and verifies the phone; entering its current code on the website completes binding.
+
+The CMS backend must reserve one immutable pending action per session before opening the prompt. Another tab cannot replace it. Obtain the user from the server session and check CSRF and business permissions. Verify the passcode on the server and atomically commit verificationId with the saved operation before returning success. onVerified only updates the UI.
 
 ```sh
-npm install @auth-link/web@latest
-# Also install the framework your project uses: vue, or react / react-dom.
+npm install @auth-link/web@^1.1.0
 ```
 
-| Origin | Frontend option | Purpose |
-| --- | --- | --- |
-| Your application API, e.g. `https://cms-api.example.com` | baseUrl, allowedBackendOrigins | Session, request creation and results |
-| AuthLink production API `https://api.getauthlink.com` | authLinkOrigin | Validate the AuthLink origin in the ticket |
-
-baseUrl is your own application API, not the AuthLink API or marketing site. The SDK requires your existing website login/session and the request routes below; it does not provide login/session endpoints. Never put tenant keys in browser code.
-
-The root import provides clients and types; /vue and /react provide components and useAuthLink; explicitly import /styles.css. ESM and TypeScript, Node 22.13+ tooling; React 18.2+/19 or Vue 3.3+. Install only your framework.
-
-## 2. Load the current session and initialize a 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',
-  });
-}
-```
-
-After website login, read your existing session endpoint. This example uses the CMS response authenticated/csrf. If your response field is csrfToken, read that field instead and supply it to the SDK csrfToken callback.
-
-```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 is your application's example route; adapt it. Same-origin uses relative URLs and same-origin cookies. Cross-origin cookies need include and an application API that already allows your frontend origin; browser cookie policy still applies. Do not read HttpOnly cookies, generate your own CSRF token, or substitute a matching number.
+The default client posts only {passcode} to POST /api/auth with current CMS credentials and CSRF. To submit a form at the same time, supply your own client.verify callback and send {form,passcode} to your CMS. The CMS checks the form against its saved snapshot; never send tenant keys or passcode seeds to the browser.
 
-For existing Bearer/JWT login, auth below is your website's mutable login state. Read its refreshed accessToken on every request. This is not an AuthLink tenant key. CSRF may be omitted only for Bearer with credentials=omit; sending cookies still requires csrfToken.
+## Options and callbacks
 
-```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',
-});
-```
+Required: client.verify(passcode, signal) and expiresAt (the pending CMS action deadline). Optional: locale, variant A/B/C, bindingQr and authLinkOrigin for first enrollment only, onVerified, onError, onClose, onExpired. Success contains status, verificationId, authenticationPolicy and expiresAt; it has no requestId or businessId.
 
-## 3. Vue: create on click, display and clean up
+Cookie authentication requires CSRF. Bearer authentication uses accessToken with credentials=omit. For a cross-origin CMS explicitly set allowedBackendOrigins. Bare HTTPS origins are required outside loopback development.
 
-The package includes `examples/vue-client.vue`; copy it as AuthLinkPanel.vue. After login pass the current session.csrf, and backendOrigin for cross-origin calls. Unmount on logout/account/session changes and mount a new instance. Update the csrf prop after token refresh.
+## React and 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';
+The React component takes the same options. Vue emits verified, error, close and expired. Keep client references stable. Thirteen languages remain supported; Simplified Chinese is the default. A is minimal, B is split, C is compact.
 
-// 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>
 ```
 
-Keep ticket in shallowRef and client in markRaw. Retain a failed creation's key when retrying the same mode; clear it only after success. Create only in user handlers, never mounted/watch. Confirmation, rejection, expiry and close clear the ticket and unmount the dialog. Keep the dialog on network errors and use its retry control for the current request. Reload actual account state from your own API when needed.
-
-## 4. React
-
-Pass a stable client created as above and mode=bind or confirm. Unmount the instance on logout/account/session changes.
-
-```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. Plain JavaScript / direct dialogs
-
-```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');
-```
-
-For binding use client.create('bind', ...) and openAuthLinkBind(...). Confirmation/rejection dismiss before their callbacks and do not emit onClose. Close stops frontend observation; call destroy when leaving the page/component. Success is delivered once per request per instance. Callbacks update UI; protected actions still call your application's API.
-
-## 6. API shapes the frontend needs
-
-| Application route | Frontend sends | Frontend reads |
-| --- | --- | --- |
-| POST /api/authlink/requests | purpose=bind or confirm; Idempotency-Key | Ticket |
-| POST /api/authlink/requests/{requestId}/result | empty object; current login credentials | Result; polled automatically |
-
-Both send the current CSRF header in cookie mode. Ticket contains requestId, purpose, qr, pairingCode and expiresAt; confirm also requires displayCode. Import Ticket/Result/Confirmation rather than inventing QR data or matching numbers. Only status=confirmed triggers success. new/pending/approved/consumed are waiting states; rejected/expired trigger their events.
-
-SDK create() sends purpose only. If your application expects additional fields, create via your own fetch, validate the returned ticket and pass it to the same component. post, session and backendOrigin below are your frontend state; retain the creation key across retries of the same payload.
-
-```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. Props, events and presentation
-
-| Prop | Type | Meaning |
-| --- | --- | --- |
-| `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 callback / Vue event | Value | Behavior |
-| --- | --- | --- |
-| `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 is a centered card (default), B splits on desktop and stacks on narrow screens, and C is compact with a mobile bottom sheet. Changing locale/variant does not create a request. Browser support for native dialog.showModal() is required.
-
-Import CSS explicitly. Dialogs mount under document.body; set --authlink-foreground, --authlink-background, --authlink-accent and --authlink-muted on :root or .authlink-dialog. Vue class accepts strings/arrays/objects alongside className. SSR renders no dialog and creates no requests.
-
-Locales: `zh-CN` (default), `zh-TW`, `en`, `ja`, `bn`, `es`, `fil`, `hi`, `id`, `ms`, `pt`, `th`, `vi`. Missing/unsupported values fall back to Simplified Chinese. Import supportedLocales for the list.
-
-## 8. Transport options and troubleshooting
-
-| Option | Purpose |
-| --- | --- |
-| `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 |
-
-Custom headers cannot replace Accept, Content-Type, Authorization, Idempotency-Key or the configured CSRF header. Read error.message: CSRF_REQUIRED means check the session token; ACCESS_TOKEN_REQUIRED means check login state; BACKEND_ORIGIN_NOT_ALLOWED means check exact allowed origins; NETWORK_ERROR means inspect browser Network, connectivity and CORS. Requests time out after 10 seconds; closing/unmounting cancels observation.
+## Errors and cleanup
 
-Expired digits are hidden; do not generate or cache new ones in the frontend. QR generation is local; allow data: images if your page uses CSP. A callback, localStorage or a browser-supplied status is not authorization.
+A used code cannot authorize a second action, even in another session. After sign-in or first enrollment, wait for the next code. PASSCODE_INVALID/PASSCODE_USED/PASSCODE_LOCKED are validation errors, not success. Retain the same backend idempotency key and original code when a result is unknown; retries must not repeat the business action.
 
-## License
+destroy() aborts browser work and clears timers without a close callback. close() also calls onClose. Closing a dialog does not roll back server work: your CMS must manage cancellation and its pending slot. Waiting and local expiry never poll.
 
-MIT. See LICENSE and THIRD_PARTY_NOTICES.md.
+The older openAuthLink / Ticket / Consume workflow remains available for the earlier protocol; new apps use openPasscode / AuthLinkPasscode and the backend Authenticate/authenticate method. No old-binding migration is provided.