@witnium-tech/witniumchain 0.3.0 → 0.6.0

package/FRONTEND-INTEGRATION.md

@@ -0,0 +1,265 @@
+# WitniumChain — Frontend Integration Guide
+
+Audience: the team building the WitniumChain dashboard frontend. This is the
+contract between the backend (accounts + chain-api) and your UI. It covers the
+end-to-end user flows, where keys live, the recovery-file format, and the
+known sharp edges discovered during backend validation.
+
+The SDK that backs all of this is **`@witnium-tech/witniumchain`** (npm). Every
+flow below has a typed method on it.
+
+---
+
+## 1. The custody model — read this first
+
+Two ed25519 keys are generated **client-side** at signup and never leave the
+user's device in plaintext:
+
+| Key | Controls | Used for |
+|---|---|---|
+| **Owner key** | The contract's signing-key set (add/revoke), pause/unpause | Authorizing changes. Never signs witnesses. |
+| **Signing key** | — | Signing witnesses day-to-day |
+
+Witnium only ever receives the **public** halves. The backend enforces
+`ownerPublicKey !== initialSigningPublicKey`.
+
+**Your job on the frontend:** generate these keys, store them encrypted, let
+the user export/import them, and produce owner-key signatures when the backend
+asks for them (the MCP-CUSTODY ceremony, §6). You are the custody surface. If
+you lose the keys with no recovery file, the account's contract is
+unrecoverable — there is no server-side escrow by design.
+
+### Recommended storage (production)
+
+The throwaway test frontend stored keys as plain hex in `localStorage`. **Do
+not ship that.** The intended production design:
+
+- Wrap the two private keys with a key derived from a **WebAuthn PRF** assertion
+  (passkey). The user authenticates with their passkey to decrypt.
+- Issue **recovery codes** at signup (one-time display) as the fallback when no
+  passkey is available (new device, lost authenticator).
+- Persist the wrapped blob in IndexedDB.
+
+The backend does not need to know how you wrap the keys — it only sees public
+keys + signatures. But see §7 for the **same-origin requirement**, which is a
+hard constraint on where this storage lives.
+
+---
+
+## 2. Install
+
+```bash
+npm install @witnium-tech/witniumchain
+```
+
+```ts
+import { WitniumchainClient } from '@witnium-tech/witniumchain';
+
+const client = new WitniumchainClient({
+  baseUrl: 'https://auth.witniumchain.com',       // accounts
+  chainBaseUrl: 'https://api.witniumchain.com',   // chain-api (read methods)
+});
+```
+
+Generate keys with any ed25519 lib. The backend + SDK speak 64-hex-char
+public keys (no `0x`). Example with `@noble/ed25519`:
+
+```ts
+import * as ed from '@noble/ed25519';
+const priv = ed.utils.randomPrivateKey();
+const pub = await ed.getPublicKeyAsync(priv);   // hex-encode both halves
+```
+
+---
+
+## 3. Signup → org → contract (one call)
+
+`createOrg` is the self-serve path. It creates the admin user, the
+organization, the org-admin membership, **and deploys the contract** with the
+client-generated keys — all in one request.
+
+```ts
+const result = await client.createOrg({
+  orgName: 'Acme Inc.',
+  adminEmail: 'you@example.com',
+  adminPassword: '≥12 chars',
+  ownerPublicKey: ownerPubHex,
+  initialSigningPublicKey: signingPubHex,
+});
+// → { orgId, userId, contractAddress, contractVersion, emailVerifyToken }
+```
+
+Persist the two private keys + `contractAddress` locally (wrapped, per §1) and
+prompt a recovery-file download (§5) before doing anything else.
+
+`emailVerifyToken` is also emailed to the admin. It's echoed in the response so
+you can render a "click to verify" link inline if you prefer. **The email is
+the login gate, not the contract-deploy gate** — the contract is already live
+when this returns.
+
+---
+
+## 4. Auth flows
+
+### Email verify
+
+```ts
+await client.verifyEmail(token);   // GET /v1/auth/verify?token=…
+```
+
+> ⚠️ This is a **GET**, not POST. (Caught in testing — easy to get wrong.)
+
+### Password login
+
+```ts
+await client.login({ email, password });   // sets wac_session cookie
+```
+
+In a browser the `wac_session` cookie is set automatically (the SDK uses
+`credentials: 'include'`). Server-side callers must capture + replay the cookie.
+
+### Magic-link sign-in
+
+`beginOAuthLogin` / passwordless paths exist; see the SDK's `OauthNamespace`
+and the accounts OpenAPI for `/v1/auth/magic/*`.
+
+### MFA (TOTP)
+
+```ts
+const { secret, otpauthUrl } = await client.mfa.totp.enroll();   // render QR from otpauthUrl
+const { recoveryCodes } = await client.mfa.totp.confirm({ code }); // show ONCE
+```
+
+### OAuth 2.1 + PKCE (for when your dashboard is itself an OAuth client)
+
+```ts
+const { authorizationUrl } = await client.beginOAuthLogin({ … });
+// …redirect, then on callback:
+await client.completeOAuthLogin({ … });   // PKCE verifier from sessionStorage
+```
+
+Access token held in memory; refresh token delivered as an HttpOnly
+`wac_refresh` cookie scoped to `/token` (JS never touches it). The SDK does
+transparent single-flight refresh on 401.
+
+---
+
+## 5. Recovery-file format
+
+The throwaway frontend used this shape. **Treat it as a starting point** —
+production should wrap `record` with WebAuthn/recovery-code encryption rather
+than storing cleartext keys.
+
+```json
+{
+  "version": 1,
+  "type": "witnium-recovery",
+  "created": "<ISO 8601>",
+  "record": {
+    "email": "you@example.com",
+    "orgId": "<uuid>",
+    "userId": "<uuid>",
+    "contractAddress": "0x… (lowercase)",
+    "contractVersion": "5.0.0",
+    "ownerPublicKey": "<64 hex>",
+    "ownerPrivateKey": "<64 hex — ENCRYPT THIS>",
+    "signingPublicKey": "<64 hex>",
+    "signingPrivateKey": "<64 hex — ENCRYPT THIS>"
+  }
+}
+```
+
+Import = restore `record` into local storage. The owner private key must be
+retrievable for the MCP-CUSTODY ceremony (§6).
+
+---
+
+## 6. MCP-CUSTODY consent ceremony
+
+When a user connects an AI agent (claude.ai's MCP connector, or a self-hosted
+one) the backend runs a ceremony at OAuth-consent time that mints a **fresh
+ephemeral signing key per connection** and asks the user to sign two owner-key
+operations:
+
+1. `addSigningKey(<ephemeral key>)` — registers it on the contract (submitted now)
+2. `revokeSigningKey(<same key>)` — pre-signed, stored, fired automatically on disconnect
+
+**What the frontend must provide:** the page that collects these two
+signatures is currently *server-rendered by accounts* at
+`/interaction/:uid/sign-keys`. It runs inline JS that reads the owner key from
+`localStorage['witnium.ownerPrivateKey:<contractAddress>']`, signs both
+messages, and form-POSTs them back.
+
+You have two choices:
+
+- **Let accounts render it** (current behavior). Then your only job is to make
+  sure the owner key is in `localStorage` under that exact key, **on the
+  accounts origin** (see §7).
+- **Render it yourself** and POST the two signatures to
+  `/interaction/:uid/sign-keys` (`addOwnerSignature`, `revokeOwnerSignature`,
+  `revokeNonce`). Gives you full UX control. The signed message formats are:
+  - add: `{"op":1,"contract":"<addr>","nonce":<ownerNonce+1>,"newKey":"<pub>"}`
+  - revoke: `{"op":2,"contract":"<addr>","nonce":<ownerNonce+2>,"key":"<pub>"}`
+  (canonical JSON, signed as UTF-8 bytes with the owner key)
+
+To get refresh tokens (required for the agent to stay connected + for the
+disconnect-on-revoke cascade), the OAuth client **must request
+`prompt=consent`** and include `offline_access` in scope. Without
+`prompt=consent` the AS silently drops `offline_access` and no refresh token is
+issued — this is standard OIDC, not a bug.
+
+---
+
+## 7. Same-origin requirement (architectural — needs a decision)
+
+**The dashboard that stores keys and the accounts OIDC interaction pages must
+share an origin**, because `localStorage` is origin-scoped. Discovered in
+testing: keys saved on `test-frontend.witniumchain.com` were invisible to the
+sign-keys page rendered at `auth.witniumchain.com` → the ceremony couldn't find
+the owner key.
+
+Pick one:
+
+- **(Recommended) Serve the dashboard from `auth.witniumchain.com`** (a path,
+  or accounts serving the SPA). Owner key in localStorage is naturally visible
+  to the OIDC interaction pages. Simplest, no cross-origin plumbing.
+- **Cross-origin with `postMessage`** — dashboard on its own domain passes the
+  owner-key signature to the accounts interaction page via a `postMessage`
+  handshake. More moving parts; partially erodes the "keys never leave your
+  page" story. Only do this if a separate dashboard domain is a hard
+  requirement.
+
+This decision blocks the key-storage implementation, so settle it early.
+
+---
+
+## 8. Known limitations / sharp edges
+
+| Issue | Impact | Status |
+|---|---|---|
+| **Pre-signed revoke nonce drift** | If a user opens several agent connections in a row without disconnecting, older connections' on-chain `revokeSigningKey` fails when finally fired (the pre-signed sig is bound to a stale ownerNonce). The Vault key is still destroyed — Witnium genuinely loses signing ability — but the on-chain key stays listed as active. | Known. On-chain cleanup is best-effort under serial grants. Mitigation TBD (revoke-then-add atomic, or periodic re-sign). |
+| **`prompt=consent` required for refresh tokens** | Omitting it silently drops `offline_access`. | Working as designed (OIDC). Document in your OAuth client. |
+| **Email verify is GET** | POST returns "Cannot POST". | Working as designed. |
+| **Same-origin localStorage** | §7. | Architectural decision required. |
+
+---
+
+## 9. API reference
+
+- **accounts OpenAPI**: `https://auth.witniumchain.com/openapi.json` (or the
+  committed `specs/accounts.openapi.json` in the SDK repo)
+- **chain-api OpenAPI**: `specs/chain-api.openapi.json` in the SDK repo
+- Every SDK method's request/response type is derived from these specs via
+  `openapi-typescript`, so they stay in lockstep. Re-export aliases (e.g.
+  `CreateOrgRequest`, `SignupResponse`) are in `src/types.ts`.
+
+## 10. SDK clients at a glance
+
+| Client | For | Auth |
+|---|---|---|
+| `WitniumchainClient` | end-users (signup, login, OAuth, MFA, delegated keys, witness reads) | session cookie / access token |
+| `WitniumchainOrgClient` | org admins managing members | org API key |
+| `WitniumchainAdminClient` | sysadmin org lifecycle | admin token |
+| `WitniumchainChainAdminClient` | **service-to-service only** — not for frontend use | admin token / service-principal JWT |
+
+The frontend lives almost entirely in `WitniumchainClient`.

