@catbee/utils 1.1.0 → 2.0.0-next.1

package/context-store/index.mjs

@@ -0,0 +1,261 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var StoreKeys = {
+  LOGGER: Symbol("LOGGER"),
+  REQUEST_ID: Symbol("REQUEST_ID"),
+  USER: Symbol("USER"),
+  SESSION: Symbol("SESSION"),
+  TRANSACTION_ID: Symbol("TRANSACTION_ID"),
+  USER_ID: Symbol("USER_ID"),
+  TENANT_ID: Symbol("TENANT_ID"),
+  TRACE_ID: Symbol("TRACE_ID"),
+  CORRELATION_ID: Symbol("CORRELATION_ID")
+};
+function getRequestId() {
+  return ContextStore.get(StoreKeys.REQUEST_ID);
+}
+__name(getRequestId, "getRequestId");
+function getFromContext(key) {
+  return ContextStore.get(key);
+}
+__name(getFromContext, "getFromContext");
+var ContextStore = class _ContextStore {
+  static {
+    __name(this, "ContextStore");
+  }
+  /**
+  * The underlying AsyncLocalStorage instance for context.
+  * @private
+  */
+  static storage = new AsyncLocalStorage();
+  /**
+  * Returns the raw AsyncLocalStorage instance for advanced access.
+  *
+  * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.
+  */
+  static getInstance() {
+    return this.storage;
+  }
+  /**
+  * Retrieves a value from the async context store by symbol key.
+  *
+  * @typeParam T - The expected return type of the value.
+  * @param {symbol} key - Unique symbol used as the store key.
+  * @returns {T | undefined} The value found (typed) or undefined if not present.
+  */
+  static get(key) {
+    const store = this.storage.getStore();
+    return store?.[key];
+  }
+  /**
+  * Sets a value in the current context store by symbol key.
+  *
+  * @typeParam T - The value type to set.
+  * @param {symbol} key - Unique symbol key.
+  * @param {T} value - Value to set in context.
+  * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).
+  */
+  static set(key, value) {
+    const store = this.storage.getStore();
+    if (!store) {
+      throw new Error(`Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`);
+    }
+    store[key] = value;
+  }
+  /**
+  * Retrieves the entire context store object for the current async context.
+  *
+  * @returns {Store | undefined} The current store object or undefined if called outside a context.
+  */
+  static getAll() {
+    return this.storage.getStore();
+  }
+  /**
+  * Initializes a new async context and executes a callback within it.
+  * This must be called at the beginning of a request or logical async flow.
+  *
+  * @typeParam T - The callback's return type.
+  * @param {Store} store - The initial key-value store object.
+  * @param {() => T} callback - The function to run within the new context.
+  * @returns {T} The result of the callback function.
+  */
+  static run(store, callback) {
+    return this.storage.run(store, callback);
+  }
+  /**
+  * Checks if a key exists in the current context store.
+  *
+  * @param {symbol} key - The symbol key to check.
+  * @returns {boolean} True if the key exists, false otherwise.
+  */
+  static has(key) {
+    const store = this.storage.getStore();
+    return store !== void 0 && key in store;
+  }
+  /**
+  * Removes a value from the current context store by symbol key.
+  *
+  * @param {symbol} key - The symbol key to delete.
+  * @returns {boolean} True if the key was deleted, false if the key wasn't found or no active context.
+  * @throws {Error} If called outside an active context.
+  */
+  static delete(key) {
+    const store = this.storage.getStore();
+    if (!store) {
+      throw new Error(`Failed to delete ${String(key)}: AsyncLocalStorage store is not initialized.`);
+    }
+    return delete store[key];
+  }
+  /**
+  * Updates multiple values in the current context store at once.
+  *
+  * @param {Partial<Record<symbol, unknown>>} values - Object containing symbol keys and values to update.
+  * @throws {Error} If called outside an active context.
+  */
+  static patch(values) {
+    const store = this.storage.getStore();
+    if (!store) {
+      throw new Error("Failed to patch: AsyncLocalStorage store is not initialized.");
+    }
+    Object.getOwnPropertySymbols(values).forEach((key) => {
+      store[key] = values[key];
+    });
+  }
+  /**
+  * Executes a callback with a temporary store value that only exists during execution.
+  * Original store is restored after callback completes.
+  *
+  * @typeParam T - The callback's return type.
+  * @param {symbol} key - The symbol key to temporarily set.
+  * @param {unknown} value - The temporary value.
+  * @param {() => T} callback - The function to execute with the temporary value.
+  * @returns {T} The result of the callback function.
+  * @throws {Error} If called outside an active context.
+  */
+  static withValue(key, value, callback) {
+    const store = this.storage.getStore();
+    if (!store) {
+      throw new Error(`Failed to set temporary value: AsyncLocalStorage store is not initialized.`);
+    }
+    const hasOriginal = key in store;
+    const originalValue = store[key];
+    store[key] = value;
+    try {
+      return callback();
+    } finally {
+      if (hasOriginal) {
+        store[key] = originalValue;
+      } else {
+        delete store[key];
+      }
+    }
+  }
+  /**
+  * Creates a new context that inherits values from the current context.
+  *
+  * @typeParam T - The callback's return type.
+  * @param {Partial<Record<symbol, unknown>>} newValues - New values to add to or override in the context.
+  * @param {() => T} callback - The function to execute in the new context.
+  * @returns {T} The result of the callback function.
+  */
+  static extend(newValues, callback) {
+    const currentStore = this.storage.getStore() || {};
+    const newStore = {
+      ...currentStore
+    };
+    Object.getOwnPropertySymbols(newValues).forEach((key) => {
+      newStore[key] = newValues[key];
+    });
+    return this.storage.run(newStore, callback);
+  }
+  /**
+  * Creates Express middleware that initializes a context for each request.
+  *
+  * @param {(req: any) => Partial<Record<symbol, unknown>>} initialValuesFactory - Function that returns initial context values.
+  * @returns Express middleware function.
+  */
+  static createExpressMiddleware(initialValuesFactory = () => ({})) {
+    return (req, _res, next) => {
+      const initialValues = initialValuesFactory(req);
+      _ContextStore.run(initialValues, next);
+    };
+  }
+};
+var TypedContextKey = class {
+  static {
+    __name(this, "TypedContextKey");
+  }
+  symbol;
+  defaultValue;
+  /**
+  * Creates a new typed context key.
+  *
+  * @param symbol - The unique symbol for this key
+  * @param defaultValue - Optional default value if key is not found
+  */
+  constructor(symbol, defaultValue) {
+    this.symbol = symbol;
+    this.defaultValue = defaultValue;
+  }
+  /**
+  * Gets the current value for this key.
+  *
+  * @returns The value or defaultValue if not found
+  */
+  get() {
+    const value = ContextStore.get(this.symbol);
+    return value !== void 0 ? value : this.defaultValue;
+  }
+  /**
+  * Sets the value for this key.
+  *
+  * @param value The value to set
+  */
+  set(value) {
+    ContextStore.set(this.symbol, value);
+  }
+  /**
+  * Checks if this key exists in the context.
+  *
+  * @returns True if the key exists
+  */
+  exists() {
+    return ContextStore.has(this.symbol);
+  }
+  /**
+  * Deletes this key from the context.
+  *
+  * @returns True if the key was deleted
+  */
+  delete() {
+    return ContextStore.delete(this.symbol);
+  }
+};
+
+export { ContextStore, StoreKeys, TypedContextKey, getFromContext, getRequestId };

