@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.
Files changed (78) hide show
  1. package/CHANGELOG.md +340 -0
  2. package/README.md +137 -548
  3. package/index.js +80 -35
  4. package/package.json +161 -33
  5. package/src/Arr.js +1050 -418
  6. package/src/Async.js +817 -0
  7. package/src/Cache.js +433 -0
  8. package/src/Checker.js +1202 -539
  9. package/src/Cli.js +1293 -0
  10. package/src/Color.js +556 -0
  11. package/src/Crypto.js +1082 -0
  12. package/src/Emitter.js +356 -0
  13. package/src/Env.js +689 -0
  14. package/src/FS.js +1626 -894
  15. package/src/Func.js +823 -356
  16. package/src/Http.js +700 -0
  17. package/src/Id.js +568 -200
  18. package/src/Logger.js +963 -378
  19. package/src/Num.js +965 -360
  20. package/src/Obj.js +1077 -379
  21. package/src/SQLite.js +1629 -1005
  22. package/src/Schema.js +2101 -0
  23. package/src/Str.js +1209 -432
  24. package/src/Sys.js +654 -0
  25. package/src/Time.js +1533 -440
  26. package/src/Utils.js +342 -325
  27. package/src/errors.js +335 -0
  28. package/src/internal/shared.js +415 -0
  29. package/types/index.d.ts +735 -526
  30. package/types/src/Arr.d.ts +533 -145
  31. package/types/src/Arr.d.ts.map +1 -1
  32. package/types/src/Async.d.ts +372 -0
  33. package/types/src/Async.d.ts.map +1 -0
  34. package/types/src/Cache.d.ts +221 -0
  35. package/types/src/Cache.d.ts.map +1 -0
  36. package/types/src/Checker.d.ts +651 -232
  37. package/types/src/Checker.d.ts.map +1 -1
  38. package/types/src/Cli.d.ts +664 -0
  39. package/types/src/Cli.d.ts.map +1 -0
  40. package/types/src/Color.d.ts +300 -0
  41. package/types/src/Color.d.ts.map +1 -0
  42. package/types/src/Crypto.d.ts +620 -0
  43. package/types/src/Crypto.d.ts.map +1 -0
  44. package/types/src/Emitter.d.ts +189 -0
  45. package/types/src/Emitter.d.ts.map +1 -0
  46. package/types/src/Env.d.ts +412 -0
  47. package/types/src/Env.d.ts.map +1 -0
  48. package/types/src/FS.d.ts +717 -238
  49. package/types/src/FS.d.ts.map +1 -1
  50. package/types/src/Func.d.ts +508 -135
  51. package/types/src/Func.d.ts.map +1 -1
  52. package/types/src/Http.d.ts +444 -0
  53. package/types/src/Http.d.ts.map +1 -0
  54. package/types/src/Id.d.ts +199 -66
  55. package/types/src/Id.d.ts.map +1 -1
  56. package/types/src/Logger.d.ts +414 -46
  57. package/types/src/Logger.d.ts.map +1 -1
  58. package/types/src/Num.d.ts +514 -137
  59. package/types/src/Num.d.ts.map +1 -1
  60. package/types/src/Obj.d.ts +453 -104
  61. package/types/src/Obj.d.ts.map +1 -1
  62. package/types/src/SQLite.d.ts +754 -308
  63. package/types/src/SQLite.d.ts.map +1 -1
  64. package/types/src/Schema.d.ts +1189 -0
  65. package/types/src/Schema.d.ts.map +1 -0
  66. package/types/src/Str.d.ts +617 -166
  67. package/types/src/Str.d.ts.map +1 -1
  68. package/types/src/Sys.d.ts +314 -0
  69. package/types/src/Sys.d.ts.map +1 -0
  70. package/types/src/Time.d.ts +759 -204
  71. package/types/src/Time.d.ts.map +1 -1
  72. package/types/src/Utils.d.ts +158 -102
  73. package/types/src/Utils.d.ts.map +1 -1
  74. package/types/src/errors.d.ts +316 -0
  75. package/types/src/errors.d.ts.map +1 -0
  76. package/types/src/internal/shared.d.ts +123 -0
  77. package/types/src/internal/shared.d.ts.map +1 -0
  78. 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":"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"}