@cosmixclub/crypto

Este pacote fornece funções robustas de criptografia e descriptografia utilizando o algoritmo AES-256-GCM, com chaves derivadas por meio de Argon2 e suporte para operações de criptografia em strings e objetos aninhados. Além disso, oferece funcionalidades para geração de hash de strings e propriedades específicas de objetos usando diversos algoritmos de hash.

Índice

• @cosmixclub/crypto
  • Índice
• Instalação
• Uso
  • Configurando
  • Criptografando uma String
  • Criptografando Objetos
  • Descriptografando uma String
  • Descriptografando Objetos
  • Gerando Hash de Strings
  • Gerando Hash de Objetos
• API
  • Funções de Criptografia
    • encrypt(config: CryptoConfig)
  • Funções de Descriptografia
    • decrypt(config: CryptoConfig)
  • Funções de Hash
    • hash(algorithm: HashAlgorithm)
• Erros
  • Tipos de Erros
• Contribuição

Instalação

pnpm add @cosmixclub/crypto

Uso

Configurando

As funções encrypt e decrypt necessitam de um objeto de configuração com as chaves secretas e contexto adicional (opcional). Tome cuidado com o armazenamento das suas chaves e contexto, vazamentos irão comprometer a segurança dos seus dados.

import { type CryptoConfig } from "@cosmixclub/crypto";

const config: CryptoConfig = {
	privacyKey: "uma_chave_privada_secreta_de_32_caracteres_no_minimo",
	privacySalt: "um_salt_aleatorio_de_16_caracteres_no_minimo",
	context: ["context1", "context2"], // Opcional
};

Criptografando uma String

Você pode usar a função fromString para criptografar uma string de texto simples. A chave de criptografia é derivada de uma chave de privacidade e um sal dinâmico.

import { encrypt } from "@cosmixclub/crypto";

const encryptedString = encrypt(config).fromString("Hello World");
console.log("Encrypted String:", encryptedString);

Criptografando Objetos

A função fromObject permite criptografar seletivamente as propriedades de um objeto, incluindo suporte para objetos aninhados e arrays.

Assim como na função decrypt, o usuário tem a opção de passar uma lista de chaves do objeto para selecionar quais valores serão decriptados. Se nenhum valor for passado, ou a lista não for passada, todos os valores serão criptografados/decriptografados.

import { encrypt } from "@cosmixclub/crypto";

const user = {
	name: "John Doe",
	email: "[email protected]",
	age: 30,
};

const encryptedUser = encrypt(config).fromObject(user, ["email"]);
console.log("Encrypted Object:", encryptedUser);

Descriptografando uma String

Para descriptografar uma string criptografada, você pode usar a função fromString no módulo decrypt.

import { decrypt } from "@cosmixclub/crypto";

const decryptedString = decrypt(config).fromString(encryptedString);
console.log("Decrypted String:", decryptedString);

Descriptografando Objetos

A função fromObject no módulo decrypt pode descriptografar propriedades específicas de um objeto, permitindo também trabalhar com objetos aninhados e arrays.

import { decrypt } from "@cosmixclub/crypto";

const decryptedUser = decrypt(config).fromObject(encryptedUser, ["email"]);
console.log("Decrypted User:", decryptedUser);

Gerando Hash de Strings

Utilize a função fromString para gerar o hash de uma string. Por padrão, o algoritmo SHA-512 é utilizado, mas você pode especificar outros algoritmos suportados.

import { hash } from "@cosmixclub/crypto";

const hashedString = hash("sha256").fromString("Hello World");
console.log("Hashed String:", hashedString);

Gerando Hash de Objetos

A função fromObject permite gerar hash de propriedades específicas de um objeto, com suporte para dot notation. Esta função evita aplicar hash em tipos complexos (como funções e instâncias de classes) e permite gerar hash de objetos aninhados ou arrays.

import { hash } from "@cosmixclub/crypto";

const user = {
	name: "John Doe",
	password: "supersecret",
	profile: {
		email: "[email protected]",
		phone: "123456789",
	},
};

const hashedUser = hash("sha512").fromObject(user, ["password", "profile.email"]);
console.log("Hashed Object:", hashedUser);

API

Funções de Criptografia

encrypt(config: CryptoConfig)

• Parâmetros:
  • config (Object): Objeto de configuração para criptografia.
• Retorno: Um objeto com as funções:
  • fromString(plainText: string): string: Criptografa uma string.
  • fromObject<I, K>(obj: I, keys?: K[]): EncryptNestedKeys<I, K>: Criptografa as chaves especificadas de um objeto.

Funções de Descriptografia

decrypt(config: CryptoConfig)

• Parâmetros:
  • config (Object): Configuração usada na criptografia.
• Retorno: Um objeto com as funções:
  • fromString(content: string): string: Descriptografa uma string.
  • fromObject<I>(obj: I, list?: string[]): I: Descriptografa as chaves especificadas de um objeto.

Funções de Hash

hash(algorithm: HashAlgorithm)

• Parâmetros:
  • algorithm (string, opcional): Algoritmo de hash a ser utilizado. Suporta "sha1", "sha256", "sha384", "sha512", "md5", e "ripemd160". O padrão é "sha512".
• Retorno: Um objeto com as funções:
  • fromString(str: string): string: Gera o hash de uma string.
  • fromObject<I, K>(obj: I, keys?: K[]): EncryptNestedKeys<I, K>: Gera o hash de propriedades específicas de um objeto com suporte a dot notation.

Erros

O pacote lança erros personalizados para facilitar a identificação de problemas.

Tipos de Erros

• CryptoError: Classe base para todos os erros de criptografia.
• InvalidPrefixError: Prefixo inválido na string criptografada.
• InvalidIVError: IV inválido.
• InvalidCiphertextError: Ciphertext inválido.
• InvalidAuthTagError: authTag inválido.
• EncryptionFailedError: Erro ao criptografar.
• DecryptionFailedError: Erro ao descriptografar.
• HashFailedError: Erro ao gerar hash.

Contribuição

1. Faça um fork do repositório.
2. Crie uma nova branch (git checkout -b feature/nova-funcionalidade).
3. Faça commit das alterações (git commit -m 'Adiciona nova funcionalidade').
4. Envie para a branch (git push origin feature/nova-funcionalidade).
5. Abra um Pull Request.

Este pacote é projetado para fornecer uma maneira segura e eficiente de criptografar, descriptografar e hashear dados, com funcionalidades adicionais para criptografia seletiva em objetos aninhados e arrays, além de suporte a múltiplos algoritmos de hash para diferentes necessidades de segurança.