@rodit/rodit-auth-be 9.11.20 → 9.12.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to `@rodit/rodit-auth-be` are documented here.
 
+## [9.12.0] — 2026-07-02
+
+### Fixed
+
+- **Multi-peer inbound webhook verification.** Inbound webhook signatures were
+  verified against `stateManager.getPeerBase64urlJwkPublicKey()`, a single
+  mutable "current peer" slot. When an agent was connected to several peers the
+  slot was clobbered by the most recent peer, so webhooks from other senders
+  (including the central API) failed with a false `401`
+  `WEBHOOK_SIGNATURE_INVALID` / `PEER_KEY_UNAVAILABLE`.
+
+### Added
+
+- **Self-identifying webhooks.** The signer's Ed25519 public key now travels
+  with each webhook, so verification no longer depends on a shared "current
+  peer" slot and is correct when connected to many peers at once:
+  - `send_webhook` advertises the signer identity via `X-Rodit-Public-Key`,
+    `X-Rodit-Implicit-Account` (hex of the signing key), and `X-Rodit-Token-Id`.
+  - `webhookHandler.extractWebhookSignerKey(headers)` reads that key directly
+    (implicit account is authoritative on its own; a raw advertised key must
+    agree with it). Exported from the package root as `extractWebhookSignerKey`.
+- **Signer ↔ session authorization gate.** A valid signature only proves the
+  sender holds the advertised private key; it does not prove that identity is a
+  peer we established a session with. `createWebhookAuthenticationMiddleware`
+  now enforces, after the signature verifies, that the (signed) `session_id`
+  maps to a live session whose `ownerId` equals the verified signer's implicit
+  account. New rejections: `401 WEBHOOK_SESSION_REQUIRED`,
+  `401 WEBHOOK_SESSION_INVALID`, `403 WEBHOOK_SIGNER_SESSION_MISMATCH`
+  (bypassed only under `NODE_ENV=test` or
+  `SECURITY_OPTIONS.BYPASS_WEBHOOK_VERIFICATION`). The validated binding is
+  exposed as `req.webhook_session`, `req.webhook_session_id`, and
+  `req.webhook_signer_implicit_account`.
+- **Webhook ↔ session correlation.** `send_webhook` stamps the originating
+  session id into the **signed** payload (`session_id`) so receivers can link an
+  inbound webhook to the session opened at login:
+  - `extractWebhookSessionId({ headers, rawPayload, parsedBody })` returns the
+    session id (signed payload authoritative, `X-Rodit-Session-Id` header as
+    fallback). Exported from the package root and from `webhookHandler`.
+  - `createPublicKeyMiddleware` sets `req.webhook_session_id` for downstream
+    handlers.
+  - The session id is resolved without requiring a request context: it falls
+    back to **session storage** (the SessionManager singleton, in-memory by
+    default) via `findSessionsByRoditId(options.sessionRoditId)`, so a JWT issuer
+    (`login_client`) can stamp the shared session id for out-of-band webhooks.
+  - `RoditClient.sendWebhook` / `sendWebhookToEndpoint` / `sendWakeHook` /
+    `sendAgentHook` accept an `options` argument (`sessionId`, `sessionRoditId`)
+    and default `sessionId` to the client's own `this.sessionId` (set at
+    `login_server`), so a peer that initiated the login stamps its session
+    automatically.
+- **Client-side session recording (symmetric session store).** The
+  `SessionManager` facility used by servers to track client sessions is now also
+  used by clients to record the sessions they open:
+  - `SessionManager.recordSession({ id, roditId, ... })` stores an
+    externally-issued session under its own id (idempotent), tagged
+    `origin: "client"`. `createSession` now tags issued sessions
+    `origin: "server"`.
+  - `SessionManager.hasSession(id)` quietly reports whether an id is a known,
+    live session (no warn logs, no lastAccessedAt bump); `forgetSession(id)`
+    removes one.
+  - `RoditClient.login_server` records each opened session keyed by the server's
+    roditId, so a client connected to many servers can cross-reference an inbound
+    webhook's `session_id` to a live session (multi-peer safe, unlike the single
+    `this.sessionId` slot). `clearSession` forgets it.
+  - `RoditClient.isKnownSession(id)` cross-references a webhook's session id
+    against the client's open sessions.
+  - Issuer-side webhook session lookup only considers `origin !== "client"`
+    sessions, so mutual peers don't cross-stamp.
+
+### Changed
+
+- **`createPublicKeyMiddleware`** extracts the verification key from the webhook
+  itself (`extractWebhookSignerKey`) instead of the mutable
+  `stateManager.getPeerBase64urlJwkPublicKey()` slot, and attaches
+  `req.webhook_session_id`. Authentication (key from the webhook) and
+  authorization (binding to a session) are now cleanly separated.
+
 ## [8.0.0] — 2026-05-02
 
 ### Breaking

package/index.js

