@interop/byoe-react-template 0.1.0

package/src/pages/LoginPage.tsx

@@ -0,0 +1,76 @@
+/**
+ * Login With Wallet: one button driving the library's CHAPI login flow, with
+ * a progress line per flow phase and an error alert. An authenticated visitor
+ * is bounced straight to the app.
+ */
+import { Navigate } from 'react-router'
+import {
+  Alert,
+  Box,
+  Button,
+  CircularProgress,
+  Paper,
+  Stack,
+  Typography
+} from '@mui/material'
+import WalletIcon from '@mui/icons-material/AccountBalanceWallet'
+import { useLogin } from '@interop/was-react'
+
+const PHASE_LABELS: Record<string, string> = {
+  probing: 'Contacting your wallet...',
+  'storing-key': 'Storing your app key in the wallet...',
+  'requesting-grants': 'Requesting storage access...',
+  verifying: 'Verifying the wallet response...'
+}
+
+export function LoginPage() {
+  const { login, status, phase, error } = useLogin()
+  const busy = status === 'authenticating'
+
+  if (status === 'authenticated') {
+    return <Navigate to="/" replace />
+  }
+
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        minHeight: '100vh',
+        p: 2
+      }}
+    >
+      <Paper sx={{ p: 4, maxWidth: 420, width: '100%' }}>
+        <Stack spacing={3} sx={{ alignItems: 'center' }}>
+          <Typography variant="h5" component="h1">
+            BYOE Notes
+          </Typography>
+          <Typography color="text.secondary" align="center">
+            Your notes live in your own wallet-attached storage, encrypted so
+            only you can read them. Log in with your digital wallet to begin.
+          </Typography>
+          <Button
+            variant="contained"
+            size="large"
+            startIcon={busy ? <CircularProgress size={20} /> : <WalletIcon />}
+            onClick={() => void login()}
+            disabled={busy}
+          >
+            {busy ? 'Connecting your wallet...' : 'Login with wallet'}
+          </Button>
+          {busy && phase && (
+            <Typography color="text.secondary" data-testid="login-phase">
+              {PHASE_LABELS[phase] ?? phase}
+            </Typography>
+          )}
+          {error && (
+            <Alert severity="error" sx={{ width: '100%' }} role="alert">
+              {error}
+            </Alert>
+          )}
+        </Stack>
+      </Paper>
+    </Box>
+  )
+}

package/src/pages/NotesPage.tsx

