ecwt 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -1,3 +1,234 @@
 
-# ecwt
+# ECWT
 Encrypted CBOR-encoded Web Token
+
+## What is it?
+
+ECWT is module for creating and verifying encrypted CBOR-encoded Web Tokens. It is designed to be used in situations where JWT is used, but there are major differences:
+
+| | JWT | ECWT |
+| --- | --- | --- |
+| Encoding | 🧐 JSON with base64 | ✅ CBOR <br> 2x smaller output |
+| Binary data | 🧐 Double base64 encoding | ✅ Supported out of the box |
+| Security | 📝 Signed <br> Payload is readable by everyone | 🔒 Encrypted <br> Payload is readable only by the private key possessor |
+| Metadata | ➕ Type and algorithm, increases size | ✅ No unnecessary metadata |
+| Revocation | 🧑‍💻 Requires additional implementation | ✅ Included with Redis |
+
+## Installation
+
+ECWT depends on other modules, so you need to install them too.
+
+```
+npm install ecwt @kirick/snowflake
+pnpm install ecwt @kirick/snowflake
+bun install ecwt @kirick/snowflake
+```
+
+### Some dependencies
+
+`EcwtFactory` depends on other modules, so you might be need to install them too.
+
+#### `@kirick/snowflake` to create unique IDs (required)
+
+For documentation, see [snowflake-js repository](https://github.com/kirick13/snowflake-js).
+
+```javascript
+import { SnowflakeFactory } from '@kirick/snowflake';
+
+const snowflakeFactory = new SnowflakeFactory({
+	server_id: 0,
+	worker_id: 0,
+});
+```
+
+#### `redis` to store revoked tokens (optional)
+
+```javascript
+import { createClient } from 'redis';
+
+const redisClient = createClient({
+	socket: {
+		host: 'localhost',
+		port: 6379,
+	},
+});
+
+await redisClient.connect();
+```
+
+#### `lru` to avoid decrypt the same token multiple times (optional)
+
+```javascript
+import { LRUCache } from 'lru-cache';
+
+const lruCache = new LRUCache({
+    max: 1000, // maximum of 1000 items
+    ttl: 60 * 60 * 1000, // 1 hour
+});
+```
+
+#### Validation library of your choice (optional)
+
+To reduce the size of the token, ECWT does not include object keys in the payload. By specifying the schema, you also can validate the payloads.
+
+In our example, we use [valibot](https://valibot.dev) library.
+
+```javascript
+import {
+	number,
+	string,
+	maxValue,
+	maxLength,
+	safeParse } from 'valibot';
+
+const schema = {
+    user_id: (value) => safeParse(
+        number([
+            maxValue(10),
+        ]),
+        value,
+    ).success,
+    nick: (value) => safeParse(
+        string([
+            maxLength(10),
+        ]),
+        value,
+    ).success,
+};
+```
+
+That schema will prevent creating tokens for users with ID greater than 10 and nicknames longer than 10 characters.
+
+## API
+
+### `EcwtFactory`
+
+```typescript
+constructor({
+    redisClient: RedisClientType?,
+    lruCache: LRU?,
+    snowflakeFactory: SnowflakeFactory,
+    options: {
+        namespace: string?,
+        key: Buffer,
+        schema: {
+            [key: string]: (value: any) => boolean,
+        } = {},
+    },
+})
+```
+
+Create your `EcwtFactory` instance to create, and parse tokens.
+
+```javascript
+import { EcwtFactory } from 'ecwt';
+
+const ecwtFactory = new EcwtFactory({
+	redisClient,
+	lruCache,
+	snowflakeFactory,
+	options: {
+        // "options.namespace" is required to identify the storage of revoked tokens in Redis
+		namespace: 'test',
+		key: Buffer.from(
+			'54RoavO+7orGGCKqLXcMwNGFGbcnSEq22f9bJX3lT9lgEPSaRAMBaEnHgMQPTPXcifFvGZmDGzOFqUMfqXsAhQ==',
+			'base64',
+		),
+		schema,
+	},
+});
+```
+
+#### Class method `create`
+
+```typescript
+create(
+    payload: {
+        [key: string]: any,
+    },
+    options: {
+        ttl: number?,
+    }
+): Promise<Ecwt>
+```
+
+Creates a token.
+
+`options.ttl` specifies the time to live of the token in seconds. If not specified, the token will not expire.
+
+Returns `Ecwt` instance.
+
+```javascript
+const ecwt_token = await ecwtFactory.create(
+    {
+        user_id: 1,
+        nick: 'kirick',
+    },
+    {
+        ttl: 30 * 60,
+    }
+);
+```
+
+#### Class method `verify`
+
+```typescript
+verify(
+    token: string,
+): Promise<Ecwt>
+```
+
+Parses string representation of the token and verifies it:
+
+- to be decrypted properly,
+- for expiration,
+- for revocation (if Redis client is provided),
+- for schema.
+
+Returns `Ecwt` instance.
+
+If the token is invalid, throws `EcwtInvalidError` which contains `Ecwt` instance in the `ecwt` property.
+
+```javascript
+const ecwt_token = await ecwtFactory.verify(token);
+```
+
+### `Ecwt`
+
+Represents the token. It cannot be created by the user.
+
+```javascript
+import { Ecwt } from 'ecwt';
+```
+
+#### Class property `token: string`
+
+The string representation of the token.
+
+#### Class property `id: string`
+
+The unique ID of the token.
+
+#### Class property `snowflake: Snowflake`
+
+The `Snowflake` instance of the token. For documentation, see [snowflake-js repository](https://github.com/kirick13/snowflake-js).
+
+#### Class property `ts_expired: number`
+
+The timestamp of the token expiration in seconds. If the token does not expire, it is `Number.POSITIVE_INFINITY`.
+
+#### Class property `ttl: number`
+
+Current the time to live of the token in seconds. If the token does not expire, it is `Number.POSITIVE_INFINITY`.
+
+#### Class property `data: { [key: string]: any }`
+
+The payload of the token.
+
+#### Class method `revoke`
+
+```typescript
+revoke(): Promise<void>
+```
+
+Revokes the token. It will be impossible to verify it after that.

package/dist/ecwt.cjs

@@ -1,6 +1,8 @@
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -14,29 +16,374 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/main.js
 var main_exports = {};
 __export(main_exports, {
   Ecwt: () => Ecwt,
-  EcwtGenerator: () => EcwtGenerator
+  EcwtFactory: () => EcwtFactory
 });
 module.exports = __toCommonJS(main_exports);
 
 // src/factory.js
-var EcwtGenerator = class {
-  constructor() {
-  }
-};
+var import_snowflake = require("@kirick/snowflake");
+var import_cbor_x = require("cbor-x");
+var import_evilcrypt = require("evilcrypt");
+var import_lru_cache = require("lru-cache");
+var import_redis = require("redis");
+
+// src/utils/time.js
+function toSeconds(value) {
+  return Math.floor(value / 1e3);
+}
 
 // src/token.js
 var Ecwt = class {
-  constructor() {
+  #ecwtFactory;
+  #token;
+  #snowflake;
+  #ttl_initial;
+  #data;
+  /**
+   * @param {EcwtFactory} ecwtFactory -
+   * @param {object} options -
+   * @param {string} options.token String representation of token.
+   * @param {Snowflake} options.snowflake -
+   * @param {number | null} options.ttl_initial Time to live in seconds at the moment of token creation.
+   * @param {object} options.data Data stored in token.
+   */
+  constructor(ecwtFactory, {
+    token,
+    snowflake,
+    ttl_initial,
+    data
+  }) {
+    this.#ecwtFactory = ecwtFactory;
+    this.#token = token;
+    this.#snowflake = snowflake;
+    this.#ttl_initial = ttl_initial;
+    this.#data = Object.freeze(data);
+  }
+  get token() {
+    return this.#token;
+  }
+  get id() {
+    return this.#snowflake.base62;
+  }
+  get snowflake() {
+    return this.#snowflake;
+  }
+  get ts_expired() {
+    if (this.#ttl_initial === null) {
+      return Number.POSITIVE_INFINITY;
+    }
+    return toSeconds(this.#snowflake.timestamp) + this.#ttl_initial;
+  }
+  /**
+   * Time to live in seconds.
+   * @type {number}
+   * @readonly
+   */
+  get ttl() {
+    if (this.#ttl_initial === null) {
+      return Number.POSITIVE_INFINITY;
+    }
+    return this.#ttl_initial - toSeconds(Date.now() - this.#snowflake.timestamp);
+  }
+  get data() {
+    return this.#data;
+  }
+  /* async */
+  revoke() {
+    return this.#ecwtFactory._revoke({
+      token_id: this.id,
+      ts_ms_created: this.#snowflake.timestamp,
+      ttl_initial: this.#ttl_initial
+    });
+  }
+};
+
+// src/utils/base62.js
+var import_base_x = __toESM(require("base-x"), 1);
+var base62 = (0, import_base_x.default)("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz");
+
+// src/utils/errors.js
+var InvalidPackageInstanceError = class extends TypeError {
+  constructor(property, class_name, package_name) {
+    super(`Value ${property} must be an instance of ${class_name} from package "${package_name}". That error is probably caused by two separate installations of "${package_name}". Please, make sure that "${package_name}" in your project is matches "peerDependencies" of "ecwt" package.`);
+  }
+};
+var EcwtInvalidError = class extends Error {
+  constructor(ecwt) {
+    super("Ecwt token is invalid.");
+    this.ecwt = ecwt;
+  }
+};
+var EcwtExpiredError = class extends EcwtInvalidError {
+  constructor(ecwt) {
+    super();
+    this.ecwt = ecwt;
+    this.message = "Ecwt is expired.";
+  }
+};
+var EcwtRevokedError = class extends EcwtInvalidError {
+  constructor(ecwt) {
+    super();
+    this.ecwt = ecwt;
+    this.message = "Ecwt is revoked.";
+  }
+};
+
+// src/factory.js
+var REDIS_PREFIX = "@ecwt:";
+function getAllKeysList(value) {
+  const keys = [];
+  for (const key in value) {
+    keys.push(key);
+  }
+  return keys.sort().join(",");
+}
+var redisClient = (0, import_redis.createClient)();
+var redis_client_constructor_name = redisClient.constructor.name;
+var redis_client_keys = getAllKeysList(redisClient);
+var EcwtFactory = class {
+  #redisClient;
+  #lruCache;
+  #snowflakeFactory;
+  #redis_keys = {};
+  #encryption_key;
+  #schema;
+  #schema_keys_sorted;
+  /**
+   *
+   * @param {object} param0 -
+   * @param {import('redis').RedisClientType} [param0.redisClient] RedisClient instance. If not provided, tokens will not be revoked and cannot be checked for revocation.
+   * @param {LRUCache} [param0.lruCache] LRUCache instance. If not provided, tokens will be decrypted every time they are verified.
+   * @param {SnowflakeFactory} param0.snowflakeFactory SnowflakeFactory instance.
+   * @param {object} param0.options -
+   * @param {string} [param0.options.namespace] Namespace for Redis keys.
+   * @param {Buffer} param0.options.key Encryption key, 64 bytes
+   * @param {{ [key: string]: (value: any) => boolean }} param0.options.schema Schema for token data. Each property is a validator function that returns true if value is valid.
+   */
+  constructor({
+    redisClient: redisClient2 = null,
+    lruCache = null,
+    snowflakeFactory,
+    options: {
+      namespace = null,
+      key,
+      schema = {}
+    }
+  }) {
+    if (redisClient2 !== null && (redisClient2.constructor.name !== redis_client_constructor_name || getAllKeysList(redisClient2) !== redis_client_keys)) {
+      throw new InvalidPackageInstanceError(
+        "redisClient",
+        "Commander extends RedisClient",
+        "redis"
+      );
+    }
+    this.#redisClient = redisClient2;
+    if (lruCache !== null && lruCache instanceof import_lru_cache.LRUCache !== true) {
+      throw new InvalidPackageInstanceError(
+        "lruCache",
+        "LRUCache",
+        "lru-cache"
+      );
+    }
+    this.#lruCache = lruCache;
+    if (snowflakeFactory instanceof import_snowflake.SnowflakeFactory !== true) {
+      throw new InvalidPackageInstanceError(
+        "snowflakeFactory",
+        "SnowflakeFactory",
+        "@kirick/snowflake"
+      );
+    }
+    this.#snowflakeFactory = snowflakeFactory;
+    this.#redis_keys.revoked = `${REDIS_PREFIX}${namespace}:revoked`;
+    this.#encryption_key = key;
+    this.#schema = schema;
+    this.#schema_keys_sorted = Object.keys(schema).sort();
+  }
+  /**
+   * Creates new token.
+   * @async
+   * @param {object} data Data to be stored in token.
+   * @param {object} [options] -
+   * @param {number} [options.ttl] Time to live in seconds. By default, token will never expire.
+   * @returns {Promise<Ecwt>} -
+   */
+  async create(data, {
+    ttl
+  } = {}) {
+    const payload = [];
+    for (const key of this.#schema_keys_sorted) {
+      const value = data[key];
+      const validator = this.#schema[key];
+      if (typeof validator === "function" && validator(value) !== true) {
+        throw new TypeError(`Value "${value}" of property "${key}" is invalid.`);
+      }
+      payload.push(value);
+    }
+    if (typeof ttl !== "number" && Number.isNaN(ttl) !== true || ttl === Number.POSITIVE_INFINITY) {
+      ttl = null;
+    }
+    const snowflake = await this.#snowflakeFactory.createSafe();
+    const token_raw = (0, import_cbor_x.encode)([
+      snowflake.buffer,
+      ttl,
+      payload
+    ]);
+    const token_encrypted = await import_evilcrypt.v2.encrypt(
+      token_raw,
+      this.#encryption_key
+    );
+    const token = base62.encode(token_encrypted);
+    this.#setCache(
+      token,
+      {
+        snowflake,
+        ttl_initial: ttl,
+        data
+      }
+    );
+    return new Ecwt(
+      this,
+      {
+        token,
+        snowflake,
+        ttl_initial: ttl,
+        data
+      }
+    );
+  }
+  #setCache(token, data) {
+    this.#lruCache?.set(
+      token,
+      data,
+      {
+        ttl: data.ttl * 1e3
+      }
+    );
+  }
+  /**
+   * Parses token.
+   * @async
+   * @param {string} token String representation of token.
+   * @returns {Promise<Ecwt>} -
+   */
+  async verify(token) {
+    if (typeof token !== "string") {
+      throw new TypeError("Token must be a string.");
+    }
+    let snowflake;
+    let ttl_initial;
+    let data;
+    const cached_entry = this.#lruCache?.info(token);
+    if (cached_entry === void 0) {
+      const token_encrypted = Buffer.from(
+        base62.decode(token)
+      );
+      const token_raw = await (0, import_evilcrypt.decrypt)(
+        token_encrypted,
+        this.#encryption_key
+      );
+      const [
+        snowflake_buffer,
+        _ttl_initial,
+        payload
+      ] = (0, import_cbor_x.decode)(token_raw);
+      snowflake = this.#snowflakeFactory.parse(snowflake_buffer);
+      ttl_initial = _ttl_initial;
+      data = {};
+      for (const [index, key] of this.#schema_keys_sorted.entries()) {
+        data[key] = payload[index];
+      }
+      this.#setCache(
+        token,
+        {
+          snowflake,
+          ttl_initial,
+          data
+        }
+      );
+    } else {
+      ({
+        snowflake,
+        ttl_initial,
+        data
+      } = cached_entry.value);
+    }
+    const ecwt = new Ecwt(
+      this,
+      {
+        token,
+        snowflake,
+        ttl_initial,
+        data
+      }
+    );
+    if (typeof ttl_initial === "number" && Number.isNaN(ttl_initial) !== true && snowflake.timestamp + ttl_initial * 1e3 < Date.now()) {
+      throw new EcwtExpiredError(ecwt);
+    }
+    if (this.#redisClient) {
+      const score = await this.#redisClient.ZSCORE(
+        this.#redis_keys.revoked,
+        ecwt.id
+      );
+      if (score !== null) {
+        throw new EcwtRevokedError(ecwt);
+      }
+    }
+    return ecwt;
+  }
+  /**
+   * Revokes token.
+   * @async
+   * @param {object} options -
+   * @param {string} options.token_id -
+   * @param {number} options.ts_ms_created -
+   * @param {number} options.ttl_initial -
+   * @returns {Promise<void>} -
+   */
+  async _revoke({
+    token_id,
+    ts_ms_created,
+    ttl_initial
+  }) {
+    if (this.#redisClient) {
+      const ts_ms_expired = ts_ms_created + ttl_initial * 1e3;
+      if (ts_ms_expired > Date.now()) {
+        await this.#redisClient.sendCommand([
+          "ZADD",
+          this.#redis_keys.revoked,
+          String(ts_ms_expired),
+          token_id
+        ]);
+      }
+    } else {
+      console.warn("[ecwt] Redis client is not provided. Tokens cannot be revoked.");
+    }
+  }
+  /**
+   * Purges cache.
+   * @private
+   * @returns {void} -
+   */
+  _purgeCache() {
+    this.#lruCache?.clear();
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Ecwt,
-  EcwtGenerator
+  EcwtFactory
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ecwt",
-	"version": "0.1.0-beta.1",
+	"version": "0.1.0-beta.3",
 	"description": "Encrypted CBOR-encoded Web Token",
 	"main": "src/main.js",
 	"type": "module",
@@ -14,30 +14,36 @@
 		"node": ">=14.0.0"
 	},
 	"dependencies": {
-		"cbor-x": "1.5.6",
 		"base-x": "4.0.0",
-		"evilcrypt": "0.2.0-beta.1"
+		"cbor-x": "1.5.6",
+		"evilcrypt": "0.2.0-beta.4"
 	},
 	"peerDependencies": {
-		"@kirick/redis-client": "^4.0.1-beta.3",
-		"@kirick/snowflake": "^0.2.0-beta.3",
-		"lru-cache": "^7"
+		"@kirick/snowflake": "^0.2.0-beta.7",
+		"lru-cache": "^7 || ^8 || ^9 || ^10",
+		"redis": "^4"
 	},
 	"devDependencies": {
 		"@babel/eslint-parser": "7.21.8",
 		"eslint": "8.41.0",
 		"eslint-config-xo": "0.43.1",
 		"eslint-plugin-import": "2.27.5",
+		"eslint-plugin-jsdoc": "^46.9.1",
 		"eslint-plugin-node": "11.1.0",
 		"eslint-plugin-promise": "6.1.1",
-		"eslint-plugin-unicorn": "47.0.0"
+		"eslint-plugin-unicorn": "47.0.0",
+		"jest": "^29.7.0",
+		"valibot": "^0.24.1"
 	},
 	"scripts": {
-		"test": "npm run test-node && bun test",
-		"test-node": "NODE_OPTIONS=--experimental-vm-modules jest",
+		"test": "bun run redis-up && npm run test-node && bun test",
+		"test-node": "NODE_OPTIONS=--experimental-vm-modules jest --forceExit",
+		"coverage": "bun run redis-up && bun test --coverage",
 		"build": "bun run build-cjs",
 		"build-cjs": "bunx esbuild --bundle --platform=node --format=cjs --packages=external --outfile=dist/ecwt.cjs src/main.js",
-		"npm-publish": "bun run build && npm publish --tag beta"
+		"npm-publish": "bun run build && bun run eslint . && bun run test && npm publish --tag beta; bun run redis-down",
+		"redis-up": "docker ps | grep test-redis-ecwt-test >/dev/null || docker run --rm -d -p 16274:6379 --name test-redis-ecwt-test redis:7-alpine",
+		"redis-down": "docker stop test-redis-ecwt-test"
 	},
 	"repository": {
 		"type": "git",

package/src/factory.js

@@ -1,5 +1,325 @@
 
-export class EcwtGenerator {
-	constructor() {
+import { SnowflakeFactory }       from '@kirick/snowflake';
+import {
+	encode as cborEncode,
+	decode as cborDecode }        from 'cbor-x';
+import {
+	decrypt as evilcryptDecrypt,
+	v2 as evilcryptV2          }  from 'evilcrypt';
+import { LRUCache }               from 'lru-cache';
+import { createClient }           from 'redis';
+import { Ecwt }                   from './token.js';
+import { base62 }                 from './utils/base62.js';
+import {
+	InvalidPackageInstanceError,
+	EcwtExpiredError,
+	EcwtRevokedError }            from './utils/errors.js';
+
+const REDIS_PREFIX = '@ecwt:';
+
+// eslint-disable-next-line jsdoc/require-jsdoc
+function getAllKeysList(value) {
+	const keys = [];
+	// eslint-disable-next-line guard-for-in
+	for (const key in value) {
+		keys.push(key);
+	}
+	return keys.sort().join(',');
+}
+
+const redisClient = createClient();
+const redis_client_constructor_name = redisClient.constructor.name;
+const redis_client_keys = getAllKeysList(redisClient);
+
+export class EcwtFactory {
+	#redisClient;
+	#lruCache;
+	#snowflakeFactory;
+
+	#redis_keys = {};
+	#encryption_key;
+
+	#schema;
+	#schema_keys_sorted;
+
+	/**
+	 *
+	 * @param {object} param0 -
+	 * @param {import('redis').RedisClientType} [param0.redisClient] RedisClient instance. If not provided, tokens will not be revoked and cannot be checked for revocation.
+	 * @param {LRUCache} [param0.lruCache] LRUCache instance. If not provided, tokens will be decrypted every time they are verified.
+	 * @param {SnowflakeFactory} param0.snowflakeFactory SnowflakeFactory instance.
+	 * @param {object} param0.options -
+	 * @param {string} [param0.options.namespace] Namespace for Redis keys.
+	 * @param {Buffer} param0.options.key Encryption key, 64 bytes
+	 * @param {{ [key: string]: (value: any) => boolean }} param0.options.schema Schema for token data. Each property is a validator function that returns true if value is valid.
+	 */
+	constructor({
+		redisClient = null,
+		lruCache = null,
+		snowflakeFactory,
+		options: {
+			namespace = null,
+			key,
+			schema = {},
+		},
+	}) {
+		if (
+			redisClient !== null
+			&& (
+				redisClient.constructor.name !== redis_client_constructor_name
+				|| getAllKeysList(redisClient) !== redis_client_keys
+			)
+		) {
+			throw new InvalidPackageInstanceError(
+				'redisClient',
+				'Commander extends RedisClient',
+				'redis',
+			);
+		}
+		this.#redisClient = redisClient;
+
+		if (
+			lruCache !== null
+			&& lruCache instanceof LRUCache !== true
+		) {
+			throw new InvalidPackageInstanceError(
+				'lruCache',
+				'LRUCache',
+				'lru-cache',
+			);
+		}
+		this.#lruCache = lruCache;
+
+		if (snowflakeFactory instanceof SnowflakeFactory !== true) {
+			throw new InvalidPackageInstanceError(
+				'snowflakeFactory',
+				'SnowflakeFactory',
+				'@kirick/snowflake',
+			);
+		}
+		this.#snowflakeFactory = snowflakeFactory;
+
+		this.#redis_keys.revoked = `${REDIS_PREFIX}${namespace}:revoked`;
+
+		this.#encryption_key = key;
+
+		this.#schema = schema;
+		this.#schema_keys_sorted = Object.keys(schema).sort();
+	}
+
+	/**
+	 * Creates new token.
+	 * @async
+	 * @param {object} data Data to be stored in token.
+	 * @param {object} [options] -
+	 * @param {number} [options.ttl] Time to live in seconds. By default, token will never expire.
+	 * @returns {Promise<Ecwt>} -
+	 */
+	async create(
+		data,
+		{
+			ttl,
+		} = {},
+	) {
+		const payload = [];
+		for (const key of this.#schema_keys_sorted) {
+			const value = data[key];
+			const validator = this.#schema[key];
+
+			if (
+				typeof validator === 'function'
+				&& validator(value) !== true
+			) {
+				throw new TypeError(`Value "${value}" of property "${key}" is invalid.`);
+			}
+
+			payload.push(value);
+		}
+
+		if (
+			(
+				typeof ttl !== 'number'
+				&& Number.isNaN(ttl) !== true
+			)
+			|| ttl === Number.POSITIVE_INFINITY
+		) {
+			ttl = null;
+		}
+
+		const snowflake = await this.#snowflakeFactory.createSafe();
+
+		const token_raw = cborEncode([
+			snowflake.buffer,
+			ttl,
+			payload,
+		]);
+
+		const token_encrypted = await evilcryptV2.encrypt(
+			token_raw,
+			this.#encryption_key,
+		);
+
+		const token = base62.encode(token_encrypted);
+
+		this.#setCache(
+			token,
+			{
+				snowflake,
+				ttl_initial: ttl,
+				data,
+			},
+		);
+
+		return new Ecwt(
+			this,
+			{
+				token,
+				snowflake,
+				ttl_initial: ttl,
+				data,
+			},
+		);
+	}
+
+	#setCache(token, data) {
+		this.#lruCache?.set(
+			token,
+			data,
+			{
+				ttl: data.ttl * 1000,
+			},
+		);
+	}
+
+	/**
+	 * Parses token.
+	 * @async
+	 * @param {string} token String representation of token.
+	 * @returns {Promise<Ecwt>} -
+	 */
+	async verify(token) {
+		if (typeof token !== 'string') {
+			throw new TypeError('Token must be a string.');
+		}
+
+		let snowflake;
+		let ttl_initial;
+		let data;
+
+		const cached_entry = this.#lruCache?.info(token);
+		// token is cached
+		if (cached_entry === undefined) {
+			const token_encrypted = Buffer.from(
+				base62.decode(token),
+			);
+
+			const token_raw = await evilcryptDecrypt(
+				token_encrypted,
+				this.#encryption_key,
+			);
+
+			const [
+				snowflake_buffer,
+				_ttl_initial,
+				payload,
+			] = cborDecode(token_raw);
+
+			snowflake = this.#snowflakeFactory.parse(snowflake_buffer);
+			ttl_initial = _ttl_initial;
+
+			data = {};
+			for (const [ index, key ] of this.#schema_keys_sorted.entries()) {
+				data[key] = payload[index];
+			}
+
+			this.#setCache(
+				token,
+				{
+					snowflake,
+					ttl_initial,
+					data,
+				},
+			);
+		}
+		else {
+			({
+				snowflake,
+				ttl_initial,
+				data,
+			} = cached_entry.value);
+		}
+
+		// console.log('snowflake', snowflake);
+		// console.log('ttl', ttl);
+		// console.log('data', data);
+
+		const ecwt = new Ecwt(
+			this,
+			{
+				token,
+				snowflake,
+				ttl_initial,
+				data,
+			},
+		);
+
+		if (
+			typeof ttl_initial === 'number'
+			&& Number.isNaN(ttl_initial) !== true
+			&& snowflake.timestamp + (ttl_initial * 1000) < Date.now()
+		) {
+			throw new EcwtExpiredError(ecwt);
+		}
+
+		if (this.#redisClient) {
+			const score = await this.#redisClient.ZSCORE(
+				this.#redis_keys.revoked,
+				ecwt.id,
+			);
+			if (score !== null) {
+				throw new EcwtRevokedError(ecwt);
+			}
+		}
+
+		return ecwt;
+	}
+
+	/**
+	 * Revokes token.
+	 * @async
+	 * @param {object} options -
+	 * @param {string} options.token_id -
+	 * @param {number} options.ts_ms_created -
+	 * @param {number} options.ttl_initial -
+	 * @returns {Promise<void>} -
+	 */
+	async _revoke({
+		token_id,
+		ts_ms_created,
+		ttl_initial,
+	}) {
+		if (this.#redisClient) {
+			const ts_ms_expired = ts_ms_created + (ttl_initial * 1000);
+			if (ts_ms_expired > Date.now()) {
+				await this.#redisClient.sendCommand([
+					'ZADD',
+					this.#redis_keys.revoked,
+					String(ts_ms_expired),
+					token_id,
+				]);
+			}
+		}
+		else {
+			console.warn('[ecwt] Redis client is not provided. Tokens cannot be revoked.');
+		}
+	}
+
+	/**
+	 * Purges cache.
+	 * @private
+	 * @returns {void} -
+	 */
+	_purgeCache() {
+		this.#lruCache?.clear();
 	}
 }

