Node, Bun, and Deno Support

This NPM module is designed for sites running Node, Bun, or Deno that participate in the Zero Ad Network program.

The @zeroad.network/token module is a lightweight, TypeScript-ready, open-source, and fully tested HTTP-header-based "access/entitlement token" library with no production dependencies.

For detailed guides and implementation instructions, see the official Zero Ad Network documentation.

Runtime Compatibility

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

Purpose

The module helps developers to:

• Generate a valid "Welcome Header" when clientId and features are provided.

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

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

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

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

• Verify client token integrity locally.

Implementation Details

• Uses node:crypto to verify token signatures with Zero Ad Network's public ED25519 key.
• Decodes 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:

{
  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,
};

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

Benefits of Joining

Partnering with Zero Ad Network allows your site to:

• Generate a new revenue stream by:
  • Providing a clean, unobstructed user experience
  • Removing paywalls and enabling free access to your base subscription plan
  • Or both combined
• Contribute to a truly joyful, user-friendly internet experience

Onboarding Your Site

1. Sign up with Zero Ad Network.
2. Register your site to receive your unique X-Better-Web-Welcome header.

Your site must include this header on all publicly accessible HTML or RESTful endpoints so that Zero Ad Network users' browser extensions can recognize participation.

Module Installation

• Written entirely 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.