@interop/byoe-react-template 0.1.0

package/playwright.config.ts

@@ -0,0 +1,38 @@
+/**
+ * Offline (mocked) Playwright config: the default suite. Serves the app in
+ * dev auth mode (local dev-seed store, no wallet, no WAS server) and
+ * exercises the UI against the encrypted local replica only. No sibling
+ * checkouts or servers needed; this is the tier suited to CI.
+ *
+ * Run: pnpm run test:browser
+ */
+import { defineConfig, devices } from '@playwright/test'
+
+const APP_PORT = 5173
+
+export default defineConfig({
+  testDir: './test/browser',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: `http://localhost:${APP_PORT}`,
+    trace: 'on-first-retry'
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] }
+    }
+  ],
+  webServer: {
+    command: `pnpm exec vite --port ${APP_PORT} --strictPort`,
+    url: `http://localhost:${APP_PORT}/`,
+    reuseExistingServer: !process.env.CI,
+    env: {
+      VITE_AUTH_MODE: 'dev'
+    }
+  }
+})

package/playwright.wallet.config.ts

@@ -0,0 +1,82 @@
+/**
+ * Wallet-login (Login With Wallet) Playwright config. Boots three servers:
+ * a local was-teaching-server (sibling checkout, override with
+ * WAS_SERVER_DIR), the freewallet dev server (sibling checkout, override with
+ * FREEWALLET_DIR), and this app in wallet auth mode. CHAPI is driven through
+ * the library's non-production e2e bridge (no mediator). Ports are distinct
+ * from every other suite so configs can never clash.
+ *
+ * Run: pnpm run test:browser:wallet
+ */
+import { resolve } from 'node:path'
+import { defineConfig, devices } from '@playwright/test'
+
+const APP_PORT = 5177
+const WALLET_PORT = 5277
+const WAS_PORT = 3103
+export const APP_URL = `http://localhost:${APP_PORT}`
+export const WALLET_URL = `http://localhost:${WALLET_PORT}`
+export const WAS_URL = `http://localhost:${WAS_PORT}`
+
+const WALLET_DIR = resolve(process.env.FREEWALLET_DIR ?? '../freewallet')
+const WAS_SERVER_DIR = resolve(
+  process.env.WAS_SERVER_DIR ?? '../was-teaching-server'
+)
+
+export default defineConfig({
+  testDir: './test/browser-wallet',
+  testMatch: /.*\.spec\.ts/,
+  fullyParallel: false,
+  workers: 1,
+  forbidOnly: !!process.env.CI,
+  retries: 0,
+  reporter: [['html', { outputFolder: 'playwright-report-wallet' }]],
+  outputDir: 'test-results-wallet',
+  timeout: 360_000,
+  use: {
+    baseURL: APP_URL,
+    trace: 'retain-on-failure'
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] }
+    }
+  ],
+  webServer: [
+    {
+      // Local WAS teaching server; SERVER_URL must exactly match the URL both
+      // the wallet and this app sign zcap requests against.
+      command: 'pnpm run dev',
+      cwd: WAS_SERVER_DIR,
+      url: WAS_URL,
+      reuseExistingServer: !process.env.CI,
+      env: { PORT: String(WAS_PORT), SERVER_URL: WAS_URL },
+      timeout: 60_000
+    },
+    {
+      // freewallet dev server pointed at the local WAS server (its KMS rides
+      // on the WAS server's in-process /kms facet).
+      command: `pnpm exec vite --cors --host --port ${WALLET_PORT} --strictPort`,
+      cwd: WALLET_DIR,
+      url: WALLET_URL,
+      reuseExistingServer: false,
+      env: { VITE_WAS_SERVER_URL: WAS_URL },
+      timeout: 60_000
+    },
+    {
+      // This app in wallet auth mode.
+      command: `pnpm exec vite --port ${APP_PORT} --strictPort`,
+      url: `${APP_URL}/`,
+      reuseExistingServer: false,
+      env: {
+        VITE_AUTH_MODE: 'wallet',
+        VITE_APP_ORIGIN: APP_URL,
+        VITE_WAS_SERVER_URL: WAS_URL,
+        VITE_WAS_SYNC_RETRY_MS: '1500',
+        VITE_WAS_SYNC_POLL_MS: '1500'
+      },
+      timeout: 60_000
+    }
+  ]
+})

