feat(nextjs): Introduce machine authentication

[wobsoriano]

Description

This is a companion PR to #5689, that updates the Next.js SDK clerkMiddleware(), auth(), and auth.protect() helpers to accommodate machine auth tokens.

Key changes:

• Updated auth() to accept a acceptTokens param. Useful for leaf node route protection.
• Updated auth.protect() to accept a tokens param. Useful in protecting routes inside a middleware.
• Updated clerkMiddleware() to pass any as the default acceptsToken type to authenticateRequest. This however opens up an opportunity for an economic attacks and will be tackled in a separate PR.
• Added proper type inference for auth objects based on token types.
• Added tests for middleware and auth() verification with machine tokens.

Resolves ROBO-114 and ROBO-134

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1fc468b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	⬜️ Skipped (Inspect)			May 6, 2025 2:43am

[jescalan]

Looks good so far

[wobsoriano]

!snapshot

[clerk-cookie]

Hey @wobsoriano - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.0.29-snapshot.v20250501230217
@clerk/astro	2.6.11-snapshot.v20250501230217
@clerk/backend	1.31.0-snapshot.v20250501230217
@clerk/chrome-extension	2.3.5-snapshot.v20250501230217
@clerk/clerk-js	5.63.3-snapshot.v20250501230217
@clerk/clerk-expo	2.10.5-snapshot.v20250501230217
@clerk/express	1.4.12-snapshot.v20250501230217
@clerk/fastify	2.2.12-snapshot.v20250501230217
@clerk/nextjs	6.18.3-snapshot.v20250501230217
@clerk/nuxt	1.5.12-snapshot.v20250501230217
@clerk/react-router	1.3.3-snapshot.v20250501230217
@clerk/remix	4.6.3-snapshot.v20250501230217
@clerk/tanstack-react-start	0.14.3-snapshot.v20250501230217
@clerk/testing	1.6.2-snapshot.v20250501230217

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

[wobsoriano]

Since getAuth() does not have machine auth feature yet (will be breaking because it's async), we need to type it as session auth

[brkalow]

🤔 it might be a good idea to assert on the explicit value here, instead of just the truthy check

[wobsoriano]

Updated!