@witnium-tech/witniumchain 0.11.0 → 0.12.0

package/dist/index.d.mts

@@ -73,8 +73,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -264,8 +264,8 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -323,7 +323,7 @@ interface paths$1 {
         put?: never;
         /**
          * Log in with email + password
-         * @description On success, sets a `wac_session` cookie (httpOnly, secure, SameSite=Lax, 30-day TTL) and returns a 200. No token is included in the body.
+         * @description Without confirmed TOTP: sets a `wac_session` cookie (httpOnly, secure, 30-day TTL) and returns `status: "authenticated"`. With confirmed TOTP: NO session is issued. The response is `status: "mfa_required"` and sets a `wac_mfa` challenge cookie (httpOnly, secure, Path=/v1/auth/login/mfa, 5 minutes); complete the login with `POST /v1/auth/login/mfa`. No token is included in the body.
          */
         post: {
             parameters: {
@@ -347,14 +347,163 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description `authenticated`: the `wac_session` cookie is set. `mfa_required`: no session yet; send the second factor to `/v1/auth/login/mfa`.
+                             * @enum {string}
+                             */
+                            status: "authenticated" | "mfa_required";
+                            message: string;
+                            /** @description Present when `status` is `mfa_required`. */
+                            methods?: ("totp" | "recovery_code")[];
+                            /** @description Challenge lifetime; present when `status` is `mfa_required`. */
+                            expiresInSeconds?: number;
+                        };
+                    };
+                };
+                /** @description Bad Request — validation failed */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Too Many Requests */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/auth/login/mfa": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Complete an MFA login with a TOTP or recovery code
+         * @description Second step after `/v1/auth/login` answered `mfa_required`. Requires the `wac_mfa` cookie that response set. On success sets `wac_session`, clears `wac_mfa` and returns `status: "authenticated"`. 401 with error `mfa_code_invalid`: wrong or already-used code, retry. 401 with error `mfa_challenge_invalid`: the challenge expired (5 min), was used, or saw 5 wrong codes; start again at `/v1/auth/login`. 429 `mfa_rate_limited`: the per-user attempt budget (10 per 15 min) is exhausted.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /**
+                         * @description Current 6-digit TOTP code. Each code is accepted once.
+                         * @example 123456
+                         */
+                        code?: string;
+                        /**
+                         * @description An unused recovery code (consumed by this request).
+                         * @example ABCD-EFGH
+                         */
+                        recoveryCode?: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
                         "application/json": {
+                            /**
+                             * @description `authenticated`: the `wac_session` cookie is set. `mfa_required`: no session yet; send the second factor to `/v1/auth/login/mfa`.
+                             * @enum {string}
+                             */
+                            status: "authenticated" | "mfa_required";
                             message: string;
+                            /** @description Present when `status` is `mfa_required`. */
+                            methods?: ("totp" | "recovery_code")[];
+                            /** @description Challenge lifetime; present when `status` is `mfa_required`. */
+                            expiresInSeconds?: number;
                         };
                     };
                 };
@@ -452,7 +601,7 @@ interface paths$1 {
         put?: never;
         /**
          * Clear the current session
-         * @description Revokes the session bound to the `wac_session` cookie (if present) and clears the cookie. Idempotent — works even with no active session.
+         * @description Revokes the session bound to the `wac_session` cookie (if present) and clears the cookie; access tokens minted from that session via `POST /v1/auth/access-token` stop working at once. Idempotent — works even with no active session.
          */
         post: {
             parameters: {
@@ -463,8 +612,8 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -515,8 +664,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -595,7 +744,7 @@ interface paths$1 {
         put?: never;
         /**
          * Apply a password reset
-         * @description Exchanges a reset token for a new password. The token from the email is single-use and time-limited.
+         * @description Exchanges a reset token for a new password. The token from the email is single-use and time-limited. Also signs the user out everywhere: every session, every token minted from one, and every connected OAuth app (grants revoked, security epoch bumped).
          */
         post: {
             parameters: {
@@ -615,8 +764,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -708,7 +857,7 @@ interface paths$1 {
                 content: {
                     "application/json": {
                         /**
-                         * @description Stripe Price ID. Drives the line item on the Checkout session — the Price's associated Product must carry a `witnessCredits` metadata key for credits to land in the ledger on `checkout.session.completed`.
+                         * @description Stripe Price ID. Drives the line item on the Checkout session — the Price's Product must carry `credits` (and, for subscriptions, `plan_slug`) metadata for credits/plan to apply via the webhook.
                          * @example price_1ABC...
                          */
                         priceId: string;
@@ -717,12 +866,22 @@ interface paths$1 {
                          * @enum {string}
                          */
                         mode: "payment" | "subscription";
+                        /**
+                         * Format: uri
+                         * @description Override the post-checkout success redirect.
+                         */
+                        successUrl?: string;
+                        /**
+                         * Format: uri
+                         * @description Override the checkout-cancelled redirect.
+                         */
+                        cancelUrl?: string;
                     };
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -926,9 +1085,11 @@ interface paths$1 {
         /**
          * Stripe webhook receiver
          * @description Source of truth for credit grants. Verifies the `stripe-signature` header against `STRIPE_WEBHOOK_SECRET` over the raw request body, then dispatches on event type:
-         *       - `checkout.session.completed` → grant `metadata.witnessCredits` from the Price's Product to the org's credit ledger.
-         *       - `invoice.paid` → grant subscription monthly credits.
-         *       - `customer.subscription.deleted` → noop (handled at access-control layer).
+         *       - `checkout.session.completed` (payment mode only) → grant pack `credits`.
+         *       - `invoice.paid` → grant subscription monthly `credits`.
+         *       - `customer.subscription.created`/`.updated` → set org `plan`, `current_period_end`, `subscription_status`.
+         *       - `customer.subscription.deleted` → revert to free plan + resume free-tier.
+         *       - `invoice.payment_failed` → mark `past_due` (grace).
          *     Idempotent via the `stripe_events` table keyed on `event.id`. Body is the raw Stripe event (consumed pre-JSON-parse), not the documented schema.
          */
         post: {
@@ -940,8 +1101,8 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -996,7 +1157,7 @@ interface paths$1 {
         put?: never;
         /**
          * Create an organisation with client-generated keys
-         * @description Phase RBAC Thread D — explicit org creation. The caller generates the owner key and the initial signing key client-side; Witnium never holds the private bytes. The response includes the freshly-deployed contract address and a one-time email-verify token.
+         * @description Phase RBAC Thread D — explicit org creation. The caller generates the owner key and the initial signing key client-side; Witnium never holds the private bytes. The response includes the freshly-deployed contract address. The email-verify link is sent to adminEmail and is never returned. If that email cannot be sent, nothing is created and the route returns 502; retry the request.
          */
         post: {
             parameters: {
@@ -1034,8 +1195,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -1055,8 +1216,6 @@ interface paths$1 {
                             contractAddress: string;
                             /** @description Semantic on-chain Solidity version (e.g. "5.0.0"). */
                             contractVersion: string;
-                            /** @description Email-verify token. Already sent to adminEmail; echoed here for flows that prefer to surface a "click this link" in their own UI. */
-                            emailVerifyToken: string;
                         };
                     };
                 };
@@ -1110,6 +1269,56 @@ interface paths$1 {
                         };
                     };
                 };
+                /** @description Too Many Requests */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Bad Gateway */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
             };
         };
         delete?: never;
@@ -1281,10 +1490,21 @@ interface paths$1 {
                                 createdAt: string;
                                 /**
                                  * Format: date-time
-                                 * @description ISO 8601 date-time string
+                                 * @description When the user proved control of the mailbox by consuming an emailed verify token. Null for users the org created via its API key until they do; org creation is recorded in identityAttestedByOrgId instead.
                                  * @example 2026-05-20T10:30:00.000Z
                                  */
                                 emailVerifiedAt: string | null;
+                                /**
+                                 * @description Org whose API key created the user and vouched for the identity. This is NOT proof of mailbox control.
+                                 * @example 550e8400-e29b-41d4-a716-446655440000
+                                 */
+                                identityAttestedByOrgId: string | null;
+                                /**
+                                 * Format: date-time
+                                 * @description ISO 8601 date-time string
+                                 * @example 2026-05-20T10:30:00.000Z
+                                 */
+                                identityAttestedAt: string | null;
                             }[];
                         };
                     };
@@ -1343,8 +1563,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -1552,7 +1772,10 @@ interface paths$1 {
         };
         get?: never;
         put?: never;
-        /** Invite a member to the caller's org */
+        /**
+         * Invite a member to the caller's org
+         * @description Adds the membership and, unless the invitee already verified their email, mails them an invitation with the verify link. Idempotent: re-inviting re-sends the mail. 502 means the membership was recorded but the email could not be sent; retry.
+         */
         post: {
             parameters: {
                 query?: never;
@@ -1578,8 +1801,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -1597,7 +1820,8 @@ interface paths$1 {
                             membershipId: string;
                             userPreexisted: boolean;
                             membershipPreexisted: boolean;
-                            emailVerifyToken?: string;
+                            /** @description True when an invitation email (with the verify link) was sent, i.e. the invitee had not yet verified their email. The token is never returned. */
+                            inviteEmailSent: boolean;
                         };
                     };
                 };
@@ -1651,49 +1875,99 @@ interface paths$1 {
                         };
                     };
                 };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/v1/orgs/me/members/{userId}/suspend": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /** Suspend a member (reversible). The owner cannot be suspended. */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Success */
-                200: {
+                /** @description Too Many Requests */
+                429: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
                         "application/json": {
                             /**
-                             * @description UUID v4
-                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             * @description HTTP status code
+                             * @example 400
                              */
-                            membershipId: string;
+                            statusCode?: number;
                             /**
-                             * Format: date-time
-                             * @description ISO 8601 date-time string
-                             * @example 2026-05-20T10:30:00.000Z
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Bad Gateway */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/orgs/me/members/{userId}/suspend": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Suspend a member (reversible). The owner cannot be suspended. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Created */
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description UUID v4
+                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             */
+                            membershipId: string;
+                            /**
+                             * Format: date-time
+                             * @description ISO 8601 date-time string
+                             * @example 2026-05-20T10:30:00.000Z
                              */
                             suspendedAt: string;
                         };
@@ -1801,8 +2075,8 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -2133,7 +2407,10 @@ interface paths$1 {
         };
         get?: never;
         put?: never;
-        /** Re-mint an email-verify token for a pending member */
+        /**
+         * Re-send the invitation email to a pending member
+         * @description Mints a fresh verify token, invalidates earlier ones and mails it. The token is never returned. 502 means the email could not be sent and nothing changed (the previous link stays valid).
+         */
         post: {
             parameters: {
                 query?: never;
@@ -2143,14 +2420,13 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
                         "application/json": {
-                            emailVerifyToken: string;
                             /**
                              * Format: email
                              * @description RFC 5321 email address
@@ -2235,6 +2511,56 @@ interface paths$1 {
                         };
                     };
                 };
+                /** @description Too Many Requests */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Bad Gateway */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
             };
         };
         delete?: never;
@@ -2287,8 +2613,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -2726,8 +3052,8 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -2877,8 +3203,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -3016,6 +3342,10 @@ interface paths$1 {
                              * @example 2026-05-20T10:30:00.000Z
                              */
                             revokedAt: string | null;
+                            /** @description True when the key belongs to one OAuth grant (a connected app): only that app can sign with it, and disconnecting the app ends it. */
+                            boundToOauthGrant: boolean;
+                            /** @description For a key that belongs to no grant: whether the user shared it with OAuth clients (PATCH). Only shared keys are visible and usable to them. */
+                            sharedWithOauthClients: boolean;
                         }[];
                     };
                 };
@@ -3120,8 +3450,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -3293,8 +3623,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -3618,45 +3948,23 @@ interface paths$1 {
         };
         options?: never;
         head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/v1/sign": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
         /**
-         * Sign bytes with a delegated key
-         * @description Vault Transit signs the supplied payload using the user's delegated key. Vault returns the signature; the accounts-service process never sees the private bytes (delegated keys are created with `exportable=false`).
-         *
-         *     **Use:** sign the canonical-intent JSON returned by chain-api `POST /v5/contracts/.../witnesses/propose` (and the analogous v4 endpoint). The endpoint signs whatever bytes you submit because sign:write is an explicit grant to use the user's key — the on-chain authority of the key is bounded to witness ops on the user's contract, and nothing else in Witnium currently consumes these signatures. Future signing surfaces that need different keys or scopes get their own.
-         *
-         *     **Limits:** payload ≤ 8 KiB (16384 hex chars), per-user rate-limited at 20 signs/minute (429 + Retry-After on excess). Both are resource bounds, not access-control fences.
-         *
-         *     Optional `X-Request-Id` request header gets forwarded into the audit-log line; a UUID is generated if absent.
+         * Share a durable delegated key with OAuth clients (or stop)
+         * @description Dashboard only (a token from POST /v1/auth/access-token); OAuth tokens get 403. Applies to keys that belong to no OAuth grant. A shared key can be listed and used to sign by every OAuth client the user connected to this org, but submitted or revoked only from the dashboard.
          */
-        post: {
+        patch: {
             parameters: {
                 query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    id: string;
+                };
                 cookie?: never;
             };
             requestBody?: {
                 content: {
                     "application/json": {
-                        /**
-                         * @description The delegated key (per-user, per-contract) used to sign. Must be confirmed on-chain and not revoked.
-                         * @example 550e8400-e29b-41d4-a716-446655440000
-                         */
-                        delegatedKeyId: string;
-                        /** @description Hex-encoded bytes to sign (no 0x prefix). Must have an even length and at most 16384 hex characters (8 KiB raw). The expected use is signing the UTF-8 bytes of a v5 canonical-intent JSON returned by chain-api `/propose`, but the endpoint signs whatever bytes you submit — sign:write is an explicit grant to use the user's key. Witnium never logs the bytes; only their SHA-256 hash is recorded for audit cross-correlation with Vault. */
-                        payload: string;
+                        sharedWithOauthClients: boolean;
                     };
                 };
             };
@@ -3668,18 +3976,46 @@ interface paths$1 {
                     };
                     content: {
                         "application/json": {
-                            /** @description Ed25519 signature over the payload bytes, hex-encoded. */
-                            signature: string;
                             /**
-                             * @description Public key of the delegated key used to sign — for verification.
+                             * @description UUID v4
+                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             */
+                            id: string;
+                            /**
+                             * @description Ethereum address (0x + 40 hex characters)
+                             * @example 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0
+                             */
+                            contractAddress: string;
+                            /**
+                             * @description Ed25519 public key — 32 bytes hex-encoded (64 chars, no 0x prefix)
                              * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
                              */
-                            signerPublicKey: string;
+                            publicKey: string;
                             /**
-                             * @description UUID v4
-                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             * Format: date-time
+                             * @description ISO 8601 date-time string
+                             * @example 2026-05-20T10:30:00.000Z
                              */
-                            delegatedKeyId: string;
+                            createdAt: string;
+                            /**
+                             * Format: date-time
+                             * @description Set once the on-chain addSigningKey tx is mined.
+                             * @example 2026-05-20T10:30:00.000Z
+                             */
+                            confirmedAt: string | null;
+                            /** @description Transaction hash from the addSigningKey submission, if any. */
+                            confirmedTxHash: string | null;
+                            confirmedBlockNumber: number | null;
+                            /**
+                             * Format: date-time
+                             * @description Set when the user locally revokes the key (Vault key wiped). Does NOT mean the on-chain record was revoked.
+                             * @example 2026-05-20T10:30:00.000Z
+                             */
+                            revokedAt: string | null;
+                            /** @description True when the key belongs to one OAuth grant (a connected app): only that app can sign with it, and disconnecting the app ends it. */
+                            boundToOauthGrant: boolean;
+                            /** @description For a key that belongs to no grant: whether the user shared it with OAuth clients (PATCH). Only shared keys are visible and usable to them. */
+                            sharedWithOauthClients: boolean;
                         };
                     };
                 };
@@ -3808,40 +4144,11 @@ interface paths$1 {
                         };
                     };
                 };
-                /** @description Too Many Requests */
-                429: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /**
-                             * @description HTTP status code
-                             * @example 400
-                             */
-                            statusCode?: number;
-                            /**
-                             * @description Short error label
-                             * @example Bad Request
-                             */
-                            error?: string;
-                            /**
-                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
-                             * @example Validation failed
-                             */
-                            message: string | string[];
-                        };
-                    };
-                };
             };
         };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
         trace?: never;
     };
