appmesh 1.3.3 → 3.0.0

package/src/appmesh.js

@@ -10,24 +10,11 @@ let _httpsReady = null; // Promise that resolves when https/fs are loaded
 const CONSTANTS = Object.freeze({
   HTTP_USER_AGENT_HEADER_NAME: "User-Agent",
   HTTP_USER_AGENT: "appmesh/javascript",
-  HTTP_STATUS_PRECONDITION_REQUIRED: 428,
-  DEFAULT_TOKEN_EXPIRE_SECONDS: "P1W",
   DEFAULT_RUN_APP_TIMEOUT_SECONDS: "P2D",
   DEFAULT_RUN_APP_LIFECYCLE_SECONDS: "P2DT12H",
-  DEFAULT_JWT_AUDIENCE: "appmesh-service",
   HTTP_HEADER_KEY_AUTH: "Authorization",
   HTTP_HEADER_KEY_X_TARGET_HOST: "X-Target-Host",
   HTTP_HEADER_KEY_X_FILE_PATH: "X-File-Path",
-
-  // Auto-refresh pacing: the loop wakes every TOKEN_REFRESH_POLL_SECONDS but renews only
-  // once the token has burned TOKEN_REFRESH_LIFETIME_RATIO of its own lifetime.
-  TOKEN_REFRESH_POLL_SECONDS: 300,   // poll cap, NOT a renew interval
-  TOKEN_REFRESH_OFFSET_SECONDS: 30,  // floor for the pre-expiry margin
-  TOKEN_REFRESH_LIFETIME_RATIO: 0.6, // rest is the retry budget
-  TOKEN_REFRESH_JITTER_RATIO: 0.1,   // of the margin, so clients don't renew in lockstep
-  TOKEN_REFRESH_RETRY_BASE_SECONDS: 5,
-  TOKEN_REFRESH_RETRY_MAX_SECONDS: 60,
-  TOKEN_REFRESH_LOG_EVERY: 10,       // log the 1st failure, then every Nth
 });
 
 // Environment detection
@@ -35,15 +22,6 @@ const ENV = Object.freeze({
   isNode: !(typeof window !== 'undefined' && typeof window.document !== 'undefined')
 });
 
-// Base64 utilities for Node.js and browser
-const base64Utils = ENV.isNode ? {
-  encode: str => Buffer.from(str).toString('base64'),
-  decode: str => Buffer.from(str, 'base64').toString()
-} : {
-  encode: str => btoa(str),
-  decode: str => atob(str)
-};
-
 /**
  * Custom error for AppMesh with enhanced debugging
  */
@@ -65,32 +43,6 @@ class AppMeshError extends Error {
   }
 }
 
-/**
- * Error thrown when the server requires a TOTP code to complete login (HTTP 428).
- *
- * Subclasses AppMeshError with `statusCode` fixed to 428, so existing catch-based
- * callers keep working. Carries the server-issued challenge as `totpChallenge`,
- * ready to pass to `validate_totp(username, totpChallenge, totpCode)`.
- */
-class TotpRequiredError extends AppMeshError {
-  /**
-   * @param {string} message - Error message
-   * @param {any} responseData - Raw 428 response body (object or JSON string containing `totp_challenge`)
-   */
-  constructor(message, responseData = null) {
-    super(message, 428, responseData, 'TOTP_REQUIRED');
-    this.name = 'TotpRequiredError';
-    let data = responseData;
-    if (typeof data === 'string') {
-      try { data = JSON.parse(data); } catch (_) { data = null; }
-    }
-    /** @type {string|null} Server-issued TOTP challenge for validate_totp() */
-    this.totpChallenge = (data && typeof data === 'object' && typeof data.totp_challenge === 'string')
-      ? data.totp_challenge
-      : null;
-  }
-}
-
 /**
  * App removed before its async-run exit was observed. Typed replacement for the
  * old -1 sentinel, keeping real (possibly negative) exit codes unambiguous.
@@ -257,40 +209,6 @@ async function _resolveGid(group) {
   }
 }
 
-/**
- * Decode the `exp` and `iat` claims from a JWT without signature verification.
- * @param {string} token - JWT string (header.payload.signature)
- * @returns {{exp: number, iat: number}|null} Claims (`iat` is 0 when absent), or null when
- *   the token is not a decodable JWT carrying `exp`
- * @private
- */
-function _decodeJwtTimes(token) {
-  try {
-    const parts = token.split('.');
-    if (parts.length !== 3) return null;
-    const payload = JSON.parse(base64Utils.decode(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
-    if (typeof payload.exp !== 'number') return null;
-    return { exp: payload.exp, iat: typeof payload.iat === 'number' ? payload.iat : 0 };
-  } catch (_) {
-    return null;
-  }
-}
-
-/**
- * FNV-1a 32-bit hash, matching the Go SDK so both derive the same jitter from a token.
- * @param {string} str - Input string (JWTs are ASCII, so code units are bytes)
- * @returns {number} Unsigned 32-bit hash
- * @private
- */
-function _fnv1a32(str) {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < str.length; i++) {
-    hash ^= str.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193);
-  }
-  return hash >>> 0;
-}
-
 // Default App Mesh CA bundle, preferred when no sslConfig is given and the file exists
 const DEFAULT_CA_FILE = '/opt/appmesh/ssl/ca.pem';
 
@@ -327,8 +245,6 @@ class AppMeshClient {
    *   against the App Mesh default CA (/opt/appmesh/ssl/ca.pem) if installed, else the system CAs;
    *   `false` disables verification; an object supplies custom `ca`/`cert`/`key` (Buffer, inline
    *   PEM, or file path — a missing path is a hard error).
-   * @param {boolean|null} [useRefreshToken=null] - Ask the daemon for a refresh token
-   *   (see {@link AppMeshClient#set_use_refresh_token} for the tri-state and the browser default).
    * @example
    * const sslConfig = {
    *   cert: fs.readFileSync("client.pem"),
@@ -337,7 +253,7 @@ class AppMeshClient {
    *   rejectUnauthorized: true
    * };
    */
-  constructor(baseURL = ENV.isNode ? 'https://127.0.0.1:6060' : window.location.origin, sslConfig = null, useRefreshToken = null) {
+  constructor(baseURL = ENV.isNode ? 'https://127.0.0.1:6060' : window.location.origin, sslConfig = null) {
     // Base URL for API requests
     this.baseURL = baseURL;
 
@@ -348,34 +264,6 @@ class AppMeshClient {
     // sync from it via _handleTokenUpdate/_getAccessToken)
     this._token = null;
 
-    // Refresh token from the login/totp-validate/renew response body; issued by both
-    // Keycloak and local-JWT daemons, absent against an older daemon that returns none.
-    this._refreshToken = null;
-
-    // Expire seconds from login, replayed on renew so the caller's TTL is kept.
-    this._tokenExpireSeconds = null;
-
-    // {exp, iat} as reported by the daemon in the login/renew body. The only lifetime
-    // source available in a browser, where the auth cookie is HttpOnly and unreadable.
-    this._tokenTimes = null;
-
-    // Per-client jitter seed, used only when no token is readable: the session times
-    // alone are identical for every client that logs in during the same second.
-    this._jitterSeed = Math.random().toString(36).slice(2);
-
-    // Bumped by logout() so a response from a superseded session cannot revive it.
-    this._sessionEpoch = 0;
-
-    // Auto-refresh state: pending timer, consecutive renewal failures (drives the
-    // backoff), and the tail of the renewal queue that serializes renew_token().
-    this._autoRefreshEnabled = false;
-    this._autoRefreshJwt = null;
-    // Tri-state opt-in for being ISSUED a refresh token; null follows auto-refresh.
-    this._useRefreshToken = useRefreshToken;
-    this._refreshTimer = null;
-    this._refreshFailures = 0;
-    this._renewChain = null;
-
     // Configure axios instance
     const axiosConfig = {
       baseURL,
@@ -421,470 +309,40 @@ class AppMeshClient {
     );
   }
 
-  /**
-   * Login with username/password and let the server attach the session token cookie.
-   * @param {string} username
-   * @param {string} password
-   * @param {string} [totpCode] - TOTP code if 2FA is enabled
-   * @param {string|number} [tokenExpire] - Token expiry (integer seconds or ISO 8601 string)
-   * @param {string} [audience] - JWT audience
-   * @returns {Promise<void>} Resolves when login succeeds.
-   * @throws {TotpRequiredError} When the server requires TOTP (HTTP 428) and no valid code was
-   * supplied. Catch it, read `error.totpChallenge`, then complete the login with
-   * `validate_totp(username, error.totpChallenge, totpCode)`:
-   * @example
-   * try {
-   *   await client.login(user, pass);
-   * } catch (err) {
-   *   if (err instanceof TotpRequiredError) {
-   *     await client.validate_totp(user, err.totpChallenge, totpCode);
-   *   } else {
-   *     throw err;
-   *   }
-   * }
-   */
-  async login(username, password, totpCode = null, tokenExpire = CONSTANTS.DEFAULT_TOKEN_EXPIRE_SECONDS, audience = CONSTANTS.DEFAULT_JWT_AUDIENCE) {
-    // Validate inputs
-    if (!username || !password) {
-      throw new AppMeshError('Username and password are required', 400, null, 'INVALID_CREDENTIALS');
-    }
-
-    const auth = base64Utils.encode(`${username}:${password}`);
-    const headers = {
-      [CONSTANTS.HTTP_HEADER_KEY_AUTH]: `Basic ${auth}`,
-      "X-Set-Cookie": "true"
-    };
-    // Omitted, not "false", when declined: the daemon only issues on an explicit opt-in.
-    if (this._wantRefreshToken()) headers["X-Refresh-Token-Request"] = "true";
-    if (totpCode) headers["X-Totp-Code"] = totpCode;
-    if (tokenExpire) headers["X-Expire-Seconds"] = parseDuration(tokenExpire);
-    if (audience) headers["X-Audience"] = audience;
-
-    const response = await this._request("post", "/appmesh/login", null, { headers });
-    this._captureRefreshToken(response);
-    this._tokenExpireSeconds = tokenExpire ? parseDuration(tokenExpire) : null;
+  /** Attach a caller-owned Dex access token in memory. */
+  set_bearer_token(token) {
+    const value = typeof token === 'string' ? token.trim() : '';
+    this._handleTokenUpdate(value || null);
   }
 
-  /**
-   * Verify an external JWT token and optionally update this client session.
-   *
-   * @param {string} token - JWT token to verify
-   * @param {string} [permission=null] - Permission to check
-   * @param {string} [audience] - JWT audience
-   * @param {boolean} [updateSession=true] - When true, updates this client session with the
-   *   verified token and persists local auth state on success. When false, the token is only
-   *   verified and local state is unchanged.
-   * @returns {Promise<{success: boolean, responseText: string}>} Verification result (success is always true).
-   * @throws {AppMeshError} If verification fails (invalid token, permission or audience mismatch, network error).
-   */
-  async authenticate(token, permission = null, audience = CONSTANTS.DEFAULT_JWT_AUDIENCE, updateSession = true) {
-    const headers = { Authorization: `Bearer ${token}` };
-    if (permission) headers["X-Permission"] = permission;
-    if (audience) headers["X-Audience"] = audience;
-    if (updateSession) headers["X-Set-Cookie"] = "true";
-    const response = await this._request("post", "/appmesh/auth", null, { headers });
-    if (updateSession) {
-      // /appmesh/auth returns the same body as login. In a browser this is the only way to
-      // learn the lifetime — set_token() cannot replace an HttpOnly cookie — so without it
-      // auto-refresh would idle at the poll interval until the session silently died.
-      this._captureRefreshToken(response);
-    }
-    const responseText = typeof response.data === 'string' ? response.data : JSON.stringify(response.data);
-    return { success: true, responseText };
+  /** Source-compatible alias for set_bearer_token(). */
+  set_token(token) {
+    this.set_bearer_token(token);
   }
 
-  /**
-   * Set a JWT token directly without server-side verification.
-   * Use when the token is already known to be valid.
-   * For server-side verification, use authenticate() instead.
-   * @param {string} token - A valid JWT token string. In Node.js this updates the outgoing Cookie
-   * header; in browsers it cannot replace the HttpOnly auth cookie.
-   */
-  set_token(token) {
-    if (ENV.isNode) {
-      this._handleTokenUpdate(token);
-    } else {
-      // Browser: auth token is HttpOnly (set by server via Set-Cookie),
-      // document.cookie cannot access or override HttpOnly cookies.
-      // Use authenticate() for browser-based token verification instead.
-      console.warn('set_token() is not supported in browser mode (auth cookie is HttpOnly). Use authenticate() instead.');
-    }
+  /** Remove the locally attached bearer without contacting Engine or Dex. */
+  clear_bearer_token() {
+    this._handleTokenUpdate(null);
   }
 
-  /**
-   * Get the current access token known to this client.
-   * @returns {string|null} Current JWT token or null
-   * @protected
-   */
+  /** Return the current in-memory Dex access token. */
   _getAccessToken() {
     return this._token || null;
   }
 
-  /**
-   * Store a new access token and propagate it to the transport layer.
-   * Called after login/renew/authenticate responses and by set_token().
-   * Base implementation keeps the token in memory, syncs the Node.js outgoing
-   * Cookie header, and reschedules auto-refresh when enabled.
-   * Subclasses using other transports (e.g. TCP) override this to sync their own store.
-   * @param {string|null} token - New JWT token (falsy clears the in-memory token)
-   * @protected
-   */
+  /** Store only the in-memory access token; never synthesize a Cookie header. */
   _handleTokenUpdate(token) {
-    const COOKIE_NAME = 'appmesh_auth_token';
     this._token = token || null;
-    if (ENV.isNode && this._token) {
-      const existingCookies = this._client.defaults.headers.Cookie || '';
-      const cookies = existingCookies.split('; ').filter(c =>
-        c && !c.startsWith(COOKIE_NAME + '=')
-      );
-      cookies.push(`${COOKIE_NAME}=${this._token}`);
-      this._client.defaults.headers.Cookie = cookies.join('; ');
-    }
-    this._autoRefreshJwt = this._token;
-    if (this._autoRefreshEnabled) {
-      this._scheduleTokenRefresh();
-    }
-  }
-
-  /**
-   * Store the refresh token carried by a login/totp-validate/renew response body.
-   * Both modes rotate it on renew, so a present value replaces the stored one and an
-   * absent value keeps it.
-   * @param {Object} response - Response object from _request
-   * @private
-   */
-  _captureRefreshToken(response, epoch = this._sessionEpoch) {
-    if (epoch !== this._sessionEpoch) return; // superseded by a logout
-    let data = response && response.data;
-    if (typeof data === 'string') {
-      try { data = JSON.parse(data); } catch (_) { return; }
-    }
-    if (!data) return;
-    if (typeof data.refresh_token === 'string' && data.refresh_token) {
-      this._refreshToken = data.refresh_token;
-    }
-    // The daemon reports the lifetime in the response body, which stays readable even when
-    // the token itself is an HttpOnly cookie. That is what lets a browser pace itself off
-    // the real lifetime instead of falling back to a fixed cadence.
-    if (Number.isFinite(data.expire_time) && Number.isFinite(data.issued_at)) {
-      this._tokenTimes = { exp: data.expire_time, iat: data.issued_at };
-    }
-  }
-
-  /**
-   * Logout from the current session.
-   */
-  async logout() {
-    try {
-      // OAuth2 (Keycloak) proxy mode: present the refresh token so the daemon can end the
-      // upstream session. Optional — logoff still succeeds (local revoke) without it.
-      const headers = this._refreshToken ? { "X-Refresh-Token": this._refreshToken } : {};
-      await this._request("post", "/appmesh/self/logoff", null, { headers });
-    } catch (error) {
-      console.error("Failed to logoff:", error.message);
-    } finally {
-      // Clean up keepAlive connections
-      if (ENV.isNode && this._client.defaults.httpsAgent) {
-        this._client.defaults.httpsAgent.destroy();
-      }
-
-      this._stopAutoRefresh();
-      // Supersede any renewal already in flight: its response would otherwise land after
-      // this block and re-populate the token, the refresh token and the times — leaving a
-      // logged-out client holding a credential pair the daemon minted after logoff.
-      this._sessionEpoch++;
-      this._token = null;
-      this._refreshToken = null;
-      this._tokenTimes = null;
-
-      // Clear the outgoing auth cookie (Node); the browser's HttpOnly auth cookie is cleared
-      // server-side on logoff.
-      if (ENV.isNode) {
-        this._client.defaults.headers.Cookie = null;
-      }
-    }
-  }
-
-  /**
-   * Enable or disable background token auto-refresh.
-   * @param {boolean} enable - true to start, false to stop
-   * @param {string} [jwtToken] - Optional token used only to calculate the first refresh delay
-   */
-  set_auto_refresh_token(enable, jwtToken = null) {
-    this._stopAutoRefresh();
-    this._autoRefreshEnabled = enable;
-    if (enable) {
-      this._autoRefreshJwt = jwtToken || this._getAccessToken() || null;
-      this._scheduleTokenRefresh();
-    }
-  }
-
-  /**
-   * Choose whether login/totp-validate/renew ask the daemon to issue a refresh token.
-   *
-   * A refresh token is a long-lived credential (TTL `max(2*access, access+1h)`), so a one-shot
-   * script that logs in, makes a call and exits would be handed a multi-day credential it
-   * neither stores nor revokes. Hence the caller decides.
-   *
-   * @param {boolean|null} [value=null] - `true`/`false` force the choice; `null` (default) follows
-   *   auto-refresh, which is already the "is this client long-lived?" signal — except in a browser.
-   *
-   * Browser asymmetry: the resolved default is `false` even with auto-refresh on. The auth cookie is
-   * HttpOnly precisely so XSS cannot reach it; a refresh token held in JS memory would hand that back
-   * to any injected script, and for far longer. Nothing in the browser needs it either — pacing reads
-   * `expire_time`/`issued_at` from the response body and renewal goes through the cookie. An explicit
-   * `true` is still honoured.
-   */
-  set_use_refresh_token(value = null) {
-    this._useRefreshToken = value;
-  }
-
-  /**
-   * Resolve the refresh-token tri-state for the outgoing request.
-   * @returns {boolean} true to send the opt-in header; false to omit it entirely
-   * @private
-   */
-  _wantRefreshToken() {
-    if (typeof this._useRefreshToken === 'boolean') return this._useRefreshToken;
-    return ENV.isNode && this._autoRefreshEnabled;
-  }
-
-  /** @private */
-  _stopAutoRefresh() {
-    this._autoRefreshEnabled = false;
-    this._refreshFailures = 0;
-    if (this._refreshTimer) {
-      clearTimeout(this._refreshTimer);
-      this._refreshTimer = null;
-    }
-  }
-
-  /**
-   * Seconds before expiry at which to renew: a fraction of the token's own lifetime,
-   * floored at TOKEN_REFRESH_OFFSET_SECONDS.
-   * @param {string} token - JWT the margin is derived from (also seeds the jitter)
-   * @param {number} exp - Expiry claim, epoch seconds
-   * @param {number} iat - Issued-at claim, epoch seconds; 0 when absent
-   * @returns {number} Margin in seconds
-   * @private
-   */
-  static _refreshMargin(token, exp, iat) {
-    const lifetime = (iat > 0 && exp > iat) ? exp - iat : exp - Date.now() / 1000;
-    let margin = Math.max(lifetime * (1 - CONSTANTS.TOKEN_REFRESH_LIFETIME_RATIO), CONSTANTS.TOKEN_REFRESH_OFFSET_SECONDS);
-
-    // Jitter derived from the token: stable across polls, distinct per client.
-    const spread = margin * CONSTANTS.TOKEN_REFRESH_JITTER_RATIO;
-    margin += ((_fnv1a32(token) % 2001) / 1000 - 1) * spread;
-
-    // Clamp last: the 30s floor (and its jitter) must never exceed the token's own life,
-    // or every renewal would land past the refresh point and the loop would spin at ~1Hz.
-    return lifetime > 0 ? Math.min(margin, lifetime / 2) : margin;
   }
 
-  /**
-   * Bounded exponential backoff for the nth consecutive renewal failure (n >= 1).
-   * @param {number} failures - Consecutive failure count
-   * @returns {number} Delay in seconds
-   * @private
-   */
-  static _refreshRetryDelay(failures) {
-    const shift = Math.min(Math.max(failures - 1, 0), 16);
-    return Math.min(CONSTANTS.TOKEN_REFRESH_RETRY_BASE_SECONDS * Math.pow(2, shift), CONSTANTS.TOKEN_REFRESH_RETRY_MAX_SECONDS);
-  }
-
-  /**
-   * Decide how long to sleep and whether a renewal is due when that sleep ends.
-   * The sleep is capped at the poll interval so a token replaced elsewhere is noticed;
-   * waking early is not by itself a reason to renew.
-   * @returns {{delaySec: number, due: boolean}}
-   * @private
-   */
-  _computeRefreshPlan() {
-    const poll = CONSTANTS.TOKEN_REFRESH_POLL_SECONDS;
-
-    const token = this._autoRefreshJwt || this._getAccessToken();
-    const tokenTimes = token ? _decodeJwtTimes(token) : null;
-
-    // In a browser the auth cookie is HttpOnly, so the token is never readable here. Pace
-    // off the lifetime the daemon reported in the login/renew body instead — same 60% rule
-    // as every other SDK, rather than the fixed cadence this change exists to remove.
-    //
-    // Prefer whichever source expires later. _autoRefreshJwt is set once by
-    // set_auto_refresh_token and never updated in a browser (_handleTokenUpdate is
-    // Node-only), so a frozen copy would otherwise shadow the times every renewal
-    // refreshes — and once it aged past its refresh point the loop would renew once per
-    // second forever, which is far worse than the cadence this replaced.
-    const times = this._tokenTimes && (!tokenTimes || this._tokenTimes.exp > tokenTimes.exp)
-      ? this._tokenTimes
-      : tokenTimes;
-
-    if (!token && !times) {
-      // A held refresh token can still mint a new access token, so an access token lost
-      // to an expired cookie is recoverable — but only if we actually try.
-      if (this._refreshToken) return { delaySec: 1, due: true };
-      return { delaySec: poll, due: false }; // nothing to renew, just idle
-    }
-    if (!times) return { delaySec: poll, due: true }; // unreadable lifetime: fixed cadence
-
-    const nowSec = Date.now() / 1000;
-    // Times saying the session is already dead cannot be acted on once per second: a
-    // successful renewal would have replaced them, so they are stale rather than urgent.
-    // Fall back to the fixed cadence, which bounds the worst case at the poll interval.
-    if (times.exp <= nowSec) return { delaySec: poll, due: true };
-
-    // Jitter needs a per-client seed; without a readable token the session times alone
-    // would collide for every client that logged in during the same second, so mix in
-    // this client's own random seed.
-    const seed = token || `${this._jitterSeed}.${times.iat}.${times.exp}`;
-    const wait = times.exp - AppMeshClient._refreshMargin(seed, times.exp, times.iat) - nowSec;
-    if (wait <= 0) return { delaySec: 1, due: true };  // at or past the refresh point
-    if (wait > poll) return { delaySec: poll, due: false }; // not due; wake only to re-evaluate
-    return { delaySec: wait, due: true };
-  }
-
-  /** @private */
-  _scheduleTokenRefresh() {
-    if (!this._autoRefreshEnabled) return;
-
-    // Replace any pending timer so re-scheduling (e.g. from _handleTokenUpdate) never stacks timers
-    if (this._refreshTimer) {
-      clearTimeout(this._refreshTimer);
-      this._refreshTimer = null;
-    }
-
-    let { delaySec, due } = this._computeRefreshPlan();
-    if (this._refreshFailures > 0) {
-      // Retry on the backoff schedule, not the stale plan.
-      delaySec = AppMeshClient._refreshRetryDelay(this._refreshFailures);
-      due = true;
-    }
-
-    this._refreshTimer = setTimeout(async () => {
-      this._refreshTimer = null;
-      if (!this._autoRefreshEnabled) return;
-      if (due) {
-        try {
-          // _request captures the renewed token cookie and routes it through
-          // _handleTokenUpdate, which updates _autoRefreshJwt for precise delays
-          await this.renew_token();
-          if (this._refreshFailures > 0) {
-            console.info(`Auto-refresh: token renewal recovered after ${this._refreshFailures} failure(s)`);
-          }
-          this._refreshFailures = 0;
-        } catch (err) {
-          this._refreshFailures++;
-          // Log sparsely: a daemon outage must not flood at the backoff rate.
-          if (this._refreshFailures === 1 || this._refreshFailures % CONSTANTS.TOKEN_REFRESH_LOG_EVERY === 0) {
-            console.warn(`Auto-refresh: token renewal failed (attempt ${this._refreshFailures}):`, err.message);
-          }
-        }
-      }
-      this._scheduleTokenRefresh(); // keep the loop armed, failure or not
-    }, delaySec * 1000);
-
-    // Don't block Node.js process exit
-    if (this._refreshTimer.unref) {
-      this._refreshTimer.unref();
-    }
+  /** Return Engine's public Dex/OIDC configuration. */
+  async get_auth_config() {
+    return (await this._request("get", "/appmesh/auth/config")).data;
   }
 
-  /**
-   * Renew the current JWT token.
-   *
-   * A held refresh token is the sole credential the daemon needs, so renewal succeeds even
-   * after the access token expired — that is how a missed refresh window recovers without a
-   * re-login. Without one, the daemon authenticates the access token instead.
-   *
-   * @param {string|number} [tokenExpire] - Token expiry (integer seconds or ISO 8601 string).
-   *   Defaults to the value used at login; the header is omitted when that is unknown, so the
-   *   daemon applies its own default rather than silently extending a short-lived token.
-   */
-  async renew_token(tokenExpire = null) {
-    // Serialize renewals: rotation makes a refresh token single-use, so two concurrent
-    // renewals present the same one and the loser is told it is revoked — permanently
-    // wedging a client that holds no other credential. (See also the AppMeshWorker
-    // constructor docs on sharing one client instead of running two renew loops.)
-    const run = (this._renewChain || Promise.resolve()).then(() => this._renewTokenOnce(tokenExpire));
-    this._renewChain = run.catch(() => { /* a failed renewal must not break the queue */ });
-    return run;
-  }
-
-  /** @private */
-  async _renewTokenOnce(tokenExpire) {
-    const expire = (tokenExpire === null || tokenExpire === undefined) ? this._tokenExpireSeconds : tokenExpire;
-    const headers = {};
-    if (this._wantRefreshToken()) headers["X-Refresh-Token-Request"] = "true";
-    if (expire !== null && expire !== undefined) {
-      headers["X-Expire-Seconds"] = parseDuration(expire);
-    }
-    if (this._refreshToken) {
-      headers["X-Refresh-Token"] = this._refreshToken;
-    }
-
-    let response;
-    try {
-      response = await this._request("post", "/appmesh/token/renew", null, { headers });
-    } catch (error) {
-      // A rejected refresh token will never be accepted again (rotated away, revoked, or the
-      // session ended). Drop it so the next attempt presents the access token instead.
-      if (error && error.statusCode === 401) this._refreshToken = null;
-      throw error;
-    }
-    // Both modes rotate the refresh token on renew — store the new one for the next cycle.
-    this._captureRefreshToken(response);
-  }
-
-  /**
-   * Get the decoded OTP provisioning URI for the current user.
-   * @returns {Promise<string>} Decoded `otpauth://...` URI, not just the raw secret field
-   */
-  async get_totp_uri() {
-    const response = await this._request("post", "/appmesh/totp/secret");
-    return base64Utils.decode(response.data["mfa_uri"]);
-  }
-
-  /**
-   * Setup 2FA with a verification code and update the current session token cookie.
-   * @param {string} totpCode - TOTP verification code
-   */
-  async enable_totp(totpCode) {
-    const headers = { "X-Totp-Code": totpCode };
-    await this._request("post", "/appmesh/totp/setup", null, { headers });
-  }
-
-  /**
-   * Validate a TOTP login challenge and update the current session token cookie.
-   * @param {string} username - Username
-   * @param {string} totpChallenge - Server challenge
-   * @param {string} totpCode - TOTP code
-   * @param {string|number} [tokenExpire] - Token expiry in seconds or ISO8601 duration (e.g. "P1DT12H", 604800)
-   */
-  async validate_totp(username, totpChallenge, totpCode, tokenExpire = CONSTANTS.DEFAULT_TOKEN_EXPIRE_SECONDS) {
-    const body = {
-      "user_name": username,
-      "totp_code": totpCode,
-      "totp_challenge": totpChallenge,
-      "expire_seconds": parseDuration(tokenExpire)
-    };
-    // Set cookie header for browser
-    const headers = { "X-Set-Cookie": "true" };
-    if (this._wantRefreshToken()) headers["X-Refresh-Token-Request"] = "true";
-
-    const response = await this._request("post", "/appmesh/totp/validate", body, { headers });
-    // A validated challenge completes the login, so it owes the same session setup as
-    // login(); auto-refresh itself is (re)armed by _handleTokenUpdate when the token lands.
-    this._captureRefreshToken(response);
-    this._tokenExpireSeconds = tokenExpire ? parseDuration(tokenExpire) : null;
-  }
-
-  /**
-   * Disable TOTP for user
-   * @param {string} [user='self'] - Username
-   * @returns {Promise<boolean>} true on success; failures throw AppMeshError
-   */
-  async disable_totp(user = "self") {
-    await this._request("post", `/appmesh/totp/${user}/disable`);
-    return true;
+  /** Return the verified Dex principal represented by the current bearer. */
+  async get_current_principal() {
+    return (await this._request("get", "/appmesh/principal/self")).data;
   }
 
   /**
@@ -1359,88 +817,26 @@ class AppMeshClient {
   }
 
 
-  /**
-   * Change user password
-   * @param {string} oldPassword - Old password
-   * @param {string} newPassword - New password
-   * @param {string} [username="self"] - Username
-   * @returns {Promise<boolean>} true on success; failures throw AppMeshError
-   */
-  async update_password(oldPassword, newPassword, username = "self") {
-    const body = {
-      "old_password": base64Utils.encode(oldPassword),
-      "new_password": base64Utils.encode(newPassword)
-    };
-    await this._request("post", `/appmesh/user/${username}/passwd`, body);
-    return true;
-  }
-
-  /**
-   * Add new user
-   * @param {string} username - Username
-   * @param {Object} userData - User definition
-   * @returns {Promise<boolean>} true on success; failures throw AppMeshError
-   */
-  async add_user(username, userData) {
-    await this._request("put", `/appmesh/user/${username}`, userData);
-    return true;
-  }
-
-  /**
-   * Delete user
-   * @param {string} username - Username
-   * @returns {Promise<boolean>} true on success; failures throw AppMeshError
-   */
-  async delete_user(username) {
-    await this._request("delete", `/appmesh/user/${username}`);
-    return true;
+  /** List Engine authorization overlays keyed by immutable Dex principal ID. */
+  async list_principals() {
+    return (await this._request("get", "/appmesh/principals")).data;
   }
 
-  /**
-   * Lock user account
-   * @param {string} username - Username
-   * @returns {Promise<boolean>} true on success; failures throw AppMeshError
-   */
-  async lock_user(username) {
-    await this._request("post", `/appmesh/user/${username}/lock`);
+  /** Update an Engine authorization overlay; never mutate IdP account data. */
+  async update_principal(principalId, policy) {
+    await this._request("post", `/appmesh/principal/${encodeURIComponent(principalId)}`, policy);
     return true;
   }
 
-  /**
-   * Unlock user account
-   * @param {string} username - Username
-   * @returns {Promise<boolean>} true on success; failures throw AppMeshError
-   */
-  async unlock_user(username) {
-    await this._request("post", `/appmesh/user/${username}/unlock`);
+  /** Delete only an Engine authorization overlay. */
+  async delete_principal(principalId) {
+    await this._request("delete", `/appmesh/principal/${encodeURIComponent(principalId)}`);
     return true;
   }
 
-  /**
-   * Get user list
-   * @returns {Object[]} User array
-   */
-  async list_users() {
-    const response = await this._request("get", "/appmesh/users");
-    return response.data;
-  }
-
-  /**
-   * Get current user info
-   * @returns {Object} User properties
-   */
+  /** Safe compatibility alias returning a Principal, not an IdP user. */
   async get_current_user() {
-    const response = await this._request("get", "/appmesh/user/self");
-    return response.data;
-  }
-
-  /**
-   * Get all user groups
-   * @returns {Object[]} Group array
-   */
-  async list_groups() {
-    const response = await this._request("get", "/appmesh/user/groups");
-    return response.data;
+    return this.get_current_principal();
   }
 
   /**
@@ -1452,15 +848,17 @@ class AppMeshClient {
     return response.data;
   }
 
-  /**
-   * Get user permissions
-   * @returns {Object[]} Permission array
-   */
-  async get_user_permissions() {
-    const response = await this._request("get", "/appmesh/user/permissions");
+  /** Get effective permissions for the current verified principal. */
+  async get_principal_permissions() {
+    const response = await this._request("get", "/appmesh/principal/self/permissions");
     return response.data;
   }
 
+  /** Safe compatibility alias for get_principal_permissions(). */
+  async get_user_permissions() {
+    return this.get_principal_permissions();
+  }
+
   /**
    * Get all roles and permissions
    * @returns {Object[]} Role array
@@ -1544,6 +942,11 @@ class AppMeshClient {
       headers[CONSTANTS.HTTP_USER_AGENT_HEADER_NAME] = CONSTANTS.HTTP_USER_AGENT;
     }
 
+    const token = this._getAccessToken();
+    if (token) {
+      headers[CONSTANTS.HTTP_HEADER_KEY_AUTH] = `Bearer ${token}`;
+    }
+
     // Add forwarding host if specified
     if (this.forwardingHost) {
       if (this.forwardingHost.includes(":")) {
@@ -1588,7 +991,7 @@ class AppMeshClient {
       const requestConfig = {
         method,
         url: path,
-        withCredentials: true,  // for browser send cookie
+        withCredentials: false,
         ...config,
         headers: { ...headers },
         params: { ...params }
@@ -1599,39 +1002,13 @@ class AppMeshClient {
       }
 
       const response = await this._client(requestConfig);
-      if (response.status !== 200) {
+      if (response.status < 200 || response.status >= 300) {
         const errMsg = this._extractErrorMessage(response.data);
-        if (response.status === CONSTANTS.HTTP_STATUS_PRECONDITION_REQUIRED) {
-          throw new TotpRequiredError(errMsg, response.data);
-        }
         throw new AppMeshError(errMsg, response.status, response.data);
       }
 
-      // axios response header use lower case
-      if (ENV.isNode && response.headers['Set-Cookie'.toLowerCase()]) {
-        // Handle array of cookies or single cookie
-        const cookies = Array.isArray(response.headers['Set-Cookie'.toLowerCase()]) ?
-          response.headers['Set-Cookie'.toLowerCase()] :
-          [response.headers['Set-Cookie'.toLowerCase()]];
-
-        // Join all cookies with semicolon separator
-        this._client.defaults.headers.Cookie = cookies.join('; ');
-
-        // Keep the in-memory token store in sync with the server-issued cookie
-        // (login, renew, authenticate, TOTP setup/validate)
-        const authCookie = cookies
-          .map(c => c.split(';')[0].trim())
-          .find(c => c.startsWith('appmesh_auth_token='));
-        if (authCookie) {
-          this._handleTokenUpdate(authCookie.substring('appmesh_auth_token='.length));
-        }
-      }
-
       return response;
     } catch (error) {
-      if (error instanceof AppMeshError && error.statusCode === CONSTANTS.HTTP_STATUS_PRECONDITION_REQUIRED) {
-        throw error;
-      }
       throw this.onError(error);
     }
   }
@@ -1766,5 +1143,5 @@ class AppRun {
 }
 
 // Export the main classes
-export { AppMeshClient, AppOutput, AppRun, AppMeshError, TotpRequiredError, AppRemovedError, TransportDisconnectedError, DEFAULT_CA_FILE };
+export { AppMeshClient, AppOutput, AppRun, AppMeshError, AppRemovedError, TransportDisconnectedError, DEFAULT_CA_FILE };
 export default AppMeshClient;