@witnium-tech/witniumchain 0.9.0 → 0.10.0

package/FRONTEND-INTEGRATION.md

@@ -118,6 +118,36 @@ await client.login({ email, password });   // sets wac_session cookie
 In a browser the `wac_session` cookie is set automatically (the SDK uses
 `credentials: 'include'`). Server-side callers must capture + replay the cookie.
 
+### Cookie-only dashboard → bearer calls (automatic, no OAuth needed)
+
+You do **not** need to run the OAuth code flow to call the operational API
+(delegated keys, witness writes, chain reads). After `login()`, just call them:
+
+```ts
+await client.login({ email, password });   // sets wac_session
+await client.listDelegatedKeys();           // ← works; SDK mints a bearer token
+```
+
+How: those endpoints are bearer-only (they never accept the ambient cookie, so
+there's **no CSRF surface** even with `SameSite=None`). On the first such call
+the SDK transparently exchanges the session cookie for a short-lived access
+token via `POST /v1/auth/access-token`, caches it, and re-mints on a 401. You
+never see the token unless you want it:
+
+```ts
+const { accessToken, expiresAt } = await client.exchangeSessionForToken(); // optional pre-warm
+```
+
+Requirements: in the browser the `wac_session` cookie rides automatically
+(`credentials: 'include'`). Node/SSR callers pass `sessionCookie: '<value>'` to
+the constructor. If there's no valid session, the call throws a descriptive
+"requires an OAuth access token … or provide `sessionCookie`" error — that's
+your cue to send the user back to login.
+
+This is the recommended path for a first-party dashboard. Reach for the full
+OAuth flow below only when the dashboard is itself a registered OAuth client
+(e.g. third-party apps, or you want long-lived refresh tokens).
+
 ### Magic-link sign-in
 
 `beginOAuthLogin` / passwordless paths exist; see the SDK's `OauthNamespace`

package/dist/index.d.mts

@@ -10580,6 +10580,8 @@ declare class WitniumchainClient {
     private readonly verifierStorage;
     private discoveryCache;
     private refreshInFlight;
+    private accessTokenFromSession;
+    private sessionExchangeInFlight;
     /** Subscriptions / billing helpers. See {@link Subscriptions}. */
     readonly subscriptions: Subscriptions;
     /** Delegated-key namespace including the one-call {@link DelegatedKeys.provision} flow. */
@@ -10754,6 +10756,41 @@ declare class WitniumchainClient {
      * instead of retrying with a now-invalid token.
      */
     refreshAccessToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Exchange the logged-in session (the `wac_session` cookie) for a short-lived
+     * bearer access token and cache it as the client's `accessToken`.
+     *
+     * This is the SDK side of the session→token model (accounts'
+     * `POST /v1/auth/access-token`): the dashboard authenticates with the
+     * cookie, but the operational API (delegated keys, witness writes, chain
+     * reads) is bearer-only — no endpoint accepts the ambient cookie, so there's
+     * no CSRF surface even with `SameSite=None`. The minted token is
+     * byte-compatible with an OAuth user token (same signing key, `iss`, `aud`,
+     * scope + org/role/contracts claims), so every `BearerJWT` route accepts it.
+     *
+     * Callers rarely invoke this directly — {@link applyAuth} mints transparently
+     * on the first `BearerJWT` call when no token is set and re-mints on a 401.
+     * It's exposed so a dashboard can pre-warm the token right after login.
+     *
+     * Requires a session: either `sessionCookie` on the constructor (Node) or an
+     * ambient `wac_session` cookie carried by the browser (`credentials:
+     * 'include'`). Throws {@link WitniumchainApiError} (401) when there's no
+     * valid session.
+     */
+    exchangeSessionForToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Best-effort transparent mint for the `BearerJWT` path: if no access token
+     * is cached, try the session exchange (single-flight). Swallows failure so
+     * the caller in {@link applyAuth} surfaces the actionable "no token / no
+     * session" guidance rather than a raw 401 from the exchange endpoint.
+     */
+    private ensureSessionAccessToken;
+    /**
+     * Obtain a fresh access token for a 401-retry, picking the right mechanism:
+     * an OAuth refresh when a refresh credential exists, else a session re-mint
+     * for a session-exchanged token. Returns true when a fresh token is in hand.
+     */
+    private reauthenticateForRetry;
     /**
      * End the OAuth session.
      *

package/dist/index.d.ts

@@ -10580,6 +10580,8 @@ declare class WitniumchainClient {
     private readonly verifierStorage;
     private discoveryCache;
     private refreshInFlight;
+    private accessTokenFromSession;
+    private sessionExchangeInFlight;
     /** Subscriptions / billing helpers. See {@link Subscriptions}. */
     readonly subscriptions: Subscriptions;
     /** Delegated-key namespace including the one-call {@link DelegatedKeys.provision} flow. */
@@ -10754,6 +10756,41 @@ declare class WitniumchainClient {
      * instead of retrying with a now-invalid token.
      */
     refreshAccessToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Exchange the logged-in session (the `wac_session` cookie) for a short-lived
+     * bearer access token and cache it as the client's `accessToken`.
+     *
+     * This is the SDK side of the session→token model (accounts'
+     * `POST /v1/auth/access-token`): the dashboard authenticates with the
+     * cookie, but the operational API (delegated keys, witness writes, chain
+     * reads) is bearer-only — no endpoint accepts the ambient cookie, so there's
+     * no CSRF surface even with `SameSite=None`. The minted token is
+     * byte-compatible with an OAuth user token (same signing key, `iss`, `aud`,
+     * scope + org/role/contracts claims), so every `BearerJWT` route accepts it.
+     *
+     * Callers rarely invoke this directly — {@link applyAuth} mints transparently
+     * on the first `BearerJWT` call when no token is set and re-mints on a 401.
+     * It's exposed so a dashboard can pre-warm the token right after login.
+     *
+     * Requires a session: either `sessionCookie` on the constructor (Node) or an
+     * ambient `wac_session` cookie carried by the browser (`credentials:
+     * 'include'`). Throws {@link WitniumchainApiError} (401) when there's no
+     * valid session.
+     */
+    exchangeSessionForToken(): Promise<OAuthTokenSnapshot>;
+    /**
+     * Best-effort transparent mint for the `BearerJWT` path: if no access token
+     * is cached, try the session exchange (single-flight). Swallows failure so
+     * the caller in {@link applyAuth} surfaces the actionable "no token / no
+     * session" guidance rather than a raw 401 from the exchange endpoint.
+     */
+    private ensureSessionAccessToken;
+    /**
+     * Obtain a fresh access token for a 401-retry, picking the right mechanism:
+     * an OAuth refresh when a refresh credential exists, else a session re-mint
+     * for a session-exchanged token. Returns true when a fresh token is in hand.
+     */
+    private reauthenticateForRetry;
     /**
      * End the OAuth session.
      *

package/dist/index.js

@@ -111,6 +111,16 @@ var WitniumchainClient = class {
   // tokens rotate on use (D10), so a second concurrent refresh would race the
   // first and one of them would 401.
   refreshInFlight;
+  // True when the current `accessToken` was minted by the session→token
+  // exchange (`exchangeSessionForToken`) rather than the OAuth code/refresh
+  // flow. Drives the 401-retry: a session-exchanged token has no refresh
+  // credential, so on expiry the SDK re-mints from the cookie instead of
+  // refreshing. Reset to false whenever an OAuth /token response lands.
+  accessTokenFromSession = false;
+  // Single-flight gate for the session→token exchange. A cookie-only client's
+  // first BearerJWT call (and any concurrent fan-out) awaits one in-flight
+  // mint rather than minting N tokens.
+  sessionExchangeInFlight;
   /** Subscriptions / billing helpers. See {@link Subscriptions}. */
   subscriptions;
   /** Delegated-key namespace including the one-call {@link DelegatedKeys.provision} flow. */
@@ -787,6 +797,84 @@ var WitniumchainClient = class {
     })();
     return this.refreshInFlight;
   }
+  /**
+   * Exchange the logged-in session (the `wac_session` cookie) for a short-lived
+   * bearer access token and cache it as the client's `accessToken`.
+   *
+   * This is the SDK side of the session→token model (accounts'
+   * `POST /v1/auth/access-token`): the dashboard authenticates with the
+   * cookie, but the operational API (delegated keys, witness writes, chain
+   * reads) is bearer-only — no endpoint accepts the ambient cookie, so there's
+   * no CSRF surface even with `SameSite=None`. The minted token is
+   * byte-compatible with an OAuth user token (same signing key, `iss`, `aud`,
+   * scope + org/role/contracts claims), so every `BearerJWT` route accepts it.
+   *
+   * Callers rarely invoke this directly — {@link applyAuth} mints transparently
+   * on the first `BearerJWT` call when no token is set and re-mints on a 401.
+   * It's exposed so a dashboard can pre-warm the token right after login.
+   *
+   * Requires a session: either `sessionCookie` on the constructor (Node) or an
+   * ambient `wac_session` cookie carried by the browser (`credentials:
+   * 'include'`). Throws {@link WitniumchainApiError} (401) when there's no
+   * valid session.
+   */
+  async exchangeSessionForToken() {
+    if (this.sessionExchangeInFlight) return this.sessionExchangeInFlight;
+    this.sessionExchangeInFlight = (async () => {
+      try {
+        const res = await this.req("POST", "/v1/auth/access-token", { auth: "SessionCookie" });
+        this.accessToken = res.accessToken;
+        this.accessTokenFromSession = true;
+        this.refreshToken = void 0;
+        this.hasRefreshCookie = false;
+        return {
+          accessToken: res.accessToken,
+          expiresAt: Math.floor(new Date(res.expiresAt).getTime() / 1e3)
+        };
+      } finally {
+        this.sessionExchangeInFlight = void 0;
+      }
+    })();
+    return this.sessionExchangeInFlight;
+  }
+  /**
+   * Best-effort transparent mint for the `BearerJWT` path: if no access token
+   * is cached, try the session exchange (single-flight). Swallows failure so
+   * the caller in {@link applyAuth} surfaces the actionable "no token / no
+   * session" guidance rather than a raw 401 from the exchange endpoint.
+   */
+  async ensureSessionAccessToken() {
+    if (this.accessToken) return;
+    try {
+      await this.exchangeSessionForToken();
+    } catch {
+    }
+  }
+  /**
+   * Obtain a fresh access token for a 401-retry, picking the right mechanism:
+   * an OAuth refresh when a refresh credential exists, else a session re-mint
+   * for a session-exchanged token. Returns true when a fresh token is in hand.
+   */
+  async reauthenticateForRetry() {
+    if (this.refreshToken || this.hasRefreshCookie) {
+      try {
+        await this.refreshAccessToken();
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    if (this.accessTokenFromSession) {
+      this.accessToken = void 0;
+      try {
+        await this.exchangeSessionForToken();
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
   /**
    * End the OAuth session.
    *
@@ -801,6 +889,7 @@ var WitniumchainClient = class {
    */
   signOut() {
     this.accessToken = void 0;
+    this.accessTokenFromSession = false;
     this.refreshToken = void 0;
     this.hasRefreshCookie = false;
     this.pendingLogins.clear();
@@ -898,6 +987,7 @@ var WitniumchainClient = class {
       });
     }
     this.accessToken = tokens.access_token;
+    this.accessTokenFromSession = false;
     if (tokens.refresh_token) {
       this.refreshToken = tokens.refresh_token;
     } else {
@@ -1028,13 +1118,9 @@ var WitniumchainClient = class {
     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 {
+    if (!this.refreshToken && !this.hasRefreshCookie && !this.accessTokenFromSession)
       return false;
-    }
+    return this.reauthenticateForRetry();
   }
   /**
    * Same decision as `shouldRefreshAndRetry` but for the JSON-parsed path,
@@ -1048,18 +1134,14 @@ var WitniumchainClient = class {
     if (opts._isRetry) return false;
     if (opts.auth !== "BearerJWT") return false;
     if (status !== 401) return false;
-    if (!this.refreshToken && !this.hasRefreshCookie) return false;
+    if (!this.refreshToken && !this.hasRefreshCookie && !this.accessTokenFromSession)
+      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;
-    }
+    return this.reauthenticateForRetry();
   }
   /**
    * Resolve which base URL to call. Default is accounts (`baseUrl`). When a
@@ -1099,9 +1181,12 @@ var WitniumchainClient = class {
         return;
       }
       case "BearerJWT": {
+        if (!this.accessToken) {
+          await this.ensureSessionAccessToken();
+        }
         if (!this.accessToken) {
           throw new Error(
-            `WitniumchainClient: ${method} ${path} requires an OAuth access token. Pass \`accessToken\` to the constructor, or call \`beginOAuthLogin\`/\`completeOAuthLogin\` to obtain one.`
+            `WitniumchainClient: ${method} ${path} requires an OAuth access token. Pass \`accessToken\` to the constructor, call \`beginOAuthLogin\`/\`completeOAuthLogin\`, or \u2014 for a logged-in dashboard \u2014 provide \`sessionCookie\` (Node) or rely on the browser \`wac_session\` cookie so the SDK can mint one.`
           );
         }
         headers["authorization"] = `Bearer ${this.accessToken}`;