-    "/v1/contracts/provision": {
+    "/v1/sign": {
         parameters: {
             query?: never;
             header?: never;
@@ -3851,8 +4158,14 @@ interface paths$1 {
         get?: never;
         put?: never;
         /**
-         * Provision a witness contract for a user
-         * @description Consumes the user's `provisioningToken` and deploys their on-chain WitnessRegistry. Email must already be verified (the token bundles that gate). Idempotent in the sense that a second call with the same token returns 4xx because the token is single-use.
+         * Sign bytes with a delegated key
+         * @description Vault Transit signs the supplied payload using the user's delegated key. Vault returns the signature; the accounts-service process never sees the private bytes (delegated keys are created with `exportable=false`).
+         *
+         *     **Use:** sign the canonical-intent JSON returned by chain-api `POST /v5/contracts/.../witnesses/propose` (and the analogous v4 endpoint). The endpoint signs whatever bytes you submit because sign:write is an explicit grant to use the user's key — the on-chain authority of the key is bounded to witness ops on the user's contract, and nothing else in Witnium currently consumes these signatures. Future signing surfaces that need different keys or scopes get their own.
+         *
+         *     **Limits:** payload ≤ 8 KiB (16384 hex chars), per-user rate-limited at 20 signs/minute (429 + Retry-After on excess). Both are resource bounds, not access-control fences.
+         *
+         *     Optional `X-Request-Id` request header gets forwarded into the audit-log line; a UUID is generated if absent.
          */
         post: {
             parameters: {
@@ -3864,11 +4177,225 @@ interface paths$1 {
             requestBody?: {
                 content: {
                     "application/json": {
-                        /** @description One-time token issued after email verification (or by an org admin via POST /v1/orgs/me/users). Consumed atomically. */
-                        provisioningToken: string;
                         /**
-                         * @description Owner Ed25519 public key. Generated client-side and never seen by the server again — must NOT equal `initialSigningPublicKey`.
-                         * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
+                         * @description The delegated key (per-user, per-contract) used to sign. Must be confirmed on-chain and not revoked.
+                         * @example 550e8400-e29b-41d4-a716-446655440000
+                         */
+                        delegatedKeyId: string;
+                        /** @description Hex-encoded bytes to sign (no 0x prefix). Must have an even length and at most 16384 hex characters (8 KiB raw). The expected use is signing the UTF-8 bytes of a v5 canonical-intent JSON returned by chain-api `/propose`, but the endpoint signs whatever bytes you submit — sign:write is an explicit grant to use the user's key. Witnium never logs the bytes; only their SHA-256 hash is recorded for audit cross-correlation with Vault. */
+                        payload: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Created */
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @description Ed25519 signature over the payload bytes, hex-encoded. */
+                            signature: string;
+                            /**
+                             * @description Public key of the delegated key used to sign — for verification.
+                             * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
+                             */
+                            signerPublicKey: string;
+                            /**
+                             * @description UUID v4
+                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             */
+                            delegatedKeyId: string;
+                        };
+                    };
+                };
+                /** @description Bad Request — validation failed */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Forbidden — insufficient permissions or scope */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Not Found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Conflict */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Too Many Requests */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/contracts/provision": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Provision a witness contract for a user
+         * @description Consumes the user's `provisioningToken` and deploys their on-chain WitnessRegistry. Email must already be verified (the token bundles that gate). Idempotent in the sense that a second call with the same token returns 4xx because the token is single-use.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description One-time token issued after email verification (or by an org admin via POST /v1/orgs/me/users). Consumed atomically. */
+                        provisioningToken: string;
+                        /**
+                         * @description Owner Ed25519 public key. Generated client-side and never seen by the server again — must NOT equal `initialSigningPublicKey`.
+                         * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
                          */
                         ownerPublicKey: string;
                         /**
@@ -3880,8 +4407,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -3993,8 +4520,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4098,8 +4625,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4198,8 +4725,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4298,8 +4825,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4411,8 +4938,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4543,8 +5070,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4662,8 +5189,8 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4797,8 +5324,8 @@ interface paths$1 {
                 };
             };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -4974,7 +5501,7 @@ interface paths$1 {
         put?: never;
         /**
          * Internal callback from chain-api
-         * @description NOT for external use. Invoked by chain-api when a witness tx settles so accounts can update its credit reservations. HMAC-authenticated via X-Witnium-Callback-{Timestamp,Signature} headers using the shared INTERNAL_CALLBACK_HMAC_SECRET. Listed in the spec for completeness; SDK consumers should ignore.
+         * @description NOT for external use. Invoked by chain-api when a witness tx settles so accounts can update its credit reservations. Authenticated by internal callback protocol v1 (docs/internal-callback-protocol.md): X-Witnium-Event-Id, X-Witnium-Callback-Timestamp and X-Witnium-Callback-Signature, an HMAC over the event id, timestamp, method, path with query and body hash using the shared INTERNAL_CALLBACK_HMAC_SECRET. Deduplicated by event id: a redelivered event returns 200 without side effects. Listed in the spec for completeness; SDK consumers should ignore.
          */
         post: {
             parameters: {
@@ -4989,12 +5516,12 @@ interface paths$1 {
                 content: {
                     "application/json": {
                         /** @description 32-byte hash, lower-case hex without 0x prefix. */
-                        witnessId?: string;
+                        witnessId: string;
                         /**
-                         * @description Settlement state from chain-api. `confirmed` → release reservation against the witness. `failed` / `dropped` → release back to the org.
+                         * @description Settlement state from chain-api. `confirmed` → commit the reservation against the witness. `failed` → release it back to the org.
                          * @enum {string}
                          */
-                        status?: "confirmed" | "failed" | "dropped";
+                        status: "confirmed" | "failed";
                         error?: string;
                     };
                 };
@@ -5007,8 +5534,8 @@ interface paths$1 {
                     };
                     content: {
                         "application/json": {
-                            ok: boolean;
-                            reason?: string;
+                            /** @enum {boolean} */
+                            ok: true;
                         };
                     };
                 };
@@ -5675,24 +6202,25 @@ interface paths$1 {
         patch?: never;
         trace?: never;
     };
-    "/v1/account/provisioning-token/reissue": {
+    "/v3/contracts/{contractAddress}/witnesses/intents/{intentId}": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
-        put?: never;
         /**
-         * Re-mint a provisioning token (verified-but-not-provisioned recovery)
-         * @description Mints a fresh single-use provisioning token for a signed-in user whose email is verified but who has no contract yet — recovery for when the token from email-verify was lost (e.g. verify opened on another device). Returns 409 if email is unverified or a contract already exists. Rate limited per account.
+         * Recover a v3 witness intent's outcome
+         * @description For a client that lost a finalize (or propose) response. Returns the stored finalize response when accounts has one, otherwise chain-api's status for the intent. The URL contract must be the caller's. Read-only: never finalizes.
          */
-        post: {
+        get: {
             parameters: {
                 query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    contractAddress: string;
+                    intentId: string;
+                };
                 cookie?: never;
             };
             requestBody?: never;
@@ -5704,16 +6232,77 @@ interface paths$1 {
                     };
                     content: {
                         "application/json": {
-                            provisioningToken: string;
+                            /** @enum {string} */
+                            source: "stored";
+                            intentId: string;
+                            registryVersion: number;
                             /**
-                             * Format: date-time
-                             * @description ISO 8601 date-time string
-                             * @example 2026-05-20T10:30:00.000Z
+                             * @description The caller's credit reservation for this intent: `held` (reserved, not finalized), `finalizing` (finalize forwarded, outcome pending), `committed` (charged), `released` / `expired` (refunded; nothing was charged).
+                             * @enum {string}
                              */
-                            expiresAt: string;
-                        };
-                    };
-                };
+                            reservationState: "held" | "finalizing" | "committed" | "released" | "expired";
+                            /** @description The finalize response, exactly as first returned. */
+                            result: {
+                                [key: string]: unknown;
+                            };
+                        } | {
+                            /** @enum {string} */
+                            source: "chain";
+                            intentId: string;
+                            registryVersion: number;
+                            /**
+                             * @description The caller's credit reservation for this intent: `held` (reserved, not finalized), `finalizing` (finalize forwarded, outcome pending), `committed` (charged), `released` / `expired` (refunded; nothing was charged).
+                             * @enum {string|null}
+                             */
+                            reservationState: "held" | "finalizing" | "committed" | "released" | "expired" | null;
+                            /**
+                             * WitnessIntentChainStatus
+                             * @description chain-api's status for the intent, verbatim.
+                             */
+                            status: {
+                                intentId: string;
+                                contractAddress: string;
+                                registryVersion: number;
+                                /** @enum {string} */
+                                status: "prepared" | "allocated" | "submitted" | "confirmed" | "failed" | "cancelled" | "expired_unsubmitted" | "unknown";
+                                prepareTtlSeconds: number;
+                                /** @description Present when `confirmed`. */
+                                witnessId?: string;
+                                /** @description Present when `confirmed`. */
+                                transactionHash?: string;
+                                /** @description Present when `confirmed`. */
+                                blockNumber?: number;
+                                /** @description Present when `unknown`. */
+                                reason?: string;
+                            };
+                        };
+                    };
+                };
+                /** @description Bad Request — validation failed */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
                 /** @description Unauthorized — authentication required or invalid */
                 401: {
                     headers: {
@@ -5739,8 +6328,8 @@ interface paths$1 {
                         };
                     };
                 };
-                /** @description Conflict */
-                409: {
+                /** @description Forbidden — insufficient permissions or scope */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -5764,8 +6353,8 @@ interface paths$1 {
                         };
                     };
                 };
-                /** @description Too Many Requests */
-                429: {
+                /** @description Not Found */
+                404: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -5791,13 +6380,15 @@ interface paths$1 {
                 };
             };
         };
+        put?: never;
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/v1/account": {
+    "/v4/contracts/{contractAddress}/witnesses/intents/{intentId}": {
         parameters: {
             query?: never;
             header?: never;
@@ -5805,14 +6396,17 @@ interface paths$1 {
             cookie?: never;
         };
         /**
-         * Read the authenticated user's account
-         * @description Returns the user profile, a summary of their organisation, and the list of signing keys (active + revoked).
+         * Recover a v4 witness intent's outcome
+         * @description For a client that lost a finalize (or propose) response. Returns the stored finalize response when accounts has one, otherwise chain-api's status for the intent. The URL contract must be the caller's. Read-only: never finalizes.
          */
         get: {
             parameters: {
                 query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    contractAddress: string;
+                    intentId: string;
+                };
                 cookie?: never;
             };
             requestBody?: never;
@@ -5824,89 +6418,74 @@ interface paths$1 {
                     };
                     content: {
                         "application/json": {
-                            /** AccountUser */
-                            user: {
-                                /**
-                                 * @description UUID v4
-                                 * @example 550e8400-e29b-41d4-a716-446655440000
-                                 */
-                                id: string;
-                                /**
-                                 * Format: email
-                                 * @description RFC 5321 email address
-                                 * @example user@example.com
-                                 */
-                                email: string;
-                                /**
-                                 * Format: date-time
-                                 * @description ISO 8601 date-time string
-                                 * @example 2026-05-20T10:30:00.000Z
-                                 */
-                                emailVerifiedAt: string | null;
-                                /**
-                                 * @description Ethereum address (0x + 40 hex characters)
-                                 * @example 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0
-                                 */
-                                contractAddress: string | null;
-                                /**
-                                 * @description Ed25519 public key — 32 bytes hex-encoded (64 chars, no 0x prefix)
-                                 * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
-                                 */
-                                ownerPublicKey: string | null;
-                                /** @description Server-cached owner nonce (`ownerNonceCached`). */
-                                ownerNonce: number | null;
-                                externalUserId: string | null;
-                                /**
-                                 * Format: uri
-                                 * @description Webhook URL for chain-api to hit on witness settle (per-user).
-                                 */
-                                callbackUrl: string | null;
+                            /** @enum {string} */
+                            source: "stored";
+                            intentId: string;
+                            registryVersion: number;
+                            /**
+                             * @description The caller's credit reservation for this intent: `held` (reserved, not finalized), `finalizing` (finalize forwarded, outcome pending), `committed` (charged), `released` / `expired` (refunded; nothing was charged).
+                             * @enum {string}
+                             */
+                            reservationState: "held" | "finalizing" | "committed" | "released" | "expired";
+                            /** @description The finalize response, exactly as first returned. */
+                            result: {
+                                [key: string]: unknown;
                             };
-                            /** AccountOrgSummary */
-                            organization: {
-                                /**
-                                 * @description UUID v4
-                                 * @example 550e8400-e29b-41d4-a716-446655440000
-                                 */
-                                id: string;
-                                name: string;
-                                /**
-                                 * Format: email
-                                 * @description RFC 5321 email address
-                                 * @example user@example.com
-                                 */
-                                email: string;
-                                /**
-                                 * @description `metered` orgs pay per witness (credit ledger drives gating). `unlimited` orgs are flat-fee billed outside Stripe Checkout.
-                                 * @enum {string}
-                                 */
-                                accountType: "metered" | "unlimited";
-                                /** @description Cached credit balance; `null` for `unlimited` orgs. */
-                                balance: number | null;
-                                isPersonal: boolean;
+                        } | {
+                            /** @enum {string} */
+                            source: "chain";
+                            intentId: string;
+                            registryVersion: number;
+                            /**
+                             * @description The caller's credit reservation for this intent: `held` (reserved, not finalized), `finalizing` (finalize forwarded, outcome pending), `committed` (charged), `released` / `expired` (refunded; nothing was charged).
+                             * @enum {string|null}
+                             */
+                            reservationState: "held" | "finalizing" | "committed" | "released" | "expired" | null;
+                            /**
+                             * WitnessIntentChainStatus
+                             * @description chain-api's status for the intent, verbatim.
+                             */
+                            status: {
+                                intentId: string;
+                                contractAddress: string;
+                                registryVersion: number;
+                                /** @enum {string} */
+                                status: "prepared" | "allocated" | "submitted" | "confirmed" | "failed" | "cancelled" | "expired_unsubmitted" | "unknown";
+                                prepareTtlSeconds: number;
+                                /** @description Present when `confirmed`. */
+                                witnessId?: string;
+                                /** @description Present when `confirmed`. */
+                                transactionHash?: string;
+                                /** @description Present when `confirmed`. */
+                                blockNumber?: number;
+                                /** @description Present when `unknown`. */
+                                reason?: string;
                             };
-                            signingKeys: {
-                                /**
-                                 * @description Ed25519 public key — 32 bytes hex-encoded (64 chars, no 0x prefix)
-                                 * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
-                                 */
-                                publicKey: string;
-                                label: string | null;
-                                /**
-                                 * Format: date-time
-                                 * @description ISO 8601 date-time string
-                                 * @example 2026-05-20T10:30:00.000Z
-                                 */
-                                addedAt: string;
-                                /**
-                                 * Format: date-time
-                                 * @description ISO 8601 date-time string
-                                 * @example 2026-05-20T10:30:00.000Z
-                                 */
-                                revokedAt: string | null;
-                                /** @description `true` iff `revokedAt` is null. Convenience for clients. */
-                                active: boolean;
-                            }[];
+                        };
+                    };
+                };
+                /** @description Bad Request — validation failed */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
                         };
                     };
                 };
@@ -5935,6 +6514,31 @@ interface paths$1 {
                         };
                     };
                 };
+                /** @description Forbidden — insufficient permissions or scope */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
                 /** @description Not Found */
                 404: {
                     headers: {
@@ -5964,15 +6568,31 @@ interface paths$1 {
         };
         put?: never;
         post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v5/contracts/{contractAddress}/witnesses/intents/{intentId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
         /**
-         * DEV-ONLY: delete the caller's account (pre-launch reset)
-         * @description Hard-deletes the authenticated user + their organisation + contracts + delegated keys (Vault keys destroyed too) so signup can be re-run from scratch. Gated behind WITNIUM_PRE_LAUNCH — returns 403 otherwise. The on-chain contract is orphaned (immutable). This endpoint is removed before customer onboarding; do not build product UI on it.
+         * Recover a v5 witness intent's outcome
+         * @description For a client that lost a finalize (or propose) response. Returns the stored finalize response when accounts has one, otherwise chain-api's status for the intent. The URL contract must be the caller's. Read-only: never finalizes.
          */
-        delete: {
+        get: {
             parameters: {
                 query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    contractAddress: string;
+                    intentId: string;
+                };
                 cookie?: never;
             };
             requestBody?: never;
@@ -5984,26 +6604,54 @@ interface paths$1 {
                     };
                     content: {
                         "application/json": {
-                            /** @enum {boolean} */
-                            deleted: true;
+                            /** @enum {string} */
+                            source: "stored";
+                            intentId: string;
+                            registryVersion: number;
                             /**
-                             * @description UUID v4
-                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             * @description The caller's credit reservation for this intent: `held` (reserved, not finalized), `finalizing` (finalize forwarded, outcome pending), `committed` (charged), `released` / `expired` (refunded; nothing was charged).
+                             * @enum {string}
                              */
-                            userId: string;
+                            reservationState: "held" | "finalizing" | "committed" | "released" | "expired";
+                            /** @description The finalize response, exactly as first returned. */
+                            result: {
+                                [key: string]: unknown;
+                            };
+                        } | {
+                            /** @enum {string} */
+                            source: "chain";
+                            intentId: string;
+                            registryVersion: number;
                             /**
-                             * @description UUID v4
-                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             * @description The caller's credit reservation for this intent: `held` (reserved, not finalized), `finalizing` (finalize forwarded, outcome pending), `committed` (charged), `released` / `expired` (refunded; nothing was charged).
+                             * @enum {string|null}
                              */
-                            organizationId: string;
-                            /** @description How many OpenBao Transit keys were destroyed. */
-                            vaultKeysPurged: number;
-                            notice: string;
+                            reservationState: "held" | "finalizing" | "committed" | "released" | "expired" | null;
+                            /**
+                             * WitnessIntentChainStatus
+                             * @description chain-api's status for the intent, verbatim.
+                             */
+                            status: {
+                                intentId: string;
+                                contractAddress: string;
+                                registryVersion: number;
+                                /** @enum {string} */
+                                status: "prepared" | "allocated" | "submitted" | "confirmed" | "failed" | "cancelled" | "expired_unsubmitted" | "unknown";
+                                prepareTtlSeconds: number;
+                                /** @description Present when `confirmed`. */
+                                witnessId?: string;
+                                /** @description Present when `confirmed`. */
+                                transactionHash?: string;
+                                /** @description Present when `confirmed`. */
+                                blockNumber?: number;
+                                /** @description Present when `unknown`. */
+                                reason?: string;
+                            };
                         };
                     };
                 };
-                /** @description Unauthorized — authentication required or invalid */
-                401: {
+                /** @description Bad Request — validation failed */
+                400: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -6027,8 +6675,8 @@ interface paths$1 {
                         };
                     };
                 };
-                /** @description Forbidden — insufficient permissions or scope */
-                403: {
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -6052,76 +6700,730 @@ interface paths$1 {
                         };
                     };
                 };
-            };
-        };
-        options?: never;
-        head?: never;
-        patch?: never;
+                /** @description Forbidden — insufficient permissions or scope */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Not Found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/account/provisioning-token/reissue": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Re-mint a provisioning token (verified-but-not-provisioned recovery)
+         * @description Mints a fresh single-use provisioning token for a signed-in user whose email is verified but who has no contract yet — recovery for when the token from email-verify was lost (e.g. verify opened on another device). Returns 409 if email is unverified or a contract already exists. Rate limited per account.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            provisioningToken: string;
+                            /**
+                             * Format: date-time
+                             * @description ISO 8601 date-time string
+                             * @example 2026-05-20T10:30:00.000Z
+                             */
+                            expiresAt: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Conflict */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Too Many Requests */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/account": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read the authenticated user's account
+         * @description Returns the user profile, a summary of their organisation, and the list of signing keys (active + revoked).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** AccountUser */
+                            user: {
+                                /**
+                                 * @description UUID v4
+                                 * @example 550e8400-e29b-41d4-a716-446655440000
+                                 */
+                                id: string;
+                                /**
+                                 * Format: email
+                                 * @description RFC 5321 email address
+                                 * @example user@example.com
+                                 */
+                                email: string;
+                                /**
+                                 * Format: date-time
+                                 * @description ISO 8601 date-time string
+                                 * @example 2026-05-20T10:30:00.000Z
+                                 */
+                                emailVerifiedAt: string | null;
+                                /**
+                                 * @description Ethereum address (0x + 40 hex characters)
+                                 * @example 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0
+                                 */
+                                contractAddress: string | null;
+                                /**
+                                 * @description Ed25519 public key — 32 bytes hex-encoded (64 chars, no 0x prefix)
+                                 * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
+                                 */
+                                ownerPublicKey: string | null;
+                                /** @description Server-cached owner nonce (`ownerNonceCached`). */
+                                ownerNonce: number | null;
+                                externalUserId: string | null;
+                                /**
+                                 * Format: uri
+                                 * @description Webhook URL for chain-api to hit on witness settle (per-user).
+                                 */
+                                callbackUrl: string | null;
+                            };
+                            /** AccountOrgSummary */
+                            organization: {
+                                /**
+                                 * @description UUID v4
+                                 * @example 550e8400-e29b-41d4-a716-446655440000
+                                 */
+                                id: string;
+                                name: string;
+                                /**
+                                 * Format: email
+                                 * @description RFC 5321 email address
+                                 * @example user@example.com
+                                 */
+                                email: string;
+                                /**
+                                 * @description `metered` orgs pay per witness (credit ledger drives gating). `unlimited` orgs are flat-fee billed outside Stripe Checkout.
+                                 * @enum {string}
+                                 */
+                                accountType: "metered" | "unlimited";
+                                /**
+                                 * @description Subscription plan tier (drives the UI badge).
+                                 * @enum {string}
+                                 */
+                                plan: "free" | "starter" | "professional" | "business" | "enterprise";
+                                /**
+                                 * @description Stripe subscription state; `none` on the free tier.
+                                 * @enum {string}
+                                 */
+                                subscriptionStatus: "none" | "active" | "past_due" | "canceled";
+                                /** @description ISO end of the current paid period ("Renews on…"); null on free. */
+                                currentPeriodEnd: string | null;
+                                /** @description Cached credit balance; `null` for `unlimited` orgs. */
+                                balance: number | null;
+                                isPersonal: boolean;
+                            };
+                            signingKeys: {
+                                /**
+                                 * @description Ed25519 public key — 32 bytes hex-encoded (64 chars, no 0x prefix)
+                                 * @example 4cdde7a3e3a1d8a48d2b9eaf2bcbe2db1d57d3e1a8d6c20e0a86c0f9c4b6cf2e
+                                 */
+                                publicKey: string;
+                                label: string | null;
+                                /**
+                                 * Format: date-time
+                                 * @description ISO 8601 date-time string
+                                 * @example 2026-05-20T10:30:00.000Z
+                                 */
+                                addedAt: string;
+                                /**
+                                 * Format: date-time
+                                 * @description ISO 8601 date-time string
+                                 * @example 2026-05-20T10:30:00.000Z
+                                 */
+                                revokedAt: string | null;
+                                /** @description `true` iff `revokedAt` is null. Convenience for clients. */
+                                active: boolean;
+                            }[];
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Not Found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        /**
+         * DEV-ONLY: delete the caller's account (pre-launch reset)
+         * @description Hard-deletes the authenticated user + their organisation + contracts + delegated keys (Vault keys destroyed too) so signup can be re-run from scratch. Gated behind WITNIUM_PRE_LAUNCH — returns 403 otherwise. The on-chain contract is orphaned (immutable). This endpoint is removed before customer onboarding; do not build product UI on it.
+         */
+        delete: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @enum {boolean} */
+                            deleted: true;
+                            /**
+                             * @description UUID v4
+                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             */
+                            userId: string;
+                            /**
+                             * @description UUID v4
+                             * @example 550e8400-e29b-41d4-a716-446655440000
+                             */
+                            organizationId: string;
+                            /** @description True if the org was also deleted (personal org). False for a shared org, where only the caller was removed and the org left intact. */
+                            orgDeleted: boolean;
+                            /** @description How many OpenBao Transit keys were destroyed. */
+                            vaultKeysPurged: number;
+                            notice: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Forbidden — insufficient permissions or scope */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/account/ledger": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read the org's credit ledger
+         * @description Returns the most recent 200 ledger entries for the authenticated user's organisation. Use to render the credits/billing history view.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            entries: {
+                                /**
+                                 * @description UUID v4
+                                 * @example 550e8400-e29b-41d4-a716-446655440000
+                                 */
+                                id: string;
+                                /**
+                                 * @description UUID v4
+                                 * @example 550e8400-e29b-41d4-a716-446655440000
+                                 */
+                                organizationId: string;
+                                /**
+                                 * @description Set when the entry was caused by a user action; null for org-level grants.
+                                 * @example 550e8400-e29b-41d4-a716-446655440000
+                                 */
+                                userId: string | null;
+                                /** @description Positive = credits added, negative = credits consumed/released. */
+                                delta: number;
+                                /**
+                                 * LedgerReason
+                                 * @description Why a credit-ledger entry was written. Matches the pg enum on disk.
+                                 * @enum {string}
+                                 */
+                                reason: "signup_grant" | "purchase" | "subscription_grant" | "reservation_hold" | "reservation_commit" | "reservation_release" | "adjustment";
+                                /** @description External ref (e.g. Stripe session ID, witnessId). */
+                                ref: string | null;
+                                note: string | null;
+                                /**
+                                 * Format: date-time
+                                 * @description ISO 8601 date-time string
+                                 * @example 2026-05-20T10:30:00.000Z
+                                 */
+                                createdAt: string;
+                            }[];
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/oauth/sessions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the caller's active OAuth sessions
+         * @description Returns every non-revoked, non-expired access + refresh token belonging to the authenticated user. Drives the "active devices" view in the dashboard.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            sessions: {
+                                /** @description Opaque identifier of the token: the sha256 of its id, never the token itself. Use as the path param for DELETE. */
+                                jti: string;
+                                /** @enum {string} */
+                                kind: "AccessToken" | "RefreshToken";
+                                clientId: string;
+                                /** @description Human-readable client name from oauth_clients (falls back to clientId). */
+                                clientName: string;
+                                /** @description Space-separated OAuth scopes granted to this token. */
+                                scope: string;
+                                /** @description `resource` claim from RFC 8707 — `aud` of the access token. Typically `https://api.witniumchain.com` for the chain RS. */
+                                resource: string | null;
+                                /**
+                                 * Format: date-time
+                                 * @description ISO 8601 date-time string
+                                 * @example 2026-05-20T10:30:00.000Z
+                                 */
+                                issuedAt: string;
+                                /**
+                                 * Format: date-time
+                                 * @description ISO 8601 date-time string
+                                 * @example 2026-05-20T10:30:00.000Z
+                                 */
+                                expiresAt: string;
+                            }[];
+                        };
+                    };
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        /**
+         * Revoke all of the caller's OAuth sessions
+         * @description Cascades `revokeByGrantId` across every distinct grant the user holds, plus deletes any non-grant rows. Returns 204.
+         */
+        delete: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description No Content */
+                204: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Unauthorized — authentication required or invalid */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+            };
+        };
+        options?: never;
+        head?: never;
+        patch?: never;
         trace?: never;
     };
