@rodit/rodit-auth-be 9.16.0 → 9.17.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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
+
+- **`send_webhook` URL join:** append `endpoint` (e.g. `/hooks/wake`) only when
+  peer `webhook_url` / `rodit_webhookurl` has no path. A URL that already
+  includes a path (e.g. `host:7443/hooks/agent`) is used as-is, so paths are
+  no longer doubled.
+
+## [9.16.1] — 2026-09-18
+
+### Changed
+
+- **Docs:** Clarify that peer `webhook_url` / `rodit_webhookurl` is a base
+  (`host` or `host:port` only). The SDK appends the endpoint path; including
+  `/hooks/wake` or `/hooks/agent` in the metadata doubles the path.
+
 ## [9.16.0] — 2026-09-14
 
 ### Removed

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.15.0 · **License:** Proprietary · **Author:** Discernible IO
+**Version:** 9.17.0 · **License:** Proprietary · **Author:** Discernible IO
 
 ## Production deployments
 
@@ -1197,7 +1197,7 @@ const jwtDuration = metadata.jwt_duration;  // JWT expiration time
 const maxRequests = metadata.max_requests;  // Rate limit
 const maxRqWindow = metadata.maxrq_window;  // Rate limit window
 const apiEndpoint = metadata.subjectuniqueidentifier_url;  // API URL
-const webhookUrl = metadata.webhook_url;  // Webhook endpoint
+const webhookUrl = metadata.webhook_url;  // Webhook host[:port] (optional path)
 // Parse permissioned routes
 const permissionedRoutes = JSON.parse(metadata.permissioned_routes || '{}')
 // Use SDK config for application settings
@@ -1542,12 +1542,12 @@ Peer RODiT metadata:
 
 ```json
 {
-  "webhook_url": "hooks.example.com",
+  "webhook_url": "hooks.example.com:7443",
   "webhook_cidr": "0.0.0.0/0"
 }
 ```
 
-- `webhook_url` — host (optional path); SDK POSTs `https://{webhook_url}{endpoint}`
+- `webhook_url` — `host` or `host:port` (scheme optional), optionally with a path. If **no path** is present, the SDK appends `endpoint` (e.g. `https://hooks.example.com:7443/hooks/wake`). If a path is already present (e.g. `…:7443/hooks/agent`), that path is used as-is and nothing is appended.
 - `webhook_cidr` — allowlist for the **resolved** destination IP (`0.0.0.0/0` / empty = any public IP still subject to the SSRF blocklist)
 
 Outbound rejection codes (returned as `{ isValid: false, error: { code, message, requestId } }`):
@@ -2390,6 +2390,10 @@ const webhookHandler = roditClient.getWebhookHandler()
 
 Send a webhook notification to the peer URL in `req.user.rodit_webhookurl`.
 
+`rodit_webhookurl` is typically a base (`host` or `host:port`). When it has
+no path, the SDK appends `options.endpoint` (default `/webhook`). When a path
+is already present, that path is used as-is (endpoint is not appended).
+
 Outbound delivery rejects private / loopback / metadata destinations (and
 resolved addresses), enforces peer JWT `rodit_webhookcidr` when set, and pins
 DNS for the request. `SECURITY_OPTIONS.WEBHOOK_TLS_SKIP_VERIFY` still applies
@@ -2485,7 +2489,7 @@ When you call `roditClient.getConfigOwnRodit()`, you get access to these metadat
 | `subjectuniqueidentifier_url` | string | Primary API service endpoint |
 | `userselected_dn` | string | User-selected display name |
 | `webhook_cidr` | string | Allowlist CIDR(s) for outbound webhook resolved IPs (`0.0.0.0/0` = any public IP; private ranges are still blocked by SSRF controls) |
-| `webhook_url` | string | Peer webhook host used as `rodit_webhookurl` in issued JWTs |
+| `webhook_url` | string | Peer webhook host (`host` or `host:port`, optional path). Used as `rodit_webhookurl` in issued JWTs; the SDK appends the endpoint only when no path is present |
 
 ## Best Practices
 

package/index.js

@@ -18,10 +18,12 @@ const {
   authenticate_logout,
   login_client,
   logout_client,
+  refresh_client,
   login_client_withnep413,
   login_portal,
   login_server,
-  logout_server
+  logout_server,
+  createLoginTimestampChallenge,
 } = require('./lib/middleware/authenticationmw');
 
 const {
@@ -159,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
@@ -1041,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).
    *
