@rodit/rodit-auth-be 9.16.2 → 9.17.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `@rodit/rodit-auth-be` are documented here.
 
+## [9.17.0] — 2026-10-06
+
+### Fixed
+
+- **`nearorg_rpc_tokenfromroditid`:** a failed NEAR RPC call no longer looks like a
+  missing token. An empty `RODiT` is returned only when the `rodit_token` view
+  completes and decodes to JSON `null`. HTTP errors (including 402/403 credit
+  exhaustion), JSON-RPC `error` objects, WASM errors, and undecodable results
+  throw `NearRpcError` with the HTTP status and provider message. The function
+  catch rethrows that error instead of returning `new RODiT()`.
+
 ## [9.16.2] — 2026-09-19
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@ Node.js / Express SDK for RODiT-based mutual authentication, authorization, sess
 
 **npm:** [https://www.npmjs.com/package/@rodit/rodit-auth-be](https://www.npmjs.com/package/@rodit/rodit-auth-be)  
 **Monorepo:** [discernible-io/rodit-sdk](https://github.com/discernible-io/rodit-sdk) (this directory)  
-**Version:** 9.16.2 · **License:** Proprietary · **Author:** Discernible IO
+**Version:** 9.17.0 · **License:** Proprietary · **Author:** Discernible IO
 
 ## Production deployments
 

package/index.js

@@ -18,6 +18,7 @@ const {
   authenticate_logout,
   login_client,
   logout_client,
+  refresh_client,
   login_client_withnep413,
   login_portal,
   login_server,
@@ -160,6 +161,17 @@ class RoditClient {
     return authenticate_logout;
   }
 
+  /**
+   * Optional refresh auth middleware (same tolerance as logout: signature-valid
+   * expired tokens allowed). Only relevant if the host mounts POST /api/refresh;
+   * default SERVER-INITIATED renewals do not require this route.
+   *
+   * @returns {Function} Refresh authentication middleware function
+   */
+  get authenticateForRefresh() {
+    return authenticate_logout;
+  }
+
   /**
    * Get permissions validation middleware (clean syntax)
    * @returns {Function} Permissions validation middleware function
@@ -1042,6 +1054,27 @@ class RoditClient {
     return await logout_client(req, res);
   }
 
+  /**
+   * Optional Express handler for client-initiated token refresh (POST /api/refresh).
+   * Normally unnecessary: default SERVER-INITIATED mode renews credentials on
+   * authenticate and returns New-Token. Mount only for idle-client refresh or
+   * when SECURITY_OPTIONS.SERVERORCLIENT=CLIENT-INITIATED.
+   *
+   * @param {Object} req - Express request object
+   * @param {Object} res - Express response object
+   * @returns {Promise<*>} Express response
+   */
+  async refresh_client(req, res) {
+    logger.debug('Processing Express token refresh request', {
+      component: 'RoditClient',
+      method: 'refresh_client',
+      path: req.path,
+      ip: req.ip
+    });
+
+    return await refresh_client(req, res);
+  }
+
   /**
    * Login to a peer RODiT API using RODiT id (matches login_client / POST /api/login).
    *
@@ -1838,19 +1871,71 @@ class RoditClient {
   }
   
   /**
-   * Refresh the authentication token by calling `login_server` (RODiT id flow, default `POST /api/login`).
+   * Refresh the access credential. Prefers optional peer POST /api/refresh when
+   * available; otherwise falls back to full `login_server`. Under default
+   * SERVER-INITIATED deployments, routine renewal is handled by the server via
+   * New-Token on authenticated calls — this method is for explicit refresh or
+   * re-login after hard expiry.
+   * @param {Object} [options]
+   * @param {string} [options.refreshPath='/api/refresh'] - Refresh endpoint path
+   * @param {boolean} [options.preferLogin=false] - Force re-login instead of refresh
    * @returns {Promise<string>} New token
    */
-  async refreshToken() {
+  async refreshToken(options = {}) {
+    const refreshPath = options.refreshPath || '/api/refresh';
+    const preferLogin = options.preferLogin === true;
+
     logger.debug('Refreshing authentication token', {
       component: 'RoditClient',
-      method: 'refreshToken'
+      method: 'refreshToken',
+      refreshPath,
+      preferLogin
     });
 
-    await this.login_server();
-    const refreshedToken = await this.getSessionToken();
+    if (!preferLogin && this.jwt_token) {
+      try {
+        const base =
+          this.apiEndpoint ||
+          config.get('API_DEFAULT_OPTIONS.API_ENDPOINT', '') ||
+          '';
+        if (base) {
+          const url = `${String(base).replace(/\/$/, '')}${
+            refreshPath.startsWith('/') ? refreshPath : `/${refreshPath}`
+          }`;
+          const refreshResponse = await fetch(url, {
+            method: 'POST',
+            headers: {
+              Authorization: `Bearer ${this.jwt_token}`,
+              'Content-Type': 'application/json',
+            },
+          });
+          if (refreshResponse.ok) {
+            const body = await refreshResponse.json().catch(() => ({}));
+            const headerToken =
+              typeof refreshResponse.headers?.get === 'function'
+                ? refreshResponse.headers.get('New-Token')
+                : null;
+            const newToken = body.token || body.jwt_token || headerToken;
+            if (newToken) {
+              this.jwt_token = newToken;
+              if (typeof this.setSessionToken === 'function') {
+                await this.setSessionToken(newToken);
+              }
+              return newToken;
+            }
+          }
+        }
+      } catch (refreshError) {
+        logger.warn('Client-initiated refresh failed; falling back to login_server', {
+          component: 'RoditClient',
+          method: 'refreshToken',
+          error: refreshError.message
+        });
+      }
+    }
 
-    return refreshedToken;
+    await this.login_server();
+    return this.getSessionToken();
   }
   
   /**
@@ -1920,7 +2005,7 @@ class RoditClient {
 }
 
 // Import health check and retry functions
-const { healthCheckRPC, resolveHealthyNearRpcUrl, fetchWithRetry } = require('./lib/blockchain/blockchainservice');
+const { healthCheckRPC, resolveHealthyNearRpcUrl, fetchWithRetry, NearRpcError } = require('./lib/blockchain/blockchainservice');
 
 // Export the RoditClient class and commonly used SDK components
 module.exports = {
@@ -1941,6 +2026,7 @@ module.exports = {
   authenticate_logout,
   login_client,
   logout_client,
+  refresh_client,
   login_client_withnep413,
   login_portal,
   login_server,
@@ -1966,6 +2052,7 @@ module.exports = {
   VersionManager,
   // Blockchain service functions
   nearorg_rpc_timestamp: blockchainService.nearorg_rpc_timestamp,
+  NearRpcError,
   // Startup validation and health check functions
   validateConfig: config.validate,
   healthCheckRPC,

package/lib/auth/tokenservice.js

@@ -977,9 +977,15 @@ function resolveCredentialExpirationUnix(now, sessionExpiration, own_rodit) {
               tokenJti: token.jti,
             });
 
-            throw new Error("Session inactive or closed");
+            const closedError = new Error("Session inactive or closed");
+            closedError.code = "SESSION_CLOSED";
+            closedError.renewalReason = "session_closed";
+            throw closedError;
           }
         } catch (sessionError) {
+          if (sessionError.renewalReason === "session_closed" || sessionError.code === "SESSION_CLOSED") {
+            throw sessionError;
+          }
           logger.error("Session check failed", {
             component: "JwtAuth",
             method: "generate_jwt_token_fromtoken",
@@ -988,7 +994,10 @@ function resolveCredentialExpirationUnix(now, sessionExpiration, own_rodit) {
             error: sessionError.message,
           });
           // Fail closed for session validation errors during renewal.
-          throw new Error(`Session check failed: ${sessionError.message}`);
+          const checkFailed = new Error(`Session check failed: ${sessionError.message}`);
+          checkFailed.code = "SESSION_CLOSED";
+          checkFailed.renewalReason = "session_closed";
+          throw checkFailed;
         }
       }
 
@@ -1795,45 +1804,92 @@ function resolveCredentialExpirationUnix(now, sessionExpiration, own_rodit) {
       };
   
       let newToken = null;
-      if (!options.allowExpiredToken) {
-        // Check if token needs renewal or is expired
+      const serverOrClient = String(
+        config.get("SECURITY_OPTIONS.SERVERORCLIENT", "SERVER-INITIATED")
+      ).toUpperCase();
+      const clientInitiatedRenewal = serverOrClient === "CLIENT-INITIATED";
+      const forceCredentialRenewal = options.forceCredentialRenewal === true;
+
+      if (forceCredentialRenewal) {
         const renewalResult = await checkandrenew_jwt_token(
           payload,
           Math.floor(Date.now() / 1000),
           requestId,
-          isExpired
+          true
         );
         newToken = renewalResult.newToken;
-        
-        if (isExpired && !newToken) {
-          const renewalNow = Math.floor(Date.now() / 1000);
-          const sessionExpUnix =
-            payload.session_exp != null ? Number(payload.session_exp) : null;
-          const sessionStillActive =
-            Number.isFinite(sessionExpUnix) && sessionExpUnix > renewalNow;
-
-          if (sessionStillActive) {
-            logger.warn(
-              "Credential expired and renewal failed but session still active; allowing request",
-              {
+        if (renewalResult.reason === "session_closed") {
+          throw new Error("Error 012: Session is not active");
+        }
+        if (!newToken) {
+          const renewFail = new Error(
+            "Error 007: Token has expired and renewal failed"
+          );
+          renewFail.code = "RENEWAL_FAILED";
+          renewFail.renewalReason = renewalResult.reason || "renewal_failed";
+          throw renewFail;
+        }
+      } else if (!options.allowExpiredToken) {
+        if (clientInitiatedRenewal && !isExpired) {
+          // CLIENT-INITIATED: skip piggyback renewal; client must call /api/refresh.
+          newToken = null;
+        } else if (clientInitiatedRenewal && isExpired) {
+          logger.error(
+            "Token expired under CLIENT-INITIATED mode; client must refresh explicitly",
+            {
+              component: "JwtAuth",
+              method: "validate_jwt_token_be",
+              requestId,
+              jti: payload.jti,
+            }
+          );
+          throw new Error("Error 007: Token has expired and renewal failed");
+        } else {
+          // SERVER-INITIATED: renew on authenticate when eligible or expired
+          const renewalResult = await checkandrenew_jwt_token(
+            payload,
+            Math.floor(Date.now() / 1000),
+            requestId,
+            isExpired
+          );
+          newToken = renewalResult.newToken;
+
+          if (renewalResult.reason === "session_closed") {
+            throw new Error("Error 012: Session is not active");
+          }
+
+          if (isExpired && !newToken) {
+            const renewalNow = Math.floor(Date.now() / 1000);
+            const sessionExpUnix =
+              payload.session_exp != null ? Number(payload.session_exp) : null;
+            const sessionStillActive =
+              Number.isFinite(sessionExpUnix) && sessionExpUnix > renewalNow;
+
+            if (sessionStillActive) {
+              logger.warn(
+                "Credential expired and renewal failed but session still active; allowing request",
+                {
+                  component: "JwtAuth",
+                  method: "validate_jwt_token_be",
+                  requestId,
+                  jti: payload.jti,
+                  sessionExp: sessionExpUnix,
+                  now: renewalNow,
+                  renewalReason: renewalResult.reason || "renewal_failed",
+                }
+              );
+            } else {
+              logger.error("Token expired and renewal failed", {
                 component: "JwtAuth",
                 method: "validate_jwt_token_be",
                 requestId,
                 jti: payload.jti,
                 sessionExp: sessionExpUnix,
-                now: renewalNow,
-              }
-            );
-          } else {
-            logger.error("Token expired and renewal failed", {
-              component: "JwtAuth",
-              method: "validate_jwt_token_be",
-              requestId,
-              jti: payload.jti,
-              sessionExp: sessionExpUnix,
-            });
+                renewalReason: renewalResult.reason || "renewal_failed",
+              });
 
-            throw new Error("Error 007: Token has expired and renewal failed");
+              throw new Error("Error 007: Token has expired and renewal failed");
+            }
           }
         }
       } else if (isExpired) {
@@ -2472,7 +2528,7 @@ async function thorough_validate_jwt_token_be(token, requestId = ulid()) {
         session_status: payload.session_status || "unknown",
         seconds_until_eligibility: secondsUntilEligibility,
       });
-      return { newToken: null };
+      return { newToken: null, reason: null };
     }
 
     // Token needs renewal
@@ -2602,6 +2658,7 @@ async function thorough_validate_jwt_token_be(token, requestId = ulid()) {
 
         return {
           newToken,
+          reason: null,
           logInfo: {
             newDuration: newduration,
             reason: shouldDoFullVerification
@@ -2618,15 +2675,35 @@ async function thorough_validate_jwt_token_be(token, requestId = ulid()) {
         };
       }
     } catch (error) {
+      const sessionClosed =
+        error.renewalReason === "session_closed" ||
+        error.code === "SESSION_CLOSED" ||
+        /session inactive or closed/i.test(error.message || "");
+
       logger.error("Token renewal failed", {
         component: "TokenRenewalService",
         method: "checkandrenew_jwt_token",
         requestId,
         error: error.message,
+        reason: sessionClosed ? "session_closed" : "renewal_failed",
+      });
+
+      const totalDuration = Date.now() - startTime;
+      logger.metric("token_renewal_check_duration_ms", totalDuration, {
+        component: "TokenRenewalService",
+        renewalNeeded: true,
+        success: false,
+        session_status: payload.session_status || "unknown",
+        reason: sessionClosed ? "session_closed" : "renewal_failed",
       });
+
+      return {
+        newToken: null,
+        reason: sessionClosed ? "session_closed" : "renewal_failed",
+      };
     }
 
-    // If we reach here, renewal wasn't successful
+    // If we reach here, renewal wasn't successful (verification returned invalid)
     const totalDuration = Date.now() - startTime;
     logger.debug("Token renewal not performed", {
       component: "TokenRenewalService",
@@ -2641,9 +2718,10 @@ async function thorough_validate_jwt_token_be(token, requestId = ulid()) {
       renewalNeeded: true,
       success: false,
       session_status: payload.session_status || "unknown",
+      reason: "verification_failed",
     });
 
-    return { newToken: null };
+    return { newToken: null, reason: "verification_failed" };
   }
 
 

package/lib/blockchain/blockchainservice.js

@@ -82,6 +82,96 @@ class RODiT {
   }
 }
 
+/**
+ * A NEAR RPC query failed before a completed view result was available.
+ * `status` is the HTTP status. `message` includes that status and the
+ * provider text (including credit or quota notices). `creditFailure` is set
+ * for HTTP 402 and for messages that say the provider is out of credits.
+ *
+ * A completed `rodit_token` view whose decoded value is JSON null is not this
+ * error: that path returns an empty RODiT.
+ */
+class NearRpcError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ status?: number|null, providerMessage?: string, creditFailure?: boolean }} [details]
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "NearRpcError";
+    this.status = details.status == null ? null : details.status;
+    this.providerMessage = details.providerMessage || "";
+    this.creditFailure = details.creditFailure === true;
+  }
+}
+
+function clipRpcText(value, max = 500) {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}...`;
+}
+
+function describeRpcError(errorField) {
+  if (errorField == null) return "";
+  if (typeof errorField === "string") return clipRpcText(errorField);
+  if (typeof errorField === "object") {
+    const message = errorField.message || errorField.name || "";
+    const code = errorField.code != null ? ` (${errorField.code})` : "";
+    let dataText = "";
+    if (errorField.data != null) {
+      dataText = typeof errorField.data === "string"
+        ? errorField.data
+        : JSON.stringify(errorField.data);
+    }
+    const combined = [message ? `${message}${code}` : "", dataText].filter(Boolean).join(": ");
+    return clipRpcText(combined || JSON.stringify(errorField));
+  }
+  return clipRpcText(errorField);
+}
+
+function looksLikeCreditFailure(status, text) {
+  if (status === 402) return true;
+  return /credit|quota|payment required|insufficient (balance|funds)/i.test(text || "");
+}
+
+function nearRpcFailure(status, providerMessage) {
+  const detail = providerMessage ? clipRpcText(providerMessage) : "";
+  const message = detail
+    ? `NEAR RPC call failed (HTTP ${status}): ${detail}`
+    : `NEAR RPC call failed (HTTP ${status})`;
+  return new NearRpcError(message, {
+    status,
+    providerMessage: detail,
+    creditFailure: looksLikeCreditFailure(status, detail)
+  });
+}
+
+async function readResponseErrorMessage(response) {
+  let bodyText = "";
+  try {
+    bodyText = await response.text();
+  } catch (_readError) {
+    bodyText = "";
+  }
+  const trimmed = bodyText.trim();
+  if (!trimmed) {
+    return response.statusText ? clipRpcText(response.statusText) : "";
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && parsed.error) {
+      const described = describeRpcError(parsed.error);
+      if (described) return described;
+    }
+    if (parsed && typeof parsed.message === "string" && parsed.message.trim()) {
+      return clipRpcText(parsed.message);
+    }
+  } catch (_parseError) {
+    // Credit notices are often plain text rather than JSON-RPC.
+  }
+  return clipRpcText(trimmed);
+}
+
 /**
  * Payload class for NEP-413 standard
  */
@@ -340,10 +430,16 @@ const PayloadNEP413Schema = {
   }
 
   /**
-   * Fetches a RODiT token by ID from the NEAR blockchain
-   * 
+   * Fetches a RODiT token by ID from the NEAR blockchain.
+   *
+   * An empty RODiT (no token_id) is returned only when the view call completes
+   * and the contract decodes to JSON null (token absent). HTTP failures,
+   * JSON-RPC errors, credit exhaustion, WASM errors, and undecodable results
+   * throw NearRpcError.
+   *
    * @param {string} roditid - RODiT token ID to fetch
    * @returns {Promise<RODiT>} RODiT token object
+   * @throws {NearRpcError} When the NEAR RPC call does not yield a completed view
    */
   async function nearorg_rpc_tokenfromroditid(roditid) {
     const requestId = ulid();
@@ -423,13 +519,16 @@ const PayloadNEP413Schema = {
 
       if (!response.ok) {
         const duration = Date.now() - startTime;
+        const providerMessage = await readResponseErrorMessage(response);
+        const httpError = nearRpcFailure(response.status, providerMessage);
         
         // Add metric for failed RPC calls
         logger.metric("near_rpc_calls", fetchDuration, {
           result: "failure",
-          reason: `HTTP error from blockchain RPC: status ${response.status}`,
+          reason: httpError.message,
           status_code: response.status,
           method: "rodit_token",
+          credit_failure: httpError.creditFailure ? "true" : "false",
         });
         
         logErrorWithMetrics(
@@ -437,27 +536,37 @@ const PayloadNEP413Schema = {
           {
             ...baseContext,
             statusCode: response.status,
+            providerMessage: httpError.providerMessage,
+            creditFailure: httpError.creditFailure,
             duration,
             result: 'failure',
-            reason: `HTTP error from blockchain RPC: status ${response.status}`
+            reason: httpError.message
           },
-          new Error(`HTTP error! status: ${response.status}`),
+          httpError,
           "near_rpc_http_error",
           {
             result: "failure",
-            reason: `HTTP error from blockchain RPC: status ${response.status}`,
+            reason: httpError.message,
             status_code: response.status,
             method: "rodit_token",
             duration
           }
         );
 
-        return new RODiT();
+        throw httpError;
       }
 
       const parseStartTime = Date.now();
       const responseText = await response.text();
-      const parsedJson = JSON.parse(responseText);
+      let parsedJson;
+      try {
+        parsedJson = JSON.parse(responseText);
+      } catch (error) {
+        throw nearRpcFailure(
+          response.status,
+          `Failed to parse NEAR RPC response: ${error.message}`
+        );
+      }
       const parseDuration = Date.now() - parseStartTime;
 
       logger.debugWithContext("RPC response parsed", {
@@ -466,15 +575,60 @@ const PayloadNEP413Schema = {
         hasResult: !!parsedJson.result
       });
 
+      if (parsedJson.error) {
+        const duration = Date.now() - startTime;
+        const rpcError = nearRpcFailure(
+          response.status,
+          describeRpcError(parsedJson.error)
+        );
+
+        logger.metric("near_rpc_calls", fetchDuration, {
+          result: "failure",
+          reason: rpcError.message,
+          status_code: response.status,
+          method: "rodit_token",
+          credit_failure: rpcError.creditFailure ? "true" : "false",
+        });
+
+        logErrorWithMetrics(
+          "JSON-RPC error from blockchain RPC",
+          {
+            ...baseContext,
+            statusCode: response.status,
+            rpcError: parsedJson.error,
+            providerMessage: rpcError.providerMessage,
+            creditFailure: rpcError.creditFailure,
+            duration,
+            result: 'failure',
+            reason: rpcError.message
+          },
+          rpcError,
+          "near_rpc_jsonrpc_error",
+          {
+            result: "failure",
+            reason: rpcError.message,
+            status_code: response.status,
+            method: "rodit_token",
+            duration
+          }
+        );
+
+        throw rpcError;
+      }
+
       if (parsedJson.result && parsedJson.result.error) {
         const duration = Date.now() - startTime;
+        const wasmText = typeof parsedJson.result.error === "string"
+          ? parsedJson.result.error
+          : JSON.stringify(parsedJson.result.error);
+        const wasmError = nearRpcFailure(response.status, `WASM execution error: ${wasmText}`);
         
         // Add metric for WASM errors
         logger.metric("near_rpc_wasm_errors", 1, {
           method: "rodit_token",
           rodit_id: roditid,
           result: 'failure',
-          reason: `WASM execution error: ${parsedJson.result.error}`
+          reason: wasmError.message
         });
         
         logErrorWithMetrics(
@@ -484,25 +638,26 @@ const PayloadNEP413Schema = {
             wasmError: parsedJson.result.error,
             duration,
             result: 'failure',
-            reason: `WASM execution error: ${parsedJson.result.error}`
+            reason: wasmError.message
           },
-          new Error(`WASM execution error: ${parsedJson.result.error}`),
+          wasmError,
           "near_rpc_wasm_error",
           {
             method: "rodit_token",
             rodit_id: roditid,
             duration,
             result: 'failure',
-            reason: `WASM execution error: ${parsedJson.result.error}`
+            reason: wasmError.message
           }
         );
 
-        return new RODiT();
+        throw wasmError;
       }
 
-      const resultArray = parsedJson.result.result;
+      const resultArray = parsedJson.result && parsedJson.result.result;
       if (!Array.isArray(resultArray)) {
         const duration = Date.now() - startTime;
+        const formatError = nearRpcFailure(response.status, "Result is not an array");
         
         // Add metric for format errors
         logger.metric("near_rpc_format_errors", 1, {
@@ -510,7 +665,7 @@ const PayloadNEP413Schema = {
           rodit_id: roditid,
           error_type: "invalid_array",
           result: 'failure',
-          reason: 'Invalid result format: not an array'
+          reason: formatError.message
         });
         
         logErrorWithMetrics(
@@ -520,9 +675,9 @@ const PayloadNEP413Schema = {
             resultType: typeof resultArray,
             duration,
             result: 'failure',
-            reason: 'Invalid result format: not an array'
+            reason: formatError.message
           },
-          new Error("Result is not an array"),
+          formatError,
           "near_rpc_format_error",
           {
             method: "rodit_token",
@@ -530,11 +685,11 @@ const PayloadNEP413Schema = {
             error_type: "invalid_array",
             duration,
             result: 'failure',
-            reason: 'Invalid result format: not an array'
+            reason: formatError.message
           }
         );
 
-        return new RODiT();
+        throw formatError;
       }
 
       const decodeStartTime = Date.now();
@@ -544,24 +699,28 @@ const PayloadNEP413Schema = {
       try {
         parsed = JSON.parse(resultString);
       } catch (error) {
+        const parseError = nearRpcFailure(
+          response.status,
+          `Failed to parse RODiT data: ${error.message}`
+        );
         logErrorWithMetrics(
           "Failed to parse RODiT data",
           {
             ...baseContext,
             error: error.message,
             result: 'failure',
-            reason: `Failed to parse RODiT data: ${error.message}`
+            reason: parseError.message
           },
-          error,
+          parseError,
           "rodit_parse_error",
           {
             error_type: error.name || "Unknown",
             rodit_id: roditid,
             result: 'failure',
-            reason: `Failed to parse RODiT data: ${error.message}`
+            reason: parseError.message
           }
         );
-        return new RODiT();
+        throw parseError;
       }
       
       const decodeDuration = Date.now() - decodeStartTime;
@@ -610,13 +769,18 @@ const PayloadNEP413Schema = {
           roditMetadata: rodit.metadata
         });
       } else {
+        const formatError = nearRpcFailure(
+          response.status,
+          "Invalid RODiT data format from blockchain"
+        );
         logger.warnWithContext("Invalid RODiT data format", {
           ...baseContext,
           parsedType: typeof parsed,
           parsedValue: parsed,
           result: 'failure',
-          reason: 'Invalid RODiT data format from blockchain'
+          reason: formatError.message
         });
+        throw formatError;
       }
 
       const totalDuration = Date.now() - startTime;
@@ -675,7 +839,7 @@ const PayloadNEP413Schema = {
         }
       );
 
-      return new RODiT();
+      throw error;
     }
   }
 
@@ -1697,6 +1861,7 @@ async function fetchWithRetry(url, options, maxRetries = 3) {
 
 module.exports = {
     RODiT,
+    NearRpcError,
     PayloadNEP413,
     PayloadNEP413Schema,
     CONSTANTS,

package/lib/middleware/authenticationmw.js

@@ -1343,6 +1343,191 @@ async function login_client(req, res) {
     }
   }
 
+  /**
+   * Optional client-initiated access-credential refresh.
+   * Not required for default SERVER-INITIATED deployments: the server renews
+   * access JWTs on authenticated API calls and returns them via New-Token.
+   * Mount POST /api/refresh only for idle-client timers or CLIENT-INITIATED mode.
+   *
+   * @param {Object} req - Express request object
+   * @param {Object} res - Express response object
+   * @returns {Object} Response object
+   */
+  async function refresh_client(req, res) {
+    const requestId = ulid();
+    const startTime = Date.now();
+    const baseContext = createLogContext(
+      "AuthenticationService",
+      "refresh_client",
+      {
+        requestId,
+        path: req.path,
+        method: req.method,
+        ip: req.ip,
+      }
+    );
+
+    logger.infoWithContext("Token refresh request received", {
+      ...baseContext,
+      userAgent: req.get("User-Agent"),
+    });
+
+    try {
+      verifySessionManager();
+
+      const jwt_token =
+        req.headers.authorization &&
+        req.headers.authorization.startsWith("Bearer ")
+          ? req.headers.authorization.substring(7)
+          : null;
+
+      if (!jwt_token) {
+        logger.metric &&
+          logger.metric("token_refresh_attempts", 1, {
+            component: "AuthenticationService",
+            result: "no_jwt_token",
+          });
+        return sendError(res, {
+          statusCode: 401,
+          requestId,
+          code: "MISSING_TOKEN",
+          message: "No authentication jwt_token provided",
+        });
+      }
+
+      const isTokenInvalid = await sessionManager.isTokenInvalidated(jwt_token);
+      if (isTokenInvalid) {
+        const invalidationInfo =
+          await sessionManager.getTokenInvalidationInfo(jwt_token);
+        logger.metric &&
+          logger.metric("token_refresh_attempts", 1, {
+            component: "AuthenticationService",
+            result: "invalidated_token",
+          });
+        return sendError(res, {
+          statusCode: 401,
+          requestId,
+          code: "INVALIDATED_TOKEN",
+          message: "Token has been invalidated",
+          details: {
+            reason: invalidationInfo?.reason || "session_inactive",
+            invalidatedAt: invalidationInfo?.timestamp,
+          },
+        });
+      }
+
+      const config_own_rodit = await stateManager.getConfigOwnRodit();
+      if (!config_own_rodit || !config_own_rodit.own_rodit) {
+        return sendError(res, {
+          statusCode: 500,
+          requestId,
+          code: "SERVER_CONFIG_ERROR",
+          message: "Server configuration not initialized",
+        });
+      }
+
+      let validationResult;
+      try {
+        validationResult = await validate_jwt_token_be(
+          jwt_token,
+          config_own_rodit.own_rodit,
+          {
+            allowExpiredToken: true,
+            forceCredentialRenewal: true,
+          }
+        );
+      } catch (validationError) {
+        const message = validationError.message || "Token refresh failed";
+        const sessionClosed =
+          /Error 012/i.test(message) ||
+          /Session is not active/i.test(message) ||
+          validationError.renewalReason === "session_closed";
+        logger.metric &&
+          logger.metric("token_refresh_attempts", 1, {
+            component: "AuthenticationService",
+            result: sessionClosed ? "session_closed" : "validation_failed",
+          });
+        return sendError(res, {
+          statusCode: sessionClosed ? 401 : 403,
+          requestId,
+          code: sessionClosed
+            ? "INVALIDATED_TOKEN"
+            : validationError.code || "REFRESH_FAILED",
+          message,
+        });
+      }
+
+      const newToken = validationResult?.newToken;
+      if (!newToken) {
+        logger.metric &&
+          logger.metric("token_refresh_attempts", 1, {
+            component: "AuthenticationService",
+            result: "no_new_token",
+          });
+        return sendError(res, {
+          statusCode: 403,
+          requestId,
+          code: "REFRESH_FAILED",
+          message: "Token refresh did not produce a new credential",
+        });
+      }
+
+      if (typeof res.setHeader === "function") {
+        res.setHeader("New-Token", newToken);
+      } else if (typeof res.set === "function") {
+        res.set("New-Token", newToken);
+      }
+
+      const duration = Date.now() - startTime;
+      logger.infoWithContext("Token refresh completed", {
+        ...baseContext,
+        duration,
+        success: true,
+      });
+      logger.metric &&
+        logger.metric("token_refresh_attempts", 1, {
+          component: "AuthenticationService",
+          result: "success",
+        });
+      logger.metric &&
+        logger.metric("token_refresh_duration_ms", duration, {
+          component: "AuthenticationService",
+          success: true,
+        });
+
+      return res.json({
+        token: newToken,
+        jwt_token: newToken,
+        message: "Token refreshed",
+        requestId,
+      });
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      logErrorWithMetrics(
+        "Token refresh process failed",
+        {
+          ...baseContext,
+          duration,
+        },
+        error,
+        "refresh_error",
+        { error_type: "general_refresh_error" }
+      );
+      logger.metric &&
+        logger.metric("token_refresh_attempts", 1, {
+          component: "AuthenticationService",
+          result: "error",
+        });
+      return sendError(res, {
+        statusCode: 500,
+        requestId,
+        code: "REFRESH_ERROR",
+        message: "Internal server error during token refresh",
+        details: !isStrictEnvironment() ? { error: error.message } : undefined,
+      });
+    }
+  }
+
   /**
    * Handle client login with NEP-413 standard
    *
@@ -2474,5 +2659,6 @@ module.exports = {
   login_client_withnep413,
   logout_client,
   logout_server,
+  refresh_client,
   createLoginTimestampChallenge,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rodit/rodit-auth-be",
-  "version": "9.16.2",
+  "version": "9.17.0",
   "description": "RODiT-based authentication system for Express.js applications",
   "main": "index.js",
   "exports": {

package/services/configsdk.js

@@ -229,10 +229,12 @@ const FALLBACK_DEFAULTS = {
     LAPSED_LIFETIME_PROPORTION_4RENEWAL_ELIGIBILITY: "0.80",
     THRESHOLD_VALIDATION_TYPE: "0.10",
     DURATIONRAMP: "0.85",
-    // RODiT flow initiator behavior.
+    // Token renewal initiator (default: server handles renewals).
     // Options:
-    // - "SERVER-INITIATED": server starts the flow
-    // - "CLIENT-INITIATED": client starts the flow
+    // - "SERVER-INITIATED" (default): renew access JWT during authenticate and
+    //   return New-Token. Clients normally do not need POST /api/refresh.
+    // - "CLIENT-INITIATED" (optional/advanced): skip piggyback renewal; client
+    //   must call the optional POST /api/refresh endpoint.
     SERVERORCLIENT: "SERVER-INITIATED",
     // Login error behavior.
     // Options: