@contrast/sources 1.1.0

package/lib/index.js

@@ -0,0 +1,109 @@
+/*
+ * Copyright: 2025 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+
+'use strict';
+
+const { EventEmitter } = require('events');
+const onFinished = require('on-finished');
+const { set, Event } = require('@contrast/common');
+const { Core } = require('@contrast/core/lib/ioc/core');
+const NormalizedUriMapper = require('./normalized-uri-mapper');
+const { HttpSourceInfo } = require('./source-info');
+
+const componentName = 'sources';
+
+module.exports = Core.makeComponent({
+  name: componentName,
+  factory: (core) => new Sources(core),
+});
+
+class Sources {
+  constructor(core) {
+    // decorate
+    set(core, componentName, this);
+
+    this.core = core;
+    this._hooks = new EventEmitter();
+    this._normalizedUriMapper = new NormalizedUriMapper(core);
+  }
+
+  addHook(name, handler) {
+    // only this one hook atm
+    if (name === 'onSource') this._hooks.on(name, handler);
+  }
+
+  aroundHook(serverType) {
+    const { _hooks, _normalizedUriMapper, core } = this;
+
+    return function (next, data) {
+      const { args: [event, req, res] } = data;
+
+      if (event !== 'request') {
+        if (event === 'listening') {
+          // take a snapshot of Perf.all at this point. this will get logged
+          // at some point on the perf interval timer.
+          core.Perf.mark('listening');
+          core.messages.emit(Event.SERVER_LISTENING, { type: serverType, server: data.obj });
+        }
+        return next();
+      }
+
+      core.Perf.requestCount += 1;
+
+      const sourceInfo = new HttpSourceInfo({
+        serverType,
+        raw: req,
+        normalizedUriMapper: _normalizedUriMapper,
+      });
+      const store = { sourceInfo };
+
+      onFinished(res, (/* err, req */) => {
+        core.messages.emit(Event.RESPONSE_FINISH, store);
+      });
+
+      return core.scopes.sources.run(store, () => {
+        if (_hooks._events.onSource) {
+          _hooks.emit('onSource', {
+            // future: non-http sources will have their own type
+            sourceType: 'HTTP',
+            store,
+            incomingMessage: req,
+            serverResponse: res,
+          });
+        }
+
+        return next();
+      });
+    };
+  }
+
+  install() {
+    const { instrumentation, sources } = this.core;
+
+    ['http', 'https', 'spdy', 'http2'].forEach((moduleName) => {
+      instrumentation.instrument({
+        moduleName,
+        patchObjects: [{
+          name: 'Server.prototype',
+          methods: ['emit'],
+          patchType: 'sources',
+          around: sources.aroundHook(moduleName)
+        }]
+      });
+    });
+  }
+}
+
+module.exports.HttpSourceInfo = HttpSourceInfo;

package/lib/index.test.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const EventEmitter = require('events');
+const { expect } = require('chai');
+const sinon = require('sinon');
+const { initProtectFixture } = require('@contrast/test/fixtures');
+const mocks = require('@contrast/test/mocks');
+const proxyquire = require('proxyquire');
+
+describe('agentify sources', function () {
+  [
+    {
+      name: 'http',
+      expected: {
+        port: 8080,
+        protocol: 'http',
+        serverType: 'http',
+      },
+    },
+    {
+      name: 'https',
+      expected: {
+        port: 8080,
+        protocol: 'https',
+        serverType: 'https',
+      },
+    },
+    {
+      name: 'spdy',
+      expected: {
+        port: 8080,
+        protocol: 'https',
+        serverType: 'spdy',
+      },
+    },
+    {
+      name: 'http2',
+      method: 'createServer',
+      expected: {
+        port: 8080,
+        protocol: 'https',
+        serverType: 'spdy',
+      },
+    },
+    {
+      name: 'http2',
+      method: 'createSecureServer',
+      expected: {
+        port: 8080,
+        protocol: 'https',
+        serverType: 'spdy',
+      },
+    }
+  ].forEach(({ name, method, expected }) => {
+    describe(`${name} sources using ${method || 'Server'}()`, function () {
+      let core, api, ServerMock, reqMock, resMock, onFinishedMock;
+
+      beforeEach(function () {
+        ({ core } = initProtectFixture());
+        ServerMock = function ServerMock() {
+          this.e = new EventEmitter();
+        };
+        ServerMock.prototype.emit = function (...args) {
+          this.e.emit(...args);
+        };
+        ServerMock.prototype.on = function (...args) {
+          this.e.on(...args);
+        };
+        api = {
+          Server: ServerMock,
+          createServer() {
+            return new ServerMock();
+          },
+          createSecureServer() {
+            return new ServerMock();
+          }
+        };
+        reqMock = mocks.incomingMessage();
+        // resMock = new EventEmitter();
+        onFinishedMock = sinon.stub();
+
+        core.depHooks.resolve.withArgs(sinon.match({ name: 'http' })).yields(api);
+        proxyquire('.', {
+          'on-finished': onFinishedMock,
+        })(core).install();
+      });
+
+      it('"request" events run in scope with correct sourceInfo', function () {
+        const server = method ? api[method]() : new ServerMock();
+        let store;
+
+        server.on('request', function () {
+          store = core.scopes.sources.getStore();
+        });
+
+        server.emit('request', reqMock, resMock);
+
+        expect(store.sourceInfo).to.deep.include({
+          port: 8080,
+          protocol: 'http',
+          serverType: 'http',
+        });
+
+        expect(onFinishedMock).to.have.been.calledWith(resMock);
+      });
+
+      it('non-"request" events do not run in scope', function () {
+        const server = method ? api[method]() : new ServerMock();
+        let store;
+
+        server.on('foo', function () {
+          store = core.scopes.sources.getStore();
+        });
+
+        server.emit('foo', reqMock, resMock);
+        expect(store).to.be.undefined;
+      });
+    });
+  });
+});

