Add optional /vue wrapper and isolated framework demos

Author: ryan-williams

README.md

@@ -2,7 +2,7 @@
 
 > Named share links, Google sign-in, email codes, and an access log for gated dashboards.
 
-Reusable auth layers for apps with the "public site, gate a slice" shape: a backend kernel (HMAC sessions, DB-backed grant tokens, Google/OIDC sign-in, emailed codes) and unstyled React primitives (`useWhoami` / `AuthGate` / `SignInPanel` / `WhoamiChip`).
+Reusable auth layers for apps with the "public site, gate a slice" shape: a backend kernel (HMAC sessions, DB-backed grant tokens, Google/OIDC sign-in, emailed codes), a framework-free client, unstyled React primitives, and Vue `useWhoami` / `AuthGate` wrappers.
 
 Mint a link, name it after the person you're sending it to, set how many times and how long it works, and see what they looked at. Google or an emailed code for people the policy admits; request-access for everyone else.
 
@@ -33,6 +33,7 @@ src/adapters/   d1 (stores, audit sink & queries), oidc (Google + any issuer), r
                 r2 (avatar bytes), google-directory (group → allowlist sync)
 src/client/     typed fetch client, URL/exchange/identity/image helpers — no framework imports
 src/react/      useWhoami / AuthGate / SignInPanel / WhoamiChip / Avatar / AvatarField / disclosure — unstyled
+src/vue/        useWhoami / AuthGate — Vue-only composable and slotted gate, unstyled
 src/testing/    in-memory stores, so adopters can test a gated route without a DB
 migrations/     the schema (one baseline file pre-1.0; see below)
 scripts/        provisioning (Google client, Resend domain, group-sync SA) and d1-rebaseline
@@ -59,7 +60,44 @@ await auth.grants.revoke(grant.id)
 
 `displayName`, `hasScope`, `hasKeyParam`, `exchangeKeyParam` and `downscaleImage` are available from `/client`, along with the shared wire types. Existing `/react` helper imports still work. Importing `/client` is SSR-safe; browser-only helpers need browser APIs when called, and `shareUrl` needs an explicit absolute target outside the browser. It preserves the target's other query parameters and hash, replacing an existing `key`. The emitted module graph is checked during `pnpm build` for external dependencies, including React/Vue.
 
-The backend root import and platform adapters remain separate from `/client`; there is no Vue dependency or Vue-specific UI package. React hooks/components remain under `/react`.
+The backend root import and platform adapters remain separate from `/client`. React hooks/components live under `/react`; Vue wrappers live under `/vue`. Vanilla apps need neither framework.
+
+## Vue
+
+Import `useWhoami`, `AuthGate`, and shared identity helpers from `@open-athena/auth/vue`. Vue is an optional peer dependency; React and TanStack Query are not required for this subpath.
+
+```vue
+<script setup lang="ts">
+import { AuthGate, displayName } from '@open-athena/auth/vue'
+
+const options = {
+  basePath: '/api/view',
+  exchange: { endpoint: '/api/view/exchange' },
+}
+</script>
+
+<template>
+  <AuthGate :options="options">
+    <template #loading>Checking access...</template>
+    <template #error="{ error }"><p role="alert">{{ error.message }}</p></template>
+    <template #unauthenticated><h2>Private workspace</h2></template>
+    <template #default="{ whoami, signOut }">
+      <p>{{ displayName(whoami) ?? 'Anonymous link' }}</p>
+      <button @click="signOut">Sign out</button>
+    </template>
+  </AuthGate>
+</template>
+```
+
+`useWhoami(options)` runs during component setup and returns readonly `whoami`, `loading`, and `error` refs plus `refetch()` and `signOut()`. A 401 means signed out; other failures populate `error`. Matching clients share state within a Vue app, not across apps or SSR requests. Options are setup-time configuration: remount to change them. The composable opts into key exchange through `exchange`; `AuthGate` enables it by default, before probing identity. The exchange endpoint defaults to `<basePath>/exchange`; a supplied custom client needs an explicit exchange endpoint if its base differs. Slots receive `whoami`, `loading`, `error`, `refetch`, and `signOut`. `signOut()` records errors in state and rejects, so event handlers should handle that rejection. The server must still enforce authorization.
+
+## Minimal Demo Routes
+
+The demo's [root][demo-root] and [Vanilla][demo-vanilla] routes use the framework-free client; [Vue][demo-vue] and [React][demo-react] show their respective wrappers. Framework links navigate to separate documents so vanilla loads neither framework, and Vue and React do not load each other.
+
+Each example opens a named or anonymous share link, exchanges its `key` for a session, removes the key from the URL, and shows the returned identity. Sign out returns to the private-workspace wall. The examples use raw identity JSON from `GET /api/view/whoami` (401 when signed out), `POST /api/view/exchange` with `{ token }`, and `POST /api/view/logout`; `/api/demo-link?named=1|0&next=<route>` mints a link and redirects back to the selected example.
+
+Run `pnpm test:browser` for isolated Chromium regressions (mocked auth boundaries). With `pnpm --filter @open-athena/auth-demo dev` running at `http://localhost:4187`, `pnpm test:browser:live` exercises actual local Pages Functions, D1, and shared session cookies across frameworks. It does not send email or authenticate with Google.
 
 ## Installing
 
