@rodit/rodit-auth-be 9.14.0 → 9.15.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@rodit/rodit-auth-be` are documented here.
 
+## [9.15.0] — 2026-08-11
+
+### Added
+
+- **Outbound webhook SSRF controls** in `send_webhook` (CC-0001 residual):
+  before `fetch`, reject userinfo and private / loopback / link-local / ULA /
+  CGNAT / cloud-metadata hostnames and resolved A/AAAA addresses (same policy
+  as SLC `url-join-identity.js`); enforce JWT/peer `rodit_webhookcidr` when
+  present; resolve-once and pin the IP for the request via undici `lookup`.
+  `SECURITY_OPTIONS.WEBHOOK_TLS_SKIP_VERIFY` is unchanged for **public**
+  self-signed destinations.
+- **`req.authenticatedRoditId` + login JSON `roditid`** after successful
+  `login_client` / `login_client_withnep413` signature verification (server-
+  derived peer token id only).
+- **`enforceRateLimitFromClaims()`** middleware (and
+  `RoditClient#getClaimRateLimitMiddleware`) that consumes `req.rateLimit`
+  set by `validatepermissions`.
+
+### Security
+
+- Compromised or DNS-rebound JWT `rodit_webhookurl` values can no longer reach
+  internal targets through the SDK outbound webhook path.
+
+## [9.14.1] — 2026-08-07
+
+### Changed
+
+- Package version bumped to **9.14.1** (local `package.json` version restored).
+
 ## [9.14.0] — 2026-07-16
 
 ### Removed

package/README.md

@@ -2,12 +2,14 @@
 
 A comprehensive Node.js SDK for implementing RODiT-based mutual authentication, authorization, self-configuration, and session management in Express.js applications.
 
-**Version:** 9.13.0  
+**Version:** 9.15.0  
 **License:** Proprietary  
 **Author:** Discernible IO
 
 **Login `POST` /api/login:** Use **`accountid`** (or **`roditid`**), **`timestamp`**, and **`base64url_signature`**. Sign UTF-8 bytes of `identifier + timestamp_iso`, and reject deprecated keys such as **`signature`** and **`account_id`**. See [CHANGELOG.md](./CHANGELOG.md).
 
