feat(auth0-server-js): send telemetry for every request to auth0

packages/auth0-server-js/src/server-client.spec.ts

@@ -2769,3 +2769,115 @@ test('handleBackchannelLogout - should throw when no refresh token provided', as
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   await expect(serverClient.handleBackchannelLogout(undefined as any)).rejects.toThrowError('Missing Logout Token');
 });
+
+test('Telemetry - should include Auth0-Client header with server-js package info by default', async () => {
+  let capturedHeader: string | null = null;
+  server.use(
+    http.get(`https://${domain}/.well-known/openid-configuration`, ({ request }) => {
+      capturedHeader = request.headers.get('Auth0-Client');
+      return HttpResponse.json(mockOpenIdConfiguration);
+    })
+  );
+
+  const serverClient = new ServerClient({
+    domain,
+    clientId: '<client_id>',
+    clientSecret: '<client_secret>',
+    stateStore: new DefaultStateStore({ secret: '<secret>' }),
+    transactionStore: new DefaultTransactionStore({ secret: '<secret>' }),
+  });
+
+  await serverClient.startInteractiveLogin({
+    authorizationParams: { redirect_uri: '/test_redirect_uri' },
+  });
+
+  expect(capturedHeader).toBeDefined();
+  const decoded = JSON.parse(Buffer.from(capturedHeader!, 'base64').toString());
+  expect(decoded.name).toBe('@auth0/auth0-server-js');
+  expect(decoded.version).toMatch(/^\d+\.\d+\.\d+/);
+});
+
+test('Telemetry - should allow custom telemetry name and version', async () => {
+  let capturedHeader: string | null = null;
+  server.use(
+    http.get(`https://${domain}/.well-known/openid-configuration`, ({ request }) => {
+      capturedHeader = request.headers.get('Auth0-Client');
+      return HttpResponse.json(mockOpenIdConfiguration);
+    })
+  );
+
+  const serverClient = new ServerClient({
+    domain,
+    clientId: '<client_id>',
+    clientSecret: '<client_secret>',
+    stateStore: new DefaultStateStore({ secret: '<secret>' }),
+    transactionStore: new DefaultTransactionStore({ secret: '<secret>' }),
+    telemetry: {
+      name: 'my-custom-server-app',
+      version: '3.0.0',
+    },
+  });
+
+  await serverClient.startInteractiveLogin({
+    authorizationParams: { redirect_uri: '/test_redirect_uri' },
+  });
+
+  expect(capturedHeader).toBeDefined();
+  const decoded = JSON.parse(Buffer.from(capturedHeader!, 'base64').toString());
+  expect(decoded.name).toBe('my-custom-server-app');
+  expect(decoded.version).toBe('3.0.0');
+});
+
+test('Telemetry - should not include Auth0-Client header when telemetry is disabled', async () => {
+  let capturedHeader: string | null = null;
+  server.use(
+    http.get(`https://${domain}/.well-known/openid-configuration`, ({ request }) => {
+      capturedHeader = request.headers.get('Auth0-Client');
+      return HttpResponse.json(mockOpenIdConfiguration);
+    })
+  );
+
+  const serverClient = new ServerClient({
+    domain,
+    clientId: '<client_id>',
+    clientSecret: '<client_secret>',
+    stateStore: new DefaultStateStore({ secret: '<secret>' }),
+    transactionStore: new DefaultTransactionStore({ secret: '<secret>' }),
+    telemetry: { enabled: false },
+  });
+
+  await serverClient.startInteractiveLogin({
+    authorizationParams: { redirect_uri: '/test_redirect_uri' },
+  });
+
+  expect(capturedHeader).toBeNull();
+});
+
+test('Telemetry - should include Auth0-Client header in token requests', async () => {
+  let capturedHeader: string | null = null;
+  server.use(
+    http.post(mockOpenIdConfiguration.backchannel_authentication_endpoint, async ({ request }) => {
+      capturedHeader = request.headers.get('Auth0-Client');
+      return HttpResponse.json({
+        auth_req_id: 'auth_req_123',
+        interval: 0.5,
+        expires_in: 60,
+      });
+    })
+  );
+
+  const serverClient = new ServerClient({
+    domain,
+    clientId: '<client_id>',
+    clientSecret: '<client_secret>',
+    stateStore: new DefaultStateStore({ secret: '<secret>' }),
+    transactionStore: new DefaultTransactionStore({ secret: '<secret>' }),
+  });
+
+  await serverClient.loginBackchannel({ loginHint: 'user@example.com' });
+
+  expect(capturedHeader).toBeDefined();
+  const decoded = JSON.parse(Buffer.from(capturedHeader!, 'base64').toString());
+  expect(decoded.name).toBe('@auth0/auth0-server-js');
+  expect(decoded.version).toMatch(/^\d+\.\d+\.\d+/);
+});

