@excofy/utils 1.0.12 → 1.0.14

package/.secrets.sample

@@ -0,0 +1 @@
+NPM_TOKEN=

package/dist/index.cjs

@@ -31,6 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createValidator: () => createValidator,
+  cryptoUtils: () => cryptoUtils,
+  generateCode: () => generateCode,
   htmlEntityDecode: () => htmlEntityDecode,
   numberUtils: () => number_exports,
   slugUtils: () => slug_exports,
@@ -644,11 +646,150 @@ function createValidator() {
   };
 }
 
+// src/helpers/generateCode.ts
+var generateCode = (length = 6, alphanumeric = true) => {
+  const digits = "0123456789";
+  const letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+  const charset = alphanumeric ? digits + letters : digits;
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const randomIndex = Math.floor(Math.random() * charset.length);
+    result += charset[randomIndex];
+  }
+  return result;
+};
+
 // src/helpers/string.ts
 var stringUtils = {
   removeFileExtension: (fileName) => fileName.replace(/\.[^/.]+$/, "")
 };
 
+// src/helpers/crypto.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var toBase64 = (buffer) => btoa(String.fromCharCode(...new Uint8Array(buffer)));
+var fromBase64 = (str) => Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
+var signatureKey = async (AUTH_SIGN_SECRET) => crypto.subtle.importKey(
+  "raw",
+  encoder.encode(AUTH_SIGN_SECRET),
+  { name: "HMAC", hash: "SHA-256" },
+  false,
+  ["sign", "verify"]
+);
+var payloadKey = async (AUTH_PAYLOAD_SECRET) => crypto.subtle.importKey(
+  "raw",
+  encoder.encode(AUTH_PAYLOAD_SECRET.substring(0, 32)),
+  { name: "AES-GCM", length: 256 },
+  true,
+  ["encrypt", "decrypt"]
+);
+var encryptPayload = async ({
+  AUTH_PAYLOAD_SECRET,
+  payload
+}) => {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await payloadKey(AUTH_PAYLOAD_SECRET);
+  const buffer = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    encoder.encode(payload)
+  );
+  return `${toBase64(iv)}.${toBase64(buffer)}`;
+};
+var decryptPayload = async ({
+  AUTH_PAYLOAD_SECRET,
+  token
+}) => {
+  const [header, payload] = token.split(".");
+  const key = await payloadKey(AUTH_PAYLOAD_SECRET);
+  const buffer = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: fromBase64(header).buffer },
+    key,
+    fromBase64(payload).buffer
+  );
+  return decoder.decode(buffer);
+};
+var cryptoUtils = {
+  uuidV4: () => crypto.randomUUID(),
+  hash: async (password, salt) => {
+    const importedKey = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(password),
+      { name: "PBKDF2" },
+      false,
+      ["deriveBits"]
+    );
+    const derivedKey = await crypto.subtle.deriveBits(
+      {
+        name: "PBKDF2",
+        salt: encoder.encode(String(salt)),
+        iterations: 1e3,
+        hash: "SHA-256"
+      },
+      importedKey,
+      256
+    );
+    return Array.from(new Uint8Array(derivedKey)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  },
+  isMatch: async (password, hash, salt = 10) => {
+    const hashed = await cryptoUtils.hash(password, salt);
+    return hashed === hash;
+  },
+  generateAccessToken: async ({
+    AUTH_PAYLOAD_SECRET,
+    AUTH_SIGN_SECRET,
+    payload
+  }) => {
+    const key = await signatureKey(AUTH_SIGN_SECRET);
+    const payloadEncrypted = await encryptPayload({
+      AUTH_PAYLOAD_SECRET,
+      payload
+    });
+    const signatureBuffer = await crypto.subtle.sign(
+      "HMAC",
+      key,
+      encoder.encode(payload)
+    );
+    const signature = toBase64(signatureBuffer);
+    return `${payloadEncrypted}.${signature}`;
+  },
+  validateAccessToken: async ({
+    AUTH_PAYLOAD_SECRET,
+    AUTH_SIGN_SECRET,
+    accessToken
+  }) => {
+    let payloadDecrypted;
+    try {
+      const [header, payload, signature] = accessToken.split(".");
+      payloadDecrypted = await decryptPayload({
+        AUTH_PAYLOAD_SECRET,
+        token: `${header}.${payload}`
+      });
+      const key = await signatureKey(AUTH_SIGN_SECRET);
+      const valid = await crypto.subtle.verify(
+        "HMAC",
+        key,
+        fromBase64(signature).buffer,
+        encoder.encode(payloadDecrypted)
+      );
+      if (!valid) throw new Error("Invalid access token");
+    } catch (err) {
+      throw new Error("Invalid access token");
+    }
+    const { expiresAt } = JSON.parse(payloadDecrypted);
+    if (Date.now() > new Date(expiresAt).getTime()) {
+      throw new Error("Expired access token");
+    }
+    return payloadDecrypted;
+  },
+  sha256ToHex: async (data) => {
+    const buffer = await crypto.subtle.digest("SHA-256", encoder.encode(data));
+    return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  },
+  encryptPayload,
+  decryptPayload
+};
+
 // src/helpers/slug.ts
 var slug_exports = {};
 __export(slug_exports, {
@@ -689,6 +830,8 @@ var toDecimal = (value) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createValidator,
+  cryptoUtils,
+  generateCode,
   htmlEntityDecode,
   numberUtils,
   slugUtils,

package/dist/index.d.cts

@@ -85,10 +85,53 @@ declare function createValidator<TRaw extends Record<string, TInputValue>, TPars
     };
 };
 