@@ -0,0 +1,166 @@
+/**
+ * The example WAS-backed collection: list / add / edit / delete notes. All
+ * reads come from the in-memory entity store (hydrated from the encrypted
+ * local replica); the store's `insert` / `update` / `remove` verbs persist
+ * locally first and replicate to WAS in the background.
+ */
+import { useState } from 'react'
+import {
+  Box,
+  Button,
+  IconButton,
+  List,
+  ListItem,
+  ListItemText,
+  Stack,
+  TextField,
+  Typography
+} from '@mui/material'
+import DeleteIcon from '@mui/icons-material/Delete'
+import EditIcon from '@mui/icons-material/Edit'
+import { uuidv7 } from 'uuidv7'
+import { getDeviceId } from '@interop/was-react'
+import { useNotes, type Note } from '@/stores/notes'
+
+function NoteRow({ note }: { note: Note }) {
+  const update = useNotes(state => state.update)
+  const remove = useNotes(state => state.remove)
+  const [editing, setEditing] = useState(false)
+  const [draft, setDraft] = useState(note.text)
+
+  async function save() {
+    const text = draft.trim()
+    if (text && text !== note.text) {
+      await update({
+        ...note,
+        text,
+        updatedAt: new Date().toISOString(),
+        deviceId: getDeviceId()
+      })
+    }
+    setEditing(false)
+  }
+
+  if (editing) {
+    return (
+      <ListItem>
+        <Stack direction="row" spacing={1} sx={{ width: '100%' }}>
+          <TextField
+            value={draft}
+            onChange={event => setDraft(event.target.value)}
+            onKeyDown={event => {
+              if (event.key === 'Enter') {
+                void save()
+              }
+            }}
+            size="small"
+            fullWidth
+            autoFocus
+            aria-label="edit note"
+          />
+          <Button onClick={() => void save()}>Save</Button>
+          <Button
+            color="inherit"
+            onClick={() => {
+              setDraft(note.text)
+              setEditing(false)
+            }}
+          >
+            Cancel
+          </Button>
+        </Stack>
+      </ListItem>
+    )
+  }
+
+  return (
+    <ListItem
+      secondaryAction={
+        <Stack direction="row" spacing={1}>
+          <IconButton
+            edge="end"
+            aria-label={`edit ${note.text}`}
+            onClick={() => setEditing(true)}
+          >
+            <EditIcon />
+          </IconButton>
+          <IconButton
+            edge="end"
+            aria-label={`delete ${note.text}`}
+            onClick={() => void remove(note.id)}
+          >
+            <DeleteIcon />
+          </IconButton>
+        </Stack>
+      }
+    >
+      <ListItemText
+        primary={note.text}
+        secondary={new Date(note.createdAt).toLocaleString()}
+      />
+    </ListItem>
+  )
+}
+
+export function NotesPage() {
+  const notes = useNotes(state => state.byId)
+  const insert = useNotes(state => state.insert)
+  const [text, setText] = useState('')
+
+  const sorted = [...notes.values()].sort((a, b) =>
+    b.createdAt.localeCompare(a.createdAt)
+  )
+
+  async function addNote() {
+    const trimmed = text.trim()
+    if (!trimmed) {
+      return
+    }
+    const now = new Date().toISOString()
+    await insert({
+      id: uuidv7(),
+      text: trimmed,
+      createdAt: now,
+      updatedAt: now,
+      deviceId: getDeviceId()
+    })
+    setText('')
+  }
+
+  return (
+    <Box>
+      <Typography variant="h5" component="h2" gutterBottom>
+        Notes
+      </Typography>
+      <Stack direction="row" spacing={1} sx={{ mb: 2 }}>
+        <TextField
+          value={text}
+          onChange={event => setText(event.target.value)}
+          onKeyDown={event => {
+            if (event.key === 'Enter') {
+              void addNote()
+            }
+          }}
+          placeholder="A new note..."
+          size="small"
+          fullWidth
+          aria-label="new note"
+        />
+        <Button variant="contained" onClick={() => void addNote()}>
+          Add
+        </Button>
+      </Stack>
+      {sorted.length === 0 ? (
+        <Typography color="text.secondary" data-testid="notes-empty">
+          No notes yet. Add one above.
+        </Typography>
+      ) : (
+        <List data-testid="notes-list">
+          {sorted.map(note => (
+            <NoteRow key={note.id} note={note} />
+          ))}
+        </List>
+      )}
+    </Box>
+  )
+}

package/src/stores/notes.ts

@@ -0,0 +1,41 @@
+/**
+ * The one example collection: a zustand entity store of notes, plus the
+ * {@link StoreRegistry} the library's rehydrate mechanism drives (hydrate on
+ * login, per-doc patch on remote sync, clear on logout).
+ *
+ * When adding a collection to an app built from this template: add a
+ * `{ key, id }` entry to `COLLECTIONS` in app.config.ts, create its entity
+ * store here, and give it a registry entry.
+ */
+import { createEntityStore, type StoreRegistry } from '@interop/was-react'
+
+/**
+ * `updatedAt` and `deviceId` are REQUIRED by the sync layer: remote conflicts
+ * are resolved last-writer-wins on the payload's own `(updatedAt, deviceId)`,
+ * so every insert/update must stamp both (see NotesPage). A payload without
+ * them loses every conflict to the server copy.
+ */
+export interface Note {
+  id: string
+  text: string
+  createdAt: string
+  updatedAt: string
+  deviceId: string
+}
+
+/** Zustand hook holding the decrypted notes as a `Map<uuid, Note>`. */
+export const useNotes = createEntityStore<Note>('notes')
+
+/**
+ * Per-collection handlers for the rehydrate mechanism. `upsert` maps to the
+ * entity store's non-persisting `patch` (the sync stream already owns the
+ * persisted row) and `clear` to `replaceAll([])`.
+ */
+export const registry: StoreRegistry = {
+  notes: {
+    hydrate: () => useNotes.getState().hydrate(),
+    upsert: doc => useNotes.getState().patch(doc as Note),
+    drop: uuid => useNotes.getState().drop(uuid),
+    clear: () => useNotes.getState().replaceAll([])
+  }
+}

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/test/browser/notes.spec.ts