package/src/main.js

@@ -1,3 +1,3 @@
 
-export { EcwtGenerator } from './factory.js';
+export { EcwtFactory } from './factory.js';
 export { Ecwt } from './token.js';

package/src/token.js

@@ -1,5 +1,86 @@
 
+import { toSeconds } from './utils/time.js';
+
+/**
+ * @typedef {import('@kirick/snowflake/src/snowflake.js').Snowflake} Snowflake
+ * @typedef {import('./factory.js').EcwtFactory} EcwtFactory
+ */
+
 export class Ecwt {
-	constructor() {
+	#ecwtFactory;
+
+	#token;
+	#snowflake;
+	#ttl_initial;
+	#data;
+
+	/**
+	 * @param {EcwtFactory} ecwtFactory -
+	 * @param {object} options -
+	 * @param {string} options.token String representation of token.
+	 * @param {Snowflake} options.snowflake -
+	 * @param {number | null} options.ttl_initial Time to live in seconds at the moment of token creation.
+	 * @param {object} options.data Data stored in token.
+	 */
+	constructor(
+		ecwtFactory,
+		{
+			token,
+			snowflake,
+			ttl_initial,
+			data,
+		},
+	) {
+		this.#ecwtFactory = ecwtFactory;
+
+		this.#token = token;
+		this.#snowflake = snowflake;
+		this.#ttl_initial = ttl_initial;
+		this.#data = Object.freeze(data);
+	}
+
+	get token() {
+		return this.#token;
+	}
+
+	get id() {
+		return this.#snowflake.base62;
+	}
+
+	get snowflake() {
+		return this.#snowflake;
+	}
+
+	get ts_expired() {
+		if (this.#ttl_initial === null) {
+			return Number.POSITIVE_INFINITY;
+		}
+
+		return toSeconds(this.#snowflake.timestamp) + this.#ttl_initial;
+	}
+
+	/**
+	 * Time to live in seconds.
+	 * @type {number}
+	 * @readonly
+	 */
+	get ttl() {
+		if (this.#ttl_initial === null) {
+			return Number.POSITIVE_INFINITY;
+		}
+
+		return this.#ttl_initial - toSeconds(Date.now() - this.#snowflake.timestamp);
+	}
+
+	get data() {
+		return this.#data;
+	}
+
+	/* async */ revoke() {
+		return this.#ecwtFactory._revoke({
+			token_id: this.id,
+			ts_ms_created: this.#snowflake.timestamp,
+			ttl_initial: this.#ttl_initial,
+		});
 	}
 }

