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

.changeset/hot-tables-worry.md

@@ -0,0 +1,72 @@
+---
+"@clerk/backend": minor
+---
+
+Adds machine-to-machine endpoints to the Backend SDK:
+
+### Create M2M Tokens
+
+A machine secret is required when creating M2M tokens.
+
+```ts
+const clerkClient = createClerkClient()
+
+clerkClient.machineTokens.create({
+    machineSecret: 'ak_xxxxx',
+})
+```
+
+### Revoke M2M Tokens
+
+You can revoke tokens using either a machine secret or instance secret:
+
+```ts
+// Using machine secret
+const clerkClient = createClerkClient()
+clerkClient.machineTokens.revoke({
+    machineSecret: 'ak_xxxxx',
+    m2mTokenId: 'mt_xxxxx',
+    revocationReason: 'Revoked by user',
+})
+
+// Using instance secret (default)
+const clerkClient = createClerkClient({ secretKey: 'sk_xxxx' })
+clerkClient.machineTokens.revoke({
+    m2mTokenId: 'mt_xxxxx',
+    revocationReason: 'Revoked by user',
+})
+```
+
+### Verify M2M Tokens
+
+You can verify tokens using either a machine secret or instance secret:
+
+```ts
+// Using machine secret
+const clerkClient = createClerkClient()
+clerkClient.machineTokens.verifySecret({
+    machineSecret: 'ak_xxxxx',
+    secret: 'mt_secret_xxxxx',
+})
+
+// Using instance secret (default)
+const clerkClient = createClerkClient({ secretKey: 'sk_xxxx' })
+clerkClient.machineTokens.verifySecret({
+    secret: 'mt_secret_xxxxx',
+})
+```
+
+To verify machine-to-machine tokens using when using `authenticateRequest()` with a machine secret, use the `machineSecret` option:
+
+```ts
+const clerkClient = createClerkClient()
+
+const authReq = await clerkClient.authenticateRequest(c.req.raw, {
+  acceptsToken: 'machine_token',
+  machineSecret: 'ak_xxxxx'
+})
+
+if (authReq.isAuthenticated) {
+    // ... do something
+}
+```

packages/backend/src/api/__tests__/MachineTokenApi.test.ts

