@mrxsys/mrx-core 2.6.0 → 2.8.0

package/dist/modules/kvStore/types/kvStore.d.ts

@@ -0,0 +1,81 @@
+export interface KvStore {
+    /**
+     * Connect to the store.
+     */
+    connect?(): Promise<void>;
+    /**
+     * Close the connection to the store.
+     */
+    close?(): Promise<void>;
+    /**
+     * Get the value associated with a key.
+     *
+     * @template T - The type of the value to retrieve.
+     *
+     * @param key - The key to retrieve the value for.
+     *
+     * @returns The value associated with the key, or `null` if the key does not exist.
+     */
+    get<T = unknown>(key: string): T | null | Promise<T | null>;
+    /**
+     * Set the value associated with a key.
+     *
+     * @template T - The type of the value to set.
+     *
+     * @param key - The key to set the value for.
+     * @param value - The value to set.
+     * @param ttlSec - The time-to-live for the key, in seconds.
+     */
+    set<T = unknown>(key: string, value: T, ttlSec?: number): void | Promise<void>;
+    /**
+     * Increment the value associated with a key.
+     * Value needs to be a number.
+     *
+     * @param key - The key to increment the value for.
+     * @param amount - The amount to increment by.
+     *
+     * @returns The new value after incrementing.
+     */
+    increment(key: string, amount?: number): number | Promise<number>;
+    /**
+     * Decrement the value associated with a key.
+     * Value needs to be a number.
+     *
+     * @param key - The key to decrement the value for.
+     * @param amount - The amount to decrement by.
+     *
+     * @returns The new value after decrementing.
+     */
+    decrement(key: string, amount?: number): number | Promise<number>;
+    /**
+     * Delete a key from the store.
+     *
+     * @param key - The key to delete.
+     *
+     * @returns `true` if the key was deleted, `false` otherwise.
+     */
+    del(key: string): boolean | Promise<boolean>;
+    /**
+     * Set the expiration time for a key.
+     *
+     * @param key - The key to set the expiration for.
+     * @param ttlSec - The time-to-live for the key, in seconds.
+     *
+     * @returns `true` if the expiration was set, `false` otherwise.
+     */
+    expire(key: string, ttlSec: number): boolean | Promise<boolean>;
+    /**
+     * Get the remaining time-to-live for a key.
+     *
+     * @param key - The key to retrieve the TTL for.
+     *
+     * @returns The remaining time-to-live for the key, in seconds.
+     */
+    ttl(key: string): number | Promise<number>;
+    /**
+     * Clean all keys from the store.
+     *
+     * @returns The number of keys that were removed.
+     */
+    clean(): number | Promise<number>;
+}

package/dist/modules/repository/index.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   Repository
-} from "../../chunk-9wk2pajt.js";
+} from "../../chunk-syhskygx.js";
 import"../../chunk-5qtpggzv.js";
 import"../../chunk-zaje5tv4.js";
 import"../../chunk-683sda6e.js";

package/dist/modules/repository/types/queryOptions.d.ts

@@ -1,3 +1,4 @@
+import type { HTTP_ERROR_STATUS_CODES } from '../../../errors/enums/httpErrorStatusCodes';
 import type { Filter } from './filter';
 import type { OrderByItem } from './orderByItem';
 import type { SelectedFields } from './selectedFields';
@@ -28,7 +29,10 @@ export interface QueryOptions<TModel> {
      * Whether to throw an error if the query does not return any result.
      * @defaultValue false
      */
-    readonly throwIfNoResult?: boolean | string;
+    readonly throwIfNoResult?: boolean | {
+        message?: string;
+        code?: keyof typeof HTTP_ERROR_STATUS_CODES | typeof HTTP_ERROR_STATUS_CODES[keyof typeof HTTP_ERROR_STATUS_CODES];
+    };
     /**
      * The transaction context for the query. ({@link Transaction})
      */

package/dist/modules/totp/enums/index.d.ts

@@ -0,0 +1 @@
+export { TOTP_ERROR_KEYS } from './totpErrorKeys';

package/dist/modules/totp/enums/index.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  TOTP_ERROR_KEYS
+} from "../../../chunk-snqdnkk7.js";
+export {
+  TOTP_ERROR_KEYS
+};

