ecwt 0.1.0-beta.2 → 0.1.1-beta.1

package/README.md

@@ -1,3 +1,243 @@
 
-# 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 | null,
+    }
+): Promise<Ecwt>
+```
+
+Creates a token.
+
+`options.ttl` specifies the time to live of the token in seconds. If set to null, token will never expire.
+
+> **Be careful with `ttl=null`!**
+>
+> Revoked tokens are stored in Redis until they expire. But such tokens will be stored in Redis forever, which will lead to uncontrolled Redis database growth.
+
+Returns `Ecwt` instance.
+
+```javascript
+// Example
+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 `readonly token: string`
+
+The string representation of the token.
+
+#### Class property `readonly id: string`
+
+The unique ID of the token.
+
+#### Class property `readonly snowflake: Snowflake`
+
+The `Snowflake` instance of the token. For documentation, see [snowflake-js repository](https://github.com/kirick13/snowflake-js).
+
+#### Class property `readonly ts_expired: number | null`
+
+The timestamp of the token expiration in seconds. Equals to `null` if the token does not expire.
+
+#### Class property `readonly data: { [key: string]: any }`
+
+The payload of the token.
+
+#### Class method `getTTL`
+
+```typescript
+getTTL(): number | null
+```
+
+Returns current the time to live of the token in seconds. If the token does not expire, returns `null`.
+
+#### Class method `revoke`
+
+```typescript
+revoke(): Promise<void>
+```
+
+Revokes the token. Attempts to verify the revoked token will throw `EcwtRevokedError`.

package/dist/ecwt.cjs

@@ -47,18 +47,57 @@ function toSeconds(value) {
 }
 
 // src/token.js
+function assign(target, key, value) {
+  Object.defineProperty(
+    target,
+    key,
+    {
+      value,
+      enumerable: true,
+      writable: false,
+      configurable: false
+    }
+  );
+}
 var Ecwt = class {
   #ecwtFactory;
-  #token;
-  #snowflake;
   #ttl_initial;
-  #data;
+  /**
+   * Token string representation.
+   * @type {string}
+   * @readonly
+   */
+  token;
+  /**
+   * Token ID.
+   * @type {string}
+   * @readonly
+   */
+  id;
+  /**
+   * Snowflake associated with token.
+   * @type {Snowflake}
+   * @readonly
+   */
+  snowflake;
+  /**
+   * Timestamp when token expires in seconds.
+   * @type {number?}
+   * @readonly
+   */
+  ts_expired;
+  /**
+   * Data stored in token.
+   * @type {{ [key: string]: any }}
+   * @readonly
+   */
+  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 {number?} options.ttl_initial Time to live in seconds at the moment of token creation.
    * @param {object} options.data Data stored in token.
    */
   constructor(ecwtFactory, {
@@ -68,45 +107,46 @@ var Ecwt = class {
     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;
+    assign(this, "token", token);
+    assign(
+      this,
+      "id",
+      snowflake.toBase62()
+    );
+    assign(this, "snowflake", snowflake);
+    assign(
+      this,
+      "ts_expired",
+      this.#getTimestampExpired()
+    );
+    assign(
+      this,
+      "data",
+      Object.freeze(data)
+    );
   }
-  get ts_expired() {
+  #getTimestampExpired() {
     if (this.#ttl_initial === null) {
-      return Number.POSITIVE_INFINITY;
+      return null;
     }
-    return toSeconds(this.#snowflake.timestamp) + this.#ttl_initial;
+    return toSeconds(this.snowflake.timestamp) + this.#ttl_initial;
   }
   /**
-   * Time to live in seconds.
-   * @type {number}
-   * @readonly
+   * Actual time to live in seconds.
+   * @returns {number | null} -
    */
-  get ttl() {
+  getTTL() {
     if (this.#ttl_initial === null) {
-      return Number.POSITIVE_INFINITY;
+      return null;
     }
-    return this.#ttl_initial - toSeconds(Date.now() - this.#snowflake.timestamp);
-  }
-  get data() {
-    return this.#data;
+    return this.#ttl_initial - toSeconds(Date.now() - this.snowflake.timestamp);
   }
   /* async */
   revoke() {
     return this.#ecwtFactory._revoke({
       token_id: this.id,
-      ts_ms_created: this.#snowflake.timestamp,
+      ts_ms_created: this.snowflake.timestamp,
       ttl_initial: this.#ttl_initial
     });
   }
@@ -233,16 +273,16 @@ var EcwtFactory = class {
       }
       payload.push(value);
     }
-    if (typeof ttl !== "number" && Number.isNaN(ttl) !== true || ttl === Number.POSITIVE_INFINITY) {
-      ttl = null;
+    if (typeof ttl !== "number" && Number.isNaN(ttl) !== true && ttl !== null) {
+      throw new TypeError("TTL must be a number or null.");
     }
     const snowflake = await this.#snowflakeFactory.createSafe();
     const token_raw = (0, import_cbor_x.encode)([
-      snowflake.buffer,
+      snowflake.toBuffer(),
       ttl,
       payload
     ]);
-    const token_encrypted = await (0, import_evilcrypt.encrypt)(
+    const token_encrypted = await import_evilcrypt.v2.encrypt(
       token_raw,
       this.#encryption_key
     );
@@ -360,6 +400,7 @@ var EcwtFactory = class {
     ttl_initial
   }) {
     if (this.#redisClient) {
+      ttl_initial = ttl_initial ?? Number.MAX_SAFE_INTEGER;
       const ts_ms_expired = ts_ms_created + ttl_initial * 1e3;
       if (ts_ms_expired > Date.now()) {
         await this.#redisClient.sendCommand([

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ecwt",
-	"version": "0.1.0-beta.2",
+	"version": "0.1.1-beta.1",
 	"description": "Encrypted CBOR-encoded Web Token",
 	"main": "src/main.js",
 	"type": "module",
@@ -16,10 +16,10 @@
 	"dependencies": {
 		"base-x": "4.0.0",
 		"cbor-x": "1.5.6",
-		"evilcrypt": "0.2.0-beta.2"
+		"evilcrypt": "0.2.0-beta.4"
 	},
 	"peerDependencies": {
-		"@kirick/snowflake": "^0.2.0-beta.7",
+		"@kirick/snowflake": "^0.2.1-beta.1",
 		"lru-cache": "^7 || ^8 || ^9 || ^10",
 		"redis": "^4"
 	},

package/src/factory.js

@@ -4,8 +4,8 @@ import {
 	encode as cborEncode,
 	decode as cborDecode }        from 'cbor-x';
 import {
-	encrypt as evilcryptEncrypt,
-	decrypt as evilcryptDecrypt } from 'evilcrypt';
+	decrypt as evilcryptDecrypt,
+	v2 as evilcryptV2          }  from 'evilcrypt';
 import { LRUCache }               from 'lru-cache';
 import { createClient }           from 'redis';
 import { Ecwt }                   from './token.js';
@@ -137,24 +137,22 @@ export class EcwtFactory {
 		}
 
 		if (
-			(
-				typeof ttl !== 'number'
-				&& Number.isNaN(ttl) !== true
-			)
-			|| ttl === Number.POSITIVE_INFINITY
+			typeof ttl !== 'number'
+			&& Number.isNaN(ttl) !== true
+			&& ttl !== null
 		) {
-			ttl = null;
+			throw new TypeError('TTL must be a number or null.');
 		}
 
 		const snowflake = await this.#snowflakeFactory.createSafe();
 
 		const token_raw = cborEncode([
-			snowflake.buffer,
+			snowflake.toBuffer(),
 			ttl,
 			payload,
 		]);
 
-		const token_encrypted = await evilcryptEncrypt(
+		const token_encrypted = await evilcryptV2.encrypt(
 			token_raw,
 			this.#encryption_key,
 		);
@@ -299,6 +297,8 @@ export class EcwtFactory {
 		ttl_initial,
 	}) {
 		if (this.#redisClient) {
+			ttl_initial = ttl_initial ?? Number.MAX_SAFE_INTEGER;
+
 			const ts_ms_expired = ts_ms_created + (ttl_initial * 1000);
 			if (ts_ms_expired > Date.now()) {
 				await this.#redisClient.sendCommand([

package/src/token.js

@@ -2,24 +2,70 @@
 import { toSeconds } from './utils/time.js';
 
 /**
- * @typedef {import('@kirick/snowflake/src/snowflake.js').Snowflake} Snowflake
+ * @typedef {import('@kirick/snowflake').Snowflake} Snowflake
  * @typedef {import('./factory.js').EcwtFactory} EcwtFactory
  */
 
+/**
+ * Assigns property to object.
+ * @param {object} target -
+ * @param {string} key -
+ * @param {any} value -
+ */
+function assign(target, key, value) {
+	Object.defineProperty(
+		target,
+		key,
+		{
+			value,
+			enumerable: true,
+			writable: false,
+			configurable: false,
+		},
+	);
+}
+
 export class Ecwt {
 	#ecwtFactory;
-
-	#token;
-	#snowflake;
 	#ttl_initial;
-	#data;
+
+	/**
+	 * Token string representation.
+	 * @type {string}
+	 * @readonly
+	 */
+	token;
+	/**
+	 * Token ID.
+	 * @type {string}
+	 * @readonly
+	 */
+	id;
+	/**
+	 * Snowflake associated with token.
+	 * @type {Snowflake}
+	 * @readonly
+	 */
+	snowflake;
+	/**
+	 * Timestamp when token expires in seconds.
+	 * @type {number?}
+	 * @readonly
+	 */
+	ts_expired;
+	/**
+	 * Data stored in token.
+	 * @type {{ [key: string]: any }}
+	 * @readonly
+	 */
+	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 {number?} options.ttl_initial Time to live in seconds at the moment of token creation.
 	 * @param {object} options.data Data stored in token.
 	 */
 	constructor(
@@ -33,53 +79,51 @@ export class Ecwt {
 	) {
 		this.#ecwtFactory = ecwtFactory;
 
-		this.#token = token;
-		this.#snowflake = snowflake;
 		this.#ttl_initial = ttl_initial;
-		this.#data = Object.freeze(data);
-	}
 
-	get token() {
-		return this.#token;
+		assign(this, 'token', token);
+		assign(
+			this,
+			'id',
+			snowflake.toBase62(),
+		);
+		assign(this, 'snowflake', snowflake);
+		assign(
+			this,
+			'ts_expired',
+			this.#getTimestampExpired(),
+		);
+		assign(
+			this,
+			'data',
+			Object.freeze(data),
+		);
 	}
 
-	get id() {
-		return this.#snowflake.base62;
-	}
-
-	get snowflake() {
-		return this.#snowflake;
-	}
-
-	get ts_expired() {
+	#getTimestampExpired() {
 		if (this.#ttl_initial === null) {
-			return Number.POSITIVE_INFINITY;
+			return null;
 		}
 
-		return toSeconds(this.#snowflake.timestamp) + this.#ttl_initial;
+		return toSeconds(this.snowflake.timestamp) + this.#ttl_initial;
 	}
 
 	/**
-	 * Time to live in seconds.
-	 * @type {number}
-	 * @readonly
+	 * Actual time to live in seconds.
+	 * @returns {number | null} -
 	 */
-	get ttl() {
+	getTTL() {
 		if (this.#ttl_initial === null) {
-			return Number.POSITIVE_INFINITY;
+			return null;
 		}
 
-		return this.#ttl_initial - toSeconds(Date.now() - this.#snowflake.timestamp);
-	}
-
-	get data() {
-		return this.#data;
+		return this.#ttl_initial - toSeconds(Date.now() - this.snowflake.timestamp);
 	}
 
 	/* async */ revoke() {
 		return this.#ecwtFactory._revoke({
 			token_id: this.id,
-			ts_ms_created: this.#snowflake.timestamp,
+			ts_ms_created: this.snowflake.timestamp,
 			ttl_initial: this.#ttl_initial,
 		});
 	}