@zeroad.network/token 0.13.5 → 0.13.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +59 -53
  2. package/dist/browser.d.cts +10 -7
  3. package/dist/browser.d.mts +10 -7
  4. package/package.json +28 -4
package/README.md CHANGED
@@ -1,41 +1,45 @@
1
1
  # Introduction
2
2
 
3
- This NPM module is meant to be used by sites participating in [Zero Ad Network](https://zeroad.network) program, that are running in either Node.js, Bun or Deno runtimes. The `@zeroad.network/token` module is a lightweight, TypeScript ready, fully open source, well tested and has no production dependencies.
3
+ This NPM module is designed for sites running Node.js, Bun, or Deno that participate in the [Zero Ad Network](https://zeroad.network) program.
4
4
 
5
- You will find the official Zero Ad Network documentation at [docs.zeroad.network](https://docs.zeroad.network). Up-to-date and in depth guides, how-to's and platform implementation details can be found there.
5
+ 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.
6
6
 
7
- ## Runtime compatibility
7
+ For detailed guides and implementation instructions, see the [official Zero Ad Network documentation](https://docs.zeroad.network).
8
8
 
9
- | Runtime | Compatibility | ESM | CJS |
10
- | :------ | :------------ | :-: | :-: |
11
- | Node.js | 16+ | ✅ | ✅ |
12
- | Bun | 1.1.0+ | ✅ | ✅ |
13
- | Deno | 2.0.0+ | ✅ | ✅ |
9
+ ## Runtime Compatibility
10
+
11
+ | Runtime | Version | ESM | CJS |
12
+ | :------ | :------ | :-: | :-: |
13
+ | Node.js | 16+ | ✅ | ✅ |
14
+ | Bun | 1.1.0+ | ✅ | ✅ |
15
+ | Deno | 2.0.0+ | ✅ | ✅ |
14
16
 
15
17
  ## Purpose
16
18
 
17
- It helps partnered site developer to:
19
+ The module helps developers to:
20
+
21
+ - Inject a valid site's HTTP Response Header (**Welcome Header**) into every endpoint. Example:
18
22
 
19
- - Inject a valid site's HTTP Response Header known as "Welcome Header" to every endpoint. An example:
20
23
  ```http
21
24
  X-Better-Web-Welcome: "AZqnKU56eIC7vCD1PPlwHg^1^3"
22
25
  ```
23
- - Check for Zero Ad Network user's token presence that gets injected as a HTTP Request Header by their browser extension. An example of such Request Header:
26
+
27
+ - Detect and parse Zero Ad Network user tokens sent via HTTP Request Header. Example:
28
+
24
29
  ```http
25
30
  X-Better-Web-Hello: "Aav2IXRoh0oKBw==.2yZfC2/pM9DWfgX+von4IgWLmN9t67HJHLiee/gx4+pFIHHurwkC3PCHT1Kaz0yUhx3crUaxST+XLlRtJYacAQ=="
26
31
  ```
27
- - If found, parse the token from the HTTP Request Header value and verify its integrity.
28
- - (Optionally) Generate a valid "Welcome Header" value when `siteId` UUID and site `features` array are provided.
29
32
 
30
- ## Implementation details
33
+ - Verify token integrity locally.
34
+ - Optionally generate a valid "Welcome Header" when `siteId` and `features` are provided.
31
35
 
32
- The module uses the `node:crypto` runtime module to ensure the user's Request Header payload is valid by verifying its signature for the payload using Zero Ad Network's public ED25519 cryptographic key which is supplied within the module. Then:
36
+ ## Implementation Details
33
37
 
34
- - User's token payload is decoded and token's protocol version, expiration timestamp and site's feature list are extracted.
35
- - A map of the site's features and their toggle states is generated.
36
- - An expired token will produce a feature list with all flags being set to `false`.
38
+ - Uses `node:crypto` to verify token signatures with Zero Ad Network's public ED25519 key.
39
+ - Decodes token payload to extract protocol version, expiration timestamp, and site features.
40
+ - Generates a feature map; expired tokens produce all flags as `false`.
37
41
 
38
- Parsed token result example:
42
+ Parsed token example:
39
43
 
40
44
  ```js
41
45
  {
@@ -47,27 +51,29 @@ Parsed token result example:
47
51
  };
48
52
  ```
49
53
 
50
- User's token payload verification is done locally within your app and no data leaves your server.
51
-
52
- When a token is present, parsing and token integrity verification will roughly add between `0.06ms` to `0.6ms` to the total endpoint execution time (as per testing done on a M1 MacBook Pro). Your mileage will vary depending on your hardware, but the impact should stay minimal.
53
-
54
- As per our exploratory test results in attempts to cache the token and its parsed results in Redis - it takes longer to retrieve the cached result than to verify token payload integrity.
54
+ - Verification occurs locally; no data leaves your server.
55
+ - Parsing and verification adds roughly 0.06ms–0.6ms to endpoint execution time (tested on M1 MacBook Pro). Performance may vary.
56
+ - Redis caching tests show local verification is faster than retrieving cached results.
55
57
 
56
- ## Why to join
58
+ ## Benefits of Joining
57
59
 
58
- By partnering with Zero Ad Network your site establishes a new stream of revenue enabling you to provide a tangible and meaningful value while simultaneously providing a pure, clean and unobstructed site UI that everyone loves.
60
+ Partnering with Zero Ad Network allows your site to:
59
61
 
60
- With every new site joining us, it becomes easier to reshape the internet closer to its original intention - a joyful and wonderful experience for everyone.
62
+ - Generate a new revenue stream
63
+ - Provide a clean, unobstructed user experience
64
+ - Contribute to a more joyful, user-friendly internet
61
65
 
62
- ## Onboard your site
66
+ ## Onboarding Your Site
63
67
 
64
- To register your site, [sign up](https://zeroad.network/login) with Zero Ad Network and [register your site](https://zeroad.network/publisher/sites/add). On the second step of the Site registration process you'll be provided with your unique `X-Better-Web-Welcome` header value.
68
+ 1. [Sign up](https://zeroad.network/login) with Zero Ad Network.
69
+ 2. [Register your site](https://zeroad.network/publisher/sites/add) to receive your unique `X-Better-Web-Welcome` header.
65
70
 
66
- If you decide for your site to participate in the Zero Ad Network program, then it must respond with this header at all times on every publicly accessible endpoint containing HTML or RESTful response. When Zero Ad Network users visit your site, this allows their browser extension to know your site is participating in the program.
71
+ 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.
67
72
 
68
- ## Module installation
73
+ ## Module Installation
69
74
 
70
- Great news for TypeScript enjoyers, the module is written purely in TypeScript, hence all types and interfaces are readily available. The module works well in EcmaScript (`import {} from ""`) and CommonJS `const {} = require("")` environments. If unsure - prefer ESM when possible.
75
+ - Written entirely in TypeScript with full types and interfaces.
76
+ - Supports both ESM (`import`) and CommonJS (`require`). ESM is recommended when possible.
71
77
 
72
78
  To install the module use your favourite package manager:
73
79
 
@@ -90,15 +96,15 @@ deno add npm:@zeroad.network/token
90
96
 
91
97
  ## Examples
92
98
 
93
- To find more example implementations for `Express.js` (JavaScript), `Hono` and `Fastify` (both TypeScript), please go to [examples section on our Github repository](https://github.com/laurynas-karvelis/zeroad-token-ts/tree/main/examples/).
99
+ For more example implementations using `Express.js` (JavaScript), `Hono`, and `Fastify` (TypeScript), visit the [examples section on our GitHub repository](https://github.com/laurynas-karvelis/zeroad-token-typescript/tree/main/examples/).
94
100
 
95
- Take this JavaScript example as a quick reference. The example will show how to:
101
+ The following JavaScript example provides a quick reference, demonstrating how to:
96
102
 
97
- - Inject the "Welcome Header" into each response;
98
- - Parse user's token from their request header;
99
- - Use the `tokenContext` value later in your controllers and templates.
103
+ - Inject the "Welcome Header" into responses
104
+ - Parse the user's token from the request header
105
+ - Use the `tokenContext` in controllers and templates
100
106
 
101
- An Express.js v.5 example of a minimal app:
107
+ Minimal Express.js v5 app example:
102
108
 
103
109
  ```js
104
110
  import express from "express";
@@ -106,42 +112,42 @@ import { Site } from "@zeroad.network/token";
106
112
 
107
113
  const app = express();
108
114
 
109
- // Initialize your Zero Ad Network module once at startup.
110
- // "Welcome Header" value is acquired during Site's registration process at Zero Ad Network platform (see https://zeroad.network).
115
+ // Initialize the Zero Ad Network module at app startup.
116
+ // The "Welcome Header" value is obtained during site registration on the Zero Ad Network platform (https://zeroad.network).
111
117
  const ZERO_AD_NETWORK_WELCOME_HEADER_VALUE = "AZqnKU56eIC7vCD1PPlwHg^1^3";
112
118
  const site = Site(ZERO_AD_NETWORK_WELCOME_HEADER_VALUE);
113
119
 
114
120
  app
115
- // Your middleware
121
+ // Apply middleware for all routes
116
122
  .use((req, res, next) => {
117
- // Inject "X-Better-Web-Welcome" header
123
+ // Inject the "X-Better-Web-Welcome" header into the response
118
124
  res.set(site.SERVER_HEADER_NAME, site.SERVER_HEADER_VALUE);
119
125
 
120
- // Parse the request token from incoming client token header value.
121
- // And attach parsed info to request object for downstream usage.
122
- req.tokenContext = site.parseToken(req.get[site.CLIENT_HEADER_NAME]);
126
+ // Parse the incoming user token from the request header
127
+ // Attach the parsed token data to the request object for downstream use
128
+ req.tokenContext = site.parseToken(req.get(site.CLIENT_HEADER_NAME));
123
129
 
124
130
  next();
125
131
  })
126
132
  .get("/", (req, res) => {
127
- // If you would print it's contents:
133
+ // Access parsed token data for this request
128
134
  console.log(req.tokenContext);
129
135
 
130
- // This will produce:
136
+ // Example structure of tokenContext:
131
137
  req.tokenContext = {
132
- // If set to true: Render no advertisements anywhere on the page
138
+ // If true: Hide advertisements on the page
133
139
  ADS_OFF: boolean,
134
- // If set to true: Render no Cookie Consent screens (headers, footers or dialogs) on the page with complete OPT-OUT for non-functional trackers
140
+ // If true: Hide Cookie Consent screens and opt out non-functional trackers
135
141
  COOKIE_CONSENT_OFF: boolean,
136
- // If set to true: Render no marketing dialogs or popups such as newsletter, promotion etc. on the page
142
+ // If true: Hide marketing dialogs or popups (e.g., newsletter, promotions)
137
143
  MARKETING_DIALOG_OFF: boolean,
138
- // If set to true: Provide automatic access to otherwise paywalled content such as articles, news etc.
144
+ // If true: Provide automatic access to paywalled content
139
145
  CONTENT_PAYWALL_OFF: boolean,
140
- // If set to true: Provide automatic access to site features provided behind a SaaS at least the basic subscription plan
146
+ // If true: Provide access to site features behind SaaS subscription (at least basic plan)
141
147
  SUBSCRIPTION_ACCESS_ON: boolean,
142
148
  };
143
149
 
144
- // In your template adjust your content depending on tokenContext values
150
+ // Adjust content in your templates based on tokenContext values
145
151
  res.render("index.ejs", { tokenContext });
146
152
  });
147
153
 
package/dist/browser.d.cts CHANGED
@@ -1,18 +1,21 @@
1
1
  /**
2
- * This is an official ZeroAd Network public key.
3
- * Used to verify `X-Better-Web-User` header values are not tampered with.
2
+ * Official Zero Ad Network public key.
3
+ * Used to verify that `X-Better-Web-Hello` header values are authentic
4
+ * and have not been tampered with.
4
5
  */
5
6
  declare const ZEROAD_NETWORK_PUBLIC_KEY: string;
6
7
  declare enum FEATURES {
7
- /** Render no advertisements anywhere on the page */
8
+ /** Disable all advertisements on the page */
8
9
  ADS_OFF = 1,
9
- /** Render no Cookie Consent screens (headers, footers or dialogs) on the page with complete OPT-OUT for non-functional trackers */
10
+ /** Disable all Cookie Consent screens (headers, footers, or dialogs)
11
+ and fully opt out of non-functional trackers */
10
12
  COOKIE_CONSENT_OFF = 2,
11
- /** Render no marketing dialogs or popups such as newsletter, promotion etc. on the page */
13
+ /** Disable all marketing dialogs or popups (e.g., newsletters, promotions) */
12
14
  MARKETING_DIALOG_OFF = 4,
13
- /** Provide automatic access to otherwise paywalled content such as articles, news etc. */
15
+ /** Provide automatic access to content that is normally paywalled */
14
16
  CONTENT_PAYWALL_OFF = 8,
15
- /** Provide automatic access to site features provided behind a SaaS at least the basic subscription plan */
17
+ /** Grant automatic access to site features behind a SaaS,
18
+ at least the basic subscription plan */
16
19
  SUBSCRIPTION_ACCESS_ON = 16
17
20
  }
18
21
  type UUID = string;
package/dist/browser.d.mts CHANGED
@@ -1,18 +1,21 @@
1
1
  /**
2
- * This is an official ZeroAd Network public key.
3
- * Used to verify `X-Better-Web-User` header values are not tampered with.
2
+ * Official Zero Ad Network public key.
3
+ * Used to verify that `X-Better-Web-Hello` header values are authentic
4
+ * and have not been tampered with.
4
5
  */
5
6
  declare const ZEROAD_NETWORK_PUBLIC_KEY: string;
6
7
  declare enum FEATURES {
7
- /** Render no advertisements anywhere on the page */
8
+ /** Disable all advertisements on the page */
8
9
  ADS_OFF = 1,
9
- /** Render no Cookie Consent screens (headers, footers or dialogs) on the page with complete OPT-OUT for non-functional trackers */
10
+ /** Disable all Cookie Consent screens (headers, footers, or dialogs)
11
+ and fully opt out of non-functional trackers */
10
12
  COOKIE_CONSENT_OFF = 2,
11
- /** Render no marketing dialogs or popups such as newsletter, promotion etc. on the page */
13
+ /** Disable all marketing dialogs or popups (e.g., newsletters, promotions) */
12
14
  MARKETING_DIALOG_OFF = 4,
13
- /** Provide automatic access to otherwise paywalled content such as articles, news etc. */
15
+ /** Provide automatic access to content that is normally paywalled */
14
16
  CONTENT_PAYWALL_OFF = 8,
15
- /** Provide automatic access to site features provided behind a SaaS at least the basic subscription plan */
17
+ /** Grant automatic access to site features behind a SaaS,
18
+ at least the basic subscription plan */
16
19
  SUBSCRIPTION_ACCESS_ON = 16
17
20
  }
18
21
  type UUID = string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeroad.network/token",
3
- "version": "0.13.5",
3
+ "version": "0.13.7",
4
4
  "license": "Apache-2.0",
5
5
  "repository": "github:laurynas-karvelis/zeroad-token-typescript",
6
6
  "homepage": "https://zeroad.network",
@@ -14,10 +14,34 @@
14
14
  "./dist/**/*"
15
15
  ],
16
16
  "keywords": [
17
- "better web",
18
17
  "zero ad network",
19
- "zero ad",
20
- "zeroad"
18
+ "zeroad",
19
+ "zero-ad",
20
+ "token",
21
+ "access-token",
22
+ "http-header",
23
+ "welcome-header",
24
+ "auth",
25
+ "authorization",
26
+ "subscription",
27
+ "feature-flags",
28
+ "entitlement",
29
+ "ad-free",
30
+ "ads-free",
31
+ "paywall",
32
+ "content-access",
33
+ "middleware",
34
+ "typescript",
35
+ "javascript",
36
+ "nodejs",
37
+ "deno",
38
+ "bun",
39
+ "esm",
40
+ "cjs",
41
+ "web-server",
42
+ "express",
43
+ "fastify",
44
+ "hono"
21
45
  ],
22
46
  "engines": {
23
47
  "node": ">= 18.0.0",