@@ -1137,7 +1171,13 @@ class RoditClient {
             errorMessage += '\n→ [CLIENT REJECTED] The RODiT is missing required metadata. The RODiT may be corrupted or incomplete.';
             break;
           case 'LOGIN_BASE64URL_SIGNATURE_INVALID':
-            errorMessage += '\n→ [CLIENT REJECTED] The base64url login signature did not verify. Sign UTF-8 (roditid or accountid + canonical timestamp_iso) with the correct NEAR account private key; encoding must be base64url.';
+            errorMessage += '\n→ [CLIENT REJECTED] The base64url login signature did not verify. Sign UTF-8 (roditid or accountid + canonical timestamp_iso[, + nonce when present]) with the correct NEAR account private key; encoding must be base64url.';
+            break;
+          case 'LOGIN_NONCE_REPLAY':
+            errorMessage += '\n→ [CLIENT REJECTED] The login nonce was already used. Fetch a fresh challenge from GET /api/login/timestamp and sign again.';
+            break;
+          case 'INVALID_LOGIN_NONCE':
+            errorMessage += '\n→ [CLIENT REJECTED] The login nonce is malformed. Use the nonce string from GET /api/login/timestamp (base64url or hex).';
             break;
           case 'RODIT_FAMILY_MISMATCH':
             errorMessage += '\n→ [CLIENT REJECTED] Your RODiT does not belong to the same family as the server. You may need a different RODiT.';
@@ -1831,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();
   }
   
   /**
@@ -1913,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 = {
@@ -1934,10 +2026,12 @@ module.exports = {
   authenticate_logout,
   login_client,
   logout_client,
+  refresh_client,
   login_client_withnep413,
   login_portal,
   login_server,
   logout_server,
+  createLoginTimestampChallenge,
   validate_jwt_token_be,
   generate_jwt_token,
   normalizeUrlWithoutPort,
@@ -1958,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/authentication.js

@@ -23,12 +23,17 @@ const {
   PayloadNEP413Schema,
   CONSTANTS,
 } = require("../blockchain/blockchainservice");
+const {
+  buildLoginSigningMessageBytes,
+  tryConsumeLoginNonce,
+} = require("./login-nonce");
 
 async function verify_rodit_ownership(
     peerroditid,
     peertimestamp,
     peerroditid_base64url_signature,
-    peer_rodit
+    peer_rodit,
+    peerNonce = null
   ) {
     const requestId = ulid();
     const startTime = Date.now();
@@ -41,6 +46,7 @@ async function verify_rodit_ownership(
         requestId,
         peerRoditId: peerroditid,
         timestamp: peertimestamp,
+        hasNonce: !!peerNonce,
       }
     );
     
@@ -56,16 +62,21 @@ async function verify_rodit_ownership(
       // DO NOT DELETE THE FOLLOWING COMMENT
       /* Maybe for NEP413 compatibility, the following line added "NEAR" before peerroditid */
       
-      // Match legacy implementation exactly
+      // Legacy: identifier + timestamp_iso. With nonce: identifier + timestamp_iso + nonce.
       const timeString = await unixTimeToDateString(peertimestamp);
