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 },
+ });
+ }
+}