-    "/v1/account/ledger": {
+    "/v1/oauth/sessions/{jti}": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
+        post?: never;
         /**
-         * Read the org's credit ledger
-         * @description Returns the most recent 200 ledger entries for the authenticated user's organisation. Use to render the credits/billing history view.
+         * Revoke a single OAuth session
+         * @description Revokes one jti by walking up to its `grantId` and calling `provider.AccessToken.revokeByGrantId` — that cascades through the whole refresh-token rotation chain, not just this jti. Returns 204 whether the jti exists or not (to avoid leaking which jtis belong to which user).
          */
-        get: {
+        delete: {
             parameters: {
                 query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    jti: string;
+                };
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Success */
-                200: {
+                /** @description No Content */
+                204: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content: {
-                        "application/json": {
-                            entries: {
-                                /**
-                                 * @description UUID v4
-                                 * @example 550e8400-e29b-41d4-a716-446655440000
-                                 */
-                                id: string;
-                                /**
-                                 * @description UUID v4
-                                 * @example 550e8400-e29b-41d4-a716-446655440000
-                                 */
-                                organizationId: string;
-                                /**
-                                 * @description Set when the entry was caused by a user action; null for org-level grants.
-                                 * @example 550e8400-e29b-41d4-a716-446655440000
-                                 */
-                                userId: string | null;
-                                /** @description Positive = credits added, negative = credits consumed/released. */
-                                delta: number;
-                                /**
-                                 * LedgerReason
-                                 * @description Why a credit-ledger entry was written. Matches the pg enum on disk.
-                                 * @enum {string}
-                                 */
-                                reason: "signup_grant" | "purchase" | "subscription_grant" | "reservation_hold" | "reservation_commit" | "reservation_release" | "adjustment";
-                                /** @description External ref (e.g. Stripe session ID, witnessId). */
-                                ref: string | null;
-                                note: string | null;
-                                /**
-                                 * Format: date-time
-                                 * @description ISO 8601 date-time string
-                                 * @example 2026-05-20T10:30:00.000Z
-                                 */
-                                createdAt: string;
-                            }[];
-                        };
-                    };
+                    content?: never;
                 };
                 /** @description Unauthorized — authentication required or invalid */
                 401: {
@@ -6150,33 +7452,39 @@ interface paths$1 {
                 };
             };
         };
-        put?: never;
-        post?: never;
-        delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/v1/oauth/sessions": {
+    "/v1/oauth/introspect": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
+        get?: never;
+        put?: never;
         /**
-         * List the caller's active OAuth sessions
-         * @description Returns every non-revoked, non-expired access + refresh token belonging to the authenticated user. Drives the "active devices" view in the dashboard.
+         * Check whether an accounts-minted access token is still active
+         * @description For resource servers (MCP, chain API). Verifies the signature, then checks the security epoch, the grant or session the token came from, and the membership, uncached. Answers 200 `{active:false}` for any token that is not active. Callers MUST treat any non-200 answer or network failure as inactive. See docs/token-introspection.md.
          */
-        get: {
+        post: {
             parameters: {
                 query?: never;
                 header?: never;
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description The bearer JWT the caller received (an accounts-minted access token). */
+                        token: string;
+                    };
+                };
+            };
             responses: {
                 /** @description Success */
                 200: {
@@ -6185,36 +7493,42 @@ interface paths$1 {
                     };
                     content: {
                         "application/json": {
-                            sessions: {
-                                /** @description Token identifier (UUID-shaped in practice). Use as the path param for DELETE. */
-                                jti: string;
-                                /** @enum {string} */
-                                kind: "AccessToken" | "RefreshToken";
-                                clientId: string;
-                                /** @description Human-readable client name from oauth_clients (falls back to clientId). */
-                                clientName: string;
-                                /** @description Space-separated OAuth scopes granted to this token. */
-                                scope: string;
-                                /** @description `resource` claim from RFC 8707 — `aud` of the access token. Typically `https://api.witniumchain.com` for the chain RS. */
-                                resource: string | null;
-                                /**
-                                 * Format: date-time
-                                 * @description ISO 8601 date-time string
-                                 * @example 2026-05-20T10:30:00.000Z
-                                 */
-                                issuedAt: string;
-                                /**
-                                 * Format: date-time
-                                 * @description ISO 8601 date-time string
-                                 * @example 2026-05-20T10:30:00.000Z
-                                 */
-                                expiresAt: string;
-                            }[];
+                            /** @enum {boolean} */
+                            active: true;
+                            /**
+                             * @description `oauth`: issued by the OAuth flow from a grant. `session`: minted by POST /v1/auth/access-token.
+                             * @enum {string}
+                             */
+                            token_kind: "oauth" | "session";
+                            /** @description False when the membership in `org` is suspended: the caller MUST refuse writes. */
+                            writable: boolean;
+                            sub: string;
+                            client_id: string | null;
+                            scope: string;
+                            aud: string | string[] | unknown;
+                            iss: string;
+                            exp: number;
+                            iat: number;
+                            jti: string;
+                            /** @description Organization the token acts in; its membership is active. */
+                            org: string;
+                            /**
+                             * @description The CURRENT membership role in `org` (authoritative over the token's `role` claim).
+                             * @enum {string}
+                             */
+                            role: "org-admin" | "member";
+                            contracts: string[];
+                            sepoch: number;
+                            grant_id: string | null;
+                            session_id: string | null;
+                        } | {
+                            /** @enum {boolean} */
+                            active: false;
                         };
                     };
                 };
-                /** @description Unauthorized — authentication required or invalid */
-                401: {
+                /** @description Bad Request — validation failed */
+                400: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -6240,13 +7554,26 @@ interface paths$1 {
                 };
             };
         };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/account/mfa/totp/enroll": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
         put?: never;
-        post?: never;
         /**
-         * Revoke all of the caller's OAuth sessions
-         * @description Cascades `revokeByGrantId` across every distinct grant the user holds, plus deletes any non-grant rows. Returns 204.
+         * Start TOTP enrolment
+         * @description Generates a fresh TOTP secret + otpauth URL. The user scans the QR (rendered client-side from `otpauthUrl`) into their authenticator app and then calls `/v1/account/mfa/totp/confirm` with the first 6-digit code. The enrolment is NOT a usable second factor until confirmed.
          */
-        delete: {
+        post: {
             parameters: {
                 query?: never;
                 header?: never;
@@ -6255,12 +7582,50 @@ interface paths$1 {
             };
             requestBody?: never;
             responses: {
-                /** @description No Content */
-                204: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description Base32 TOTP secret. Show to the user as a typeable fallback alongside the QR code rendered from `otpauthUrl`.
+                             * @example JBSWY3DPEHPK3PXP
+                             */
+                            secret: string;
+                            /**
+                             * @description Standard `otpauth://totp/...` URL. The dashboard renders this as a QR code; the user scans it with an authenticator app.
+                             * @example otpauth://totp/WitniumChain:alice%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=WitniumChain&algorithm=SHA1&digits=6&period=30
+                             */
+                            otpauthUrl: string;
+                        };
+                    };
+                };
+                /** @description Bad Request — validation failed */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
                 };
                 /** @description Unauthorized — authentication required or invalid */
                 401: {
@@ -6289,12 +7654,13 @@ interface paths$1 {
                 };
             };
         };
+        delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/v1/oauth/sessions/{jti}": {
+    "/v1/account/mfa/totp/confirm": {
         parameters: {
             query?: never;
             header?: never;
@@ -6303,28 +7669,65 @@ interface paths$1 {
         };
         get?: never;
         put?: never;
-        post?: never;
         /**
-         * Revoke a single OAuth session
-         * @description Revokes one jti by walking up to its `grantId` and calling `provider.AccessToken.revokeByGrantId` — that cascades through the whole refresh-token rotation chain, not just this jti. Returns 204 whether the jti exists or not (to avoid leaking which jtis belong to which user).
+         * Confirm TOTP enrolment
+         * @description Validates the first user-supplied code against the secret minted by `/enroll`, marks the enrolment confirmed, and returns 10 single-use recovery codes. The recovery codes appear ONCE in this response and are never readable again — the dashboard must show them immediately and prompt the user to store them. Confirming bumps the user's security epoch: every OTHER session, session-minted access token and OAuth grant of the user ends; the calling session stays valid. Access tokens minted earlier from this session via `/v1/auth/access-token` stop working too and must be re-minted. 409 when the enrolment was restarted (`/enroll` called again) after this code was checked: scan the new QR code and confirm again. 429 when the per-user second-factor attempt budget is exhausted.
          */
-        delete: {
+        post: {
             parameters: {
                 query?: never;
                 header?: never;
-                path: {
-                    jti: string;
-                };
+                path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /**
+                         * @description Current 6-digit TOTP code shown by the authenticator app.
+                         * @example 123456
+                         */
+                        code: string;
+                    };
+                };
+            };
             responses: {
-                /** @description No Content */
-                204: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            /** @description Ten single-use recovery codes. Shown ONCE and never returned again — the user must store them now. Each code is consumed atomically when used in place of a TOTP code at MFA challenge time. */
+                            recoveryCodes: string[];
+                        };
+                    };
+                };
+                /** @description Bad Request — validation failed */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
                 };
                 /** @description Unauthorized — authentication required or invalid */
                 401: {
@@ -6351,57 +7754,8 @@ interface paths$1 {
                         };
                     };
                 };