package/playwright.was.config.ts

@@ -0,0 +1,56 @@
+/**
+ * WAS-backed Playwright config: real replication against a local
+ * was-teaching-server booted from a sibling checkout (override with
+ * WAS_SERVER_DIR), with dev grants provisioned in globalSetup. The app runs
+ * in dev auth mode with dev-sync on, on a dedicated port so it never clashes
+ * with the offline suite's dev server. Tests are serialized (a single shared
+ * Space).
+ *
+ * Run: pnpm run test:browser:was
+ */
+import { defineConfig, devices } from '@playwright/test'
+
+const APP_PORT = 5174
+export const WAS_PORT = Number(process.env.WAS_E2E_PORT ?? 3102)
+export const WAS_URL = `http://localhost:${WAS_PORT}`
+
+export default defineConfig({
+  testDir: './test/browser-was',
+  testMatch: /.*\.spec\.ts/,
+  // One shared WAS Space across tests; serialize to keep assertions clean.
+  fullyParallel: false,
+  workers: 1,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  reporter: [['html', { outputFolder: 'playwright-report-was' }]],
+  outputDir: 'test-results-was',
+  timeout: 60_000,
+  globalSetup: './test/browser-was/globalSetup.ts',
+  globalTeardown: './test/browser-was/globalTeardown.ts',
+  use: {
+    baseURL: `http://localhost:${APP_PORT}`,
+    trace: 'on-first-retry'
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] }
+    }
+  ],
+  webServer: {
+    command: `pnpm exec vite --port ${APP_PORT} --strictPort`,
+    url: `http://localhost:${APP_PORT}/`,
+    reuseExistingServer: false,
+    timeout: 60_000,
+    env: {
+      VITE_AUTH_MODE: 'dev',
+      VITE_WAS_DEV_SYNC: 'true',
+      // Must EXACTLY equal the server's SERVER_URL (zcap invocation targets).
+      VITE_WAS_SERVER_URL: WAS_URL,
+      // Snappier backoff + change-feed polling so multi-device convergence
+      // and offline/online recovery land within the test timeouts.
+      VITE_WAS_SYNC_RETRY_MS: '1500',
+      VITE_WAS_SYNC_POLL_MS: '1500'
+    }
+  }
+})

package/pnpm-workspace.yaml

@@ -0,0 +1,11 @@
+allowBuilds:
+  core-js: false
+  esbuild: true
+minimumReleaseAgeExclude:
+  - '@interop/data-integrity-core@8.2.0'
+  - '@interop/storage-core@0.3.3 || 0.3.4'
+  - '@interop/was-client@0.13.3 || 0.14.5'
+  - '@interop/was-react@0.1.2 || 0.1.3'
+  - '@interop/x25519-key-agreement-key@5.1.2 || 5.2.0'
+  - '@interop/edv-client@17.6.1'
+  - '@interop/minimal-cipher@7.6.1'

package/prettier.config.js

@@ -0,0 +1,9 @@
+export default {
+  arrowParens: 'avoid',
+  bracketSameLine: false,
+  bracketSpacing: true,
+  proseWrap: 'always',
+  semi: false,
+  singleQuote: true,
+  trailingComma: 'none'
+}

package/scripts/provision-dev-grants.ts

