@witnium-tech/witniumchain 0.11.0 → 0.12.1

package/dist/index.mjs

@@ -119,6 +119,11 @@ var WitniumchainClient = class {
   // first BearerJWT call (and any concurrent fan-out) awaits one in-flight
   // mint rather than minting N tokens.
   sessionExchangeInFlight;
+  // Bumped whenever the cached credentials stop being valid (sign-out, the
+  // TOTP-confirm epoch bump). A mint or refresh that started under an older
+  // generation must not store its result: it could be a previous user's
+  // token, or one the server has already ended.
+  credentialGeneration = 0;
   /** Subscriptions / billing helpers. See {@link Subscriptions}. */
   subscriptions;
   /** Delegated-key namespace including the one-call {@link DelegatedKeys.provision} flow. */
@@ -175,9 +180,10 @@ var WitniumchainClient = class {
    * 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) {
     return this.req("POST", "/v1/orgs", { auth: "Public", body });
@@ -235,11 +241,36 @@ var WitniumchainClient = class {
       query: { token }
     });
   }
+  /**
+   * 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) {
     return this.req("POST", "/v1/auth/login", { auth: "Public", body });
   }
-  logout() {
-    return this.req("POST", "/v1/auth/logout", { auth: "Public" });
+  /**
+   * 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) {
+    return this.req("POST", "/v1/auth/login/mfa", { auth: "Public", body });
+  }
+  /**
+   * 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.
+   */
+  async logout() {
+    try {
+      return await this.req("POST", "/v1/auth/logout", { auth: "Public" });
+    } finally {
+      this.signOut();
+    }
   }
   forgotPassword(body) {
     return this.req("POST", "/v1/auth/forgot-password", { auth: "Public", body });
@@ -472,20 +503,32 @@ var WitniumchainClient = class {
       auth: "SessionCookie"
     });
   }