package/crypto/index.cjs

@@ -0,0 +1,182 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+'use strict';
+
+var crypto = require('crypto');
+var util = require('util');
+var id = require('@catbee/utils/id');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function hmac(algorithm, input, secret, encoding = "hex") {
+  return crypto.createHmac(algorithm, secret).update(input).digest(encoding);
+}
+__name(hmac, "hmac");
+function hash(algorithm, input, encoding = "hex") {
+  return crypto.createHash(algorithm).update(input).digest(encoding);
+}
+__name(hash, "hash");
+function sha256Hmac(input, secret) {
+  return hmac("sha256", input, secret);
+}
+__name(sha256Hmac, "sha256Hmac");
+function sha1(input, encoding = "hex") {
+  return hash("sha1", input, encoding);
+}
+__name(sha1, "sha1");
+function sha256(input, encoding = "hex") {
+  return hash("sha256", input, encoding);
+}
+__name(sha256, "sha256");
+function md5(input) {
+  return hash("md5", input);
+}
+__name(md5, "md5");
+function randomString() {
+  return sha256(id.uuid());
+}
+__name(randomString, "randomString");
+function generateRandomBytes(byteLength = 32) {
+  return crypto.randomBytes(byteLength);
+}
+__name(generateRandomBytes, "generateRandomBytes");
+function generateRandomBytesAsString(byteLength = 32, encoding = "hex") {
+  return crypto.randomBytes(byteLength).toString(encoding);
+}
+__name(generateRandomBytesAsString, "generateRandomBytesAsString");
+function generateApiKey(prefix = "", byteLength = 24) {
+  const randomString2 = generateRandomBytesAsString(byteLength, "base64");
+  const key = randomString2.replace(/[+/=]/g, "").substring(0, 32);
+  return prefix ? `${prefix}_${key}` : key;
+}
+__name(generateApiKey, "generateApiKey");
+function safeCompare(a, b) {
+  if (typeof a === "string" && typeof b === "string") {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) return false;
+    return crypto.timingSafeEqual(bufA, bufB);
+  } else if ((a instanceof Buffer || a instanceof Uint8Array) && (b instanceof Buffer || b instanceof Uint8Array)) {
+    if (a.length !== b.length) return false;
+    return crypto.timingSafeEqual(a instanceof Buffer ? a : Buffer.from(a), b instanceof Buffer ? b : Buffer.from(b));
+  }
+  throw new Error("Cannot compare: inputs must be strings, Buffers, or Uint8Arrays");
+}
+__name(safeCompare, "safeCompare");
+var scryptAsync = util.promisify(crypto.scrypt);
+async function encrypt(data, key, options = {}) {
+  const algorithm = options.algorithm || "aes-256-gcm";
+  const inputEncoding = options.inputEncoding || "utf8";
+  const outputEncoding = options.outputEncoding || "hex";
+  const iv = crypto.randomBytes(16);
+  const derivedKey = typeof key === "string" ? await scryptAsync(key, iv.slice(0, 8), 32) : key;
+  const cipher = crypto.createCipheriv(algorithm, derivedKey, iv);
+  let ciphertext;
+  if (typeof data === "string") {
+    ciphertext = cipher.update(data, inputEncoding, outputEncoding);
+    ciphertext += cipher.final(outputEncoding);
+  } else {
+    const encrypted = Buffer.concat([
+      cipher.update(data),
+      cipher.final()
+    ]);
+    ciphertext = encrypted.toString(outputEncoding) ;
+  }
+  const authTag = algorithm.includes("gcm") ? cipher.getAuthTag() : void 0;
+  return {
+    ciphertext,
+    iv,
+    authTag,
+    algorithm
+  };
+}
+__name(encrypt, "encrypt");
+async function decrypt(encryptedData, key, options = {}) {
+  const algorithm = options.algorithm || encryptedData.algorithm || "aes-256-gcm";
+  const inputEncoding = options.inputEncoding || "hex";
+  const outputEncoding = options.outputEncoding || "utf8";
+  const derivedKey = typeof key === "string" ? await scryptAsync(key, encryptedData.iv.slice(0, 8), 32) : key;
+  const decipher = crypto.createDecipheriv(algorithm, derivedKey, encryptedData.iv);
+  if (encryptedData.authTag && algorithm.includes("gcm")) {
+    decipher.setAuthTag(encryptedData.authTag);
+  }
+  let decrypted;
+  if (typeof encryptedData.ciphertext === "string") {
+    decrypted = decipher.update(encryptedData.ciphertext, inputEncoding, outputEncoding);
+    decrypted += decipher.final(outputEncoding);
+  } else {
+    const result = Buffer.concat([
+      decipher.update(encryptedData.ciphertext),
+      decipher.final()
+    ]);
+    decrypted = result.toString(outputEncoding) ;
+  }
+  return decrypted;
+}
+__name(decrypt, "decrypt");
+function createSignedToken(payload, secret, expiresInSeconds = 3600) {
+  const tokenPayload = {
+    ...payload,
+    exp: Math.floor(Date.now() / 1e3) + expiresInSeconds
+  };
+  const payloadStr = JSON.stringify(tokenPayload);
+  const base64Payload = Buffer.from(payloadStr).toString("base64url");
+  const signature = hmac("sha256", base64Payload, secret, "base64url");
+  return `${base64Payload}.${signature}`;
+}
+__name(createSignedToken, "createSignedToken");
+function verifySignedToken(token, secret) {
+  try {
+    const [payloadB64, signature] = token.split(".");
+    if (!payloadB64 || !signature) return null;
+    const expectedSignature = hmac("sha256", payloadB64, secret, "base64url");
+    if (!safeCompare(signature, expectedSignature)) return null;
+    const payloadStr = Buffer.from(payloadB64, "base64url").toString("utf8");
+    const payload = JSON.parse(payloadStr);
+    if (payload.exp && payload.exp < Math.floor(Date.now() / 1e3)) {
+      return null;
+    }
+    return payload;
+  } catch {
+    return null;
+  }
+}
+__name(verifySignedToken, "verifySignedToken");
+
+exports.createSignedToken = createSignedToken;
+exports.decrypt = decrypt;
+exports.encrypt = encrypt;
+exports.generateApiKey = generateApiKey;
+exports.generateRandomBytes = generateRandomBytes;
+exports.generateRandomBytesAsString = generateRandomBytesAsString;
+exports.hash = hash;
+exports.hmac = hmac;
+exports.md5 = md5;
+exports.randomString = randomString;
+exports.safeCompare = safeCompare;
+exports.sha1 = sha1;
+exports.sha256 = sha256;
+exports.sha256Hmac = sha256Hmac;
+exports.verifySignedToken = verifySignedToken;