+/**
+ * Gera um código de validação.
+ *
+ * @param {number} [length=6] - Número de caracteres do código.
+ * @param {boolean} [alphanumeric=true] - Se `true`, gera código alfanumérico (letras e números).
+ *                                         Se `false`, gera apenas dígitos numéricos.
+ * @returns {string} Código gerado.
+ *
+ * @example
+ * generateCode(); // "482901"
+ * generateCode(8); // "83910274"
+ * generateCode(8, true); // "A9F3D2K7"
+ */
+declare const generateCode: (length?: number, alphanumeric?: boolean) => string;
+
 declare const stringUtils: {
     removeFileExtension: (fileName: string) => string;
 };
 
+interface IGenerateAccessToken {
+    AUTH_SIGN_SECRET: string;
+    AUTH_PAYLOAD_SECRET: string;
+    payload: string;
+}
+interface IValidateAccessToken {
+    AUTH_SIGN_SECRET: string;
+    AUTH_PAYLOAD_SECRET: string;
+    accessToken: string;
+}
+interface ICrypto {
+    uuidV4: () => string;
+    hash: (password: string, salt: number) => Promise<string>;
+    isMatch: (password: string, hash: string, salt?: number) => Promise<boolean>;
+    generateAccessToken: (data: IGenerateAccessToken) => Promise<string>;
+    validateAccessToken: (data: IValidateAccessToken) => Promise<string>;
+    sha256ToHex: (data: string) => Promise<string>;
+    encryptPayload: (data: {
+        AUTH_PAYLOAD_SECRET: string;
+        payload: string;
+    }) => Promise<string>;
+    decryptPayload: (data: {
+        AUTH_PAYLOAD_SECRET: string;
+        token: string;
+    }) => Promise<string>;
+}
+declare const cryptoUtils: ICrypto;
+
 /**
  * Generates a unique slug by appending a numeric suffix to the base slug if necessary.
  *
@@ -151,4 +194,4 @@ declare namespace number {
   export { number_toCents as toCents, number_toDecimal as toDecimal };
 }
 
-export { createValidator, htmlEntityDecode, number as numberUtils, slug as slugUtils, stringUtils };
+export { createValidator, cryptoUtils, generateCode, htmlEntityDecode, number as numberUtils, slug as slugUtils, stringUtils };

package/dist/index.d.ts

@@ -85,10 +85,53 @@ declare function createValidator<TRaw extends Record<string, TInputValue>, TPars
     };
 };
 
+/**
+ * Gera um código de validação.
+ *
+ * @param {number} [length=6] - Número de caracteres do código.
+ * @param {boolean} [alphanumeric=true] - Se `true`, gera código alfanumérico (letras e números).
+ *                                         Se `false`, gera apenas dígitos numéricos.
+ * @returns {string} Código gerado.
+ *
+ * @example
+ * generateCode(); // "482901"
+ * generateCode(8); // "83910274"
+ * generateCode(8, true); // "A9F3D2K7"
+ */
+declare const generateCode: (length?: number, alphanumeric?: boolean) => string;
+
 declare const stringUtils: {
     removeFileExtension: (fileName: string) => string;
 };
 
