feat(console): wire onboarding to real /orgs + eERC onboarding + treasury

apps/console/src/app/RootGate.tsx

@@ -1,9 +1,9 @@
 /**
- * RootGate - decides between SIWE sign-in and the workspace. Real mode trusts the
- * cookie-backed /auth/me probe in the store; demo mode keeps the old local
- * onboarding flag so the seeded showcase still boots straight into the shell.
+ * RootGate - decides between SIWE sign-in, no-org onboarding, and the workspace.
+ * Real mode trusts the cookie-backed /auth/me probe in the store; demo mode keeps
+ * the old local onboarding flag so the seeded showcase still boots into the shell.
  */
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Shell } from "./Shell";
 import { Onboarding } from "./Onboarding";
 import { DesktopOnly, useIsDesktop } from "./DesktopOnly";
@@ -16,11 +16,23 @@ export function RootGate() {
   // Demo mode skips SIWE onboarding entirely and boots into the Shell (the
   // desktop-only gate below still applies — this stays a desktop product).
   const [onboarded, setOnboarded] = useState(() => DEMO_MODE || localStorage.getItem("benzo.console.onboarded") === "1");
+  const [orgOnboarding, setOrgOnboarding] = useState(false);
   function finish() {
     localStorage.setItem("benzo.console.onboarded", "1");
     setOnboarded(true);
     void refresh();
   }
+  function finishOrgOnboarding() {
+    setOrgOnboarding(false);
+    void refresh();
+  }
+  useEffect(() => {
+    if (!session) {
+      setOrgOnboarding(false);
+      return;
+    }
+    if (!session.activeOrg) setOrgOnboarding(true);
+  }, [session]);
   if (!isDesktop) return <DesktopOnly />;
   if (DEMO_MODE) return onboarded ? <Shell /> : <Onboarding onDone={finish} />;
   if (loading && !session) {
@@ -30,5 +42,6 @@ export function RootGate() {
       </div>
     );
   }
-  return session ? <Shell /> : <Onboarding onDone={() => void refresh()} />;
+  if (session && (orgOnboarding || !session.activeOrg)) return <Onboarding onDone={finishOrgOnboarding} />;
+  return session?.activeOrg ? <Shell /> : <Onboarding onDone={() => void refresh()} />;
 }

apps/console/src/demo/api.ts

