feat(nextjs): Include metadata as headers on keyless creation

.changeset/strong-chicken-lie.md

@@ -0,0 +1,6 @@
+---
+"@clerk/backend": patch
+"@clerk/nextjs": patch
+---
+
+feat(nextjs): Forward user-agent, arch, platform, and npm config with POST requests to /accountless_applications

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -5,17 +5,21 @@ import { AbstractAPI } from './AbstractApi';
 const basePath = '/accountless_applications';
 
 export class AccountlessApplicationAPI extends AbstractAPI {
-  public async createAccountlessApplication() {
+  public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+    const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
     return this.request<AccountlessApplication>({
       method: 'POST',
       path: basePath,
+      headerParams,
     });
   }
 
-  public async completeAccountlessApplicationOnboarding() {
+  public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+    const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
     return this.request<AccountlessApplication>({
       method: 'POST',
       path: joinPaths(basePath, 'complete'),
+      headerParams,
     });
   }
 }

packages/nextjs/src/app-router/server/keyless-provider.tsx

@@ -5,6 +5,7 @@ import type { PropsWithChildren } from 'react';
 import React from 'react';
 
 import { createClerkClientWithOptions } from '../../server/createClerkClient';
+import { collectKeylessMetadata, formatMetadataHeaders } from '../../server/keyless-custom-headers';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -92,12 +93,20 @@ export const KeylessProvider = async (props: KeylessProviderProps) => {
         secretKey,
       });
 
+      // Collect metadata
+      const keylessHeaders = await collectKeylessMetadata()
+        .then(formatMetadataHeaders)
+        .catch(() => new Headers());
+
       /**
        * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
        * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
        */
       await clerkDevelopmentCache?.run(
-        () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+        () =>
+          client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+            requestHeaders: keylessHeaders,
+          }),
         {
           cacheKey: `${newOrReadKeys.publishableKey}_complete`,
           onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours

packages/nextjs/src/server/keyless-custom-headers.ts

@@ -0,0 +1,58 @@
+import { headers } from 'next/headers';
+
+interface MetadataHeaders {
+  nodeVersion?: string;
+  nextVersion?: string;
+  npmConfigUserAgent?: string;
+  userAgent?: string;
+}
+
+/**
+ * Collects metadata from the environment and request headers
+ */
+export async function collectKeylessMetadata(): Promise<MetadataHeaders> {
+  const headerStore = await headers(); // eslint-disable-line
+
+  return {
+    nodeVersion: process.version,
+    nextVersion: getNextVersion(),
+    npmConfigUserAgent: process.env.npm_config_user_agent, // eslint-disable-line
+    userAgent: headerStore.get('User-Agent') ?? undefined,
+  };
+}
+
+/**
+ * Extracts Next.js version from process title
+ */
+function getNextVersion(): string | undefined {
+  try {
+    return process.title ?? 'unknown-process-title'; // 'next-server (v15.4.5)'
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Converts metadata to HTTP headers
+ */
+export function formatMetadataHeaders(metadata: MetadataHeaders): Headers {
+  const headers = new Headers();
+
+  if (metadata.nodeVersion) {
+    headers.set('Clerk-Node-Version', metadata.nodeVersion);
+  }
+
+  if (metadata.nextVersion) {
+    headers.set('Clerk-Next-Version', metadata.nextVersion);
+  }
+
+  if (metadata.npmConfigUserAgent) {
+    headers.set('Clerk-NPM-Config-User-Agent', metadata.npmConfigUserAgent);
+  }
+
+  if (metadata.userAgent) {
+    headers.set('Clerk-Client-User-Agent', metadata.userAgent);
+  }
+
+  return headers;
+}

packages/nextjs/src/server/keyless-node.ts

@@ -2,6 +2,7 @@ import type { AccountlessApplication } from '@clerk/backend';
 
 import { createClerkClientWithOptions } from './createClerkClient';
 import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './fs/utils';
+import { collectKeylessMetadata, formatMetadataHeaders } from './keyless-custom-headers';
 
 /**
  * The Clerk-specific directory name.
@@ -134,8 +135,14 @@ async function createOrReadKeyless(): Promise<AccountlessApplication | null> {
    * At this step, it is safe to create new keys and store them.
    */
   const client = createClerkClientWithOptions({});
+
+  // Collect metadata
+  const keylessHeaders = await collectKeylessMetadata()
+    .then(formatMetadataHeaders)
+    .catch(() => new Headers());
+
   const accountlessApplication = await client.__experimental_accountlessApplications
-    .createAccountlessApplication()
+    .createAccountlessApplication({ requestHeaders: keylessHeaders })
     .catch(() => null);
 
   if (accountlessApplication) {