@seams/wallet 0.8.0 → 0.9.1

package/README.md

@@ -1,110 +1,131 @@
-# Seams wallet SDK
+# Seams Wallet SDK
 
-Embedded passkey wallet SDK for platforms that provision persistent wallets for
-their users. It supports NEAR and EVM-family signing through SecureConfirm
-WebAuthn, cross-origin iframe isolation, and WASM-based cryptography.
+`@seams/wallet` **0.9.1** provides browser wallet lifecycle, NEAR and EVM-family
+threshold signing, React components, and hosted wallet runtime assets.
 
-Strong fits include marketplaces, trading platforms, games, payout and
-remittance products, stablecoin accounts, rewards networks, and applications
-that sponsor or automate onchain operations. Read the
-wallet vision (`docs/vision.md`) for the complete use-case boundary.
+## Install
 
-Featuring:
-
-- **Core SDK**: Framework-agnostic JavaScript/TypeScript library
-- **React Components**: Drop-in components and hooks for React applications
-- **Hosted wallet runtime**: static wallet-service, worker, WASM, and export
-  viewer support assets for the wallet origin
-
-## Installation
-
-Install the published package:
-
-```bash
-npm install @seams/wallet
-# or
-pnpm add @seams/wallet
-# or
-yarn add @seams/wallet
+```sh
+pnpm add @seams/wallet@0.9.1
 ```
 
-### For SDK Developers
+React integrations support React 18 and 19. Import the provider and UI from
+`@seams/wallet/react` and its stylesheet from `@seams/wallet/react/styles`.
+Keep the application package, wallet-origin assets, and
+`@seams/wallet-server@0.9.1` on the matching release.
 
-**Build**:
+## Next release migration (unreleased)
 
-```bash
-# From repo root
-pnpm install
-pnpm build:wasm       # Builds Rust/WASM packages
-pnpm build:sdk        # Builds SDK dist from existing WASM outputs
-pnpm build:sdk-full   # Builds WASM packages + SDK dist
-pnpm -C packages/wallet dev       # Watch mode
-```
+The development API groups calls under `auth`, `connection`, `config`, `events`,
+`registration`, and the chain namespaces. See the
+[complete migration map](../../docs/refactor-171.md#complete-operation-migration-map).
+Use `auth.lock()` to end the session while retaining valid durable presignatures.
 
-**Test**:
+Custom email unlock uses a host-owned challenge:
 
-```bash
-pnpm test:wallet-browser               # Playwright tests
-pnpm -C packages/wallet run type-check # TypeScript validation
+```ts
+const requested = await seams.auth.requestEmailCode({
+  method: 'google',
+  idToken,
+  target: { kind: 'wallet', walletId },
+});
+if (!requested.ok) throw new Error(requested.error.message);
+const result = await seams.auth.unlockWithEmailCode({
+  challenge: requested.value,
+  code,
+});
+if (!result.ok) throw new Error(result.error.message);
 ```
 
-## Quick Start
+For an existing local email method, request with
+`{ method: 'email', walletId, email }`. The challenge supports `resend()` and
+`cancel()`. Use the replacement challenge returned by a successful resend.
+The SDK selects signers and completes pending activation internally.
+
+Release 0.9.0 contains these changes. Its wallet iframe protocol is `15.0.0`
+and rejects older protocol versions, so keep the client and the wallet-host
+assets on the matching release. The 0.8.0 release does not contain them.
 
-### React Integration
+## React quick start
 
-The easiest way to get started with React (React 18+)
+The three required values are the wallet origin, Gateway/relayer URL, and
+managed-registration publishable key. Obtain them from your project and allow
+your application's origin in that environment. Browser configuration is public.
 
 ```tsx
-import { SeamsWebProvider, useSeams } from '@seams/wallet/react';
+import {
+  HostedSeamsAuthMenu,
+  SeamsWebProvider,
+  seamsTestnetConfig,
+  type HostedAuthMenuOutcome,
+} from '@seams/wallet/react';
+import '@seams/wallet/react/styles';
+
+const config = seamsTestnetConfig({
+  walletOrigin: import.meta.env.VITE_WALLET_ORIGIN,
+  relayerUrl: import.meta.env.VITE_RELAYER_URL,
+  publishableKey: import.meta.env.VITE_SEAMS_PUBLISHABLE_KEY,
+});
 
-function App() {
+function handleOutcome(outcome: HostedAuthMenuOutcome): void {
+  console.log('Wallet authentication:', outcome);
+}
+
+export function App() {
   return (
-    <SeamsWebProvider
-      config={{
-        chains: [
-          {
-            network: 'near-testnet',
-            rpcUrl: 'https://rpc.testnet.fastnear.com',
-            explorerUrl: 'https://testnet.nearblocks.io',
-          },
-        ],
-        iframeWallet: {
-          walletOrigin: 'https://wallet.web3authn.org',
-        },
-        relayer: {
-          url: 'https://router-api.example.com',
-        },
-      }}
-    >
-      <YourApp />
+    <SeamsWebProvider config={config}>
+      <HostedSeamsAuthMenu onOutcome={handleOutcome} />
     </SeamsWebProvider>
   );
 }
+```
 
