@witnium-tech/witniumchain 0.3.0 → 0.5.0

package/dist/index.js

@@ -14,12 +14,103 @@ var WitniumchainApiError = class extends Error {
   }
 };
 
+// src/pkce.ts
+var STORAGE_PREFIX = "witniumchain.pkce.";
+function defaultVerifierStorage() {
+  const storage = globalThis.sessionStorage;
+  if (!storage) {
+    throw new Error(
+      "WitniumchainClient: defaultVerifierStorage requires globalThis.sessionStorage. In a non-browser context, pass `verifierStorage` to the OAuth helpers."
+    );
+  }
+  return {
+    set(stateKey, verifier) {
+      storage.setItem(STORAGE_PREFIX + stateKey, verifier);
+    },
+    get(stateKey) {
+      return storage.getItem(STORAGE_PREFIX + stateKey);
+    },
+    remove(stateKey) {
+      storage.removeItem(STORAGE_PREFIX + stateKey);
+    }
+  };
+}
+function generateCodeVerifier() {
+  const bytes = new Uint8Array(64);
+  cryptoRef().getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function deriveCodeChallenge(verifier) {
+  const data = new TextEncoder().encode(verifier);
+  const digest = await cryptoRef().subtle.digest("SHA-256", data);
+  return base64UrlEncode(new Uint8Array(digest));
+}
+function generateState() {
+  const bytes = new Uint8Array(32);
+  cryptoRef().getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+function base64UrlEncode(bytes) {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  const b64 = typeof btoa === "function" ? btoa(binary) : Buffer.from(binary, "binary").toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function cryptoRef() {
+  const c = globalThis.crypto;
+  if (!c || !c.subtle || !c.getRandomValues) {
+    throw new Error(
+      "WitniumchainClient: globalThis.crypto with subtle + getRandomValues is required for PKCE. Modern browsers and Node 18+ provide this natively."
+    );
+  }
+  return c;
+}
+
 // src/client.ts
 var WitniumchainClient = class {
   baseUrl;
+  chainBaseUrl;
   cfg;
   timeout;
   fetchImpl;
+  // Mutable OAuth state. Constructor seeds these from the config; the OAuth
+  // flow helpers (begin/complete/refresh/signOut) read and rewrite them as
+  // the user authenticates and tokens rotate. `applyAuth` reads `accessToken`
+  // off this field — never directly off `cfg` — so a token rotated mid-flight
+  // (during a 401-retry refresh) is picked up by the very next call.
+  accessToken;
+  // Browser SPAs in production receive the refresh token as an HttpOnly cookie
+  // (see src/oauth/refresh-cookie.ts on the server), so this field stays
+  // `undefined` and the cookie rides via `credentials: 'include'` on every
+  // /token call. Non-browser callers (Node SSR, native apps without a cookie
+  // jar) get the refresh token in the response body and the SDK stashes it
+  // here as a fallback. Either path drives `refreshAccessToken` identically.
+  refreshToken;
+  // Sentinel: the most recent token response set an HttpOnly refresh cookie.
+  // The SDK can't directly observe an HttpOnly cookie, but the response body
+  // tells us indirectly — server strips `refresh_token` when it sets the
+  // cookie, so an absent body field on a successful /token response means
+  // the cookie path is in use. Used to gate the 401-retry: with a cookie,
+  // refresh might work even when the in-memory refresh token is undefined.
+  hasRefreshCookie = false;
+  oauthClientId;
+  // The redirect URI the most recent `beginOAuthLogin` issued, alongside the
+  // PKCE verifier. `completeOAuthLogin` reads it back so the token-exchange
+  // request matches the original /auth request (RFC 6749 §4.1.3 requires
+  // redirect_uri at /token to equal the one at /auth). Keyed by state.
+  pendingLogins = /* @__PURE__ */ new Map();
+  verifierStorage;
+  // Cache of the parsed OIDC discovery document keyed by issuer URL. Saves a
+  // round trip on every OAuth call after the first. oidc-provider's discovery
+  // doc is static for the life of an issuer; cache is per-client-instance, so
+  // it dies with the SDK consumer's lifecycle.
+  discoveryCache;
+  // Single-flight gate for refresh. When a 401 fans out to N concurrent retries
+  // (or the consumer calls refreshAccessToken directly while another refresh
+  // is mid-flight), all callers await the same in-flight promise — refresh
+  // tokens rotate on use (D10), so a second concurrent refresh would race the
+  // first and one of them would 401.
+  refreshInFlight;
   /** Subscriptions / billing helpers. See {@link Subscriptions}. */
   subscriptions;
   /** Delegated-key namespace including the one-call {@link DelegatedKeys.provision} flow. */
@@ -28,12 +119,15 @@ var WitniumchainClient = class {
   keys;
   /** OAuth session management. Accessed as `client.oauth.sessions.*`. */
   oauth;
+  /** MFA self-management. Accessed as `client.mfa.totp.*` and `client.mfa.recoveryCodes.*`. */
+  mfa;
   constructor(config) {
     if (!config.baseUrl) {
       throw new Error("WitniumchainClient: baseUrl is required");
     }
     this.cfg = config;
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.chainBaseUrl = config.chainBaseUrl?.replace(/\/$/, "");
     this.timeout = config.timeout ?? 3e4;
     this.fetchImpl = config.fetch ?? globalThis.fetch;
     if (!this.fetchImpl) {
@@ -41,10 +135,14 @@ var WitniumchainClient = class {
         "WitniumchainClient: no fetch implementation available. Pass `config.fetch`."
       );
     }
+    this.accessToken = config.accessToken;
+    this.oauthClientId = config.oauthClientId;
+    this.verifierStorage = config.verifierStorage;
     this.subscriptions = new Subscriptions(this);
     this.delegatedKeys = new DelegatedKeys(this);
     this.keys = new SigningKeys(this);
     this.oauth = new OauthNamespace(this);
+    this.mfa = new MfaNamespace(this);
   }
   /**
    * Convenience alias for {@link getAccount} — returns the authenticated
@@ -212,8 +310,8 @@ var WitniumchainClient = class {
   // ────────────────────────────────────────────────────────────────────────
   // Witnesses (/v1/contracts/{addr}/witnesses/*)
   // ────────────────────────────────────────────────────────────────────────
-  proposeWitness(contractAddress, body, idempotencyKey) {
-    const key = idempotencyKey ?? randomUUID();
+  async proposeWitness(contractAddress, body, idempotencyKey) {
+    const key = idempotencyKey ?? await deriveBodyKey("v1:propose", contractAddress, body);
     return this.req(
       "POST",
       `/v1/contracts/${encodeURIComponent(contractAddress)}/witnesses/propose`,
@@ -234,8 +332,8 @@ var WitniumchainClient = class {
       { auth: "SignedRequest" }
     );
   }
-  revokeWitness(contractAddress, witnessId, body, idempotencyKey) {
-    const key = idempotencyKey ?? randomUUID();
+  async revokeWitness(contractAddress, witnessId, body, idempotencyKey) {
+    const key = idempotencyKey ?? await deriveBodyKey("v1:revoke", contractAddress, { witnessId, body });
     return this.req(
       "POST",
       `/v1/contracts/${encodeURIComponent(contractAddress)}/witnesses/${encodeURIComponent(witnessId)}/revoke`,
@@ -257,12 +355,15 @@ var WitniumchainClient = class {
   // chain-api with the admin token. Auth is OAuth Bearer; the URL
   // contract must match the user's bound contract.
   //
-  // The propose/revoke methods auto-generate an Idempotency-Key when the
-  // caller doesn't supply one — server side that header is part of the
-  // billing identity and is required.
+  // The propose/revoke methods default Idempotency-Key to a stable hash
+  // of the request body so an application-level retry with the same
+  // arguments dedupes against the original reservation instead of
+  // burning a second credit. Pass an explicit `idempotencyKey` to
+  // override (e.g. if you genuinely want two witnesses for the same
+  // body).
   // ────────────────────────────────────────────────────────────────────────
-  proposeWitnessV5(contractAddress, body, idempotencyKey) {
-    const key = idempotencyKey ?? randomUUID();
+  async proposeWitnessV5(contractAddress, body, idempotencyKey) {
+    const key = idempotencyKey ?? await deriveBodyKey("v5:propose", contractAddress, body);
     return this.req(
       "POST",
       `/v5/contracts/${encodeURIComponent(contractAddress)}/witnesses/propose`,
@@ -283,8 +384,8 @@ var WitniumchainClient = class {
       { auth: "BearerJWT" }
     );
   }
-  revokeWitnessV5(contractAddress, witnessId, body, idempotencyKey) {
-    const key = idempotencyKey ?? randomUUID();
+  async revokeWitnessV5(contractAddress, witnessId, body, idempotencyKey) {
+    const key = idempotencyKey ?? await deriveBodyKey("v5:revoke", contractAddress, { witnessId, body });
     return this.req(
       "POST",
       `/v5/contracts/${encodeURIComponent(contractAddress)}/witnesses/${encodeURIComponent(witnessId)}/revoke`,
@@ -301,6 +402,37 @@ var WitniumchainClient = class {
     return this.req("GET", "/v1/account/ledger", { auth: "SessionCookie" });
   }
   // ────────────────────────────────────────────────────────────────────────
+  // MFA (/v1/account/mfa/*)
+  //
+  // SessionCookie auth (self-management). Returns the same shapes the
+  // dashboard renders directly; the SDK is also a viable consumer for any
+  // Node-side tooling that needs to programmatically enrol a service account.
+  //
+  // The MFA challenge step that runs inside the OAuth interaction (Thread E)
+  // is NOT here — it's a server-rendered HTML form, not a JSON surface.
+  // ────────────────────────────────────────────────────────────────────────
+  enrollTotp() {
+    return this.req("POST", "/v1/account/mfa/totp/enroll", {
+      auth: "SessionCookie"
+    });
+  }
+  confirmTotp(body) {
+    return this.req("POST", "/v1/account/mfa/totp/confirm", {
+      auth: "SessionCookie",
+      body
+    });
+  }
+  disableTotp() {
+    return this.req("DELETE", "/v1/account/mfa/totp", {
+      auth: "SessionCookie"
+    });
+  }
+  regenerateRecoveryCodes() {
+    return this.req("POST", "/v1/account/mfa/recovery-codes/regenerate", {
+      auth: "SessionCookie"
+    });
+  }
+  // ────────────────────────────────────────────────────────────────────────
   // OAuth sessions (/v1/oauth/sessions*)
   // ────────────────────────────────────────────────────────────────────────
   listOauthSessions() {
@@ -327,12 +459,408 @@ var WitniumchainClient = class {
   healthReady() {
     return this.req("GET", "/health/ready", { auth: "Public" });
   }
+  // ════════════════════════════════════════════════════════════════════════
+  // Chain-api reads (called against chainBaseUrl, e.g. api.witniumchain.com)
+  //
+  // Routing: every method here passes `service: 'chain'` to `req()`. Calls
+  // throw at call time if `chainBaseUrl` wasn't configured.
+  //
+  // Auth: BearerJWT. The accounts-issued OAuth access token already carries
+  // `aud=https://api.witniumchain.com`, so the same `accessToken` works
+  // unchanged against both services.
+  //
+  // What's NOT here: chain-api v5 WRITES (propose/sign/finalize/revoke). Those
+  // are proxied by accounts (proposeWitnessV5, etc.) so credits get reserved
+  // and idempotency is enforced. See docs/PLAN-PHASE-SDK-UNIFIED.md for the
+  // routing rules; calling chain-api writes directly would burn credits
+  // without billing them.
+  // ════════════════════════════════════════════════════════════════════════
+  getContractInfo(contractAddress) {
+    return this.req(
+      "GET",
+      `/v5/contracts/${encodeURIComponent(contractAddress)}/info`,
+      { auth: "BearerJWT", service: "chain" }
+    );
+  }
+  getContractVerification(contractAddress) {
+    return this.req(
+      "GET",
+      `/v5/contracts/${encodeURIComponent(contractAddress)}/verify`,
+      { auth: "BearerJWT", service: "chain" }
+    );
+  }
+  listWitnessesV5(contractAddress, params) {
+    return this.req(
+      "GET",
+      `/v5/contracts/${encodeURIComponent(contractAddress)}/witnesses`,
+      { auth: "BearerJWT", service: "chain", query: params }
+    );
+  }
+  getWitnessV5(contractAddress, witnessId) {
+    return this.req(
+      "GET",
+      `/v5/contracts/${encodeURIComponent(contractAddress)}/witnesses/${encodeURIComponent(witnessId)}`,
+      { auth: "BearerJWT", service: "chain" }
+    );
+  }
+  getContractTransaction(contractAddress, txHash) {
+    return this.req(
+      "GET",
+      `/v5/contracts/${encodeURIComponent(contractAddress)}/transactions/${encodeURIComponent(txHash)}`,
+      { auth: "BearerJWT", service: "chain" }
+    );
+  }
+  getTransaction(txHash) {
+    return this.req(
+      "GET",
+      `/v5/transactions/${encodeURIComponent(txHash)}`,
+      { auth: "BearerJWT", service: "chain" }
+    );
+  }
+  getWalletBalance(address) {
+    return this.req(
+      "GET",
+      `/v5/wallets/${encodeURIComponent(address)}/balance`,
+      { auth: "BearerJWT", service: "chain" }
+    );
+  }
+  getDashboardContract() {
+    return this.req("GET", "/v5/dashboard/contract", {
+      auth: "BearerJWT",
+      service: "chain"
+    });
+  }
+  getDashboardWitnesses(params) {
+    return this.req("GET", "/v5/dashboard/witnesses", {
+      auth: "BearerJWT",
+      service: "chain",
+      query: params
+    });
+  }
+  // ════════════════════════════════════════════════════════════════════════
+  // OAuth 2.1 + PKCE flow helpers (Phase AUTH Thread A)
+  //
+  // Designed for browser SPAs without a backend ("Sign in with Witnium" for a
+  // Lovable customer). The flow:
+  //
+  //   1. App calls `beginOAuthLogin({ redirectUri })`, gets a URL, redirects.
+  //   2. User authenticates at auth.witniumchain.com, server redirects back
+  //      to the app's redirectUri with `?code=…&state=…`.
+  //   3. App calls `completeOAuthLogin(window.location.href)`, gets back an
+  //      access token. The SDK stashes it in memory; subsequent `BearerJWT`
+  //      calls use it transparently.
+  //   4. When a `BearerJWT` call returns 401 (token expired), `req()` calls
+  //      `refreshAccessToken` once and retries. Caller never sees the 401.
+  //
+  // Access tokens live in memory only — never localStorage. They die on tab
+  // close; the refresh token (held in memory today, planned to migrate to an
+  // HttpOnly cookie set by /token server-side) survives long enough for a
+  // silent refresh on the next /completeOAuthLogin or 401-retry. Refresh
+  // tokens rotate on every use, so a single-flight gate avoids racing two
+  // concurrent refreshes against the same token.
+  //
+  // Endpoint discovery: the SDK fetches /.well-known/openid-configuration
+  // from `baseUrl` once and reuses the parsed result. oidc-provider's paths
+  // (/auth, /token, /jwks, etc.) are not hard-coded — if accounts ever moves
+  // them, only the discovery doc has to be right.
+  // ════════════════════════════════════════════════════════════════════════
+  /**
+   * Build the authorization-server URL for the start of an OAuth login flow.
+   *
+   * Generates a fresh PKCE verifier + challenge, stashes the verifier in the
+   * configured {@link PkceVerifierStorage} under the `state` key, and returns
+   * the URL the caller should redirect the user to. Side-effects:
+   *
+   *   - sessionStorage gets a PKCE entry under `witniumchain.pkce.<state>`.
+   *   - The client instance remembers the `redirectUri` for this `state`
+   *     so {@link completeOAuthLogin} can rebuild the matching token request
+   *     without the caller threading the URI through twice.
+   *
+   * The caller is responsible for the redirect itself
+   * (`window.location.assign(result.authorizationUrl)`); the SDK doesn't
+   * touch `window` directly so SSR + non-browser callers are not broken.
+   */
+  async beginOAuthLogin(args) {
+    if (!this.oauthClientId) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: beginOAuthLogin requires `oauthClientId` to be set on the constructor."
+      });
+    }
+    const discovery = await this.fetchDiscovery();
+    const state = args.state ?? generateState();
+    const verifier = generateCodeVerifier();
+    const challenge = await deriveCodeChallenge(verifier);
+    const scope = (args.scope ?? ["openid", "profile", "email"]).join(" ");
+    const url = new URL(discovery.authorization_endpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", this.oauthClientId);
+    url.searchParams.set("redirect_uri", args.redirectUri);
+    url.searchParams.set("scope", scope);
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge", challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    if (args.prompt) url.searchParams.set("prompt", args.prompt);
+    this.verifierStorageOrDefault().set(state, verifier);
+    this.pendingLogins.set(state, { redirectUri: args.redirectUri });
+    return { authorizationUrl: url.toString(), state };
+  }
+  /**
+   * Exchange an authorization-code callback for an access token.
+   *
+   * Reads `code` and `state` from the callback URL, validates the state
+   * against a stored verifier, exchanges the code at the token endpoint,
+   * and stores the access token (and refresh token) in the client's
+   * in-memory state. Returns the access token + its expiry for callers
+   * who want to display the session or schedule a proactive refresh.
+   *
+   * Throws (without consuming the verifier) when the callback URL is
+   * missing `code` or `state`, or when the state has no matching verifier
+   * — the latter happens when the user opens an old/forged callback URL,
+   * or when sessionStorage was cleared between authorize and callback.
+   *
+   * The caller is responsible for stripping `code` and `state` from the
+   * browser URL afterwards (`window.history.replaceState`) so a refresh
+   * doesn't re-trigger the exchange against an already-consumed code.
+   */
+  async completeOAuthLogin(callbackUrl) {
+    if (!this.oauthClientId) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: completeOAuthLogin requires `oauthClientId` to be set on the constructor."
+      });
+    }
+    const url = callbackUrl instanceof URL ? callbackUrl : new URL(callbackUrl);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    const error = url.searchParams.get("error");
+    if (error) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: `OAuth authorize returned error: ${error}${url.searchParams.get("error_description") ? ` (${url.searchParams.get("error_description")})` : ""}`,
+        errorLabel: error
+      });
+    }
+    if (!code || !state) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: callbackUrl missing required `code` and/or `state` parameters."
+      });
+    }
+    const storage = this.verifierStorageOrDefault();
+    const verifier = storage.get(state);
+    if (!verifier) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: no PKCE verifier stored for this `state`. The login flow either was not started in this tab, was already completed, or the sessionStorage entry was cleared."
+      });
+    }
+    const pending = this.pendingLogins.get(state);
+    if (!pending) {
+      storage.remove(state);
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: PKCE verifier exists but the redirectUri for this `state` was not found in client memory (the client instance was replaced between beginOAuthLogin and completeOAuthLogin)."
+      });
+    }
+    const discovery = await this.fetchDiscovery();
+    const form = new URLSearchParams();
+    form.set("grant_type", "authorization_code");
+    form.set("code", code);
+    form.set("redirect_uri", pending.redirectUri);
+    form.set("client_id", this.oauthClientId);
+    form.set("code_verifier", verifier);
+    const tokens = await this.postTokenEndpoint(discovery.token_endpoint, form);
+    storage.remove(state);
+    this.pendingLogins.delete(state);
+    return this.persistTokenResponse(tokens);
+  }
+  /**
+   * Refresh the access token. Sends `grant_type=refresh_token` to the token
+   * endpoint with the in-memory refresh token, and updates `accessToken`
+   * (and the rotated refresh token) on success.
+   *
+   * Concurrent callers — including the 401-retry interceptor inside `req()`
+   * fanning out N parallel calls — share a single in-flight refresh promise:
+   * refresh tokens rotate on use, so issuing two concurrent refreshes would
+   * race and one would 401 with `invalid_grant`.
+   *
+   * Throws `WitniumchainApiError` if the refresh token is missing (the SDK
+   * was constructed without one and `completeOAuthLogin` was never called)
+   * or if the AS rejects the refresh (token revoked / expired). On rejection
+   * the in-memory tokens are cleared so subsequent BearerJWT calls fail fast
+   * instead of retrying with a now-invalid token.
+   */
+  async refreshAccessToken() {
+    if (this.refreshInFlight) return this.refreshInFlight;
+    this.refreshInFlight = (async () => {
+      try {
+        return await this.refreshAccessTokenInternal();
+      } finally {
+        this.refreshInFlight = void 0;
+      }
+    })();
+    return this.refreshInFlight;
+  }
+  /**
+   * End the OAuth session.
+   *
+   * Clears the in-memory access + refresh tokens. Best-effort revocation of
+   * the server-side session would require a server endpoint that accepts a
+   * Bearer-token-authenticated DELETE (today's `/v1/oauth/sessions` requires
+   * the first-party `wac_session` cookie, see oauth-sessions.controller.ts).
+   * That endpoint will arrive with Phase AUTH Thread E; until then,
+   * `signOut` clears local state only and the access token's natural TTL
+   * (currently 60 min) bounds residual risk if the refresh token is also
+   * dropped — which it is, here.
+   */
+  signOut() {
+    this.accessToken = void 0;
+    this.refreshToken = void 0;
+    this.hasRefreshCookie = false;
+    this.pendingLogins.clear();
+  }
+  // ────────────────────────────────────────────────────────────────────────
+  // Internal: OAuth flow helpers
+  // ────────────────────────────────────────────────────────────────────────
+  verifierStorageOrDefault() {
+    if (this.verifierStorage) return this.verifierStorage;
+    return defaultVerifierStorage();
+  }
+  async fetchDiscovery() {
+    if (this.discoveryCache) return this.discoveryCache;
+    this.discoveryCache = (async () => {
+      const url = `${this.baseUrl}/.well-known/openid-configuration`;
+      let res;
+      try {
+        res = await this.fetchImpl(url, {
+          method: "GET",
+          headers: { accept: "application/json" }
+        });
+      } catch (err) {
+        this.discoveryCache = void 0;
+        throw new WitniumchainApiError({
+          status: 0,
+          message: err instanceof Error ? `OIDC discovery fetch failed: ${err.message}` : "OIDC discovery fetch failed"
+        });
+      }
+      if (!res.ok) {
+        this.discoveryCache = void 0;
+        throw new WitniumchainApiError({
+          status: res.status,
+          message: `OIDC discovery fetch failed: HTTP ${res.status}`
+        });
+      }
+      const parsed = await res.json();
+      if (!parsed.authorization_endpoint || !parsed.token_endpoint) {
+        this.discoveryCache = void 0;
+        throw new WitniumchainApiError({
+          status: 0,
+          message: "OIDC discovery doc is missing `authorization_endpoint` or `token_endpoint`."
+        });
+      }
+      return {
+        authorization_endpoint: parsed.authorization_endpoint,
+        token_endpoint: parsed.token_endpoint,
+        issuer: parsed.issuer ?? this.baseUrl
+      };
+    })();
+    return this.discoveryCache;
+  }
+  async postTokenEndpoint(endpoint, form) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let res;
+    try {
+      res = await this.fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          accept: "application/json",
+          "content-type": "application/x-www-form-urlencoded"
+        },
+        body: form.toString(),
+        signal: controller.signal,
+        // Sends the HttpOnly refresh-token cookie when the server starts
+        // setting it (planned server-side change); a no-op until then.
+        credentials: "include"
+      });
+    } catch (err) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: err instanceof Error ? `Token endpoint fetch failed: ${err.message}` : "Token endpoint fetch failed"
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let parsed = null;
+    if (text.length > 0) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+      }
+    }
+    if (!res.ok) {
+      throw this.parseApiError(res.status, parsed, text);
+    }
+    return parsed;
+  }
+  persistTokenResponse(tokens) {
+    if (!tokens.access_token) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "Token endpoint response missing `access_token`."
+      });
+    }
+    this.accessToken = tokens.access_token;
+    if (tokens.refresh_token) {
+      this.refreshToken = tokens.refresh_token;
+    } else {
+      this.refreshToken = void 0;
+      this.hasRefreshCookie = true;
+    }
+    const ttlSeconds = typeof tokens.expires_in === "number" ? tokens.expires_in : 3600;
+    const expiresAt = Math.floor(Date.now() / 1e3) + ttlSeconds;
+    return { accessToken: tokens.access_token, expiresAt };
+  }
+  async refreshAccessTokenInternal() {
+    if (!this.oauthClientId) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: refreshAccessToken requires `oauthClientId` to be set on the constructor."
+      });
+    }
+    if (!this.refreshToken && !this.hasRefreshCookie) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: no refresh credential available. Call `completeOAuthLogin` first \u2014 the server delivers the refresh token either in the response body (Node) or as an HttpOnly cookie (browser)."
+      });
+    }
+    const discovery = await this.fetchDiscovery();
+    const form = new URLSearchParams();
+    form.set("grant_type", "refresh_token");
+    form.set("client_id", this.oauthClientId);
+    if (this.refreshToken) {
+      form.set("refresh_token", this.refreshToken);
+    }
+    try {
+      const tokens = await this.postTokenEndpoint(discovery.token_endpoint, form);
+      return this.persistTokenResponse(tokens);
+    } catch (err) {
+      this.accessToken = void 0;
+      this.refreshToken = void 0;
+      this.hasRefreshCookie = false;
+      throw err;
+    }
+  }
   // ────────────────────────────────────────────────────────────────────────
   // Internal: fetch wrapper that maps non-2xx → WitniumchainApiError
   // and applies the configured credential to the request.
   // ────────────────────────────────────────────────────────────────────────
   async req(method, path, opts) {
-    const url = this.buildUrl(path, opts.query);
+    const pathWithQuery = this.buildPathWithQuery(path, opts.query);
+    const base = this.resolveBaseUrl(opts.service);
+    const url = `${base}${pathWithQuery}`;
     const headers = {
       accept: "application/json",
       ...opts.headers ?? {}
@@ -341,7 +869,13 @@ var WitniumchainClient = class {
       headers["content-type"] = "application/json";
     }
     const bodyString = opts.body !== void 0 ? JSON.stringify(opts.body) : void 0;
-    await this.applyAuth(headers, opts.auth, method, path, bodyString ?? "");
+    await this.applyAuth(
+      headers,
+      opts.auth,
+      method,
+      pathWithQuery,
+      bodyString ?? ""
+    );
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeout);
     let res;
@@ -358,13 +892,16 @@ var WitniumchainClient = class {
     } catch (err) {
       throw new WitniumchainApiError({
         status: 0,
-        message: err instanceof Error ? `Network error contacting ${this.baseUrl}: ${err.message}` : `Network error contacting ${this.baseUrl}`
+        message: err instanceof Error ? `Network error contacting ${base}: ${err.message}` : `Network error contacting ${base}`
       });
     } finally {
       clearTimeout(timer);
     }
     if (opts.expectNoContent) {
       if (!res.ok) {
+        if (await this.shouldRefreshAndRetry(res, opts)) {
+          return this.req(method, path, { ...opts, _isRetry: true });
+        }
         throw await this.toApiError(res);
       }
       return void 0;
@@ -378,18 +915,93 @@ var WitniumchainClient = class {
       }
     }
     if (!res.ok) {
+      if (await this.shouldRefreshAndRetryParsed(res.status, parsed, opts)) {
+        return this.req(method, path, { ...opts, _isRetry: true });
+      }
       throw this.parseApiError(res.status, parsed, text);
     }
     return parsed;
   }