package/src/utils/base62.js

@@ -0,0 +1,4 @@
+
+import basex from 'base-x';
+
+export const base62 = basex('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz');

package/src/utils/errors.js

@@ -0,0 +1,32 @@
+
+export class InvalidPackageInstanceError extends TypeError {
+	constructor(property, class_name, package_name) {
+		super(`Value ${property} must be an instance of ${class_name} from package "${package_name}". That error is probably caused by two separate installations of "${package_name}". Please, make sure that "${package_name}" in your project is matches "peerDependencies" of "ecwt" package.`);
+	}
+}
+
+export class EcwtInvalidError extends Error {
+	constructor(ecwt) {
+		super('Ecwt token is invalid.');
+
+		this.ecwt = ecwt;
+	}
+}
+
+export class EcwtExpiredError extends EcwtInvalidError {
+	constructor(ecwt) {
+		super();
+
+		this.ecwt = ecwt;
+		this.message = 'Ecwt is expired.';
+	}
+}
+
+export class EcwtRevokedError extends EcwtInvalidError {
+	constructor(ecwt) {
+		super();
+
+		this.ecwt = ecwt;
+		this.message = 'Ecwt is revoked.';
+	}
+}

package/src/utils/time.js

@@ -0,0 +1,17 @@
+
+/**
+ * Convert timestamp in seconds to milliseconds.
+ * @param {*} value Timestamp in milliseconds.
+ * @returns {number} Timestamp in seconds.
+ */
+export function toSeconds(value) {
+	return Math.floor(value / 1000);
+}
+
+// /**
+//  * Returns current timestamp in seconds.
+//  * @returns {number} Timestamp in seconds.
+//  */
+// export function unixtime() {
+// 	return toSeconds(Date.now());
+// }