|
1 | | -# SignedAccess |
2 | | -[](https://github.com/JadsonLucena/SignedAccess.js/actions/workflows/github-code-scanning/codeql) |
3 | | -[](https://github.com/JadsonLucena/SignedAccess.js/actions?workflow=test) |
4 | | -[](https://coveralls.io/github/JadsonLucena/SignedAccess.js) |
5 | | -[](https://standardjs.com) |
6 | | -[](https://conventionalcommits.org) |
7 | | - |
8 | | -Sign and verify URLs and cookies to add a layer of protection to publicly accessible routes |
9 | | - |
10 | | -## Which is? |
11 | | -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. |
12 | | -The subscription ensures that the permissions for a particular resource are not modified or tampered with. |
13 | | - |
14 | | -## Features |
15 | | -- [x] Sign and verify URL and cookie |
16 | | -- [x] Freedom of choice in algorithm and encryption key |
17 | | -- [x] Access validity time |
18 | | -- [x] Possibility of using IP to prevent unauthorized access |
19 | | -- [x] Possibility to restrict which HTTP methods can be used in the request |
20 | | -- [x] Possibility to use nonce values to prevent replay attacks |
21 | | -- [x] Possibility to allow access to multiple URLs based on a common prefix |
22 | | - |
23 | | - |
24 | | -## Interfaces |
25 | | -```typescript |
26 | | -/** |
27 | | - * @constructor |
28 | | - * @throws {TypeError} Invalid key |
29 | | - * @throws {TypeError} Invalid algorithm |
30 | | - * @throws {TypeError|SyntaxError} Invalid ttl |
31 | | - * @throws {AggregateError} Invalid arguments |
32 | | - */ |
33 | | -SignedAccess( |
34 | | - key: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, // https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options |
35 | | - { |
36 | | - algorithm = 'sha512', |
37 | | - ttl = 86400 // Time to Live in seconds (Natural number) |
38 | | - }: { |
39 | | - algorithm?: string, // https://nodejs.org/api/crypto.html#cryptogethashes |
40 | | - ttl?: number // https://wikipedia.org/wiki/Time_to_live |
41 | | - } |
42 | | -) |
43 | | -``` |
44 | | - |
45 | | -```typescript |
46 | | -/** |
47 | | - * @throws {TypeError} Invalid algorithm |
48 | | - * @see https://nodejs.org/api/crypto.html#cryptogethashes |
49 | | - */ |
50 | | -set algorithm(param?: string = 'sha512') |
51 | | -get algorithm(): string |
52 | | - |
53 | | -/** |
54 | | - * @throws {TypeError} Invalid key |
55 | | - * @see https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options |
56 | | - */ |
57 | | -set key(param?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey) |
58 | | -get key(): string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey |
59 | | - |
60 | | -/** |
61 | | - * @throws {TypeError|SyntaxError} Invalid ttl |
62 | | - * @see https://wikipedia.org/wiki/Time_to_live |
63 | | - */ |
64 | | -set ttl(param?: number = 86400) |
65 | | -get ttl(): number |
66 | | -``` |
67 | | - |
68 | | -```typescript |
69 | | -/** |
70 | | - * @method |
71 | | - * @throws {TypeError} Invalid prefix |
72 | | - * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods |
73 | | - * @throws {TypeError} Invalid algorithm |
74 | | - * @throws {TypeError} Invalid key |
75 | | - * @throws {TypeError} Invalid nonce |
76 | | - * @throws {TypeError|SyntaxError} Invalid remoteAddress |
77 | | - * @throws {TypeError|SyntaxError} Invalid ttl |
78 | | - * @throws {AggregateError} Invalid arguments |
79 | | - */ |
80 | | -signCookie( |
81 | | - 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 #. |
82 | | - { |
83 | | - accessControlAllowMethods = '*', |
84 | | - algorithm = this.algorithm, |
85 | | - key = this.key, |
86 | | - nonce = '', |
87 | | - remoteAddress = '', |
88 | | - ttl = this.ttl |
89 | | - }: { |
90 | | - accessControlAllowMethods?: string, // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods |
91 | | - algorithm?: string, |
92 | | - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, |
93 | | - nonce?: string, // https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes |
94 | | - remoteAddress?: string, // https://developer.mozilla.org/en-US/docs/Glossary/IP_Address |
95 | | - ttl?: number |
96 | | - } |
97 | | -): string // Cookie signed |
98 | | - |
99 | | -/** |
100 | | - * @method |
101 | | - * @throws {TypeError} Invalid URL |
102 | | - * @throws {TypeError} Invalid cookie |
103 | | - * @throws {TypeError} Invalid algorithm |
104 | | - * @throws {TypeError} Invalid key |
105 | | - * @throws {TypeError} Invalid method |
106 | | - * @throws {TypeError|SyntaxError} Invalid remoteAddress |
107 | | - * @throws {AggregateError} Invalid arguments |
108 | | - * @throws {Error} method required |
109 | | - * @throws {Error} remoteAddress required |
110 | | - * @throws {AggregateError} Invalid cookie |
111 | | - */ |
112 | | -verifyCookie( |
113 | | - url: string, |
114 | | - cookie: string, |
115 | | - { |
116 | | - algorithm = this.algorithm, |
117 | | - key = this.key, |
118 | | - method = '', // will be required if it has been added to the signature |
119 | | - remoteAddress = '' // will be required if it has been added to the signature |
120 | | - }: { |
121 | | - algorithm?: string, |
122 | | - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, |
123 | | - method?: string, // https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods |
124 | | - remoteAddress?: string |
125 | | - } |
126 | | -): boolean |
127 | | - |
128 | | -/** |
129 | | - * @method |
130 | | - * @throws {TypeError} Invalid URL |
131 | | - * @throws {TypeError} Invalid algorithm |
132 | | - * @throws {TypeError|SyntaxError} Invalid accessControlAllowMethods |
133 | | - * @throws {TypeError} Invalid key |
134 | | - * @throws {TypeError} Invalid nonce |
135 | | - * @throws {TypeError|SyntaxError} Invalid pathname |
136 | | - * @throws {TypeError|SyntaxError} Invalid remoteAddress |
137 | | - * @throws {TypeError|SyntaxError} Invalid ttl |
138 | | - * @throws {AggregateError} Invalid arguments |
139 | | - */ |
140 | | -signURL( |
141 | | - url: string, |
142 | | - { |
143 | | - accessControlAllowMethods = '*', |
144 | | - algorithm = this.algorithm, |
145 | | - key = this.key, |
146 | | - nonce = '', |
147 | | - pathname = '', // Must be a valid path contained in the url |
148 | | - remoteAddress = '', |
149 | | - ttl = this.ttl |
150 | | - }: { |
151 | | - accessControlAllowMethods?: string, |
152 | | - algorithm?: string, |
153 | | - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, |
154 | | - nonce?: string, |
155 | | - pathname?: string, // https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname |
156 | | - remoteAddress?: string, |
157 | | - ttl?: number |
158 | | - } |
159 | | -): string // URL signed |
160 | | - |
161 | | -/** |
162 | | - * @method |
163 | | - * @throws {TypeError} Invalid URL |
164 | | - * @throws {TypeError} Invalid algorithm |
165 | | - * @throws {TypeError} Invalid key |
166 | | - * @throws {TypeError} Invalid method |
167 | | - * @throws {TypeError|SyntaxError} Invalid remoteAddress |
168 | | - * @throws {AggregateError} Invalid arguments |
169 | | - * @throws {Error} method required |
170 | | - * @throws {Error} remoteAddress required |
171 | | - * @throws {AggregateError} Invalid URL |
172 | | - */ |
173 | | -verifyURL( |
174 | | - url: string, |
175 | | - { |
176 | | - algorithm = this.algorithm, |
177 | | - key = this.key, |
178 | | - method = '', |
179 | | - remoteAddress = '' |
180 | | - }: { |
181 | | - algorithm?: string, |
182 | | - key?: string | ArrayBuffer | Buffer | TypedArray | DataView | KeyObject | CryptoKey, |
183 | | - method?: string, |
184 | | - remoteAddress?: string |
185 | | - } |
186 | | -): boolean |
187 | | -``` |
188 | | - |
189 | | -> It is recommended to end all pathnames with / unless you intentionally choose to end the pathname with a partial filename.\ |
190 | | -> The pathname /data grants access to at least two of the following URLs:\ |
191 | | -> example.com/database\ |
192 | | -> example.com/data/file1 |
193 | | -
|
194 | | -> 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. |
195 | | -
|
196 | | -> 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. |
197 | | -
|
198 | | -## Specifications |
199 | | -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) |
| 1 | +# SignedAccess |
| 2 | +[](https://github.com/JadsonLucena/SignedAccess.js/actions/workflows/github-code-scanning/codeql) |
| 3 | +[](https://github.com/JadsonLucena/SignedAccess.js/actions?workflow=test) |
| 4 | +[](https://coveralls.io/github/JadsonLucena/SignedAccess.js) |
| 5 | +[](https://standardjs.com) |
| 6 | +[](https://conventionalcommits.org) |
| 7 | + |
| 8 | +Sign and verify URLs and cookies to add a layer of protection to publicly accessible routes |
| 9 | + |
| 10 | +## Which is? |
| 11 | +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. |
| 12 | +The subscription ensures that the permissions for a particular resource are not modified or tampered with. |
| 13 | + |
| 14 | +## Features |
| 15 | +- [x] Sign and verify URL and cookie |
| 16 | +- [x] Freedom of choice in algorithm and encryption key |
| 17 | +- [x] Access validity time |
| 18 | +- [x] Possibility of using IP to prevent unauthorized access |
| 19 | +- [x] Possibility to restrict which HTTP methods can be used in the request |
| 20 | +- [x] Possibility to use nonce values to prevent replay attacks |
| 21 | +- [x] Possibility to allow access to multiple URLs based on a common prefix |
| 22 | + |
| 23 | + |
| 24 | +## Interfaces |
| 25 | +Although this is a javascript module, we use a typescript interface to maintain interoperability and better readability. See: [src/SignedAccess.d.ts](src/SignedAccess.d.ts) |
| 26 | + |
| 27 | + |
| 28 | +> It is recommended to end all pathnames with / unless you intentionally choose to end the pathname with a partial filename.\ |
| 29 | +> The pathname /data grants access to at least two of the following URLs:\ |
| 30 | +> example.com/database\ |
| 31 | +> example.com/data/file1 |
| 32 | +
|
| 33 | +> 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. |
| 34 | +
|
| 35 | +> 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. |
| 36 | +
|
| 37 | +## Specifications |
| 38 | +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](test/SignedAccess.spec.js) |
0 commit comments