@@ -0,0 +1,255 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server, validateHeaders } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('MachineTokenAPI', () => {
+  const m2mId = 'mt_xxxxx';
+  const m2mSecret = 'mt_secret_xxxxx';
+
+  const mockM2MToken = {
+    object: 'machine_to_machine_token',
+    id: m2mId,
+    subject: 'mch_xxxxx',
+    scopes: ['mch_1xxxxx', 'mch_2xxxxx'],
+    claims: { foo: 'bar' },
+    secret: m2mSecret,
+    revoked: false,
+    revocation_reason: null,
+    expired: false,
+    expiration: 1753746916590,
+    created_at: 1753743316590,
+    updated_at: 1753743316590,
+  };
+
+  describe('create', () => {
+    it('creates a m2m token using machine secret', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+      });
+
+      const createParams = {
+        machineSecret: 'ak_xxxxx',
+        secondsUntilExpiration: 3600,
+      };
+
+      server.use(
+        http.post(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(({ request }) => {
+            expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+            return HttpResponse.json(mockM2MToken);
+          }),
+        ),
+      );
+
+      const response = await apiClient.machineTokens.create(createParams);
+
+      expect(response.id).toBe(m2mId);
+      expect(response.secret).toBe(m2mSecret);
+      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.claims).toEqual({ foo: 'bar' });
+    });
+
+    it('does not accept an instance secret as authorization header', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'sk_xxxxx',
+      });
+
+      server.use(
+        http.post(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(() => {
+            return HttpResponse.json(mockM2MToken);
+          }),
+        ),
+      );
+
+      // @ts-expect-error - machineSecret is required
+      const response = await apiClient.machineTokens.create({}).catch(err => err);
+
+      expect(response.message).toBe('Missing machine secret.');
+    });
+  });
+
+  describe('revoke', () => {
+    const mockRevokedM2MToken = {
+      object: 'machine_to_machine_token',
+      id: m2mId,
+      subject: 'mch_xxxxx',
+      scopes: ['mch_1xxxxx', 'mch_2xxxxx'],
+      claims: { foo: 'bar' },
+      revoked: true,
+      revocation_reason: 'revoked by test',
+      expired: false,
+      expiration: 1753746916590,
+      created_at: 1753743316590,
+      updated_at: 1753743316590,
+    };
+
+    it('revokes a m2m token using machine secret', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+      });
+
+      const revokeParams = {
+        machineSecret: 'ak_xxxxx',
+        m2mTokenId: m2mId,
+        revocationReason: 'revoked by test',
+      };
+
+      server.use(
+        http.post(
+          `https://api.clerk.test/m2m_tokens/${m2mId}/revoke`,
+          validateHeaders(({ request }) => {
+            expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+            return HttpResponse.json(mockRevokedM2MToken);
+          }),
+        ),
+      );
+
+      const response = await apiClient.machineTokens.revoke(revokeParams);
+
+      expect(response.revoked).toBe(true);
+      expect(response.secret).toBeUndefined();
+      expect(response.revocationReason).toBe('revoked by test');
+      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.claims).toEqual({ foo: 'bar' });
+    });
+
+    it('revokes a m2m token using instance secret', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'sk_xxxxx',
+      });
+
+      const revokeParams = {
+        m2mTokenId: m2mId,
+        revocationReason: 'revoked by test',
+      };
+
+      server.use(
+        http.post(
+          `https://api.clerk.test/m2m_tokens/${m2mId}/revoke`,
+          validateHeaders(({ request }) => {
+            expect(request.headers.get('Authorization')).toBe('Bearer sk_xxxxx');
+            return HttpResponse.json(mockRevokedM2MToken);
+          }),
+        ),
+      );
+
+      const response = await apiClient.machineTokens.revoke(revokeParams);
+
+      expect(response.revoked).toBe(true);
+      expect(response.secret).toBeUndefined();
+      expect(response.revocationReason).toBe('revoked by test');
+    });
+
+    it('requires a machine secret or instance secret to revoke a m2m token', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+      });
+
+      const revokeParams = {
+        m2mTokenId: m2mId,
+        revocationReason: 'revoked by test',
+      };
+
+      server.use(
+        http.post(
+          `https://api.clerk.test/m2m_tokens/${m2mId}/revoke`,
+          validateHeaders(() => {
+            return HttpResponse.json(mockRevokedM2MToken);
+          }),
+        ),
+      );
+
+      const errResponse = await apiClient.machineTokens.revoke(revokeParams).catch(err => err);
+
+      expect(errResponse.status).toBe(401);
+    });
+  });
+
+  describe('verifySecret', () => {
+    it('verifies a m2m token using machine secret', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+      });
+
+      const verifyParams = {
+        machineSecret: 'ak_xxxxx',
+        secret: m2mSecret,
+      };
+
+      server.use(
+        http.post(
+          'https://api.clerk.test/m2m_tokens/verify',
+          validateHeaders(({ request }) => {
+            expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+            return HttpResponse.json(mockM2MToken);
+          }),
+        ),
+      );
+
+      const response = await apiClient.machineTokens.verifySecret(verifyParams);
+
+      expect(response.id).toBe(m2mId);
+      expect(response.secret).toBe(m2mSecret);
+      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.claims).toEqual({ foo: 'bar' });
+    });
+
+    it('verifies a m2m token using instance secret', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'sk_xxxxx',
+      });
+
+      const verifyParams = {
+        secret: m2mSecret,
+      };
+
+      server.use(
+        http.post(
+          'https://api.clerk.test/m2m_tokens/verify',
+          validateHeaders(({ request }) => {
+            expect(request.headers.get('Authorization')).toBe('Bearer sk_xxxxx');
+            return HttpResponse.json(mockM2MToken);
+          }),
+        ),
+      );
+
+      const response = await apiClient.machineTokens.verifySecret(verifyParams);
+
+      expect(response.id).toBe(m2mId);
+      expect(response.secret).toBe(m2mSecret);
+      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.claims).toEqual({ foo: 'bar' });
+    });
+
+    it('requires a machine secret or instance secret to verify a m2m token', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+      });
+
+      const verifyParams = {
+        secret: m2mSecret,
+      };
+
+      server.use(
+        http.post(
+          'https://api.clerk.test/m2m_tokens/verify',
+          validateHeaders(() => {
+            return HttpResponse.json(mockM2MToken);
+          }),
+        ),
+      );
+
+      const errResponse = await apiClient.machineTokens.verifySecret(verifyParams).catch(err => err);
+
+      expect(errResponse.status).toBe(401);
+    });
+  });
+});