@@ -0,0 +1,82 @@
+/**
+ * Offline (mocked) tier: the app boots through the dev gate into the Notes page
+ * over the encrypted local replica -- no wallet, no WAS server. Adds / edits /
+ * deletes a note, proves persistence across a reload (IndexedDB), and checks the
+ * sync chip advertises local-only mode. Each test runs in an isolated browser
+ * context (fresh IndexedDB), so no cross-test cleanup.
+ */
+import { test, expect, type Page } from '@playwright/test'
+
+async function bootToNotes(page: Page) {
+  await page.goto('/')
+  await expect(page.getByRole('heading', { name: 'BYOE Notes' })).toBeVisible()
+  await expect(page.getByTestId('bootstrap-loading')).toHaveCount(0)
+  await expect(
+    page.getByRole('heading', { name: 'Notes', exact: true })
+  ).toBeVisible()
+}
+
+async function addNote(page: Page, text: string) {
+  await page.getByLabel('new note').locator('input').fill(text)
+  await page.getByRole('button', { name: 'Add' }).click()
+  await expect(page.getByTestId('notes-list').getByText(text)).toBeVisible()
+}
+
+test.beforeEach(async ({ page }) => {
+  await bootToNotes(page)
+})
+
+test('boots through the dev gate into an empty Notes page', async ({
+  page
+}) => {
+  await expect(page.getByTestId('notes-empty')).toBeVisible()
+  await expect(page.getByTestId('notes-list')).toHaveCount(0)
+})
+
+test('adds a note', async ({ page }) => {
+  await addNote(page, 'Remember the milk')
+
+  await expect(page.getByTestId('notes-empty')).toHaveCount(0)
+  await expect(page.getByTestId('notes-list')).toBeVisible()
+})
+
+test('edits a note in place', async ({ page }) => {
+  await addNote(page, 'Draft title')
+
+  await page.getByRole('button', { name: 'edit Draft title' }).click()
+  const field = page.getByLabel('edit note').locator('input')
+  await field.fill('Final title')
+  await page.getByRole('button', { name: 'Save' }).click()
+
+  await expect(
+    page.getByTestId('notes-list').getByText('Final title')
+  ).toBeVisible()
+  await expect(page.getByText('Draft title')).toHaveCount(0)
+})
+
+test('deletes a note, returning to the empty state', async ({ page }) => {
+  await addNote(page, 'Delete me')
+
+  await page.getByRole('button', { name: 'delete Delete me' }).click()
+
+  await expect(page.getByText('Delete me')).toHaveCount(0)
+  await expect(page.getByTestId('notes-empty')).toBeVisible()
+})
+
+test('persists notes across a page reload (IndexedDB)', async ({ page }) => {
+  await addNote(page, 'Durable note')
+
+  await page.reload()
+  await expect(page.getByTestId('bootstrap-loading')).toHaveCount(0)
+
+  await expect(
+    page.getByTestId('notes-list').getByText('Durable note')
+  ).toBeVisible()
+})
+
+test('sync chip advertises local-only (offline) mode', async ({ page }) => {
+  const chip = page.getByTestId('sync-status-chip')
+  await expect(chip).toBeVisible()
+  await expect(chip).toHaveText(/Offline/)
+  await expect(chip).toHaveAttribute('data-sync-state', 'offline')
+})

package/test/browser-wallet/walletLogin.spec.ts

