From aed3641e4c7a51bd5984760932d00ef1dae0abf4 Mon Sep 17 00:00:00 2001 From: = Date: Tue, 4 Jun 2024 11:26:05 -0300 Subject: [PATCH] feat: interoperability with typescript --- README.md | 235 ++------- package.json | 27 +- src/SignedAccess.d.ts | 221 +++++++++ src/SignedAccess.js | 1058 ++++++++++++++++++++--------------------- 4 files changed, 807 insertions(+), 734 deletions(-) create mode 100644 src/SignedAccess.d.ts diff --git a/README.md b/README.md index 56f3ed3..c453e3a 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,38 @@ -# SignedAccess -[![CodeQL](https://github.com/JadsonLucena/SignedAccess.js/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/JadsonLucena/SignedAccess.js/actions/workflows/github-code-scanning/codeql) -[![Test](https://github.com/JadsonLucena/SignedAccess.js/workflows/test/badge.svg)](https://github.com/JadsonLucena/SignedAccess.js/actions?workflow=test) -[![Coverage](https://coveralls.io/repos/github/JadsonLucena/SignedAccess.js/badge.svg)](https://coveralls.io/github/JadsonLucena/SignedAccess.js) -[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) -[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) - -Sign and verify URLs and cookies to add a layer of protection to publicly accessible routes - -## Which is? -A signed URL or signed cookie provides limited time and permission for non-credentialed origins to perform a number of specific actions on one resource or several based on a common prefix. -The subscription ensures that the permissions for a particular resource are not modified or tampered with. - -## Features -- [x] Sign and verify URL and cookie -- [x] Freedom of choice in algorithm and encryption key -- [x] Access validity time -- [x] Possibility of using IP to prevent unauthorized access -- [x] Possibility to restrict which HTTP methods can be used in the request -- [x] Possibility to use nonce values to prevent replay attacks -- [x] Possibility to allow access to multiple URLs based on a common prefix - - -## Interfaces -```typescript -/** - * @constructor - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid algorithm - * @throws {TypeError|SyntaxError} Invalid ttl - * @throws {AggregateError} Invalid arguments - */ -SignedAccess( - key: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, // https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options - { - algorithm = 'sha512', - ttl = 86400 // Time to Live in seconds (Natural number) - }: { - algorithm?: string, // https://nodejs.org/api/crypto.html#cryptogethashes - ttl?: number // https://wikipedia.org/wiki/Time_to_live - } -) -``` - -```typescript -/** - * @throws {TypeError} Invalid algorithm - * @see https://nodejs.org/api/crypto.html#cryptogethashes - */ -set algorithm(param?: string = 'sha512') -get algorithm(): string - -/** - * @throws {TypeError} Invalid key - * @see https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options - */ -set key(param?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey) -get key(): string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey - -/** - * @throws {TypeError|SyntaxError} Invalid ttl - * @see https://wikipedia.org/wiki/Time_to_live - */ -set ttl(param?: number = 86400) -get ttl(): number -``` - -```typescript -/** - * @method - * @throws {TypeError} Invalid prefix - * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods - * @throws {TypeError} Invalid algorithm - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid nonce - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {TypeError|SyntaxError} Invalid ttl - * @throws {AggregateError} Invalid arguments - */ -signCookie( - prefix: string, // A prefix encodes a scheme (either http:// or https://), FQDN, and an optional path. Ending the path with a / is optional but recommended. The prefix shouldn't include query parameters or fragments such as ? or #. - { - accessControlAllowMethods = '*', - algorithm = this.algorithm, - key = this.key, - nonce = '', - remoteAddress = '', - ttl = this.ttl - }: { - accessControlAllowMethods?: string, // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods - algorithm?: string, - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, - nonce?: string, // https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes - remoteAddress?: string, // https://developer.mozilla.org/en-US/docs/Glossary/IP_Address - ttl?: number - } -): string // Cookie signed - -/** - * @method - * @throws {TypeError} Invalid URL - * @throws {TypeError} Invalid cookie - * @throws {TypeError} Invalid algorithm - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid method - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {AggregateError} Invalid arguments - * @throws {Error} method required - * @throws {Error} remoteAddress required - * @throws {AggregateError} Invalid cookie - */ -verifyCookie( - url: string, - cookie: string, - { - algorithm = this.algorithm, - key = this.key, - method = '', // will be required if it has been added to the signature - remoteAddress = '' // will be required if it has been added to the signature - }: { - algorithm?: string, - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, - method?: string, // https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods - remoteAddress?: string - } -): boolean - -/** - * @method - * @throws {TypeError} Invalid URL - * @throws {TypeError} Invalid algorithm - * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid nonce - * @throws {TypeError|SyntaxError} Invalid pathname - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {TypeError|SyntaxError} Invalid ttl - * @throws {AggregateError} Invalid arguments - */ -signURL( - url: string, - { - accessControlAllowMethods = '*', - algorithm = this.algorithm, - key = this.key, - nonce = '', - pathname = '', // Must be a valid path contained in the url - remoteAddress = '', - ttl = this.ttl - }: { - accessControlAllowMethods?: string, - algorithm?: string, - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, - nonce?: string, - pathname?: string, // https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname - remoteAddress?: string, - ttl?: number - } -): string // URL signed - -/** - * @method - * @throws {TypeError} Invalid URL - * @throws {TypeError} Invalid algorithm - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid method - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {AggregateError} Invalid arguments - * @throws {Error} method required - * @throws {Error} remoteAddress required - * @throws {AggregateError} Invalid URL - */ -verifyURL( - url: string, - { - algorithm = this.algorithm, - key = this.key, - method = '', - remoteAddress = '' - }: { - algorithm?: string, - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, - method?: string, - remoteAddress?: string - } -): boolean -``` - -> It is recommended to end all pathnames with / unless you intentionally choose to end the pathname with a partial filename.\ -> The pathname /data grants access to at least two of the following URLs:\ -> example.com/database\ -> example.com/data/file1 - -> The signURL method needs to save the information in the searchParams, so the "expires, ip, method, nonce, prefix and signature" queries are reserved for this module's control. If your original url has one of these queries previously, it will be removed or overwritten to avoid conflicts in the signature verification. - -> The nonce is signed in the cookie or URL, but it's up to your application to save them and check if they've already been used. - -## Specifications +# SignedAccess +[![CodeQL](https://github.com/JadsonLucena/SignedAccess.js/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/JadsonLucena/SignedAccess.js/actions/workflows/github-code-scanning/codeql) +[![Test](https://github.com/JadsonLucena/SignedAccess.js/workflows/test/badge.svg)](https://github.com/JadsonLucena/SignedAccess.js/actions?workflow=test) +[![Coverage](https://coveralls.io/repos/github/JadsonLucena/SignedAccess.js/badge.svg)](https://coveralls.io/github/JadsonLucena/SignedAccess.js) +[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) + +Sign and verify URLs and cookies to add a layer of protection to publicly accessible routes + +## Which is? +A signed URL or signed cookie provides limited time and permission for non-credentialed origins to perform a number of specific actions on one resource or several based on a common prefix. +The subscription ensures that the permissions for a particular resource are not modified or tampered with. + +## Features +- [x] Sign and verify URL and cookie +- [x] Freedom of choice in algorithm and encryption key +- [x] Access validity time +- [x] Possibility of using IP to prevent unauthorized access +- [x] Possibility to restrict which HTTP methods can be used in the request +- [x] Possibility to use nonce values to prevent replay attacks +- [x] Possibility to allow access to multiple URLs based on a common prefix + + +## Interfaces +Although this is a javascript module, we use a typescript interface to maintain interoperability and better readability. See: [src/SignedAccess.d.ts](https://github.com/JadsonLucena/SignedAccess.js/blob/main/src/SignedAccess.d.ts) + + +> It is recommended to end all pathnames with / unless you intentionally choose to end the pathname with a partial filename.\ +> The pathname /data grants access to at least two of the following URLs:\ +> example.com/database\ +> example.com/data/file1 + +> The signURL method needs to save the information in the searchParams, so the "expires, ip, method, nonce, prefix and signature" queries are reserved for this module's control. If your original url has one of these queries previously, it will be removed or overwritten to avoid conflicts in the signature verification. + +> The nonce is signed in the cookie or URL, but it's up to your application to save them and check if they've already been used. + +## Specifications We strive to maintain complete code coverage in tests. With that, we provide all the necessary use cases for a good understanding of how this module works. See: [test/SignedAccess.spec.js](https://github.com/JadsonLucena/SignedAccess.js/blob/main/test/SignedAccess.spec.js) \ No newline at end of file diff --git a/package.json b/package.json index fd9154f..c57585e 100644 --- a/package.json +++ b/package.json @@ -38,18 +38,27 @@ }, "homepage": "https://github.com/JadsonLucena/SignedAccess.js#readme", "devDependencies": { - "jest": "latest", + "@commitlint/cli": "latest", + "@commitlint/config-conventional": "latest", + "@types/node": "latest", "eslint": "latest", "eslint-config-standard": "latest", "eslint-plugin-jest": "latest", - "@commitlint/cli": "latest", - "@commitlint/config-conventional": "latest" + "jest": "latest" }, "jest": { "collectCoverage": true, "verbose": true, - "collectCoverageFrom": ["./src/*.js"], - "coverageReporters": ["clover", "json", "lcov", "text", "html"], + "collectCoverageFrom": [ + "./src/*.js" + ], + "coverageReporters": [ + "clover", + "json", + "lcov", + "text", + "html" + ], "coverageThreshold": { "global": { "branches": 100, @@ -60,13 +69,17 @@ } }, "eslintConfig": { - "plugins": ["jest"], + "plugins": [ + "jest" + ], "env": { "jest/globals": true }, "extends": "standard" }, "commitlint": { - "extends": ["@commitlint/config-conventional"] + "extends": [ + "@commitlint/config-conventional" + ] } } diff --git a/src/SignedAccess.d.ts b/src/SignedAccess.d.ts new file mode 100644 index 0000000..09614f4 --- /dev/null +++ b/src/SignedAccess.d.ts @@ -0,0 +1,221 @@ +import { KeyObject, webcrypto } from 'crypto' + +declare module '@jadsonlucena/signedaccess' { + export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array + export type Key = string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | webcrypto.CryptoKey + + /** + * @classdesc Sign and verify URLs and cookies to add a layer of protection to publicly accessible routes + */ + export default class SignedAccess { + + /** + * Create a Signed Access + * @param {Key} key - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {Object} [options] + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds (Natural number) + * + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid algorithm + * @throws {TypeError|SyntaxError} Invalid ttl + * @throws {AggregateError} Invalid arguments + */ + constructor( + key: Key, + { + algorithm, + ttl + }: { + algorithm?: string, + ttl?: number + } + ) + + /** + * @default 'sha512' + * + * @throws {TypeError} Invalid algorithm + * + * @see https://nodejs.org/api/crypto.html#cryptogethashes + */ + set algorithm(param: string) + get algorithm(): string + + /** + * @throws {TypeError} Invalid key + * + * @see https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options + */ + set key(param: Key) + get key(): Key + + /** + * Time to Live in seconds (Natural number) + * @default 86400 + * + * @throws {TypeError|SyntaxError} Invalid ttl + * + * @see https://wikipedia.org/wiki/Time_to_live + */ + set ttl(param: number) + get ttl(): number + + /** + * @param {string} prefix - A prefix encodes a scheme (either http:// or https://), {@link Fully_qualified_domain_name FQDN}, and an optional {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname path}. Ending the path with a / is optional but recommended. The prefix shouldn't include query parameters or fragments such as ? or # + * @param {Object} [options] + * @param {string} [options.accessControlAllowMethods=*] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods Access control allow methods} + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.nonce] - Use random {@link https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes Number Once} + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds (Natural number) + * + * @throws {TypeError} Invalid prefix + * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods + * @throws {TypeError} Invalid algorithm + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid nonce + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {TypeError|SyntaxError} Invalid ttl + * @throws {AggregateError} Invalid arguments + * + * @return {string} Signed cookie + */ + signCookie( + prefix: string, + { + accessControlAllowMethods, + algorithm, + key, + nonce, + remoteAddress, + ttl + }: { + accessControlAllowMethods?: string, + algorithm?: string, + key?: Key, + nonce?: string, + remoteAddress?: string, + ttl?: number + } + ): string + + /** + * @param {string} url - Requisition {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} + * @param {string} cookie - Signed {@link https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Cookies cookie} + * @param {Object} [options] + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.method] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods HTTP request methods} + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * + * @throws {TypeError} Invalid URL + * @throws {TypeError} Invalid cookie + * @throws {TypeError} Invalid algorithm + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid method + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {AggregateError} Invalid arguments + * @throws {Error} method required + * @throws {Error} remoteAddress required + * @throws {AggregateError} Invalid cookie + * + * @return {boolean} + */ + verifyCookie( + url: string, + cookie: string, + { + algorithm, + key, + method, + remoteAddress + }: { + algorithm?: string, + key?: Key, + method?: string, + remoteAddress?: string + } + ): boolean + + /** + * @param {string} url - {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} to be signed + * @param {Object} [options] + * @param {string} [options.accessControlAllowMethods=*] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods Access control allow methods} + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.nonce] - Use random {@link https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes Number Once} + * @param {string} [options.pathname] - Starts with / followed by the {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname URL path}, shouldn't include query parameters or fragments such as ? or # + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds (Natural number) + * + * @throws {TypeError} Invalid URL + * @throws {TypeError} Invalid algorithm + * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid nonce + * @throws {TypeError|SyntaxError} Invalid pathname + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {TypeError|SyntaxError} Invalid ttl + * @throws {AggregateError} Invalid arguments + * + * @return {string} Signed URL + */ + signURL( + url: string, + { + accessControlAllowMethods, + algorithm, + key, + nonce, + pathname, + remoteAddress, + ttl + }: { + accessControlAllowMethods?: string, + algorithm?: string, + key?: Key, + nonce?: string, + pathname?: string, + remoteAddress?: string, + ttl?: number + } + ): string + + /** + * @param {string} url - Signed {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} + * @param {Object} [options] + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.method] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods HTTP request methods} + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * + * @throws {TypeError} Invalid URL + * @throws {TypeError} Invalid algorithm + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid method + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {AggregateError} Invalid arguments + * @throws {Error} method required + * @throws {Error} remoteAddress required + * @throws {AggregateError} Invalid URL + * + * @return {boolean} + */ + verifyURL( + url: string, + { + algorithm, + key, + method, + remoteAddress + }: { + algorithm?: string, + key?: Key, + method?: string, + remoteAddress?: string + } + ): boolean + } +} \ No newline at end of file diff --git a/src/SignedAccess.js b/src/SignedAccess.js index ed74c3d..2830f42 100644 --- a/src/SignedAccess.js +++ b/src/SignedAccess.js @@ -1,529 +1,529 @@ -'use strict' - -const crypto = require('node:crypto') -const net = require('node:net') - -/** - * @class - * @classdesc Sign and verify URLs and cookies to add a layer of protection to publicly accessible routes - * - * @typedef {(Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array|BigInt64Array|BigUint64Array)} TypedArray - * @typedef {(string|ArrayBuffer|TypedArray|DataView|Buffer|KeyObject|CryptoKey)} Key - */ -class SignedAccess { - #key - #algorithm - #ttl - - #HTTPMethods - - /** - * Create a Signed Access - * @constructor - * @param {Key} key - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} - * @param {Object} [options] - * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} - * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds - * - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid algorithm - * @throws {TypeError|SyntaxError} Invalid ttl - * @throws {AggregateError} Invalid arguments - */ - constructor (key, { - algorithm, - ttl - } = {}) { - const errors = [] - - try { - this.key = key - } catch (err) { - errors.push(err) - } - - try { - this.algorithm = algorithm - } catch (err) { - errors.push(err) - } - - try { - this.ttl = ttl - } catch (err) { - errors.push(err) - } - - if (errors.length > 1) { - throw new AggregateError(errors, 'Invalid arguments') - } else if (errors.length === 1) { - throw errors.pop() - } - - this.#HTTPMethods = ['CONNECT', 'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT', 'TRACE'] - } - - /** - * @type {string} - * @default 'sha512' - * - * @throws {TypeError} Invalid algorithm - * - * @see https://nodejs.org/api/crypto.html#cryptogethashes - */ - set algorithm ( - algorithm = 'sha512' // https://nodejs.org/api/crypto.html#cryptogethashes - ) { - if (typeof algorithm !== 'string' || !crypto.getHashes().includes(algorithm.trim())) { - throw new TypeError('Invalid algorithm') - } - - this.#algorithm = algorithm - } - - /** - * @return {string} - */ - get algorithm () { return this.#algorithm } - - /** - * @type {Key} - * - * @throws {TypeError} Invalid key - * - * @see https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options - */ - set key (key) { - try { - crypto.createHmac('sha1', key) - } catch (err) { - throw new TypeError('Invalid key') - } - - this.#key = key - } - - /** - * @return {Key} - */ - get key () { return this.#key } - - /** - * Time to Live in seconds - * @type {number} - * @default 86400 - * - * @throws {TypeError|SyntaxError} Invalid ttl - * - * @see https://wikipedia.org/wiki/Time_to_live - */ - set ttl ( - ttl = 86400 // Seconds - ) { - if (!Number.isSafeInteger(ttl)) { - throw new TypeError('Invalid ttl') - } else if (ttl < 1) { - throw new SyntaxError('Invalid ttl') - } - - this.#ttl = ttl - } - - /** - * @return {number} - */ - get ttl () { return this.#ttl } - - #encodePrefix (prefix) { - prefix = new URL(prefix) - - // The prefix shouldn't include query parameters or fragments such as ? or # - return Buffer.from(decodeURIComponent(prefix.origin + prefix.pathname), 'ascii').toString('base64url') - } - - #decodePrefix (prefix) { - // https://www.w3schools.com/tags/ref_urlencode.asp - // https://datatracker.ietf.org/doc/html/rfc4648#section-5 - return Buffer.from(prefix, 'base64url').toString('ascii') - } - - #timestamp (ttl) { - return Date.now() + parseInt(ttl) * 1000 - } - - #toSign ( - input, - key, - algorithm - ) { - if (typeof algorithm !== 'string' || !crypto.getHashes().includes(algorithm.trim())) { - throw new TypeError('Invalid algorithm') - } - - try { - return crypto.createHmac(algorithm.trim(), key).update(decodeURIComponent(input)).digest('base64url') - } catch (err) { - throw new TypeError('Invalid key') - } - } - - /** - * @method - * @param {string} url - {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} to be signed - * @param {Object} [options] - * @param {string} [options.accessControlAllowMethods=*] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods Access control allow methods} - * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} - * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} - * @param {string} [options.nonce] - Use random {@link https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes Number Once} - * @param {string} [options.pathname] - Starts with / followed by the {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname URL path}, shouldn't include query parameters or fragments such as ? or # - * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} - * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds - * - * @throws {TypeError} Invalid URL - * @throws {TypeError} Invalid algorithm - * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid nonce - * @throws {TypeError|SyntaxError} Invalid pathname - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {TypeError|SyntaxError} Invalid ttl - * @throws {AggregateError} Invalid arguments - * - * @return {string} Signed URL - */ - signURL ( - url, - { - accessControlAllowMethods = '*', - algorithm = this.#algorithm, - key = this.#key, - nonce = '', - pathname = '', - remoteAddress = '', - ttl = this.#ttl - } = {} - ) { - const errors = [] - - try { - url = new URL(url) - } catch (err) { - errors.push(new TypeError('Invalid URL')) - } - - if (typeof accessControlAllowMethods !== 'string') { - errors.push(new TypeError('Invalid accessControlAllowMethods')) - } else if (!new RegExp(`^\\s*(\\*|(${this.#HTTPMethods.join('|')})(\\s*,\\s*(${this.#HTTPMethods.join('|')}))*)\\s*$`, 'i').test(accessControlAllowMethods)) { - errors.push(new SyntaxError('Invalid accessControlAllowMethods')) - } - if (typeof nonce !== 'string') { - errors.push(new TypeError('Invalid nonce')) - } - if (typeof pathname !== 'string') { - errors.push(new TypeError('Invalid pathname')) - } else if (pathname && !decodeURIComponent(url.pathname).startsWith(pathname)) { - errors.push(new SyntaxError('Invalid pathname')) - } - if (typeof remoteAddress !== 'string') { - errors.push(new TypeError('Invalid remoteAddress')) - } else if (remoteAddress && net.isIP(remoteAddress) === 0) { - errors.push(new SyntaxError('Invalid remoteAddress')) - } - if (!Number.isSafeInteger(ttl)) { - errors.push(new TypeError('Invalid ttl')) - } else if (ttl < 1) { - errors.push(new SyntaxError('Invalid ttl')) - } - - if (errors.length > 1) { - throw new AggregateError(errors, 'Invalid arguments') - } else if (errors.length === 1) { - throw errors.pop() - } - - url.searchParams.delete('expires') - url.searchParams.delete('ip') - url.searchParams.delete('method') - url.searchParams.delete('nonce') - url.searchParams.delete('prefix') - url.searchParams.delete('signature') - - const searchParams = new URLSearchParams() - - searchParams.set('expires', this.#timestamp(ttl)) - if (remoteAddress.trim()) searchParams.set('ip', remoteAddress.trim()) - if (accessControlAllowMethods.trim() && accessControlAllowMethods.trim() !== '*') [...new Set(accessControlAllowMethods.split(',').map(method => method.trim().toUpperCase()))].forEach(method => searchParams.append('method', method)) - if (nonce.trim()) searchParams.set('nonce', nonce.trim()) - if (pathname.trim()) searchParams.set('prefix', this.#encodePrefix(new URL(pathname.trim(), url.origin).href)) - - for (const pair of searchParams.entries()) { - url.searchParams.append(pair[0], pair[1]) - } - - url.searchParams.set('signature', this.#toSign(searchParams.has('prefix') ? searchParams.toString() : url.href, key, algorithm)) - - return decodeURIComponent(url.href) - } - - /** - * @method - * @param {string} url - Signed {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} - * @param {Object} [options] - * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} - * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} - * @param {string} [options.method] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods HTTP request methods} - * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} - * - * @throws {TypeError} Invalid URL - * @throws {TypeError} Invalid algorithm - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid method - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {AggregateError} Invalid arguments - * @throws {Error} method required - * @throws {Error} remoteAddress required - * @throws {AggregateError} Invalid URL - * - * @return {boolean} - */ - verifyURL ( - url, - { - algorithm = this.#algorithm, - key = this.#key, - method = '', - remoteAddress = '' - } = {} - ) { - const errors = [] - - try { - url = new URL(url) - } catch (err) { - errors.push(new TypeError('Invalid URL')) - } - - if (typeof method !== 'string' || !['', ...this.#HTTPMethods].includes(method.trim().toUpperCase())) { - errors.push(new TypeError('Invalid method')) - } - if (typeof remoteAddress !== 'string') { - errors.push(new TypeError('Invalid remoteAddress')) - } else if (remoteAddress && net.isIP(remoteAddress) === 0) { - errors.push(new SyntaxError('Invalid remoteAddress')) - } - - if (errors.length > 1) { - throw new AggregateError(errors, 'Invalid arguments') - } else if (errors.length === 1) { - throw errors.pop() - } - - if (url.searchParams.has('method') && !method.trim()) { - errors.push(new Error('method required')) - } - if (url.searchParams.has('ip') && !remoteAddress.trim()) { - errors.push(new Error('remoteAddress required')) - } - - if (errors.length > 1) { - throw new AggregateError(errors, 'Invalid URL') - } else if (errors.length === 1) { - throw errors.pop() - } - - const signature = url.searchParams.get('signature') - - url.searchParams.delete('signature') - - if (url.searchParams.has('prefix')) { - const searchParams = new URLSearchParams() - - // get the parameters keeping the order - for (const pair of url.searchParams.entries()) { - if (['expires', 'ip', 'method', 'nonce', 'prefix'].includes(pair[0])) { - searchParams.append(pair[0], pair[1]) - } - } - - return ( - signature === this.#toSign(searchParams.toString(), key, algorithm) && - Date.now() < url.searchParams.get('expires') && - (url.searchParams.has('ip') ? url.searchParams.get('ip') === remoteAddress.trim() : true) && - (url.searchParams.has('method') ? url.searchParams.getAll('method').includes(method.trim().toUpperCase()) : true) && - decodeURIComponent(url.href).startsWith(this.#decodePrefix(url.searchParams.get('prefix'))) - ) - } else { - return ( - signature === this.#toSign(url.href, key, algorithm) && - Date.now() < url.searchParams.get('expires') && - (url.searchParams.has('ip') ? url.searchParams.get('ip') === remoteAddress.trim() : true) && - (url.searchParams.has('method') ? url.searchParams.getAll('method').includes(method.trim().toUpperCase()) : true) - ) - } - } - - /** - * @method - * @param {string} prefix - A prefix encodes a scheme (either http:// or https://), {@link Fully_qualified_domain_name FQDN}, and an optional {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname path}. Ending the path with a / is optional but recommended. The prefix shouldn't include query parameters or fragments such as ? or # - * @param {Object} [options] - * @param {string} [options.accessControlAllowMethods=*] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods Access control allow methods} - * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} - * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} - * @param {string} [options.nonce] - Use random {@link https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes Number Once} - * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} - * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds - * - * @throws {TypeError} Invalid prefix - * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods - * @throws {TypeError} Invalid algorithm - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid nonce - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {TypeError|SyntaxError} Invalid ttl - * @throws {AggregateError} Invalid arguments - * - * @return {string} Signed cookie - */ - signCookie ( - prefix, - { - accessControlAllowMethods = '*', - algorithm = this.#algorithm, - key = this.#key, - nonce = '', - remoteAddress = '', - ttl = this.#ttl - } = {} - ) { - const errors = [] - - if (typeof prefix !== 'string') { - errors.push(new TypeError('Invalid prefix')) - } - if (typeof accessControlAllowMethods !== 'string') { - errors.push(new TypeError('Invalid accessControlAllowMethods')) - } else if (!new RegExp(`^\\s*(\\*|(${this.#HTTPMethods.join('|')})(\\s*,\\s*(${this.#HTTPMethods.join('|')}))*)\\s*$`, 'i').test(accessControlAllowMethods)) { - errors.push(new SyntaxError('Invalid accessControlAllowMethods')) - } - if (typeof nonce !== 'string') { - errors.push(new TypeError('Invalid nonce')) - } - if (typeof remoteAddress !== 'string') { - errors.push(new TypeError('Invalid remoteAddress')) - } else if (remoteAddress && net.isIP(remoteAddress) === 0) { - errors.push(new SyntaxError('Invalid remoteAddress')) - } - if (!Number.isSafeInteger(ttl)) { - errors.push(new TypeError('Invalid ttl')) - } else if (ttl < 1) { - errors.push(new SyntaxError('Invalid ttl')) - } - - if (errors.length > 1) { - throw new AggregateError(errors, 'Invalid arguments') - } else if (errors.length === 1) { - throw errors.pop() - } - - const cookie = new URLSearchParams() - - cookie.set('expires', this.#timestamp(ttl)) - if (remoteAddress.trim()) cookie.set('ip', remoteAddress.trim()) - if (accessControlAllowMethods.trim() && accessControlAllowMethods.trim() !== '*') [...new Set(accessControlAllowMethods.split(',').map(method => method.trim().toUpperCase()))].forEach(method => cookie.append('method', method)) - if (nonce.trim()) cookie.set('nonce', nonce.trim()) - cookie.set('prefix', this.#encodePrefix(prefix.trim())) - - cookie.set('signature', this.#toSign(cookie.toString(), key, algorithm)) - - return cookie.toString() - } - - /** - * @method - * @param {string} url - Requisition {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} - * @param {string} cookie - Signed {@link https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Cookies cookie} - * @param {Object} [options] - * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} - * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} - * @param {string} [options.method] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods HTTP request methods} - * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} - * - * @throws {TypeError} Invalid URL - * @throws {TypeError} Invalid cookie - * @throws {TypeError} Invalid algorithm - * @throws {TypeError} Invalid key - * @throws {TypeError} Invalid method - * @throws {TypeError|SyntaxError} Invalid remoteAddress - * @throws {AggregateError} Invalid arguments - * @throws {Error} method required - * @throws {Error} remoteAddress required - * @throws {AggregateError} Invalid cookie - * - * @return {boolean} - */ - verifyCookie ( - url, - cookie, - { - algorithm = this.#algorithm, - key = this.#key, - method = '', - remoteAddress = '' - } = {} - ) { - const errors = [] - - try { - url = new URL(url) - } catch (err) { - errors.push(new TypeError('Invalid URL')) - } - - cookie = new URLSearchParams(cookie) - - if (!cookie.has('prefix') || !cookie.has('expires') || !cookie.has('signature')) { - errors.push(new TypeError('Invalid cookie')) - } - if (typeof method !== 'string' || !['', ...this.#HTTPMethods].includes(method.trim().toUpperCase())) { - errors.push(new TypeError('Invalid method')) - } - if (typeof remoteAddress !== 'string') { - errors.push(new TypeError('Invalid remoteAddress')) - } else if (remoteAddress && net.isIP(remoteAddress) === 0) { - errors.push(new SyntaxError('Invalid remoteAddress')) - } - - if (errors.length > 1) { - throw new AggregateError(errors, 'Invalid arguments') - } else if (errors.length === 1) { - throw errors.pop() - } - - if (cookie.has('method') && !method.trim()) { - errors.push(new Error('method required')) - } - if (cookie.has('ip') && !remoteAddress.trim()) { - errors.push(new Error('remoteAddress required')) - } - - if (errors.length > 1) { - throw new AggregateError(errors, 'Invalid cookie') - } else if (errors.length === 1) { - throw errors.pop() - } - - const signature = cookie.get('signature') - - cookie.delete('signature') - - return ( - signature === this.#toSign(cookie.toString(), key, algorithm) && - Date.now() < cookie.get('expires') && - (cookie.has('ip') ? cookie.get('ip') === remoteAddress.trim() : true) && - (cookie.has('method') ? cookie.getAll('method').includes(method.trim().toUpperCase()) : true) && - decodeURIComponent(url.href).startsWith(this.#decodePrefix(cookie.get('prefix'))) - ) - } -} - -module.exports = SignedAccess +'use strict' + +const crypto = require('node:crypto') +const net = require('node:net') + +/** + * @class + * @classdesc Sign and verify URLs and cookies to add a layer of protection to publicly accessible routes + * + * @typedef {(Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array|BigInt64Array|BigUint64Array)} TypedArray + * @typedef {(string|ArrayBuffer|TypedArray|DataView|Buffer|KeyObject|CryptoKey)} Key + */ +class SignedAccess { + #key + #algorithm + #ttl + + #HTTPMethods + + /** + * Create a Signed Access + * @constructor + * @param {Key} key - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {Object} [options] + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds (Natural number) + * + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid algorithm + * @throws {TypeError|SyntaxError} Invalid ttl + * @throws {AggregateError} Invalid arguments + */ + constructor (key, { + algorithm, + ttl + } = {}) { + const errors = [] + + try { + this.key = key + } catch (err) { + errors.push(err) + } + + try { + this.algorithm = algorithm + } catch (err) { + errors.push(err) + } + + try { + this.ttl = ttl + } catch (err) { + errors.push(err) + } + + if (errors.length > 1) { + throw new AggregateError(errors, 'Invalid arguments') + } else if (errors.length === 1) { + throw errors.pop() + } + + this.#HTTPMethods = ['CONNECT', 'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT', 'TRACE'] + } + + /** + * @type {string} + * @default 'sha512' + * + * @throws {TypeError} Invalid algorithm + * + * @see https://nodejs.org/api/crypto.html#cryptogethashes + */ + set algorithm ( + algorithm = 'sha512' // https://nodejs.org/api/crypto.html#cryptogethashes + ) { + if (typeof algorithm !== 'string' || !crypto.getHashes().includes(algorithm.trim())) { + throw new TypeError('Invalid algorithm') + } + + this.#algorithm = algorithm + } + + /** + * @return {string} + */ + get algorithm () { return this.#algorithm } + + /** + * @type {Key} + * + * @throws {TypeError} Invalid key + * + * @see https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options + */ + set key (key) { + try { + crypto.createHmac('sha1', key) + } catch (err) { + throw new TypeError('Invalid key') + } + + this.#key = key + } + + /** + * @return {Key} + */ + get key () { return this.#key } + + /** + * Time to Live in seconds (Natural number) + * @type {number} + * @default 86400 + * + * @throws {TypeError|SyntaxError} Invalid ttl + * + * @see https://wikipedia.org/wiki/Time_to_live + */ + set ttl ( + ttl = 86400 // Seconds + ) { + if (!Number.isSafeInteger(ttl)) { + throw new TypeError('Invalid ttl') + } else if (ttl < 1) { + throw new SyntaxError('Invalid ttl') + } + + this.#ttl = ttl + } + + /** + * @return {number} + */ + get ttl () { return this.#ttl } + + #encodePrefix (prefix) { + prefix = new URL(prefix) + + // The prefix shouldn't include query parameters or fragments such as ? or # + return Buffer.from(decodeURIComponent(prefix.origin + prefix.pathname), 'ascii').toString('base64url') + } + + #decodePrefix (prefix) { + // https://www.w3schools.com/tags/ref_urlencode.asp + // https://datatracker.ietf.org/doc/html/rfc4648#section-5 + return Buffer.from(prefix, 'base64url').toString('ascii') + } + + #timestamp (ttl) { + return Date.now() + parseInt(ttl) * 1000 + } + + #toSign ( + input, + key, + algorithm + ) { + if (typeof algorithm !== 'string' || !crypto.getHashes().includes(algorithm.trim())) { + throw new TypeError('Invalid algorithm') + } + + try { + return crypto.createHmac(algorithm.trim(), key).update(decodeURIComponent(input)).digest('base64url') + } catch (err) { + throw new TypeError('Invalid key') + } + } + + /** + * @method + * @param {string} url - {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} to be signed + * @param {Object} [options] + * @param {string} [options.accessControlAllowMethods=*] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods Access control allow methods} + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.nonce] - Use random {@link https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes Number Once} + * @param {string} [options.pathname] - Starts with / followed by the {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname URL path}, shouldn't include query parameters or fragments such as ? or # + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds (Natural number) + * + * @throws {TypeError} Invalid URL + * @throws {TypeError} Invalid algorithm + * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid nonce + * @throws {TypeError|SyntaxError} Invalid pathname + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {TypeError|SyntaxError} Invalid ttl + * @throws {AggregateError} Invalid arguments + * + * @return {string} Signed URL + */ + signURL ( + url, + { + accessControlAllowMethods = '*', + algorithm = this.#algorithm, + key = this.#key, + nonce = '', + pathname = '', + remoteAddress = '', + ttl = this.#ttl + } = {} + ) { + const errors = [] + + try { + url = new URL(url) + } catch (err) { + errors.push(new TypeError('Invalid URL')) + } + + if (typeof accessControlAllowMethods !== 'string') { + errors.push(new TypeError('Invalid accessControlAllowMethods')) + } else if (!new RegExp(`^\\s*(\\*|(${this.#HTTPMethods.join('|')})(\\s*,\\s*(${this.#HTTPMethods.join('|')}))*)\\s*$`, 'i').test(accessControlAllowMethods)) { + errors.push(new SyntaxError('Invalid accessControlAllowMethods')) + } + if (typeof nonce !== 'string') { + errors.push(new TypeError('Invalid nonce')) + } + if (typeof pathname !== 'string') { + errors.push(new TypeError('Invalid pathname')) + } else if (pathname && !decodeURIComponent(url.pathname).startsWith(pathname)) { + errors.push(new SyntaxError('Invalid pathname')) + } + if (typeof remoteAddress !== 'string') { + errors.push(new TypeError('Invalid remoteAddress')) + } else if (remoteAddress && net.isIP(remoteAddress) === 0) { + errors.push(new SyntaxError('Invalid remoteAddress')) + } + if (!Number.isSafeInteger(ttl)) { + errors.push(new TypeError('Invalid ttl')) + } else if (ttl < 1) { + errors.push(new SyntaxError('Invalid ttl')) + } + + if (errors.length > 1) { + throw new AggregateError(errors, 'Invalid arguments') + } else if (errors.length === 1) { + throw errors.pop() + } + + url.searchParams.delete('expires') + url.searchParams.delete('ip') + url.searchParams.delete('method') + url.searchParams.delete('nonce') + url.searchParams.delete('prefix') + url.searchParams.delete('signature') + + const searchParams = new URLSearchParams() + + searchParams.set('expires', this.#timestamp(ttl)) + if (remoteAddress.trim()) searchParams.set('ip', remoteAddress.trim()) + if (accessControlAllowMethods.trim() && accessControlAllowMethods.trim() !== '*') [...new Set(accessControlAllowMethods.split(',').map(method => method.trim().toUpperCase()))].forEach(method => searchParams.append('method', method)) + if (nonce.trim()) searchParams.set('nonce', nonce.trim()) + if (pathname.trim()) searchParams.set('prefix', this.#encodePrefix(new URL(pathname.trim(), url.origin).href)) + + for (const pair of searchParams.entries()) { + url.searchParams.append(pair[0], pair[1]) + } + + url.searchParams.set('signature', this.#toSign(searchParams.has('prefix') ? searchParams.toString() : url.href, key, algorithm)) + + return decodeURIComponent(url.href) + } + + /** + * @method + * @param {string} url - Signed {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} + * @param {Object} [options] + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.method] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods HTTP request methods} + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * + * @throws {TypeError} Invalid URL + * @throws {TypeError} Invalid algorithm + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid method + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {AggregateError} Invalid arguments + * @throws {Error} method required + * @throws {Error} remoteAddress required + * @throws {AggregateError} Invalid URL + * + * @return {boolean} + */ + verifyURL ( + url, + { + algorithm = this.#algorithm, + key = this.#key, + method = '', + remoteAddress = '' + } = {} + ) { + const errors = [] + + try { + url = new URL(url) + } catch (err) { + errors.push(new TypeError('Invalid URL')) + } + + if (typeof method !== 'string' || !['', ...this.#HTTPMethods].includes(method.trim().toUpperCase())) { + errors.push(new TypeError('Invalid method')) + } + if (typeof remoteAddress !== 'string') { + errors.push(new TypeError('Invalid remoteAddress')) + } else if (remoteAddress && net.isIP(remoteAddress) === 0) { + errors.push(new SyntaxError('Invalid remoteAddress')) + } + + if (errors.length > 1) { + throw new AggregateError(errors, 'Invalid arguments') + } else if (errors.length === 1) { + throw errors.pop() + } + + if (url.searchParams.has('method') && !method.trim()) { + errors.push(new Error('method required')) + } + if (url.searchParams.has('ip') && !remoteAddress.trim()) { + errors.push(new Error('remoteAddress required')) + } + + if (errors.length > 1) { + throw new AggregateError(errors, 'Invalid URL') + } else if (errors.length === 1) { + throw errors.pop() + } + + const signature = url.searchParams.get('signature') + + url.searchParams.delete('signature') + + if (url.searchParams.has('prefix')) { + const searchParams = new URLSearchParams() + + // get the parameters keeping the order + for (const pair of url.searchParams.entries()) { + if (['expires', 'ip', 'method', 'nonce', 'prefix'].includes(pair[0])) { + searchParams.append(pair[0], pair[1]) + } + } + + return ( + signature === this.#toSign(searchParams.toString(), key, algorithm) && + Date.now() < url.searchParams.get('expires') && + (url.searchParams.has('ip') ? url.searchParams.get('ip') === remoteAddress.trim() : true) && + (url.searchParams.has('method') ? url.searchParams.getAll('method').includes(method.trim().toUpperCase()) : true) && + decodeURIComponent(url.href).startsWith(this.#decodePrefix(url.searchParams.get('prefix'))) + ) + } else { + return ( + signature === this.#toSign(url.href, key, algorithm) && + Date.now() < url.searchParams.get('expires') && + (url.searchParams.has('ip') ? url.searchParams.get('ip') === remoteAddress.trim() : true) && + (url.searchParams.has('method') ? url.searchParams.getAll('method').includes(method.trim().toUpperCase()) : true) + ) + } + } + + /** + * @method + * @param {string} prefix - A prefix encodes a scheme (either http:// or https://), {@link Fully_qualified_domain_name FQDN}, and an optional {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname path}. Ending the path with a / is optional but recommended. The prefix shouldn't include query parameters or fragments such as ? or # + * @param {Object} [options] + * @param {string} [options.accessControlAllowMethods=*] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods Access control allow methods} + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.nonce] - Use random {@link https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes Number Once} + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * @param {number} [options.ttl=86400] - {@link https://wikipedia.org/wiki/Time_to_live Time to Live} in seconds (Natural number) + * + * @throws {TypeError} Invalid prefix + * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods + * @throws {TypeError} Invalid algorithm + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid nonce + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {TypeError|SyntaxError} Invalid ttl + * @throws {AggregateError} Invalid arguments + * + * @return {string} Signed cookie + */ + signCookie ( + prefix, + { + accessControlAllowMethods = '*', + algorithm = this.#algorithm, + key = this.#key, + nonce = '', + remoteAddress = '', + ttl = this.#ttl + } = {} + ) { + const errors = [] + + if (typeof prefix !== 'string') { + errors.push(new TypeError('Invalid prefix')) + } + if (typeof accessControlAllowMethods !== 'string') { + errors.push(new TypeError('Invalid accessControlAllowMethods')) + } else if (!new RegExp(`^\\s*(\\*|(${this.#HTTPMethods.join('|')})(\\s*,\\s*(${this.#HTTPMethods.join('|')}))*)\\s*$`, 'i').test(accessControlAllowMethods)) { + errors.push(new SyntaxError('Invalid accessControlAllowMethods')) + } + if (typeof nonce !== 'string') { + errors.push(new TypeError('Invalid nonce')) + } + if (typeof remoteAddress !== 'string') { + errors.push(new TypeError('Invalid remoteAddress')) + } else if (remoteAddress && net.isIP(remoteAddress) === 0) { + errors.push(new SyntaxError('Invalid remoteAddress')) + } + if (!Number.isSafeInteger(ttl)) { + errors.push(new TypeError('Invalid ttl')) + } else if (ttl < 1) { + errors.push(new SyntaxError('Invalid ttl')) + } + + if (errors.length > 1) { + throw new AggregateError(errors, 'Invalid arguments') + } else if (errors.length === 1) { + throw errors.pop() + } + + const cookie = new URLSearchParams() + + cookie.set('expires', this.#timestamp(ttl)) + if (remoteAddress.trim()) cookie.set('ip', remoteAddress.trim()) + if (accessControlAllowMethods.trim() && accessControlAllowMethods.trim() !== '*') [...new Set(accessControlAllowMethods.split(',').map(method => method.trim().toUpperCase()))].forEach(method => cookie.append('method', method)) + if (nonce.trim()) cookie.set('nonce', nonce.trim()) + cookie.set('prefix', this.#encodePrefix(prefix.trim())) + + cookie.set('signature', this.#toSign(cookie.toString(), key, algorithm)) + + return cookie.toString() + } + + /** + * @method + * @param {string} url - Requisition {@link https://nodejs.org/api/url.html#url-strings-and-url-objects URL} + * @param {string} cookie - Signed {@link https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Cookies cookie} + * @param {Object} [options] + * @param {string} [options.algorithm=sha512] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptogethashes hash algorithms} + * @param {Key} [options.key] - One of the supported {@link https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options key types} + * @param {string} [options.method] - {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods HTTP request methods} + * @param {string} [options.remoteAddress] - {@link https://developer.mozilla.org/en-US/docs/Glossary/IP_Address Client IP} + * + * @throws {TypeError} Invalid URL + * @throws {TypeError} Invalid cookie + * @throws {TypeError} Invalid algorithm + * @throws {TypeError} Invalid key + * @throws {TypeError} Invalid method + * @throws {TypeError|SyntaxError} Invalid remoteAddress + * @throws {AggregateError} Invalid arguments + * @throws {Error} method required + * @throws {Error} remoteAddress required + * @throws {AggregateError} Invalid cookie + * + * @return {boolean} + */ + verifyCookie ( + url, + cookie, + { + algorithm = this.#algorithm, + key = this.#key, + method = '', + remoteAddress = '' + } = {} + ) { + const errors = [] + + try { + url = new URL(url) + } catch (err) { + errors.push(new TypeError('Invalid URL')) + } + + cookie = new URLSearchParams(cookie) + + if (!cookie.has('prefix') || !cookie.has('expires') || !cookie.has('signature')) { + errors.push(new TypeError('Invalid cookie')) + } + if (typeof method !== 'string' || !['', ...this.#HTTPMethods].includes(method.trim().toUpperCase())) { + errors.push(new TypeError('Invalid method')) + } + if (typeof remoteAddress !== 'string') { + errors.push(new TypeError('Invalid remoteAddress')) + } else if (remoteAddress && net.isIP(remoteAddress) === 0) { + errors.push(new SyntaxError('Invalid remoteAddress')) + } + + if (errors.length > 1) { + throw new AggregateError(errors, 'Invalid arguments') + } else if (errors.length === 1) { + throw errors.pop() + } + + if (cookie.has('method') && !method.trim()) { + errors.push(new Error('method required')) + } + if (cookie.has('ip') && !remoteAddress.trim()) { + errors.push(new Error('remoteAddress required')) + } + + if (errors.length > 1) { + throw new AggregateError(errors, 'Invalid cookie') + } else if (errors.length === 1) { + throw errors.pop() + } + + const signature = cookie.get('signature') + + cookie.delete('signature') + + return ( + signature === this.#toSign(cookie.toString(), key, algorithm) && + Date.now() < cookie.get('expires') && + (cookie.has('ip') ? cookie.get('ip') === remoteAddress.trim() : true) && + (cookie.has('method') ? cookie.getAll('method').includes(method.trim().toUpperCase()) : true) && + decodeURIComponent(url.href).startsWith(this.#decodePrefix(cookie.get('prefix'))) + ) + } +} + +module.exports = SignedAccess