+interface IGenerateAccessToken {
+    AUTH_SIGN_SECRET: string;
+    AUTH_PAYLOAD_SECRET: string;
+    payload: string;
+}
+interface IValidateAccessToken {
+    AUTH_SIGN_SECRET: string;
+    AUTH_PAYLOAD_SECRET: string;
+    accessToken: string;
+}
+interface ICrypto {
+    uuidV4: () => string;
+    hash: (password: string, salt: number) => Promise<string>;
+    isMatch: (password: string, hash: string, salt?: number) => Promise<boolean>;
+    generateAccessToken: (data: IGenerateAccessToken) => Promise<string>;
+    validateAccessToken: (data: IValidateAccessToken) => Promise<string>;
+    sha256ToHex: (data: string) => Promise<string>;
+    encryptPayload: (data: {
+        AUTH_PAYLOAD_SECRET: string;
+        payload: string;
+    }) => Promise<string>;
+    decryptPayload: (data: {
+        AUTH_PAYLOAD_SECRET: string;
+        token: string;
+    }) => Promise<string>;
+}
+declare const cryptoUtils: ICrypto;
+
 /**
  * Generates a unique slug by appending a numeric suffix to the base slug if necessary.
  *
@@ -151,4 +194,4 @@ declare namespace number {
   export { number_toCents as toCents, number_toDecimal as toDecimal };
 }
 
-export { createValidator, htmlEntityDecode, number as numberUtils, slug as slugUtils, stringUtils };
+export { createValidator, cryptoUtils, generateCode, htmlEntityDecode, number as numberUtils, slug as slugUtils, stringUtils };

package/dist/index.js

@@ -610,11 +610,150 @@ function createValidator() {
   };
 }
 
+// src/helpers/generateCode.ts
+var generateCode = (length = 6, alphanumeric = true) => {
+  const digits = "0123456789";
+  const letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+  const charset = alphanumeric ? digits + letters : digits;
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const randomIndex = Math.floor(Math.random() * charset.length);
+    result += charset[randomIndex];
+  }
+  return result;
+};
+
 // src/helpers/string.ts
 var stringUtils = {
   removeFileExtension: (fileName) => fileName.replace(/\.[^/.]+$/, "")
 };
 
+// src/helpers/crypto.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var toBase64 = (buffer) => btoa(String.fromCharCode(...new Uint8Array(buffer)));
+var fromBase64 = (str) => Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
+var signatureKey = async (AUTH_SIGN_SECRET) => crypto.subtle.importKey(
+  "raw",
+  encoder.encode(AUTH_SIGN_SECRET),
+  { name: "HMAC", hash: "SHA-256" },
+  false,
+  ["sign", "verify"]
+);
+var payloadKey = async (AUTH_PAYLOAD_SECRET) => crypto.subtle.importKey(
+  "raw",
+  encoder.encode(AUTH_PAYLOAD_SECRET.substring(0, 32)),
+  { name: "AES-GCM", length: 256 },
+  true,
+  ["encrypt", "decrypt"]
+);
+var encryptPayload = async ({
+  AUTH_PAYLOAD_SECRET,
+  payload
+}) => {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await payloadKey(AUTH_PAYLOAD_SECRET);
+  const buffer = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    encoder.encode(payload)
+  );
+  return `${toBase64(iv)}.${toBase64(buffer)}`;
+};
+var decryptPayload = async ({
+  AUTH_PAYLOAD_SECRET,
+  token
+}) => {
+  const [header, payload] = token.split(".");
+  const key = await payloadKey(AUTH_PAYLOAD_SECRET);
+  const buffer = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: fromBase64(header).buffer },
+    key,
+    fromBase64(payload).buffer
+  );
+  return decoder.decode(buffer);
+};
+var cryptoUtils = {
+  uuidV4: () => crypto.randomUUID(),
+  hash: async (password, salt) => {
+    const importedKey = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(password),
+      { name: "PBKDF2" },
+      false,
+      ["deriveBits"]
+    );
+    const derivedKey = await crypto.subtle.deriveBits(
+      {
+        name: "PBKDF2",
+        salt: encoder.encode(String(salt)),
+        iterations: 1e3,
+        hash: "SHA-256"
+      },
+      importedKey,
+      256
+    );
+    return Array.from(new Uint8Array(derivedKey)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  },
+  isMatch: async (password, hash, salt = 10) => {
+    const hashed = await cryptoUtils.hash(password, salt);
+    return hashed === hash;
+  },
+  generateAccessToken: async ({
+    AUTH_PAYLOAD_SECRET,
+    AUTH_SIGN_SECRET,
+    payload
+  }) => {
+    const key = await signatureKey(AUTH_SIGN_SECRET);
+    const payloadEncrypted = await encryptPayload({
+      AUTH_PAYLOAD_SECRET,
+      payload
+    });
+    const signatureBuffer = await crypto.subtle.sign(
+      "HMAC",
+      key,
+      encoder.encode(payload)
+    );
+    const signature = toBase64(signatureBuffer);
+    return `${payloadEncrypted}.${signature}`;
+  },
+  validateAccessToken: async ({
+    AUTH_PAYLOAD_SECRET,
+    AUTH_SIGN_SECRET,
+    accessToken
+  }) => {
+    let payloadDecrypted;
+    try {
+      const [header, payload, signature] = accessToken.split(".");
+      payloadDecrypted = await decryptPayload({
+        AUTH_PAYLOAD_SECRET,
+        token: `${header}.${payload}`
+      });
+      const key = await signatureKey(AUTH_SIGN_SECRET);
+      const valid = await crypto.subtle.verify(
+        "HMAC",
+        key,
+        fromBase64(signature).buffer,
+        encoder.encode(payloadDecrypted)
+      );
+      if (!valid) throw new Error("Invalid access token");
+    } catch (err) {
+      throw new Error("Invalid access token");
+    }
+    const { expiresAt } = JSON.parse(payloadDecrypted);
+    if (Date.now() > new Date(expiresAt).getTime()) {
+      throw new Error("Expired access token");
+    }
+    return payloadDecrypted;
+  },
+  sha256ToHex: async (data) => {
+    const buffer = await crypto.subtle.digest("SHA-256", encoder.encode(data));
+    return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  },
+  encryptPayload,
+  decryptPayload
+};
+
 // src/helpers/slug.ts
 var slug_exports = {};
 __export(slug_exports, {
@@ -654,6 +793,8 @@ var toDecimal = (value) => {
 };
 export {
   createValidator,
+  cryptoUtils,
+  generateCode,
   htmlEntityDecode,
   number_exports as numberUtils,
   slug_exports as slugUtils,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excofy/utils",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Biblioteca de utilitários para o Excofy",
   "main": "dist/index.js",
   "type": "module",
@@ -15,7 +15,8 @@
     "lint": "biome lint",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
-    "deploy": "act"
+    "deploy": "act",
+    "test": "tsx --test 'tests/**/*.spec.ts' --testTimeout=10000"
   },
   "repository": {
     "type": "git",
@@ -33,6 +34,7 @@
     "@types/big.js": "^6.2.2",
     "@types/node": "^24.0.3",
     "tsup": "^8.5.0",
+    "tsx": "^4.20.4",
     "typescript": "^5.8.3"
   },
   "dependencies": {

package/src/helpers/crypto.ts

@@ -0,0 +1,202 @@
+interface IGenerateAccessToken {
+  AUTH_SIGN_SECRET: string;
+  AUTH_PAYLOAD_SECRET: string;
+  payload: string;
+}
+
+interface IValidateAccessToken {
+  AUTH_SIGN_SECRET: string;
+  AUTH_PAYLOAD_SECRET: string;
+  accessToken: string;
+}
+
+interface ICrypto {
+  uuidV4: () => string;
+  hash: (password: string, salt: number) => Promise<string>;
+  isMatch: (password: string, hash: string, salt?: number) => Promise<boolean>;
+  generateAccessToken: (data: IGenerateAccessToken) => Promise<string>;
+  validateAccessToken: (data: IValidateAccessToken) => Promise<string>;
+  sha256ToHex: (data: string) => Promise<string>;
+  encryptPayload: (data: {
+    AUTH_PAYLOAD_SECRET: string;
+    payload: string;
+  }) => Promise<string>;
+  decryptPayload: (data: {
+    AUTH_PAYLOAD_SECRET: string;
+    token: string;
+  }) => Promise<string>;
+}
+
+/* --------------------- Helpers básicos --------------------- */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+const toBase64 = (buffer: ArrayBuffer | Uint8Array): string =>
+  btoa(String.fromCharCode(...new Uint8Array(buffer)));
+
+const fromBase64 = (str: string): Uint8Array =>
+  Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
+
+const signatureKey = async (AUTH_SIGN_SECRET: string) =>
+  crypto.subtle.importKey(
+    'raw',
+    encoder.encode(AUTH_SIGN_SECRET),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify']
+  );
+
+const payloadKey = async (AUTH_PAYLOAD_SECRET: string) =>
+  crypto.subtle.importKey(
+    'raw',
+    encoder.encode(AUTH_PAYLOAD_SECRET.substring(0, 32)),
+    { name: 'AES-GCM', length: 256 },
+    true,
+    ['encrypt', 'decrypt']
+  );
+
+/* --------------------- Payload (encrypt/decrypt) --------------------- */
+const encryptPayload = async ({
+  AUTH_PAYLOAD_SECRET,
+  payload,
+}: {
+  AUTH_PAYLOAD_SECRET: string;
+  payload: string;
+}): Promise<string> => {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await payloadKey(AUTH_PAYLOAD_SECRET);
+
+  const buffer = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    encoder.encode(payload)
+  );
+
+  return `${toBase64(iv)}.${toBase64(buffer)}`;
+};
+
+const decryptPayload = async ({
+  AUTH_PAYLOAD_SECRET,
+  token,
+}: {
+  AUTH_PAYLOAD_SECRET: string;
+  token: string;
+}): Promise<string> => {
+  const [header, payload] = token.split('.');
+  const key = await payloadKey(AUTH_PAYLOAD_SECRET);
+
+  const buffer = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv: fromBase64(header).buffer as ArrayBuffer },
+    key,
+    fromBase64(payload).buffer as ArrayBuffer
+  );
+
+  return decoder.decode(buffer);
+};
+
+/* --------------------- Main API --------------------- */
+export const cryptoUtils: ICrypto = {
+  uuidV4: (): string => crypto.randomUUID(),
+
+  hash: async (password: string, salt: number): Promise<string> => {
+    const importedKey = await crypto.subtle.importKey(
+      'raw',
+      encoder.encode(password),
+      { name: 'PBKDF2' },
+      false,
+      ['deriveBits']
+    );
+
+    const derivedKey = await crypto.subtle.deriveBits(
+      {
+        name: 'PBKDF2',
+        salt: encoder.encode(String(salt)),
+        iterations: 1000,
+        hash: 'SHA-256',
+      },
+      importedKey,
+      256
+    );
+
+    return Array.from(new Uint8Array(derivedKey))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  },
+
+  isMatch: async (password, hash, salt = 10): Promise<boolean> => {
+    const hashed = await cryptoUtils.hash(password, salt);
+    return hashed === hash;
+  },
+
+  generateAccessToken: async ({
+    AUTH_PAYLOAD_SECRET,
+    AUTH_SIGN_SECRET,
+    payload,
+  }) => {
+    const key = await signatureKey(AUTH_SIGN_SECRET);
+
+    // cifra payload
+    const payloadEncrypted = await encryptPayload({
+      AUTH_PAYLOAD_SECRET,
+      payload,
+    });
+
+    // assinatura
+    const signatureBuffer = await crypto.subtle.sign(
+      'HMAC',
+      key,
+      encoder.encode(payload)
+    );
+    const signature = toBase64(signatureBuffer);
+
+    return `${payloadEncrypted}.${signature}`;
+  },
+
+  validateAccessToken: async ({
+    AUTH_PAYLOAD_SECRET,
+    AUTH_SIGN_SECRET,
+    accessToken,
+  }) => {
+    let payloadDecrypted: string;
+
+    try {
+      const [header, payload, signature] = accessToken.split('.');
+
+      payloadDecrypted = await decryptPayload({
+        AUTH_PAYLOAD_SECRET,
+        token: `${header}.${payload}`,
+      });
+
+      const key = await signatureKey(AUTH_SIGN_SECRET);
+      const valid = await crypto.subtle.verify(
+        'HMAC',
+        key,
+        fromBase64(signature).buffer as ArrayBuffer,
+        encoder.encode(payloadDecrypted)
+      );
+
+      if (!valid) throw new Error('Invalid access token');
+    } catch (err) {
+      // qualquer falha na decriptação ou verificação -> token inválido
+      throw new Error('Invalid access token');
+    }
+
+    // verifica expiração **fora do try/catch**, para não ser capturada como token inválido
+    const { expiresAt } = JSON.parse(payloadDecrypted);
+    if (Date.now() > new Date(expiresAt).getTime()) {
+      throw new Error('Expired access token');
+    }
+
+    return payloadDecrypted;
+  },
+
+  sha256ToHex: async (data: string): Promise<string> => {
+    const buffer = await crypto.subtle.digest('SHA-256', encoder.encode(data));
+    return Array.from(new Uint8Array(buffer))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  },
+
+  encryptPayload,
+  decryptPayload,
+};