packages/auth0-server-js/src/server-client.ts

@@ -30,6 +30,7 @@ import {
   TokenByRefreshTokenOptions,
 } from '@auth0/auth0-auth-js';
 import { compareScopes } from './utils.js';
+import { getTelemetryConfig } from './telemetry.js';
 
 const DEFAULT_SCOPES = 'openid profile email offline_access';
 
@@ -91,6 +92,7 @@ export class ServerClient<TStoreOptions = unknown> {
       authorizationParams: this.#options.authorizationParams,
       customFetch: this.#options.customFetch,
       useMtls: this.#options.useMtls,
+      telemetry: getTelemetryConfig(this.#options.telemetry),
     });
   }
 

packages/auth0-server-js/src/telemetry.ts

@@ -0,0 +1,17 @@
+import { TelemetryConfig } from '@auth0/auth0-auth-js';
+
+// These constants are injected at build time via tsup
+declare const __AUTH0_SERVER_JS_PACKAGE_NAME__: string;
+declare const __AUTH0_SERVER_JS_PACKAGE_VERSION__: string;
+
+export function getTelemetryConfig(config?: TelemetryConfig): TelemetryConfig {
+  if (config?.enabled === false) {
+    return config;
+  }
+
+  return {
+    enabled: true,
+    name: config?.name ?? __AUTH0_SERVER_JS_PACKAGE_NAME__,
+    version: config?.version ?? __AUTH0_SERVER_JS_PACKAGE_VERSION__,
+  };
+}

packages/auth0-server-js/src/types.ts

@@ -1,4 +1,6 @@
-import { AuthorizationDetails } from '@auth0/auth0-auth-js';
+import type { AuthorizationDetails, TelemetryConfig } from '@auth0/auth0-auth-js';
+
+export type { TelemetryConfig } from '@auth0/auth0-auth-js';
 
 export interface ServerClientOptions<TStoreOptions = unknown> {
   domain: string;
@@ -18,10 +20,16 @@ export interface ServerClientOptions<TStoreOptions = unknown> {
 
   /**
    * Indicates whether the SDK should use the mTLS endpoints if they are available.
-   * 
+   *
    * When set to `true`, using a `customFetch` is required.
    */
   useMtls?: boolean;
+
+  /**
+   * Optional telemetry configuration.
+   * Telemetry is enabled by default and sends the Auth0-Client header with package name and version.
+   */
+  telemetry?: TelemetryConfig;
 }
 
 export interface UserClaims {

packages/auth0-server-js/tsup.config.ts

@@ -1,4 +1,7 @@
 import { defineConfig } from "tsup";
+import { readFileSync } from "fs";
+
+const packageJson = JSON.parse(readFileSync("./package.json", "utf-8"));
 
 export default defineConfig([
   {
@@ -8,5 +11,9 @@ export default defineConfig([
     format: ["cjs", "esm"],
     dts: true,
     sourcemap: true,
+    define: {
+      __AUTH0_SERVER_JS_PACKAGE_NAME__: JSON.stringify(packageJson.name),
+      __AUTH0_SERVER_JS_PACKAGE_VERSION__: JSON.stringify(packageJson.version),
+    },
   },
 ]);

packages/auth0-server-js/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+import { readFileSync } from 'fs';
+
+const packageJson = JSON.parse(readFileSync('./package.json', 'utf-8'));
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'v8',
+    },
+  },
+  define: {
+    __AUTH0_SERVER_JS_PACKAGE_NAME__: JSON.stringify(packageJson.name),
+    __AUTH0_SERVER_JS_PACKAGE_VERSION__: JSON.stringify(packageJson.version),
+  },
+});