-function SignInButton() {
-  const seams = useSeams();
+`seamsTestnetConfig` selects NEAR and Tempo testnets. Use `defineSeamsConfig`
+for another chain set. EVM-family chain records require their numeric `chainId`.
+An optional `projectEnvironmentId` cross-check rejects a publishable key for a
+different environment.
 
-  const handleSignIn = async () => {
-    const result = await seams.registerPasskey();
-    console.log('Registered:', result.success);
-  };
+The hosted menu owns registration, sign-in, OTP prompts, recovery-code backup,
+and user presence. Supply `externalAuthBroker` when your application acquires
+Google identity evidence for the wallet host. Keep secret credentials and
+recovery material out of app configuration and logs.
 
-  return <button onClick={handleSignIn}>Sign In with Passkey</button>;
-}
-```
+## Signing and lifecycle
+
+`useSeams()` exposes the SDK client and authentication state. `useWallet()`
+provides `near`, `evm`, and `tempo` signers bound to the authenticated wallet.
+`near` is null until a NEAR account is ready. Check registration's pending
+branches and use `registration.awaitNearReady` before signing NEAR.
+
+The framework-neutral `SeamsWeb` client groups operations under `registration`,
+`auth`, `near`, `evm`, `tempo`, `recovery`, `devices`, and `keys`. Signing can
+use fresh authorization for one operation; `unlock` provisions a bounded
+reusable Wallet Session. An EVM-family signing or export call requires a
+`chainTarget` naming a configured chain.
 
-### Full-page wallet settings
+`keys.exportKeypair` opens a wallet-origin viewer and returns an export outcome.
+It does not return a private key to the application. `recovery.syncAccount`
+synchronizes a known wallet's account state; the hosted menu handles recovery
+codes and new-factor verification.
 
-`WalletSettingsPage` provides sidebar navigation for accounts, key export,
-recovery codes, authentication methods, device linking, linked devices, and
-transaction preferences. It uses the existing wallet operations and capability
-checks. Signed-out users see the hosted authentication menu.
+See the [compiled examples](https://wallet.seams.sh/docs/examples/) for
+registration, unlock, signing, linked devices, export, recovery, and theming.
+
+## Wallet settings
+
+`WalletSettingsPage` provides accounts, key export, recovery codes,
+authentication methods, device linking, linked devices, and transaction
+preferences. Signed-out users see the hosted authentication menu.
 
 ```tsx
-import { SeamsWebProvider, WalletSettingsPage, type SeamsConfigsInput } from '@seams/wallet/react';
+import {
+  SeamsWebProvider,
+  WalletSettingsPage,
+  type SeamsConfigsInput,
+} from '@seams/wallet/react';
 import '@seams/wallet/react/styles';
 