package/README.md

@@ -1,25 +1,43 @@
 # @witnium-tech/witniumchain
 
-TypeScript SDK for the WitniumChain accounts service — identity, billing,
-organisation administration, OAuth sessions, and delegated-signing-key
-management.
+TypeScript SDK for WitniumChain — the canonical single client for both the
+accounts service (identity, billing, OAuth, delegated keys, witness writes)
+and the chain-api read surfaces (contract info, witness lookup, wallet
+balance, dashboards). The two-service backend is hidden behind one
+`WitniumchainClient` class; you give it one OAuth access token and it knows
+where each call belongs.
 
 ## Status
 
-**v0.1 — low-level "shell" client.** One method per OpenAPI route, five
-auth modes selectable on a single client. Thread 4 of Phase C will layer
-three higher-level clients on top:
-
-- `WitniumchainClient` (end-user) — wraps signup, login, subscriptions,
-  delegated-key one-call provisioning, account management.
-- `WitniumchainOrgClient` (org admin) — wraps user provisioning, Stripe
-  Connect onboarding.
-- `WitniumchainAdminClient` (sysadmin) — wraps org lifecycle, key
-  rotation, credit adjustment.
-
-For now, this shell client is what's published. Every type comes from the
-OpenAPI spec via `openapi-typescript`; a CI drift test in the parent repo
-gates regeneration on every change.
+**v0.5 — adds OAuth 2.1 + PKCE login helpers** on top of the v0.4 surface:
+
+- All 41 accounts routes (five auth modes: session / OAuth / org / admin / signed)
+- 9 chain-api read methods, routed to `chainBaseUrl`, reusing the same OAuth
+  `accessToken` (accounts mints tokens with `aud=https://api.witniumchain.com`,
+  so they're valid against both services unchanged)
+- Three layered clients on top: `WitniumchainClient` (end-user),
+  `WitniumchainOrgClient` (org admin), `WitniumchainAdminClient` (sysadmin)
+- **`beginOAuthLogin` / `completeOAuthLogin` / `refreshAccessToken` / `signOut`** —
+  browser-side Authorization-Code + PKCE login flow. Discovery-driven
+  endpoint resolution (`/.well-known/openid-configuration`), PKCE verifier
+  in `sessionStorage`, access token held in memory only, transparent 401-retry
+  with single-flight refresh-token rotation. Refresh tokens are delivered as
+  an HttpOnly `wac_refresh` cookie scoped to `Path=/token` — JavaScript never
+  touches them. Non-browser callers (Node SSR, native apps without a cookie
+  jar) fall back to in-band refresh-token delivery; the SDK handles both.
+- **`client.mfa.totp.enroll/confirm/disable` + `client.mfa.recoveryCodes.regenerate`** —
+  TOTP MFA self-management. `enroll` returns the secret + otpauth URL (render
+  as a QR code in your dashboard with any QR lib); `confirm` validates the
+  first code and returns 10 single-use recovery codes (shown ONCE).
+
+What's NOT exposed (by design): chain-api v5 writes — those are proxied by
+accounts' v5 surface which adds credit reservation + idempotency + scope
+checks. Calling chain-api writes directly would burn credits without
+billing them. See `docs/PLAN-PHASE-SDK-UNIFIED.md` for the routing rules.
+
+Every type comes from the published OpenAPI specs of both services via
+`openapi-typescript`. `npm run openapi:check` regenerates and fails on
+diff; it runs ahead of every `npm publish`.
 
 ## Install
 
@@ -29,14 +47,14 @@ npm install @witnium-tech/witniumchain
 
 ## Auth model
 
-The accounts service accepts five distinct credentials. Configure whichever
+The SDK accepts five distinct credentials. Configure whichever
 you need on the client; methods that require a credential you didn't supply
 throw at call time.
 
 | Credential | Header / Cookie | Used by |
 |---|---|---|
 | `sessionCookie` | `Cookie: wac_session=…` | `/v1/auth/logout`, `/v1/account/*`, `/v1/billing/*`, `/v1/keys/*`, `/v1/contracts/{pause,unpause}`, `/v1/oauth/sessions*` |
-| `accessToken` | `Authorization: Bearer <JWT>` | `/v1/users/me/delegated-keys/*`, `/v1/sign` |
+| `accessToken` | `Authorization: Bearer <JWT>` | `/v1/users/me/delegated-keys/*`, `/v1/sign`, **all chain-api reads** |
 | `orgApiKey` | `Authorization: Bearer wcorg_live_…` | `/v1/orgs/me/*` |
 | `adminToken` | `Authorization: Bearer <ADMIN_TOKEN>` | `/v1/admin/*` |
 | `signedRequest` | `X-Witnium-Key/Timestamp/Signature` | `/v1/contracts/{addr}/witnesses/{propose,sign,finalize,revoke}` |
@@ -45,6 +63,30 @@ Public routes need no credential (`/v1/auth/{signup,verify,login,…}`,
 `/v1/contracts/provision`, `GET /v1/contracts/{addr}/witnesses/{id}`,
 `/health/*`).
 
+## Two services, one client
+
+Accounts and chain-api are separate services today (consolidation is a
+later phase). The SDK hides that:
+
+```ts
+const client = new WitniumchainClient({
+  baseUrl: 'https://auth.witniumchain.com',      // accounts
+  chainBaseUrl: 'https://api.witniumchain.com',  // chain-api (omit if you only need accounts)
+  accessToken: oauthBearerJwt,
+});
+
+// Writes / billing / auth → accounts (baseUrl)
+await client.proposeWitnessV5('0xabc', { ... });
+
+// Reads of on-chain state → chain-api (chainBaseUrl)
+const witness = await client.getWitnessV5('0xabc', witnessId);
+const balance = await client.getWalletBalance('0xabc');
+```
+
+If you call a chain-api method without `chainBaseUrl` configured, the SDK
+throws a clear `WitniumchainApiError` at call time naming the missing
+config — no silent fallback to a wrong base URL.
+
 ## Examples
 
 ### End-user signup + login
@@ -97,6 +139,40 @@ const { organization, apiKey } = await sys.createOrganization({
 // `apiKey` is shown ONCE — store it now.
 ```
 
+### Sign in with Witnium (Authorization Code + PKCE)
+
+For a browser SPA (e.g. a Lovable app) that wants to authenticate end-users
+against a Witnium org. No backend required.
+
+```ts
+const client = new WitniumchainClient({
+  baseUrl: 'https://auth.witniumchain.com',
+  oauthClientId: 'your-registered-client-id',
+});
+
+// 1. Kick off login. The SDK generates a PKCE pair, stashes the verifier in
+//    sessionStorage, and returns the URL to send the user to.
+const { authorizationUrl } = await client.beginOAuthLogin({
+  redirectUri: 'https://your-app.example/callback',
+});
+window.location.assign(authorizationUrl);
+
+// 2. On the callback page, complete the exchange. Returns the access token
+//    (the SDK ALSO holds it in memory; subsequent BearerJWT calls Just Work).
+const { accessToken, expiresAt } = await client.completeOAuthLogin(
+  window.location.href,
+);
+window.history.replaceState({}, '', window.location.pathname); // strip ?code=…
+
+// 3. Use the SDK normally. When the access token expires, the SDK refreshes
+//    transparently on the next call. You only need to redirect to login if
+//    refresh itself fails (refresh token revoked or expired).
+const { keys } = await client.listDelegatedKeys();
+
+// 4. Sign-out clears in-memory tokens.
+client.signOut();
+```
+
 ### OAuth API — delegated-key + sign
 
 ```ts