@@ -78,7 +116,7 @@ pnpm add "@open-athena/auth@github:Open-Athena/auth#$SHA"
 
 The `dist` branch only advances on a commit whose tests passed, and CI then installs the published branch and exercises it (`scripts/verify-dist.mjs`) — so any SHA you can pin is green *as an artifact*, not just as source. It carries built JS + `.d.ts`, the migrations, and the peer-dep declarations; versions read `0.1.0-dist.<sha>`.
 
-Peer deps are all optional and only needed for what you use: `@cloudflare/workers-types` (types only), and `react` + `@tanstack/react-query` for the `/react` subpath.
+Peer deps are all optional and only needed for what you use: `@cloudflare/workers-types` (types only), `react` + `@tanstack/react-query` for `/react`, and `vue` for `/vue`.
 
 ## Migrations
 
@@ -321,3 +359,7 @@ cd demo && pnpm dev    # the whole thing running, on :4187
 `pnpm build` compiles `src/core` and `src/adapters` against `@cloudflare/workers-types` alone (no Node types), which is what keeps them honest about being runtime-agnostic. `src/react` is a separate compilation because DOM lib and workers-types declare conflicting globals.
 
 [`npm-dist`]: https://github.com/runsascoded/npm-dist
+[demo-root]: https://auth.oa.dev/
+[demo-vanilla]: https://auth.oa.dev/vanilla
+[demo-vue]: https://auth.oa.dev/vue
+[demo-react]: https://auth.oa.dev/react

demo/functions/api/demo-link.ts

@@ -22,7 +22,10 @@ const TTL_S = 60 * 60
 
 export const onRequestGet = async ({ request, env }: Ctx): Promise<Response> => {
   const { viewGate } = gates(env, request)
-  const named = new URL(request.url).searchParams.get('named') === '1'
+  const query = new URL(request.url).searchParams
+  const named = query.get('named') === '1'
+  const next = query.get('next') ?? '/dashboard'
+  const target = ['/', '/vanilla', '/vue', '/react', '/dashboard'].includes(next) ? next : '/dashboard'
 
   // A real face, copied here once rather than fetched in the recipient's
   // browser on every render. GitHub rather than Gravatar for the demo persona
@@ -46,6 +49,6 @@ export const onRequestGet = async ({ request, env }: Ctx): Promise<Response> =>
 
   return new Response(null, {
     status: 302,
-    headers: { location: `/dashboard?key=${token}`, 'cache-control': 'no-store' },
+    headers: { location: `${target}?key=${token}`, 'cache-control': 'no-store' },
   })
 }

demo/index.html

@@ -18,6 +18,6 @@
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
+    <script type="module" src="/src/boot.ts"></script>
   </body>
 </html>

demo/package.json

@@ -17,7 +17,8 @@
     "@open-athena/auth": "workspace:*",
     "@tanstack/react-query": "^5.101.4",
     "react": "^19.2.8",
-    "react-dom": "^19.2.8"
+    "react-dom": "^19.2.8",
+    "vue": "^3.5.44"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260601.0",

demo/src/App.tsx

