@decionis/presence-vercel

@decionis/presence-vercel

Presence adds execution-time human verification to sensitive Next.js routes. It gates configured POST, PUT, and DELETE requests before they reach your application, validates Presence sessions and ES256 proofs locally at the edge, and returns explicit 403 or 503 outcomes when verification is denied or unavailable — the same enforcement contract (docs/41) the Cloudflare and Fastly edge filters ship, with the execution mode as a developer choice.

Install

npm install @decionis/presence-vercel

Set three Vercel environment variables (server-side only — the tenant secret never reaches the browser): PRESENCE_API_SECRET, PRESENCE_TENANT_ID, and optionally PRESENCE_API_HOST (defaults to https://presence.decionis.com).

Gate configured paths with the Edge Middleware

Route selection lives in middleware.ts, with no application code:

// middleware.ts
import { createPresenceMiddleware } from "@decionis/presence-vercel";

export const middleware = createPresenceMiddleware({
  apiHost: "https://presence.decionis.com",
  apiSecret: process.env.PRESENCE_API_SECRET!, // a Vercel env var, server-side only
  tenantId: process.env.PRESENCE_TENANT_ID!,
  protectedRoutes: "/api/checkout/*,/api/transfer",
});

export const config = { matcher: ["/api/:path*"] };

Or wrap a single route handler

Where the choice belongs in code, wrap the handler itself — there is no protectedRoutes, because wrapping is the selection:

// app/api/transfers/route.ts
import { withPresence } from "@decionis/presence-vercel";

export const POST = withPresence(async (req) => {
  return Response.json({ ok: true });
});

withPresence reads PRESENCE_API_HOST (defaulting to the production API), PRESENCE_API_SECRET, and PRESENCE_TENANT_ID from the environment at first request; a config object can also be passed as a second argument. A gated write whose configuration cannot verify anything fails closed (503), never open.

One fail-closed gate

Both modes run the identical gate on write requests (POST/PUT/DELETE):

Condition	Result
Valid x-presence-proof	Verified locally against the JWKS, forwarded (no API)
x-presence-token valid, risk ≤ 0.75	Forwarded to the app / handler
Token missing	403 { code: "PRESENCE_TOKEN_MISSING" }
Token invalid / high-risk	403 { code: "PRESENCE_CHALLENGE_FAILED" }
/v1/verify unavailable	Fail closed 503 PRESENCE_VERIFICATION_UNAVAILABLE
Non-write method or unselected route	Continues to the app

The middleware returns a Response to short-circuit, or undefined to continue — so it drops into a Next.js middleware.ts or any Vercel Edge Function. withPresence returns the denial or the handler's own Response, and passes the route context ({ params }) through untouched. Everything is Web APIs only, so it runs on the Vercel Edge Runtime and the Node runtime alike; the test suite runs in the Edge Runtime (vitest edge-runtime environment). See docs/44 in the repository.

Support

• presence.decionis.com — product, security review, and developer quickstart
• GitHub Issues

License

Apache-2.0. Use of the hosted Presence service is governed separately.