-            };
-        };
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/v1/account/mfa/totp/enroll": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Start TOTP enrolment
-         * @description Generates a fresh TOTP secret + otpauth URL. The user scans the QR (rendered client-side from `otpauthUrl`) into their authenticator app and then calls `/v1/account/mfa/totp/confirm` with the first 6-digit code. The enrolment is NOT a usable second factor until confirmed.
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Success */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /**
-                             * @description Base32 TOTP secret. Show to the user as a typeable fallback alongside the QR code rendered from `otpauthUrl`.
-                             * @example JBSWY3DPEHPK3PXP
-                             */
-                            secret: string;
-                            /**
-                             * @description Standard `otpauth://totp/...` URL. The dashboard renders this as a QR code; the user scans it with an authenticator app.
-                             * @example otpauth://totp/WitniumChain:alice%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=WitniumChain&algorithm=SHA1&digits=6&period=30
-                             */
-                            otpauthUrl: string;
-                        };
-                    };
-                };
-                /** @description Bad Request — validation failed */
-                400: {
+                /** @description Conflict */
+                409: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -6425,8 +7779,8 @@ interface paths$1 {
                         };
                     };
                 };
-                /** @description Unauthorized — authentication required or invalid */
-                401: {
+                /** @description Too Many Requests */
+                429: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -6458,7 +7812,7 @@ interface paths$1 {
         patch?: never;
         trace?: never;
     };
-    "/v1/account/mfa/totp/confirm": {
+    "/v1/account/mfa/totp": {
         parameters: {
             query?: never;
             header?: never;
@@ -6467,11 +7821,12 @@ interface paths$1 {
         };
         get?: never;
         put?: never;
+        post?: never;
         /**
-         * Confirm TOTP enrolment
-         * @description Validates the first user-supplied code against the secret minted by `/enroll`, marks the enrolment confirmed, and returns 10 single-use recovery codes. The recovery codes appear ONCE in this response and are never readable again — the dashboard must show them immediately and prompt the user to store them.
+         * Disable TOTP and clear recovery codes
+         * @description Wipes the TOTP secret and all recovery codes. The user re-enrolls from scratch with `/enroll`. Step-up: the JSON body must carry a fresh second factor (`code` or `recoveryCode`); 403 `mfa_step_up_failed` when it is wrong or already used, 429 when the attempt budget is exhausted.
          */
-        post: {
+        delete: {
             parameters: {
                 query?: never;
                 header?: never;
@@ -6482,10 +7837,15 @@ interface paths$1 {
                 content: {
                     "application/json": {
                         /**
-                         * @description Current 6-digit TOTP code shown by the authenticator app.
+                         * @description Current 6-digit TOTP code. Each code is accepted once.
                          * @example 123456
                          */
-                        code: string;
+                        code?: string;
+                        /**
+                         * @description An unused recovery code (consumed by this request).
+                         * @example ABCD-EFGH
+                         */
+                        recoveryCode?: string;
                     };
                 };
             };
@@ -6497,8 +7857,8 @@ interface paths$1 {
                     };
                     content: {
                         "application/json": {
-                            /** @description Ten single-use recovery codes. Shown ONCE and never returned again — the user must store them now. Each code is consumed atomically when used in place of a TOTP code at MFA challenge time. */
-                            recoveryCodes: string[];
+                            /** @enum {boolean} */
+                            disabled: true;
                         };
                     };
                 };
@@ -6552,51 +7912,33 @@ interface paths$1 {
                         };
                     };
                 };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/v1/account/mfa/totp": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        post?: never;
-        /**
-         * Disable TOTP and clear recovery codes
-         * @description Wipes the TOTP secret and all recovery codes. The user re-enrolls from scratch with `/enroll`. Future versions of this endpoint will require a recent MFA assertion (step-up) — Thread E of Phase AUTH.
-         */
-        delete: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Success */
-                200: {
+                /** @description Forbidden — insufficient permissions or scope */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
                         "application/json": {
-                            /** @enum {boolean} */
-                            disabled: true;
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
                         };
                     };
                 };
-                /** @description Unauthorized — authentication required or invalid */
-                401: {
+                /** @description Too Many Requests */
+                429: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -6638,7 +7980,7 @@ interface paths$1 {
         put?: never;
         /**
          * Generate a fresh set of recovery codes
-         * @description Invalidates the prior set and issues 10 new codes. Future versions will require step-up auth.
+         * @description Invalidates the prior set and issues 10 new codes. Step-up: the JSON body must carry a fresh second factor (`code` or `recoveryCode`); 403 `mfa_step_up_failed` when it is wrong or already used, 429 when the attempt budget is exhausted.
          */
         post: {
             parameters: {
@@ -6647,10 +7989,25 @@ interface paths$1 {
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /**
+                         * @description Current 6-digit TOTP code. Each code is accepted once.
+                         * @example 123456
+                         */
+                        code?: string;
+                        /**
+                         * @description An unused recovery code (consumed by this request).
+                         * @example ABCD-EFGH
+                         */
+                        recoveryCode?: string;
+                    };
+                };
+            };
             responses: {
-                /** @description Success */
-                200: {
+                /** @description Created */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -6711,6 +8068,56 @@ interface paths$1 {
                         };
                     };
                 };
+                /** @description Forbidden — insufficient permissions or scope */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
+                /** @description Too Many Requests */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description HTTP status code
+                             * @example 400
+                             */
+                            statusCode?: number;
+                            /**
+                             * @description Short error label
+                             * @example Bad Request
+                             */
+                            error?: string;
+                            /**
+                             * @description Human-readable error message. Validation errors from `ZodError.flatten()` may be returned as an array.
+                             * @example Validation failed
+                             */
+                            message: string | string[];
+                        };
+                    };
+                };
             };
         };
         delete?: never;