@@ -27,6 +27,9 @@ export function App() {
           <code>@open-athena/auth</code>
         </Link>
         <div className="nav-links">
+          <a href="/vanilla">Vanilla</a>
+          <a href="/vue">Vue</a>
+          <a href="/react">React</a>
           <Link to="/dashboard" className={path === '/dashboard' ? 'on' : ''}>
             Dashboard
           </Link>

demo/src/boot.ts

@@ -0,0 +1,7 @@
+import './styles.scss'
+
+const path = location.pathname.replace(/\/$/, '') || '/'
+if (path === '/' || path === '/vanilla') await import('./examples/vanilla-entry.js')
+else if (path === '/vue') await import('./examples/vue-entry.js')
+else if (path === '/react') await import('./examples/react-entry.js')
+else await import('./main.js')

demo/src/examples/react-entry.tsx

@@ -0,0 +1,47 @@
+import { createAuthClient, displayName } from '@open-athena/auth/client'
+import { Avatar, useWhoami, useKeyExchange, useForgetWhoami, type Whoami } from '@open-athena/auth/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { useState } from 'react'
+import { createRoot } from 'react-dom/client'
+import { endpoint, exchange, linkFor, mountShell, source, trackView } from './shell.js'
+
+const host = mountShell('React · @open-athena/auth/react')
+const client = createAuthClient({ basePath: endpoint })
+
+function Identity({ whoami }: { whoami: Whoami }) {
+  const forget = useForgetWhoami()
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState(false)
+  async function signOut() {
+    setBusy(true)
+    setError(false)
+    try { await client.logout(); forget() } catch { setError(true) } finally { setBusy(false) }
+  }
+  return <>
+    <h2>You're in.</h2>
+    <p className="example-identity"><Avatar whoami={whoami} size={40} /><span>{displayName(whoami) ?? 'Anonymous link'}</span></p>
+    <code>{whoami.kind === 'grant' ? `g:${whoami.id}` : `e:${whoami.email}`}</code>
+    <div className="placeholder">Your private workspace</div>
+    <button className="btn" disabled={busy} onClick={() => void signOut()}>Sign out</button>
+    {error && <p role="alert">Could not sign out. Please try again.</p>}
+  </>
+}
+
+function Example() {
+  const ready = useKeyExchange(exchange)
+  const { whoami, error, refresh } = useWhoami(source, { enabled: ready })
+  if (!ready || whoami === undefined) return <p>Checking access…</p>
+  if (error) return <><p role="alert">Could not check access. Please try again.</p><button className="btn" onClick={refresh}>Try again</button></>
+  if (whoami) return <Identity whoami={whoami} />
+  return <>
+    <h2>Private workspace</h2>
+    <p className="muted">Open a demo link to enter. No account needed.</p>
+    <div className="wall-actions">
+      <a className="btn primary" href={linkFor(true)}>Open named link</a>
+      <a className="btn" href={linkFor(false)}>Open anonymous link</a>
+    </div>
+  </>
+}
+
+createRoot(host).render(<QueryClientProvider client={new QueryClient()}><Example /></QueryClientProvider>)
+trackView()

demo/src/examples/shell.ts

@@ -0,0 +1,64 @@
+import type { Whoami } from '@open-athena/auth/client'
+import { displayName } from '@open-athena/auth/client'
+
+export const endpoint = '/api/view'
+export const source = { endpoint: `${endpoint}/whoami` }
+export const exchange = { endpoint: `${endpoint}/exchange` }
+
+export function identityLabel(whoami: Whoami): string {
+  return displayName(whoami) ?? 'Anonymous link'
+}
+
+export function linkFor(named: boolean): string {
+  const next = location.pathname.replace(/\/$/, '') || '/'
+  return `/api/demo-link?${new URLSearchParams({ named: named ? '1' : '0', next })}`
+}
+
+/** Static shared chrome; framework runtimes mount only inside the example. */
+export function mountShell(framework: string): HTMLElement {
+  const root = document.getElementById('root')!
+  root.innerHTML = `
+    <nav class="nav" aria-label="Main navigation">
+      <a class="brand" href="/"><code>@open-athena/auth</code></a>
+      <div class="nav-links">
+        <a href="/vanilla">Vanilla</a><a href="/vue">Vue</a><a href="/react">React</a>
+        <a href="/dashboard">Dashboard</a><a href="/admin">Admin</a>
+        <a href="https://github.com/Open-Athena/auth">GitHub</a>
+      </div>
+    </nav>
+    <main class="examples">
+      <header class="example-intro">
+        <h1>@open-athena/auth</h1>
+        <p class="lede">An auth wall. A link that lets you through.</p>
+        <p class="muted">Named share links, Google sign-in, email codes, and revocable access.</p>
+      </header>
+      <nav class="framework-tabs" aria-label="Framework examples">
+        <a href="/vanilla">Vanilla JS</a><a href="/vue">Vue</a><a href="/react">React</a>
+      </nav>
+      <section class="example-stage" aria-label="Live auth example">
+        <p class="example-caption"></p>
+        <div id="example"></div>
+      </section>
+      <section class="example-more">
+        <h2>One gate, more ways in</h2>
+        <p><a href="/dashboard">Google or an emailed code</a> · <a href="/admin">Mint and revoke links</a></p>
+        <p class="muted small">The library also handles approval queues, email notifications, allowlists, and access logs.</p>
+        <a href="https://github.com/Open-Athena/auth#readme">Documentation and source</a>
+      </section>
+    </main>
+    <footer><p class="muted small">Demo content only. Access to gated pages is logged. <a href="/privacy">Privacy</a></p></footer>`
+  root.querySelector('.example-caption')!.textContent = framework
+  for (const anchor of root.querySelectorAll<HTMLAnchorElement>('.framework-tabs a')) {
+    if (anchor.pathname === location.pathname || (location.pathname === '/' && anchor.pathname === '/vanilla')) {
+      anchor.setAttribute('aria-current', 'page')
+    }
+  }
+  return document.getElementById('example')!
+}
+
+export function trackView(): void {
+  void fetch(`${endpoint}/track`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ path: location.pathname }), keepalive: true,
+  }).catch(() => {})
+}