package/src/helpers/generateCode.ts

@@ -0,0 +1,26 @@
+/**
+ * Gera um código de validação.
+ *
+ * @param {number} [length=6] - Número de caracteres do código.
+ * @param {boolean} [alphanumeric=true] - Se `true`, gera código alfanumérico (letras e números).
+ *                                         Se `false`, gera apenas dígitos numéricos.
+ * @returns {string} Código gerado.
+ *
+ * @example
+ * generateCode(); // "482901"
+ * generateCode(8); // "83910274"
+ * generateCode(8, true); // "A9F3D2K7"
+ */
+export const generateCode = (length = 6, alphanumeric = true): string => {
+  const digits = '0123456789';
+  const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+  const charset = alphanumeric ? digits + letters : digits;
+
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    const randomIndex = Math.floor(Math.random() * charset.length);
+    result += charset[randomIndex];
+  }
+
+  return result;
+};

package/src/index.ts

@@ -1,6 +1,8 @@
 import { createValidator } from './helpers/validator';
 import { htmlEntityDecode } from './helpers/sanitize';
+import { generateCode } from './helpers/generateCode';
 import { stringUtils } from './helpers/string';
+import { cryptoUtils } from './helpers/crypto';
 import * as slugUtils from './helpers/slug';
 import * as numberUtils from './helpers/number';
 