@@ -61,6 +61,10 @@ function sessionFieldsFromJwt(token) {
       sessionId: payload.session_id,
       expiresAt: payload.session_exp,
       createdAt: payload.session_iat,
+      // Identity of the peer (server) that issued this JWT, so the client can
+      // record the session keyed by the server it opened it with.
+      peerRoditId: payload.rodit_id,
+      peerOwnerId: payload.rodit_owner,
     };
   } catch (_error) {
     return {};
@@ -281,32 +285,53 @@ class RoditClient {
    * @param {Object} [req] - Express request (for deriving peer webhook URL and headers)
    * @returns {Promise<Object>} Webhook result
    */
-  async sendWebhookToEndpoint(data, endpoint, req) {
+  async sendWebhookToEndpoint(data, endpoint, req, options = {}) {
     if (webhookHandler.send_webhook) {
-      return webhookHandler.send_webhook(data, req, { endpoint });
+      return webhookHandler.send_webhook(data, req, this._buildWebhookOptions(endpoint, options));
     }
     throw new Error('Webhook functionality not available');
   }
 
+  /**
+   * Build the options passed to the underlying send_webhook. Defaults the
+   * session id to this client's own session (set at login_server) so a peer that
+   * initiated the login stamps the shared session id automatically. Callers can
+   * override with options.sessionId or resolve from storage via
+   * options.sessionRoditId.
+   * @private
+   * @param {string} endpoint
+   * @param {Object} [options]
+   * @returns {Object}
+   */
+  _buildWebhookOptions(endpoint, options = {}) {
+    const merged = { ...options, endpoint };
+    if (merged.sessionId == null && this.sessionId) {
+      merged.sessionId = this.sessionId;
+    }
+    return merged;
+  }
+
   /**
    * Send webhook (backward compatibility alias)
    * @param {Object} data - Webhook payload object
    * @param {Object} [req] - Express request (for deriving peer webhook URL and headers)
+   * @param {Object} [options] - Webhook options (sessionId, sessionRoditId)
    * @returns {Promise<Object>} Webhook result
    */
-  async send_webhook(data, req) {
-    return this.sendWebhook(data, req);
+  async send_webhook(data, req, options = {}) {
+    return this.sendWebhook(data, req, options);
   }
 
   /**
    * Send webhook to default /webhook endpoint
    * @param {Object} data - Webhook payload object
    * @param {Object} [req] - Express request (optional)
+   * @param {Object} [options] - Webhook options (sessionId, sessionRoditId)
    * @returns {Promise<Object>} Webhook result
    */
-  async sendWebhook(data, req) {
+  async sendWebhook(data, req, options = {}) {
     if (webhookHandler.send_webhook) {
-      return webhookHandler.send_webhook(data, req, { endpoint: '/webhook' });
+      return webhookHandler.send_webhook(data, req, this._buildWebhookOptions('/webhook', options));
     }
     throw new Error('Webhook functionality not available');
   }
@@ -316,10 +341,11 @@ class RoditClient {
    * Trigger immediate heartbeat (enqueues system event for main session)
    * @param {Object} data - Webhook payload
    * @param {Object} [req] - Express request
+   * @param {Object} [options] - Webhook options (sessionId, sessionRoditId)
    * @returns {Promise<Object>} Webhook result
    */
-  async sendWakeHook(data, req) {
-    return this.sendWebhookToEndpoint(data, '/hooks/wake', req);
+  async sendWakeHook(data, req, options = {}) {
+    return this.sendWebhookToEndpoint(data, '/hooks/wake', req, options);
   }
 
   /**
@@ -327,10 +353,11 @@ class RoditClient {
    * Run isolated agent task with optional reply to messaging channels
    * @param {Object} data - Webhook payload
    * @param {Object} [req] - Express request
+   * @param {Object} [options] - Webhook options (sessionId, sessionRoditId)
    * @returns {Promise<Object>} Webhook result
    */
-  async sendAgentHook(data, req) {
-    return this.sendWebhookToEndpoint(data, '/hooks/agent', req);
+  async sendAgentHook(data, req, options = {}) {
+    return this.sendWebhookToEndpoint(data, '/hooks/agent', req, options);
   }
 
   /**
@@ -880,15 +907,32 @@ class RoditClient {
       sessionId: this.sessionData?.id
     });
     
+    // Forget the recorded session so it no longer cross-references webhooks.
+    if (this.sessionId) {
+      Promise.resolve(sessionManager.forgetSession(this.sessionId)).catch(() => {});
+    }
+
     // Clear session data
     this.sessionData = null;
     this.jwt_token = null;
+    this.sessionId = null;
     
     // Also clear JWT token from stateManager
     this.stateManager.setJwtToken(null);
     
     return true;
   }
+
+  /**
+   * Check whether a session id refers to a live session this client currently
+   * holds open. Use this to cross-reference the session_id carried by an inbound
+   * webhook against the sessions opened at login.
+   * @param {string} sessionId
+   * @returns {Promise<boolean>}
+   */
+  async isKnownSession(sessionId) {
+    return sessionManager.hasSession(sessionId);
+  }
   
   
   /**
@@ -1124,14 +1168,42 @@ class RoditClient {
         const fromJwt = sessionFieldsFromJwt(loginResult.jwt_token);
         const nowSec = Math.floor(Date.now() / 1000);
         this.sessionId = fromJwt.sessionId || ulid();
+        const sessionCreatedAt = fromJwt.createdAt ?? nowSec;
+        const sessionExpiresAt =
+          fromJwt.expiresAt ?? nowSec + config.getDefaultJwtDurationSeconds();
         this.setSessionData({
           id: this.sessionId,
-          createdAt: fromJwt.createdAt ?? nowSec,
-          expiresAt:
-            fromJwt.expiresAt ??
-            nowSec + config.getDefaultJwtDurationSeconds(),
+          createdAt: sessionCreatedAt,
+          expiresAt: sessionExpiresAt,
           status: 'active'
         });
+
+        // Record the opened session in the shared SessionManager, keyed by the
+        // server we logged into. This mirrors how a server stores sessions for
+        // its client peers, so a client connected to many servers can
+        // cross-reference an inbound webhook's session_id to a live session
+        // (multi-peer safe, unlike the single this.sessionId slot).
+        try {
+          const serverRoditId =
+            fromJwt.peerRoditId || config_own_rodit?.own_rodit?.token_id || null;
+          if (serverRoditId) {
+            await sessionManager.recordSession({
+              id: this.sessionId,
+              roditId: serverRoditId,
+              ownerId: fromJwt.peerOwnerId,
+              createdAt: sessionCreatedAt,
+              expiresAt: sessionExpiresAt,
+              status: 'active'
+            });
+          }
+        } catch (recordErr) {
+          logger.debug('Unable to record client session for webhook correlation', {
+            component: 'RoditClient',
+            method: 'login_server',
+            requestId,
+            error: recordErr.message
+          });
+        }
       }
 
       const duration = Date.now() - startTime;
@@ -1859,6 +1931,10 @@ module.exports = {
   generate_jwt_token,
   validatepermissions,
   webhookHandler,
+  // Webhook identity + session helpers (key travels with the webhook; trust is
+  // established by binding the verified signer to a session opened at login)
+  extractWebhookSignerKey: webhookHandler.extractWebhookSignerKey,
+  extractWebhookSessionId: webhookHandler.extractWebhookSessionId,
   versioningMiddleware,
   loggingmw,
   ratelimitmw,

package/lib/auth/sessionmanager.js

@@ -532,7 +532,10 @@ class SessionManager {
       const sessionId = this._generateSessionId(sessionData.roditId);
       const now = Math.floor(Date.now() / 1000);
       
-      // Create the session object
+      // Create the session object.
+      // origin distinguishes sessions this peer *issued* as a server ('server')
+      // from sessions a client peer *opened* and recorded ('client', see
+      // recordSession). Both live in the same store.
       const session = {
         id: sessionId,
         roditId: sessionData.roditId,
@@ -541,6 +544,7 @@ class SessionManager {
         expiresAt: sessionData.expiresAt,
         lastAccessedAt: now,
         status: 'active',
+        origin: sessionData.origin || 'server',
         metadata: sessionData.metadata || {},
       };
       
@@ -588,6 +592,125 @@ class SessionManager {
   }
 
 
+  /**
+   * Record an externally-issued session under its own id.
+   *
+   * Unlike createSession (which mints a new id when this peer, acting as a
+   * server, issues a JWT), recordSession stores a session using the id supplied
+   * by the issuer. It lets a *client* peer track the sessions it holds open with
+   * each server — the session_id embedded in every JWT it receives — using the
+   * same storage facility the server uses for its client peers. This makes
+   * multi-peer session tracking robust and lets an inbound webhook's session_id
+   * be cross-referenced to a live session (see hasSession).
+   *
+   * Idempotent upsert: recording an existing id refreshes it.
+   *
+   * @param {Object} sessionData
+   * @param {string} sessionData.id Issuer-provided session id
+   * @param {string} sessionData.roditId Peer (server) roditId this session is with
+   * @param {string} [sessionData.ownerId]
+   * @param {number} [sessionData.createdAt]
+   * @param {number} [sessionData.expiresAt]
+   * @param {string} [sessionData.status]
+   * @returns {Promise<Object|null>} The stored session, or null on error
+   */
+  async recordSession(sessionData) {
+    const requestId = ulid();
+    const baseContext = createLogContext("SessionManager", "recordSession", {
+      requestId,
+      sessionId: sessionData?.id
+    });
+
+    try {
+      if (!sessionData || !sessionData.id) {
+        throw new Error("recordSession requires sessionData.id");
+      }
+      if (!sessionData.roditId) {
+        throw new Error("recordSession requires sessionData.roditId");
+      }
+
+      const now = Math.floor(Date.now() / 1000);
+      const session = {
+        id: sessionData.id,
+        roditId: sessionData.roditId,
+        ownerId: sessionData.ownerId,
+        createdAt: sessionData.createdAt || now,
+        expiresAt: sessionData.expiresAt,
+        lastAccessedAt: now,
+        status: sessionData.status || 'active',
+        origin: 'client',
+        metadata: sessionData.metadata || {},
+      };
+
+      await this.storage.set(session.id, session);
+
+      logger.debugWithContext("Recorded client-side session", {
+        ...baseContext,
+        roditId: session.roditId,
+        expiresAt: session.expiresAt,
+        origin: session.origin
+      });
+
+      return session;
+    } catch (error) {
+      logger.warnWithContext("Failed to record client-side session", {
+        ...baseContext,
+        error: error.message
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Quietly test whether a session id refers to a known, live (active,
+   * non-expired) session. Unlike getSession this does not log warnings or bump
+   * lastAccessedAt, so it is safe to call on every inbound webhook to
+   * cross-reference the carried session_id.
+   *
+   * @param {string} sessionId
+   * @returns {Promise<boolean>}
+   */
+  async hasSession(sessionId) {
+    if (!sessionId) return false;
+    try {
+      const session = await this.storage.get(sessionId);
+      if (!session) return false;
+      const now = Math.floor(Date.now() / 1000);
+      if (session.expiresAt && session.expiresAt <= now) return false;
+      return session.status ? session.status === 'active' : true;
+    } catch (error) {
+      logger.debugWithContext("hasSession lookup failed", {
+        component: "SessionManager",
+        method: "hasSession",
+        sessionId,
+        error: error.message
+      });
+      return false;
+    }
+  }
+
+  /**
+   * Remove a session from storage (e.g. when a client peer logs out). Best
+   * effort; missing sessions are treated as already gone.
+   *
+   * @param {string} sessionId
+   * @returns {Promise<boolean>}
+   */
+  async forgetSession(sessionId) {
+    if (!sessionId) return false;
+    try {
+      return await this.storage.delete(sessionId);
+    } catch (error) {
+      logger.debugWithContext("forgetSession failed", {
+        component: "SessionManager",
+        method: "forgetSession",
+        sessionId,
+        error: error.message
+      });
+      return false;
+    }
+  }
+
   async getSession(sessionId) {
     const requestId = ulid();
     const startTime = Date.now();
@@ -1083,13 +1206,9 @@ class SessionManager {
 
 
   async findSessionsByRoditId(roditId) {
-    const requestId = ulid();
-    const startTime = Date.now();
-    const baseContext = createLogContext("SessionManager", "findSessionsByRoditId", { requestId, roditId });
-    
-    
+    const baseContext = createLogContext("SessionManager", "findSessionsByRoditId", { roditId });
+
     try {
-      let result = [];
       // Get sessions from storage
       let allSessions = [];
       if (typeof this.storage.getAll === 'function') {
@@ -1101,16 +1220,12 @@ class SessionManager {
           if (s) allSessions.push(s);
         }
       }
-      result = allSessions.filter(s => s && s.roditId === roditId);
-      
-      const duration = Date.now() - startTime;
-      
-      
-      return result;
+      return allSessions.filter(s => s && s.roditId === roditId);
     } catch (error) {
-      const duration = Date.now() - startTime;
-          
-      
+      logger.debugWithContext("findSessionsByRoditId lookup failed", {
+        ...baseContext,
+        error: error.message
+      });
       return [];
     }
   }

package/lib/middleware/authenticationmw.js

@@ -2160,6 +2160,9 @@ async function login_portal(config_own_rodit, port, options = {}) {
 
         const peer_base64url_jwk_public_key = Buffer.from(peer_rodit.owner_id, "hex").toString("base64url");
         await stateManager.setPeerBase64urlJwkPublicKey(peer_base64url_jwk_public_key);
+        // Inbound webhooks are verified against the key each webhook advertises
+        // and authorized by binding to the session opened here, so there is no
+        // per-peer key registry to populate.
 
         logger.debug("Peer public key set in state manager", {
           component: "AuthenticationService",

package/lib/middleware/webhookhandlermw.js

@@ -17,8 +17,145 @@ const { ulid } = require("ulid");
 const { sendError } = require("../../services/error-response");
 const nacl = require("tweetnacl");
 const stateManager = require("../blockchain/statemanager");
+const { sessionManager } = require("../auth/sessionmanager");
 const { authenticate_webhook } = require("../auth/authentication");
 
+// ---------------------------------------------------------------------------
+// Webhook identity + session helpers
+// ---------------------------------------------------------------------------
+// A webhook is a one-way POST whose only proof of origin is an Ed25519
+// signature. The signer's public key travels WITH the webhook: the implicit
+// account (hex of the key) and/or the base64url key are advertised in headers.
+// Verification uses that key; authorization then binds it to a live session
+// opened at login (see createWebhookAuthenticationMiddleware). There is nothing
+// to "resolve" from local state, so these are plain extraction helpers.
+
+const IMPLICIT_ACCOUNT_RE = /^[0-9a-f]{64}$/;
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function isImplicitAccount(tokenId) {
+  return IMPLICIT_ACCOUNT_RE.test(normalizeString(tokenId).toLowerCase());
+}
+
+function implicitAccountToBase64urlKey(tokenId) {
+  const hex = normalizeString(tokenId).toLowerCase();
+  if (!IMPLICIT_ACCOUNT_RE.test(hex)) return null;
+  return Buffer.from(hex, "hex").toString("base64url");
+}
+
+function base64urlKeyToImplicitAccount(base64urlKey) {
+  const key = normalizeString(base64urlKey);
+  if (!key) return null;
+  try {
+    const hex = Buffer.from(key, "base64url").toString("hex");
+    return IMPLICIT_ACCOUNT_RE.test(hex) ? hex : null;
+  } catch {
+    return null;
+  }
+}
+
+function headerValue(headers, name) {
+  if (!headers) return "";
+  const raw = headers[name] ?? headers[name.toLowerCase()];
+  if (typeof raw === "string") return raw.trim();
+  if (Array.isArray(raw) && raw.length > 0) return String(raw[0]).trim();
+  return "";
+}
+
+function parseWebhookPayload(rawPayload, parsedBody) {
+  if (parsedBody && typeof parsedBody === "object") return parsedBody;
+  if (typeof rawPayload === "string" && rawPayload.trim()) {
+    try {
+      return JSON.parse(rawPayload);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function sessionIdFromPayload(payload) {
+  if (!payload || typeof payload !== "object") return "";
+  const nested =
+    payload.data && typeof payload.data === "object" && !Array.isArray(payload.data)
+      ? payload.data
+      : null;
+  return (
+    normalizeString(payload.session_id) ||
+    (nested && normalizeString(nested.session_id)) ||
+    ""
+  );
+}
+
+/**
+ * Extract the session id an inbound webhook is correlated with.
+ *
+ * The value carried in the SIGNED payload is authoritative because it is covered
+ * by the Ed25519 signature (payload + timestamp). The x-rodit-session-id header
+ * is only a pre-parse convenience mirror and is used as a fallback. Callers that
+ * need a trusted value should read this only after the signature has verified.
+ *
+ * @param {Object} params
+ * @param {Object} [params.headers] Incoming request headers.
+ * @param {string} [params.rawPayload] Raw request body (string).
+ * @param {Object} [params.parsedBody] Pre-parsed body, if available.
+ * @returns {string} The session id, or "" when none is present.
+ */
+function extractWebhookSessionId(params = {}) {
+  const { headers, rawPayload, parsedBody } = params;
+  const payload = parseWebhookPayload(rawPayload, parsedBody);
+  const fromPayload = sessionIdFromPayload(payload);
+  if (fromPayload) return fromPayload;
+  return headerValue(headers, "x-rodit-session-id");
+}
+
+/**
+ * Extract the Ed25519 public key an inbound webhook must be verified against,
+ * taken directly from the identity the webhook advertises. There is no local
+ * lookup: the key IS the identifier (the implicit account is the hex of the
+ * key). Authorization — proving that key belongs to a peer we logged in with —
+ * is enforced separately by binding to a live session.
+ *
+ * The signer key is carried in two mutually exclusive encodings of the same
+ * identity: `X-Rodit-Implicit-Account` (hex, authoritative and preferred) and
+ * `X-Rodit-Public-Key` (base64url, used only when the implicit account is
+ * absent). Both are emitted by `send_webhook`. The chosen encoding is reported
+ * in `source` so the decision is observable in logs.
+ *
+ * @param {Object} [headers] Incoming request headers.
+ * @returns {{ key: string|null, source: string, implicitAccount: string }}
+ */
+function extractWebhookSignerKey(headers) {
+  const advertisedKey = headerValue(headers, "x-rodit-public-key");
+  const implicit = headerValue(headers, "x-rodit-implicit-account");
+
+  if (isImplicitAccount(implicit)) {
+    const derived = implicitAccountToBase64urlKey(implicit);
+    // When the sender also advertises the raw key it must agree with the
+    // implicit account; a mismatch means a buggy or spoofing sender.
+    if (advertisedKey) {
+      const advertisedImplicit = base64urlKeyToImplicitAccount(advertisedKey);
+      if (advertisedImplicit && advertisedImplicit !== implicit.toLowerCase()) {
+        return { key: null, source: "implicit_mismatch", implicitAccount: implicit.toLowerCase() };
+      }
+    }
+    return { key: derived, source: "implicit_account", implicitAccount: implicit.toLowerCase() };
+  }
+
+  // Only the raw key was advertised: its identity is derived from the key.
+  if (advertisedKey) {
+    const advertisedImplicit = base64urlKeyToImplicitAccount(advertisedKey);
+    if (advertisedImplicit) {
+      return { key: advertisedKey, source: "advertised_key", implicitAccount: advertisedImplicit };
+    }
+  }
+
+  return { key: null, source: "unresolved", implicitAccount: "" };
+}
+
 /**
  * Create a raw body parser middleware specifically for webhook endpoints
  * This preserves the raw body for signature verification
@@ -78,14 +215,15 @@ function createWebhookProcessingMiddleware() {
 }
 
 /**
- * Create middleware to attach the server's public key to the request
- * @param {Object} stateManager - State manager instance
+ * Create middleware that extracts the signer's public key from the inbound
+ * webhook and attaches it to the request for signature verification.
  * @returns {Function} Express middleware
  */
-function createPublicKeyMiddleware(stateManager) {
+function createPublicKeyMiddleware() {
   return async (req, res, next) => {
     const requestId = crypto.randomUUID();
     const logContext = {
+      component: "WebhookHandler",
       requestId,
       apiEndpoint: req.path,
       method: req.method,
@@ -95,17 +233,38 @@ function createPublicKeyMiddleware(stateManager) {
     };
 
     try {
-      // Check if this is a test environment where we should bypass signature verification      
-      // Get the peer public key from the state manager
-      const peerBase64urlJwkPublicKey = stateManager.getPeerBase64urlJwkPublicKey();
-      
-      // If the peer public key is not available and we're not in test mode, return an error
+      // The signer's public key travels with the webhook itself (implicit
+      // account = hex of the key). Extract it directly; each webhook is
+      // self-identifying, so reception is correct even when connected to many
+      // peers. Trust that the key belongs to a known peer is established later
+      // by binding to a session (createWebhookAuthenticationMiddleware).
+      const resolution = extractWebhookSignerKey(req.headers);
+      const peerBase64urlJwkPublicKey = resolution.key;
+
+      // Correlate to the originating session (authoritative once the signature
+      // verifies downstream, since it is carried in the signed payload). Exposed
+      // on the request so handlers can link the webhook to a known session.
+      req.webhook_session_id = extractWebhookSessionId({
+        headers: req.headers,
+        rawPayload: req.rawBody,
+        parsedBody: req.body,
+      });
+
+      if (peerBase64urlJwkPublicKey) {
+        logger.debugWithContext("Extracted webhook signer key", {
+          ...logContext,
+          source: resolution.source,
+          implicitAccount: resolution.implicitAccount
+        });
+      }
+
+      // If the public key is not available and we're not in test mode, return an error
       if (!peerBase64urlJwkPublicKey) {
-        logger.warnWithContext("Peer public key not available in state manager", logContext);
+        logger.warnWithContext("Webhook signer public key not present in request", logContext);
         
         // On main, we need the key
         if (isStrictEnvironment()) {
-          logger.errorWithContext("Peer public key not available in main environment", logContext);
+          logger.errorWithContext("Webhook signer public key not present in main environment", logContext);
           return sendError(res, {
             statusCode: 500,
             requestId,
@@ -115,15 +274,15 @@ function createPublicKeyMiddleware(stateManager) {
         }
         
         // In development or test, we'll continue without the key and skip verification
-        logger.infoWithContext("Continuing without peer public key in non-main environment", {
+        logger.infoWithContext("Continuing without webhook signer key in non-main environment", {
           ...logContext,
           environment: getNodeEnv()
         });
       }
       
       if (peerBase64urlJwkPublicKey) {
-        // Log that we're using the peer public key
-        logger.infoWithContext("Using peer public key from state manager", {
+        // Log that we're using the signer key advertised by the webhook
+        logger.infoWithContext("Using webhook signer public key from request", {
           ...logContext,
           keyFormat: "JWK",
           keyFound: true
@@ -188,6 +347,7 @@ function createWebhookAuthenticationMiddleware() {
   return async (req, res, next) => {
     const requestId = crypto.randomUUID();
     const logContext = {
+      component: "WebhookHandler",
       requestId,
       apiEndpoint: req.path,
       method: req.method,
@@ -306,6 +466,110 @@ function createWebhookAuthenticationMiddleware() {
         });
       }
 
+      // Authorization gate (signer <-> session binding).
+      //
+      // A valid signature only proves the sender holds the private key for the
+      // identity it advertised; it does NOT prove that identity is a peer we
+      // established a session with. Bind the verified signer to a live session
+      // opened at login: the session_id carried in the (now signature-verified)
+      // payload must map to an active session whose ownerId equals the signer's
+      // implicit account (hex of the public key the signature verified against).
+      // This rejects a made-up key that is internally consistent but unrelated
+      // to any peer we logged in with.
+      const bypassSessionBinding =
+        String(config.get('NODE_ENV', 'development')).toLowerCase() === 'test' ||
+        config.get('SECURITY_OPTIONS.BYPASS_WEBHOOK_VERIFICATION', false) === true;
+
+      if (!bypassSessionBinding) {
+        const sessionId =
+          req.webhook_session_id ||
+          extractWebhookSessionId({
+            headers: req.headers,
+            rawPayload: req.rawBody,
+            parsedBody: req.body,
+          });
+
+        if (!sessionId) {
+          logger.warnWithContext("Webhook rejected: not associated with a session", {
+            ...logContext,
+            result: 'failure',
+            reason: 'missing_session_id',
+          });
+          return sendError(res, {
+            statusCode: 401,
+            requestId,
+            code: 'WEBHOOK_SESSION_REQUIRED',
+            message: "Webhook is not associated with a session",
+          });
+        }
+
+        // Derive the verified signer's implicit account from the exact public
+        // key the signature was checked against.
+        let signerImplicitAccount = '';
+        try {
+          signerImplicitAccount = Buffer.from(publicKeyBase64url, 'base64url')
+            .toString('hex')
+            .toLowerCase();
+        } catch (implicitError) {
+          signerImplicitAccount = '';
+        }
+
+        if (!sessionManager || typeof sessionManager.getSession !== 'function') {
+          logger.errorWithContext("Session manager unavailable for webhook binding check", logContext);
+          return sendError(res, {
+            statusCode: 500,
+            requestId,
+            code: "SERVER_CONFIG_ERROR",
+            message: "Server configuration error",
+          });
+        }
+
+        const session = await sessionManager.getSession(sessionId);
+        const nowSec = Math.floor(Date.now() / 1000);
+        const sessionLive =
+          !!session &&
+          (session.status ? session.status === 'active' : true) &&
+          (!session.expiresAt || session.expiresAt > nowSec);
+
+        if (!sessionLive) {
+          logger.warnWithContext("Webhook rejected: session unknown or expired", {
+            ...logContext,
+            result: 'failure',
+            reason: 'session_not_live',
+            sessionId,
+          });
+          return sendError(res, {
+            statusCode: 401,
+            requestId,
+            code: 'WEBHOOK_SESSION_INVALID',
+            message: "Webhook session is unknown or expired",
+          });
+        }
+
+        const sessionOwner = String(session.ownerId || '').toLowerCase();
+        if (!sessionOwner || !signerImplicitAccount || sessionOwner !== signerImplicitAccount) {
+          logger.warnWithContext("Webhook rejected: signer does not match session owner", {
+            ...logContext,
+            result: 'failure',
+            reason: 'signer_session_mismatch',
+            sessionId,
+            signerImplicitAccount,
+            sessionOwner,
+          });
+          return sendError(res, {
+            statusCode: 403,
+            requestId,
+            code: 'WEBHOOK_SIGNER_SESSION_MISMATCH',
+            message: "Webhook signer is not the peer bound to this session",
+          });
+        }
+
+        // Expose the validated binding for downstream handlers.
+        req.webhook_session = session;
+        req.webhook_session_id = sessionId;
+        req.webhook_signer_implicit_account = signerImplicitAccount;
+      }
+
       logger.infoWithContext("Webhook authenticated successfully", {
         ...logContext,
         authDuration: authResult.duration,
@@ -401,15 +665,18 @@ function processWebhookEvent(req, logContext = {}) {
 }
 
 /**
- * Create a complete webhook handler for Express
- * @param {Object} stateManager - State manager instance
- * @param {Object} configuration - Configuration configuration
+ * Create a complete webhook handler for Express.
+ *
+ * The middleware is self-contained: the signer key is extracted from each
+ * inbound webhook and the shared state manager / session manager are imported
+ * directly, so no constructor arguments are required.
+ *
  * @returns {Object} Webhook handler with middleware and utilities
  */
-function createWebhookHandler(stateManager, configuration = {}) {
+function createWebhookHandler() {
   const rawBodyParser = createRawBodyParser();
   const webhookProcessingMiddleware = createWebhookProcessingMiddleware();
-  const publicKeyMiddleware = createPublicKeyMiddleware(stateManager);
+  const publicKeyMiddleware = createPublicKeyMiddleware();
   const authenticationMiddleware = createWebhookAuthenticationMiddleware();
   
   return {
@@ -461,6 +728,65 @@ function createWebhookHandler(stateManager, configuration = {}) {
   };
 }
 
+/**
+ * Resolve the session id to stamp into an outbound webhook so the receiver can
+ * correlate it with the session opened at login.
+ *
+ * Resolution order:
+ *   1. options.sessionId — explicit override (most reliable for multi-peer).
+ *   2. req.user.session_id — the authenticated peer JWT context (set by the auth
+ *      middleware when replying to a request).
+ *   3. req.session_id — session id attached directly to the request.
+ *   4. Session storage — the JWT issuer (login_client) keeps a session per peer
+ *      keyed by that peer's roditId. Given the recipient's identity
+ *      (options.sessionRoditId / options.peerTokenId) we resolve the shared
+ *      session id from the SessionManager without needing any request context.
+ *
+ * @param {Object} options
+ * @param {Object} req
+ * @returns {Promise<string>} The resolved session id, or "" if none.
+ */
+async function resolveOutboundWebhookSessionId(options = {}, req = null) {
+  const explicit =
+    (options && typeof options.sessionId === "string" && options.sessionId.trim()) ||
+    (req && req.user && typeof req.user.session_id === "string" && req.user.session_id.trim()) ||
+    (req && typeof req.session_id === "string" && req.session_id.trim()) ||
+    "";
+  if (explicit) return explicit;
+
+  const roditId =
+    (options && typeof options.sessionRoditId === "string" && options.sessionRoditId.trim()) ||
+    (options && typeof options.peerTokenId === "string" && options.peerTokenId.trim()) ||
+    "";
+  if (!roditId || !sessionManager || typeof sessionManager.findSessionsByRoditId !== "function") {
+    return "";
+  }
+
+  try {
+    const sessions = await sessionManager.findSessionsByRoditId(roditId);
+    if (!Array.isArray(sessions) || sessions.length === 0) return "";
+    const nowSec = Math.floor(Date.now() / 1000);
+    const usable = sessions
+      .filter((s) => s && s.id)
+      // Stamp the session the recipient holds *as a client*, i.e. one this peer
+      // issued as a server. Exclude sessions this peer merely recorded as a
+      // client (origin === "client") so mutual peers don't cross-stamp.
+      .filter((s) => (s.origin ? s.origin !== "client" : true))
+      .filter((s) => (s.status ? s.status === "active" : true))
+      .filter((s) => !s.expiresAt || s.expiresAt > nowSec)
+      .sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
+    return usable.length > 0 ? String(usable[0].id) : "";
+  } catch (sessionLookupError) {
+    logger.debugWithContext("Session storage lookup for webhook failed", {
+      component: "WebhookHandler",
+      method: "send_webhook",
+      roditId,
+      error: sessionLookupError.message
+    });
+    return "";
+  }
+}
+
 /**
     * Send a webhook notification with comprehensive logging
     *
@@ -468,6 +794,8 @@ function createWebhookHandler(stateManager, configuration = {}) {
     * @param {Object} req - Express request object (optional)
     * @param {Object} options - Options object (optional)
     * @param {string} options.endpoint - Target endpoint path (e.g., '/webhook', '/hooks/wake', '/hooks/agent'). Defaults to '/webhook'
+    * @param {string} [options.sessionId] - Explicit session id to correlate this webhook with
+    * @param {string} [options.sessionRoditId] - Recipient peer roditId; used to resolve the session id from session storage
     * @returns {Promise<Object>} Webhook delivery result with requestId
     */
    async function send_webhook(data, req = null, options = {}) {
@@ -632,6 +960,12 @@ function createWebhookHandler(stateManager, configuration = {}) {
          };
        }
        
+       // Correlate this webhook with an existing session when one is known.
+       // Resolved from the explicit option, the authenticated request context,
+       // or session storage (by recipient roditId). Included in the SIGNED
+       // payload below so the receiver can trust and match it.
+       const webhookSessionId = await resolveOutboundWebhookSessionId(options, req);
+
        // Create the payload object
        const payloadObj = {
          event,
@@ -639,6 +973,9 @@ function createWebhookHandler(stateManager, configuration = {}) {
          isError,
          requestId,
        };
+       if (webhookSessionId) {
+         payloadObj.session_id = webhookSessionId;
+       }
        
        // Create the payload with consistent JSON formatting
        // Sort keys to ensure canonical representation regardless of object creation order
@@ -760,15 +1097,41 @@ function createWebhookHandler(stateManager, configuration = {}) {
          signatureHex: signature_hex_ofpayload
        });
    
-       // Prepare headers for the webhook request
-       // Only include webhook-specific authentication headers (digital signature)
-       // No API bearer tokens - webhook security relies on cryptographic signatures
-       const headers = {
-         "Content-Type": "application/json",
-         "X-Signature": signature_hex_ofpayload,
-         "X-Timestamp": timestamp.toString(),
-         "X-Request-ID": requestId
-       };
+      // Prepare headers for the webhook request
+      // Only include webhook-specific authentication headers (digital signature)
+      // No API bearer tokens - webhook security relies on cryptographic signatures
+      const headers = {
+        "Content-Type": "application/json",
+        "X-Signature": signature_hex_ofpayload,
+        "X-Timestamp": timestamp.toString(),
+        "X-Request-ID": requestId
+      };
+
+      // Advertise the signer identity so multi-peer receivers can resolve the
+      // correct verification key deterministically instead of relying on a
+      // single mutable "current peer" slot. The implicit account is the hex of
+      // the signing Ed25519 public key and is authoritative on its own.
+      try {
+        if (publicKey) {
+          headers["X-Rodit-Public-Key"] = publicKey;
+          headers["X-Rodit-Implicit-Account"] = Buffer.from(publicKey, "base64url").toString("hex");
+        }
+        const ownTokenId = config_own_rodit?.own_rodit?.token_id;
+        if (ownTokenId) {
+          headers["X-Rodit-Token-Id"] = String(ownTokenId);
+        }
+      } catch (identityHeaderError) {
+        logger.debugWithContext("Unable to attach signer identity headers", {
+          ...baseContext,
+          error: identityHeaderError.message
+        });
+      }
+
+      // Mirror the (signed) session id into a header for pre-parse correlation.
+      // The signed payload value remains authoritative; this is convenience only.
+      if (webhookSessionId) {
+        headers["X-Rodit-Session-Id"] = webhookSessionId;
+      }
        
        // Log the exact headers being sent
        logger.debugWithContext("Webhook request headers", {
@@ -1377,7 +1740,14 @@ module.exports = {
   processWebhookEvent,
   createWebhookHandler,
   send_webhook,
-  
+
+  // Webhook identity + session helpers
+  extractWebhookSignerKey,
+  extractWebhookSessionId,
+  isImplicitAccount,
+  implicitAccountToBase64urlKey,
+  base64urlKeyToImplicitAccount,
+
   // Added exports from eventhandler.js
   WebhookEventHandler,
   TestConfigUpdateHandler,

package/package.json

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