@witnium-tech/witniumchain 0.11.0 → 0.12.0

package/FRONTEND-INTEGRATION.md

@@ -86,16 +86,17 @@ const result = await client.createOrg({
   ownerPublicKey: ownerPubHex,
   initialSigningPublicKey: signingPubHex,
 });
-// → { orgId, userId, contractAddress, contractVersion, emailVerifyToken }
+// → { orgId, userId, contractAddress, contractVersion }
 ```
 
 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.
+The verification email is sent to `adminEmail`; there is nothing to render.
+The response never carries the verify token. If the email cannot be sent,
+nothing is created and the call fails with a 502; retry the same request.
+**The email is the login gate, not the contract-deploy gate**: the contract is
+already live when this returns.
 
 ---
 
@@ -112,12 +113,27 @@ await client.verifyEmail(token);   // GET /v1/auth/verify?token=…
 ### Password login
 
 ```ts
-await client.login({ email, password });   // sets wac_session cookie
+const res = await client.login({ email, password });
+if (res.status === 'mfa_required') {
+  // NO session yet. Ask for the authenticator code (offer "use a recovery code").
+  await client.loginMfa({ code });            // or { recoveryCode }
+}
+// status 'authenticated': the wac_session cookie is set
 ```
 
-In a browser the `wac_session` cookie is set automatically (the SDK uses
+Always check `status`. A user with an authenticator app gets `mfa_required`
+and only a short-lived challenge cookie scoped to `/v1/auth/login/mfa`;
+treating that as logged in leaves the user without a session. `loginMfa`
+errors: 401 `mfa_code_invalid` (wrong or reused code, let them retry), 401
+`mfa_challenge_invalid` (expired or too many tries, back to the password
+step), 429 `mfa_rate_limited` (`retryAfterSeconds` on the error body).
+
+In a browser the cookies are set automatically (the SDK uses
 `credentials: 'include'`). Server-side callers must capture + replay the cookie.
 
+`client.logout()` ends the session and drops the SDK's cached bearer token,
+even when the request fails.
+
 ### Cookie-only dashboard → bearer calls (automatic, no OAuth needed)
 
 You do **not** need to run the OAuth code flow to call the operational API
@@ -157,9 +173,19 @@ and the accounts OpenAPI for `/v1/auth/magic/*`.
 
 ```ts
 const { secret, otpauthUrl } = await client.mfa.totp.enroll();   // render QR from otpauthUrl
-const { recoveryCodes } = await client.mfa.totp.confirm({ code }); // show ONCE
+const { recoveryCodes } = await client.mfa.totp.confirm(code);    // show ONCE
+
+// Both need the user's current code (or a recovery code):
+await client.mfa.totp.disable({ code });
+const { recoveryCodes: fresh } = await client.mfa.recoveryCodes.regenerate({ recoveryCode });
 ```
 
+`confirm` signs the user out of every other device and connected app (MCP
+connectors included); tell the user so. The SDK drops its cached
+session-minted bearer token and mints a fresh one on the next call.
+`disable` and `regenerate` fail with 403 `mfa_step_up_failed` on a wrong
+proof and 429 `mfa_rate_limited`.
+
 ### OAuth 2.1 + PKCE (for when your dashboard is itself an OAuth client)
 
 ```ts

package/README.md

@@ -28,16 +28,25 @@ where each call belongs.
 - **`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).
+  first code and returns 10 single-use recovery codes (shown ONCE). `disable`
+  and `regenerate` require a second-factor proof (`{ code }` or
+  `{ recoveryCode }`). Password login: check `login()`'s `status`; on
+  `mfa_required`, finish with `loginMfa({ code })`.
 
 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`.
+Every type comes from the OpenAPI specs of both services, vendored in
+`specs/` and compiled with `openapi-typescript`. `npm test` fails when the
+chain spec differs from this repo's `public/openapi.json`, when the accounts
+spec differs from the sha256 recorded in `specs/sources.json`, or when
+`src/generated/` is stale. The accounts service is a separate private repo, so
+CI cannot read it: `npm run openapi:verify:accounts` (with
+`WITNIUMCHAIN_ACCOUNTS_REPO` pointing at a clone) checks the recorded commit
+and the current `origin/main` there, and runs ahead of every `npm publish`.
+`npm run openapi:refresh` re-vendors both specs and regenerates the types.
 
 ## Install
 
@@ -104,7 +113,8 @@ const { provisioningToken } = await client.verifyEmail('the-token-from-the-link'
 
 // Then login (sets the wac_session cookie in a browser; in Node, capture
 // from response headers and pass back via `sessionCookie`).
-await client.login({ email: 'alice@example.com', password: '…' });
+const res = await client.login({ email: 'alice@example.com', password: '…' });
+if (res.status === 'mfa_required') await client.loginMfa({ code: '123456' });
 ```
 
 ### Org admin — create a user