@interop/was-react 0.1.0

package/LICENSE.md

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Interop Alliance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,410 @@
+# @interop/was-react _(@interop/was-react)_
+
+[![NPM Version](https://img.shields.io/npm/v/@interop/was-react.svg)](https://npm.im/@interop/was-react)
+
+> React library for building "Bring Your Own Everything" (BYOE) apps on Wallet
+> Attached Storage: DID-Auth login via a CHAPI wallet, local-first encrypted
+> storage, and background sync to a WAS server.
+
+## Table of Contents
+
+- [Background](#background)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Login flow](#login-flow)
+- [Session lifecycle](#session-lifecycle)
+- [Sync architecture](#sync-architecture)
+- [Entry points](#entry-points)
+- [Dev tooling](#dev-tooling)
+- [Testing](#testing)
+- [Contribute](#contribute)
+- [License](#license)
+
+## Background
+
+"Bring Your Own Everything" (BYOE) is a way to build web apps with no backend
+that the app owns. The user brings their own identity (a wallet) and their own
+storage (Wallet Attached Storage, WAS), and the app stores everything encrypted
+in that user-owned space. The app is a Relying Party (RP): it authenticates via
+"Login With Wallet" (CHAPI) and reads and writes the user's WAS space using
+wallet-delegated authorization capabilities (zcaps). It never owns the space,
+never holds the wallet's root key, and invokes only the zcaps the wallet grants
+it.
+
+"Bring Your Own Storage" (BYOS) is the storage half of that model. Every
+application collection is encrypted client-side as an Encrypted Data Vault
+(EDV): the WAS server only ever sees opaque JWE envelopes and can neither read
+nor search the plaintext. Data is local-first -- a local RxDB (IndexedDB)
+database holds the encrypted envelopes and replicates them to WAS in the
+background. The app works fully offline; sync resumes on reconnect.
+
+`@interop/was-react` is the reusable plumbing for that model, extracted from a
+production BYOE app. It wraps
+[`@interop/was-client`](https://npm.im/@interop/was-client) and owns identity
+derivation, the CHAPI login flow, the session lifecycle store, the encrypted
+local replica, WAS replication, and a small set of React hooks and optional MUI
+components. An app supplies its configuration, its collection registry, and its
+own domain and UI; the library owns everything in between.
+
+## Install
+
+Node.js 24+ is recommended. The package is ESM-only.
+
+```
+pnpm add @interop/was-react
+```
+
+Peer dependencies (install the ones you use):
+
+```
+pnpm add react zustand rxdb
+```
+
+`react >= 19`, `zustand ^5`, and `rxdb ^17` are required peers. The optional
+`@interop/was-react/mui` entry additionally needs `@mui/material`,
+`@mui/icons-material`, and `react-router`; the core entry never imports them.
+
+```
+pnpm add @mui/material @mui/icons-material @emotion/react @emotion/styled react-router
+```
+
+## Quick start
+
+An app builds one `WasAppConfig`, a `StoreRegistry` (per-collection hydrate and
+patch handlers), wraps its tree in `<WasSessionProvider>`, and drives the
+session through the hooks. The example below wires a single `notes` collection.
+
+### 1. Configuration
+
+```ts
+// app.config.ts
+import type { WasAppConfig } from '@interop/was-react'
+
+export const config: WasAppConfig = {
+  appName: 'Notes',
+  appOrigin: 'https://notes.example',
+  wasServerUrl: 'https://was.example',
+  collections: [{ key: 'notes', id: 'notes' }],
+  credential: {
+    credentialType: 'NotesAppKey',
+    vocabBase: 'urn:notes-app:vocab#'
+  }
+}
+```
+
+`collections` maps each app-side `key` (the local RxDB collection handle) to a
+WAS collection `id` (a deliberately unprefixed, generic name shared across
+interoperable apps). `credential` names the self-issued seed credential the
+first-run flow mints. All other fields (`mediatorBase`, `dbName`,
+`storageKeyPrefix`, `sync`, `expiry`) are optional with documented defaults.
+
+### 2. Entity stores and the registry
+
+```ts
+// stores.ts
+import { createEntityStore, type StoreRegistry } from '@interop/was-react'
+
+export interface Note {
+  id: string
+  title: string
+  body: string
+  createdAt: string
+  updatedAt: string
+}
+
+export const useNotes = createEntityStore<Note>('notes')
+
+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([])
+  }
+}
+```
+
+`createEntityStore` returns a zustand hook holding the decrypted payloads as a
+`Map<uuid, Note>`; its `insert` / `update` / `remove` verbs persist through the
+encrypted local store, while `hydrate` / `patch` / `drop` / `replaceAll` are the
+handlers the rehydrate mechanism drives on login, remote sync, and logout.
+
+### 3. Provider
+
+```tsx
+// main.tsx
+import { WasSessionProvider } from '@interop/was-react'
+import { config } from './app.config.js'
+import { registry } from './stores.js'
+
+export function Root() {
+  return (
+    <WasSessionProvider config={config} registry={registry}>
+      <App />
+    </WasSessionProvider>
+  )
+}
+```
+
+### 4. Login page
+
+```tsx
+// LoginPage.tsx
+import { useLogin } from '@interop/was-react'
+
+export function LoginPage() {
+  const { login, status, phase, error } = useLogin()
+  const busy = status === 'authenticating'
+
+  return (
+    <div>
+      <button onClick={() => void login()} disabled={busy}>
+        {busy ? 'Connecting your wallet...' : 'Login with wallet'}
+      </button>
+      {busy && phase && <p>{phase}</p>}
+      {error && <p role="alert">{error}</p>}
+    </div>
+  )
+}
+```
+
+### 5. Reading and writing
+
+```tsx
+import { uuidv7 } from 'uuidv7'
+import { useNotes } from './stores.js'
+
+export function Notes() {
+  const notes = useNotes(state => [...state.byId.values()])
+  const insert = useNotes(state => state.insert)
+
+  async function addNote() {
+    const now = new Date().toISOString()
+    await insert({
+      id: uuidv7(),
+      title: 'Untitled',
+      body: '',
+      createdAt: now,
+      updatedAt: now
+    })
+  }
+
+  return (
+    <div>
+      <button onClick={() => void addNote()}>Add note</button>
+      <ul>
+        {notes.map(note => (
+          <li key={note.id}>{note.title}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+The MUI entry supplies a router gate and status UI on top of this; see
+[Entry points](#entry-points).
+
+## Login flow
+
+Login is driven by CHAPI Verifiable Presentation Requests (VPRs). The
+`useLogin().login()` action (backed by `loginWithWallet`) runs the flow, with a
+`phase` string surfaced for a progress line (`probing` to `storing-key` to
+`requesting-grants` to `verifying`):
+
+1. **CHAPI polyfill loads lazily.** The `credential-handler-polyfill` is loaded
+   on demand the first time a wallet request is made, not at import time.
+2. **Probe (popup #1).** A VPR asking for DIDAuthentication plus the app's seed
+   credential is sent to the wallet. No credential returned means this is a
+   first run.
+3. **First run: mint and store the seed.** A fresh 32-byte master seed is
+   generated (`crypto.getRandomValues`), a seed credential is self-issued
+   (`issueSeedCredential`, using the configured `credentialType` and `vocabBase`
+   plus the app `origin` anti-phishing bind), and stored in the wallet via
+   `chapiStore`. The flow blocks until the wallet confirms the store -- a
+   dismissed store would silently break cross-device recovery.
+4. **Returning login: recover and verify.** When the probe returns the seed
+   credential, `parseSeedCredential` recovers the seed and cryptographically
+   verifies the credential is self-issued, origin-bound, and seed-to-DID bound.
+5. **Derive identity.** The stable `did:key` controller and its signer are
+   derived deterministically from the seed via `CapabilityAgent.fromSeed`
+   (`initAppSession` / `deriveIdentity`). The same seed yields the same identity
+   on every device.
+6. **Request grants (popup #2).** `buildGrantsVpr` requests a per-collection
+   read/write zcap (plus a read-only space grant) for the controller DID. The
+   wallet provisions the collections and returns a signed presentation.
+7. **Verify the response.** `verifyLoginPresentation` checks the VP and embedded
+   proofs (purpose `authentication`, matching domain and challenge), and
+   `checkGrants` asserts every zcap is controlled by the app DID, targets the
+   configured `wasServerUrl`, shares one space, and is unexpired.
+8. **Activate.** The session (seed, grants, earliest expiry) is persisted to
+   IndexedDB, the encrypted local store is opened, the entity stores hydrate,
+   and background WAS sync starts.
+
+## Session lifecycle
+
+The session is owned by a zustand auth store built once per app by the provider
+(`createAuthStore`). Its `status` is `idle` to `restoring` to `unauthenticated`
+/ `authenticating` / `authenticated`, and it is the router gate: a protected
+route waits for the restore attempt to settle before choosing between the app
+and the login page.
+
+- **Restore (zero popups).** On mount, `restore()` reads the persisted session
+  from IndexedDB and, if present and consistent, re-derives the identity, opens
+  the local store, hydrates, and starts sync with no wallet interaction. A
+  missing, corrupt, or wrong-server record falls through to `unauthenticated`.
+- **Login.** `useLogin().login()` runs the full [login flow](#login-flow).
+- **Reconnect.** Grants are expiry-only. The store watches the earliest grant
+  expiry and, once within the warning window (`expiry.warningMs`, default 1h) or
+  after a live 401/403, sets `accessExpired`. `useReconnect().reconnect()`
+  re-requests grants with the existing seed (one wallet popup, same identity,
+  same data) and restarts sync.
+- **Logout.** `useLogout()` stops sync, closes and forgets the local store,
+  clears the entity stores, and clears the persisted session.
+- **Expiry.** Because the seed survives grant expiry and the derived DID and
+  vault keys are stable, an expired session re-grants in place; previously
+  stored data stays readable.
+
+Hooks:
+
+| Hook              | Returns                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------- |
+| `useSession()`    | `status`, `phase`, `error`, `controllerDid`, `expires`, `accessExpired`, `reconnecting` |
+| `useLogin()`      | `{ login, status, phase, error }`                                                       |
+| `useLogout()`     | `() => Promise<void>`                                                                   |
+| `useReconnect()`  | `{ accessExpired, reconnecting, reconnect }`                                            |
+| `useSyncStatus()` | `{ state, label, title }` (see below)                                                   |
+| `useAppReady()`   | `{ ready, error }` -- the hydration gate                                                |
+| `useAuthStore()`  | the bound vanilla store (for `getState().restore()`, etc.)                              |
+
+## Sync architecture
+
+- **Local-first replica.** An always-on local encrypted RxDB (Dexie/IndexedDB)
+  database (`LocalStore`) holds one collection per app collection. Every at-rest
+  row is `{ id, updatedAt, version, data }`, where `data` is an EDV envelope
+  `{ id, sequence, jwe }`. The app reads exclusively from the in-memory entity
+  stores hydrated from this replica, so it works fully offline.
+- **Envelope encryption.** Each collection is encrypted with its own X25519
+  key-agreement key, HKDF-derived from the master seed with the label
+  `kak:v1:<collectionId>` (`deriveCollectionKeys`). HKDF one-wayness means a
+  shared per-collection key exposes nothing about the master seed or the sibling
+  collections. The WAS server never sees plaintext.
+- **Replication.** A per-session `SyncController` runs RxDB replication per
+  collection over a `WasSyncPort` (signed requests authorized by the granted
+  zcaps). Pull is driven by the WAS `changes` feed; a low-frequency periodic
+  re-sync (`sync.pollMs`, default 15s) keeps open sessions converging.
+- **Conflict resolution.** Last-writer-wins on the payload's own
+  `(updatedAt, deviceId)` (ISO lexical compare, with a per-install random
+  `deviceId` tiebreaker). Updates re-encrypt in place under the same envelope id
+  with `sequence`+1 (a mutable-head model); deletes are soft-delete tombstones.
+- **Status.** `useSyncStatus()` rolls the per-collection replication states up
+  to an aggregate: `offline` (no replication running / local-only), or
+  `error > syncing > synced`. The `SyncStatusChip` MUI component renders it.
+
+## Entry points
+
+The package exposes three entry points. `./mui` and `./dev` are never
+re-exported from the root, so an app that does not use them pays no dependency
+cost.
+
+| Import                   | Contents                                                                             | Extra peers                                            |
+| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
+| `@interop/was-react`     | Core: config, identity, auth, sync, storage, session store, React provider and hooks | `react`, `zustand`, `rxdb`                             |
+| `@interop/was-react/mui` | Optional `ProtectedRoute`, `ReconnectBanner`, `SyncStatusChip`                       | `@mui/material`, `@mui/icons-material`, `react-router` |
+| `@interop/was-react/dev` | Node-only `provisionDevGrants` + the `was-provision-dev-grants` CLI                  | (none; Node only)                                      |
+
+MUI usage:
+
+```tsx
+import { Routes, Route } from 'react-router'
+import {
+  ProtectedRoute,
+  ReconnectBanner,
+  SyncStatusChip
+} from '@interop/was-react/mui'
+import { LoginPage } from './LoginPage.js'
+
+export function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route element={<ProtectedRoute loginPath="/login" />}>
+        <Route
+          path="/"
+          element={
+            <>
+              <SyncStatusChip />
+              <ReconnectBanner />
+              <Notes />
+            </>
+          }
+        />
+      </Route>
+    </Routes>
+  )
+}
+```
+
+`ProtectedRoute` calls `restore()` on mount, shows a spinner while the session
+restores and the stores hydrate, redirects an unauthenticated visitor to
+`loginPath`, and renders the routed `<Outlet />` once ready.
+
+## Dev tooling
+
+The `./dev` entry provisions a Space, collections, and delegated read/write
+grants against a running was-teaching-server, so an app can dev-sync without a
+CHAPI wallet in the loop. It is Node-only (uses `node:fs`).
+
+CLI:
+
+```
+was-provision-dev-grants \
+  --server-url http://localhost:3002 \
+  --seed <hex-or-base64url 32-byte seed> \
+  --collections notes \
+  --space-name "Dev Space" \
+  --out ./public/dev-grants.local.json
+```
+
+Programmatic:
+
+```ts
+import { provisionDevGrants } from '@interop/was-react/dev'
+
+const result = await provisionDevGrants({
+  serverUrl: 'http://localhost:3002',
+  seed: mySeedBytes,
+  collections: ['notes'],
+  outFile: './public/dev-grants.local.json'
+})
+// result.grants, result.spaceId, result.spaceUrl, result.appDid
+```
+
+A throwaway "provisioner" identity owns the created Space (a genuine
+cross-identity delegation, as in the real wallet-to-relying-party flow), and a
+per-collection RW zcap is delegated to the app DID derived from `seed`. Pass
+`--probe` (or `probe: true`) to check whether the delegated zcap authorizes
+PUTting the EDV encryption marker.
+
+## Testing
+
+The repo runs three test tiers:
+
+```
+pnpm run test:node       # Vitest unit tests (test/node/), Node
+pnpm run test:browser    # Playwright tests (test/browser/), real Chromium
+pnpm test                # fix + lint + typecheck + node + browser
+```
+
+`pnpm run test:coverage` runs the Vitest suite with V8 coverage. The Playwright
+tier runs against a Vite dev server that serves and transforms the TypeScript
+source on the fly; there is no standalone browser app.
+
+## Contribute
+
+PRs accepted. If editing the Readme, please conform to the
+[standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+
+## License
+
+[MIT License](LICENSE.md) © 2026 Interop Alliance. </content> </invoke>

package/dist/auth/chapi.d.ts

@@ -0,0 +1,43 @@
+import type { IVerifiablePresentation } from '@interop/data-integrity-core';
+import type { IVPRDetails } from './walletRequestTypes.js';
+/** The default CHAPI mediator base; the requesting origin is appended at load. */
+export declare const DEFAULT_MEDIATOR_BASE = "https://authn.io/mediator?origin=";
+/**
+ * Loads the CHAPI polyfill once (no-op under the e2e bridge).
+ *
+ * @param [options] {object}
+ * @param [options.mediatorBase] {string}   the mediator base URL (defaults to
+ *   `DEFAULT_MEDIATOR_BASE`)
+ * @returns {Promise<void>}
+ */
+export declare function loadChapi({ mediatorBase }?: {
+    mediatorBase?: string;
+}): Promise<void>;
+/**
+ * Sends a VPR to the user's wallet via CHAPI `credentials.get()`. Returns the
+ * wallet's response VP, or `null` when the user cancelled/dismissed.
+ *
+ * @param options {object}
+ * @param options.vpr {IVPRDetails}
+ * @param [options.mediatorBase] {string}
+ * @returns {Promise<IVerifiablePresentation | null>}
+ */
+export declare function chapiGet({ vpr, mediatorBase }: {
+    vpr: IVPRDetails;
+    mediatorBase?: string;
+}): Promise<IVerifiablePresentation | null>;
+/**
+ * Offers a VP (wrapping a credential) to the wallet via CHAPI
+ * `credentials.store()`. Returns true when the wallet confirmed the store,
+ * false when the user cancelled/dismissed.
+ *
+ * @param options {object}
+ * @param options.presentation {IVerifiablePresentation}
+ * @param [options.mediatorBase] {string}
+ * @returns {Promise<boolean>}
+ */
+export declare function chapiStore({ presentation, mediatorBase }: {
+    presentation: IVerifiablePresentation;
+    mediatorBase?: string;
+}): Promise<boolean>;
+//# sourceMappingURL=chapi.d.ts.map

package/dist/auth/chapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chapi.d.ts","sourceRoot":"","sources":["../../src/auth/chapi.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,sCAAsC,CAAA;AAmDxE;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,EAC9B,YAAoC,EACrC,GAAE;IACD,YAAY,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,EAC7B,GAAG,EACH,YAAY,EACb,EAAE;IACD,GAAG,EAAE,WAAW,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAgB1C;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,EAC/B,YAAY,EACZ,YAAY,EACb,EAAE;IACD,YAAY,EAAE,uBAAuB,CAAA;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,GAAG,OAAO,CAAC,OAAO,CAAC,CAcnB"}

package/dist/auth/chapi.js

@@ -0,0 +1,107 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/// <reference types="vite/client" />
+/**
+ * The CHAPI transport: credential-handler-polyfill loading (authn.io mediator)
+ * plus thin `get()` / `store()` wrappers around `navigator.credentials`.
+ *
+ * E2E seam (non-production builds only): the real CHAPI channel needs the
+ * mediator's cross-origin handshake, which a test harness cannot perform.
+ * When a Playwright spec sets `window.__WAS_REACT_E2E_CHAPI__ = true` (via
+ * addInitScript), requests are queued on `window.__WAS_REACT_E2E_CHAPI_REQUESTS__`
+ * instead; the spec observes them, drives the wallet page directly (using
+ * freewallet's own `__E2E_CHAPI_GET_EVENT__` injection), and posts the wallet
+ * response into `window.__WAS_REACT_E2E_CHAPI_RESPONSES__[id]`. Responses use
+ * the CHAPI WebCredential wire shape `{ dataType, data } | null`.
+ */
+import { loadOnce, WebCredential } from 'credential-handler-polyfill';
+/** The default CHAPI mediator base; the requesting origin is appended at load. */
+export const DEFAULT_MEDIATOR_BASE = 'https://authn.io/mediator?origin=';
+function e2eBridgeActive() {
+    return (import.meta.env.MODE !== 'production' &&
+        window.__WAS_REACT_E2E_CHAPI__ === true);
+}
+let e2eRequestId = 0;
+/** Queues a request for the e2e harness and polls for its response. */
+async function e2eRoundTrip(type, body) {
+    const win = window;
+    win.__WAS_REACT_E2E_CHAPI_REQUESTS__ ??= [];
+    win.__WAS_REACT_E2E_CHAPI_RESPONSES__ ??= {};
+    const id = ++e2eRequestId;
+    win.__WAS_REACT_E2E_CHAPI_REQUESTS__.push({ id, type, body });
+    const deadline = Date.now() + 120_000;
+    while (Date.now() < deadline) {
+        if (id in win.__WAS_REACT_E2E_CHAPI_RESPONSES__) {
+            const value = win.__WAS_REACT_E2E_CHAPI_RESPONSES__[id];
+            delete win.__WAS_REACT_E2E_CHAPI_RESPONSES__[id];
+            return value ?? null;
+        }
+        await new Promise(resolve => setTimeout(resolve, 150));
+    }
+    throw new Error('E2E CHAPI bridge timed out waiting for a response.');
+}
+let polyfillLoaded = false;
+/**
+ * Loads the CHAPI polyfill once (no-op under the e2e bridge).
+ *
+ * @param [options] {object}
+ * @param [options.mediatorBase] {string}   the mediator base URL (defaults to
+ *   `DEFAULT_MEDIATOR_BASE`)
+ * @returns {Promise<void>}
+ */
+export async function loadChapi({ mediatorBase = DEFAULT_MEDIATOR_BASE } = {}) {
+    if (polyfillLoaded || e2eBridgeActive()) {
+        return;
+    }
+    await loadOnce(mediatorBase + encodeURIComponent(window.location.origin));
+    polyfillLoaded = true;
+}
+/**
+ * Sends a VPR to the user's wallet via CHAPI `credentials.get()`. Returns the
+ * wallet's response VP, or `null` when the user cancelled/dismissed.
+ *
+ * @param options {object}
+ * @param options.vpr {IVPRDetails}
+ * @param [options.mediatorBase] {string}
+ * @returns {Promise<IVerifiablePresentation | null>}
+ */
+export async function chapiGet({ vpr, mediatorBase }) {
+    let wire;
+    if (e2eBridgeActive()) {
+        wire = await e2eRoundTrip('get', vpr);
+    }
+    else {
+        await loadChapi(mediatorBase !== undefined ? { mediatorBase } : {});
+        const result = (await navigator.credentials.get({
+            // The polyfill extends CredentialRequestOptions with the `web` member.
+            web: { VerifiablePresentation: vpr }
+        }));
+        wire = result;
+    }
+    if (!wire || wire.data === undefined || wire.data === null) {
+        return null;
+    }
+    return wire.data;
+}
+/**
+ * Offers a VP (wrapping a credential) to the wallet via CHAPI
+ * `credentials.store()`. Returns true when the wallet confirmed the store,
+ * false when the user cancelled/dismissed.
+ *
+ * @param options {object}
+ * @param options.presentation {IVerifiablePresentation}
+ * @param [options.mediatorBase] {string}
+ * @returns {Promise<boolean>}
+ */
+export async function chapiStore({ presentation, mediatorBase }) {
+    if (e2eBridgeActive()) {
+        const wire = await e2eRoundTrip('store', presentation);
+        return wire !== null && wire.data !== undefined && wire.data !== null;
+    }
+    await loadChapi(mediatorBase !== undefined ? { mediatorBase } : {});
+    const credential = new WebCredential('VerifiablePresentation', presentation);
+    const result = (await navigator.credentials.store(credential));
+    return result !== null && result !== undefined;
+}
+//# sourceMappingURL=chapi.js.map

package/dist/auth/chapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chapi.js","sourceRoot":"","sources":["../../src/auth/chapi.ts"],"names":[],"mappings":"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"}

package/dist/auth/loginFlow.d.ts

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The Login-With-Wallet orchestration:
+ *
+ * - First run (the wallet holds no app key): generate a fresh 32-byte master
+ *   seed, self-issue the credential, and BLOCK until the wallet confirms
+ *   storing it (a dismissed store would silently break cross-device recovery),
+ *   then request the storage grants.
+ * - Returning (the wallet returns the credential): recover the seed, verify
+ *   the credential's self-issue/origin/DID binding, then request grants for
+ *   the same stable controller DID.
+ *
+ * Hot restore (seed + grants already persisted locally) never reaches this
+ * module -- the caller's session restore short-circuits it.
+ */
+import type { IZcap } from '@interop/data-integrity-core';
+import type { DocumentLoader } from '../identity/documentLoader.js';
+import { type SeedCredentialConfig } from '../identity/seedCredential.js';
+import type { IdentityAgents } from '../identity/agents.js';
+import { type CheckedGrants } from './verifyResponse.js';
+import type { ParsedGrants } from '../grants.js';
+/**
+ * The cohesive configuration for a Login-With-Wallet flow. App-specific values
+ * are injected here rather than baked in; this becomes part of the library's
+ * central app config later.
+ */
+export interface LoginConfig {
+    /** This app's own web origin (the anti-phishing bind on the app key). */
+    appOrigin: string;
+    /** Human-readable app name, used in the wallet consent reason lines. */
+    appName: string;
+    /** The WAS collection ids to request read/write grants for. */
+    collections: string[];
+    /** The seed-credential type name + vocabulary namespace. */
+    credential: SeedCredentialConfig;
+    /** The JSON-LD document loader (see `createDocumentLoader`). */
+    documentLoader: DocumentLoader;
+    /**
+     * The expected WAS server URL. When set, every granted zcap must target it;
+     * grants pointing anywhere else are rejected at login.
+     */
+    wasServerUrl?: string;
+    /** The CHAPI mediator base URL (defaults to `DEFAULT_MEDIATOR_BASE`). */
+    mediatorBase?: string;
+}
+/** A user-facing progress phase, for the login page's status line. */
+export type LoginPhase = 'probing' | 'storing-key' | 'requesting-grants' | 'verifying';
+export interface LoginOutcome {
+    seed: Uint8Array;
+    identity: IdentityAgents;
+    grants: IZcap[];
+    parsed: ParsedGrants;
+    /** ISO timestamp: the earliest expiry across the grants. */
+    expires: string;
+    /** Whether this login created a brand-new app key (first run). */
+    firstRun: boolean;
+}
+/** Thrown when the user cancels/dismisses a wallet popup. */
+export declare class LoginCancelledError extends Error {
+    constructor(step: string);
+}
+/**
+ * Requests storage grants for `identity` and validates them. Shared by the
+ * login flow and the expired-access reconnect path.
+ *
+ * @param options {object}
+ * @param options.identity {IdentityAgents}
+ * @param options.config {LoginConfig}
+ * @param [options.onPhase] {Function}
+ * @returns {Promise<CheckedGrants>}
+ */
+export declare function requestGrants({ identity, config, onPhase }: {
+    identity: IdentityAgents;
+    config: LoginConfig;
+    onPhase?: (phase: LoginPhase) => void;
+}): Promise<CheckedGrants>;
+/**
+ * Runs the full Login-With-Wallet flow (first-run or returning, decided by
+ * the seed probe). Throws `LoginCancelledError` on dismissal and `Error` on
+ * verification failures; nothing is persisted here (the caller persists).
+ *
+ * @param options {object}
+ * @param options.config {LoginConfig}
+ * @param [options.onPhase] {Function}
+ * @returns {Promise<LoginOutcome>}
+ */
+export declare function loginWithWallet({ config, onPhase }: {
+    config: LoginConfig;
+    onPhase?: (phase: LoginPhase) => void;
+}): Promise<LoginOutcome>;
+//# sourceMappingURL=loginFlow.d.ts.map