Add "source" field to user-agent header (#2740)

* Add source field to user-agent header

* be more defensive in case something goes wrong

Author: xavdid

src/platform/NodePlatformFunctions.ts

@@ -1,5 +1,6 @@
 import * as crypto from 'crypto';
 import * as http from 'http';
+import * as os from 'os';
 import {CryptoProvider} from '../crypto/CryptoProvider.js';
 import {EventEmitter} from 'events';
 import {HttpClient, NodeHttpClientInterface} from '../net/HttpClient.js';
@@ -8,7 +9,6 @@ import {NodeHttpClient} from '../net/NodeHttpClient.js';
 import {PlatformFunctions} from './PlatformFunctions.js';
 import {StripeError} from '../Error.js';
 import {concat} from '../utils.js';
-import {arch, release} from 'os';
 import {MultipartRequestData, RequestData, BufferedFile} from '../Types.js';
 
 class StreamProcessingError extends StripeError {}
@@ -28,7 +28,7 @@ export class NodePlatformFunctions extends PlatformFunctions {
 
   /** @override */
   getPlatformInfo(): string {
-    return `${process.platform} ${release()} ${arch()}`;
+    return `${process.platform} ${os.release()} ${os.arch()}`;
   }
 
   /** @override */
@@ -50,6 +50,38 @@ export class NodePlatformFunctions extends PlatformFunctions {
     return process.version;
   }
 
+  private getUname(): string | null {
+    try {
+      const parts = [os.type(), os.release(), os.arch()];
+      // os.version() returns detailed kernel version, available since Node 10.7.0
+      // It may not exist in older typings, so access carefully
+      const version = (os as any).version?.();
+      if (version) parts.push(version);
+      try {
+        parts.push(os.hostname());
+        // eslint-disable-next-line no-empty
+      } catch (_e) {}
+      return parts.join(' ');
+    } catch {
+      return null;
+    }
+  }
+
+  /** @override */
+  getSourceHash(): string | null {
+    try {
+      const uname = this.getUname();
+      return uname
+        ? crypto
+            .createHash('md5')
+            .update(uname)
+            .digest('hex')
+        : null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * @override
    * Secure compare, from https://github.com/freewil/scmp

src/platform/PlatformFunctions.ts

@@ -35,6 +35,10 @@ export class PlatformFunctions {
     return null;
   }
 
+  getSourceHash(): string | null {
+    return null;
+  }
+
   /**
    * Emits a warning. Node.js uses process.emitWarning; other runtimes
    * fall back to console.warn.

src/stripe.core.ts

@@ -956,6 +956,7 @@ export class Stripe {
     lang: 'node',
     typescript: false,
   };
+  static SOURCE_HASH: string | null = null;
   static StripeResource = StripeResource;
   static resources = resources;
   static HttpClient = HttpClient;
@@ -1099,6 +1100,8 @@ export class Stripe {
       ...(runtimeVersion ? {lang_version: runtimeVersion} : {}),
       ...(Stripe.aiAgent ? {ai_agent: Stripe.aiAgent} : {}),
     };
+
+    Stripe.SOURCE_HASH = platformFunctions.getSourceHash();
   }
 
   constructor(key: string, config: StripeConfig = {}) {
@@ -1445,6 +1448,10 @@ export class Stripe {
       userAgent.application = this._appInfo;
     }
 
+    if (Stripe.SOURCE_HASH) {
+      userAgent.source = Stripe.SOURCE_HASH;
+    }
+
     cb(JSON.stringify(userAgent));
   }
 

test/PlatformFunctions.spec.ts

@@ -160,6 +160,27 @@ function testPlatform(platformFunctions: PlatformFunctions): void {
       }
     });
 
+    describe('getSourceHash', () => {
+      if (isNodeEnvironment) {
+        it('returns a 32-character hex MD5 string', () => {
+          const hash = platformFunctions.getSourceHash();
+          expect(hash).to.be.a('string');
+          expect(hash).to.match(/^[0-9a-f]{32}$/);
+        });
+
+        it('returns null when getUname returns null', () => {
+          const orig = platformFunctions.getUname.bind(platformFunctions);
+          (platformFunctions as any).getUname = () => null;
+          expect(platformFunctions.getSourceHash()).to.be.null;
+          (platformFunctions as any).getUname = orig;
+        });
+      } else {
+        it('returns null on non-Node environments', () => {
+          expect(platformFunctions.getSourceHash()).to.be.null;
+        });
+      }
+    });
+
     describe('createEmitter', () => {
       let emitter;
       beforeEach(() => {

test/stripe.spec.ts

@@ -253,6 +253,37 @@ describe('Stripe Module', function() {
         })
       ).to.eventually.have.property('httplib', 'node');
     });
+
+    it('Should include source field when SOURCE_HASH is set', async () => {
+      const origSourceHash = StripeCore.SOURCE_HASH;
+      StripeCore.SOURCE_HASH = 'abc123def456abc123def456abc123de';
+
+      const userAgent: Record<string, string> = await new Promise((resolve) => {
+        stripe.getClientUserAgentSeeded({lang: 'node'}, (c) => {
+          resolve(JSON.parse(c));
+        });
+      });
+
+      StripeCore.SOURCE_HASH = origSourceHash;
+      expect(userAgent).to.have.property(
+        'source',
+        'abc123def456abc123def456abc123de'
+      );
+    });
+
+    it('Should omit source field when SOURCE_HASH is null', async () => {
+      const origSourceHash = StripeCore.SOURCE_HASH;
+      StripeCore.SOURCE_HASH = null;
+
+      const userAgent: Record<string, string> = await new Promise((resolve) => {
+        stripe.getClientUserAgentSeeded({lang: 'node'}, (c) => {
+          resolve(JSON.parse(c));
+        });
+      });
+
+      StripeCore.SOURCE_HASH = origSourceHash;
+      expect(userAgent).to.not.have.property('source');
+    });
   });
 
   describe('AI agent detection', () => {
@@ -324,11 +355,13 @@ describe('Stripe Module', function() {
     const origAIAgent = StripeCore.aiAgent;
     const origAiAgentStatic = StripeCore.AI_AGENT;
     const origUserAgent = StripeCore.USER_AGENT;
+    const origSourceHash = StripeCore.SOURCE_HASH;
 
     afterEach(() => {
       StripeCore.aiAgent = origAIAgent;
       StripeCore.AI_AGENT = origAiAgentStatic;
       StripeCore.USER_AGENT = origUserAgent;
+      StripeCore.SOURCE_HASH = origSourceHash;
       StripeCore.initialize(new NodePlatformFunctions());
     });
 
@@ -358,6 +391,32 @@ describe('Stripe Module', function() {
       expect(StripeCore.USER_AGENT).to.not.have.property('ai_agent');
       expect(StripeCore.USER_AGENT).to.not.have.property('lang_version');
     });
+
+    it('sets SOURCE_HASH to an MD5 hex string when getSourceHash is available', () => {
+      const mockPlatform = new NodePlatformFunctions();
+      const expectedHash = crypto
+        .createHash('md5')
+        .update('Linux hostname 5.4.0 #1 SMP x86_64 GNU/Linux')
+        .digest('hex');
+      mockPlatform.getSourceHash = () => expectedHash;
+
+      StripeCore.initialize(mockPlatform);
+
+      expect(StripeCore.SOURCE_HASH).to.be.a('string');
+      expect(StripeCore.SOURCE_HASH).to.match(/^[0-9a-f]{32}$/);
+      expect(StripeCore.SOURCE_HASH).to.equal(expectedHash);
+    });
+
+    it('sets SOURCE_HASH to null when getSourceHash returns null', () => {
+      const {
+        PlatformFunctions,
+      } = require('../src/platform/PlatformFunctions.js');
+      const basePlatform = new PlatformFunctions();
+
+      StripeCore.initialize(basePlatform);
+
+      expect(StripeCore.SOURCE_HASH).to.be.null;
+    });
   });
 
   describe('timeout config', () => {