@@ -7238,12 +8645,6 @@ interface paths {
                          * @description AGE-armored tlock ciphertext, hex-encoded UTF-8. Output of tlock-js `timelockEncrypt`. Max 4096 bytes (8192 hex chars).
                          */
                         tlockCiphertext?: string;
-                        /**
-                         * Format: uri
-                         * @description Valid URL
-                         * @example https://example.com/path
-                         */
-                        callbackUrl?: string;
                     };
                 };
             };
@@ -8494,14 +9895,20 @@ interface paths {
         };
         /**
          * List v5 witnesses (optionally filtered by dataId)
-         * @description Scans the WitnessCreated event log from contract deployment to head. The v5 event adds drandRound — non-zero means the witness carries a drand IBE ciphertext decryptable at that round. Query the full witness via /get for the ciphertext bytes.
+         * @description Lists WitnessCreated events, newest first. The v5 event adds drandRound — non-zero means the witness carries a drand IBE ciphertext decryptable at that round. Query the full witness via /get for the ciphertext bytes. Each request scans one window of at most 200,000 blocks of the WitnessCreated event log, newest first: from `beforeBlock - 1` (or the head) down, never below the deploy block. To list everything, repeat the request with `beforeBlock = nextBeforeBlock`, `beforeLogIndex = nextBeforeLogIndex` (omitted when null) and no `offset`, until `nextBeforeBlock` is null; every matching witness is returned exactly once, newest first. A page can be empty while older witnesses exist; only a null `nextBeforeBlock` means the listing is exhausted. `hasMore` reports more matches inside the current window.
          */
         get: {
             parameters: {
                 query?: {
                     dataId?: string;
+                    /** @description Page size, 1-200, default 50. */
                     limit?: number;
+                    /** @description Offset into the matches of this scan window, 0-10000. */
                     offset?: number | null;
+                    /** @description Exclusive upper bound of the scan: blocks below it are scanned. Omit for the head; to continue, pass the previous response's `nextBeforeBlock`. At most the current head + 1. */
+                    beforeBlock?: number | null;
+                    /** @description Requires `beforeBlock`. Within block `beforeBlock - 1`, only logs with a lower log index are listed. Pass the previous response's `nextBeforeLogIndex` when it is not null. */
+                    beforeLogIndex?: number | null;
                 };
                 header?: never;
                 path: {
@@ -8536,6 +9943,12 @@ interface paths {
                             }[];
                             hasMore: boolean;
                             totalReturned: number;
+                            /** @description True when this request's scan window reached the contract's deploy block. */
+                            scanComplete: boolean;
+                            /** @description The `beforeBlock` of the next page. Null when every matching witness has been listed. */
+                            nextBeforeBlock: number | null;
+                            /** @description The `beforeLogIndex` of the next page, or null to start at the top of block `nextBeforeBlock - 1`. */
+                            nextBeforeLogIndex: number | null;
                         };
                     };
                 };