package/dist/modules/totp/enums/totpErrorKeys.d.ts

@@ -0,0 +1,7 @@
+export declare const TOTP_ERROR_KEYS: {
+    readonly INVALID_BASE32_CHARACTER: "totp.error.invalid_base32_character";
+    readonly INVALID_SECRET_LENGTH: "totp.error.invalid_secret_length";
+    readonly INVALID_ALGORITHM: "totp.error.invalid_algorithm";
+    readonly INVALID_OTP_AUTH_URI: "totp.error.invalid_otp_auth_uri";
+    readonly MISSING_SECRET: "totp.error.missing_secret";
+};

package/dist/modules/totp/hotp.d.ts

@@ -0,0 +1,11 @@
+import type { TotpOptions } from './types/totpOptions';
+/**
+ * HMAC-based One-Time Password (HOTP) implementation
+ *
+ * @param secret - Secret key as bytes
+ * @param counter - Counter value
+ * @param opts - HOTP options
+ *
+ * @returns Promise resolving to the HOTP code
+ */
+export declare const hotp: (secret: Uint8Array, counter: number | bigint, { algorithm, digits }?: TotpOptions) => Promise<string>;

package/dist/modules/totp/index.d.ts

@@ -0,0 +1,3 @@
+export { hotp } from './hotp';
+export { buildOtpAuthUri, parseOtpAuthUri } from './otpAuthUri';
+export { totp, verifyTotp } from './totp';

package/dist/modules/totp/index.js

@@ -0,0 +1,110 @@
+// @bun
+import {
+  createCounterBuffer,
+  dynamicTruncation,
+  generateHmac
+} from "../../chunk-4mt568fz.js";
+import {
+  TOTP_ERROR_KEYS
+} from "../../chunk-snqdnkk7.js";
+import {
+  BaseError
+} from "../../chunk-vknq69e0.js";
+
+// source/modules/totp/hotp.ts
+import { webcrypto } from "crypto";
+var hotp = async (secret, counter, {
+  algorithm = "SHA-1",
+  digits = 6
+} = {}) => {
+  const counterBuffer = createCounterBuffer(counter);
+  const key = await webcrypto.subtle.importKey("raw", secret, { name: "HMAC", hash: algorithm }, false, ["sign"]);
+  const hmacArray = await generateHmac(key, counterBuffer);
+  return dynamicTruncation(hmacArray, digits);
+};
+// source/modules/totp/otpAuthUri.ts
+var buildOtpAuthUri = ({
+  secretBase32,
+  label,
+  issuer,
+  algorithm = "SHA-1",
+  digits = 6,
+  period = 30
+}) => {
+  const encodedLabel = encodeURIComponent(label);
+  const encodedIssuer = issuer ? encodeURIComponent(issuer) : undefined;
+  let uri = `otpauth://totp/${encodedLabel}?secret=${secretBase32}`;
+  if (encodedIssuer)
+    uri += `&issuer=${encodedIssuer}`;
+  if (algorithm !== "SHA-1")
+    uri += `&algorithm=${algorithm}`;
+  if (digits !== 6)
+    uri += `&digits=${digits}`;
+  if (period !== 30)
+    uri += `&period=${period}`;
+  return uri;
+};
+var parseOtpAuthUri = (uri) => {
+  const url = new URL(uri);
+  if (url.protocol !== "otpauth:")
+    throw new BaseError({
+      message: TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI
+    });
+  if (url.hostname !== "totp")
+    throw new BaseError({
+      message: TOTP_ERROR_KEYS.INVALID_OTP_AUTH_URI
+    });
+  const label = decodeURIComponent(url.pathname.slice(1));
+  const secretBase32 = url.searchParams.get("secret");
+  if (!secretBase32)
+    throw new BaseError({
+      message: TOTP_ERROR_KEYS.MISSING_SECRET
+    });
+  const issuerParam = url.searchParams.get("issuer");
+  const issuer = issuerParam ? decodeURIComponent(issuerParam) : undefined;
+  const algorithm = url.searchParams.get("algorithm") || "SHA-1";
+  const digits = parseInt(url.searchParams.get("digits") || "6", 10);
+  const period = parseInt(url.searchParams.get("period") || "30", 10);
+  const result = {
+    secretBase32,
+    label,
+    algorithm,
+    digits,
+    period,
+    ...issuer && { issuer }
+  };
+  return result;
+};
+// source/modules/totp/totp.ts
+var totp = async (secret, {
+  algorithm = "SHA-1",
+  digits = 6,
+  period = 30,
+  now = Date.now()
+} = {}) => {
+  const timeStep = Math.floor(now / 1000 / period);
+  return hotp(secret, timeStep, { algorithm, digits });
+};
+var verifyTotp = async (secret, code, {
+  algorithm = "SHA-1",
+  digits = 6,
+  period = 30,
+  window = 0,
+  now = Date.now()
+} = {}) => {
+  const currentTimeStep = Math.floor(now / 1000 / period);
+  for (let i = -window;i <= window; ++i) {
+    const timeStep = currentTimeStep + i;
+    const expectedCode = await hotp(secret, timeStep, { algorithm, digits });
+    if (expectedCode === code)
+      return true;
+  }
+  return false;
+};
+export {
+  verifyTotp,
+  totp,
+  parseOtpAuthUri,
+  hotp,
+  buildOtpAuthUri
+};

