Node.js, Bun, and Deno Support

To distinguish between active Zero Ad Network subscribers and regular visitors, we provide the NPM module @zeroad.network/token. This module is a lightweight, TypeScript-ready, open-source, and fully tested HTTP-header-based "access/entitlement token" library with no production dependencies.

Runtime Compatibility

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

Purpose

The module allows developers to:

• Inject a valid site's HTTP Response Header (Welcome Header) on every endpoint. Example:

  X-Better-Web-Welcome: "AZqnKU56eIC7vCD1PPlwHg^1^3"

• Detect and parse Zero Ad Network user tokens sent via HTTP Request Header by their browser extension. Example:

  X-Better-Web-Hello: "Aav2IXRoh0oKBw==.2yZfC2/pM9DWfgX+von4IgWLmN9t67HJHLiee/gx4+pFIHHurwkC3PCHT1Kaz0yUhx3crUaxST+XLlRtJYacAQ=="

• Verify token integrity locally.

• Optionally generate a valid "Welcome Header" when siteId and features are provided.

Implementation Details

• Uses the node:crypto module to verify token signatures with Zero Ad Network's public ED25519 key.
• Decodes the token payload to extract protocol version, expiration timestamp, and site features.
• Generates a feature map; expired tokens produce all flags as false.

Parsed token example:

{
  ADS_OFF: boolean,
  COOKIE_CONSENT_OFF: boolean,
  MARKETING_DIALOG_OFF: boolean,
  CONTENT_PAYWALL_OFF: boolean,
  SUBSCRIPTION_ACCESS_ON: boolean,
};

• Verification is local; no data leaves your server.
• Parsing and verification add approximately 0.06ms–0.6ms to endpoint execution time (tested on M1 MacBook Pro). Performance may vary.
• Redis caching tests showed local verification is faster than retrieving cached results.

Module Installation

• Written in TypeScript with full types and interfaces.
• Supports both ESM (import) and CommonJS (require). ESM is recommended when possible.

To install the module use your favourite package manager:

npm

npm install --save @zeroad.network/token

Yarn

yarn add @zeroad.network/token

pnpm

pnpm add @zeroad.network/token

Bun

bun add @zeroad.network/token

Deno

deno add npm:@zeroad.network/token

Next steps

Please refer to the integration examples for a few frameworks below to understand how to use the @zeroad.network/token module in your site or web application:

• Express.js - minimalistic design that enables fast, flexible server-side development with JavaScript.
• Fastify - high-performance architecture that delivers rapid request handling with minimal overhead.
• Hono - ultra-lightweight, edge-friendly design that provides exceptional speed and a clean, modern routing API.