@zeroad.network/token 0.13.2 → 0.13.3

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 (2) hide show
  1. package/README.md +81 -38
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,28 +1,75 @@
1
- ## Introduction
1
+ # Introduction
2
2
 
3
- **@zeroad.network/token** is a TypeScript ready module meant to be used by partnering sites of [Zero Ad Network](https://zeroad.network) platform. It's a lightweight module that works on Nodejs v18 and above, Bun v1.1.0 and above, and Deno v2.0.0 and above runtimes.
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 a lightweight, TypeScript ready, fully open source, is well tested and has no production dependencies.
4
4
 
5
- This module allows a Zero Ad Network program partnering sites and Web APIs to verify determine if incoming web requests are coming from our browser extension users with active subscription.
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.
6
6
 
7
- Their browser extension will send the `X-Better-Web-Hello` Request Header which will let our module to verify it's our actively subscribed user and will allow your site to make a decision whether to disable ads, paywalls or enable access to otherwise paid content of yours.
7
+ ## Runtime compatibility
8
8
 
9
- ZeroAd user browser extension will measure how many times and how long they spent on each resource of your website that sends the `X-Better-Web-Welcome` token. This information will go back to us and at the end of each month based on how large the active user base is and how much competition you got, you'll get awarded from each user's monthly subscription paid amount based on their usage patterns interacting with your site.
9
+ | Runtime | Compatibility | ESM | CJS |
10
+ | :------ | :------------ | :-: | :-: |
11
+ | Node.js | 18+ | ✅ | ✅ |
12
+ | Bun | 1.1.0+ | ✅ | ✅ |
13
+ | Deno | 2.0.0+ | ✅ | ✅ |
10
14
 
11
- ## Setup
15
+ ## Purpose
12
16
 
13
- If you already have your site registered with us, you can skip the section below.
17
+ It helps partnered site developer to:
14
18
 
15
- ### Register your website or web API
19
+ - Inject a valid site's HTTP Response Header known as "Welcome Header" to every endpoint. An example:
20
+ ```http
21
+ X-Better-Web-Welcome: "AZqnKU56eIC7vCD1PPlwHg^1^3"
22
+ ```
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:
24
+ ```http
25
+ X-Better-Web-Hello: "Aav2IXRoh0oKBw==.2yZfC2/pM9DWfgX+von4IgWLmN9t67HJHLiee/gx4+pFIHHurwkC3PCHT1Kaz0yUhx3crUaxST+XLlRtJYacAQ=="
26
+ ```
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.
16
29
 
17
- Sign up with us by navigating in your browser to [sign up](https://zeroad.network/login), once you've logged in successfully, go to and [add a project](https://zeroad.network/publisher/sites/add) page and register your site.
30
+ ## Implementation details
18
31
 
19
- In the second step of the Site registration process you'll be presented with your unique `X-Better-Web-Welcome` header value for that site. Your website must respond with this header in all publicly accessible endpoints that contain HTML or RESTful response types. This will let ZeroAd Network users know that you are participating in the program.
32
+ The modules uses `node:crypto` runtime module to ensure 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:
20
33
 
21
- ## Module Installation
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 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`.
22
37
 
23
- As it is written in TypeScript, all types and interfaces are available. Also, this package works well in `mjs` (ESM) and `cjs` (CJS - older node versions) environments. You choose to either use `import` or `require()` statements. Imports are always preferred.
38
+ Parsed token result example:
24
39
 
25
- Install this package using your favourite package manager:
40
+ ```js
41
+ {
42
+ ADS_OFF: boolean,
43
+ COOKIE_CONSENT_OFF: boolean,
44
+ MARKETING_DIALOG_OFF: boolean,
45
+ CONTENT_PAYWALL_OFF: boolean,
46
+ SUBSCRIPTION_ACCESS_ON: boolean,
47
+ };
48
+ ```
49
+
50
+ User's token payload verification is done locally on 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 token and its parsed results in Redis - it takes longer to retrieve the cached result than to verify token payload integrity.
55
+
56
+ ## Why to join
57
+
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.
59
+
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.
61
+
62
+ ## Onboard your site
63
+
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.
65
+
66
+ If you decide for your site to participate in 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.
67
+
68
+ ## Module installation
69
+
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.
71
+
72
+ To install the module use your favourite package manager:
26
73
 
27
74
  ```shell
28
75
  # npm
@@ -36,11 +83,22 @@ pnpm add @zeroad.network/token
36
83
 
37
84
  # or Bun
38
85
  bun add @zeroad.network/token
86
+
87
+ # or Deno
88
+ deno add npm:@zeroad.network/token
39
89
  ```
40
90
 
41
- # Examples
91
+ ## Examples
92
+
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/).
94
+
95
+ Take this JavaScript example as a quick reference. The example will show how to:
42
96
 
43
- Take the simplest JavaScript example as a reference. The most basic, and honestly, quite complete use with `express` v.5 could look similar to this:
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.
100
+
101
+ An Express.js v.5 example of a minimal app:
44
102
 
45
103
  ```js
46
104
  import express from "express";
@@ -48,27 +106,28 @@ import { Site } from "@zeroad.network/token";
48
106
 
49
107
  const app = express();
50
108
 
51
- // Initialize your Zero Ad Network module
52
- // Welcome Header Value acquired during Site Registration process at Zero Ad Network platform
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).
53
111
  const ZERO_AD_NETWORK_WELCOME_HEADER_VALUE = "AZqnKU56eIC7vCD1PPlwHg^1^3";
54
112
  const site = Site(ZERO_AD_NETWORK_WELCOME_HEADER_VALUE);
55
113
 
56
114
  app
115
+ // Your middleware
57
116
  .use((req, res, next) => {
58
- // X-Better-Web-Welcome header injection can could have it's own simple middleware like this:
117
+ // Inject "X-Better-Web-Welcome" header
59
118
  res.set(site.SERVER_HEADER_NAME, site.SERVER_HEADER_VALUE);
60
119
 
61
- // Process request token from incoming client token header value.
62
- // And attach processed token info to request for downstream usage.
120
+ // Parse the request token from incoming client token header value.
121
+ // And attach parsed info to request object for downstream usage.
63
122
  req.tokenContext = site.parseToken(req.get[site.CLIENT_HEADER_NAME]);
64
123
 
65
124
  next();
66
125
  })
67
126
  .get("/", (req, res) => {
68
- // For example:
127
+ // If you would print it's contents:
69
128
  console.log(req.tokenContext);
70
129
 
71
- // Will produce the following structure:
130
+ // This will produce:
72
131
  req.tokenContext = {
73
132
  // If set to true: Render no advertisements anywhere on the page
74
133
  ADS_OFF: boolean,
@@ -92,19 +151,3 @@ app.listen(port, () => {
92
151
  console.log(`Server listening at http://localhost:${port}`);
93
152
  });
94
153
  ```
95
-
96
- For all example implementations such as `Express.js` (JavaScript), `Hono` and `Fastify` (both are TypeScript), please go to [see more examples](https://github.com/laurynas-karvelis/zeroad-token-ts/tree/main/examples/).
97
-
98
- P.S.: Each web request coming from active subscriber using their Zero Ad Network browser extension will incur a tiny fraction of CPU computation cost to verify the token data matches its encrypted signature. On modern web infrastructure a request execution time will increase roughly by ~0.06ms to 0.2ms or so. Mileage might vary, but the impact is minimal.
99
-
100
- # Final thoughts
101
-
102
- If no user of ours interacts with your website or web app, you lose nothing. You can keep showing ads to normal users, keep your paywalls etc.
103
-
104
- We hope the opposite will happen and you'll realize how many people value pure, clean content created that is meant for them, actual people, that brings tangible and meaningful value for everyone.
105
-
106
- Each website that joins us, becomes a part of re-making the web as it originally was intended to be - a joyful and wonderful experience once again.
107
-
108
- **Thank you!**
109
-
110
- > The "Zero Ad Network" team.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeroad.network/token",
3
- "version": "0.13.2",
3
+ "version": "0.13.3",
4
4
  "license": "Apache-2.0",
5
5
  "repository": "github:laurynas-karvelis/zeroad-token-typescript",
6
6
  "homepage": "https://zeroad.network",