Node.js, Bun, and Deno

The @zeroad.network/token package handles both sides of the integration: generating your site’s partner header and verifying incoming subscriber tokens on each request.

By the end of this guide your site will: - Send the X-Better-Web-Welcome header on every response (declaring partnership) - Verify each visitor’s subscription token in under 1 ms - Expose a tokenContext object to your route handlers and templates

Prerequisites

A registered site on zeroad.network - you’ll need the clientId from your site’s settings
Node.js 16+, Bun 1.1.0+, or Deno 2.0.0+

Install

npm
Yarn
pnpm
Bun
Deno

npm install @zeroad.network/token

yarn add @zeroad.network/token

pnpm add @zeroad.network/token

bun add @zeroad.network/token

deno add npm:@zeroad.network/token

Initialize once at startup

Create the site instance once when your application starts. It computes your X-Better-Web-Welcome header value at initialization time - not on every request.

import { Site, FEATURE } from "@zeroad.network/token"

// Replace with the clientId from your site's dashboard
const site = Site({
  clientId: "Z2CclA8oXIT1e0QmqTWF8w",
  features: [FEATURE.CLEAN_WEB, FEATURE.ONE_PASS],
})

FEATURE.CLEAN_WEB and FEATURE.ONE_PASS declare what your site offers. Only include the features you actually support - a site without a paywall shouldn’t declare ONE_PASS.

Use in middleware

In your framework’s middleware, do two things on every request:

// 1. Inject your site's partner header into the response
res.setHeader(site.SERVER_HEADER_NAME, site.SERVER_HEADER_VALUE)

// 2. Parse the subscriber token from the incoming request (returns feature flags)
const tokenContext = site.parseClientToken(req.headers[site.CLIENT_HEADER_NAME])

parseClientToken verifies the token signature locally against Zero Ad Network’s public ED25519 key - no network call, no latency. If no token is present, or the token is invalid or expired, all flags are false. Your site behaves normally for non-subscribers without any extra handling.

The tokenContext object

parseClientToken returns a flat object of booleans:

{
  HIDE_ADVERTISEMENTS: boolean,
  HIDE_COOKIE_CONSENT_SCREEN: boolean,
  HIDE_MARKETING_DIALOGS: boolean,
  DISABLE_NON_FUNCTIONAL_TRACKING: boolean,
  DISABLE_CONTENT_PAYWALL: boolean,
  ENABLE_SUBSCRIPTION_ACCESS: boolean,
}

Each flag is true only when the subscriber’s plan and your site’s declared features overlap. Use them directly in your route handlers and templates:

Flag	When `true`	What to do in your code
`HIDE_ADVERTISEMENTS`	Subscriber has Clean Web, site declares Clean Web	Skip rendering ad slots and ad SDK tags
`HIDE_COOKIE_CONSENT_SCREEN`	Same	Skip cookie consent banner
`HIDE_MARKETING_DIALOGS`	Same	Skip newsletter/promo popups
`DISABLE_NON_FUNCTIONAL_TRACKING`	Same	Skip loading third-party analytics trackers
`DISABLE_CONTENT_PAYWALL`	Subscriber has One Pass, site declares One Pass	Serve full content instead of teaser
`ENABLE_SUBSCRIPTION_ACCESS`	Same	Treat visitor as having a subscription to your service

Runtime compatibility

Runtime	Version	ESM	CJS
Node.js	16+	✅	✅
Bun	1.1.0+	✅	✅
Deno	2.0.0+	✅	✅

Framework guides

Pick your framework for a complete working example: