Vercel middleware (clearance)

WebDecoy’s clearance validator, the same one that runs as a Cloudflare Worker, an AWS Lambda@Edge function or in the Netlify extension, can run as middleware in your Vercel project. It needs no proxy or CDN in front of the site, and it works with any framework Vercel deploys.

On the paths you protect, a visitor needs a WebDecoy clearance token. A real browser earns one automatically on a short check page and is sent straight back. A client that runs no JavaScript, such as a scraper fetching pages with a browser user agent, never gets one and never gets the page.

It changes nothing until you say so. The site follows its WebDecoy mode. In Monitor, the default, the middleware labels each request with what it would have done and blocks nothing. Requests are refused only once you switch the site to Enforce and protect some paths.

Install

1. In WebDecoy, open Enforcement → Setup, go to the edge validator step and choose Vercel. It shows your site key, the site’s scanner id and the command that stores the sensor key.

2. In the Vercel project, under Project Settings → Environment Variables, add:

   Variable	What it is
   WEBDECOY_SITE_KEY	The organization the site belongs to
   WEBDECOY_SCANNER_ID	This site’s scanner id
   WEBDECOY_SENSOR_KEY	A secret that proves the validator is one WebDecoy issued. Add it with the command Setup shows, never in a file you commit

3. Add the middleware.

   Next.js: install @webdecoy/nextjs and create middleware.ts:

   import { withClearance } from '@webdecoy/nextjs';
   
   export default withClearance();
   
   export const config = {
     matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
   };

   Astro, SvelteKit, Nuxt, Remix or a static site: install @webdecoy/node and create middleware.ts at the project root:

   export { default } from '@webdecoy/node/vercel';
   
   export const config = {
     matcher: ['/((?!_astro/|_next/static/|favicon.ico|.*\\.(?:css|js|png|jpg|svg|webp|woff2?)$).*)'],
   };

   Keep /.well-known/ in the matcher. The check page uses it to issue the token.

4. Deploy, then on Enforcement → Setup enter your domain and press Verify deployment. The middleware answers the check itself and reports the site’s mode.

How it decides

For each request, in order:

1. A valid service credential, a verified search crawler, or a bot that signs its requests (Web Bot Auth) passes.
2. A path you have not protected passes.
3. On a protected path, a valid clearance token passes. A missing, invalid or revoked one (revoked when that browser later tripped a decoy) is labeled missing, invalid or revoked. In Monitor the request is still served. In Enforce a browser gets the check page, and any other client gets a 403 with a JSON body.

The page receives the verdict as the x-wd-clearance request header, so your own code can read it. In Next.js, getEdgeVerdict() reads it in a route handler or server component. A client cannot set that header itself: the middleware removes any copy it sends.

Particular to Vercel

• Verified crawlers. Vercel gives middleware no verified-bot signal, so the validator verifies search engines itself by forward-confirmed reverse DNS (Google, Bing, Yahoo, Apple, Yandex, Baidu), asked over DNS-over-HTTPS, and accepts any bot that signs its requests. Other crawlers you allow under access exceptions are let through only if they sign. A lookup happens only for a request that claims to be a crawler on a protected path, never for a browser.
• Fails open. If WebDecoy cannot be reached, a token cannot be checked, or the middleware is missing a variable, the request is served. A missing variable is logged once.
• Works with the log drain. The Vercel integration reports what reached your site. The middleware is what refuses the requests you choose to refuse. You can run both.

Remove

Delete middleware.ts (or the withClearance() call) and deploy.