@@ -0,0 +1,312 @@
+/**
+ * Login-With-Wallet e2e against a real local freewallet + was-teaching-server.
+ *
+ * CHAPI has no mediator here; two injection seams stand in for it:
+ * - App side: `window.__WAS_REACT_E2E_CHAPI__` switches the library's
+ *   `src/auth/chapi.ts` to a request queue (`__WAS_REACT_E2E_CHAPI_REQUESTS__` /
+ *   `__WAS_REACT_E2E_CHAPI_RESPONSES__`) this spec services.
+ * - Wallet side: freewallet's own non-production `__E2E_CHAPI_GET_EVENT__` seam
+ *   drives its /#/wallet/get popup with the app's captured VPR; the response VP
+ *   is read back off `__E2E_CHAPI_RESPONSE__`.
+ * The CHAPI store() step has no wallet-side seam, so the spec lands the seed
+ * credential through the wallet's Add Credential paste flow -- the same
+ * wallet-vault write path -- and then acks the app's store request.
+ *
+ * One serialized test walks the life cycle on a single wallet account (signup
+ * is deliberately expensive PBKDF2): first login (store key + grants), a note
+ * write that replicates to WAS, then logout and a returning login that recovers
+ * the note from WAS.
+ */
+import {
+  test,
+  expect,
+  type BrowserContext,
+  type Page,
+  type TestInfo
+} from '@playwright/test'
+import { APP_URL, WALLET_URL } from '../../playwright.wallet.config'
+
+/* ----------------------------- wallet helpers ----------------------------- */
+
+function testUser(testInfo: TestInfo) {
+  const token = `${Date.now()}-w${testInfo.workerIndex}`
+  return {
+    passphrase: `Str0ngpass-${token}-Aa1!`,
+    email: `e2e-${token}@example.com`
+  }
+}
+
+/** Creates a wallet account; leaves `page` logged in on the wallet dashboard. */
+async function signupWallet(page: Page, testInfo: TestInfo) {
+  const { passphrase, email } = testUser(testInfo)
+  await page.goto(`${WALLET_URL}/#/signup`)
+  await page.locator('input[type="password"]').fill(passphrase)
+  await expect(page.getByRole('button', { name: 'Next' })).toBeEnabled({
+    timeout: 20_000
+  })
+  await page.getByRole('button', { name: 'Next' }).click()
+  await page.locator('input[type="email"]').fill(email)
+  await expect(page.getByRole('button', { name: 'Next' })).toBeEnabled()
+  await page.getByRole('button', { name: 'Next' }).click()
+  await expect(page).toHaveURL(/#\/signup\?.*step=storage/)
+  await page.getByRole('button', { name: 'Create Wallet' }).click()
+  // Signup binds the keyring (deliberately slow PBKDF2) + provisions storage.
+  await expect(page).toHaveURL(/#\/dashboard/, { timeout: 45_000 })
+  return { passphrase, email }
+}
+
+/**
+ * Services one app-captured `get()` VPR through the wallet's /#/wallet/get page
+ * (freewallet's injection seam), returning the CHAPI wire response.
+ */
+async function driveWalletGet(
+  context: BrowserContext,
+  {
+    vpr,
+    passphrase,
+    selectCredential = false
+  }: { vpr: unknown; passphrase: string; selectCredential?: boolean }
+): Promise<unknown> {
+  const page = await context.newPage()
+  await page.addInitScript(
+    cfg => {
+      const win = window as unknown as {
+        __E2E_CHAPI_GET_EVENT__?: unknown
+        __E2E_CHAPI_RESPONSE__?: { value: unknown }
+      }
+      win.__E2E_CHAPI_RESPONSE__ = undefined
+      win.__E2E_CHAPI_GET_EVENT__ = {
+        credentialRequestOrigin: cfg.origin,
+        credentialRequestOptions: {
+          web: { VerifiablePresentation: cfg.vpr }
+        },
+        respondWith(promise: Promise<unknown>) {
+          void Promise.resolve(promise).then(value => {
+            win.__E2E_CHAPI_RESPONSE__ = { value: value ?? null }
+          })
+        }
+      }
+    },
+    { origin: APP_URL, vpr }
+  )
+  await page.goto(`${WALLET_URL}/#/wallet/get`)
+  // The popup always asks for the passphrase (it is designed for a cold
+  // cross-origin popup, not the dashboard session).
+  await page.locator('input[type="password"]').fill(passphrase)
+  await page.getByRole('button', { name: 'Continue' }).click()
+  await page
+    .locator('input[type="password"]')
+    .waitFor({ state: 'detached', timeout: 30_000 })
+  if (selectCredential) {
+    // The app key is not a wallet Login Credential, so it is not pre-selected
+    // on the share screen.
+    const checkbox = page.getByRole('checkbox').first()
+    await checkbox.waitFor({ timeout: 15_000 })
+    await checkbox.check()
+  }
+  await page.getByRole('button', { name: 'Continue' }).click()
+  await expect
+    .poll(
+      () =>
+        page.evaluate(
+          () =>
+            (
+              window as unknown as {
+                __E2E_CHAPI_RESPONSE__?: { value: unknown }
+              }
+            ).__E2E_CHAPI_RESPONSE__ !== undefined
+        ),
+      { timeout: 30_000, intervals: [500] }
+    )
+    .toBe(true)
+  const response = await page.evaluate(
+    () =>
+      (window as unknown as { __E2E_CHAPI_RESPONSE__?: { value: unknown } })
+        .__E2E_CHAPI_RESPONSE__
+  )
+  await page.close()
+  return (response as { value: unknown }).value
+}
+
+/**
+ * Lands a credential in the wallet vault via the dashboard Add Credential paste
+ * flow (`walletPage` must be logged in on the dashboard).
+ */
+async function walletAddCredential(walletPage: Page, credentialJson: string) {
+  await walletPage.getByRole('link', { name: 'Add Credential' }).click()
+  await expect(walletPage).toHaveURL(/#\/add-credential/)
+  await walletPage
+    .getByRole('textbox', { name: /Paste a URL/ })
+    .fill(credentialJson)
+  await walletPage.getByRole('button', { name: 'Add' }).click()
+  await expect(walletPage).toHaveURL(/#\/accept-credentials/)
+  await walletPage.getByRole('button', { name: 'Accept all' }).click()
+  await expect(walletPage).toHaveURL(/#\/dashboard/)
+}
+
+/* ------------------------------ app helpers ------------------------------ */
+
+interface ChapiBridgeRequest {
+  id: number
+  type: 'get' | 'store'
+  body: unknown
+}
+
+/** Arms the app-side CHAPI bridge (must run before the page loads). */
+async function armChapiBridge(page: Page) {
+  await page.addInitScript(() => {
+    ;(
+      window as unknown as { __WAS_REACT_E2E_CHAPI__?: boolean }
+    ).__WAS_REACT_E2E_CHAPI__ = true
+  })
+}
+
+/** Pops the next queued CHAPI request from the app page. */
+async function popChapiRequest(page: Page): Promise<ChapiBridgeRequest> {
+  let request: ChapiBridgeRequest | null = null
+  await expect
+    .poll(
+      async () => {
+        request = await page.evaluate(
+          () =>
+            (
+              window as unknown as {
+                __WAS_REACT_E2E_CHAPI_REQUESTS__?: ChapiBridgeRequest[]
+              }
+            ).__WAS_REACT_E2E_CHAPI_REQUESTS__?.shift() ?? null
+        )
+        return request
+      },
+      { timeout: 30_000, intervals: [300] }
+    )
+    .not.toBeNull()
+  return request as unknown as ChapiBridgeRequest
+}
+
+/** Posts a wire response for a bridged CHAPI request. */
+async function respondChapi(page: Page, id: number, value: unknown) {
+  await page.evaluate(
+    ([responseId, responseValue]) => {
+      const win = window as unknown as {
+        __WAS_REACT_E2E_CHAPI_RESPONSES__?: Record<number, unknown>
+      }
+      win.__WAS_REACT_E2E_CHAPI_RESPONSES__ ??= {}
+      win.__WAS_REACT_E2E_CHAPI_RESPONSES__[responseId as number] =
+        responseValue
+    },
+    [id, value] as const
+  )
+}
+
+/** Runs the app side of one full wallet login from the login page. */
+async function loginFromAppPage(
+  appPage: Page,
+  walletContext: BrowserContext,
+  {
+    passphrase,
+    walletPage,
+    expectFirstRun
+  }: { passphrase: string; walletPage: Page; expectFirstRun: boolean }
+) {
+  const loginButton = appPage.getByRole('button', { name: 'Login with wallet' })
+  await expect(loginButton).toBeEnabled({ timeout: 15_000 })
+  await loginButton.click()
+
+  // Popup #1: the seed probe.
+  const probe = await popChapiRequest(appPage)
+  expect(probe.type).toBe('get')
+  const probeResponse = await driveWalletGet(walletContext, {
+    vpr: probe.body,
+    passphrase,
+    selectCredential: !expectFirstRun
+  })
+  await respondChapi(appPage, probe.id, probeResponse)
+
+  if (expectFirstRun) {
+    // First run: the app stores its key credential in the wallet.
+    const store = await popChapiRequest(appPage)
+    expect(store.type).toBe('store')
+    const offered = store.body as {
+      verifiableCredential: Array<Record<string, unknown>>
+    }
+    const credential = offered.verifiableCredential[0]!
+    expect(credential.type).toContain('ByoeNotesAppKey')
+    await walletAddCredential(walletPage, JSON.stringify(credential))
+    await respondChapi(appPage, store.id, {
+      dataType: 'VerifiablePresentation',
+      data: store.body
+    })
+  }
+
+  // Popup #2: the storage grants.
+  const grants = await popChapiRequest(appPage)
+  expect(grants.type).toBe('get')
+  const grantsResponse = await driveWalletGet(walletContext, {
+    vpr: grants.body,
+    passphrase
+  })
+  await respondChapi(appPage, grants.id, grantsResponse)
+
+  // Login completes and the router lands on the notes shell.
+  await expect(appPage.getByTestId('sync-status-chip')).toBeVisible({
+    timeout: 60_000
+  })
+  await expect(appPage.getByRole('textbox', { name: 'new note' })).toBeVisible()
+}
+
+/** Adds a note on the app's notes page and waits for it to appear. */
+async function addNote(appPage: Page, text: string) {
+  await appPage.getByRole('textbox', { name: 'new note' }).fill(text)
+  await appPage.getByRole('button', { name: 'Add' }).click()
+  await expect(appPage.getByTestId('notes-list').getByText(text)).toBeVisible()
+}
+
+function noteRow(appPage: Page, text: string) {
+  return appPage.getByTestId('notes-list').getByText(text)
+}
+
+/* --------------------------------- test ---------------------------------- */
+
+test('login with wallet: first login, replication, logout/login recovery', async ({
+  context
+}, testInfo) => {
+  /* Phase 0: create the wallet account (stays logged in on the dashboard). */
+  const walletPage = await context.newPage()
+  const { passphrase } = await signupWallet(walletPage, testInfo)
+
+  /* Phase 1: first login -- store the app key, approve grants, enter. */
+  const appPage = await context.newPage()
+  await armChapiBridge(appPage)
+  await appPage.goto(`${APP_URL}/#/login`)
+  await expect(
+    appPage.getByRole('button', { name: 'Login with wallet' })
+  ).toBeVisible()
+  await loginFromAppPage(appPage, context, {
+    passphrase,
+    walletPage,
+    expectFirstRun: true
+  })
+
+  /* Phase 2: write a note and wait for it to replicate to WAS. */
+  const noteText = `wallet-e2e-${Date.now()}`
+  await addNote(appPage, noteText)
+  await expect(appPage.getByTestId('sync-status-chip')).toHaveAttribute(
+    'data-sync-state',
+    'synced',
+    { timeout: 45_000 }
+  )
+
+  /* Phase 3: logout wipes the session; login again = returning path (the wallet
+     returns the stored app key; no store() this time), the note is recovered
+     from WAS. */
+  await appPage.getByRole('button', { name: 'log out' }).click()
+  await expect(
+    appPage.getByRole('button', { name: 'Login with wallet' })
+  ).toBeVisible({ timeout: 15_000 })
+  await loginFromAppPage(appPage, context, {
+    passphrase,
+    walletPage,
+    expectFirstRun: false
+  })
+  await expect(noteRow(appPage, noteText)).toBeVisible({ timeout: 30_000 })
+})

package/test/browser-was/globalSetup.ts

@@ -0,0 +1,6 @@
+import { startServerAndProvision } from './serverLifecycle.js'
+
+/** Playwright globalSetup: boot the WAS server and provision dev grants. */
+export default async function globalSetup(): Promise<void> {
+  await startServerAndProvision()
+}

package/test/browser-was/globalTeardown.ts

@@ -0,0 +1,6 @@
+import { stopServer } from './serverLifecycle.js'
+
+/** Playwright globalTeardown: stop the WAS server started in globalSetup. */
+export default async function globalTeardown(): Promise<void> {
+  await stopServer()
+}