@yieldfabric/wallet 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,13 @@
 # @yieldfabric/wallet
 
+**Proprietary and confidential — Copyright (c) 2026 YieldFabric Technologies Ltd,
+DIFC, UAE. All rights reserved.** Source review requires a signed Source Review
+Authorization incorporating [LICENSE.md](LICENSE.md). Review access permits
+visual inspection only. Obtain the authorization form from YieldFabric.
+The installation, build, and integration instructions below are for YieldFabric
+developers or users with a separate express license permitting those activities.
+See [NOTICE.md](NOTICE.md) for ownership and third-party notices.
+
 Reusable YieldFabric wallet for service developers — login + onboarding,
 signing (manual MQ + generic API), profile, and key management. Drop
 `<WalletProvider>` into your React app and the rest of the surface
@@ -7,24 +15,79 @@ signing (manual MQ + generic API), profile, and key management. Drop
 
 ## Install
 
-Published to the **public npm registry** — no scope `.npmrc`, no token:
+For authorized runtime use, install the versioned compiled package from npm:
 
 ```bash
-npm install @yieldfabric/wallet
+npm install --save-exact @yieldfabric/wallet@0.2.0
 ```
 
+The package is publicly downloadable from npm; neither repository access nor an
+npm token is required to install it.
+The package contains compiled JavaScript and TypeScript declarations, without
+TypeScript source or source maps. The existing license and notices still apply.
+
 Peer deps: `react ^18`, `react-dom ^18` (and optionally `@stripe/stripe-js` for
 the Stripe-backed KYC provider). All other runtime deps (`@avatune/*`,
 `@averer/averer-websdk`, `@heroicons/react`, `js-sha3`, `zod`) install
 automatically from the public npm registry. The SDK bundles a Tailwind-styled
 UI; consumers must add it to their Tailwind content glob (see below).
 