-      const roditidandtimestamp = new TextEncoder().encode(
-        peerroditid + timeString
+      const roditidandtimestamp = buildLoginSigningMessageBytes(
+        peerroditid,
+        timeString,
+        peerNonce
       );
+      const combinedString = peerNonce
+        ? peerroditid + timeString + peerNonce
+        : peerroditid + timeString;
 
       logger.debugWithContext("Encoded roditid and timestamp", {
         ...baseContext,
         timeString,
-        combinedString: peerroditid + timeString,
+        combinedString,
         bufferLength: roditidandtimestamp.length,
         bufferHex: Buffer.from(roditidandtimestamp).toString('hex'),
       });
@@ -128,7 +139,7 @@ async function verify_rodit_ownership(
       logger.debugWithContext("Verification inputs", {
         ...baseContext,
         messageLength: roditidandtimestamp.length,
-        messageContent: peerroditid + timeString,
+        messageContent: combinedString,
         signatureLength: bytes_ed25519_signature.length,
         publicKeyLength: peer_bytes_ed25519_public_key?.length,
         messageHex: Buffer.from(roditidandtimestamp).toString('hex'),
@@ -795,12 +806,14 @@ async function verify_rodit_ownership(
    * @param {string} peerroditid - Identifier string used in verify_rodit_ownership (client-signed prefix)
    * @param {number} peertimestamp - Unix seconds
    * @param {string} peerroditid_base64url_signature - base64url Ed25519 signature
+   * @param {string|null} [peerNonce=null] - Optional login challenge nonce; when set, bound into signature and single-use
    */
   async function verify_peer_rodit(
     peer_rodit,
     peerroditid,
     peertimestamp,
-    peerroditid_base64url_signature
+    peerroditid_base64url_signature,
+    peerNonce = null
   ) {
     const requestId = ulid();
     const startTime = Date.now();
@@ -813,6 +826,7 @@ async function verify_rodit_ownership(
       requestId,
       peerRoditId: peerroditid,
       timestamp: peertimestamp,
+      hasNonce: !!peerNonce,
       signatureLength: peerroditid_base64url_signature?.length,
       hasOwnRodit: !!config_own_rodit,
       ownRoditId: config_own_rodit?.token_id,
@@ -895,7 +909,8 @@ async function verify_rodit_ownership(
         peerroditid,
         peertimestamp,
         peerroditid_base64url_signature,
-        peer_rodit
+        peer_rodit,
+        peerNonce
       );
       const ownershipDuration = Date.now() - ownershipStart;
 
@@ -910,12 +925,32 @@ async function verify_rodit_ownership(
           requestId,
           roditId: peerroditid,
         });
+        const nonceHint = peerNonce
+          ? " When a nonce is present, the signed payload is identifier + timestamp_iso + nonce from the same login challenge."
+          : "";
         return {
           peer_rodit,
           goodrodit: false,
           failureReason: "LOGIN_BASE64URL_SIGNATURE_INVALID",
           failureMessage:
-            "Login base64url signature invalid: Ed25519 verification failed for the base64url_signature over UTF-8 (roditid or accountid) + canonical timestamp_iso from the login challenge (GET /api/login/timestamp). Wrong key, wrong payload, or wrong encoding (must be base64url, not standard base64)."
+            "Login base64url signature invalid: Ed25519 verification failed for the base64url_signature over UTF-8 (roditid or accountid) + canonical timestamp_iso from the login challenge (GET /api/login/timestamp). Wrong key, wrong payload, or wrong encoding (must be base64url, not standard base64)." +
+            nonceHint
+        };
+      }
+
+      if (peerNonce && !tryConsumeLoginNonce(peerroditid, peerNonce)) {
+        logger.warn("Login nonce replay rejected", {
+          component: "RoditAuth",
+          method: "verify_peer_rodit",
+          requestId,
+          roditId: peerroditid,
+        });
+        return {
+          peer_rodit,
+          goodrodit: false,
+          failureReason: "LOGIN_NONCE_REPLAY",
+          failureMessage:
+            "Login nonce already used: fetch a fresh challenge from GET /api/login/timestamp and sign again. Nonces are single-use when provided."
         };
       }
 
@@ -1827,5 +1862,5 @@ module.exports = {
   verify_rodit_isamatch,
   verify_rodit_islive,
   verify_rodit_istrusted_issuingsmartcontract,
-  authenticate_webhook
+  authenticate_webhook,
 };

package/lib/auth/login-nonce.js

@@ -0,0 +1,164 @@
+/**
+ * Login challenge nonce helpers (optional additive field for POST /api/login).
+ * When a nonce is present it is bound into the signed payload and single-use.
+ * Copyright (c) 2026 Discernible IO. All rights reserved.
+ */
+
+const crypto = require("crypto");
+const config = require("../../services/configsdk");
+const { unixTimeToDateString } = require("../../services/utils");
+
+const LOGIN_NONCE_BYTES = 16;
+const LOGIN_NONCE_MIN_LEN = 8;
+const LOGIN_NONCE_MAX_LEN = 128;
+
+/** @type {Map<string, { expiresAtMs: number, firstSeenAtMs: number }>} */
+const loginNonceReplayCache = new Map();
+
+/**
+ * Cryptographic login nonce for challenges (base64url, 128-bit).
+ * @returns {string}
+ */
+function generateLoginNonce() {
+  return crypto.randomBytes(LOGIN_NONCE_BYTES).toString("base64url");
+}
+
+/**
+ * Normalize optional login nonce from a request/challenge body.
+ * Missing/empty → null (legacy timestamp-only login). Invalid → { error }.
+ *
+ * @param {*} rawNonce
+ * @returns {{ nonce: string|null, error?: string, errorCode?: string }}
+ */
+function normalizeOptionalLoginNonce(rawNonce) {
+  if (rawNonce === undefined || rawNonce === null) {
+    return { nonce: null };
+  }
+  if (typeof rawNonce !== "string") {
+    return {
+      nonce: null,
+      errorCode: "INVALID_LOGIN_NONCE",
+      error: "Login nonce must be a string when provided",
+    };
+  }
+  const trimmed = rawNonce.trim();
+  if (trimmed.length === 0) {
+    return { nonce: null };
+  }
+  if (
+    trimmed.length < LOGIN_NONCE_MIN_LEN ||
+    trimmed.length > LOGIN_NONCE_MAX_LEN
+  ) {
+    return {
+      nonce: null,
+      errorCode: "INVALID_LOGIN_NONCE",
+      error: `Login nonce length must be between ${LOGIN_NONCE_MIN_LEN} and ${LOGIN_NONCE_MAX_LEN} characters`,
+    };
+  }
+  // Reject whitespace / control characters inside the token.
+  if (!/^[A-Za-z0-9_-]+$/.test(trimmed)) {
+    return {
+      nonce: null,
+      errorCode: "INVALID_LOGIN_NONCE",
+      error:
+        "Login nonce must be base64url or hex (letters, digits, '-', '_' only)",
+    };
+  }
+  return { nonce: trimmed };
+}
+
+/**
+ * Build UTF-8 bytes for login signature.
+ * Legacy: identifier + timestamp_iso
+ * With nonce: identifier + timestamp_iso + nonce
+ *
+ * @param {string} identifier
+ * @param {string} timeString - ISO timestamp string
+ * @param {string|null|undefined} nonce
+ * @returns {Uint8Array}
+ */
+function buildLoginSigningMessageBytes(identifier, timeString, nonce) {
+  const payload =
+    nonce && String(nonce).length > 0
+      ? String(identifier) + String(timeString) + String(nonce)
+      : String(identifier) + String(timeString);
+  return new TextEncoder().encode(payload);
+}
+
+function getLoginNonceReplayTtlMs() {
+  const maxAgeSeconds = Number(
+    config.get("API_DEFAULT_OPTIONS.TIMESTAMP_MAX_AGE", 300)
+  );
+  const seconds =
+    Number.isFinite(maxAgeSeconds) && maxAgeSeconds > 0 ? maxAgeSeconds : 300;
+  return seconds * 1000;
+}
+
+function cleanupExpiredLoginNonceEntries(nowMs = Date.now()) {
+  for (const [key, entry] of loginNonceReplayCache.entries()) {
+    if (!entry || entry.expiresAtMs <= nowMs) {
+      loginNonceReplayCache.delete(key);
+    }
+  }
+}
+
+function buildLoginNonceReplayKey(nonce) {
+  return String(nonce);
+}
+
+/**
+ * Atomically consume a login nonce. Returns false if already used.
+ * Call only after the signature that binds the nonce has verified.
+ *
+ * @param {string} identifier - roditid or accountid (reserved for future scoped caches / logging)
+ * @param {string} nonce
+ * @returns {boolean} true if consumed (first use), false if replay
+ */
+function tryConsumeLoginNonce(identifier, nonce) {
+  if (!nonce) {
+    return true;
+  }
+  const nowMs = Date.now();
+  cleanupExpiredLoginNonceEntries(nowMs);
+  const key = buildLoginNonceReplayKey(nonce);
+  if (loginNonceReplayCache.has(key)) {
+    return false;
+  }
+  loginNonceReplayCache.set(key, {
+    expiresAtMs: nowMs + getLoginNonceReplayTtlMs(),
+    firstSeenAtMs: nowMs,
+    identifier: identifier ? String(identifier) : undefined,
+  });
+  return true;
+}
+
+/**
+ * Host helper for GET /api/login/timestamp — issues timestamp + CSPRNG nonce.
+ * Clients that understand nonce will bind it into the signature; older clients ignore it.
+ *
+ * @returns {Promise<{ timestamp: number, timestamp_iso: string, nonce: string }>}
+ */
+async function createLoginTimestampChallenge() {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const timestamp_iso = await unixTimeToDateString(timestamp);
+  return {
+    timestamp,
+    timestamp_iso,
+    nonce: generateLoginNonce(),
+  };
+}
+
+/** Test/support: clear replay cache (does not affect production callers). */
+function clearLoginNonceReplayCacheForTests() {
+  loginNonceReplayCache.clear();
+}
+
+module.exports = {
+  generateLoginNonce,
+  normalizeOptionalLoginNonce,
+  buildLoginSigningMessageBytes,
+  tryConsumeLoginNonce,
+  createLoginTimestampChallenge,
+  clearLoginNonceReplayCacheForTests,
+  buildLoginNonceReplayKey,
+};