-  confirmTotp(body) {
-    return this.req("POST", "/v1/account/mfa/totp/confirm", {
+  /**
+   * Confirming bumps the user's security epoch server-side, which ends every
+   * session-minted access token and OAuth artifact of the user. Cached and
+   * in-flight tokens are dropped so the next bearer call mints a fresh one
+   * from the (surviving) session.
+   */
+  async confirmTotp(body) {
+    const res = await this.req("POST", "/v1/account/mfa/totp/confirm", {
       auth: "SessionCookie",
       body
     });
+    this.invalidateCredentials();
+    return res;
   }
-  disableTotp() {
+  /** Step-up: 403 `mfa_step_up_failed` on a wrong proof, 429 `mfa_rate_limited`. */
+  disableTotp(body) {
     return this.req("DELETE", "/v1/account/mfa/totp", {
-      auth: "SessionCookie"
+      auth: "SessionCookie",
+      body
     });
   }
-  regenerateRecoveryCodes() {
+  /** Step-up: 403 `mfa_step_up_failed` on a wrong proof, 429 `mfa_rate_limited`. */
+  regenerateRecoveryCodes(body) {
     return this.req("POST", "/v1/account/mfa/recovery-codes/regenerate", {
-      auth: "SessionCookie"
+      auth: "SessionCookie",
+      body
     });
   }
   // ────────────────────────────────────────────────────────────────────────
@@ -749,14 +792,16 @@ var WitniumchainClient = class {
    */
   async refreshAccessToken() {
     if (this.refreshInFlight) return this.refreshInFlight;
-    this.refreshInFlight = (async () => {
+    let flight = void 0;
+    flight = (async () => {
       try {
         return await this.refreshAccessTokenInternal();
       } finally {
-        this.refreshInFlight = void 0;
+        if (this.refreshInFlight === flight) this.refreshInFlight = void 0;
       }
     })();
-    return this.refreshInFlight;
+    this.refreshInFlight = flight;
+    return flight;
   }
   /**
    * Exchange the logged-in session (the `wac_session` cookie) for a short-lived
@@ -781,9 +826,12 @@ var WitniumchainClient = class {
    */
   async exchangeSessionForToken() {
     if (this.sessionExchangeInFlight) return this.sessionExchangeInFlight;
-    this.sessionExchangeInFlight = (async () => {
+    const generation = this.credentialGeneration;
+    let flight = void 0;
+    flight = (async () => {
       try {
         const res = await this.req("POST", "/v1/auth/access-token", { auth: "SessionCookie" });
+        this.assertCredentialGeneration(generation);
         this.accessToken = res.accessToken;
         this.accessTokenFromSession = true;
         this.refreshToken = void 0;
@@ -793,10 +841,32 @@ var WitniumchainClient = class {
           expiresAt: Math.floor(new Date(res.expiresAt).getTime() / 1e3)
         };
       } finally {
-        this.sessionExchangeInFlight = void 0;
+        if (this.sessionExchangeInFlight === flight) this.sessionExchangeInFlight = void 0;
       }
     })();
-    return this.sessionExchangeInFlight;
+    this.sessionExchangeInFlight = flight;
+    return flight;
+  }
+  assertCredentialGeneration(generation) {
+    if (generation !== this.credentialGeneration) {
+      throw new WitniumchainApiError({
+        status: 0,
+        message: "WitniumchainClient: the session changed (sign-out or MFA confirmation) while a token request was in flight; its token was discarded."
+      });
+    }
+  }
+  /**
+   * Forget every cached credential and orphan in-flight mints/refreshes, so
+   * none of them can store a token afterwards.
+   */
+  invalidateCredentials() {
+    this.credentialGeneration++;
+    this.accessToken = void 0;
+    this.accessTokenFromSession = false;
+    this.refreshToken = void 0;
+    this.hasRefreshCookie = false;
+    this.sessionExchangeInFlight = void 0;
+    this.refreshInFlight = void 0;
   }
   /**
    * Best-effort transparent mint for the `BearerJWT` path: if no access token
@@ -808,7 +878,8 @@ var WitniumchainClient = class {
     if (this.accessToken) return;
     try {
       await this.exchangeSessionForToken();
-    } catch {
+    } catch (err) {
+      if (!(err instanceof WitniumchainApiError && err.status === 401)) throw err;
     }
   }
   /**
@@ -849,10 +920,7 @@ var WitniumchainClient = class {
    * dropped — which it is, here.
    */
   signOut() {
-    this.accessToken = void 0;
-    this.accessTokenFromSession = false;
-    this.refreshToken = void 0;
-    this.hasRefreshCookie = false;
+    this.invalidateCredentials();
     this.pendingLogins.clear();
   }
   // ────────────────────────────────────────────────────────────────────────
@@ -972,6 +1040,7 @@ var WitniumchainClient = class {
         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 generation = this.credentialGeneration;
     const discovery = await this.fetchDiscovery();
     const form = new URLSearchParams();
     form.set("grant_type", "refresh_token");
@@ -979,15 +1048,18 @@ var WitniumchainClient = class {
     if (this.refreshToken) {
       form.set("refresh_token", this.refreshToken);
     }
+    let tokens;
     try {
-      const tokens = await this.postTokenEndpoint(discovery.token_endpoint, form);
-      return this.persistTokenResponse(tokens);
+      tokens = await this.postTokenEndpoint(discovery.token_endpoint, form);
     } catch (err) {
+      this.assertCredentialGeneration(generation);
       this.accessToken = void 0;
       this.refreshToken = void 0;
       this.hasRefreshCookie = false;
       throw err;
     }
+    this.assertCredentialGeneration(generation);
+    return this.persistTokenResponse(tokens);
   }
   // ────────────────────────────────────────────────────────────────────────
   // Internal: fetch wrapper that maps non-2xx → WitniumchainApiError
@@ -1350,7 +1422,12 @@ var OrgMembers = class {
   list() {
     return this.client.listMembers();
   }
-  /** 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) {
     return this.client.inviteMember(body);
   }
@@ -1370,7 +1447,10 @@ var OrgMembers = class {
   remove(userId) {
     return this.client.removeMember(userId);
   }
-  /** 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) {
     return this.client.resendMemberInvite(userId);
   }
@@ -1394,14 +1474,18 @@ var MfaTotp = class {
    * 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) {
     return this.client.confirmTotp({ code });
   }
-  /** Disable TOTP, wiping both the secret and all recovery codes. */
-  disable() {
-    return this.client.disableTotp();
+  /**
+   * Disable TOTP, wiping both the secret and all recovery codes. Requires the
+   * user's current code or a recovery code.
+   */
+  disable(proof) {
+    return this.client.disableTotp(proof);
   }
 };
 var MfaRecoveryCodes = class {
@@ -1412,9 +1496,10 @@ var MfaRecoveryCodes = class {
   /**
    * 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() {
-    return this.client.regenerateRecoveryCodes();
+  regenerate(proof) {
+    return this.client.regenerateRecoveryCodes(proof);
   }
 };
 function sleep(ms) {