package/dist/modules/totp/otpAuthUri.d.ts

@@ -0,0 +1,21 @@
+import type { OtpAuthUri } from './types/otpAuthUri';
+/**
+ * Build an OTPAuth URI for QR code generation
+ *
+ * @param params - URI parameters
+ *
+ * @returns OTPAuth URI string
+ */
+export declare const buildOtpAuthUri: ({ secretBase32, label, issuer, algorithm, digits, period }: OtpAuthUri) => string;
+/**
+ * Parse an OTPAuth URI
+ *
+ * @param uri - OTPAuth URI to parse
+ *
+ * @throws ({@link BaseError}) - if the URI is invalid or missing required parameters
+ *
+ * @returns Parsed URI parameters
+ */
+export declare const parseOtpAuthUri: (uri: string) => Required<Omit<OtpAuthUri, "issuer">> & {
+    issuer?: string;
+};

package/dist/modules/totp/totp.d.ts

@@ -0,0 +1,23 @@
+import type { TotpOptions } from './types/totpOptions';
+import type { VerifyOptions } from './types/verifyOptions';
+/**
+ * Time-based One-Time Password (TOTP) implementation
+ *
+ * @param secret - Secret key as bytes
+ * @param opts - TOTP options including current time
+ *
+ * @returns Promise resolving to the TOTP code
+ */
+export declare const totp: (secret: Uint8Array, { algorithm, digits, period, now }?: TotpOptions & {
+    now?: number;
+}) => Promise<string>;
+/**
+ * Verify a TOTP code against a secret
+ *
+ * @param secret - Secret key as bytes
+ * @param code - Code to verify
+ * @param opts - Verification options
+ *
+ * @returns Promise resolving to true if code is valid
+ */
+export declare const verifyTotp: (secret: Uint8Array, code: string, { algorithm, digits, period, window, now }?: VerifyOptions) => Promise<boolean>;

package/dist/modules/totp/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { OtpAuthUri } from './otpAuthUri';
+export type { TotpOptions } from './totpOptions';
+export type { VerifyOptions } from './verifyOptions';

package/dist/modules/totp/types/index.js

