@ix-xs/node-comfort 1.1.31 → 2.0.0

package/types/src/Crypto.d.ts

@@ -0,0 +1,534 @@
+/**
+ * Text encodings for digests.
+ */
+export type DigestEncoding = "hex" | "base64" | "base64url";
+/**
+ * Options for `hash()` and `hmac()`.
+ */
+export type HashOptions = {
+    /**
+     * Any algorithm OpenSSL supports. Defaults to `"sha256"`.
+     */
+    algorithm?: (string & {}) | "sha256" | "sha384" | "sha512" | "sha1" | "md5" | "sha3-256" | "sha3-512" | undefined;
+    /**
+     * Defaults to `"hex"`.
+     */
+    encoding?: DigestEncoding | undefined;
+};
+/**
+ * Options for `hashPassword()`.
+ */
+export type HashPasswordOptions = {
+    /**
+     * Work factor as a power of two; each +1 doubles the time. Defaults to `15`.
+     */
+    cost?: number | undefined;
+    /**
+     * scrypt `r`. Defaults to `8`.
+     */
+    blockSize?: number | undefined;
+    /**
+     * scrypt `p`. Defaults to `1`.
+     */
+    parallelization?: number | undefined;
+    /**
+     * In bytes. Defaults to `16`.
+     */
+    saltLength?: number | undefined;
+    /**
+     * In bytes. Defaults to `32`.
+     */
+    keyLength?: number | undefined;
+};
+/**
+ * Options for `encrypt()`.
+ */
+export type EncryptOptions = {
+    /**
+     * Data that's authenticated but not encrypted, like a user id. Pass the same value to `decrypt()`.
+     */
+    associatedData?: string | Buffer<ArrayBufferLike> | undefined;
+};
+/**
+ * Options for `decrypt()`.
+ */
+export type DecryptOptions = {
+    /**
+     * The value given to `encrypt()`, if any.
+     */
+    associatedData?: string | Buffer<ArrayBufferLike> | undefined;
+    /**
+     * Get a string or a `Buffer`. Defaults to `"utf8"`.
+     */
+    output?: "utf8" | "buffer" | undefined;
+};
+/**
+ * Standard JWT claims.
+ */
+export type JWTClaims = {
+    /**
+     * Issuer.
+     */
+    iss?: string | undefined;
+    /**
+     * Subject, usually the user id.
+     */
+    sub?: string | undefined;
+    /**
+     * Audience.
+     */
+    aud?: string | string[] | undefined;
+    /**
+     * Expiry, in Unix seconds.
+     */
+    exp?: number | undefined;
+    /**
+     * Not valid before, in Unix seconds.
+     */
+    nbf?: number | undefined;
+    /**
+     * Issued at, in Unix seconds.
+     */
+    iat?: number | undefined;
+    /**
+     * Unique token id.
+     */
+    jti?: string | undefined;
+};
+/**
+ * Supported JWT algorithms.
+ */
+export type JWTAlgorithm = "HS256" | "HS384" | "HS512";
+/**
+ * Options for `signJWT()`.
+ */
+export type SignJWTOptions = {
+    /**
+     * Defaults to `"HS256"`.
+     */
+    algorithm?: JWTAlgorithm | undefined;
+    /**
+     * Lifetime in seconds or as a duration like `"15m"`. Sets `exp`.
+     */
+    expiresIn?: string | number | undefined;
+    /**
+     * Delay before the token is valid. Sets `nbf`.
+     */
+    notBefore?: string | number | undefined;
+    /**
+     * Sets `iss`.
+     */
+    issuer?: string | undefined;
+    /**
+     * Sets `sub`.
+     */
+    subject?: string | undefined;
+    /**
+     * Sets `aud`.
+     */
+    audience?: string | string[] | undefined;
+    /**
+     * Sets `jti`, handy for revocation lists.
+     */
+    jwtId?: string | undefined;
+    /**
+     * Don't add `iat`.
+     */
+    noTimestamp?: boolean | undefined;
+    /**
+     * Extra header fields, like `{ kid: "2024-key" }`.
+     */
+    header?: Record<string, unknown> | undefined;
+};
+/**
+ * Options for `verifyJWT()`.
+ */
+export type VerifyJWTOptions = {
+    /**
+     * Accepted algorithms. Defaults to all three HMAC ones.
+     */
+    algorithms?: JWTAlgorithm[] | undefined;
+    /**
+     * Required issuer.
+     */
+    issuer?: string | string[] | undefined;
+    /**
+     * Required audience; one match is enough.
+     */
+    audience?: string | string[] | undefined;
+    /**
+     * Required subject.
+     */
+    subject?: string | undefined;
+    /**
+     * Seconds of slack for `exp` and `nbf` when server clocks differ.
+     */
+    clockTolerance?: number | undefined;
+    /**
+     * Reject tokens issued longer ago than this.
+     */
+    maxAge?: string | number | undefined;
+    /**
+     * Skip the `exp` check.
+     */
+    ignoreExpiration?: boolean | undefined;
+    /**
+     * What time it is. Defaults to now.
+     */
+    now?: number | Date | undefined;
+};
+/**
+ * A decoded JWT.
+ */
+export type DecodedJWT<P = Record<string, unknown>> = {
+    header: {
+        alg: string;
+        typ?: string;
+        [key: string]: unknown;
+    };
+    payload: P & JWTClaims;
+    /**
+     * Base64URL.
+     */
+    signature: string;
+};
+/**
+ * Options for `totp()` and `verifyTOTP()`.
+ */
+export type TOTPOptions = {
+    /**
+     * Defaults to `6`.
+     */
+    digits?: number | undefined;
+    /**
+     * How long a code lasts, in seconds. Defaults to `30`.
+     */
+    period?: number | undefined;
+    /**
+     * Defaults to `"SHA1"`, which is what authenticator apps expect.
+     */
+    algorithm?: "SHA1" | "SHA256" | "SHA512" | undefined;
+    /**
+     * Compute the code for this moment. Defaults to now.
+     */
+    time?: number | Date | undefined;
+};
+/**
+ * Options for `verifyTOTP()`. `window` is how many periods before and after
+ * now are accepted (defaults to `1`).
+ */
+export type VerifyTOTPOptions = TOTPOptions & {
+    window?: number;
+};
+/**
+ * Options for `totpURI()`.
+ */
+export type TOTPURIOptions = {
+    /**
+     * The account shown in the app, usually the email.
+     */
+    label: string;
+    /**
+     * Your app's name.
+     */
+    issuer?: string | undefined;
+    /**
+     * Defaults to `6`.
+     */
+    digits?: number | undefined;
+    /**
+     * Defaults to `30`.
+     */
+    period?: number | undefined;
+    /**
+     * Defaults to `"SHA1"`.
+     */
+    algorithm?: "SHA1" | "SHA256" | "SHA512" | undefined;
+};
+/**
+ * Hashes data, SHA-256 in hex by default.
+ *
+ * @example
+ * crypto.hash("hello");
+ * crypto.hash("hello", { algorithm: "sha512", encoding: "base64url" });
+ *
+ * @param {string | Buffer | Uint8Array} data Strings are read as UTF-8.
+ * @param {HashOptions} [options]
+ * @returns {string}
+ */
+export function hash(data: string | Buffer | Uint8Array, options?: HashOptions): string;
+/**
+ * An HMAC signature: a hash keyed with a secret. The usual way to sign and
+ * check webhooks.
+ *
+ * @example
+ * const signature = crypto.hmac(rawBody, process.env.WEBHOOK_SECRET);
+ * crypto.safeEqual(signature, req.headers["x-signature"]);
+ *
+ * @param {string | Buffer | Uint8Array} data
+ * @param {string | Buffer | Uint8Array} secret
+ * @param {HashOptions} [options]
+ * @returns {string}
+ */
+export function hmac(data: string | Buffer | Uint8Array, secret: string | Buffer | Uint8Array, options?: HashOptions): string;
+/**
+ * Compares two secrets in constant time, so the comparison can't leak
+ * anything through timing. Use it instead of `===` for tokens, signatures
+ * and API keys.
+ *
+ * @example
+ * if (!crypto.safeEqual(providedKey, process.env.API_KEY)) throw new Error("Forbidden");
+ *
+ * @param {string | Buffer | Uint8Array} a
+ * @param {string | Buffer | Uint8Array} b
+ * @returns {boolean}
+ */
+export function safeEqual(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
+/**
+ * Hashes a password with scrypt and a random salt. The result records its
+ * own settings, so you can raise the cost later without breaking old
+ * hashes.
+ *
+ * @example
+ * const stored = await crypto.hashPassword(password);
+ * // "$scrypt$ln=15,r=8,p=1$4xY...$kq9...", store this
+ *
+ * @param {string} password
+ * @param {HashPasswordOptions} [options]
+ * @returns {Promise<string>}
+ */
+export function hashPassword(password: string, options?: HashPasswordOptions): Promise<string>;
+/**
+ * Checks a password against a stored hash, in constant time. A wrong
+ * password or a broken hash gives `false`, never an error.
+ *
+ * @example
+ * if (!(await crypto.verifyPassword(input, user.passwordHash))) throw new Error("Invalid credentials");
+ *
+ * @param {string} password
+ * @param {string} stored
+ * @returns {Promise<boolean>}
+ */
+export function verifyPassword(password: string, stored: string): Promise<boolean>;
+/**
+ * Was this hash made with weaker settings than yours? If so, re-hash the
+ * password right after a successful login.
+ *
+ * @example
+ * if (await crypto.verifyPassword(input, user.hash) && crypto.needsRehash(user.hash, { cost: 16 })) {
+ *   user.hash = await crypto.hashPassword(input, { cost: 16 });
+ * }
+ *
+ * @param {string} stored
+ * @param {HashPasswordOptions} [options] The settings you use today.
+ * @returns {boolean}
+ */
+export function needsRehash(stored: string, options?: HashPasswordOptions): boolean;
+/**
+ * A random 256-bit key for `encrypt()`, as text you can put in an
+ * environment variable.
+ *
+ * @returns {string}
+ */
+export function generateKey(): string;
+/**
+ * Encrypts data with AES-256-GCM, which also detects tampering. Every call
+ * uses a fresh salt and nonce, so the same text never encrypts the same way
+ * twice.
+ *
+ * Use a key from `generateKey()` or another long random secret, not a
+ * password someone typed: that would be easy to brute-force.
+ *
+ * @example
+ * const box = crypto.encrypt(JSON.stringify(card), process.env.ENCRYPTION_KEY);
+ * const card = JSON.parse(crypto.decrypt(box, process.env.ENCRYPTION_KEY));
+ *
+ * @param {string | Buffer | Uint8Array} data
+ * @param {string | Buffer | Uint8Array} secret
+ * @param {EncryptOptions} [options]
+ * @returns {string} A compact, URL-safe string.
+ */
+export function encrypt(data: string | Buffer | Uint8Array, secret: string | Buffer | Uint8Array, options?: EncryptOptions): string;
+/**
+ * Decrypts what `encrypt()` produced. Throws if the secret is wrong or the
+ * data was changed.
+ *
+ * @example
+ * const text = crypto.decrypt(box, SECRET);
+ * const bytes = crypto.decrypt(box, SECRET, { output: "buffer" });
+ *
+ * @overload
+ * @param {string} payload
+ * @param {string | Buffer | Uint8Array} secret
+ * @param {DecryptOptions & { output: "buffer" }} options
+ * @returns {Buffer}
+ */
+export function decrypt(payload: string, secret: string | Buffer | Uint8Array, options: DecryptOptions & {
+    output: "buffer";
+}): Buffer;
+/**
+ * Decrypts what `encrypt()` produced, as text.
+ *
+ * @overload
+ * @param {string} payload
+ * @param {string | Buffer | Uint8Array} secret
+ * @param {DecryptOptions} [options]
+ * @returns {string}
+ */
+export function decrypt(payload: string, secret: string | Buffer | Uint8Array, options?: DecryptOptions | undefined): string;
+/**
+ * Creates a signed JSON Web Token. `iat` is added for you.
+ *
+ * @example
+ * const token = crypto.signJWT({ sub: String(user.id), role: user.role }, process.env.JWT_SECRET, {
+ *   expiresIn: "15m",
+ *   issuer: "api.example.com",
+ * });
+ *
+ * @param {Record<string, unknown>} payload
+ * @param {string | Buffer} secret At least 32 random bytes.
+ * @param {SignJWTOptions} [options]
+ * @returns {string}
+ */
+export function signJWT(payload: Record<string, unknown>, secret: string | Buffer, options?: SignJWTOptions): string;
+/**
+ * Reads a JWT without checking it. Fine for display; call `verifyJWT()`
+ * before trusting anything in it.
+ *
+ * @example
+ * crypto.decodeJWT(token).payload.exp;
+ *
+ * @template [P=Record<string, unknown>]
+ * @param {string} token
+ * @returns {DecodedJWT<P>}
+ * @throws {JWTError} With code `ERR_JWT_MALFORMED` if the token can't be read.
+ */
+export function decodeJWT<P = Record<string, unknown>>(token: string): DecodedJWT<P>;
+/**
+ * Verifies a JWT: algorithm, signature, expiry, and whichever claims you
+ * require. Returns the payload, or throws a `JWTError` whose `code` says
+ * what's wrong.
+ *
+ * @example
+ * try {
+ *   const { sub } = crypto.verifyJWT(token, process.env.JWT_SECRET, { issuer: "api.example.com" });
+ * } catch (error) {
+ *   res.status(401).json({ error: error.code }); // "ERR_JWT_EXPIRED"...
+ * }
+ *
+ * @template [P=Record<string, unknown>]
+ * @param {string} token
+ * @param {string | Buffer} secret
+ * @param {VerifyJWTOptions} [options]
+ * @returns {P & JWTClaims}
+ * @throws {JWTError}
+ */
+export function verifyJWT<P = Record<string, unknown>>(token: string, secret: string | Buffer, options?: VerifyJWTOptions): P & JWTClaims;
+/**
+ * A new two-factor secret, in the Base32 format authenticator apps expect.
+ * Store it encrypted.
+ *
+ * @example
+ * user.totpSecret = crypto.totpSecret();
+ *
+ * @param {number} [bytes=20]
+ * @returns {string}
+ */
+export function totpSecret(bytes?: number): string;
+/**
+ * The current 6-digit code for a two-factor secret, as shown by
+ * authenticator apps.
+ *
+ * @example
+ * crypto.totp(user.totpSecret); // "492039"
+ *
+ * @param {string} secret
+ * @param {TOTPOptions} [options]
+ * @returns {string}
+ */
+export function totp(secret: string, options?: TOTPOptions): string;
+/**
+ * Checks a code typed by a user. Codes from the neighbouring periods are
+ * accepted too, to cope with clock drift.
+ *
+ * @example
+ * if (!crypto.verifyTOTP(req.body.code, user.totpSecret)) throw new Error("Invalid code");
+ *
+ * @param {string} token Spaces are ignored.
+ * @param {string} secret
+ * @param {VerifyTOTPOptions} [options]
+ * @returns {boolean}
+ */
+export function verifyTOTP(token: string, secret: string, options?: VerifyTOTPOptions): boolean;
+/**
+ * The `otpauth://` link to show as a QR code when a user turns on 2FA.
+ *
+ * @example
+ * const uri = crypto.totpURI(user.totpSecret, { label: user.email, issuer: "My App" });
+ *
+ * @param {string} secret
+ * @param {TOTPURIOptions} options
+ * @returns {string}
+ */
+export function totpURI(secret: string, options: TOTPURIOptions): string;
+/**
+ * Secure random bytes.
+ *
+ * @param {number} size
+ * @returns {Buffer}
+ */
+export function randomBytes(size: number): Buffer;
+/**
+ * A secure random integer from `min` to `max`, both included, with no bias.
+ * For anything that has to be fair or unpredictable.
+ *
+ * @example
+ * crypto.randomInt(1, 6);       // a fair dice roll
+ * crypto.randomInt(0, 999_999); // a 6-digit code
+ *
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export function randomInt(min: number, max: number): number;
+/**
+ * Encodes to Base64, or URL-safe Base64.
+ *
+ * @example
+ * crypto.toBase64("héllo");                  // "aMOpbGxv"
+ * crypto.toBase64("héllo", { urlSafe: true });
+ *
+ * @param {string | Buffer | Uint8Array} data
+ * @param {{ urlSafe?: boolean }} [options]
+ * @returns {string}
+ */
+export function toBase64(data: string | Buffer | Uint8Array, options?: {
+    urlSafe?: boolean;
+}): string;
+/**
+ * Decodes Base64 or URL-safe Base64.
+ *
+ * @example
+ * crypto.fromBase64("aMOpbGxv");                     // "héllo"
+ * crypto.fromBase64("aMOpbGxv", { output: "buffer" }); // <Buffer 68 c3 a9 6c 6c 6f>
+ *
+ * @overload
+ * @param {string} text
+ * @param {{ output: "buffer" }} options
+ * @returns {Buffer}
+ */
+export function fromBase64(text: string, options: {
+    output: "buffer";
+}): Buffer;
+/**
+ * Decodes Base64 or URL-safe Base64 into text.
+ *
+ * @overload
+ * @param {string} text
+ * @param {{ output?: "utf8" }} [options]
+ * @returns {string}
+ */
+export function fromBase64(text: string, options?: {
+    output?: "utf8";
+} | undefined): string;
+//# sourceMappingURL=Crypto.d.ts.map

package/types/src/Crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../../src/Crypto.js"],"names":[],"mappings":"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"}

package/types/src/Emitter.d.ts

@@ -0,0 +1,170 @@
+export = Emitter;
+/**
+ * Event names mapped to their arguments, like
+ * `{ ready: [], data: [chunk: Buffer], error: [error: Error] }`.
+ * @typedef {Record<string, any[]>} EventMap
+ */
+/**
+ * Options for `waitFor()`.
+ * @template {any[]} A
+ * @typedef {object} WaitForOptions
+ * @property {number | string} [timeout] Reject with a `TimeoutError` after this long.
+ * @property {AbortSignal} [signal] Reject with an `AbortError` when aborted.
+ * @property {(...args: A) => boolean} [filter] Only resolve for events that pass this test.
+ */
+/**
+ * A typed event emitter. In JavaScript, give the variable a JSDoc type such
+ * as `import("@ix-xs/node-comfort").Emitter<{ ready: [port: number] }>`.
+ *
+ * @template {EventMap} [Events=EventMap]
+ */
+declare class Emitter<Events extends EventMap = EventMap> {
+    /**
+     * Listens to an event.
+     *
+     * @example
+     * const off = emitter.on("data", (chunk) => chunks.push(chunk));
+     * off(); // stop listening
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @param {(...args: Events[K]) => unknown} listener
+     * @returns {() => void} Removes the listener.
+     */
+    on<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => unknown): () => void;
+    /**
+     * Listens to an event once.
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @param {(...args: Events[K]) => unknown} listener
+     * @returns {() => void} Removes the listener if it hasn't run yet.
+     */
+    once<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => unknown): () => void;
+    /**
+     * Listens to every event; the listener gets the event name first. Handy for
+     * logging.
+     *
+     * @example
+     * emitter.onAny((event, ...args) => nc.debug(event, args));
+     *
+     * @param {(event: keyof Events & string, ...args: any[]) => unknown} listener
+     * @returns {() => void} Removes the listener.
+     */
+    onAny(listener: (event: keyof Events & string, ...args: any[]) => unknown): () => void;
+    /**
+     * Removes a listener, or all listeners of the event if you don't pass one.
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @param {(...args: Events[K]) => unknown} [listener]
+     * @returns {this}
+     */
+    off<K extends keyof Events & string>(event: K, listener?: (...args: Events[K]) => unknown): this;
+    /**
+     * Calls the event's listeners right away, in the order they were added.
+     * If one throws, the error propagates, as with Node's `EventEmitter`.
+     *
+     * @example
+     * emitter.emit("message", "hello", "ada");
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @param {Events[K]} args
+     * @returns {boolean} `true` if anyone was listening.
+     */
+    emit<K extends keyof Events & string>(event: K, ...args: Events[K]): boolean;
+    /**
+     * Calls the listeners one at a time, waiting for each, and resolves with
+     * what they returned. Good for hooks that may be async.
+     *
+     * @example
+     * await hooks.emitAsync("beforeSave", record);
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @param {Events[K]} args
+     * @returns {Promise<unknown[]>}
+     */
+    emitAsync<K extends keyof Events & string>(event: K, ...args: Events[K]): Promise<unknown[]>;
+    /**
+     * Waits for the next time the event fires and resolves with its arguments.
+     *
+     * @example
+     * const [code] = await child.waitFor("exit", { timeout: "30s" });
+     * const [text] = await chat.waitFor("message", { filter: (text, from) => from === "ada" });
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @param {WaitForOptions<Events[K]>} [options]
+     * @returns {Promise<Events[K]>}
+     * @throws {TimeoutError}
+     * @throws {AbortError}
+     */
+    waitFor<K extends keyof Events & string>(event: K, options?: WaitForOptions<Events[K]>): Promise<Events[K]>;
+    /**
+     * Loops over an event with `for await`. Events that fire while your loop
+     * body runs are queued, and leaving the loop removes the listener.
+     *
+     * @example
+     * for await (const [job] of queue.iterate("job")) {
+     *   await process(job);
+     * }
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @param {{ signal?: AbortSignal }} [options] Ends the loop when aborted.
+     * @returns {AsyncIterableIterator<Events[K]>}
+     */
+    iterate<K extends keyof Events & string>(event: K, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterableIterator<Events[K]>;
+    /**
+     * How many listeners an event has, or all events together. `onAny`
+     * listeners aren't counted.
+     *
+     * @param {keyof Events & string} [event]
+     * @returns {number}
+     */
+    listenerCount(event?: keyof Events & string): number;
+    /**
+     * The events that have listeners.
+     *
+     * @returns {Array<keyof Events & string>}
+     */
+    eventNames(): Array<keyof Events & string>;
+    /**
+     * Removes all listeners of an event, or everything if you don't name one.
+     *
+     * @param {keyof Events & string} [event]
+     * @returns {this}
+     */
+    clear(event?: keyof Events & string): this;
+    #private;
+}
+declare namespace Emitter {
+    export { EventMap, WaitForOptions };
+}
+/**
+ * Event names mapped to their arguments, like
+ * `{ ready: [], data: [chunk: Buffer], error: [error: Error] }`.
+ */
+type EventMap = Record<string, any[]>;
+/**
+ * Options for `waitFor()`.
+ */
+type WaitForOptions<A extends any[]> = {
+    /**
+     * Reject with a `TimeoutError` after this long.
+     */
+    timeout?: string | number | undefined;
+    /**
+     * Reject with an `AbortError` when aborted.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Only resolve for events that pass this test.
+     */
+    filter?: ((...args: A) => boolean) | undefined;
+};
+//# sourceMappingURL=Emitter.d.ts.map