@@ -9004,6 +10417,8 @@ interface paths {
          *
          *     Response shape is identical to GET /v5/contracts/{addr}/witnesses; the
          *     scan is always newest-first.
+         *
+         *     Each request scans one window of at most 200,000 blocks of the WitnessCreated event log, newest first: from `beforeBlock - 1` (or the head) down, never below the deploy block. To list everything, repeat the request with `beforeBlock = nextBeforeBlock`, `beforeLogIndex = nextBeforeLogIndex` (omitted when null) and no `offset`, until `nextBeforeBlock` is null; every matching witness is returned exactly once, newest first. A page can be empty while older witnesses exist; only a null `nextBeforeBlock` means the listing is exhausted. `hasMore` reports more matches inside the current window.
          */
         get: {
             parameters: {
@@ -9016,8 +10431,12 @@ interface paths {
                     timeLock?: "locked" | "none" | "any";
                     /** @description Page size, 1-200, default 50. */
                     limit?: number;
-                    /** @description Offset into the filtered set, default 0. */
+                    /** @description Offset into the matches of this scan window, 0-10000. */
                     offset?: number | null;
+                    /** @description Exclusive upper bound of the scan: blocks below it are scanned. Omit for the head; to continue, pass the previous response's `nextBeforeBlock`. At most the current head + 1. */
+                    beforeBlock?: number | null;
+                    /** @description Requires `beforeBlock`. Within block `beforeBlock - 1`, only logs with a lower log index are listed. Pass the previous response's `nextBeforeLogIndex` when it is not null. */
+                    beforeLogIndex?: number | null;
                 };
                 header?: never;
                 path?: never;
@@ -9049,6 +10468,12 @@ interface paths {
                             }[];
                             hasMore: boolean;
                             totalReturned: number;
+                            /** @description True when this request's scan window reached the contract's deploy block. */
+                            scanComplete: boolean;
+                            /** @description The `beforeBlock` of the next page. Null when every matching witness has been listed. */
+                            nextBeforeBlock: number | null;
+                            /** @description The `beforeLogIndex` of the next page, or null to start at the top of block `nextBeforeBlock - 1`. */
+                            nextBeforeLogIndex: number | null;
                         };
                     };
                 };