package/crypto/index.d.ts

@@ -0,0 +1,187 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { BinaryToTextEncoding, CipherGCMTypes } from 'node:crypto';
+
+type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'utf-16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
+/**
+ * Generates an HMAC digest using the specified algorithm and secret key.
+ *
+ * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'sha1').
+ * @param {string} input - The string to hash.
+ * @param {string} secret - The secret key for HMAC.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
+ * @returns {string} HMAC digest as a string.
+ */
+declare function hmac(algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates a hash digest using the specified algorithm.
+ *
+ * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'md5').
+ * @param {string} input - The string to hash.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
+ * @returns {string} Hash digest as a string.
+ */
+declare function hash(algorithm: string, input: string, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates an HMAC-SHA256 digest.
+ *
+ * @param {string} input - The string to hash.
+ * @param {string} secret - The secret key.
+ * @returns {string} SHA-256 HMAC digest as a string.
+ */
+declare function sha256Hmac(input: string, secret: string): string;
+/**
+ * Generates a SHA1 hash digest.
+ *
+ * @param {string} input - The string to hash.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} SHA-1 hash as a string.
+ */
+declare function sha1(input: string, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates a SHA256 hash digest.
+ *
+ * @param {string} input - The string to hash.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} SHA-256 hash as a string.
+ */
+declare function sha256(input: string, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates an MD5 hash digest.
+ *
+ * @param {string} input - The string to hash.
+ * @returns {string} MD5 hash as a string.
+ */
+declare function md5(input: string): string;
+/**
+ * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.
+ *
+ * @returns {string} Random string hashed with SHA-256 (hex encoding).
+ */
+declare function randomString(): string;
+/**
+ * Generates a secure random buffer of specified byte length.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @returns {Buffer} Buffer containing random bytes.
+ */
+declare function generateRandomBytes(byteLength?: number): Buffer;
+/**
+ * Generates a secure random string of specified byte length with specified encoding.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} Random string in specified encoding.
+ */
+declare function generateRandomBytesAsString(byteLength?: number, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates a secure API key with a specified format.
+ *
+ * @param {string} [prefix=''] - Optional prefix for the key.
+ * @param {number} [byteLength=24] - Number of random bytes to generate.
+ * @returns {string} Formatted API key.
+ */
+declare function generateApiKey(prefix?: string, byteLength?: number): string;
+/**
+ * Compares two strings, arrays, or buffers in constant time to prevent timing attacks.
+ *
+ * @param {string | Buffer | Uint8Array} a - First value to compare
+ * @param {string | Buffer | Uint8Array} b - Second value to compare
+ * @returns {boolean} True if values are equal
+ */
+declare function safeCompare(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
+/**
+ * Interface for encryption options
+ */
+interface EncryptionOptions {
+    /** Algorithm to use (default: aes-256-gcm) */
+    algorithm?: CipherGCMTypes;
+    /** Input encoding for plaintext if string (default: utf8) */
+    inputEncoding?: BufferEncoding;
+    /** Output encoding for ciphertext (default: hex) */
+    outputEncoding?: BinaryToTextEncoding;
+}
+/**
+ * Interface for decryption options
+ */
+interface DecryptionOptions {
+    /** Algorithm to use (default: aes-256-gcm) */
+    algorithm?: CipherGCMTypes;
+    /** Input encoding for ciphertext if string (default: hex) */
+    inputEncoding?: BinaryToTextEncoding;
+    /** Output encoding for plaintext (default: utf8) */
+    outputEncoding?: BufferEncoding;
+}
+/**
+ * Result of encryption operation including all data needed for decryption
+ */
+interface EncryptionResult {
+    /** Encrypted data (string or Buffer based on options) */
+    ciphertext: string | Buffer;
+    /** Initialization vector */
+    iv: Buffer;
+    /** Authentication tag (for GCM mode) */
+    authTag?: Buffer;
+    /** Algorithm used */
+    algorithm: string;
+}
+/**
+ * Encrypts data using a symmetric key with secure defaults (AES-256-GCM).
+ *
+ * @param {string | Buffer} data - Data to encrypt
+ * @param {string | Buffer} key - Encryption key or passphrase
+ * @param {EncryptionOptions} [options] - Encryption options
+ * @returns {Promise<EncryptionResult>} Encrypted data with metadata
+ */
+declare function encrypt(data: string | Buffer, key: string | Buffer, options?: EncryptionOptions): Promise<EncryptionResult>;
+/**
+ * Decrypts data that was encrypted with the encrypt function.
+ *
+ * @param {EncryptionResult} encryptedData - The encrypted data and metadata
+ * @param {string | Buffer} key - Decryption key or passphrase
+ * @param {DecryptionOptions} [options] - Decryption options
+ * @returns {Promise<string | Buffer>} Decrypted data
+ */
+declare function decrypt(encryptedData: EncryptionResult, key: string | Buffer, options?: DecryptionOptions): Promise<string | Buffer>;
+/**
+ * Creates a signed token with an expiration time and payload.
+ *
+ * @param {object} payload - Data to include in the token
+ * @param {string} secret - Secret key for signing
+ * @param {number} [expiresInSeconds=3600] - Token expiration in seconds
+ * @returns {string} Signed token string
+ */
+declare function createSignedToken(payload: Record<string, any>, secret: string, expiresInSeconds?: number): string;
+/**
+ * Verifies and decodes a signed token.
+ *
+ * @param {string} token - The token to verify
+ * @param {string} secret - Secret key for verification
+ * @returns {object | null} Decoded payload if valid, null if invalid
+ */
+declare function verifySignedToken(token: string, secret: string): Record<string, any> | null;
+
+export { createSignedToken, decrypt, encrypt, generateApiKey, generateRandomBytes, generateRandomBytesAsString, hash, hmac, md5, randomString, safeCompare, sha1, sha256, sha256Hmac, verifySignedToken };
+export type { BufferEncoding, DecryptionOptions, EncryptionOptions, EncryptionResult };