@verdify/auth-browser

Verdify Tier-2 browser auth client — the credential ceremony for product frontends. Generated from verdify-contracts (auth.v1). Runs in the SPA; holds body tokens.

Browser-token security note: This package intentionally holds RpSessionTokens (access token, refresh token, device ID) in the browser — the design for the Tier-2 client-direct flow. This is the opposite posture from @verdify/sdk-ts, which is server-side only (D-On7). Do not confuse the two. See docs/adr/0001-browser-token-posture.md for the full security guidance.

Install

pnpm add @verdify/auth-browser

Quick start — integrating Verdify auth into your product frontend

import { createRpAuthClient } from "@verdify/auth-browser";

// baseUrl MUST include /auth/v1 — the generated paths are server-relative /rp/...
const rp = createRpAuthClient({
  baseUrl: "https://<auth-host>/auth/v1",
  clientId: "rp_spare",
});

Replace <auth-host> with the per-environment Verdify auth host. The client adds X-Verdify-Client-Id: rp_spare on every request; the browser sets Origin automatically.

Credential ceremony

Sign up + verify email

// Step 1: initiate sign-up (triggers OTP email)
const signUpResult = await rp.signUpEmail({
  email: "[email protected]",
  password: "S3cur3P@ss!",
});
if (!signUpResult.ok) {
  console.error(signUpResult.status, signUpResult.error);
}

// Step 2: verify the OTP from email
const verifyResult = await rp.verifyEmail({
  email: "[email protected]",
  code: "123456",
});
if (verifyResult.ok) {
  // Tokens stored automatically; verifyResult.data holds RpSessionTokens
  console.log("access token:", rp.store.get()?.accessToken); // vfy_at_...
}

Login

const loginResult = await rp.login({
  email: "[email protected]",
  password: "S3cur3P@ss!",
});
if (loginResult.ok) {
  // Tokens stored automatically
  const tokens = rp.store.get();
  console.log("session:", tokens?.sessionId);
}

Refresh (auto and manual)

refreshIfNeeded() returns the current tokens, refreshing first if the access token is within 30 seconds of expiry. Call it before any authenticated request to ensure the access token is valid.

// At app mount or before an authenticated fetch:
const tokens = await rp.refreshIfNeeded();
if (!tokens) {
  // No stored session — redirect to login
}

Single-flight guarantee: concurrent refreshIfNeeded() calls in a SPA (e.g. from multiple components mounting simultaneously) share a single POST /rp/token request. Without this, a second call could replay an already-rotated refresh token, which triggers Verdify's reuse-detection and revokes the entire session family.

Use rp.refresh() to force an unconditional refresh regardless of expiry.

Logout

rp.logout(); // Clears the token store. Call your own navigation/state cleanup.

Token storage

The default TokenStore is in-memory (most XSS-resistant). Tokens are held in a plain heap object and are lost on page reload.

In-memory (default)

// Default — no configuration needed.
const rp = createRpAuthClient({ baseUrl: "...", clientId: "rp_spare" });

WebStorage (opt-in, persists across reloads)

import { createRpAuthClient, WebStorageTokenStore } from "@verdify/auth-browser";

const rp = createRpAuthClient({
  baseUrl: "https://<auth-host>/auth/v1",
  clientId: "rp_spare",
  store: new WebStorageTokenStore(localStorage, "vfy"),
});

Warning: WebStorageTokenStore exposes tokens to XSS. Only opt in if you need persistence across reloads and you have a strict Content Security Policy in place. The key argument ("vfy" above) is the localStorage key; choose one that does not collide with other libraries.

Custom store

Implement the TokenStore interface to integrate with your own state management:

import type { TokenStore, StoredTokens } from "@verdify/auth-browser";

class ReduxTokenStore implements TokenStore {
  get(): StoredTokens | null { return store.getState().auth.tokens; }
  set(t: StoredTokens): void { store.dispatch(setTokens(t)); }
  clear(): void { store.dispatch(clearTokens()); }
}

All options

createRpAuthClient({
  /** Auth host including the /auth/v1 path prefix. Required. */
  baseUrl: "https://<auth-host>/auth/v1",

  /** Your relying-party client ID (must be in verdify-auth's AllowedOrigins config). */
  clientId: "rp_spare",

  /** Custom fetch (e.g. for testing). Defaults to globalThis.fetch. */
  fetch?: typeof fetch,

  /** Max GET retries on network failure. Default: 2. */
  maxRetries?: number,

  /** Token persistence. Default: InMemoryTokenStore. */
  store?: TokenStore,

  /** Override the clock for testing. Default: Date.now. */
  now?: () => number,

  /** Refresh this many ms before expiry. Default: 30000 (30s). */
  refreshSkewMs?: number,
})

Prerequisites

• verdify-auth must have your relying-party configured with AllowedOrigins including your frontend's origin (https://your-app.example.com). Every /rp/* call is rejected with 401 if the Origin header is not in the allowlist.
• The public /auth/v1/rp/* Gateway route is a Wave 4d deliverable. Until it ships, point baseUrl at a port-forwarded or local-compose auth service.

Status

Wave 4a-ii. Generated from verdify-contracts at ref f973bf0 (auth.v1 RP surface). The browser token posture decision is documented in docs/adr/0001-browser-token-posture.md.