@@ -10062,7 +11487,7 @@ interface paths {
         };
         /**
          * Liveness probe
-         * @description Kubernetes liveness probe. Fails if queue connection lost for > 1 minute.
+         * @description Kubernetes liveness probe. Answers 200 while the process serves HTTP; it checks no dependency (dependency health is the readiness probe).
          */
         get: {
             parameters: {
@@ -10081,41 +11506,7 @@ interface paths {
                     content: {
                         "application/json": {
                             /** @enum {string} */
-                            status: "healthy";
-                            /**
-                             * QueueStatus
-                             * @description Queue health status
-                             */
-                            queue: {
-                                healthy: boolean;
-                                timeSinceLastPingMs: number;
-                                /** Format: date-time */
-                                lastPing?: string;
-                            };
-                        };
-                    };
-                };
-                /** @description Service Unavailable */
-                503: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /**
-                             * @description Error message
-                             * @example Validation failed
-                             */
-                            error: string;
-                            /**
-                             * @description Machine-readable error code
-                             * @example VALIDATION_FAILED
-                             */
-                            code?: string;
-                            /** @description Field-level validation errors */
-                            details?: {
-                                [key: string]: string[];
-                            };
+                            status: "alive";
                         };
                     };
                 };
@@ -10329,11 +11720,15 @@ type JsonBody<T> = T extends {
 type Req<P extends keyof paths$1, M extends keyof paths$1[P]> = JsonBody<Extract<paths$1[P][M], {
     requestBody?: unknown;
 }>['requestBody']>;
-type Res<P extends keyof paths$1, M extends keyof paths$1[P], S extends number = 200> = paths$1[P][M] extends {
-    responses: {
-        [K in S]: infer R;
-    };
-} ? JsonBody<R> : never;
+/** HTTP success codes an operation's response body is taken from. */
+type SuccessCode = 200 | 201 | 202 | 203;
+/**
+ * The JSON body of an accounts operation's success response, whichever 2xx
+ * code the spec documents (accounts answers POSTs with 201).
+ */
+type Res<P extends keyof paths$1, M extends keyof paths$1[P]> = paths$1[P][M] extends {
+    responses: infer R;
+} ? JsonBody<R[Extract<keyof R, SuccessCode>]> : never;
 type ChainRes<P extends keyof paths, M extends keyof paths[P], S extends number = 200> = paths[P][M] extends {
     responses: {
         [K in S]: infer R;
@@ -10344,6 +11739,7 @@ type SignupResponse = Res<'/v1/auth/signup', 'post'>;
 type VerifyEmailResponse = Res<'/v1/auth/verify', 'get'>;
 type LoginRequest = Req<'/v1/auth/login', 'post'>;
 type LoginResponse = Res<'/v1/auth/login', 'post'>;
+type LoginMfaResponse = Res<'/v1/auth/login/mfa', 'post'>;
 type LogoutResponse = Res<'/v1/auth/logout', 'post'>;
 type ForgotPasswordRequest = Req<'/v1/auth/forgot-password', 'post'>;
 type ForgotPasswordResponse = Res<'/v1/auth/forgot-password', 'post'>;
@@ -10406,6 +11802,18 @@ type LedgerResponse = Res<'/v1/account/ledger', 'get'>;
 type TotpEnrollResponse = Res<'/v1/account/mfa/totp/enroll', 'post'>;
 type TotpConfirmRequest = Req<'/v1/account/mfa/totp/confirm', 'post'>;
 type TotpConfirmResponse = Res<'/v1/account/mfa/totp/confirm', 'post'>;
+/**
+ * A second-factor proof: exactly one of a 6-digit TOTP `code` or a
+ * `recoveryCode` (`ABCD-EFGH`). The spec types both as optional; the server
+ * rejects a body with neither or both, so the SDK type enforces exactly one.
+ */
+type MfaProofRequest = {
+    code: string;
+    recoveryCode?: never;
+} | {
+    recoveryCode: string;
+    code?: never;
+};
 type TotpDisableResponse = Res<'/v1/account/mfa/totp', 'delete'>;
 type RecoveryCodesRegenerateResponse = Res<'/v1/account/mfa/recovery-codes/regenerate', 'post'>;
 type ListOauthSessionsResponse = Res<'/v1/oauth/sessions', 'get'>;
@@ -10667,9 +12075,10 @@ declare class WitniumchainClient {
      * the contract with the caller's client-generated `ownerPublicKey` +
      * `initialSigningPublicKey`. Witnium never sees the private bytes.
      *
-     * Returns `{ orgId, userId, contractAddress, contractVersion,
-     * emailVerifyToken }`. The verify token is also emailed; it's echoed here
-     * for UIs that prefer to render the verify link themselves.
+     * Returns `{ orgId, userId, contractAddress, contractVersion }`. The
+     * email-verify link is mailed to `adminEmail` and never returned, so there
+     * is nothing to render. If the mail cannot be sent, nothing is created and
+     * the call fails with a 502; retry it.
      */
     createOrg(body: CreateOrgRequest): Promise<CreateOrgResponse>;
     listMembers(): Promise<MembersListResponse>;
@@ -10682,7 +12091,26 @@ declare class WitniumchainClient {
     removeMember(userId: string): Promise<RemoveMemberResponse>;
     resendMemberInvite(userId: string): Promise<ResendInviteResponse>;
     verifyEmail(token: string): Promise<VerifyEmailResponse>;
+    /**
+     * Password login. Check `status`: `'authenticated'` means the session
+     * cookie is set. `'mfa_required'` means NO session exists yet: the server
+     * set a short-lived challenge cookie, and {@link loginMfa} must follow with
+     * the user's TOTP or recovery code.
+     */
     login(body: LoginRequest): Promise<LoginResponse>;
+    /**
+     * Second step of an MFA login, after `login()` returned `'mfa_required'`.
+     * Relies on the challenge cookie from that call (`credentials: 'include'`).
+     * 401 `mfa_code_invalid`: wrong or reused code, the user may retry.
+     * 401 `mfa_challenge_invalid`: expired or used up, start again at `login()`.
+     * 429 `mfa_rate_limited`: the body carries `retryAfterSeconds`.
+     */
+    loginMfa(body: MfaProofRequest): Promise<LoginMfaResponse>;
+    /**
+     * End the first-party session. The cached bearer token is dropped even when
+     * the request fails, so a logged-out tab never keeps the previous user's
+     * token.
+     */
     logout(): Promise<LogoutResponse>;
     forgotPassword(body: ForgotPasswordRequest): Promise<ForgotPasswordResponse>;
     resetPassword(body: ResetPasswordRequest): Promise<ResetPasswordResponse>;
@@ -10731,9 +12159,16 @@ declare class WitniumchainClient {
      */
     reissueProvisioningToken(): Promise<ReissueProvisioningTokenResponse>;
     enrollTotp(): Promise<TotpEnrollResponse>;
+    /**
+     * Confirming bumps the user's security epoch server-side, which ends every
+     * session-minted access token. A cached one is dropped so the next bearer
+     * call mints a fresh token.
+     */
     confirmTotp(body: TotpConfirmRequest): Promise<TotpConfirmResponse>;
-    disableTotp(): Promise<TotpDisableResponse>;
-    regenerateRecoveryCodes(): Promise<RecoveryCodesRegenerateResponse>;
+    /** Step-up: 403 `mfa_step_up_failed` on a wrong proof, 429 `mfa_rate_limited`. */
+    disableTotp(body: MfaProofRequest): Promise<TotpDisableResponse>;
+    /** Step-up: 403 `mfa_step_up_failed` on a wrong proof, 429 `mfa_rate_limited`. */
+    regenerateRecoveryCodes(body: MfaProofRequest): Promise<RecoveryCodesRegenerateResponse>;
     listOauthSessions(): Promise<ListOauthSessionsResponse>;
     revokeOauthSession(jti: string): Promise<void>;
     revokeAllOauthSessions(): Promise<void>;
@@ -10741,10 +12176,19 @@ declare class WitniumchainClient {
     healthReady(): Promise<HealthReadyResponse>;
     getContractInfo(contractAddress: string): Promise<ContractInfoResponse>;
     getContractVerification(contractAddress: string): Promise<VerifyContractResponse>;
-    listWitnessesV5(contractAddress: string, params?: {
+    listWitnessesV5(contractAddress: string, 
+    /**
+     * One bounded scan window per call. To list everything, call again with
+     * `beforeBlock: res.nextBeforeBlock` and, when not null,
+     * `beforeLogIndex: res.nextBeforeLogIndex` until `res.nextBeforeBlock`
+     * is null; an empty page does not mean the end.
+     */
+    params?: {
         dataId?: string;
         limit?: number;
         offset?: number;
+        beforeBlock?: number;
+        beforeLogIndex?: number;
     }): Promise<ListWitnessesResponse>;
     getWitnessV5(contractAddress: string, witnessId: string): Promise<GetChainWitnessResponse>;
     getContractTransaction(contractAddress: string, txHash: string): Promise<GetContractTransactionResponse>;
@@ -10757,6 +12201,9 @@ declare class WitniumchainClient {
         timeLock?: 'locked' | 'none';
         limit?: number;
         offset?: number;
+        /** Cursor; see listWitnessesV5. */
+        beforeBlock?: number;
+        beforeLogIndex?: number;
     }): Promise<DashboardWitnessesResponse>;
     /**
      * Build the authorization-server URL for the start of an OAuth login flow.
@@ -11014,7 +12461,12 @@ declare class OrgMembers {
     constructor(client: WitniumchainClient);
     /** List the caller's org members (role, suspendedAt, isOwner, keys). */
     list(): Promise<MembersListResponse>;
-    /** Invite a member by email (default role `member`). */
+    /**
+     * Invite a member by email (default role `member`). `inviteEmailSent` says
+     * whether the invitation (with the verify link) was mailed; the token is
+     * never returned. A 502 means the membership was recorded but the mail
+     * failed; retry.
+     */
     invite(body: InviteMemberRequest): Promise<InviteMemberResponse>;
     /** Suspend a member (reversible). The owner cannot be suspended. */
     suspend(userId: string): Promise<SuspendMemberResponse>;
@@ -11026,7 +12478,10 @@ declare class OrgMembers {
     setRole(userId: string, role: SetMemberRoleRequest['role']): Promise<SetMemberRoleResponse>;
     /** Remove a member (terminal; revokes their delegated keys). Owner protected. */
     remove(userId: string): Promise<RemoveMemberResponse>;
-    /** Re-mint an email-verify token for a pending member. */
+    /**
+     * Re-send the invitation email to a pending member. Returns `{ email }`;
+     * the fresh verify token is mailed, never returned.
+     */
     resendInvite(userId: string): Promise<ResendInviteResponse>;
 }
 declare class MfaTotp {
@@ -11044,11 +12499,15 @@ declare class MfaTotp {
      * Confirm enrolment with the first user-supplied code. Returns the 10
      * single-use recovery codes — show them to the user ONCE; the server never
      * returns them again. Throws `WitniumchainApiError` with status 400 when
-     * the code is invalid or the enrolment is already confirmed.
+     * the code is invalid or the enrolment is already confirmed. Signs the
+     * user out of every other device and connected app.
      */
     confirm(code: string): Promise<TotpConfirmResponse>;
-    /** Disable TOTP, wiping both the secret and all recovery codes. */
-    disable(): Promise<TotpDisableResponse>;
+    /**
+     * Disable TOTP, wiping both the secret and all recovery codes. Requires the
+     * user's current code or a recovery code.
+     */
+    disable(proof: MfaProofRequest): Promise<TotpDisableResponse>;
 }
 declare class MfaRecoveryCodes {
     private readonly client;
@@ -11056,8 +12515,9 @@ declare class MfaRecoveryCodes {
     /**
      * Issue a fresh set of 10 recovery codes, invalidating the prior ones.
      * Same as `confirm` — codes are returned ONCE and never readable again.
+     * Requires the user's current code or a recovery code.
      */
-    regenerate(): Promise<RecoveryCodesRegenerateResponse>;
+    regenerate(proof: MfaProofRequest): Promise<RecoveryCodesRegenerateResponse>;
 }
 
 type Body<T> = T extends {
@@ -11250,4 +12710,4 @@ declare function buildRevokeSigningKeyPayload(args: {
     key: string;
 }): string;
 
-export { type AccountResponse, type paths$1 as AccountsPaths, type AddSigningKeyRequest$1 as AddSigningKeyRequest, type AddSigningKeyResponse, type BeginOAuthLoginArgs, type BeginOAuthLoginResult, type paths as ChainPaths, type CheckoutRequest, type CheckoutResponse, type CreateOrgRequest, type CreateOrgResponse, type CreateUserRequest, type CreateUserResponse, DelegatedKeys, type FinalizeWitnessResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetWitnessResponse, type HealthLiveResponse, type HealthReadyResponse, type InviteMemberRequest, type InviteMemberResponse, type LedgerResponse, type ListDelegatedKeysResponse, type ListOauthSessionsResponse, type ListUsersResponse, type LoginRequest, type LoginResponse, type LogoutResponse, type MembersListResponse, MfaNamespace, MfaRecoveryCodes, MfaTotp, type OAuthTokenSnapshot, OWNER_OP, OauthNamespace, OauthSessions, OrgMembers, OrgUsers, type OwnerOpName, type OwnerSigner, type PauseRequest$1 as PauseRequest, type PauseResponse, type PkceVerifierStorage, type PortalResponse, type PrepareDelegatedKeyRequest, type PreparedDelegatedKeyResponse, type ProposeWitnessRequest, type ProposeWitnessResponse, type ProvisionContractRequest, type ProvisionContractResponse, type ProvisionDelegatedKeyArgs, type ProvisionDelegatedKeyResult, type PublicOrgResponse, type RecoveryCodesRegenerateResponse, type ReissueProvisioningTokenResponse, type RemoveMemberResponse, type ResendInviteResponse, type ResetAccountResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDelegatedKeyResponse, type RevokeSigningKeyRequest$1 as RevokeSigningKeyRequest, type RevokeSigningKeyResponse, type RevokeWitnessRequest, type RevokeWitnessResponse, type SetMemberRoleRequest, type SetMemberRoleResponse, type SignRequest, type SignResponse, type SignWitnessRequest, type SignWitnessResponse, type SignedRequestSigner, SigningKeys, type SignupRequest, type SignupResponse, type SubmitDelegatedKeyRequest, type SubmitDelegatedKeyResponse, Subscriptions, type SuspendMemberResponse, type TotpConfirmRequest, type TotpConfirmResponse, type TotpDisableResponse, type TotpEnrollResponse, type UnpauseRequest, type UnpauseResponse, type VerifyEmailResponse, WitniumchainApiError, WitniumchainChainAdminClient, type WitniumchainChainAdminClientConfig, WitniumchainClient, type WitniumchainClientConfig, WitniumchainOrgClient, type WitniumchainOrgClientConfig, buildAddSigningKeyPayload, buildPausePayload, buildRevokeSigningKeyPayload, buildUnpausePayload, defaultVerifierStorage };
+export { type AccountResponse, type paths$1 as AccountsPaths, type AddSigningKeyRequest$1 as AddSigningKeyRequest, type AddSigningKeyResponse, type BeginOAuthLoginArgs, type BeginOAuthLoginResult, type paths as ChainPaths, type CheckoutRequest, type CheckoutResponse, type CreateOrgRequest, type CreateOrgResponse, type CreateUserRequest, type CreateUserResponse, DelegatedKeys, type FinalizeWitnessResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetWitnessResponse, type HealthLiveResponse, type HealthReadyResponse, type InviteMemberRequest, type InviteMemberResponse, type LedgerResponse, type ListDelegatedKeysResponse, type ListOauthSessionsResponse, type ListUsersResponse, type LoginMfaResponse, type LoginRequest, type LoginResponse, type LogoutResponse, type MembersListResponse, MfaNamespace, type MfaProofRequest, MfaRecoveryCodes, MfaTotp, type OAuthTokenSnapshot, OWNER_OP, OauthNamespace, OauthSessions, OrgMembers, OrgUsers, type OwnerOpName, type OwnerSigner, type PauseRequest$1 as PauseRequest, type PauseResponse, type PkceVerifierStorage, type PortalResponse, type PrepareDelegatedKeyRequest, type PreparedDelegatedKeyResponse, type ProposeWitnessRequest, type ProposeWitnessResponse, type ProvisionContractRequest, type ProvisionContractResponse, type ProvisionDelegatedKeyArgs, type ProvisionDelegatedKeyResult, type PublicOrgResponse, type RecoveryCodesRegenerateResponse, type ReissueProvisioningTokenResponse, type RemoveMemberResponse, type ResendInviteResponse, type ResetAccountResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDelegatedKeyResponse, type RevokeSigningKeyRequest$1 as RevokeSigningKeyRequest, type RevokeSigningKeyResponse, type RevokeWitnessRequest, type RevokeWitnessResponse, type SetMemberRoleRequest, type SetMemberRoleResponse, type SignRequest, type SignResponse, type SignWitnessRequest, type SignWitnessResponse, type SignedRequestSigner, SigningKeys, type SignupRequest, type SignupResponse, type SubmitDelegatedKeyRequest, type SubmitDelegatedKeyResponse, Subscriptions, type SuspendMemberResponse, type TotpConfirmRequest, type TotpConfirmResponse, type TotpDisableResponse, type TotpEnrollResponse, type UnpauseRequest, type UnpauseResponse, type VerifyEmailResponse, WitniumchainApiError, WitniumchainChainAdminClient, type WitniumchainChainAdminClientConfig, WitniumchainClient, type WitniumchainClientConfig, WitniumchainOrgClient, type WitniumchainOrgClientConfig, buildAddSigningKeyPayload, buildPausePayload, buildRevokeSigningKeyPayload, buildUnpausePayload, defaultVerifierStorage };