@@ -0,0 +1 @@
+// @bun

package/dist/modules/totp/types/otpAuthUri.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Complete OTPAuth URI data structure
+ */
+export interface OtpAuthUri {
+    /**
+     * Base32 encoded secret
+     */
+    secretBase32: string;
+    /**
+     * Label for the account (usually email or username)
+     */
+    label: string;
+    /**
+     * Issuer name (app/service name)
+     */
+    issuer: string;
+    /**
+     * Hash algorithm
+     *
+     * @defaultValue 'SHA-1'
+     */
+    algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-512';
+    /**
+     * Number of digits
+     *
+     * @defaultValue 6
+     */
+    digits?: 6 | 8;
+    /**
+     * Time period in seconds
+     *
+     * @defaultValue 30
+     */
+    period?: number;
+}

package/dist/modules/totp/types/totpOptions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Options for TOTP/HOTP generation
+ */
+export interface TotpOptions {
+    /**
+     * Hash algorithm to use
+     *
+     * @defaultValue SHA-1
+     */
+    algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-512';
+    /**
+     * Number of digits in the code
+     *
+     * @defaultValue 6
+     */
+    digits?: 6 | 8;
+    /**
+     * Time step in seconds for TOTP
+     *
+     * @defaultValue 30
+     */
+    period?: number;
+}

package/dist/modules/totp/types/verifyOptions.d.ts

@@ -0,0 +1,18 @@
+import type { TotpOptions } from './totpOptions';
+/**
+ * Options for TOTP verification
+ */
+export interface VerifyOptions extends TotpOptions {
+    /**
+     * Time window for verification (±window periods)
+     *
+     * @defaultValue 1
+     */
+    window?: number;
+    /**
+     * Current timestamp in milliseconds
+     *
+     * @defaultValue Date.now()
+     */
+    now?: number;
+}

package/dist/modules/totp/utils/base32.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Encode bytes to Base32 string
+ *
+ * @param input - Bytes or string to encode
+ * @param withPadding - Whether to include padding (default: true)
+ *
+ * @returns Base32 encoded string
+ */
+export declare const base32Encode: (input: string | Uint8Array, withPadding?: boolean) => string;
+/**
+ * Decode Base32 string to bytes
+ *
+ * @param base32 - Base32 string to decode
+ *
+ * @throws ({@link BaseError}) - if invalid Base32 character is found
+ *
+ * @returns Decoded bytes
+ */
+export declare const base32Decode: (base32: string) => Uint8Array;

package/dist/modules/totp/utils/createCounterBuffer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Convert a counter value to an 8-byte big-endian buffer
+ *
+ * @param counter - Counter value as number or bigint
+ *
+ * @returns ArrayBuffer containing the counter in big-endian format
+ */
+export declare const createCounterBuffer: (counter: number | bigint) => ArrayBuffer;

package/dist/modules/totp/utils/dynamicTruncation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Perform dynamic truncation on HMAC result according to RFC 4226
+ *
+ * @param hmacArray - HMAC result as byte array
+ * @param digits - Number of digits in the final code
+ *
+ * @returns Truncated code as string with leading zeros
+ */
+export declare const dynamicTruncation: (hmacArray: Uint8Array, digits: number) => string;

package/dist/modules/totp/utils/generateHmac.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate HMAC for given data using a crypto key
+ *
+ * @param key - Crypto key for HMAC
+ * @param data - Data to sign
+ *
+ * @returns Promise resolving to HMAC as Uint8Array
+ */
+export declare const generateHmac: (key: CryptoKey, data: ArrayBuffer) => Promise<Uint8Array>;

package/dist/modules/totp/utils/generateSecretBytes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generate cryptographically secure random bytes for TOTP secret
+ *
+ * @param length - Number of bytes to generate (default: 20)
+ *
+ * @throws ({@link BaseError}) if length is not positive
+ *
+ * @returns Uint8Array containing the random bytes
+ */
+export declare const generateSecretBytes: (length?: number) => Uint8Array;