+## Consumer bundler setup
+
+The wallet exposes the built-in provider registry from its root entry. Bundlers
+resolve those provider imports even when the application does not enable every
+provider. For the complete entry, install its provider peers alongside React 18:
+
+```bash
+npm install @dynamic-labs/ethereum@^4 @dynamic-labs/sdk-react-core@^4 @stripe/stripe-js@^9.6 @sumsub/websdk-react@^2.6
+```
+
+The SDK pins `framer-motion@12.10.5`. Its upstream dependency ranges also admit
+newer incompatible Motion internals. Reuse Qord's tested pins in the **consumer**
+`package.json` (npm does not apply dependency packages' own overrides):
+
+```json
+{
+  "overrides": {
+    "motion-dom": "12.10.5",
+    "motion-utils": "12.9.4"
+  }
+}
+```
+
+The currently used `@averer/averer-websdk@2.1.3` package exports
+`dist/averer-websdk.es`, but ships `dist/averer-websdk.es.js`. Until that upstream
+package fixes its export, add an alias in the consumer's bundler configuration.
+For an ESM Vite configuration:
+
+```js
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const require = createRequire(import.meta.url);
+const avererEntry = join(
+  dirname(require.resolve('@averer/averer-websdk/package.json')),
+  'dist/averer-websdk.es.js',
+);
+// Merge into the existing Vite configuration:
+// resolve: { alias: [{ find: /^@averer\/averer-websdk$/, replacement: avererEntry }] }
+```
+
+Webpack/CRA applications can use the same `avererEntry` as the exact-match alias
+`'@averer/averer-websdk$'`. This resolves the installed npm artifact; it needs no
+YieldFabric source checkout. Keep the Tailwind content paths below pointing at
+the installed `dist` files.
+
 ## Quick start
 
 ```tsx
 // app/layout.tsx (Next.js App Router)
 'use client';
-import { WalletProvider, SignatureWorkflow } from '@yieldfabric/wallet';
+import {
+  CreditExhaustedHost,
+  SignatureWorkflow,
+  WalletCenter,
+  WalletProvider,
+} from '@yieldfabric/wallet';
 import { useRouter } from 'next/navigation';
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -42,14 +105,17 @@ export default function RootLayout({ children }: { children: React.ReactNode })
           }}
         >
           {children}
-          {/* Zero-config global mount — wires the wallet's signature
-              queue, drawer, toast notifier, and (optionally) the
-              Signature Center launcher. This is the component every
-              host wants at the root; <SignatureDrawer /> by itself is
+          {/* Signing and Wallet Center are intentionally separate:
+              SignatureWorkflow owns queue/toast/signer state;
+              WalletCenter owns the configurable wallet shell.
+              <SignatureDrawer /> by itself is
               a *controlled inner* that needs `message` / `onClose` /
               `userId` props and is rendered by <SignatureWorkflow>
               for each pending message. */}
           <SignatureWorkflow />
+          <WalletCenter />
+          {/* Required for prepaid plan/top-up return reconciliation. */}
+          <CreditExhaustedHost />
         </WalletProvider>
       </body>
     </html>
@@ -57,6 +123,56 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+### Configuring Wallet Center
+
+The SDK owns the shell and responsive behavior; the consuming app supplies an
+ordered module registry. Built-ins, app routes, app panels, and one searchable
+directory compose without special-case props:
+
+```tsx
+import {
+  WalletCenter,
+  WalletCenterTrigger,
+  defineWalletDirectory,
+  defineWalletPanel,
+  defineWalletRoute,
+  walletCenter,
+} from '@yieldfabric/wallet';
+
+const modules = [
+  walletCenter.transactions(),
+  walletCenter.profile(),
+  walletCenter.keys(),
+  walletCenter.groups(),
+  defineWalletPanel({
+    kind: 'panel', id: 'accounts', label: 'Accounts', icon: WalletIcon,
+    render: ({ close }) => <Accounts onDone={close} />,
+  }),
+  defineWalletRoute({
+    kind: 'route', id: 'billing', label: 'Billing', icon: CardIcon,
+    href: '/billing',
+  }),
+  walletCenter.history(),
+  defineWalletDirectory({
+    kind: 'directory', id: 'app', label: 'Explore', icon: GridIcon,
+    groups: appNavigationGroups,
+  }),
+];
+
+<WalletCenterTrigger />
+<WalletCenter config={{ modules, actors, identity }} />
+```
+
+Array order is display order. Route selection closes before using the host's
+`onNavigate`; panel renderers receive `{ close, back, navigate }`; directory
+groups may be mobile- or desktop-only. `useWalletCenter()` is the headless
+open/close API for avatar buttons and other custom triggers. It also lets a
+frame *host* the center: `setHost(element)` makes `<WalletCenter>` render
+inside that element as a page of the host's own frame (no overlay, no close
+control — the frame's own navigation is the way out) instead of as a drawer
+over the app; `setHost(null)` on unmount hands it back. A phone frame with a
+Wallet tab is the intended host.
+
 ```tsx
 // app/login/page.tsx
 'use client';
@@ -78,7 +194,10 @@ build time (see [`src/core/config.ts`](./src/core/config.ts)):
 |--|--|--|
 | `REACT_APP_AUTH_SERVICE_URL` | `http://localhost:3000` | auth REST |
 | `REACT_APP_PAYMENTS_SERVICE_URL` | `http://localhost:3002` | payments + WebSocket |
-| `REACT_APP_API_URL` | `http://localhost:3002` | shared API base (WS derivation) |
+| `REACT_APP_PAYMENTS_URLS` | — | JSON map of chain id to payments base URL |
+| `REACT_APP_TEST_CHAIN_IDS` | — | comma-separated chains displayed as Test mode |
+| `REACT_APP_ENABLED_PAYMENT_CHAIN_IDS` | — | comma-separated chains currently open to user switching |
+| `REACT_APP_API_URL` | `http://localhost:3002` | legacy single-instance WebSocket base |
 | `REACT_APP_CORE_SERVICE_URL` | `http://localhost:3002` | core service URL |
 | `REACT_APP_CHAIN_ID` | `31337` | default chain id |
 
@@ -88,14 +207,82 @@ How to expose them to the browser depends on your bundler:
 - **Vite**: define them with `define: { 'process.env.REACT_APP_*': ... }` in `vite.config.ts`, or fork `core/config.ts` to read `import.meta.env.VITE_*`.
 - **Next.js**: prefix with `NEXT_PUBLIC_` in `.env.local` AND map them in `next.config.js`'s `env` block so `process.env.REACT_APP_*` resolves in client bundles.
 
-Future work: a follow-up will move URL resolution onto the
-`WalletRuntimeConfig` so consumers can pass URLs at mount time and
-not rely on env-var plumbing. See the comment at the top of
-`core/config.ts`.
+Dual-instance deployments can configure the same values at runtime instead
+of baking CRA variables into the bundle. The active JWT's
+`default_chain_id` selects the URL; `enabledChainIds` can keep a published
+mainnet topology disabled until its contracts are deployed:
+
+```tsx
+<WalletProvider
+  config={{
+    paymentsUrls: {
+      '151': 'https://pay.live.yieldfabric.com',
+      '153': 'https://pay.test.yieldfabric.com',
+    },
+    testChainIds: ['153'],
+    enabledChainIds: ['153'], // add '151' when mainnet is ready
+  }}
+>
+  {children}
+</WalletProvider>
+```
+
+Payment mutations, settlement polling, SSE and WebSockets must all resolve
+their base URL at request/connection time. Decoding the JWT in the browser is
+only a routing hint; the selected payments instance still validates the
+signature and enforces chain affinity.
 
 The full public surface — providers, hooks, UI components, core REST/crypto
 services, types — is enumerated in [`src/index.ts`](./src/index.ts).
 
+### Prepaid plan onboarding and card Checkout
+
+`<OnboardingWizard>` uses a two-stage commercial flow for direct YieldFabric
+signups. At `/onboarding`, the unauthenticated public catalog discloses the
+exact monthly renewal and cycle credit before the user chooses an auth method.
+That choice is intent only: no Stripe Customer is created and no card is
+collected. Once authentication succeeds, the SDK best-effort persists the
+choice to `/auth/users/me/onboarding-plan-intent` so refresh/resume works.
+
+After email, key, identity, and profile gates, `/onboarding/plan` resolves the
+intent against the current catalog and repeats the terms for final
+confirmation. Personal plans then redirect to Stripe-hosted, card-only
+Checkout. A required prepaid cohort cannot defer this final step. Platform-
+tagged end users skip the self-pay flow. To offer group plans, inject
+`onSelectPlatform(planId)` and have the host create its billing group,
+subscribe that exact group SKU, then configure sponsorship:
+
+```tsx
+<OnboardingWizard
+  initialPathname={pathname}
+  onSelectPlatform={(planId) => openPlatformSetup({ planId })}
+/>
+<CreditExhaustedHost />
+```
+
+Mount exactly one `<CreditExhaustedHost />` inside `<WalletProvider>` on every
+authenticated layout, including the route used as Checkout's success return.
+The host reads the server-appended Checkout Session id, polls the authenticated
+durable status with a bounded retry schedule, refreshes the exact personal or
+group payer, and re-mints tokens only after `applied: true`. It also clears
+terminal or inconsistent markers and tells the user when a purchase failed,
+was reversed/refunded, or still needs later confirmation. Without this host, a
+successful Stripe redirect cannot heal a gated browser session.
+
+Onboarding plan Checkout returns to `/onboarding/plan`, not directly to the
+billing page or home. The wizard advances to Welcome only after the exact
+Checkout Session is durably `applied` and the refreshed billing summary holds
+that plan.
+
+Use `buildCreditCheckoutReturnUrls()` when calling the lower-level
+`billingService.createCreditCheckout()` or `createTopupCheckout()` APIs. The
+success and cancel URLs must be same-origin; the success marker must encode the
+exact purchase kind and payer. Pass a canonical group UUID both to the URL
+builder and the Checkout method for a group purchase—never infer a group from
+the active delegation. Preserve the success query string through host routing
+so the return host can verify it. A complete unresolved return marker blocks a
+second Checkout until it becomes terminal or is checked again after reload.
+
 ## Login surface API
 
 The login screen is built from three independently-mountable pieces:
@@ -141,7 +328,7 @@ Three drop-in components, ordered most opinionated → least:
 
 | Component | Use when |
 |---|---|
-| `<IncomingPaymentsLauncher />` | You want a nav-chip with a badge count. Click opens an internal drawer with the full inbox. Mirrors `<SignatureCenterLauncher>` in shape. |
+| `<IncomingPaymentsLauncher />` | You want a nav-chip with a badge count. Click opens an internal drawer with the full inbox. Mirrors `<WalletCenterTrigger>` in shape. |
 | `<IncomingPaymentsCenter />` | You want a dedicated `/payments/inbox`-style page. Adds a header, refresh button, and summary tiles on top of the inbox. |
 | `<IncomingPaymentsInbox />` | You want just the card list — embed in your own chrome (drawer, dashboard card, sidebar). |
 | `useIncomingPayments()` | You want full UI control. Returns `{ items, groups, accept, acceptState, loading, error, refetch, activeEntityId, … }`. |
@@ -186,13 +373,131 @@ scopes every query and mutation to the delegated group. No prop
 threading required. The resolution order for the active entity is:
 
 1. Explicit `entityId` prop on the hook / component (if passed).
-2. `localStorage.delegation_group_id` — set by `<AppAuthProvider>` when
+2. `localStorage.delegation_group_id` — maintained by `<WalletProvider>` when
    delegation is active.
 3. `useAuth().user.id` — the authenticated user's own entity.
 
 Hosts that maintain their own actingAs model can pass `entityId`
 explicitly to override the auto-detection.
 
+For a confirmed ownership edge `Group A → Group B`, the Wallet Center also
+supports one ownership-derived hop. Start in the direct A session, then call:
+
+```ts
+const {
+  delegationSession,
+  assumeOwnedGroup,
+  returnToParent,
+} = useAuthContext();
+
+// Select one active ECDSA USER key owned by the human operator. A group key
+// is never eligible. Custodial keys execute through Automatic; external keys
+// use the Manual signature drawer.
+const userKeys = await keysService.getUserKeyPairs(currentUser.id);
+const signer = userKeys.find(
+  (key) => ownedGroupUserSignerCustody(key, currentUser.id) !== null,
+);
+if (!signer) throw new Error('No eligible personal signing key');
+
+// Mints a non-refreshable acting-as-B child and preserves direct A locally.
+await assumeOwnedGroup(groupB, signer.id);
+
+// Restores A only while its preserved access token is still live.
+returnToParent();
+```
+
+`KeyPair.account_signer_custody` is a non-secret, server-authoritative field:
+`custodial` routes the selected human key through Automatic execution,
+`external` routes it through the Manual wallet drawer, and `null` means the key
+is not eligible for the account ECDSA65 signature profile. The SDK fails closed
+when the field is missing and never infers sealed-key availability from
+`provider_type`, `key_type`, or metadata.
+
+`delegationSession` is a discriminated `direct | owned` lineage record. An
+owned child stores the exact immutable `membershipEdge`, the selected
+`signerKeyId`/address/custody, and `You → A → B` path. It rejects the removed
+`authority_key_id` model. Owned children are capped at 15 minutes, cannot be
+nested again, and never send `X-Refresh-Token`. The SDK automatically returns
+to a still-live A when B expires; otherwise it clears delegation state.
+
+In the concrete **Head Co → Subsidiary** UX:
+
+1. A Subsidiary Owner selects **Act as Subsidiary**, opens Subsidiary,
+   enters the Head Co group UUID under **Owning groups**, and reserves the
+   relationship.
+2. A Head Co Owner selects **Act as Head Co**, enters the
+   Subsidiary group UUID under **Relationship setup**, and advances the
+   immutable NFT mint with their ordinary USER key.
+3. After that operation settles, the Subsidiary Owner returns to
+   **Act as Subsidiary** and advances the same relationship again. This adds
+   the Head Co-owned NFT as a Subsidiary member; repeat after settlement until
+   the row is `active`.
+4. The Head Co operator selects **Act as Head Co**. Wallet Center now lists
+   Subsidiary under **Owned group accounts** and asks which personal key will
+   authorize the child. A custodial USER key selects Automatic; an external
+   USER key selects Manual.
+5. **Operate as Subsidiary** installs the child and displays
+   `You → Head Co → Subsidiary`.
+6. **Return to Head Co** restores the preserved direct parent; **Act as self**
+   clears the complete delegation lineage.
+
+“Head Co operator” in the relationship ceremony means a live Head Co Owner,
+not every Head Co member/admin and not the platform `UserRole::Operator` by
+name. The narrowly defined staff fallback requires `ManageGroupOwners`.
+Ordinary consumer Owners do not need that global permission. Head Co's members
+do not become Subsidiary members. The on-chain authority is the NFT edge,
+while each transaction remains attributable to the selected human EOA;
+neither Head Co nor Subsidiary needs a YieldFabric-custodied group signing key.
+
+Headless clients can discover B with
+`groupsService.getOwnedGroups(groupAId, directAToken)` and perform the strict
+exchange with `delegationService.assumeOwnedGroup(request, directAToken)`.
+`request.signer_key_id` is mandatory and must name the operator's active USER
+key. Relationship lifecycle calls are deliberately separate from raw owner
+management:
+
+```ts
+await groupsService.establishGroupOwner(childBId, parentAId, chainId, userBToken);
+await groupsService.establishGroupOwner(childBId, parentAId, chainId, userAToken);
+await groupsService.establishGroupOwner(childBId, parentAId, chainId, userBToken);
+const status = await groupsService.getGroupOwners(childBId, chainId, userBToken);
+```
+
+Those calls form an idempotent, multi-authority saga: B reserves, A mints, and
+B adds the credential. POST/DELETE deliberately take the human's personal JWT;
+the explicit parent/child IDs identify the stage, while any resulting MQ
+message is still owned by the relevant group. Never substitute `add-owner`, a
+group key, or a platform-held key for this flow.
+
+Consumer apps should reuse the SDK panel instead of rebuilding the stage
+machine or exposing the legacy raw-owner/group-key form:
+
+```tsx
+<GroupOwnershipPanel
+  childGroup={subsidiary}
+  chainId={activeChainId}
+  accountReady={subsidiaryAccount.status === 'ready'}
+  currentRole={subsidiary.role}
+  activeDirectGroupId={delegationSession?.kind === 'direct'
+    ? delegationSession.currentGroupId
+    : null}
+  availableParentGroups={groups}
+  onChanged={() => refreshGroups()}
+/>
+```
+
+The panel is fail-closed and stage-aware. Only a live child `owner` sees
+mutations; `admin` is insufficient. It reserves and advances child membership
+with POST, reconciles revocation with DELETE, disables setup until the child's
+chain account is ready, and labels any parent groups the host already knows.
+The parent mint stage remains in the direct parent context's
+**Relationship setup** card because an A-only operator is intentionally unable
+to list B's private relationship state.
+
+The canonical business model, setup calls, exact JWT claims, lifetime rules,
+revocation behaviour, and troubleshooting are documented in
+[Group account ownership: Head Co → Subsidiary](../yieldfabric-auth/docs/api/guides/group-account-ownership.md).
+
 #### Signature requirement
 
 Accepting a payment or obligation enqueues an on-chain transaction
@@ -200,8 +505,9 @@ through the MQ. When the user is in **Manual** signature mode the
 SDK's signature drawer prompts them to sign before the executor
 fires. Consumers using this inbox **must mount
 `<SignatureWorkflow />`** once at the app root — that's the zero-prop
-component that wires the queue + drawer + toast + Signature Center
-launcher together. `<SignatureDrawer />` by itself is a controlled
+component that wires the queue + drawer + toast together. Mount
+`<WalletCenter />` separately when the app exposes the wallet shell.
+`<SignatureDrawer />` by itself is a controlled
 inner that takes `message` / `onClose` / `userId` props; you don't
 mount it directly.
 
@@ -607,7 +913,7 @@ Import graph: `ui → react → providers → core`. Forbid backward edges.
 ## Build
 
 ```bash
-npm install
+npm ci --ignore-scripts
 npm run build      # one-shot — emits dist/index.{js,cjs,d.ts}
 npm run dev        # watch mode — recompiles on save
 npm run typecheck  # tsc --noEmit
@@ -623,9 +929,9 @@ npm run clean      # rm -rf dist
 Both bundles are prepended with `"use client";` so Next.js App Router
 treats the SDK as client-side by default (the surface is hook + DOM-heavy).
 
-Externals: `react`, `react-dom`, and the runtime deps (`@averer/averer-websdk`,
-`@heroicons/react`, `js-sha3`, `zod`) are NOT bundled — consumers install
-them via the `dependencies` / `peerDependencies` declarations.
+React peers and runtime dependencies declared in `package.json` stay external
+to both bundles. Consumers install them through the `dependencies` /
+`peerDependencies` declarations.
 
 ## Consuming from another monorepo package
 
@@ -658,23 +964,43 @@ If you're iterating on the SDK while running the consumer, leave
 `npm run dev` running in the SDK directory; the consumer's bundler will
 pick up changes on the next reload.
 
-## Publishing
+## Controlled distribution
 
-Ships to the **public npm registry** as a public scoped package
-(`publishConfig.access: public`). Publishing `@yieldfabric/*` requires the
-`yieldfabric` scope on npm — i.e. an npm org (or user) named `yieldfabric`.
-Authenticate once with `npm login`, then:
+Publication targets the npm registry using the existing `prepublishOnly` build
+hook. `publishConfig.access: public` publishes the compiled artifact publicly.
+The source repository retains its separate Git hosting access controls.
+An authorized release requires an unused version and npm publish rights.
+
+For YieldFabric's authorized preparation of a runtime artifact:
 
 ```bash
-# bump "version" first — re-publishing an existing version is rejected
-npm publish             # prepublishOnly runs clean && build automatically
+npm run build
+npm pack --dry-run --ignore-scripts
 ```
 
-`prepublishOnly` runs `clean && build`, so a stale `dist/` can't leak into the
-tarball. The published tarball ships **`dist/` + `README.md` only** — no `src/`
-and no source maps, so the TypeScript source stays closed (only compiled
-output ships). Verify with `npm pack --dry-run`.
+The package allowlist contains only `dist/index.js`, `dist/index.cjs`,
+`dist/index.d.ts`, `dist/index.d.cts`, `README.md`, `LICENSE.md`, and `NOTICE.md`
+(npm also includes `package.json`). Source and declaration maps are disabled.
+Built JavaScript and declarations still disclose implementation information;
+they require an appropriate license and delivery decision.
+
+Customer source review follows the source repository's `SOURCE_ACCESS.md` guide,
+including a signed authorization and a controlled viewer. The source-review
+agreement does not grant runtime or integration rights.
 
 ## License
 
-Proprietary. See repo root for terms.
+[YieldFabric Proprietary Source Code Review and Non-Use Agreement](LICENSE.md).
+Ownership remains with YieldFabric Technologies Ltd, subject to the
+[third-party notices](NOTICE.md). No rights are granted merely by repository
+access, possession of a package, or the technical examples in this README.
+
+### Authenticated JSON event streams
+
+`subscribeJsonEvents({ url, token, onEvent, onError })` returns an unsubscribe
+function. `url` and `token` are callbacks evaluated on every connection, so a
+reconnect uses the current token and service context. It sends an Authorization
+header, never a token query parameter. Errors reconnect with bounded backoff;
+call unsubscribe on sign-out, scope changes and component unmount. The stream
+uses fetch and therefore requires the server's CORS configuration to permit
+Authorization headers. Entity subscriptions use this helper automatically.