feat(backend,nextjs): Introduce machine authentication (#5689)

Author: wobsoriano

.changeset/bumpy-carpets-study.md

@@ -0,0 +1,40 @@
+---
+'@clerk/backend': major
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed by using the `acceptsToken` option in the `authenticateRequest()` function. This option can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage:
+
+```ts
+import express from 'express';
+import { clerkClient } from '@clerk/backend';
+
+const app = express();
+
+app.use(async (req, res, next) => {
+  const requestState = await clerkClient.authenticateRequest(req, {
+    acceptsToken: 'any'
+  });
+
+  if (!requestState.isAuthenticated) {
+    // do something for unauthenticated requests
+  }
+
+  const authObject = requestState.toAuth();
+
+  if (authObject.tokenType === 'session_token') {
+    console.log('this is session token from a user')
+  } else {
+    console.log('this is some other type of machine token')
+    console.log('more specifically, a ' + authObject.tokenType)
+  }
+
+  // Attach the auth object to locals so downstream handlers
+  // and middleware can access it
+  res.locals.auth = authObject;
+  next();
+});
+```

.changeset/chatty-lions-stay.md

@@ -0,0 +1,30 @@
+---
+'@clerk/tanstack-react-start': minor
+'@clerk/agent-toolkit': minor
+'@clerk/react-router': minor
+'@clerk/express': minor
+'@clerk/fastify': minor
+'@clerk/astro': minor
+'@clerk/remix': minor
+'@clerk/nuxt': minor
+---
+
+Machine authentication is now supported for advanced use cases via the backend SDK. You can use `clerkClient.authenticateRequest` to validate machine tokens (such as API keys, OAuth tokens, and machine-to-machine tokens). No new helpers are included in these packages yet.
+
+Example (Astro):
+
+```ts
+import { clerkClient } from '@clerk/astro/server';
+
+export const GET: APIRoute = ({ request }) => {
+    const requestState = await clerkClient.authenticateRequest(request, {
+        acceptsToken: 'api_key'
+    });
+
+    if (!requestState.isAuthenticated) {
+        return new Response(401, { message: 'Unauthorized' })
+    }
+
+    return new Response(JSON.stringify(requestState.toAuth()))
+}
+```

.changeset/fast-turkeys-melt.md

@@ -0,0 +1,57 @@
+---
+'@clerk/nextjs': minor
+---
+
+Introduces machine authentication, supporting four token types: `api_key`, `oauth_token`, `machine_token`, and `session_token`. For backwards compatibility, `session_token` remains the default when no token type is specified. This enables machine-to-machine authentication and use cases such as API keys and OAuth integrations. Existing applications continue to work without modification.
+
+You can specify which token types are allowed for a given route or handler using the `acceptsToken` property in the `auth()` helper, or the `token` property in the `auth.protect()` helper. Each can be set to a specific type, an array of types, or `'any'` to accept all supported tokens.
+
+Example usage in Nextjs middleware:
+
+```ts
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isOAuthAccessible = createRouteMatcher(['/oauth(.*)'])
+const isApiKeyAccessible = createRouteMatcher(['/api(.*)'])
+const isMachineTokenAccessible = createRouteMatcher(['/m2m(.*)'])
+const isUserAccessible = createRouteMatcher(['/user(.*)'])
+const isAccessibleToAnyValidToken = createRouteMatcher(['/any(.*)'])
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isOAuthAccessible(req)) await auth.protect({ token: 'oauth_token' })
+  if (isApiKeyAccessible(req)) await auth.protect({ token: 'api_key' })
+  if (isMachineTokenAccessible(req)) await auth.protect({ token: 'machine_token' })
+  if (isUserAccessible(req)) await auth.protect({ token: 'session_token' })
+
+  if (isAccessibleToAnyValidToken(req)) await auth.protect({ token: 'any' })
+});
+
+export const config = {
+  matcher: [
+    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+    '/(api|trpc)(.*)',
+  ],
+}
+```
+
+Leaf node route protection:
+
+```ts
+import { auth } from '@clerk/nextjs/server'
+
+// In this example, we allow users and oauth tokens with the "profile" scope
+// to access the data. Other types of tokens are rejected.
+function POST(req, res) {
+  const authObject = await auth({ acceptsToken: ['session_token', 'oauth_token'] })
+  
+  if (authObject.tokenType === 'oauth_token' &&
+      !authObject.scopes?.includes('profile')) {
+      throw new Error('Unauthorized: OAuth token missing the "profile" scope')
+  }
+  
+  // get data from db using userId
+  const data = db.select().from(user).where(eq(user.id, authObject.userId))
+  
+  return { data }
+}
+```

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -118,6 +118,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "shared/version-selector.mdx",
   "nextjs/auth.mdx",
   "nextjs/build-clerk-props.mdx",
+  "nextjs/clerk-middleware-auth-object.mdx",
   "nextjs/clerk-middleware-options.mdx",
   "nextjs/clerk-middleware.mdx",
   "nextjs/create-async-get-auth.mdx",
@@ -139,6 +140,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "clerk-react/use-sign-in.mdx",
   "clerk-react/use-sign-up.mdx",
   "clerk-react/use-user.mdx",
+  "backend/verify-machine-auth-token.mdx",
   "backend/verify-token-options.mdx",
   "backend/verify-token.mdx",
   "backend/verify-webhook-options.mdx",

packages/agent-toolkit/src/lib/types.ts

@@ -1,4 +1,5 @@
-import type { AuthObject, ClerkClient } from '@clerk/backend';
+import type { ClerkClient } from '@clerk/backend';
+import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
 
 import type { ClerkTool } from './clerk-tool';
 
@@ -12,7 +13,7 @@ export type ToolkitParams = {
    * @default {}
    */
   authContext?: Pick<
-    AuthObject,
+    SignedInAuthObject | SignedOutAuthObject,
     'userId' | 'sessionId' | 'sessionClaims' | 'orgId' | 'orgRole' | 'orgSlug' | 'orgPermissions' | 'actor'
   >;
   /**

packages/astro/src/server/clerk-middleware.ts

@@ -1,5 +1,12 @@
-import type { AuthObject, ClerkClient } from '@clerk/backend';
-import type { AuthenticateRequestOptions, ClerkRequest, RedirectFun, RequestState } from '@clerk/backend/internal';
+import type { ClerkClient } from '@clerk/backend';
+import type {
+  AuthenticateRequestOptions,
+  ClerkRequest,
+  RedirectFun,
+  RequestState,
+  SignedInAuthObject,
+  SignedOutAuthObject,
+} from '@clerk/backend/internal';
 import { AuthStatus, constants, createClerkRequest, createRedirect } from '@clerk/backend/internal';
 import { isDevelopmentFromSecretKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
@@ -28,7 +35,7 @@ const CONTROL_FLOW_ERROR = {
   REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
 };
 
-type ClerkMiddlewareAuthObject = AuthObject & {
+type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
   redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
 };
 

packages/astro/src/server/get-auth.ts

@@ -1,4 +1,4 @@
-import type { AuthObject } from '@clerk/backend';
+import type { SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
 import { AuthStatus, signedInAuthObject, signedOutAuthObject } from '@clerk/backend/internal';
 import { decodeJwt } from '@clerk/backend/jwt';
 import type { PendingSessionOptions } from '@clerk/types';
@@ -7,7 +7,7 @@ import type { APIContext } from 'astro';
 import { getSafeEnv } from './get-safe-env';
 import { getAuthKeyFromRequest } from './utils';
 
-export type GetAuthReturn = AuthObject;
+export type GetAuthReturn = SignedInAuthObject | SignedOutAuthObject;
 
 export const createGetAuth = ({ noAuthStatusMessage }: { noAuthStatusMessage: string }) => {
   return (

packages/backend/src/__tests__/exports.test.ts

@@ -22,6 +22,8 @@ describe('subpath /errors exports', () => {
   it('should not include a breaking change', () => {
     expect(Object.keys(errorExports).sort()).toMatchInlineSnapshot(`
       [
+        "MachineTokenVerificationError",
+        "MachineTokenVerificationErrorCode",
         "SignJWTError",
         "TokenVerificationError",
         "TokenVerificationErrorAction",
@@ -37,18 +39,25 @@ describe('subpath /internal exports', () => {
     expect(Object.keys(internalExports).sort()).toMatchInlineSnapshot(`
       [
         "AuthStatus",
+        "TokenType",
+        "authenticatedMachineObject",
         "constants",
         "createAuthenticateRequest",
         "createClerkRequest",
         "createRedirect",
         "debugRequestState",
         "decorateObjectWithResources",
+        "getMachineTokenType",
+        "isMachineToken",
+        "isTokenTypeAccepted",
         "makeAuthObjectSerializable",
         "reverificationError",
         "reverificationErrorResponse",
         "signedInAuthObject",
         "signedOutAuthObject",
         "stripPrivateDataFromObject",
+        "unauthenticatedMachineObject",
+        "verifyMachineAuthToken",
       ]
     `);
   });

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

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { APIKey } from '../resources/APIKey';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/api_keys';
+
+export class APIKeysAPI extends AbstractAPI {
+  async verifySecret(secret: string) {
+    return this.request<APIKey>({
+      method: 'POST',
+      path: joinPaths(basePath, 'verify'),
+      bodyParams: { secret },
+    });
+  }
+}

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

@@ -0,0 +1,15 @@
+import { joinPaths } from '../../util/path';
+import type { IdPOAuthAccessToken } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/oauth_applications/access_tokens';
+
+export class IdPOAuthAccessTokenApi extends AbstractAPI {
+  async verifySecret(secret: string) {
+    return this.request<IdPOAuthAccessToken>({
+      method: 'POST',
+      path: joinPaths(basePath, 'verify'),
+      bodyParams: { secret },
+    });
+  }
+}