package/dist/modules/totp/utils/index.d.ts

@@ -0,0 +1,6 @@
+export { base32Decode, base32Encode } from './base32';
+export { createCounterBuffer } from './createCounterBuffer';
+export { dynamicTruncation } from './dynamicTruncation';
+export { generateHmac } from './generateHmac';
+export { generateSecretBytes } from './generateSecretBytes';
+export { timeRemaining } from './timeRemaining';

package/dist/modules/totp/utils/index.js

@@ -0,0 +1,81 @@
+// @bun
+import {
+  createCounterBuffer,
+  dynamicTruncation,
+  generateHmac
+} from "../../../chunk-4mt568fz.js";
+import {
+  TOTP_ERROR_KEYS
+} from "../../../chunk-snqdnkk7.js";
+import {
+  BaseError
+} from "../../../chunk-vknq69e0.js";
+
+// source/modules/totp/utils/base32.ts
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+var base32Encode = (input, withPadding = true) => {
+  let result = "";
+  let bits = 0;
+  let value = 0;
+  const bytes = input instanceof Uint8Array ? input : new TextEncoder().encode(input);
+  for (const byte of bytes) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      result += BASE32_ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0)
+    result += BASE32_ALPHABET[value << 5 - bits & 31];
+  if (withPadding)
+    while (result.length % 8 !== 0)
+      result += "=";
+  return result;
+};
+var base32Decode = (base32) => {
+  const cleanBase32 = base32.replace(/=+$/, "");
+  if (cleanBase32.length === 0)
+    return new Uint8Array(0);
+  const result = [];
+  let bits = 0;
+  let value = 0;
+  for (const char of cleanBase32) {
+    const charValue = BASE32_ALPHABET.indexOf(char);
+    if (charValue === -1)
+      throw new BaseError({
+        message: TOTP_ERROR_KEYS.INVALID_BASE32_CHARACTER,
+        cause: `Invalid Base32 character: ${char}`
+      });
+    value = value << 5 | charValue;
+    bits += 5;
+    if (bits >= 8) {
+      result.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return new Uint8Array(result);
+};
+// source/modules/totp/utils/generateSecretBytes.ts
+import { getRandomValues } from "crypto";
+var generateSecretBytes = (length = 20) => {
+  if (length <= 0)
+    throw new BaseError({
+      message: TOTP_ERROR_KEYS.INVALID_SECRET_LENGTH
+    });
+  return getRandomValues(new Uint8Array(length));
+};
+// source/modules/totp/utils/timeRemaining.ts
+var timeRemaining = (period = 30, now = Date.now()) => {
+  const elapsed = Math.floor(now / 1000) % period;
+  return period - elapsed;
+};
+export {
+  timeRemaining,
+  generateSecretBytes,
+  generateHmac,
+  dynamicTruncation,
+  createCounterBuffer,
+  base32Encode,
+  base32Decode
+};

package/dist/modules/totp/utils/timeRemaining.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Calculate remaining time until next TOTP code
+ *
+ * @param period - Time period in seconds (default: 30)
+ * @param now - Current timestamp in milliseconds (default: Date.now())
+ *
+ * @returns Seconds remaining until next code
+ */
+export declare const timeRemaining: (period?: number, now?: number) => number;

package/dist/utils/types/index.d.ts

@@ -1 +1,2 @@
+export type { RenameKey } from './renameKey';
 export type { StreamWithAsyncIterable } from './streamWithAsyncIterable';

package/dist/utils/types/renameKey.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Renames a key in an object type while preserving all other properties.
+ *
+ * @template T - The original object type
+ * @template From - The key to rename (must exist in T)
+ * @template To - The new key name
+*/
+export type RenameKey<T, From extends keyof T, To extends PropertyKey> = {
+    [K in keyof T as K extends From ? To : K]: T[K];
+};