package/lib/normalized-uri-mapper.js

@@ -0,0 +1,181 @@
+/*
+ * Copyright: 2025 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+'use strict';
+
+const {
+  Event,
+  get,
+  set,
+  primordials: { StringPrototypeSubstr, StringPrototypeSplit }
+} = require('@contrast/common');
+
+class NormalizedUriMapper {
+  constructor(core) {
+    this._db = {
+      // index by static routes e.g.
+      // '/' => {}
+      // '/home' => {}
+      static: new Map(),
+      // or segment-count for parameterized routes
+      // '2' => { '/users/:id', '/profile/:id' }
+      // '3' => { '/users/:id/orders', '/profile/:id/address' }
+      parameterized: {},
+      // regex is used instead of string path
+      regex: new Map(),
+      // dynamic beyond parameterization e.g. regex syntax, '/abc+', '/abc*', '/[v1|v1.1]/users'.
+      // we could key off of segment length here like we do above.
+      dynamic: {},
+    };
+    this._defaultDynamicRe = /\(|\?|\||\[|\*|\+|\{/;
+    this._hapiDynamicRe = /\(|\?|\||\[|\*|\+/;
+
+    core.messages.on(Event.ROUTE_COVERAGE_DISCOVERY_FINISHED, (routes) => {
+      for (const routeInfo of routes) {
+        this.handleDiscover(routeInfo);
+      }
+    });
+  }
+
+  _getPathSegments(uriPath) {
+    if (!uriPath?.length) return null;
+    return StringPrototypeSplit.call(StringPrototypeSubstr.call(uriPath, 1), '/');
+  }
+
+  _looksDynamic(segment, framework) {
+    if (framework == 'hapi') {
+      return this._hapiDynamicRe.test(segment);
+    }
+    // app.get('/::fiddle') will handle requests to '/:fiddle'
+    if (segment.includes('::')) return true;
+    return this._defaultDynamicRe.test(segment);
+  }
+
+  _looksParamaterized(segment, framework) {
+    if (framework == 'hapi') {
+      return segment.startsWith('{');
+    }
+
+    // no point iterating last character
+    for (let idx = 0; idx < segment.length - 1; idx++) {
+      // '/foo::bar' is not parameterized (fastify) - maps to '/foo:bar'
+      // make sure ':' appears by itself
+      if (
+        segment[idx] == ':' &&
+        segment[idx - 1] != ':' &&
+        segment[idx + 1] != ':'
+      ) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Tries to map a raw URL path to the "normalized" value used to declare the route.
+   * Aims to be as performant as possible.
+   * @param {string} uriPath path without queries
+   * @returns {}
+   */
+  _query(uriPath) {
+    // check if static first
+    if (this._db.static.has(uriPath)) return this._db.static.get(uriPath);
+
+    // else check dynamic routes by segment count
+    const _segments = this._getPathSegments(uriPath);
+    const entriesToCheck = this._db.parameterized[_segments.length];
+
+    if (entriesToCheck) {
+      for (const [, route] of entriesToCheck.entries()) {
+        const { segments } = route;
+        if (segments.every((seg, idx) => !seg || seg == _segments[idx])) {
+          return route;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Registers route discovery meta into _db.
+   * @param {import('@contrast/common').RouteInfo} routeInfo
+   */
+  handleDiscover(routeInfo) {
+    if (!routeInfo.normalizedUrl) {
+      // todo should log but don't have core
+      return;
+    }
+
+    let segments;
+    let dbIndex;
+    let isParameterized = false;
+    let isDynamic = false;
+    const isRegExp = routeInfo.normalizedUrl?.constructor?.name == 'RegExp';
+
+    if (!isRegExp) {
+      segments = this._getPathSegments(routeInfo.normalizedUrl);
+
+      for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        // these heuristic checks may not scale for all frameworks. we may want to dispatch to
+        // a framework-specific strategy that can specialize in mapping to the _db entry index.
+        if (this._looksDynamic(segment, routeInfo.framework)) {
+          isDynamic = true;
+        } else if (this._looksParamaterized(segment, routeInfo.framework)) {
+          isParameterized = true;
+          // replace segments to check with undefined if parameterized
+          segments[i] = undefined;
+        }
+      }
+    }
+
+    const meta = {
+      normalizedUrl: routeInfo.normalizedUrl,
+      signature: routeInfo.signature,
+    };
+
+    if (isDynamic) {
+      dbIndex = `dynamic.${segments.length}`;
+    } else if (isParameterized) {
+      // can be both dynamic and parameterized, e.g. '/:file{.:ext}', '/api/(v1|v2)/:user'
+      // but that's not what we want in this case
+      dbIndex = `parameterized.${segments.length}`;
+      meta.segments = segments;
+    } else if (isRegExp) {
+      dbIndex = 'regex';
+    } else {
+      dbIndex = 'static';
+    }
+
+    // ensure appropriate collection is there
+    if (!get(this._db, dbIndex)) set(this._db, dbIndex, new Map());
+    get(this._db, dbIndex).set(routeInfo.normalizedUrl, meta);
+  }
+
+  /**
+   * Returns the normalizedUrl associated with raw uriPath. If the
+   * value can't be determined from internal _db, this return null.
+   * @param {string} uriPath
+   * @returns {string}
+   */
+  map(uriPath) {
+    /** @type import('@contrast/common').RouteInfo */
+    const record = this._query(uriPath);
+    return record ? record.normalizedUrl : null;
+  }
+}
+
+module.exports = NormalizedUriMapper;

package/lib/normalized-uri-mapper.test.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const EventEmitter = require('node:events');
+const { expect } = require('chai');
+const { Event } = require('@contrast/common');
+const frameworkRoutingData = require('@contrast/test/data/framework-routing-data');
+const NormalizedUrlMapper = require('./normalized-uri-mapper');
+
+describe('route-coverage NormalizedUrlMapper', function() {
+  const testData = Object.values(frameworkRoutingData()).flatMap((a) => a);
+  let mapper;
+  let messages;
+
+  this.beforeEach(function() {
+    messages = new EventEmitter();
+    mapper = new NormalizedUrlMapper({
+      messages,
+    });
+  });
+
+  describe('.map', function() {
+    it('returns null if no discovery events were handled', function() {
+      [
+        '/user/1',
+        '/user/2',
+        '/user/3',
+        '/user/4',
+        '/user/1/cart',
+        '/user/2/cart',
+        '/user/3/cart',
+        '/user/4/cart',
+        '/products/all',
+        '/products/all',
+        '/products/1',
+        '/products/2',
+        '/products/3',
+        '/products/4',
+      ].forEach((uriPath) => {
+        expect(mapper.map(uriPath)).to.be.null;
+      });
+    });
+
+    it('returns normalizedUrl mapped from generic uriPath', function() {
+      messages.emit(Event.ROUTE_COVERAGE_DISCOVERY_FINISHED, testData.map((d) => d.routeInfo));
+      testData.forEach((td) => {
+        const { routeInfo, paths, hasMapping } = td;
+
+        for (const uriPath of paths) {
+          // todo - dynamic and regex paths
+          if (hasMapping === false) {
+            expect(mapper.map(uriPath)).to.be.null;
+          } else {
+            expect(mapper.map(uriPath)).to.equal(routeInfo.normalizedUrl);
+          }
+        }
+      });
+    });
+  });
+});

package/lib/req-data.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright: 2025 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */

package/lib/source-info.js

@@ -0,0 +1,183 @@
+/*
+ * Copyright: 2025 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+
+'use strict';
+
+const {
+  primordials: {
+    RegExpPrototypeExec,
+    StringPrototypeReplace,
+    StringPrototypeSlice,
+    StringPrototypeSplit,
+    StringPrototypeToLowerCase,
+  }
+} = require('@contrast/common');
+
+const NormalizationPatterns = {
+  UUID: [/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, '{uuid}'],
+  NUMERICAL: [/^\d+$/i, '{n}'],
+  HASH: [/([a-fA-F0-9]{2}){16,}/, '{hash}'],
+  // we can extend these as needed
+};
+
+class HttpSourceInfo {
+  /**
+   * @param {object} param
+   * @param {string} param.serverType
+   * @param {any} param.normalizedUriMapper
+   * @param {IncomingMessage} param.raw
+   */
+  constructor({
+    serverType,
+    normalizedUriMapper,
+    raw,
+  }) {
+    this._headerLookupCache = {};
+    this._normalizedUri = null;
+    this._normalizedUriMasked = null;
+    this._normalizedUriSegments = [];
+    this._normalizedUriMapper = normalizedUriMapper;
+    //
+    this.httpVersion = raw.httpVersion;
+    this.ip = raw.socket.remoteAddress ? StringPrototypeReplace.call(raw.socket.remoteAddress, /::ffff:/, '') : undefined;
+    this.port = raw.socket.address?.()?.port || 0;
+    this.protocol = serverType == 'http' ? 'http' : 'https'; // todo
+    this.serverType = serverType;
+    this.time = Date.now();
+    this.method = StringPrototypeToLowerCase.call(raw.method);
+    this.rawHeaders = [];
+
+    for (let i = 0; i < raw.rawHeaders.length; i += 2) {
+      const iNext = i + 1;
+      const headerName = StringPrototypeToLowerCase.call(raw.rawHeaders[i]);
+
+      headerName == 'content-type' && (this.contentType = raw.rawHeaders[iNext]);
+
+      this.rawHeaders[i] = headerName;
+      this.rawHeaders[iNext] = headerName == 'content-type' ?
+        StringPrototypeToLowerCase.call(raw.rawHeaders[iNext]) :
+        raw.rawHeaders[iNext];
+
+      if (
+        headerName == 'upgrade' &&
+        StringPrototypeToLowerCase.call(this.rawHeaders[iNext]) == 'websocket'
+      ) {
+        this.protocol = 'ws';
+      }
+    }
+
+    const idx = raw.url.indexOf('?');
+    if (idx >= 0) {
+      this.uriPath = StringPrototypeSlice.call(raw.url, 0, idx);
+      this.queries = StringPrototypeSlice.call(raw.url, idx + 1);
+    } else {
+      this.uriPath = raw.url;
+      this.queries = '';
+    }
+  }
+
+  /**
+   * Looks through rawHeaders to find it. Caches results to avoid subsequent lookups.
+   * @param {string} name needs to be lowercase
+   * @returns {string}
+   */
+  getHeader(name) {
+    if (name in this._headerLookupCache) return this._headerLookupCache[name];
+
+    for (let i = 0; i < this.rawHeaders.length; i += 2) {
+      if (name == this.rawHeaders[i]) {
+        return (this._headerLookupCache[name] = this.rawHeaders[i + 1]);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * The normalizedUri is a computed field
+   */
+  get normalizedUri() {
+    const r = Reflect.get(this, '_normalizedUri');
+    if (!r) this.generateNormalizedUri();
+    return Reflect.get(this, '_normalizedUri');
+  }
+
+  set normalizedUri(value) {
+    Reflect.set(this, '_normalizedUri', value);
+  }
+
+  generateNormalizedUri() {
+    let normalizedUri;
+
+    // leverage route discovery data to try to find route template
+    normalizedUri = this._normalizedUriMapper?.map?.(this.uriPath);
+
+    if (normalizedUri) {
+      // if we can map to the template we can use it for masked value too
+      this._normalizedUri = normalizedUri;
+      this._normalizedUriMasked = normalizedUri;
+    } else {
+      // if we can't find the template then test against common
+      // regular expressions to normalize/mask each segment per spec
+      const arr = StringPrototypeSplit.call(this.uriPath, '/');
+      let maskedUri = '';
+
+      normalizedUri = '';
+
+      for (let idx = 1; idx < arr.length; idx++) {
+        let normalSeg = arr[idx];
+        let maskedSeg = normalSeg;
+
+        let isPattern;
+
+        for (const [rx, substitution] of Object.values(NormalizationPatterns)) {
+          isPattern = !!RegExpPrototypeExec.call(rx, normalSeg);
+          if (isPattern) {
+            normalSeg = maskedSeg = substitution;
+            break;
+          }
+        }
+
+        if (!isPattern) {
+          if (idx > 1) {
+            maskedSeg = `${StringPrototypeSlice.call(normalSeg, 0, 2)}xxxx`;
+          } else {
+            // no masking/normalizing for first seg (called "context" in spec)
+            maskedSeg = arr[idx];
+          }
+        }
+
+        maskedUri += `/${maskedSeg}`;
+        normalizedUri += `/${normalSeg}`;
+      }
+
+      this._normalizedUri = normalizedUri;
+      this._normalizedUriMasked = maskedUri;
+    }
+  }
+
+  get normalizedUriMasked() {
+    const r = Reflect.get(this, '_normalizedUriMasked');
+    if (!r) this.generateNormalizedUri();
+    return Reflect.get(this, '_normalizedUriMasked');
+  }
+
+  set normalizedUriMasked(value) {
+    Reflect.set(this, '_normalizedUriMasked', value);
+  }
+}
+
+module.exports.HttpSourceInfo = HttpSourceInfo;
+module.exports.NORMALIZE_PATTERNS = NormalizationPatterns;

package/lib/source-info.test.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { expect } = require('chai');
+const mocks = require('@contrast/test/mocks');
+
+const { HttpSourceInfo } = require('./source-info');
+
+describe('sources SourceInfo', function () {
+  [
+    {
+      uriPath: '/index',
+      expectedNormalized: '/index',
+      expectedNormalizedMasked: '/index',
+    },
+    {
+      uriPath: '/orders/abc-123',
+      expectedNormalized: '/orders/abc-123',
+      expectedNormalizedMasked: '/orders/abxxxx',
+    },
+    {
+      uriPath: '/orders/abc-123/item/123',
+      expectedNormalized: '/orders/abc-123/item/{n}',
+      expectedNormalizedMasked: '/orders/abxxxx/itxxxx/{n}',
+    },
+    {
+      uriPath: '/orders/1234',
+      expectedNormalized: '/orders/{n}',
+      expectedNormalizedMasked: '/orders/{n}',
+    },
+    {
+      uriPath: '/orders/93a0862a-09be-4292-bc6a-50d38dded69c',
+      expectedNormalized: '/orders/{uuid}',
+      expectedNormalizedMasked: '/orders/{uuid}',
+    },
+    {
+      uriPath: '/orders/0f1e2d3c4b5a6f7e8d9c0b1a2f3e4d5c',
+      expectedNormalized: '/orders/{hash}',
+      expectedNormalizedMasked: '/orders/{hash}',
+    },
+  ].forEach(({
+    uriPath,
+    expectedNormalized,
+    expectedNormalizedMasked,
+  }) => {
+    it(`normalizedUri and normalizedUriMasked are built correctly: ${uriPath}`, function () {
+      const req = mocks.incomingMessage();
+      req.url = `${uriPath}?${req.queries}`;
+
+      const info = new HttpSourceInfo({
+        serverType: 'http',
+        raw: req
+      });
+      expect(info.normalizedUri).to.equal(expectedNormalized);
+      expect(info.normalizedUriMasked).to.equal(expectedNormalizedMasked);
+    });
+  });
+
+  it('trims IPv6 prefixes from mapped IPv4 addresses', function () {
+    const req = mocks.incomingMessage();
+    req.socket.remoteAddress = '::ffff:127.0.0.1';
+
+    const info = new HttpSourceInfo({
+      serverType: 'http',
+      raw: req
+    });
+    expect(info.ip).to.equal('127.0.0.1');
+  });
+});

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@contrast/sources",
+  "version": "1.1.0",
+  "description": "Instruments to have incoming messages run in async-local request scope.",
+  "main": "lib/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@contrast/common": "1.35.0",
+    "@contrast/core": "1.55.0",
+    "on-finished": "^2.4.1"
+  }
+}