@@ -10,4 +12,6 @@ export {
   slugUtils,
   numberUtils,
   stringUtils,
+  cryptoUtils,
+  generateCode,
 };

package/tests/helpers/webCrypto.spec.ts

@@ -0,0 +1,126 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { cryptoUtils } from '../../src/helpers/crypto';
+
+const AUTH_SIGN_SECRET = '12345678901234567890123456789012'; // 32 chars
+const AUTH_PAYLOAD_SECRET = 'abcdefghijklmnopqrstuvxz12345678'; // 32 chars
+
+describe('cryptoUtils helper', () => {
+  it('uuidV4 deve gerar um UUID válido', () => {
+    const id = cryptoUtils.uuidV4();
+    assert.match(
+      id,
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+    );
+  });
+
+  it('hash e isMatch devem funcionar corretamente', async () => {
+    const password = 'mypassword';
+    const salt = 1234;
+    const hashed = await cryptoUtils.hash(password, salt);
+
+    assert.equal(await cryptoUtils.isMatch(password, hashed, salt), true);
+    assert.equal(
+      await cryptoUtils.isMatch('wrongpassword', hashed, salt),
+      false
+    );
+  });
+
+  it('encryptPayload e decryptPayload devem ser inversos', async () => {
+    const payload = JSON.stringify({ foo: 'bar' });
+
+    const encrypted = await cryptoUtils.encryptPayload({
+      AUTH_PAYLOAD_SECRET,
+      payload,
+    });
+
+    const decrypted = await cryptoUtils.decryptPayload({
+      AUTH_PAYLOAD_SECRET,
+      token: encrypted,
+    });
+
+    assert.equal(decrypted, payload);
+  });
+
+  it('sha256ToHex deve gerar hash esperado', async () => {
+    const data = 'hello';
+    const hash = await cryptoUtils.sha256ToHex(data);
+
+    // hash SHA-256 conhecido de "hello"
+    assert.equal(
+      hash,
+      '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+    );
+  });
+
+  it('generateAccessToken e validateAccessToken devem funcionar', async () => {
+    const payload = JSON.stringify({
+      userId: 42,
+      expiresAt: new Date(Date.now() + 1000 * 60).toISOString(), // +1 min
+    });
+
+    const token = await cryptoUtils.generateAccessToken({
+      AUTH_SIGN_SECRET,
+      AUTH_PAYLOAD_SECRET,
+      payload,
+    });
+
+    const decrypted = await cryptoUtils.validateAccessToken({
+      AUTH_SIGN_SECRET,
+      AUTH_PAYLOAD_SECRET,
+      accessToken: token,
+    });
+
+    assert.equal(decrypted, payload);
+  });
+
+  it('validateAccessToken deve falhar com token expirado', async () => {
+    const payload = JSON.stringify({
+      userId: 42,
+      expiresAt: new Date(Date.now() - 1000).toISOString(), // já expirado
+    });
+
+    const token = await cryptoUtils.generateAccessToken({
+      AUTH_SIGN_SECRET,
+      AUTH_PAYLOAD_SECRET,
+      payload,
+    });
+
+    await assert.rejects(
+      () =>
+        cryptoUtils.validateAccessToken({
+          AUTH_SIGN_SECRET,
+          AUTH_PAYLOAD_SECRET,
+          accessToken: token,
+        }),
+      /Expired access token/
+    );
+  });
+
+  it('validateAccessToken deve falhar com assinatura inválida', async () => {
+    const payload = JSON.stringify({
+      userId: 42,
+      expiresAt: new Date(Date.now() + 1000 * 60).toISOString(),
+    });
+
+    const token = await cryptoUtils.generateAccessToken({
+      AUTH_SIGN_SECRET,
+      AUTH_PAYLOAD_SECRET,
+      payload,
+    });
+
+    // altera assinatura (última parte do token)
+    const [header, body, signature] = token.split('.');
+    const tamperedToken = `${header}.${body}.${signature.slice(1)}A`;
+
+    await assert.rejects(
+      () =>
+        cryptoUtils.validateAccessToken({
+          AUTH_SIGN_SECRET,
+          AUTH_PAYLOAD_SECRET,
+          accessToken: tamperedToken,
+        }),
+      /Invalid access token/
+    );
+  });
+});

package/tsconfig.json

@@ -13,6 +13,6 @@
     "resolveJsonModule": true,
     "isolatedModules": true
   },
-  "include": ["src"],
+  "include": ["src", "tests"],
   "exclude": ["dist", "node_modules", "**/*.test.ts"]
 }