+**9.15.0:** Outbound `send_webhook` SSRF controls (private/metadata blocklist, `webhook_cidr` enforcement, DNS pin); login success exposes verified peer id as JSON `roditid` and `req.authenticatedRoditId`; optional `enforceRateLimitFromClaims()` for per-route claim quotas. See [CHANGELOG.md](./CHANGELOG.md).
+
 **9.13 federated login:** A client RODiT issued for API A can log into API B in the same SR/CR family via `login_server({ apiEndpoint })`. See [Federated login](#federated-login-same-family-different-api-url).
 
 ## Table of Contents
@@ -23,6 +25,7 @@ A comprehensive Node.js SDK for implementing RODiT-based mutual authentication,
   - [Session lifetime and TTL](#session-lifetime-and-ttl)
 - [Configuration](#configuration)
   - [Environment Variables](#environment-variables)
+  - [Dynamic Rate Limiting](#dynamic-rate-limiting)
   - [Session Storage Configuration](#session-storage-configuration)
   - [Configuration Priority](#configuration-priority)
 - [Logging & Monitoring](#logging--monitoring)
@@ -605,26 +608,33 @@ Permissions are configured in your RODiT token metadata using the `permissioned_
 ```
 
 **Permission Format:**
-- `"+0"` = All methods allowed (GET, POST, PUT, DELETE, etc.)
-- `"+1"` = GET only
-- `"+2"` = POST only
-- Custom combinations can be defined
+
+Values are strings: optional scope prefix (`+` / `-`) plus a numeric rate:
+
+| Value | Meaning |
+|-------|---------|
+| `"+0"` | Allowed (entity + properties scope); **unlimited** rate |
+| `"+60"` | Allowed; **60 requests** per window (default window 60s) |
+| `"-0"` | Allowed (properties-only scope); unlimited |
+| (absent / no match) | Denied (`403`) |
+
+`validatepermissions` / `authorize` checks allow/deny and sets `req.rateLimit` from the numeric part. That metadata is inert until you mount `enforceRateLimitFromClaims()` (see [Dynamic Rate Limiting](#dynamic-rate-limiting)).
 
 ### Permission Validation Middleware
 
 The `authorize` middleware validates that the authenticated user has permission to access the requested route:
 
 ```javascript
-const authenticate = (req, res, next) => {
-  req.app.locals.roditClient.authenticate(req, res, next)
-}
-const authorize = (req, res, next) => {
-  req.app.locals.roditClient.authorize(req, res, next)
-}
-// Apply both authentication and authorization
+// After RoditClient.create('server') and app.locals.roditClient = roditClient
+const authenticate = (req, res, next) => roditClient.authenticate(req, res, next)
+const authorize = (req, res, next) => roditClient.authorize(req, res, next)
+const enforceClaimLimits = roditClient.getClaimRateLimitMiddleware()
+
+// Auth + permission allow/deny
 app.use('/api/admin', authenticate, authorize, adminRoutes)
-// CRUDA endpoints with full protection
-app.use('/api/cruda', authenticate, authorize, crudaRoutes)
+
+// Auth + permissions + per-route claim quotas from permissioned_routes
+app.use('/api/cruda', authenticate, authorize, enforceClaimLimits(), crudaRoutes)
 ```
 
 ### Permission Enforcement
@@ -1186,16 +1196,33 @@ const dbPath = config.get('API_DEFAULT_OPTIONS.DB_PATH')
 
 ### Dynamic Rate Limiting
 
+Two complementary limiters:
+
+1. **Global** (`getRateLimitMiddleware` / `ratelimitmw`) — from own RODiT `max_requests` / `maxrq_window` (or fixed numbers). Applies across routes.
+2. **Per-route claim** (`getClaimRateLimitMiddleware` / `enforceRateLimitFromClaims`) — consumes `req.rateLimit` set by `validatepermissions` from each peer’s `permissioned_routes` value (e.g. `"+60"` → 60 req / 60s for that path). Returns `429 RATE_LIMIT_EXCEEDED` when exceeded. In-memory, per process.
+
 ```javascript
-// Configure rate limiting from RODiT token
+// 1) Global limiter from own RODiT metadata
 const configObject = await roditClient.getConfigOwnRodit()
 const metadata = configObject.own_rodit.metadata
 if (metadata.max_requests && metadata.maxrq_window) {
-  const maxRequests = parseInt(metadata.max_requests)
-  const windowSeconds = parseInt(metadata.maxrq_window)
+  const maxRequests = parseInt(metadata.max_requests, 10)
+  const windowSeconds = parseInt(metadata.maxrq_window, 10)
   const rateLimiter = roditClient.getRateLimitMiddleware()
-  app.use(rateLimiter(maxRequests, windowSeconds))
-}
+  // Note: factory args are (maxRequests, windowMinutes)
+  app.use(rateLimiter(maxRequests, Math.ceil(windowSeconds / 60) || 1))
+}
+
+// 2) Per-route claim enforcement (after authenticate + validatepermissions)
+const { authenticate_apicall, validatepermissions, enforceRateLimitFromClaims } =
+  require('@rodit/rodit-auth-be')
+// Or: roditClient.getClaimRateLimitMiddleware()
+app.use(
+  '/api',
+  (req, res, next) => roditClient.authenticate(req, res, next),
+  validatepermissions,
+  enforceRateLimitFromClaims()
+)
 ```
 
 ### Environment Variables
@@ -1249,8 +1276,8 @@ export LOKI_TLS_SKIP_VERIFY=false    # true to skip TLS verification
 
 #### Security Options
 ```bash
-// Webhook configuration
-export WEBHOOK_TLS_SKIP_VERIFY=false  # true to skip TLS verification
+// Webhook TLS (public destinations only; private/metadata URLs are always blocked)
+export SECURITY_OPTIONS_WEBHOOK_TLS_SKIP_VERIFY=false  # true for self-signed public webhook hosts
 // Login mode control (see Login Mode section below)
 export SECURITY_OPTIONS_LOGIN_MODE=partner  # partner, promiscuous, or p2p
 // Security thresholds
@@ -1487,26 +1514,40 @@ performanceService.recordMetric('user_action', 1, {
 })
 ```
 
- ## Webhooks
- 
- ### Overview
+## Webhooks
+
+### Overview
 
-The SDK supports sending webhooks to multiple endpoints for important events. Webhook URLs are configured in the RODiT token metadata.
+The SDK supports sending webhooks to multiple endpoints for important events. Webhook URLs come from the **peer JWT** claim `rodit_webhookurl` (from that peer’s RODiT `webhook_url` metadata).
 
 **Key Features:**
 - **Custom Endpoints** - Send webhooks to any endpoint path (e.g., `/hooks/wake`, `/hooks/agent`, `/webhook`)
-- **Non-blocking** - Webhooks sent asynchronously without blocking the main response
-- **Error Resilient** - Webhook failures don't affect the main operation
+- **Ed25519 signed** - Payload + timestamp signed; receivers verify via `X-Signature` / signer identity headers
+- **Outbound SSRF controls (9.15+)** - Before `fetch`, reject userinfo and private / loopback / link-local / ULA / CGNAT / cloud-metadata hostnames and resolved A/AAAA; enforce peer `rodit_webhookcidr` when set; resolve-once and pin DNS for the request
+- **Self-signed TLS (public only)** - `SECURITY_OPTIONS.WEBHOOK_TLS_SKIP_VERIFY=true` still allowed for **public** destinations
 
-Webhooks are configured in your RODiT token:
+Peer RODiT metadata:
 
 ```json
 {
-"webhook_url": "https:
-"webhook_cidr": "0.0.0.0/0"
+  "webhook_url": "hooks.example.com",
+  "webhook_cidr": "0.0.0.0/0"
 }
 ```
 
+- `webhook_url` — host (optional path); SDK POSTs `https://{webhook_url}{endpoint}`
+- `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 } }`):
+
+| Code | Meaning |
+|------|---------|
+| `WEBHOOK_URL_MISSING` | No `rodit_webhookurl` on `req.user` |
+| `WEBHOOK_URL_INVALID` | Bad URL / userinfo / scheme |
+| `WEBHOOK_URL_BLOCKED` | Private, loopback, or metadata target |
+| `WEBHOOK_URL_UNRESOLVABLE` | DNS lookup failed |
+| `WEBHOOK_CIDR_DENIED` | Resolved IP outside peer `webhook_cidr` |
+
 ### Sending Webhooks to Default Endpoint
 
 Send webhooks to the default `/webhook` endpoint:
@@ -2079,16 +2120,24 @@ Handle Express login requests from clients. Validates RODiT credentials and issu
 app.post('/api/login', (req, res) => roditClient.login_client(req, res))
 ```
 
-**Request Body:** `login_client` accepts `accountid`, `timestamp`, and `base64url_signature`.
+**Request Body:** `accountid` or `roditid` (exactly one non-empty), `timestamp` (and/or `timestamp_iso`), and `base64url_signature` (or `roditid_base64url_signature`).
+
+**On success:**
+- Sets `req.authenticatedRoditId` to the **verified** peer token id (`peer_rodit.token_id`) — do not use `req.body.roditid` for app hooks
+- JSON body includes the same value as `roditid` (in addition to `jwt_token` / `requestId`)
+- Creates a server session keyed by that peer id; issues JWT (`New-Token` header + body)
 
 **Response:**
 ```javascript
 {
   jwt_token: '<jwt-token>',
-  requestId: '01HQXYZ...'
+  requestId: '01HQXYZ...',
+  roditid: '<verified-peer-token-id>'
 }
 ```
 
+`login_client_withnep413` returns the same success shape (`jwt_token`, `requestId`, `roditid`) and also sets `req.authenticatedRoditId`.
+
 ##### logout_client(req, res)
 
 Handle Express logout requests. Closes session and invalidates JWT token.
@@ -2275,6 +2324,23 @@ app.use(limiter)
 
 **Returns:** Express middleware function
 
+##### getClaimRateLimitMiddleware()
+
+Get the middleware factory that enforces per-route limits from
+`req.rateLimit` (populated by `validatepermissions` / `authorize`).
+
+Place **after** authentication and permission validation. Skips when
+`req.rateLimit` is missing or `unlimited: true`. Default window is
+`req.rateLimit.timeWindow` seconds (60). Optional `{ store }` Map-like
+override for multi-instance deployments.
+
+```javascript
+const enforceRateLimitFromClaims = roditClient.getClaimRateLimitMiddleware()
+app.use('/api', authenticate, authorize, enforceRateLimitFromClaims())
+```
+
+**Returns:** Middleware factory `(options?) => Express middleware`
+
 ##### getPerformanceService()
 
 Get the performance tracking service.
@@ -2310,7 +2376,12 @@ const webhookHandler = roditClient.getWebhookHandler()
 
 ##### send_webhook(payload, req)
 
-Send a webhook notification.
+Send a webhook notification to the peer URL in `req.user.rodit_webhookurl`.
+
+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
+to **public** self-signed endpoints only.
 
 ```javascript
 const result = await roditClient.send_webhook({
@@ -2318,16 +2389,23 @@ const result = await roditClient.send_webhook({
   data: { userId: '123', action: 'login' },
   isError: false
 }, req)
+
+if (!result.isValid) {
+  // e.g. WEBHOOK_URL_BLOCKED, WEBHOOK_CIDR_DENIED, WEBHOOK_SEND_ERROR
+  logger.warn('Webhook not delivered', result.error)
+}
 ```
 
+Aliases: `sendWebhook(payload, req)`, `sendWebhookToEndpoint(payload, endpoint, req)`.
+
 **Parameters:**
 - `payload` (Object): Webhook payload
   - `event` (string): Event name
   - `data` (Object): Event data
   - `isError` (boolean): Whether this is an error event
-- `req` (Object): Express request object (optional)
+- `req` (Object): Express request with authenticated `req.user` (peer JWT claims)
 
-**Returns:** `Promise<Object>` - `{ success: boolean, ... }`
+**Returns:** `Promise<Object>` — success `{ isValid: true, message, requestId, duration }` or `{ isValid: false, error: { code, message, requestId } }`
 
 ### Exported Components
 
@@ -2363,6 +2441,7 @@ const {
   versioningMiddleware,  // API versioning
   loggingmw,             // Logging middleware
   ratelimitmw,           // Rate limiting middleware
+  enforceRateLimitFromClaims, // Consumes req.rateLimit from validatepermissions
   versionManager,        // Version manager
   VersionManager,        // Version manager class
   nearorg_rpc_timestamp  // Blockchain RPC timestamp function
@@ -2393,8 +2472,8 @@ When you call `roditClient.getConfigOwnRodit()`, you get access to these metadat
 | `serviceprovider_signature` | string | Cryptographic signature for verification |
 | `subjectuniqueidentifier_url` | string | Primary API service endpoint |
 | `userselected_dn` | string | User-selected display name |
-| `webhook_cidr` | string | Allowed IP ranges for webhooks |
-| `webhook_url` | string | Webhook endpoint URL |
+| `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 |
 
 ## Best Practices
 

package/index.js

@@ -41,6 +41,7 @@ const { versioningMiddleware } = require('./lib/middleware/versioningmw');
 const { VersionManager } = require('./services/versionmanager');
 const loggingmw = require('./lib/middleware/loggingmw');
 const ratelimitmw = require('./lib/middleware/ratelimitmw');
+const enforceRateLimitFromClaims = require('./lib/middleware/enforceratelimitmw');
 const utils = require('./services/utils');
 const config = require('./services/configsdk');
 const performanceService = require('./services/performanceservice');
@@ -404,6 +405,14 @@ class RoditClient {
     return ratelimitmw;
   }
 
+  /**
+   * Get middleware that enforces `req.rateLimit` from validatepermissions.
+   * @returns {Function} Middleware factory: enforceRateLimitFromClaims(options?)
+   */
+  getClaimRateLimitMiddleware() {
+    return enforceRateLimitFromClaims;
+  }
+
   /**
    * Get utilities
    * @returns {Object} Utilities object
@@ -1950,6 +1959,7 @@ module.exports = {
   versioningMiddleware,
   loggingmw,
   ratelimitmw,
+  enforceRateLimitFromClaims,
   versionManager,
   VersionManager,
   // Blockchain service functions

package/lib/middleware/authenticationmw.js

@@ -586,9 +586,14 @@ async function login_client(req, res) {
     // Set the jwt_token in the response header
     res.setHeader('New-Token', jwt_token);
 
+    // Server-derived peer identity (verified RODiT only — do not trust client body).
+    const authenticatedRoditId = peer_rodit.token_id;
+    req.authenticatedRoditId = authenticatedRoditId;
+
     return res.json({
       jwt_token,
-      requestId
+      requestId,
+      roditid: authenticatedRoditId
     });
   } catch (error) {
     const duration = Date.now() - startTime;
@@ -1453,13 +1458,19 @@ async function login_client(req, res) {
         requestId,
         response: {
           requestId: requestId,
-          jwt_token_length: jwt_token ? jwt_token.length : 0
+          jwt_token_length: jwt_token ? jwt_token.length : 0,
+          roditid: peer_rodit.token_id
         }
       });
 
+      // Server-derived peer identity (verified RODiT only — do not trust client body).
+      const authenticatedRoditId = peer_rodit.token_id;
+      req.authenticatedRoditId = authenticatedRoditId;
+
       return res.json({
         jwt_token,
         requestId,
+        roditid: authenticatedRoditId,
       });
     } catch (error) {
       const duration = Date.now() - startTime;

package/lib/middleware/enforceratelimitmw.js

@@ -0,0 +1,135 @@
+/**
+ * Enforce per-route rate limits from `req.rateLimit` (set by validatepermissions).
+ * Copyright (c) 2026 Discernible IO. All rights reserved.
+ */
+
+const { ulid } = require("ulid");
+const logger = require("../../services/logger");
+const { createLogContext } = logger;
+const { sendError } = require("../../services/error-response");
+
+/**
+ * In-memory fixed-window counters keyed by subject + path + operation.
+ * Suitable for single-process apps; replace/store externally for multi-instance.
+ */
+const windows = new Map();
+
+function cleanupExpired(now) {
+  if (windows.size < 1000) return;
+  for (const [key, entry] of windows) {
+    if (entry.resetAt <= now) {
+      windows.delete(key);
+    }
+  }
+}
+
+function rateLimitSubject(req) {
+  if (req.authenticatedRoditId) return String(req.authenticatedRoditId);
+  if (req.user) {
+    if (req.user.sub) return String(req.user.sub);
+    if (req.user.rodit_id) return String(req.user.rodit_id);
+  }
+  return req.ip || "anonymous";
+}
+
+/**
+ * Middleware factory that consumes `req.rateLimit` metadata produced by
+ * `validatepermissions`. Place after permission validation on protected routes.
+ *
+ * @param {Object} [options]
+ * @param {Map} [options.store] Optional external store (Map-like get/set)
+ * @returns {Function} Express middleware
+ *
+ * @example
+ * app.use('/api', authenticate_apicall, validatepermissions, enforceRateLimitFromClaims());
+ */
+function enforceRateLimitFromClaims(options = {}) {
+  const store = options.store || windows;
+
+  return function enforceRateLimitFromClaimsMiddleware(req, res, next) {
+    const requestId = req.requestId || ulid();
+    const rate = req.rateLimit;
+
+    if (!rate || rate.unlimited === true) {
+      return next();
+    }
+
+    const limit = Number(rate.value);
+    if (!Number.isFinite(limit) || limit <= 0) {
+      // Missing / unparsable claim → do not invent a limit
+      return next();
+    }
+
+    const timeWindowSeconds =
+      Number.isFinite(Number(rate.timeWindow)) && Number(rate.timeWindow) > 0
+        ? Number(rate.timeWindow)
+        : 60;
+    const now = Date.now();
+    const subject = rateLimitSubject(req);
+    const pathKey = rate.path || req.path || "";
+    const operation = rate.operation || "";
+    const key = `${subject}|${pathKey}|${operation}`;
+
+    cleanupExpired(now);
+
+    let entry = store.get(key);
+    if (!entry || entry.resetAt <= now) {
+      entry = {
+        count: 0,
+        resetAt: now + timeWindowSeconds * 1000,
+        limit,
+      };
+    }
+
+    entry.count += 1;
+    store.set(key, entry);
+
+    const remaining = Math.max(0, limit - entry.count);
+    const resetSeconds = Math.max(1, Math.ceil((entry.resetAt - now) / 1000));
+
+    res.setHeader("X-RateLimit-Limit", String(limit));
+    res.setHeader("X-RateLimit-Remaining", String(remaining));
+    res.setHeader("X-RateLimit-Reset", String(resetSeconds));
+
+    if (entry.count > limit) {
+      const baseContext = createLogContext("EnforceRateLimit", "claimExceeded", {
+        requestId,
+        subject,
+        path: pathKey,
+        operation,
+        limit,
+        count: entry.count,
+        timeWindowSeconds,
+      });
+      logger.warnWithContext("Per-route claim rate limit exceeded", {
+        ...baseContext,
+        result: "blocked",
+      });
+      logger.metric &&
+        logger.metric("rate_limit_operations", 0, {
+          operation: "claim_limit_exceeded",
+          path: pathKey,
+          result: "blocked",
+        });
+
+      return sendError(res, {
+        statusCode: 429,
+        requestId,
+        code: "RATE_LIMIT_EXCEEDED",
+        message: "Rate limit exceeded for this permissioned route",
+        details: {
+          limit,
+          timeWindowSeconds,
+          operation: operation || undefined,
+          path: pathKey || undefined,
+        },
+      });
+    }
+
+    return next();
+  };
+}
+
+module.exports = enforceRateLimitFromClaims;
+module.exports.enforceRateLimitFromClaims = enforceRateLimitFromClaims;
+module.exports._windows = windows;

package/lib/middleware/validatepermissionsmw.js

@@ -416,7 +416,7 @@ async function validatepermissions(req, res, next) {
     req.commentsRate = result.commentsRate;
   }
   
-  // Make rate limit information available for future implementation
+  // Make rate limit information available for enforceRateLimitFromClaims()
   req.rateLimit = {
     value: result.rateLimit,
     unlimited: result.unlimited === true,

package/lib/middleware/webhookhandlermw.js

@@ -8,6 +8,8 @@
 
 const crypto = require("crypto");
 const https = require("https");
+const dns = require("dns").promises;
+const net = require("net");
 const { Agent } = require("undici");
 const config = require('../../services/configsdk');
 const { isStrictEnvironment, getNodeEnv } = require('../../services/env');
@@ -20,6 +22,304 @@ const stateManager = require("../blockchain/statemanager");
 const { sessionManager } = require("../auth/sessionmanager");
 const { authenticate_webhook } = require("../auth/authentication");
 
+// ---------------------------------------------------------------------------
+// Outbound webhook URL SSRF / CIDR / DNS-pin helpers
+// Policy aligned with SLC `src/game/url-join-identity.js`.
+// ---------------------------------------------------------------------------
+
+function webhookUrlError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+/**
+ * Reject loopback / RFC1918 / link-local / ULA / CGNAT / cloud-metadata destinations.
+ * Self-signed TLS for public webhook hosts remains allowed (WEBHOOK_TLS_SKIP_VERIFY).
+ */
+function isBlockedIpAddress(ip) {
+  const version = net.isIP(ip);
+  if (version === 4) {
+    const parts = ip.split(".").map((p) => Number(p));
+    if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) {
+      return true;
+    }
+    const [a, b] = parts;
+    if (a === 0) return true; // 0.0.0.0/8
+    if (a === 10) return true; // 10.0.0.0/8
+    if (a === 127) return true; // 127.0.0.0/8
+    if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local / metadata
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+    if (a === 192 && b === 168) return true; // 192.168.0.0/16
+    if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT
+    if (a >= 224) return true; // multicast / reserved
+    return false;
+  }
+  if (version === 6) {
+    const normalized = ip.toLowerCase();
+    if (normalized === "::" || normalized === "::1") return true;
+    const mapped = normalized.match(/:ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (mapped) return isBlockedIpAddress(mapped[1]);
+    const first = normalized.split(":")[0] || "";
+    const firstVal = Number.parseInt(first, 16);
+    if (Number.isFinite(firstVal)) {
+      if ((firstVal & 0xffc0) === 0xfe80) return true; // fe80::/10
+      if ((firstVal & 0xfe00) === 0xfc00) return true; // fc00::/7
+      if ((firstVal & 0xff00) === 0xff00) return true; // ff00::/8
+    }
+    return false;
+  }
+  return true;
+}
+
+function isBlockedHostname(hostname) {
+  const host = String(hostname || "")
+    .toLowerCase()
+    .replace(/\.$/, "")
+    .replace(/^\[|\]$/g, "");
+  if (!host) return true;
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (host === "metadata.google.internal" || host.endsWith(".metadata.google.internal")) {
+    return true;
+  }
+  if (host === "metadata" || host.endsWith(".internal")) return true;
+  if (net.isIP(host)) return isBlockedIpAddress(host);
+  return false;
+}
+
+/**
+ * Synchronous URL policy checks (scheme, length, userinfo, blocked hostname literals).
+ * @param {string} raw Absolute http(s) URL
+ * @returns {URL}
+ */
+function validateOutboundWebhookUrl(raw) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    throw webhookUrlError("WEBHOOK_URL_INVALID", "Webhook URL is required");
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length > 2048) {
+    throw webhookUrlError("WEBHOOK_URL_INVALID", "Webhook URL is too long");
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw webhookUrlError("WEBHOOK_URL_INVALID", "Webhook URL must be an absolute URL");
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw webhookUrlError("WEBHOOK_URL_INVALID", "Webhook URL must use http or https");
+  }
+  if (parsed.username || parsed.password) {
+    throw webhookUrlError("WEBHOOK_URL_INVALID", "Webhook URL must not contain userinfo");
+  }
+  if (isBlockedHostname(parsed.hostname)) {
+    throw webhookUrlError(
+      "WEBHOOK_URL_BLOCKED",
+      "Webhook URL must not target a private, loopback, or metadata host"
+    );
+  }
+  return parsed;
+}
+
+function ipv4ToInt(ip) {
+  return ip.split(".").reduce((acc, oct) => ((acc << 8) + Number(oct)) >>> 0, 0) >>> 0;
+}
+
+function parseCidrList(cidrClaim) {
+  if (cidrClaim == null) return [];
+  const raw = String(cidrClaim).trim();
+  if (!raw) return [];
+  return raw
+    .split(/[\s,;]+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function isUnrestrictedCidr(cidr) {
+  const value = String(cidr || "").trim().toLowerCase();
+  return value === "0.0.0.0/0" || value === "::/0" || value === "*";
+}
+
+function isIpInCidr(ip, cidr) {
+  const trimmed = String(cidr || "").trim();
+  if (!trimmed || isUnrestrictedCidr(trimmed)) return true;
+
+  const slash = trimmed.indexOf("/");
+  if (slash < 0) return false;
+  const base = trimmed.slice(0, slash);
+  const prefix = Number(trimmed.slice(slash + 1));
+  const ipVer = net.isIP(ip);
+  const baseVer = net.isIP(base);
+  if (!ipVer || !baseVer || ipVer !== baseVer || !Number.isInteger(prefix)) {
+    return false;
+  }
+
+  if (ipVer === 4) {
+    if (prefix < 0 || prefix > 32) return false;
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    return (ipv4ToInt(ip) & mask) === (ipv4ToInt(base) & mask);
+  }
+
+  // IPv6: compare prefix bits of normalized 128-bit forms
+  if (prefix < 0 || prefix > 128) return false;
+  const toBytes = (addr) => {
+    const buf = Buffer.alloc(16);
+    const full = expandIpv6(addr);
+    for (let i = 0; i < 8; i++) {
+      const hextet = Number.parseInt(full[i], 16);
+      buf.writeUInt16BE(hextet, i * 2);
+    }
+    return buf;
+  };
+
+  try {
+    const ipBuf = toBytes(ip);
+    const baseBuf = toBytes(base);
+    const fullBytes = Math.floor(prefix / 8);
+    const remBits = prefix % 8;
+    for (let i = 0; i < fullBytes; i++) {
+      if (ipBuf[i] !== baseBuf[i]) return false;
+    }
+    if (remBits === 0) return true;
+    const mask = 0xff << (8 - remBits);
+    return (ipBuf[fullBytes] & mask) === (baseBuf[fullBytes] & mask);
+  } catch {
+    return false;
+  }
+}
+
+function expandIpv6(addr) {
+  const lower = String(addr).toLowerCase().replace(/^\[|\]$/g, "");
+  const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) {
+    const parts = mapped[1].split(".").map(Number);
+    const hi = ((parts[0] << 8) | parts[1]).toString(16);
+    const lo = ((parts[2] << 8) | parts[3]).toString(16);
+    return ["0", "0", "0", "0", "0", "ffff", hi, lo];
+  }
+  const [head, tail] = lower.split("::");
+  const headParts = head ? head.split(":") : [];
+  const tailParts = tail ? tail.split(":") : [];
+  const missing = 8 - (headParts.length + tailParts.length);
+  if (missing < 0) {
+    throw new Error("invalid ipv6");
+  }
+  const middle = Array(missing).fill("0");
+  const parts = [...headParts, ...middle, ...tailParts].map((p) => p || "0");
+  if (parts.length !== 8) {
+    throw new Error("invalid ipv6");
+  }
+  return parts;
+}
+
+function assertIpAllowedByWebhookCidr(ip, cidrClaim) {
+  const cidrs = parseCidrList(cidrClaim);
+  if (cidrs.length === 0 || cidrs.every(isUnrestrictedCidr)) {
+    return;
+  }
+  const allowed = cidrs.some((cidr) => isIpInCidr(ip, cidr));
+  if (!allowed) {
+    throw webhookUrlError(
+      "WEBHOOK_CIDR_DENIED",
+      "Resolved webhook address is outside the peer webhook_cidr allowlist"
+    );
+  }
+}
+
+/**
+ * Resolve hostname once, reject blocked addresses, enforce webhook_cidr, and
+ * return a single pinned address for the request lifetime (DNS rebinding defense).
+ *
+ * @param {string|URL} url
+ * @param {string} [webhookCidr] JWT/peer `rodit_webhookcidr` / `webhook_cidr`
+ * @returns {Promise<{ url: URL, hostname: string, address: string, family: number }>}
+ */
+async function resolveAndPinWebhookDestination(url, webhookCidr) {
+  const parsed = url instanceof URL ? url : validateOutboundWebhookUrl(url);
+  const hostname = String(parsed.hostname || "").replace(/^\[|\]$/g, "");
+
+  if (net.isIP(hostname)) {
+    if (isBlockedIpAddress(hostname)) {
+      throw webhookUrlError(
+        "WEBHOOK_URL_BLOCKED",
+        "Webhook URL must not target a private, loopback, or metadata host"
+      );
+    }
+    assertIpAllowedByWebhookCidr(hostname, webhookCidr);
+    return {
+      url: parsed,
+      hostname,
+      address: hostname,
+      family: net.isIP(hostname),
+    };
+  }
+
+  let records;
+  try {
+    records = await dns.lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    throw webhookUrlError(
+      "WEBHOOK_URL_UNRESOLVABLE",
+      "Webhook URL hostname could not be resolved"
+    );
+  }
+  if (!records.length) {
+    throw webhookUrlError(
+      "WEBHOOK_URL_UNRESOLVABLE",
+      "Webhook URL hostname could not be resolved"
+    );
+  }
+
+  const candidates = records.filter((record) => !isBlockedIpAddress(record.address));
+  if (!candidates.length) {
+    throw webhookUrlError(
+      "WEBHOOK_URL_BLOCKED",
+      "Webhook URL must not resolve to a private, loopback, or metadata address"
+    );
+  }
+
+  const cidrs = parseCidrList(webhookCidr);
+  const restrictCidr = cidrs.length > 0 && !cidrs.every(isUnrestrictedCidr);
+  const allowed = restrictCidr
+    ? candidates.filter((record) => cidrs.some((cidr) => isIpInCidr(record.address, cidr)))
+    : candidates;
+
+  if (!allowed.length) {
+    throw webhookUrlError(
+      "WEBHOOK_CIDR_DENIED",
+      "Resolved webhook address is outside the peer webhook_cidr allowlist"
+    );
+  }
+
+  // Prefer IPv4 when available for broader destination compatibility.
+  const pinned = allowed.find((r) => r.family === 4) || allowed[0];
+  return {
+    url: parsed,
+    hostname,
+    address: pinned.address,
+    family: pinned.family,
+  };
+}
+
+/**
+ * undici Agent that always returns the pinned address for DNS lookups
+ * (keeps Host / SNI as the original hostname).
+ */
+function createPinnedDispatcher({ address, family, skipTlsVerify = false }) {
+  return new Agent({
+    connect: {
+      rejectUnauthorized: !skipTlsVerify,
+      lookup: (hostname, options, callback) => {
+        if (options && options.all) {
+          callback(null, [{ address, family }]);
+          return;
+        }
+        callback(null, address, family);
+      },
+    },
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Webhook identity + session helpers
 // ---------------------------------------------------------------------------
@@ -915,12 +1215,52 @@ async function resolveOutboundWebhookSessionId(options = {}, req = null) {
         .replace(/\/+$/, "");
       const normalizedEndpoint = `/${String(endpoint || "/webhook").replace(/^\/+/, "")}`;
       const formattedWebhookUrl = `https://${cleanWebhookUrl}${normalizedEndpoint}`;
+
+      // Outbound SSRF controls: reject userinfo / private / metadata destinations,
+      // enforce peer webhook_cidr, and pin DNS for the request lifetime.
+      // WEBHOOK_TLS_SKIP_VERIFY remains allowed for public self-signed hosts.
+      let pinnedDestination;
+      try {
+        validateOutboundWebhookUrl(formattedWebhookUrl);
+        pinnedDestination = await resolveAndPinWebhookDestination(
+          formattedWebhookUrl,
+          req.user.rodit_webhookcidr
+        );
+      } catch (ssrfError) {
+        const duration = Date.now() - startTime;
+        const errorCode = ssrfError.code || "WEBHOOK_URL_BLOCKED";
+        logger.warnWithContext("Outbound webhook URL rejected by SSRF controls", {
+          ...baseContext,
+          duration,
+          formattedWebhookUrl,
+          webhookCidr: req.user.rodit_webhookcidr || null,
+          errorCode,
+          error: ssrfError.message
+        });
+        logger.metric &&
+          logger.metric("webhook_delivery_failures_total", 1, {
+            component: "WebhookHandler",
+            reason: errorCode,
+            event,
+          });
+        return {
+          isValid: false,
+          error: {
+            code: errorCode,
+            message: ssrfError.message,
+            requestId,
+          },
+        };
+      }
    
        logger.debugWithContext("Webhook URL details", {
          ...baseContext,
          rawWebhookUrl: webhookUrl,
          endpoint,
-         formattedWebhookUrl
+         formattedWebhookUrl,
+         pinnedAddress: pinnedDestination.address,
+         pinnedFamily: pinnedDestination.family,
+         webhookCidr: req.user.rodit_webhookcidr || null
        });
    
        const timestamp = Date.now();
@@ -1186,7 +1526,8 @@ async function resolveOutboundWebhookSessionId(options = {}, req = null) {
        // Configure HTTPS agent to skip TLS verification if configured
       // This is necessary when webhook destinations use self-signed certificates
       // Since mutual authentication via digital signatures is already in place,
-      // skipping TLS verification is safe in this context
+      // skipping TLS verification is safe in this context (public destinations only;
+      // private/metadata hosts are rejected above).
       const skipTlsVerify = config.has('SECURITY_OPTIONS.WEBHOOK_TLS_SKIP_VERIFY') 
         ? String(config.get('SECURITY_OPTIONS.WEBHOOK_TLS_SKIP_VERIFY')).toLowerCase() === 'true'
         : false;
@@ -1196,27 +1537,37 @@ async function resolveOutboundWebhookSessionId(options = {}, req = null) {
         headers: headers,
         body: payload,
       };
-      
+
+      // Always pin DNS via undici lookup so a rebinding race cannot retarget
+      // the TCP connection after the SSRF checks above.
+      const undiciAgent = createPinnedDispatcher({
+        address: pinnedDestination.address,
+        family: pinnedDestination.family,
+        skipTlsVerify,
+      });
+      fetchOptions.dispatcher = undiciAgent;
+
       if (skipTlsVerify) {
-        // Create custom undici Agent that accepts self-signed certificates
-        // Node.js fetch uses undici under the hood and requires 'dispatcher' option
-        const undiciAgent = new Agent({
-          connect: {
-            rejectUnauthorized: false
-          }
-        });
-        fetchOptions.dispatcher = undiciAgent;
-        
         logger.debugWithContext("Webhook TLS verification disabled", {
           ...baseContext,
           skipTlsVerify: true,
-          reason: "SECURITY_OPTIONS.WEBHOOK_TLS_SKIP_VERIFY=true"
+          reason: "SECURITY_OPTIONS.WEBHOOK_TLS_SKIP_VERIFY=true",
+          pinnedAddress: pinnedDestination.address
         });
       }
       
       // Send webhook request
       const fetchStartTime = Date.now();
-      const response = await fetch(formattedWebhookUrl, fetchOptions);
+      let response;
+      try {
+        response = await fetch(formattedWebhookUrl, fetchOptions);
+      } finally {
+        try {
+          await undiciAgent.close();
+        } catch (_closeError) {
+          // ignore dispatcher close errors
+        }
+      }
       const fetchDuration = Date.now() - fetchStartTime;
    
        // Log fetch duration metrics
@@ -1748,6 +2099,11 @@ module.exports = {
   implicitAccountToBase64urlKey,
   base64urlKeyToImplicitAccount,
 
+  // Outbound SSRF / CIDR / DNS-pin helpers
+  validateOutboundWebhookUrl,
+  resolveAndPinWebhookDestination,
+  createPinnedDispatcher,
+
   // Added exports from eventhandler.js
   WebhookEventHandler,
   TestConfigUpdateHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rodit/rodit-auth-be",
-  "version": "9.14.0",
+  "version": "9.15.0",
   "description": "RODiT-based authentication system for Express.js applications",
   "main": "index.js",
   "exports": {
@@ -46,7 +46,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/discernible-io/rodit-auth-be.git"
+    "url": "https://github.com/discernible-io/rodit-auth-be.git"
   },
   "publishConfig": {
     "access": "public"