@@ -0,0 +1,42 @@
+/**
+ * Dev grant provisioning (CHAPI bypassed): against a running
+ * was-teaching-server, creates a dev Space plus the app's collections, and
+ * delegates a per-collection read/write zcap to the app DID derived from the
+ * dev seed. The signed grants land in a git-ignored JSON file the app loads
+ * in dev-sync mode.
+ *
+ * Run (with the server already up on $SERVER_URL):
+ *   pnpm run provision:dev
+ *
+ * Reads (all optional):
+ *   SERVER_URL       WAS base URL (default http://localhost:3002)
+ *   DEV_GRANTS_OUT   output path (default <repo>/public/dev-grants.local.json)
+ */
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { provisionDevGrants } from '@interop/was-react/dev'
+import { COLLECTIONS } from '../src/app.config.ts'
+import { DEV_SEED } from '../src/dev/devSeed.ts'
+
+const SERVER_URL = process.env.SERVER_URL ?? 'http://localhost:3002'
+const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const OUT_PATH =
+  process.env.DEV_GRANTS_OUT ??
+  join(repoRoot, 'public', 'dev-grants.local.json')
+
+async function main(): Promise<void> {
+  const result = await provisionDevGrants({
+    serverUrl: SERVER_URL,
+    seed: DEV_SEED,
+    collections: COLLECTIONS.map(collection => collection.id),
+    spaceName: 'BYOE Notes (dev)',
+    outFile: OUT_PATH,
+    log: console.log
+  })
+  console.log(`\nWrote ${result.grants.length} grants to ${OUT_PATH}`)
+}
+
+main().catch(err => {
+  console.error('Provisioning failed:', err)
+  process.exit(1)
+})

package/src/App.tsx

@@ -0,0 +1,34 @@
+/**
+ * App root: CssBaseline, the HashRouter, and the route table. The login page
+ * sits outside the gate; the notes page renders behind the wallet-mode
+ * `ProtectedRoute` (from `@interop/was-react/mui`) or the dev-mode `DevGate`,
+ * inside the `AppShell` layout.
+ */
+import { HashRouter, Route, Routes } from 'react-router'
+import { CssBaseline } from '@mui/material'
+import { ProtectedRoute } from '@interop/was-react/mui'
+import { AUTH_MODE } from '@/app.config'
+import { AppShell } from '@/components/AppShell'
+import { DevGate } from '@/components/DevGate'
+import { LoginPage } from '@/pages/LoginPage'
+import { NotesPage } from '@/pages/NotesPage'
+
+export function App() {
+  return (
+    <>
+      <CssBaseline />
+      <HashRouter>
+        <Routes>
+          <Route path="/login" element={<LoginPage />} />
+          <Route
+            element={AUTH_MODE === 'wallet' ? <ProtectedRoute /> : <DevGate />}
+          >
+            <Route element={<AppShell />}>
+              <Route index element={<NotesPage />} />
+            </Route>
+          </Route>
+        </Routes>
+      </HashRouter>
+    </>
+  )
+}

package/src/app.config.ts