demo/src/examples/vanilla-entry.ts

@@ -0,0 +1,108 @@
+import { AuthClientError, createAuthClient, exchangeKeyParam, type Whoami } from '@open-athena/auth/client'
+import { endpoint, exchange, identityLabel, linkFor, mountShell, trackView } from './shell.js'
+
+const host = mountShell('Vanilla JS · @open-athena/auth/client')
+const client = createAuthClient({ basePath: endpoint })
+let version = 0
+let signingOut = false
+
+function button(label: string, action: () => void): HTMLButtonElement {
+  const node = document.createElement('button')
+  node.className = 'btn'
+  node.textContent = label
+  node.onclick = action
+  return node
+}
+
+function render(whoami: Whoami | null): void {
+  host.replaceChildren()
+  const heading = document.createElement('h2')
+  heading.textContent = whoami ? "You're in." : 'Private workspace'
+  host.appendChild(heading)
+  if (whoami) {
+    const name = document.createElement('p')
+    name.className = 'example-identity'
+    name.textContent = identityLabel(whoami)
+    if (whoami.subject?.avatar) {
+      const avatar = document.createElement('img')
+      avatar.src = whoami.subject.avatar
+      avatar.alt = ''
+      avatar.width = avatar.height = 40
+      avatar.referrerPolicy = 'no-referrer'
+      avatar.onerror = () => avatar.remove()
+      name.prepend(avatar)
+    }
+    const subject = document.createElement('code')
+    subject.textContent = whoami.kind === 'grant' ? `g:${whoami.id}` : `e:${whoami.email}`
+    const content = document.createElement('div')
+    content.className = 'placeholder'
+    content.textContent = 'Your private workspace'
+    for (const node of [name, subject, content, button('Sign out', () => void signOut())]) host.appendChild(node)
+  } else {
+    const note = document.createElement('p')
+    note.className = 'muted'
+    note.textContent = 'Open a demo link to enter. No account needed.'
+    const links = document.createElement('div')
+    links.className = 'wall-actions'
+    for (const [named, label] of [[true, 'Open named link'], [false, 'Open anonymous link']] as const) {
+      const anchor = document.createElement('a')
+      anchor.className = named ? 'btn primary' : 'btn'
+      anchor.href = linkFor(named)
+      anchor.textContent = label
+      links.appendChild(anchor)
+    }
+    host.appendChild(note)
+    host.appendChild(links)
+  }
+}
+
+function showError(): void {
+  host.replaceChildren()
+  const error = document.createElement('p')
+  error.setAttribute('role', 'alert')
+  error.textContent = 'Could not check access. Please try again.'
+  host.appendChild(error)
+  host.appendChild(button('Try again', () => void refresh()))
+}
+
+async function refresh(): Promise<void> {
+  if (signingOut) return
+  const request = ++version
+  host.textContent = 'Checking access…'
+  try {
+    const identity = await client.whoami()
+    if (request === version) render(identity)
+  } catch (error) {
+    if (request !== version) return
+    if (error instanceof AuthClientError && [401, 403].includes(error.status)) render(null)
+    else showError()
+  }
+}
+
+async function signOut(): Promise<void> {
+  if (signingOut) return
+  signingOut = true
+  ++version
+  const control = host.querySelector('button')!
+  control.disabled = true
+  try {
+    await client.logout()
+    render(null)
+  } catch {
+    control.disabled = false
+    const error = document.createElement('p')
+    error.setAttribute('role', 'alert')
+    error.textContent = 'Could not sign out. Please try again.'
+    host.appendChild(error)
+  } finally {
+    signingOut = false
+  }
+}
+
+host.textContent = 'Checking access…'
+void (async () => {
+  await exchangeKeyParam(exchange)
+  await refresh()
+  trackView()
+  window.addEventListener('focus', () => void refresh())
+})()