@ix-xs/node-comfort 1.2.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +340 -0
- package/README.md +137 -548
- package/index.js +80 -35
- package/package.json +161 -33
- package/src/Arr.js +1050 -418
- package/src/Async.js +817 -0
- package/src/Cache.js +433 -0
- package/src/Checker.js +1202 -539
- package/src/Cli.js +1293 -0
- package/src/Color.js +556 -0
- package/src/Crypto.js +1082 -0
- package/src/Emitter.js +356 -0
- package/src/Env.js +689 -0
- package/src/FS.js +1626 -894
- package/src/Func.js +823 -356
- package/src/Http.js +700 -0
- package/src/Id.js +568 -200
- package/src/Logger.js +963 -378
- package/src/Num.js +965 -360
- package/src/Obj.js +1077 -379
- package/src/SQLite.js +1629 -1005
- package/src/Schema.js +2101 -0
- package/src/Str.js +1209 -432
- package/src/Sys.js +654 -0
- package/src/Time.js +1533 -440
- package/src/Utils.js +342 -325
- package/src/errors.js +335 -0
- package/src/internal/shared.js +415 -0
- package/types/index.d.ts +735 -526
- package/types/src/Arr.d.ts +533 -145
- package/types/src/Arr.d.ts.map +1 -1
- package/types/src/Async.d.ts +372 -0
- package/types/src/Async.d.ts.map +1 -0
- package/types/src/Cache.d.ts +221 -0
- package/types/src/Cache.d.ts.map +1 -0
- package/types/src/Checker.d.ts +651 -232
- package/types/src/Checker.d.ts.map +1 -1
- package/types/src/Cli.d.ts +664 -0
- package/types/src/Cli.d.ts.map +1 -0
- package/types/src/Color.d.ts +300 -0
- package/types/src/Color.d.ts.map +1 -0
- package/types/src/Crypto.d.ts +620 -0
- package/types/src/Crypto.d.ts.map +1 -0
- package/types/src/Emitter.d.ts +189 -0
- package/types/src/Emitter.d.ts.map +1 -0
- package/types/src/Env.d.ts +412 -0
- package/types/src/Env.d.ts.map +1 -0
- package/types/src/FS.d.ts +717 -238
- package/types/src/FS.d.ts.map +1 -1
- package/types/src/Func.d.ts +508 -135
- package/types/src/Func.d.ts.map +1 -1
- package/types/src/Http.d.ts +444 -0
- package/types/src/Http.d.ts.map +1 -0
- package/types/src/Id.d.ts +199 -66
- package/types/src/Id.d.ts.map +1 -1
- package/types/src/Logger.d.ts +414 -46
- package/types/src/Logger.d.ts.map +1 -1
- package/types/src/Num.d.ts +514 -137
- package/types/src/Num.d.ts.map +1 -1
- package/types/src/Obj.d.ts +453 -104
- package/types/src/Obj.d.ts.map +1 -1
- package/types/src/SQLite.d.ts +754 -308
- package/types/src/SQLite.d.ts.map +1 -1
- package/types/src/Schema.d.ts +1189 -0
- package/types/src/Schema.d.ts.map +1 -0
- package/types/src/Str.d.ts +617 -166
- package/types/src/Str.d.ts.map +1 -1
- package/types/src/Sys.d.ts +314 -0
- package/types/src/Sys.d.ts.map +1 -0
- package/types/src/Time.d.ts +759 -204
- package/types/src/Time.d.ts.map +1 -1
- package/types/src/Utils.d.ts +158 -102
- package/types/src/Utils.d.ts.map +1 -1
- package/types/src/errors.d.ts +316 -0
- package/types/src/errors.d.ts.map +1 -0
- package/types/src/internal/shared.d.ts +123 -0
- package/types/src/internal/shared.d.ts.map +1 -0
- package/types/index.d.ts.map +0 -1
|
@@ -0,0 +1,620 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Text encodings for digests.
|
|
3
|
+
*/
|
|
4
|
+
export type DigestEncoding = "hex" | "base64" | "base64url";
|
|
5
|
+
/**
|
|
6
|
+
* Options for `hash()` and `hmac()`.
|
|
7
|
+
*/
|
|
8
|
+
export type HashOptions = {
|
|
9
|
+
/**
|
|
10
|
+
* Any algorithm OpenSSL supports. Defaults to `"sha256"`.
|
|
11
|
+
*/
|
|
12
|
+
algorithm?: (string & {}) | "sha256" | "sha384" | "sha512" | "sha1" | "md5" | "sha3-256" | "sha3-512" | undefined;
|
|
13
|
+
/**
|
|
14
|
+
* Defaults to `"hex"`.
|
|
15
|
+
*/
|
|
16
|
+
encoding?: DigestEncoding | undefined;
|
|
17
|
+
};
|
|
18
|
+
/**
|
|
19
|
+
* Options for `hashPassword()`.
|
|
20
|
+
*/
|
|
21
|
+
export type HashPasswordOptions = {
|
|
22
|
+
/**
|
|
23
|
+
* Work factor as a power of two; each +1 doubles the time. Defaults to `15`.
|
|
24
|
+
*/
|
|
25
|
+
cost?: number | undefined;
|
|
26
|
+
/**
|
|
27
|
+
* scrypt `r`. Defaults to `8`.
|
|
28
|
+
*/
|
|
29
|
+
blockSize?: number | undefined;
|
|
30
|
+
/**
|
|
31
|
+
* scrypt `p`. Defaults to `1`.
|
|
32
|
+
*/
|
|
33
|
+
parallelization?: number | undefined;
|
|
34
|
+
/**
|
|
35
|
+
* In bytes. Defaults to `16`.
|
|
36
|
+
*/
|
|
37
|
+
saltLength?: number | undefined;
|
|
38
|
+
/**
|
|
39
|
+
* In bytes. Defaults to `32`.
|
|
40
|
+
*/
|
|
41
|
+
keyLength?: number | undefined;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Options for `encrypt()`.
|
|
45
|
+
*/
|
|
46
|
+
export type EncryptOptions = {
|
|
47
|
+
/**
|
|
48
|
+
* Data that's authenticated but not encrypted, like a user id. Pass the same value to `decrypt()`.
|
|
49
|
+
*/
|
|
50
|
+
associatedData?: string | Buffer<ArrayBufferLike> | undefined;
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* Options for `decrypt()`.
|
|
54
|
+
*/
|
|
55
|
+
export type DecryptOptions = {
|
|
56
|
+
/**
|
|
57
|
+
* The value given to `encrypt()`, if any.
|
|
58
|
+
*/
|
|
59
|
+
associatedData?: string | Buffer<ArrayBufferLike> | undefined;
|
|
60
|
+
/**
|
|
61
|
+
* Get a string or a `Buffer`. Defaults to `"utf8"`.
|
|
62
|
+
*/
|
|
63
|
+
output?: "utf8" | "buffer" | undefined;
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* A key for `signJWT()` and `verifyJWT()`. For the HS algorithms it's a
|
|
67
|
+
* shared secret. For the others it's a key pair: a PEM string, a
|
|
68
|
+
* `KeyObject` or a JWK, private to sign and public to verify.
|
|
69
|
+
*/
|
|
70
|
+
export type JWTKey = string | Buffer | Uint8Array | import("node:crypto").KeyObject | import("node:crypto").JsonWebKey;
|
|
71
|
+
/**
|
|
72
|
+
* A pair of keys in PEM, as made by `generateKeyPair()`.
|
|
73
|
+
*/
|
|
74
|
+
export type KeyPair = {
|
|
75
|
+
/**
|
|
76
|
+
* Give this one away: it only checks signatures.
|
|
77
|
+
*/
|
|
78
|
+
publicKey: string;
|
|
79
|
+
/**
|
|
80
|
+
* Keep this one secret: it signs.
|
|
81
|
+
*/
|
|
82
|
+
privateKey: string;
|
|
83
|
+
};
|
|
84
|
+
/**
|
|
85
|
+
* Standard JWT claims.
|
|
86
|
+
*/
|
|
87
|
+
export type JWTClaims = {
|
|
88
|
+
/**
|
|
89
|
+
* Issuer.
|
|
90
|
+
*/
|
|
91
|
+
iss?: string | undefined;
|
|
92
|
+
/**
|
|
93
|
+
* Subject, usually the user id.
|
|
94
|
+
*/
|
|
95
|
+
sub?: string | undefined;
|
|
96
|
+
/**
|
|
97
|
+
* Audience.
|
|
98
|
+
*/
|
|
99
|
+
aud?: string | string[] | undefined;
|
|
100
|
+
/**
|
|
101
|
+
* Expiry, in Unix seconds.
|
|
102
|
+
*/
|
|
103
|
+
exp?: number | undefined;
|
|
104
|
+
/**
|
|
105
|
+
* Not valid before, in Unix seconds.
|
|
106
|
+
*/
|
|
107
|
+
nbf?: number | undefined;
|
|
108
|
+
/**
|
|
109
|
+
* Issued at, in Unix seconds.
|
|
110
|
+
*/
|
|
111
|
+
iat?: number | undefined;
|
|
112
|
+
/**
|
|
113
|
+
* Unique token id.
|
|
114
|
+
*/
|
|
115
|
+
jti?: string | undefined;
|
|
116
|
+
};
|
|
117
|
+
/**
|
|
118
|
+
* Supported JWT algorithms. HS signs and verifies with one shared secret.
|
|
119
|
+
* RS, PS, ES and EdDSA sign with a private key and verify with the public
|
|
120
|
+
* one, so services that only check tokens never hold the signing key.
|
|
121
|
+
*/
|
|
122
|
+
export type JWTAlgorithm = "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA";
|
|
123
|
+
/**
|
|
124
|
+
* Options for `signJWT()`.
|
|
125
|
+
*/
|
|
126
|
+
export type SignJWTOptions = {
|
|
127
|
+
/**
|
|
128
|
+
* Defaults to what fits the key: `"HS256"` for a secret, `"RS256"` for an RSA key, `"ES256"` for a P-256 key, `"EdDSA"` for an Ed25519 key.
|
|
129
|
+
*/
|
|
130
|
+
algorithm?: JWTAlgorithm | undefined;
|
|
131
|
+
/**
|
|
132
|
+
* Lifetime in seconds or as a duration like `"15m"`. Sets `exp`.
|
|
133
|
+
*/
|
|
134
|
+
expiresIn?: string | number | undefined;
|
|
135
|
+
/**
|
|
136
|
+
* Delay before the token is valid. Sets `nbf`.
|
|
137
|
+
*/
|
|
138
|
+
notBefore?: string | number | undefined;
|
|
139
|
+
/**
|
|
140
|
+
* Sets `iss`.
|
|
141
|
+
*/
|
|
142
|
+
issuer?: string | undefined;
|
|
143
|
+
/**
|
|
144
|
+
* Sets `sub`.
|
|
145
|
+
*/
|
|
146
|
+
subject?: string | undefined;
|
|
147
|
+
/**
|
|
148
|
+
* Sets `aud`.
|
|
149
|
+
*/
|
|
150
|
+
audience?: string | string[] | undefined;
|
|
151
|
+
/**
|
|
152
|
+
* Sets `jti`, handy for revocation lists.
|
|
153
|
+
*/
|
|
154
|
+
jwtId?: string | undefined;
|
|
155
|
+
/**
|
|
156
|
+
* Don't add `iat`.
|
|
157
|
+
*/
|
|
158
|
+
noTimestamp?: boolean | undefined;
|
|
159
|
+
/**
|
|
160
|
+
* Extra header fields, like `{ kid: "2024-key" }`.
|
|
161
|
+
*/
|
|
162
|
+
header?: Record<string, unknown> | undefined;
|
|
163
|
+
};
|
|
164
|
+
/**
|
|
165
|
+
* Options for `verifyJWT()`.
|
|
166
|
+
*/
|
|
167
|
+
export type VerifyJWTOptions = {
|
|
168
|
+
/**
|
|
169
|
+
* Accepted algorithms. Defaults to the ones that fit the key, so a token can't pick a weaker one.
|
|
170
|
+
*/
|
|
171
|
+
algorithms?: JWTAlgorithm[] | undefined;
|
|
172
|
+
/**
|
|
173
|
+
* Required issuer.
|
|
174
|
+
*/
|
|
175
|
+
issuer?: string | string[] | undefined;
|
|
176
|
+
/**
|
|
177
|
+
* Required audience; one match is enough.
|
|
178
|
+
*/
|
|
179
|
+
audience?: string | string[] | undefined;
|
|
180
|
+
/**
|
|
181
|
+
* Required subject.
|
|
182
|
+
*/
|
|
183
|
+
subject?: string | undefined;
|
|
184
|
+
/**
|
|
185
|
+
* Seconds of slack for `exp` and `nbf` when server clocks differ.
|
|
186
|
+
*/
|
|
187
|
+
clockTolerance?: number | undefined;
|
|
188
|
+
/**
|
|
189
|
+
* Reject tokens issued longer ago than this.
|
|
190
|
+
*/
|
|
191
|
+
maxAge?: string | number | undefined;
|
|
192
|
+
/**
|
|
193
|
+
* Skip the `exp` check.
|
|
194
|
+
*/
|
|
195
|
+
ignoreExpiration?: boolean | undefined;
|
|
196
|
+
/**
|
|
197
|
+
* What time it is. Defaults to now. Handy in tests.
|
|
198
|
+
*/
|
|
199
|
+
now?: number | Date | undefined;
|
|
200
|
+
};
|
|
201
|
+
/**
|
|
202
|
+
* A decoded JWT.
|
|
203
|
+
*/
|
|
204
|
+
export type DecodedJWT<P = Record<string, unknown>> = {
|
|
205
|
+
header: {
|
|
206
|
+
alg: string;
|
|
207
|
+
typ?: string;
|
|
208
|
+
[key: string]: unknown;
|
|
209
|
+
};
|
|
210
|
+
payload: P & JWTClaims;
|
|
211
|
+
/**
|
|
212
|
+
* Base64URL.
|
|
213
|
+
*/
|
|
214
|
+
signature: string;
|
|
215
|
+
};
|
|
216
|
+
/**
|
|
217
|
+
* Options for `totp()` and `verifyTOTP()`.
|
|
218
|
+
*/
|
|
219
|
+
export type TOTPOptions = {
|
|
220
|
+
/**
|
|
221
|
+
* Defaults to `6`.
|
|
222
|
+
*/
|
|
223
|
+
digits?: number | undefined;
|
|
224
|
+
/**
|
|
225
|
+
* How long a code lasts, in seconds. Defaults to `30`.
|
|
226
|
+
*/
|
|
227
|
+
period?: number | undefined;
|
|
228
|
+
/**
|
|
229
|
+
* Defaults to `"SHA1"`, which is what authenticator apps expect.
|
|
230
|
+
*/
|
|
231
|
+
algorithm?: "SHA1" | "SHA256" | "SHA512" | undefined;
|
|
232
|
+
/**
|
|
233
|
+
* Compute the code for this moment. Defaults to now.
|
|
234
|
+
*/
|
|
235
|
+
time?: number | Date | undefined;
|
|
236
|
+
};
|
|
237
|
+
/**
|
|
238
|
+
* Options for `verifyTOTP()`. `window` is how many periods before and after
|
|
239
|
+
* now are accepted (defaults to `1`).
|
|
240
|
+
*/
|
|
241
|
+
export type VerifyTOTPOptions = TOTPOptions & {
|
|
242
|
+
window?: number;
|
|
243
|
+
};
|
|
244
|
+
/**
|
|
245
|
+
* Options for `totpURI()`.
|
|
246
|
+
*/
|
|
247
|
+
export type TOTPURIOptions = {
|
|
248
|
+
/**
|
|
249
|
+
* The account shown in the app, usually the email.
|
|
250
|
+
*/
|
|
251
|
+
label: string;
|
|
252
|
+
/**
|
|
253
|
+
* Your app's name.
|
|
254
|
+
*/
|
|
255
|
+
issuer?: string | undefined;
|
|
256
|
+
/**
|
|
257
|
+
* Defaults to `6`.
|
|
258
|
+
*/
|
|
259
|
+
digits?: number | undefined;
|
|
260
|
+
/**
|
|
261
|
+
* Defaults to `30`.
|
|
262
|
+
*/
|
|
263
|
+
period?: number | undefined;
|
|
264
|
+
/**
|
|
265
|
+
* Defaults to `"SHA1"`.
|
|
266
|
+
*/
|
|
267
|
+
algorithm?: "SHA1" | "SHA256" | "SHA512" | undefined;
|
|
268
|
+
};
|
|
269
|
+
/**
|
|
270
|
+
* A key, ready to use, with the algorithms it may be used with.
|
|
271
|
+
*/
|
|
272
|
+
export type _ResolvedKey = {
|
|
273
|
+
secret: Buffer;
|
|
274
|
+
key?: undefined;
|
|
275
|
+
algorithms: readonly JWTAlgorithm[];
|
|
276
|
+
} | {
|
|
277
|
+
secret?: undefined;
|
|
278
|
+
key: import("node:crypto").KeyObject;
|
|
279
|
+
algorithms: readonly JWTAlgorithm[];
|
|
280
|
+
};
|
|
281
|
+
/**
|
|
282
|
+
* Hashes data, SHA-256 in hex by default.
|
|
283
|
+
*
|
|
284
|
+
* @example
|
|
285
|
+
* crypto.hash("hello");
|
|
286
|
+
* crypto.hash("hello", { algorithm: "sha512", encoding: "base64url" });
|
|
287
|
+
*
|
|
288
|
+
* @param {string | Buffer | Uint8Array} data Strings are read as UTF-8.
|
|
289
|
+
* @param {HashOptions} [options]
|
|
290
|
+
* @returns {string}
|
|
291
|
+
*/
|
|
292
|
+
export function hash(data: string | Buffer | Uint8Array, options?: HashOptions): string;
|
|
293
|
+
/**
|
|
294
|
+
* An HMAC signature: a hash keyed with a secret. The usual way to sign and
|
|
295
|
+
* check webhooks.
|
|
296
|
+
*
|
|
297
|
+
* @example
|
|
298
|
+
* const signature = crypto.hmac(rawBody, process.env.WEBHOOK_SECRET);
|
|
299
|
+
* crypto.safeEqual(signature, req.headers["x-signature"]);
|
|
300
|
+
*
|
|
301
|
+
* @param {string | Buffer | Uint8Array} data
|
|
302
|
+
* @param {string | Buffer | Uint8Array} secret
|
|
303
|
+
* @param {HashOptions} [options]
|
|
304
|
+
* @returns {string}
|
|
305
|
+
*/
|
|
306
|
+
export function hmac(data: string | Buffer | Uint8Array, secret: string | Buffer | Uint8Array, options?: HashOptions): string;
|
|
307
|
+
/**
|
|
308
|
+
* Checks an HMAC signature you received, in constant time. A leading
|
|
309
|
+
* `sha256=`, as GitHub and others send, is ignored.
|
|
310
|
+
*
|
|
311
|
+
* @example
|
|
312
|
+
* // an Express webhook route: sign the raw body, not the parsed JSON
|
|
313
|
+
* if (!crypto.verifyHmac(req.rawBody, req.headers["x-hub-signature-256"], process.env.WEBHOOK_SECRET)) {
|
|
314
|
+
* return res.status(401).end();
|
|
315
|
+
* }
|
|
316
|
+
*
|
|
317
|
+
* @param {string | Buffer | Uint8Array} data
|
|
318
|
+
* @param {unknown} signature What the sender computed. Anything but a matching string gives `false`.
|
|
319
|
+
* @param {string | Buffer | Uint8Array} secret
|
|
320
|
+
* @param {HashOptions} [options] Must match what the sender used.
|
|
321
|
+
* @returns {boolean}
|
|
322
|
+
*/
|
|
323
|
+
export function verifyHmac(data: string | Buffer | Uint8Array, signature: unknown, secret: string | Buffer | Uint8Array, options?: HashOptions): boolean;
|
|
324
|
+
/**
|
|
325
|
+
* Compares two secrets in constant time, so the comparison can't leak
|
|
326
|
+
* anything through timing, not even their lengths. Use it instead of `===`
|
|
327
|
+
* for tokens, signatures and API keys. A missing value (`undefined`, `null`)
|
|
328
|
+
* never equals anything.
|
|
329
|
+
*
|
|
330
|
+
* @example
|
|
331
|
+
* if (!crypto.safeEqual(providedKey, process.env.API_KEY)) throw new Error("Forbidden");
|
|
332
|
+
*
|
|
333
|
+
* @param {string | Buffer | Uint8Array} a
|
|
334
|
+
* @param {string | Buffer | Uint8Array} b
|
|
335
|
+
* @returns {boolean}
|
|
336
|
+
*/
|
|
337
|
+
export function safeEqual(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
|
|
338
|
+
/**
|
|
339
|
+
* Hashes a password with scrypt and a random salt. The result records its
|
|
340
|
+
* own settings, so you can raise the cost later without breaking old
|
|
341
|
+
* hashes.
|
|
342
|
+
*
|
|
343
|
+
* @example
|
|
344
|
+
* const stored = await crypto.hashPassword(password);
|
|
345
|
+
* // "$scrypt$ln=15,r=8,p=1$4xY...$kq9...", store this
|
|
346
|
+
*
|
|
347
|
+
* @param {string} password
|
|
348
|
+
* @param {HashPasswordOptions} [options]
|
|
349
|
+
* @returns {Promise<string>}
|
|
350
|
+
* @throws {RangeError} If the settings are out of bounds, like a cost that needs more than 1 GiB of memory.
|
|
351
|
+
*/
|
|
352
|
+
export function hashPassword(password: string, options?: HashPasswordOptions): Promise<string>;
|
|
353
|
+
/**
|
|
354
|
+
* Checks a password against a stored hash, in constant time. A wrong
|
|
355
|
+
* password or a broken hash gives `false`, never an error.
|
|
356
|
+
*
|
|
357
|
+
* @example
|
|
358
|
+
* if (!(await crypto.verifyPassword(input, user.passwordHash))) throw new Error("Invalid credentials");
|
|
359
|
+
*
|
|
360
|
+
* @param {string} password
|
|
361
|
+
* @param {string} stored
|
|
362
|
+
* @returns {Promise<boolean>}
|
|
363
|
+
*/
|
|
364
|
+
export function verifyPassword(password: string, stored: string): Promise<boolean>;
|
|
365
|
+
/**
|
|
366
|
+
* Was this hash made with weaker settings than yours? If so, re-hash the
|
|
367
|
+
* password right after a successful login.
|
|
368
|
+
*
|
|
369
|
+
* @example
|
|
370
|
+
* if (await crypto.verifyPassword(input, user.hash) && crypto.needsRehash(user.hash, { cost: 16 })) {
|
|
371
|
+
* user.hash = await crypto.hashPassword(input, { cost: 16 });
|
|
372
|
+
* }
|
|
373
|
+
*
|
|
374
|
+
* @param {string} stored
|
|
375
|
+
* @param {HashPasswordOptions} [options] The settings you use today.
|
|
376
|
+
* @returns {boolean}
|
|
377
|
+
*/
|
|
378
|
+
export function needsRehash(stored: string, options?: HashPasswordOptions): boolean;
|
|
379
|
+
/**
|
|
380
|
+
* A random 256-bit key for `encrypt()`, as text you can put in an
|
|
381
|
+
* environment variable.
|
|
382
|
+
*
|
|
383
|
+
* @returns {string}
|
|
384
|
+
*/
|
|
385
|
+
export function generateKey(): string;
|
|
386
|
+
/**
|
|
387
|
+
* Encrypts data with AES-256-GCM, which also detects tampering. Every call
|
|
388
|
+
* uses a fresh salt and nonce, so the same text never encrypts the same way
|
|
389
|
+
* twice.
|
|
390
|
+
*
|
|
391
|
+
* Use a key from `generateKey()` or another long random secret, not a
|
|
392
|
+
* password someone typed: that would be easy to brute-force.
|
|
393
|
+
*
|
|
394
|
+
* @example
|
|
395
|
+
* const box = crypto.encrypt(JSON.stringify(card), process.env.ENCRYPTION_KEY);
|
|
396
|
+
* const card = JSON.parse(crypto.decrypt(box, process.env.ENCRYPTION_KEY));
|
|
397
|
+
*
|
|
398
|
+
* @param {string | Buffer | Uint8Array} data
|
|
399
|
+
* @param {string | Buffer | Uint8Array} secret
|
|
400
|
+
* @param {EncryptOptions} [options]
|
|
401
|
+
* @returns {string} A compact, URL-safe string.
|
|
402
|
+
*/
|
|
403
|
+
export function encrypt(data: string | Buffer | Uint8Array, secret: string | Buffer | Uint8Array, options?: EncryptOptions): string;
|
|
404
|
+
/**
|
|
405
|
+
* Decrypts what `encrypt()` produced. Throws an error with code
|
|
406
|
+
* `ERR_DECRYPT` if the secret is wrong or the data was changed.
|
|
407
|
+
*
|
|
408
|
+
* @example
|
|
409
|
+
* const text = crypto.decrypt(box, SECRET);
|
|
410
|
+
* const bytes = crypto.decrypt(box, SECRET, { output: "buffer" });
|
|
411
|
+
*
|
|
412
|
+
* @overload
|
|
413
|
+
* @param {string} payload
|
|
414
|
+
* @param {string | Buffer | Uint8Array} secret
|
|
415
|
+
* @param {DecryptOptions & { output: "buffer" }} options
|
|
416
|
+
* @returns {Buffer}
|
|
417
|
+
*/
|
|
418
|
+
export function decrypt(payload: string, secret: string | Buffer | Uint8Array, options: DecryptOptions & {
|
|
419
|
+
output: "buffer";
|
|
420
|
+
}): Buffer;
|
|
421
|
+
/**
|
|
422
|
+
* Decrypts what `encrypt()` produced, as text.
|
|
423
|
+
*
|
|
424
|
+
* @overload
|
|
425
|
+
* @param {string} payload
|
|
426
|
+
* @param {string | Buffer | Uint8Array} secret
|
|
427
|
+
* @param {DecryptOptions} [options]
|
|
428
|
+
* @returns {string}
|
|
429
|
+
*/
|
|
430
|
+
export function decrypt(payload: string, secret: string | Buffer | Uint8Array, options?: DecryptOptions | undefined): string;
|
|
431
|
+
/**
|
|
432
|
+
* Creates a signed JSON Web Token. `iat` is added for you.
|
|
433
|
+
*
|
|
434
|
+
* With a secret, the token is signed with HMAC. With a private key, it's
|
|
435
|
+
* signed with that key, and anyone holding the public key can verify it
|
|
436
|
+
* without being able to issue tokens.
|
|
437
|
+
*
|
|
438
|
+
* @example
|
|
439
|
+
* const token = crypto.signJWT({ sub: String(user.id), role: user.role }, process.env.JWT_SECRET, {
|
|
440
|
+
* expiresIn: "15m",
|
|
441
|
+
* issuer: "api.example.com",
|
|
442
|
+
* });
|
|
443
|
+
*
|
|
444
|
+
* // key pair: the auth service signs, every other service verifies
|
|
445
|
+
* const { publicKey, privateKey } = await crypto.generateKeyPair("ES256");
|
|
446
|
+
* const signed = crypto.signJWT({ sub: "42" }, privateKey, { expiresIn: "15m" });
|
|
447
|
+
* crypto.verifyJWT(signed, publicKey);
|
|
448
|
+
*
|
|
449
|
+
* @param {Record<string, unknown>} payload
|
|
450
|
+
* @param {JWTKey} secret For HS algorithms, at least 32 random bytes. Otherwise a private key.
|
|
451
|
+
* @param {SignJWTOptions} [options]
|
|
452
|
+
* @returns {string}
|
|
453
|
+
* @throws {TypeError} If the key can't be used, or doesn't fit the algorithm.
|
|
454
|
+
*/
|
|
455
|
+
export function signJWT(payload: Record<string, unknown>, secret: JWTKey, options?: SignJWTOptions): string;
|
|
456
|
+
/**
|
|
457
|
+
* Reads a JWT without checking it. Fine for display; call `verifyJWT()`
|
|
458
|
+
* before trusting anything in it.
|
|
459
|
+
*
|
|
460
|
+
* @example
|
|
461
|
+
* crypto.decodeJWT(token).payload.exp;
|
|
462
|
+
*
|
|
463
|
+
* @template [P=Record<string, unknown>]
|
|
464
|
+
* @param {string} token
|
|
465
|
+
* @returns {DecodedJWT<P>}
|
|
466
|
+
* @throws {JWTError} With code `ERR_JWT_MALFORMED` if the token can't be read.
|
|
467
|
+
*/
|
|
468
|
+
export function decodeJWT<P = Record<string, unknown>>(token: string): DecodedJWT<P>;
|
|
469
|
+
/**
|
|
470
|
+
* Verifies a JWT: algorithm, signature, expiry, and whichever claims you
|
|
471
|
+
* require. Returns the payload, or throws a `JWTError` whose `code` says
|
|
472
|
+
* what's wrong.
|
|
473
|
+
*
|
|
474
|
+
* The accepted algorithms follow from the key you pass, so a token signed
|
|
475
|
+
* with HMAC is never accepted where a public key is expected.
|
|
476
|
+
*
|
|
477
|
+
* @example
|
|
478
|
+
* try {
|
|
479
|
+
* const { sub } = crypto.verifyJWT(token, process.env.JWT_SECRET, { issuer: "api.example.com" });
|
|
480
|
+
* } catch (error) {
|
|
481
|
+
* res.status(401).json({ error: error.code }); // "ERR_JWT_EXPIRED"...
|
|
482
|
+
* }
|
|
483
|
+
*
|
|
484
|
+
* @template [P=Record<string, unknown>]
|
|
485
|
+
* @param {string} token
|
|
486
|
+
* @param {JWTKey} secret The shared secret, or the public key for RS, PS, ES and EdDSA tokens.
|
|
487
|
+
* @param {VerifyJWTOptions} [options]
|
|
488
|
+
* @returns {P & JWTClaims}
|
|
489
|
+
* @throws {JWTError}
|
|
490
|
+
*/
|
|
491
|
+
export function verifyJWT<P = Record<string, unknown>>(token: string, secret: JWTKey, options?: VerifyJWTOptions): P & JWTClaims;
|
|
492
|
+
/**
|
|
493
|
+
* Makes a pair of keys for signing JWTs: the private one signs, the public
|
|
494
|
+
* one verifies. Both come as PEM text, ready for an environment variable or
|
|
495
|
+
* a file.
|
|
496
|
+
*
|
|
497
|
+
* `"EdDSA"` (Ed25519) is the fastest with the shortest keys and signatures.
|
|
498
|
+
* `"ES256"` is the most widely supported after RSA. Pick `"RS256"` when the
|
|
499
|
+
* other side asks for it.
|
|
500
|
+
*
|
|
501
|
+
* @example
|
|
502
|
+
* const { publicKey, privateKey } = await crypto.generateKeyPair();
|
|
503
|
+
* const token = crypto.signJWT({ sub: "42" }, privateKey);
|
|
504
|
+
* crypto.verifyJWT(token, publicKey);
|
|
505
|
+
*
|
|
506
|
+
* @param {Exclude<JWTAlgorithm, "HS256" | "HS384" | "HS512">} [algorithm="EdDSA"] The JWT algorithm the keys are for.
|
|
507
|
+
* @param {{ modulusLength?: number }} [options] RSA key size in bits. Defaults to `2048`.
|
|
508
|
+
* @returns {Promise<KeyPair>}
|
|
509
|
+
*/
|
|
510
|
+
export function generateKeyPair(algorithm?: Exclude<JWTAlgorithm, "HS256" | "HS384" | "HS512">, options?: {
|
|
511
|
+
modulusLength?: number;
|
|
512
|
+
}): Promise<KeyPair>;
|
|
513
|
+
/**
|
|
514
|
+
* A new two-factor secret, in the Base32 format authenticator apps expect.
|
|
515
|
+
* Store it encrypted.
|
|
516
|
+
*
|
|
517
|
+
* @example
|
|
518
|
+
* user.totpSecret = crypto.totpSecret();
|
|
519
|
+
*
|
|
520
|
+
* @param {number} [bytes=20]
|
|
521
|
+
* @returns {string}
|
|
522
|
+
*/
|
|
523
|
+
export function totpSecret(bytes?: number): string;
|
|
524
|
+
/**
|
|
525
|
+
* The current 6-digit code for a two-factor secret, as shown by
|
|
526
|
+
* authenticator apps.
|
|
527
|
+
*
|
|
528
|
+
* @example
|
|
529
|
+
* crypto.totp(user.totpSecret); // "492039"
|
|
530
|
+
*
|
|
531
|
+
* @param {string} secret
|
|
532
|
+
* @param {TOTPOptions} [options]
|
|
533
|
+
* @returns {string}
|
|
534
|
+
*/
|
|
535
|
+
export function totp(secret: string, options?: TOTPOptions): string;
|
|
536
|
+
/**
|
|
537
|
+
* Checks a code typed by a user. Codes from the neighbouring periods are
|
|
538
|
+
* accepted too, to cope with clock drift.
|
|
539
|
+
*
|
|
540
|
+
* @example
|
|
541
|
+
* if (!crypto.verifyTOTP(req.body.code, user.totpSecret)) throw new Error("Invalid code");
|
|
542
|
+
*
|
|
543
|
+
* @param {string} token Spaces are ignored.
|
|
544
|
+
* @param {string} secret
|
|
545
|
+
* @param {VerifyTOTPOptions} [options]
|
|
546
|
+
* @returns {boolean}
|
|
547
|
+
*/
|
|
548
|
+
export function verifyTOTP(token: string, secret: string, options?: VerifyTOTPOptions): boolean;
|
|
549
|
+
/**
|
|
550
|
+
* The `otpauth://` link to show as a QR code when a user turns on 2FA.
|
|
551
|
+
*
|
|
552
|
+
* @example
|
|
553
|
+
* const uri = crypto.totpURI(user.totpSecret, { label: user.email, issuer: "My App" });
|
|
554
|
+
*
|
|
555
|
+
* @param {string} secret
|
|
556
|
+
* @param {TOTPURIOptions} options
|
|
557
|
+
* @returns {string}
|
|
558
|
+
*/
|
|
559
|
+
export function totpURI(secret: string, options: TOTPURIOptions): string;
|
|
560
|
+
/**
|
|
561
|
+
* Secure random bytes.
|
|
562
|
+
*
|
|
563
|
+
* @param {number} size
|
|
564
|
+
* @returns {Buffer}
|
|
565
|
+
*/
|
|
566
|
+
export function randomBytes(size: number): Buffer;
|
|
567
|
+
/**
|
|
568
|
+
* A secure random integer from `min` to `max`, both included, with no bias.
|
|
569
|
+
* For anything that has to be fair or unpredictable.
|
|
570
|
+
*
|
|
571
|
+
* @example
|
|
572
|
+
* crypto.randomInt(1, 6); // a fair dice roll
|
|
573
|
+
* crypto.randomInt(0, 999_999); // a 6-digit code
|
|
574
|
+
*
|
|
575
|
+
* @param {number} min
|
|
576
|
+
* @param {number} max
|
|
577
|
+
* @returns {number}
|
|
578
|
+
*/
|
|
579
|
+
export function randomInt(min: number, max: number): number;
|
|
580
|
+
/**
|
|
581
|
+
* Encodes to Base64, or URL-safe Base64.
|
|
582
|
+
*
|
|
583
|
+
* @example
|
|
584
|
+
* crypto.toBase64("héllo"); // "aMOpbGxv"
|
|
585
|
+
* crypto.toBase64("héllo", { urlSafe: true });
|
|
586
|
+
*
|
|
587
|
+
* @param {string | Buffer | Uint8Array} data
|
|
588
|
+
* @param {{ urlSafe?: boolean }} [options]
|
|
589
|
+
* @returns {string}
|
|
590
|
+
*/
|
|
591
|
+
export function toBase64(data: string | Buffer | Uint8Array, options?: {
|
|
592
|
+
urlSafe?: boolean;
|
|
593
|
+
}): string;
|
|
594
|
+
/**
|
|
595
|
+
* Decodes Base64 or URL-safe Base64.
|
|
596
|
+
*
|
|
597
|
+
* @example
|
|
598
|
+
* crypto.fromBase64("aMOpbGxv"); // "héllo"
|
|
599
|
+
* crypto.fromBase64("aMOpbGxv", { output: "buffer" }); // <Buffer 68 c3 a9 6c 6c 6f>
|
|
600
|
+
*
|
|
601
|
+
* @overload
|
|
602
|
+
* @param {string} text
|
|
603
|
+
* @param {{ output: "buffer" }} options
|
|
604
|
+
* @returns {Buffer}
|
|
605
|
+
*/
|
|
606
|
+
export function fromBase64(text: string, options: {
|
|
607
|
+
output: "buffer";
|
|
608
|
+
}): Buffer;
|
|
609
|
+
/**
|
|
610
|
+
* Decodes Base64 or URL-safe Base64 into text.
|
|
611
|
+
*
|
|
612
|
+
* @overload
|
|
613
|
+
* @param {string} text
|
|
614
|
+
* @param {{ output?: "utf8" }} [options]
|
|
615
|
+
* @returns {string}
|
|
616
|
+
*/
|
|
617
|
+
export function fromBase64(text: string, options?: {
|
|
618
|
+
output?: "utf8";
|
|
619
|
+
} | undefined): string;
|
|
620
|
+
//# sourceMappingURL=Crypto.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../../src/Crypto.js"],"names":[],"mappings":";;;6BAsCa,KAAK,GAAG,QAAQ,GAAG,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAqC9B,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,aAAa,EAAE,SAAS,GAAG,OAAO,aAAa,EAAE,UAAU;;;;;;;;eAMhG,MAAM;;;;gBACN,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAmBP,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAgC9H,CAAC;YAED;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;aACrD,CAAC,GAAG,SAAS;;;;eACb,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAeP,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;WAMhC,MAAM;;;;;;;;;;;;;;;;;;;;;2BAgYP;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GAAG;IAAE,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE;AAxRzL;;;;;;;;;;GAUG;AACH,2BAJW,MAAM,GAAG,MAAM,GAAG,UAAU,YAC5B,WAAW,GACT,MAAM,CAIlB;AAED;;;;;;;;;;;;GAYG;AACH,2BALW,MAAM,GAAG,MAAM,GAAG,UAAU,UAC5B,MAAM,GAAG,MAAM,GAAG,UAAU,YAC5B,WAAW,GACT,MAAM,CAOlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,iCANW,MAAM,GAAG,MAAM,GAAG,UAAU,aAC5B,OAAO,UACP,MAAM,GAAG,MAAM,GAAG,UAAU,YAC5B,WAAW,GACT,OAAO,CAOnB;AAED;;;;;;;;;;;;GAYG;AACH,6BAJW,MAAM,GAAG,MAAM,GAAG,UAAU,KAC5B,MAAM,GAAG,MAAM,GAAG,UAAU,GAC1B,OAAO,CASnB;AAmBD;;;;;;;;;;;;;GAaG;AACH,uCALW,MAAM,YACN,mBAAmB,GACjB,OAAO,CAAC,MAAM,CAAC,CAiB3B;AAED;;;;;;;;;;GAUG;AACH,yCAJW,MAAM,UACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAc5B;AAED;;;;;;;;;;;;GAYG;AACH,oCAJW,MAAM,YACN,mBAAmB,GACjB,OAAO,CAMnB;AAED;;;;;GAKG;AACH,+BAFa,MAAM,CAIlB;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,8BALW,MAAM,GAAG,MAAM,GAAG,UAAU,UAC5B,MAAM,GAAG,MAAM,GAAG,UAAU,YAC5B,cAAc,GACZ,MAAM,CAYlB;;;;;;;;;;;;;;;AAUE,iCACQ,MAAM,UACN,MAAM,GAAG,MAAM,GAAG,UAAU,WAC5B,cAAc,GAAG;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACnC,MAAM,CAClB;;;;;;;;;;AAIE,iCACQ,MAAM,UACN,MAAM,GAAG,MAAM,GAAG,UAAU,yCAE1B,MAAM,CAClB;AAyND;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iCANW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UACvB,MAAM,YACN,cAAc,GACZ,MAAM,CAsBlB;AAED;;;;;;;;;;;GAWG;AACH,0BALc,CAAC,mCACJ,MAAM,GACJ,UAAU,CAAC,CAAC,CAAC,CAMzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,0BAPc,CAAC,mCACJ,MAAM,UACN,MAAM,YACN,gBAAgB,GACd,CAAC,GAAG,SAAS,CAmCzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAJW,OAAO,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,YAClD;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACxB,OAAO,CAAC,OAAO,CAAC,CAoB5B;AAED;;;;;;;;;GASG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AA+BD;;;;;;;;;;GAUG;AACH,6BAJW,MAAM,YACN,WAAW,GACT,MAAM,CAKlB;AAED;;;;;;;;;;;GAWG;AACH,kCALW,MAAM,UACN,MAAM,YACN,iBAAiB,GACf,OAAO,CAenB;AAED;;;;;;;;;GASG;AACH,gCAJW,MAAM,WACN,cAAc,GACZ,MAAM,CAUlB;AAED;;;;;GAKG;AACH,kCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;GAWG;AACH,+BAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;;;;;GAUG;AACH,+BAJW,MAAM,GAAG,MAAM,GAAG,UAAU,YAC5B;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACnB,MAAM,CAIlB;;;;;;;;;;;;;AASE,iCACQ,MAAM,WACN;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GAClB,MAAM,CAClB;;;;;;;;;AAIE,iCACQ,MAAM;aACK,MAAM;gBACf,MAAM,CAClB"}
|