@@ -8,9 +8,14 @@
  */
 import type {
   Counterparty,
+  CreateOrgResponse,
   Invoice,
+  OnboardingStatus,
+  OnboardingStatusResponse,
   PaymentOrder,
   PayrollBatch,
+  ProvisionTreasuryResponse,
+  StartOnboardingResponse,
   ViewingGrant,
 } from "@benzo/types";
 import type {
@@ -30,6 +35,7 @@ import { createDemoDb, dashboardSummary, treasuryView, usd } from "./data";
 // PURE-annotated so a normal build (DEMO_MODE folds to false → demoApi unused)
 // tree-shakes the entire demo graph away, leaving the production bundle unchanged.
 const db = /* @__PURE__ */ createDemoDb();
+let demoMockKyc: { name?: string; country?: string } | undefined;
 
 // ---- fake-chain helpers ---------------------------------------------------
 function randHex(len: number): string {
@@ -65,13 +71,46 @@ const byId = <T extends { id: string }>(arr: T[], id: string) => arr.find((x) =>
 const READ = 140;
 const PROVE = 640;
 const SETTLE = 720;
+const ONBOARDING_STEP = 520;
 
 function activeOrg() {
   const org = db.session.activeOrg;
   if (!org) throw new Error("No demo org");
   return org;
 }
 
+const ONBOARDING_STATUSES = ["pending_kyc", "kyc_approved", "allowlisted", "gas_dripped", "awaiting_registration", "complete"] as const;
+
+function setDemoOnboardingStatus(status: OnboardingStatus["status"], mockKycPayload?: { name?: string; country?: string }): OnboardingStatus {
+  const order = ONBOARDING_STATUSES.indexOf(status as (typeof ONBOARDING_STATUSES)[number]);
+  const timestamp = now();
+  const kycDone = order >= 1;
+  const allowlistDone = order >= 2;
+  const gasDone = order >= 3;
+  const registrationChecked = order >= 4;
+  const registrationDone = order >= 5;
+  db.onboardingStatus = {
+    ...db.onboardingStatus,
+    status,
+    error: status === "failed" ? db.onboardingStatus.error ?? "Onboarding failed." : null,
+    updatedAt: timestamp,
+    mockKyc: kycDone
+      ? {
+        approvedAt: timestamp,
+        payload: mockKycPayload ?? db.onboardingStatus.mockKyc?.payload ?? {},
+        provider: "demo",
+      }
+      : null,
+    steps: {
+      kyc: { completedAt: kycDone ? timestamp : null, provider: kycDone ? "demo" : null },
+      allowlist: { completedAt: allowlistDone ? timestamp : null, result: allowlistDone ? { ok: true } : null, txHash: allowlistDone ? fakeTx() : null },
+      gas: { completedAt: gasDone ? timestamp : null, result: gasDone ? { ok: true } : null, txHash: gasDone ? fakeTx() : null },
+      registration: { completedAt: registrationDone ? timestamp : null, lastCheckedAt: registrationChecked ? timestamp : null },
+    },
+  };
+  return clone(db.onboardingStatus);
+}
+
 export const demoApi = {
   // ---- session / status ---------------------------------------------------
   session: async () => (await delay(READ), clone(db.session)),
@@ -380,14 +419,54 @@ export const demoApi = {
     return clone(p);
   },
 
-  // ---- onboarding / auth (unused: demo boots straight into the Shell) -----
-  onboarding: async () => ({}),
-  saveOnboarding: async (patch: unknown) => patch as Record<string, unknown>,
-  submitKyb: async () => ({ status: "approved" as const, provider: "demo", inquiryRef: `kyb_${randHex(6)}`, checks: ["identity", "sanctions"], onChain: true, txHash: fakeTx() }),
-  kybStatus: async () => ({ status: "approved" as const, inquiryRef: `kyb_${randHex(6)}`, onChain: true }),
-  provisionTreasury: async () => ({ onChain: true, txHash: fakeTx(), mvkRoot: fakeRoot(), treasuryAddress: db.publicAddress }),
-  registerOwnerMvk: async () => ({ onChain: true, txHash: fakeTx(), mvkRoot: fakeRoot() }),
-  finishOnboarding: async () => clone(db.session),
+  // ---- onboarding / auth -------------------------------------------------
+  createOrg: async (body: { name: string; slug: string }): Promise<CreateOrgResponse> => {
+    await delay(READ);
+    const org = { id: `org_${randHex(6)}`, name: body.name, slug: body.slug, role: "owner" as const, createdAt: now() };
+    db.session.orgs = [org, ...db.session.orgs.filter((existing) => existing.id !== org.id)];
+    db.session.activeOrg = org;
+    db.session.role = "owner";
+    return { org: clone(org), role: "owner" };
+  },
+  startOnboarding: async (mockKyc?: { name?: string; country?: string }): Promise<StartOnboardingResponse> => {
+    await delay(READ);
+    demoMockKyc = mockKyc;
+    db.onboardingStatus = {
+      ...db.onboardingStatus,
+      id: `onb_${randHex(6)}`,
+      status: "pending_kyc",
+      error: null,
+      createdAt: now(),
+      updatedAt: now(),
+      mockKyc: null,
+      steps: {
+        kyc: { completedAt: null, provider: null },
+        allowlist: { completedAt: null, result: null, txHash: null },
+        gas: { completedAt: null, result: null, txHash: null },
+        registration: { completedAt: null, lastCheckedAt: null },
+      },
+    };
+    return { jobId: `job_${randHex(8)}`, onboarding: clone(db.onboardingStatus) };
+  },
+  onboardingStatus: async (): Promise<OnboardingStatusResponse> => (await delay(READ), { onboarding: clone(db.onboardingStatus) }),
+  subscribeOnboardingStatus: (onStatus: (onboarding: OnboardingStatus) => void): { close: () => void } => {
+    let closed = false;
+    const timers = ONBOARDING_STATUSES.map((status, index) => window.setTimeout(() => {
+      if (closed) return;
+      onStatus(setDemoOnboardingStatus(status, demoMockKyc));
+    }, index * ONBOARDING_STEP));
+    return {
+      close: () => {
+        closed = true;
+        timers.forEach((timer) => window.clearTimeout(timer));
+      },
+    };
+  },
+  provisionTreasury: async (_orgId: string): Promise<ProvisionTreasuryResponse> => {
+    await delay(SETTLE);
+    db.treasuryProvision = { ...db.treasuryProvision, registered: true, consented: true, registrationTxHash: fakeTx() };
+    return clone(db.treasuryProvision);
+  },
   orgs: async () => ({ orgs: clone(db.session.orgs) }),
   siweNonce: async () => ({ nonce: randHex(16) }),
   siweVerify: async () => ({ user: clone(db.session.user) }),

apps/console/src/demo/data.ts

@@ -15,8 +15,10 @@ import type {
   LedgerEntry,
   LiveStatusResponse,
   Member,
+  OnboardingStatus,
   PaymentOrder,
   PayrollBatch,
+  ProvisionTreasuryResponse,
   TreasuryView,
   ViewingGrant,
 } from "@benzo/types";
@@ -46,6 +48,8 @@ export interface DemoDb {
   integrations: Integration[];
   invites: OrgInvite[];
   ledger: LedgerEntry[];
+  onboardingStatus: OnboardingStatus;
+  treasuryProvision: ProvisionTreasuryResponse;
   /** Private (shielded) pool total, minor units — grows when "Make private" runs. */
   privateTotal: string;
   /** Public liquid USDC balance, minor units. */
@@ -64,6 +68,7 @@ const shielded = (handle: string, spend: string) => ({
 });
 
 export function createDemoDb(): DemoDb {
+  const publicAddress = "0x9Fb2c7A11e4D3f6B8a0C15e2D9f4A7c3B6e1D8a2";
   const owner: Member = {
     id: "mem_owner",
     orgId: ORG_ID,
@@ -338,6 +343,33 @@ export function createDemoDb(): DemoDb {
     { id: "vg_1", kind: "grant", title: "Grant Thornton LLP · Q2", status: "active", amountLabel: "—", at: ISO("2026-07-01T00:00:00Z") },
   ];
 
+  const onboardingStatus: OnboardingStatus = {
+    id: "onb_demo",
+    userId: owner.id,
+    address: DEMO_OWNER_ADDRESS,
+    chainEnv: "demo",
+    chainId: 43113,
+    status: "complete",
+    error: null,
+    createdAt: ISO("2026-02-03"),
+    updatedAt: ISO("2026-02-03T00:05:00Z"),
+    mockKyc: { approvedAt: ISO("2026-02-03T00:01:00Z"), payload: { name: org.name, country: org.country }, provider: "demo" },
+    steps: {
+      kyc: { completedAt: ISO("2026-02-03T00:01:00Z"), provider: "demo" },
+      allowlist: { completedAt: ISO("2026-02-03T00:02:00Z"), result: { ok: true }, txHash: fakeHash("a110") },
+      gas: { completedAt: ISO("2026-02-03T00:03:00Z"), result: { ok: true }, txHash: fakeHash("9a5") },
+      registration: { completedAt: ISO("2026-02-03T00:04:00Z"), lastCheckedAt: ISO("2026-02-03T00:04:00Z") },
+    },
+  };
+
+  const treasuryProvision: ProvisionTreasuryResponse = {
+    address: publicAddress,
+    custody: "managed",
+    registered: true,
+    consented: true,
+    registrationTxHash: fakeHash("eerc"),
+  };
+
   return {
     session,
     live: { live: true, mode: "live", missing: [] },
@@ -352,9 +384,11 @@ export function createDemoDb(): DemoDb {
     integrations,
     invites,
     ledger,
+    onboardingStatus,
+    treasuryProvision,
     privateTotal: usd(842300),
     publicUnits: usd(48250),
-    publicAddress: "0x9Fb2c7A11e4D3f6B8a0C15e2D9f4A7c3B6e1D8a2",
+    publicAddress,
     usdcIssuer: "0x5425890298aed601595a70AB815c96711a31Bc65",
     dashboardActivity,
   };

apps/console/src/lib/api.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import type { CreatePaymentRequest } from "@benzo/types";
+import type { CreatePaymentRequest, OnboardingStatus } from "@benzo/types";
 import { ACTIVE_ORG_KEY, api, apiHref } from "./api";
 
 function jsonResponse(body: unknown, status = 200): Response {
@@ -15,6 +15,27 @@ function callHeaders(call: unknown[]): Headers {
     : new Headers();
 }
 
+function onboardingStatus(status: OnboardingStatus["status"]): OnboardingStatus {
+  return {
+    id: "onb_1",
+    userId: "usr_1",
+    address: "0x1234567890abcdef1234567890abcdef12345678",
+    chainEnv: "testnet",
+    chainId: 43113,
+    status,
+    error: status === "failed" ? "failed" : null,
+    createdAt: "2026-07-10T00:00:00.000Z",
+    updatedAt: "2026-07-10T00:00:02.000Z",
+    mockKyc: null,
+    steps: {
+      kyc: { completedAt: status === "pending_kyc" ? null : "2026-07-10T00:00:01.000Z", provider: status === "pending_kyc" ? null : "mock" },
+      allowlist: { completedAt: ["allowlisted", "gas_dripped", "awaiting_registration", "complete"].includes(status) ? "2026-07-10T00:00:02.000Z" : null, result: null, txHash: null },
+      gas: { completedAt: ["gas_dripped", "awaiting_registration", "complete"].includes(status) ? "2026-07-10T00:00:03.000Z" : null, result: null, txHash: null },
+      registration: { completedAt: status === "complete" ? "2026-07-10T00:00:04.000Z" : null, lastCheckedAt: ["awaiting_registration", "complete"].includes(status) ? "2026-07-10T00:00:04.000Z" : null },
+    },
+  };
+}
+
 describe("console API idempotency", () => {
   afterEach(() => {
     localStorage.clear();
@@ -73,12 +94,11 @@ describe("console API idempotency", () => {
       amount: { amount: "10000000", assetCode: "USDC" },
     } satisfies CreatePaymentRequest;
     const actions: Array<() => Promise<unknown>> = [
-      () => api.saveOnboarding({ name: "Acme" }),
+      () => api.createOrg({ name: "Acme", slug: "acme" }),
+      () => api.startOnboarding({ name: "Acme Inc.", country: "US" }),
       () => api.siweVerify("m", "0xsig"),
       () => api.logout(),
-      () => api.submitKyb({ legalName: "Acme Inc." }),
-      () => api.provisionTreasury(),
-      () => api.finishOnboarding(),
+      () => api.provisionTreasury("org_1"),
       () => api.proveBalance("1"),
       () => api.proveTotal(),
       () => api.proveSolvency(),
@@ -129,6 +149,73 @@ describe("console API idempotency", () => {
     expect(callHeaders(fetchMock.mock.calls[1]).get("idempotency-key")).toBe(firstKey);
   });
 
+  it("uses the real org and eERC onboarding endpoints", async () => {
+    const complete = onboardingStatus("complete");
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(jsonResponse({ org: { id: "org_1", name: "Acme", slug: "acme", role: "owner", createdAt: "2026-07-10T00:00:00.000Z" }, role: "owner" }))
+      .mockResolvedValueOnce(jsonResponse({ jobId: "job_1", onboarding: onboardingStatus("pending_kyc") }, 202))
+      .mockResolvedValueOnce(jsonResponse({ onboarding: complete }))
+      .mockResolvedValueOnce(jsonResponse({ address: "0xtreasury", custody: "managed", registered: true, consented: true, registrationTxHash: "0xreg" }, 201));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(api.createOrg({ name: "Acme", slug: "acme" })).resolves.toMatchObject({ role: "owner", org: { id: "org_1" } });
+    await expect(api.startOnboarding({ name: "Acme Inc.", country: "US" })).resolves.toMatchObject({ jobId: "job_1" });
+    await expect(api.onboardingStatus()).resolves.toMatchObject({ onboarding: { status: "complete" } });
+    await expect(api.provisionTreasury("org_1")).resolves.toMatchObject({ address: "0xtreasury", custody: "managed" });
+
+    expect(fetchMock.mock.calls.map((call) => call[0])).toEqual([
+      apiHref("/orgs"),
+      apiHref("/onboarding/start"),
+      apiHref("/onboarding/status"),
+      apiHref("/orgs/org_1/treasury"),
+    ]);
+    expect(fetchMock.mock.calls[0][1]).toMatchObject({ method: "POST", body: JSON.stringify({ name: "Acme", slug: "acme" }), credentials: "include" });
+    expect(fetchMock.mock.calls[1][1]).toMatchObject({ method: "POST", body: JSON.stringify({ mockKyc: { name: "Acme Inc.", country: "US" } }), credentials: "include" });
+    expect(callHeaders(fetchMock.mock.calls[2]).get("idempotency-key")).toBeNull();
+    expect(fetchMock.mock.calls[3][1]).toMatchObject({ method: "POST", body: JSON.stringify({ consent: true }), credentials: "include" });
+  });
+
+  it("subscribes to onboarding status with credentialed EventSource", () => {
+    class FakeEventSource {
+      static instances: FakeEventSource[] = [];
+      url: string | URL;
+      init?: EventSourceInit;
+      private listeners = new Map<string, Array<(event: MessageEvent<string>) => void>>();
+
+      constructor(url: string | URL, init?: EventSourceInit) {
+        this.url = url;
+        this.init = init;
+        FakeEventSource.instances.push(this);
+      }
+
+      addEventListener(type: string, listener: EventListenerOrEventListenerObject | null) {
+        if (typeof listener !== "function") return;
+        const listeners = this.listeners.get(type) ?? [];
+        listeners.push(listener as (event: MessageEvent<string>) => void);
+        this.listeners.set(type, listeners);
+      }
+
+      close() {}
+
+      emit(type: string, data: unknown) {
+        const event = new MessageEvent(type, { data: JSON.stringify(data) });
+        for (const listener of this.listeners.get(type) ?? []) listener(event);
+      }
+    }
+    vi.stubGlobal("EventSource", FakeEventSource as unknown as typeof EventSource);
+    const seen: OnboardingStatus["status"][] = [];
+
+    const subscription = api.subscribeOnboardingStatus((status) => seen.push(status.status));
+    const source = FakeEventSource.instances[0];
+    source.emit("status", { onboarding: onboardingStatus("kyc_approved") });
+    source.emit("status", { onboarding: onboardingStatus("complete") });
+    subscription.close();
+
+    expect(source.url).toBe(apiHref("/onboarding/status/stream"));
+    expect(source.init).toMatchObject({ withCredentials: true });
+    expect(seen).toEqual(["kyc_approved", "complete"]);
+  });
+
   it("loads proof receipts through the authenticated API without mutation idempotency", async () => {
     const fetchMock = vi.fn().mockResolvedValue(jsonResponse([{ id: "prf_1", action: "payroll.policy.cap", vkId: "SPENDCAP", verified: true, createdAt: "2026-06-26T00:00:00.000Z" }]));
     vi.stubGlobal("fetch", fetchMock);