-  buildUrl(path, query) {
-    if (!query) return `${this.baseUrl}${path}`;
+  /**
+   * Decide whether a non-2xx response on a `BearerJWT` route should trigger
+   * a refresh + single retry. Returns false (no retry) when:
+   *
+   *   - this call IS the retry — never recurse,
+   *   - the auth mode isn't BearerJWT — refresh only helps Bearer tokens,
+   *   - the status isn't 401 — refresh doesn't unstick 403/404/500/etc,
+   *   - we don't have a refresh token in memory — nothing to refresh with,
+   *   - the response body doesn't look like an expired-token signal.
+   *
+   * On a positive answer, the method ALSO performs the refresh in-line:
+   * the caller just gets back `true` and replays the original request,
+   * which picks up the freshly-rotated `accessToken` via `applyAuth`.
+   * Refresh failures are swallowed here (the caller falls through to the
+   * regular error path); `refreshAccessTokenInternal` already cleared the
+   * in-memory tokens so the retry won't have anything to send.
+   */
+  async shouldRefreshAndRetry(res, opts) {
+    if (opts._isRetry) return false;
+    if (opts.auth !== "BearerJWT") return false;
+    if (res.status !== 401) return false;
+    if (!this.refreshToken && !this.hasRefreshCookie) return false;
+    try {
+      await this.refreshAccessToken();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Same decision as `shouldRefreshAndRetry` but for the JSON-parsed path,
+   * where we have the body. Adds one extra gate: only retry when the parsed
+   * body looks like a "token expired" signal (`error: 'token_expired'` per
+   * the AUTH plan, or `error: 'invalid_token'` per RFC 6750 §3.1). A 401
+   * with any other `error` label is a real authn/authz failure that refresh
+   * won't fix — surface it instead of burning a refresh token.
+   */
+  async shouldRefreshAndRetryParsed(status, parsed, opts) {
+    if (opts._isRetry) return false;
+    if (opts.auth !== "BearerJWT") return false;
+    if (status !== 401) return false;
+    if (!this.refreshToken && !this.hasRefreshCookie) return false;
+    const body = parsed;
+    const label = typeof body?.error === "string" ? body.error : void 0;
+    if (label !== void 0 && label !== "token_expired" && label !== "invalid_token") {
+      return false;
+    }
+    try {
+      await this.refreshAccessToken();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Resolve which base URL to call. Default is accounts (`baseUrl`). When a
+   * method opts into 'chain', `chainBaseUrl` must be configured — throw at call
+   * time with a clear message rather than fall back silently to accounts (no
+   * defaults: a wrong base URL is a real bug and would mask itself as a 404).
+   */
+  resolveBaseUrl(service) {
+    if (service === "chain") {
+      if (!this.chainBaseUrl) {
+        throw new WitniumchainApiError({
+          status: 0,
+          message: 'WitniumchainClient: chain-api method called without `chainBaseUrl` configured. Pass `chainBaseUrl: "https://api.witniumchain.com"` (or your environment\'s chain-api URL) to the client constructor.'
+        });
+      }
+      return this.chainBaseUrl;
+    }
+    return this.baseUrl;
+  }
+  buildPathWithQuery(path, query) {
+    if (!query) return path;
     const qs = new URLSearchParams();
     for (const [k, v] of Object.entries(query)) {
       if (v !== void 0) qs.set(k, String(v));
     }
     const suffix = qs.toString();
-    return suffix ? `${this.baseUrl}${path}?${suffix}` : `${this.baseUrl}${path}`;
+    return suffix ? `${path}?${suffix}` : path;
   }
   async applyAuth(headers, auth, method, path, bodyString) {
     switch (auth) {
@@ -402,12 +1014,12 @@ var WitniumchainClient = class {
         return;
       }
       case "BearerJWT": {
-        if (!this.cfg.accessToken) {
+        if (!this.accessToken) {
           throw new Error(
-            `WitniumchainClient: ${method} ${path} requires an OAuth access token. Pass \`accessToken\` to the constructor.`
+            `WitniumchainClient: ${method} ${path} requires an OAuth access token. Pass \`accessToken\` to the constructor, or call \`beginOAuthLogin\`/\`completeOAuthLogin\` to obtain one.`
           );
         }
-        headers["authorization"] = `Bearer ${this.cfg.accessToken}`;
+        headers["authorization"] = `Bearer ${this.accessToken}`;
         return;
       }
       case "OrgApiKey": {
@@ -599,17 +1211,71 @@ var OauthSessions = class {
     return this.client.revokeAllOauthSessions();
   }
 };
+var MfaNamespace = class {
+  totp;
+  recoveryCodes;
+  constructor(client) {
+    this.totp = new MfaTotp(client);
+    this.recoveryCodes = new MfaRecoveryCodes(client);
+  }
+};
+var MfaTotp = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Start enrolment. Returns the secret + otpauth URL — render the URL as a
+   * QR code in your dashboard (any QR library will do; the SDK doesn't bundle
+   * one). The enrolment is NOT yet a usable second factor: call
+   * {@link confirm} with the first 6-digit code from the authenticator app
+   * to activate it AND receive the recovery codes.
+   */
+  enroll() {
+    return this.client.enrollTotp();
+  }
+  /**
+   * 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.
+   */
+  confirm(code) {
+    return this.client.confirmTotp({ code });
+  }
+  /** Disable TOTP, wiping both the secret and all recovery codes. */
+  disable() {
+    return this.client.disableTotp();
+  }
+};
+var MfaRecoveryCodes = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Issue a fresh set of 10 recovery codes, invalidating the prior ones.
+   * Same as `confirm` — codes are returned ONCE and never readable again.
+   */
+  regenerate() {
+    return this.client.regenerateRecoveryCodes();
+  }
+};
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function randomUUID() {
-  const c = globalThis.crypto;
-  if (!c?.randomUUID) {
-    throw new Error(
-      "WitniumchainClient: globalThis.crypto.randomUUID is required (Node 19+ or modern browser). Polyfill for older runtimes."
-    );
-  }
-  return c.randomUUID();
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+async function deriveBodyKey(namespace, contractAddress, body) {
+  const canonical = `${namespace}|${contractAddress.toLowerCase()}|${stableStringify(body)}`;
+  return await sha256Hex(canonical);
 }
 async function sha256Hex(input) {
   const subtle = globalThis.crypto?.subtle;
@@ -727,6 +1393,9 @@ var OrgUsers = class {
 };
 
 exports.DelegatedKeys = DelegatedKeys;
+exports.MfaNamespace = MfaNamespace;
+exports.MfaRecoveryCodes = MfaRecoveryCodes;
+exports.MfaTotp = MfaTotp;
 exports.OauthNamespace = OauthNamespace;
 exports.OauthSessions = OauthSessions;
 exports.OrgUsers = OrgUsers;
@@ -736,5 +1405,6 @@ exports.WitniumchainAdminClient = WitniumchainAdminClient;
 exports.WitniumchainApiError = WitniumchainApiError;
 exports.WitniumchainClient = WitniumchainClient;
 exports.WitniumchainOrgClient = WitniumchainOrgClient;
+exports.defaultVerifierStorage = defaultVerifierStorage;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map