-function WalletSettingsApp({ config }: { config: SeamsConfigsInput }) {
+export function WalletSettingsApp({ config }: { config: SeamsConfigsInput }) {
   return (
     <SeamsWebProvider config={config}>
       <WalletSettingsPage />
@@ -113,194 +134,59 @@ function WalletSettingsApp({ config }: { config: SeamsConfigsInput }) {
 }
 ```
 
-Use the deployment's existing SDK configuration. For hosting on the wallet
-origin, keep its configured `/wallet-service` endpoint available for embedded
-wallet operations. The bare service document still requires a top-level app
-bootstrap and deployment configuration before it can serve this settings page.
-Pass `externalAuthBroker` when the deployment supports Google authentication.
-
-### Google SSO + Email OTP Wallet Auth
-
-For the standard Google SSO plus Email OTP wallet flow, the app owns Google
-Identity token acquisition and the SDK owns wallet registration, unlock,
-challenge routing, signing-session readiness, and wallet-iframe routing.
-
-```tsx
-import { HostedSeamsAuthMenu, type HostedAuthMenuOutcome } from '@seams/wallet/react';
-
-function handleOutcome(outcome: HostedAuthMenuOutcome): void {
-  console.log('Wallet authentication:', outcome);
-}
-
-function AuthMenu() {
-  return <HostedSeamsAuthMenu onOutcome={handleOutcome} />;
-}
-```
-
-Mount `HostedSeamsAuthMenu` inside a configured `SeamsWebProvider`. The wallet-origin
-iframe owns auth inputs, progress, OTP prompts, and the final passkey activation.
-Apps can provide `externalAuthBroker` to acquire provider evidence when the wallet
-host requests it. Direct SDK calls keep their wallet-origin confirmation surface.
-
-The public flow only exposes UI-safe data: wallet id, email hint, prompt copy,
-delivery status, expiry, and `resend`/`reroll`/`submit`/`cancel` methods. It
-does not expose Wallet Session operation credentials, runtime policy scope,
-recovery codes, or ECDSA bootstrap material.
-
-Low-level Email OTP methods such as `requestEmailOtpChallenge`,
-`requestEmailOtpEnrollmentChallenge`, `enrollEmailOtp`, and
-`loginWithEmailOtpEcdsaCapability` remain available for advanced custom
-integrations. Prefer `beginGoogleEmailOtpWalletAuth` for the standard Google
-SSO wallet registration and login path.
-
-In wallet-iframe mode, the same public API is used by the app origin. The wallet
-origin owns Email OTP recovery-code backup UI, acknowledgement, workers, sealed
-refresh state, and exact Wallet Session persistence. App-origin iframe responses
-carry only non-secret flow metadata and submit results.
-
-### Exact Wallet Session authorization
-
-Wallet operations are scoped to one exact wallet, authority, and authentication
-method. The authorization also binds its authorization id, quota id, authority
-digest and revocation epoch, capability subjects, and expiry. A primary
-`WalletSessionOperationCredentialV1` authenticates ordinary wallet operations.
-Hosted iframe sessions redeem an origin-bound exchange into a
-`HostedWalletSessionOperationCredentialV1` child for the same parent
-authorization.
-
-The wallet origin persists the active authorization in the exact V6 IndexedDB
-record `wallet_session_authorization_v6` through
-`WalletSessionAuthorizationRepository`. It stores the scoped wallet, authority,
-auth-method, authorization, and Wallet Session ids; quota, authority
-digest/revocation epoch, capability subjects, issue/expiry times; and the
-matching operation credential. Credential and record identities must match
-exactly. Replacing a session retires the predecessor for that exact scope while
-sibling authentication methods remain independent.
-
-## Hosted Wallet Integration
-
-Applications import the SDK as package code and configure the hosted wallet
-origin. They do not serve Seams wallet assets from the app Vite config.
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-
-export default defineConfig({
-  plugins: [react()],
-});
-```
-
-During the stabilization milestone, configure the hosted wallet through the
-existing `iframeWallet` surface:
-
-```typescript
-const config = {
-  relayer: { url: 'https://router.example.com' },
-  iframeWallet: {
-    walletOrigin: 'https://sign.seams.sh',
-    walletServicePath: '/wallet-service',
-    sdkBasePath: '/sdk',
-  },
-};
-```
+Keep the configured `/wallet-service` endpoint available. A bare service HTML
+asset needs the deployment's bootstrap and configuration before it can serve a
+complete settings application.
 
-The Seams-operated wallet origin serves `/wallet-service`, `/sdk/*`, and
-`/sdk/workers/*` from `@seams/wallet/dist/public`. Private-key export uses a
-wallet-origin inline viewer document that loads its support files from `/sdk/*`.
-App origins should not route those paths.
+## Hosted boundary and regional homes
 
-The SDK-created wallet iframe carries the default WebAuthn delegation through
-its `allow` attribute. App-platform `Permissions-Policy` should only be added
-if hosted-origin browser smokes prove a supported browser requires it.
+The dedicated wallet origin serves `/wallet-service` and `/sdk/*`, including
+workers, WASM, and the export viewer. The SDK iframe delegates WebAuthn
+permissions to that origin. Credential creation and assertions execute there;
+there is no application-origin credential bridge.
 
-## Stable API Surfaces
+Regional hosted deployments assign each wallet a home at registration.
+Wallets in one project can have different homes, while all devices of one
+wallet use the same home. Travel does not change it. The owner can move a wallet
+to another region with the wallet region setting. Automatic region relocation is
+a future capability.
 
-Use `@seams/wallet` for the main surface (for example `SeamsWeb` and core types).
+When upgrading from 0.8.0, update application, wallet assets, and backend
+together. An older open client can receive an HTTP 409 upgrade-required message;
+show it and reload the current assets. See the
+[upgrade guide](https://wallet.seams.sh/docs/deploy-and-operate/hosted-integration#upgrading-to-0-9-0).
 
-Threshold APIs are stable under an explicit subpath:
+## Public entrypoints
 
-```ts
-import { keygenEcdsa } from '@seams/wallet/threshold';
-```
-
-## Configuration Options
-
-```typescript
-interface SeamsWebConfig {
-  // Chain settings
-  chains: Array<{
-    network:
-      | 'near-mainnet'
-      | 'near-testnet'
-      | 'tempo-mainnet'
-      | 'tempo-testnet'
-      | 'arc-mainnet'
-      | 'arc-testnet';
-    rpcUrl: string;
-    explorerUrl: string;
-    chainId?: number; // EVM (arc-*) chains only
-  }>;
-  relayerAccount: string; // Parent account used for new subaccounts
-
-  // Wallet iframe settings (recommended)
-  iframeWallet?: {
-    walletOrigin: string; // e.g., 'https://wallet.web3authn.org'
-    walletServicePath?: string; // Default: '/wallet-service'
-    sdkBasePath?: string; // Default: '/sdk'
-    walletHostVariant?: 'runtime' | 'full' | 'near' | 'ecdsa'; // Default: 'runtime'
-    rpIdOverride?: string; // Optional: Credential scope override
-  };
-
-  // Optional Router API server (for account creation & Shamir 3-pass)
-  relayer?: {
-    url: string;
-  };
-}
-```
+- `@seams/wallet` — browser client, config builders, public results and values.
+- `@seams/wallet/react` — providers, hooks, components, transaction review, and themes.
+- `@seams/wallet/external-evm` — browser EVM extension connector.
+- `@seams/wallet/advanced` — exact identity builders, RPC and encoding helpers.
+- `@seams/wallet/threshold` — session-policy helpers, PRF salts, and intent digests.
+- `@seams/wallet/runtime` — explicit platform ports and custom signing runtime.
 
-## Wallet Iframe Architecture
+Use the documented package exports. Agent-lane issuance and VoiceID
+authentication are planned and have no public 0.9.0 API.
 
-The SDK isolates all sensitive operations in a cross-origin iframe such as
-`wallet.web3authn.org`. Your app communicates via secure MessageChannel, and app
-code cannot access keys directly.
+## Develop from source
 
-### Configuration
+From the repository root:
 
-**Recommended** (dedicated wallet origin):
-
-```tsx
-iframeWallet: {
-  walletOrigin: 'https://wallet.web3authn.org',
-  walletServicePath: '/wallet-service',
-  walletHostVariant: 'runtime',
-}
-```
-
-## Project Structure
-
-```text
-repo/
-├── apps/
-│   ├── web-client/               # Browser app/site
-│   ├── web-server/               # Deployable Router API server app
-│   └── docs/                     # Documentation app
-├── packages/
-│   ├── wallet/                  # Browser SDK package and build output
-│   ├── wallet-server/            # Server library source
-│   └── shared-ts/                # Shared TypeScript utils/types
-├── crates/
-│   └── signer-core/              # Shared signer core primitives
-├── wasm/                         # Rust WASM packages
-└── tests/                        # Playwright + unit tests
+```sh
+pnpm install
+pnpm build
+pnpm -C packages/wallet dev
+pnpm test:wallet-browser
+pnpm -C packages/wallet type-check
 ```
 
-## License
+With the required WASM and server artifacts already built, rebuild only the SDK
+with `pnpm -C packages/wallet build:sdk`. See the repository README for the full
+local stack and Console Lite example.
 
-MIT License - see [LICENSE](../../LICENSE.md) for details.
+## License and support
 
-## Support
+Apache-2.0. See the package's `LICENSE.md` and `THIRD_PARTY_NOTICES.md`.
 
-- **Documentation**: [../../apps/docs/](../../apps/docs/)
-- **Issues**: [GitHub Issues](https://github.com/web3-authn/sdk/issues)
+- [Documentation](https://wallet.seams.sh/docs/)
+- [Repository and issues](https://github.com/seams-tech/seams-wallet)

package/THIRD_PARTY_NOTICES.md

@@ -5,7 +5,7 @@ distributed Seams Wallet SDK, server runtime, Wasm, strict Workers, and CLI.
 Dependency license expressions come from their package metadata. Packaged
 license and notice wording is reproduced below with normalized whitespace.
 
-Inventory: 515 dependency records (109 npm, 406 Cargo).
+Inventory: 517 dependency records (109 npm, 408 Cargo).
 
 ## Dependency inventory
 
@@ -28,6 +28,7 @@ Inventory: 515 dependency records (109 npm, 406 Cargo).
 | cargo | base64ct | 1.8.3 | Apache-2.0 OR MIT | RustCrypto Developers |
 | cargo | bitflags | 2.13.0 | MIT OR Apache-2.0 | The Rust Project Developers |
 | cargo | bitflags | 2.13.1 | MIT OR Apache-2.0 | The Rust Project Developers |
+| cargo | bitflags | 2.13.2 | MIT OR Apache-2.0 | The Rust Project Developers |
 | cargo | block-buffer | 0.10.4 | MIT OR Apache-2.0 | RustCrypto Developers |
 | cargo | block-buffer | 0.12.1 | MIT OR Apache-2.0 | RustCrypto Developers |
 | cargo | borsh-derive | 1.5.7 | Apache-2.0 | Near Inc <hello@nearprotocol.com> |
@@ -226,6 +227,7 @@ Inventory: 515 dependency records (109 npm, 406 Cargo).
 | cargo | pkcs8 | 0.10.2 | Apache-2.0 OR MIT | RustCrypto Developers |
 | cargo | pkcs8 | 0.11.0 | Apache-2.0 OR MIT | RustCrypto Developers |
 | cargo | pkg-config | 0.3.33 | MIT OR Apache-2.0 | Alex Crichton <alex@alexcrichton.com> |
+| cargo | pkg-config | 0.3.34 | MIT OR Apache-2.0 | Alex Crichton <alex@alexcrichton.com> |
 | cargo | poly1305 | 0.8.0 | Apache-2.0 OR MIT | RustCrypto Developers |
 | cargo | polyval | 0.6.2 | Apache-2.0 OR MIT | RustCrypto Developers |
 | cargo | postcard | 1.1.3 | MIT OR Apache-2.0 | James Munns <james@onevariable.com> |
@@ -4126,6 +4128,7 @@ Applies to:
 - cargo:js-sys@0.3.90
 - cargo:openssl-probe@0.2.1
 - cargo:pkg-config@0.3.33
+- cargo:pkg-config@0.3.34
 - cargo:wasm-bindgen-backend@0.2.100
 - cargo:wasm-bindgen-futures@0.4.73
 - cargo:wasm-bindgen-macro-support@0.2.100
@@ -6900,6 +6903,7 @@ Applies to:
 
 - cargo:bitflags@2.13.0
 - cargo:bitflags@2.13.1
+- cargo:bitflags@2.13.2
 - cargo:log@0.4.27
 - cargo:log@0.4.33
 - cargo:log@0.4.34
@@ -10359,6 +10363,7 @@ Applies to:
 - cargo:base64@0.23.1
 - cargo:bitflags@2.13.0
 - cargo:bitflags@2.13.1
+- cargo:bitflags@2.13.2
 - cargo:bs58@0.5.1
 - cargo:bumpalo@3.18.1
 - cargo:bumpalo@3.19.1
@@ -10420,6 +10425,7 @@ Applies to:
 - cargo:openssl-probe@0.2.1
 - cargo:percent-encoding@2.3.2
 - cargo:pkg-config@0.3.33
+- cargo:pkg-config@0.3.34
 - cargo:postcard@1.1.3
 - cargo:rustc_version@0.4.1
 - cargo:rustls-native-certs@0.8.4

package/dist/.build-inputs.sha256

@@ -1 +1 @@
-188f00b6c5d19248c0239a676e372a52d0a37751a2a56fdcf3ebd6ddb937f21c
+ae160ae14f2523702c4fef83cd460099dc8ebef71ae5079e056f38d97cc5d19d