@@ -0,0 +1,73 @@
+/**
+ * Application configuration: environment-variable exports, the collection
+ * registry, and the one `WasAppConfig` the library consumes.
+ *
+ * When renaming this template into a real app, this file is the first stop:
+ * app name, credential type/vocab, and the collection list all live here.
+ */
+import type { WasAppConfig, WasCollectionConfig } from '@interop/was-react'
+
+// Vite injects `import.meta.env` in the browser build; a plain Node context
+// (the dev provisioning script, or a bare `tsx` import) has no such object, so
+// fall back to an empty record rather than throwing on property access.
+const env: Record<string, string | undefined> =
+  (import.meta.env as Record<string, string | undefined> | undefined) ?? {}
+
+// This app's own origin: the CHAPI anti-phishing origin binding on the app-key
+// credential. Must match the URL the app is actually served from.
+export const APP_ORIGIN = env.VITE_APP_ORIGIN || 'http://localhost:5173'
+
+// Auth mode: 'wallet' (default) gates the app behind Login With Wallet
+// (CHAPI); 'dev' boots straight into a local dev-seed store with no login
+// gate (offline-first, optionally dev-syncing under VITE_WAS_DEV_SYNC).
+export const AUTH_MODE: 'dev' | 'wallet' =
+  env.VITE_AUTH_MODE === 'dev' ? 'dev' : 'wallet'
+
+// Remote WAS server URL. In wallet mode this is the expected host of every
+// granted zcap's invocationTarget (grants pointing anywhere else are rejected
+// at login).
+export const WAS_SERVER_URL = env.VITE_WAS_SERVER_URL || 'http://localhost:3002'
+
+// Dev-sync mode (CHAPI bypassed; dev auth mode only): when truthy, the app
+// loads a locally provisioned grants file and replicates to a running
+// was-teaching-server using the dev seed's delegated zcaps. Off by default.
+export const WAS_DEV_SYNC =
+  env.VITE_WAS_DEV_SYNC === 'true' || env.VITE_WAS_DEV_SYNC === '1'
+
+// URL the app fetches the dev grants JSON from (a git-ignored file written
+// into `public/` by `pnpm run provision:dev`; Vite serves `public/` at root).
+export const WAS_DEV_GRANTS_URL =
+  env.VITE_WAS_DEV_GRANTS_URL || '/dev-grants.local.json'
+
+// Replication tuning (optional). Undefined leaves the library defaults.
+export const WAS_SYNC_RETRY_MS: number | undefined = env.VITE_WAS_SYNC_RETRY_MS
+  ? Number(env.VITE_WAS_SYNC_RETRY_MS)
+  : undefined
+export const WAS_SYNC_POLL_MS: number | undefined = env.VITE_WAS_SYNC_POLL_MS
+  ? Number(env.VITE_WAS_SYNC_POLL_MS)
+  : undefined
+
+/**
+ * The storage collections: each logical `key` (the app-side / RxDB collection
+ * handle) mapped to its WAS collection `id` (a deliberately unprefixed,
+ * generic name shared across interoperable apps). This template has one.
+ */
+export const COLLECTIONS: WasCollectionConfig[] = [
+  { key: 'notes', id: 'notes' }
+]
+
+/** The app-wide was-react configuration. */
+export const appConfig: WasAppConfig = {
+  appName: 'BYOE Notes',
+  appOrigin: APP_ORIGIN,
+  wasServerUrl: WAS_SERVER_URL,
+  collections: COLLECTIONS,
+  credential: {
+    credentialType: 'ByoeNotesAppKey',
+    vocabBase: 'urn:byoe-notes:vocab#'
+  },
+  sync: {
+    ...(WAS_SYNC_RETRY_MS !== undefined && { retryMs: WAS_SYNC_RETRY_MS }),
+    ...(WAS_SYNC_POLL_MS !== undefined && { pollMs: WAS_SYNC_POLL_MS })
+  }
+}

package/src/components/AppShell.tsx

@@ -0,0 +1,58 @@
+/**
+ * The app layout: a top bar with the app name, the library's `SyncStatusChip`
+ * (offline / syncing / synced / error rollup), and a logout button (wallet
+ * mode only), with the `ReconnectBanner` (shown when granted access nears
+ * expiry) above the routed page content.
+ */
+import { Outlet, useNavigate } from 'react-router'
+import {
+  AppBar,
+  Box,
+  Container,
+  IconButton,
+  Toolbar,
+  Tooltip,
+  Typography
+} from '@mui/material'
+import LogoutIcon from '@mui/icons-material/Logout'
+import { useLogout } from '@interop/was-react'
+import { ReconnectBanner, SyncStatusChip } from '@interop/was-react/mui'
+import { AUTH_MODE } from '@/app.config'
+
+export function AppShell() {
+  const logout = useLogout()
+  const navigate = useNavigate()
+
+  async function handleLogout() {
+    await logout()
+    navigate('/login')
+  }
+
+  return (
+    <Box sx={{ minHeight: '100vh' }}>
+      <AppBar position="static">
+        <Toolbar sx={{ gap: 2 }}>
+          <Typography variant="h6" component="h1" sx={{ flexGrow: 1 }}>
+            BYOE Notes
+          </Typography>
+          <SyncStatusChip />
+          {AUTH_MODE === 'wallet' && (
+            <Tooltip title="Log out">
+              <IconButton
+                color="inherit"
+                aria-label="log out"
+                onClick={() => void handleLogout()}
+              >
+                <LogoutIcon />
+              </IconButton>
+            </Tooltip>
+          )}
+        </Toolbar>
+      </AppBar>
+      <ReconnectBanner />
+      <Container maxWidth="sm" sx={{ py: 4 }}>
+        <Outlet />
+      </Container>
+    </Box>
+  )
+}

