feat(backend): Introduce M2M endpoints authentication using machine secret keys

.changeset/hot-tables-worry.md

@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+WIP M2M Tokens

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

@@ -1,15 +1,102 @@
 import { joinPaths } from '../../util/path';
+import type { ClerkBackendApiRequestOptions } from '../request';
 import type { MachineToken } from '../resources/MachineToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+type WithMachineSecret<T> = T & { machineSecret?: string | null };
+
+type CreateMachineTokenParams = WithMachineSecret<{
+  claims?: Record<string, any> | null;
+  secondsUntilExpiration?: number | null;
+}>;
+
+type UpdateMachineTokenParams = WithMachineSecret<
+  {
+    m2mTokenId: string;
+    revocationReason?: string | null;
+    revoked?: boolean;
+  } & Pick<CreateMachineTokenParams, 'secondsUntilExpiration' | 'claims'>
+>;
+
+type RevokeMachineTokenParams = WithMachineSecret<{
+  m2mTokenId: string;
+  revocationReason?: string | null;
+}>;
+
+type VerifyMachineTokenParams = WithMachineSecret<{
+  secret: string;
+}>;
+
 export class MachineTokensApi extends AbstractAPI {
-  async verifySecret(secret: string) {
+  #requireMachineSecret(machineSecret?: string | null): asserts machineSecret is string {
+    if (!machineSecret) {
+      throw new Error('A machine secret is required.');
+    }
+  }
+
+  async create(params: CreateMachineTokenParams) {
+    const { machineSecret, ...bodyParams } = params;
+    this.#requireMachineSecret(machineSecret);
     return this.request<MachineToken>({
+      method: 'POST',
+      path: basePath,
+      bodyParams,
+      headerParams: {
+        Authorization: `Bearer ${machineSecret}`,
+      },
+    });
+  }
+
+  async update(params: UpdateMachineTokenParams) {
+    const { m2mTokenId, machineSecret, ...bodyParams } = params;
+    this.#requireMachineSecret(machineSecret);
+    this.requireId(m2mTokenId);
+    return this.request<MachineToken>({
+      method: 'PATCH',
+      path: joinPaths(basePath, m2mTokenId),
+      bodyParams,
+      headerParams: {
+        Authorization: `Bearer ${machineSecret}`,
+      },
+    });
+  }
+
+  async revoke(params: RevokeMachineTokenParams) {
+    const { m2mTokenId, machineSecret, ...bodyParams } = params;
+    this.requireId(m2mTokenId);
+
+    const requestOptions: ClerkBackendApiRequestOptions = {
+      method: 'POST',
+      path: joinPaths(basePath, m2mTokenId, 'revoke'),
+      bodyParams,
+    };
+
+    if (machineSecret) {
+      requestOptions.headerParams = {
+        Authorization: `Bearer ${machineSecret}`,
+      };
+    }
+
+    return this.request<MachineToken>(requestOptions);
+  }
+
+  async verifySecret(params: VerifyMachineTokenParams) {
+    const { secret, machineSecret } = params;
+
+    const requestOptions: ClerkBackendApiRequestOptions = {
       method: 'POST',
       path: joinPaths(basePath, 'verify'),
       bodyParams: { secret },
-    });
+    };
+
+    if (machineSecret) {
+      requestOptions.headerParams = {
+        Authorization: `Bearer ${machineSecret}`,
+      };
+    }
+
+    return this.request<MachineToken>(requestOptions);
   }
 }

packages/backend/src/api/factory.ts

@@ -70,6 +70,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
       buildRequest({
         ...options,
         skipApiVersionInUrl: true,
+        requireSecretKey: false,
       }),
     ),
     oauthApplications: new OAuthApplicationsApi(request),

packages/backend/src/api/request.ts

@@ -104,12 +104,12 @@ export function buildRequest(options: BuildRequestOptions) {
     // Build headers
     const headers = new Headers({
       'Clerk-API-Version': SUPPORTED_BAPI_VERSION,
-      'User-Agent': userAgent,
+      [constants.Headers.UserAgent]: userAgent,
       ...headerParams,
     });
 
-    if (secretKey) {
-      headers.set('Authorization', `Bearer ${secretKey}`);
+    if (secretKey && !headers.has(constants.Headers.Authorization)) {
+      headers.set(constants.Headers.Authorization, `Bearer ${secretKey}`);
     }
 
     let res: Response | undefined;

packages/backend/src/api/resources/JSON.ts

@@ -715,6 +715,7 @@ export interface MachineJSON extends ClerkResourceJSON {
 export interface MachineTokenJSON extends ClerkResourceJSON {
   object: typeof ObjectType.MachineToken;
   name: string;
+  secret?: string;
   subject: string;
   scopes: string[];
   claims: Record<string, any> | null;

packages/backend/src/api/resources/MachineToken.ts

@@ -15,9 +15,10 @@ export class MachineToken {
     readonly creationReason: string | null,
     readonly createdAt: number,
     readonly updatedAt: number,
+    readonly secret?: string,
   ) {}
 
-  static fromJSON(data: MachineTokenJSON) {
+  static fromJSON(data: MachineTokenJSON): MachineToken {
     return new MachineToken(
       data.id,
       data.name,
@@ -32,6 +33,7 @@ export class MachineToken {
       data.creation_reason,
       data.created_at,
       data.updated_at,
+      data.secret,
     );
   }
 }

packages/backend/src/tokens/verify.ts

@@ -206,7 +206,7 @@ async function verifyMachineToken(
 ): Promise<MachineTokenReturnType<MachineToken, MachineTokenVerificationError>> {
   try {
     const client = createBackendApiClient(options);
-    const verifiedToken = await client.machineTokens.verifySecret(secret);
+    const verifiedToken = await client.machineTokens.verifySecret({ secret });
     return { data: verifiedToken, tokenType: TokenType.MachineToken, errors: undefined };
   } catch (err: any) {
     return handleClerkAPIError(TokenType.MachineToken, err, 'Machine token not found');