package/src/components/DevGate.tsx

@@ -0,0 +1,51 @@
+/**
+ * Dev-mode router gate: kicks off `initApp` (local dev seed, no login) and
+ * waits for hydration before rendering the routed pages. The wallet-mode
+ * equivalent is the library's `ProtectedRoute`; the route table picks one by
+ * `AUTH_MODE`.
+ */
+import { useEffect } from 'react'
+import { Outlet } from 'react-router'
+import { Alert, Box, CircularProgress, Typography } from '@mui/material'
+import { useAppReady } from '@interop/was-react'
+import { initApp } from '@/dev/bootstrap'
+
+export function DevGate() {
+  const ready = useAppReady(s => s.ready)
+  const error = useAppReady(s => s.error)
+
+  useEffect(() => {
+    void initApp()
+  }, [])
+
+  if (error) {
+    return (
+      <Box sx={{ p: 4 }}>
+        <Alert severity="error" data-testid="bootstrap-error">
+          Failed to open local storage: {error}
+        </Alert>
+      </Box>
+    )
+  }
+
+  if (!ready) {
+    return (
+      <Box
+        sx={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: 2,
+          minHeight: '60vh'
+        }}
+        data-testid="bootstrap-loading"
+      >
+        <CircularProgress />
+        <Typography color="text.secondary">Opening your storage...</Typography>
+      </Box>
+    )
+  }
+
+  return <Outlet />
+}

package/src/dev/bootstrap.ts

@@ -0,0 +1,54 @@
+/**
+ * Dev-mode bootstrap: opens the encrypted local store from the dev seed and
+ * hydrates the entity stores from it, then flips the library's `useAppReady`
+ * gate the router waits on. Idempotent -- concurrent callers share one
+ * in-flight promise.
+ *
+ * Wallet mode does not use `initApp`; there the library's auth store owns the
+ * open/hydrate ordering (seed from the wallet session) and drives the same
+ * `useAppReady` gate.
+ */
+import {
+  hasStore,
+  hydrateAll,
+  LocalStore,
+  setLocalStore,
+  useAppReady
+} from '@interop/was-react'
+import { appConfig, WAS_DEV_SYNC } from '@/app.config'
+import { DEV_SEED } from '@/dev/devSeed'
+import { registry } from '@/stores/notes'
+
+let inFlight: Promise<void> | null = null
+
+/** Open the store (once) from the dev seed and hydrate every collection. */
+export function initApp(): Promise<void> {
+  if (inFlight) {
+    return inFlight
+  }
+  inFlight = (async () => {
+    try {
+      if (!hasStore()) {
+        const store = await LocalStore.init({
+          seed: DEV_SEED,
+          collections: appConfig.collections
+        })
+        setLocalStore(store)
+      }
+      await hydrateAll(registry)
+      useAppReady.getState().setReady()
+      // Dev-sync: start WAS replication in the background AFTER the UI gate
+      // opens, so a missing/unreachable server never blocks first paint.
+      if (WAS_DEV_SYNC) {
+        void import('@/dev/devSync')
+          .then(({ startDevSync }) => startDevSync())
+          .catch(err => console.warn('Dev-sync failed to start:', err))
+      }
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause)
+      useAppReady.getState().setError(message)
+      throw cause
+    }
+  })()
+  return inFlight
+}

package/src/dev/devSeed.ts

@@ -0,0 +1,13 @@
+/**
+ * The fixed dev-mode master seed (32 bytes). Dev auth mode derives the app's
+ * identity and vault keys from this seed instead of a wallet-held one, so a
+ * dev session is stable across restarts and provisioning runs.
+ *
+ * NEVER use this seed (or dev auth mode) in production: it is public, so
+ * anything encrypted under it is readable by anyone.
+ */
+export const DEV_SEED = new Uint8Array([
+  0x62, 0x79, 0x6f, 0x65, 0x2d, 0x6e, 0x6f, 0x74, 0x65, 0x73, 0x2d, 0x64, 0x65,
+  0x76, 0x2d, 0x73, 0x65, 0x65, 0x64, 0x2d, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35,
+  0x36, 0x37, 0x38, 0x39, 0x41, 0x42
+])

package/src/dev/devSync.ts

@@ -0,0 +1,80 @@
+/**
+ * Dev-sync bootstrap (CHAPI bypassed): when dev-sync is on, the app fetches a
+ * locally provisioned grants file, rebuilds the delegated remote store from
+ * those zcaps and the dev seed's ZcapClient, and starts background
+ * replication. This stands in for the Login-With-Wallet flow: there the
+ * grants arrive over CHAPI; here they are minted by `pnpm run provision:dev`
+ * against a running was-teaching-server.
+ */
+import {
+  createSyncController,
+  deriveIdentity,
+  parseGrants,
+  patchFromChange,
+  requireStore,
+  startWasSync,
+  type IZcap
+} from '@interop/was-react'
+import { appConfig, WAS_DEV_GRANTS_URL } from '@/app.config'
+import { DEV_SEED } from '@/dev/devSeed'
+import { registry } from '@/stores/notes'
+
+/**
+ * Fetches and parses the dev grants file. Returns `null` (with a warning)
+ * when it is missing or malformed, so a not-yet-provisioned dev environment
+ * degrades to offline-only rather than erroring the whole bootstrap.
+ */
+async function loadDevGrants(): Promise<IZcap[] | null> {
+  try {
+    const response = await fetch(WAS_DEV_GRANTS_URL, { cache: 'no-store' })
+    if (!response.ok) {
+      console.warn(
+        `Dev grants not available at "${WAS_DEV_GRANTS_URL}" (status ${response.status}); running offline.`
+      )
+      return null
+    }
+    const body = (await response.json()) as { grants?: IZcap[] } | IZcap[]
+    const grants = Array.isArray(body) ? body : body.grants
+    if (!grants || grants.length === 0) {
+      console.warn('Dev grants file has no grants; running offline.')
+      return null
+    }
+    return grants
+  } catch (err) {
+    console.warn('Failed to load dev grants; running offline.', err)
+    return null
+  }
+}
+
+let started = false
+
+/**
+ * Starts dev-sync: loads grants, builds the remote store, and starts
+ * replication with reactive store patching. Idempotent and best-effort --
+ * any failure leaves the app in offline mode.
+ */
+export async function startDevSync(): Promise<void> {
+  if (started) {
+    return
+  }
+  const grants = await loadDevGrants()
+  if (!grants) {
+    return
+  }
+  started = true
+
+  const parsed = parseGrants(grants)
+  const { zcapClient } = await deriveIdentity({ seed: DEV_SEED })
+  await startWasSync({
+    parsed,
+    zcapClient,
+    localStore: requireStore(),
+    syncController: createSyncController({
+      collections: appConfig.collections,
+      ...(appConfig.sync && { sync: appConfig.sync })
+    }),
+    onRemoteChange: (key, event) => {
+      void patchFromChange(registry, key, event)
+    }
+  })
+}

package/src/main.tsx

@@ -0,0 +1,24 @@
+/**
+ * Entry point: mounts the app inside `WasSessionProvider`, which builds the
+ * session/auth store once from the app config and store registry. The
+ * provider sits ABOVE the router so every route (including /login) can reach
+ * the session hooks.
+ */
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { WasSessionProvider } from '@interop/was-react'
+import { appConfig } from '@/app.config'
+import { registry } from '@/stores/notes'
+import { App } from '@/App'
+
+const container = document.getElementById('root')
+if (!container) {
+  throw new Error('Root container #root not found.')
+}
+createRoot(container).render(
+  <StrictMode>
+    <WasSessionProvider config={appConfig} registry={registry}>
+      <App />
+    </WasSessionProvider>
+  </StrictMode>
+)