🔐 @purecore/one-jwt-4-all

A Biblioteca one-jwt-4-all com Zero Dependências

Uma biblioteca moderna e opinativa para criação e validação de JSON Web Tokens (JWT) usando exclusivamente algoritmos state-of-the-art. API compatível com jose, mas com uma filosofia radicalmente diferente: Opinião Forte.

🎯 Filosofia "One JWT 4 ALL"

Enquanto outras bibliotecas suportam centenas de combinações de algoritmos (muitos deles inseguros ou obsoletos), nós suportamos apenas uma combinação para cada caso de uso. Essa combinação é escolhida com base no que há de mais seguro e performático na versão LTS mais recente do Node.js.

Por que EdDSA (Ed25519)?

• ⚡ Mais rápido que ECDSA e RSA
• 🔑 Chaves menores que RSA (256 bits vs 2048+ bits)
• 🛡️ Imune a ataques de timing e side-channels comuns
• 📦 Suporte nativo no Node.js 18+ (sem dependências externas)
• ✅ Padrão moderno recomendado por criptógrafos

"A complexidade é a inimiga da segurança."

📊 Comparativo: jose vs Purecore JWTfy

| Funcionalidade | Biblioteca jose (Genérica) | Purecore JWTfy (Opinativa) | |----------------|---------------------------|---------------------------| | Filosofia | Suportar tudo (Legado & Novo) | Suportar apenas o Melhor (State-of-the-Art) | | JWS Signing Algs | HS256, RS256, ES256, PS256, EdDSA... | EdDSA (Ed25519) Apenas | | JWE Encryption | RSA-OAEP, A128CBC-HS256, A256GCM... | X25519 + A256GCM (Roadmap) | | JWS Serialization | Compact, Flattened, General | Compact (Core) | | Key Management | JWK, JWKS (Local/Remote), PEM, X.509 | PEM & JWK (Simples) | | Runtime | Universal (Browser, Node, Deno, Workers) | Node.js Nativo (Foco em Performance) | | Dependências | Múltiplas | Zero (0) |

🚀 Instalação

# Com npm
npm install @purecore/one-jwt-4-all

# Com bun
bun add @purecore/one-jwt-4-all

# Com yarn
yarn add @purecore/one-jwt-4-all

📖 Uso Básico

1. Gerar Par de Chaves

import { generateKeyPair } from '@purecore/one-jwt-4-all';

const { publicKey, privateKey } = generateKeyPair();

// Salve as chaves de forma segura
console.log('Chave Privada:', privateKey);
console.log('Chave Pública:', publicKey);

2. Criar um Token JWT

import { SignJWT } from '@purecore/one-jwt-4-all';

// Criar token com builder pattern (estilo jose)
const jwt = await new SignJWT({
  userId: 123,
  email: '[email protected]',
  role: 'admin'
})
  .setProtectedHeader({ alg: 'EdDSA', typ: 'JWT' })
  .setIssuedAt()
  .setIssuer('urn:meu-sistema:issuer')
  .setAudience('urn:meu-sistema:audience')
  .setExpirationTime('2h') // Expira em 2 horas
  .setSubject('usuario-123')
  .setJti('token-unique-id')
  .sign(privateKey);

console.log('Token gerado:', jwt);

3. Verificar um Token JWT

import { jwtVerify } from '@purecore/one-jwt-4-all';

try {
  const { payload, protectedHeader } = await jwtVerify(jwt, publicKey, {
    issuer: 'urn:meu-sistema:issuer',
    audience: 'urn:meu-sistema:audience',
    maxTokenAge: '2h' // Opcional: idade máxima do token
  });

  console.log('Token válido!');
  console.log('Payload:', payload);
  console.log('Header:', protectedHeader);
} catch (error) {
  console.error('Token inválido:', error.message);
}

🔧 API Completa

SignJWT (Builder Pattern)

Métodos Disponíveis

new SignJWT(payload: JWTPayload)
  .setProtectedHeader(header: JWTHeaderParameters)  // Define o header protegido
  .setIssuer(issuer: string)                        // Define o emissor (iss)
  .setSubject(subject: string)                      // Define o assunto (sub)
  .setAudience(audience: string | string[])        // Define a audiência (aud)
  .setJti(jwtId: string)                           // Define o ID único do token (jti)
  .setIssuedAt(timestamp?: number)                 // Define quando foi emitido (iat)
  .setExpirationTime(time: number | string)        // Define expiração (exp)
  .setNotBefore(time: number | string)              // Define quando fica válido (nbf)
  .sign(privateKey: KeyObject | string)             // Assina e retorna o token

Formatos de Tempo Suportados

// Strings de duração relativa
.setExpirationTime('30s')  // 30 segundos
.setExpirationTime('5m')   // 5 minutos
.setExpirationTime('2h')   // 2 horas
.setExpirationTime('1d')   // 1 dia
.setExpirationTime('1w')   // 1 semana
.setExpirationTime('1y')   // 1 ano

// Timestamp absoluto (Unix timestamp em segundos)
.setExpirationTime(1735689600)

jwtVerify (Função)

jwtVerify(
  jwt: string,
  publicKey: KeyObject | string,
  options?: JWTVerifyOptions
): Promise<JWTVerifyResult>

Opções de Verificação

interface JWTVerifyOptions {
  issuer?: string | string[];        // Valida o emissor (iss)
  audience?: string | string[];      // Valida a audiência (aud)
  algorithms?: string[];             // Lista de algoritmos permitidos (ignorado, sempre EdDSA)
  currentDate?: Date;                // Data atual para testes (mock)
  maxTokenAge?: string | number;     // Idade máxima do token ('2h' ou segundos)
}

📝 Exemplos Práticos

Exemplo 1: Autenticação de Usuário

import { SignJWT, jwtVerify, generateKeyPair } from '@purecore/one-jwt-4-all';

// Gere as chaves uma vez e guarde em variáveis de ambiente
const { publicKey, privateKey } = generateKeyPair();

// Login: Criar token após autenticação bem-sucedida
async function login(userId: string, email: string) {
  const token = await new SignJWT({
    userId,
    email,
    loginTime: Date.now()
  })
    .setIssuedAt()
    .setIssuer('https://meuapp.com')
    .setAudience('https://meuapp.com/api')
    .setSubject(userId)
    .setExpirationTime('24h')
    .sign(privateKey);

  return token;
}

// Middleware: Verificar token em requisições
async function verifyToken(token: string) {
  try {
    const { payload } = await jwtVerify(token, publicKey, {
      issuer: 'https://meuapp.com',
      audience: 'https://meuapp.com/api',
      maxTokenAge: '24h'
    });
    
    return payload;
  } catch (error) {
    throw new Error(`Token inválido: ${error.message}`);
  }
}

Exemplo 2: Refresh Tokens

// Access Token (curta duração)
const accessToken = await new SignJWT({ userId: 123 })
  .setIssuedAt()
  .setExpirationTime('15m') // 15 minutos
  .setIssuer('https://meuapp.com')
  .setAudience('https://meuapp.com/api')
  .sign(privateKey);

// Refresh Token (longa duração)
const refreshToken = await new SignJWT({ userId: 123 })
  .setIssuedAt()
  .setExpirationTime('7d') // 7 dias
  .setIssuer('https://meuapp.com')
  .setAudience('https://meuapp.com/auth/refresh')
  .sign(privateKey);

Exemplo 3: Tokens com Not Before

// Token que só fica válido após 5 minutos
const token = await new SignJWT({ userId: 123 })
  .setIssuedAt()
  .setNotBefore('5m') // Válido apenas após 5 minutos
  .setExpirationTime('1h')
  .sign(privateKey);

Exemplo 4: Integração com Express.js

import express from 'express';
import { jwtVerify } from '@purecore/one-jwt-4-all';
import { readFileSync } from 'fs';

const app = express();
const publicKey = readFileSync('./public-key.pem', 'utf-8');

// Middleware de autenticação
async function authenticate(req: express.Request, res: express.Response, next: express.NextFunction) {
  const authHeader = req.headers.authorization;
  
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Token não fornecido' });
  }

  const token = authHeader.substring(7);

  try {
    const { payload } = await jwtVerify(token, publicKey, {
      issuer: 'https://meuapp.com',
      audience: 'https://meuapp.com/api'
    });
    
    req.user = payload;
    next();
  } catch (error) {
    return res.status(401).json({ error: `Token inválido: ${error.message}` });
  }
}

// Rota protegida
app.get('/api/protected', authenticate, (req, res) => {
  res.json({ 
    message: 'Acesso autorizado',
    user: req.user 
  });
});

🔒 Segurança

Boas Práticas

1. Nunca exponha a chave privada

   • Guarde em variáveis de ambiente
   • Use serviços de gerenciamento de segredos em produção

2. Use expiração curta para access tokens

   • Recomendado: 15 minutos a 1 hora
   • Use refresh tokens para renovação

3. Valide sempre issuer e audience

   • Previne uso de tokens em contextos errados
   • Protege contra token reuse attacks

4. Use HTTPS em produção

   • Tokens não devem trafegar em conexões não criptografadas

5. Rotacione chaves periodicamente

   • Gere novos pares de chaves regularmente
   • Mantenha versões antigas para validação durante transição

Gerenciamento de Chaves

// Gerar par de chaves
const { publicKey, privateKey } = generateKeyPair();

// Salvar em arquivos (nunca commite no git!)
import { writeFileSync } from 'fs';
writeFileSync('./private-key.pem', privateKey, { mode: 0o600 }); // Permissões restritas
writeFileSync('./public-key.pem', publicKey);

// Carregar de arquivos
import { readFileSync } from 'fs';
const privateKey = readFileSync('./private-key.pem', 'utf-8');
const publicKey = readFileSync('./public-key.pem', 'utf-8');

🧪 Testes

import { SignJWT, jwtVerify, generateKeyPair } from '@purecore/one-jwt-4-all';

describe('JWT', () => {
  const { publicKey, privateKey } = generateKeyPair();

  it('deve criar e verificar token válido', async () => {
    const jwt = await new SignJWT({ userId: 123 })
      .setIssuedAt()
      .setExpirationTime('1h')
      .sign(privateKey);

    const { payload } = await jwtVerify(jwt, publicKey);
    
    expect(payload.userId).toBe(123);
  });

  it('deve rejeitar token expirado', async () => {
    const jwt = await new SignJWT({ userId: 123 })
      .setIssuedAt()
      .setExpirationTime('-1h') // Expirado
      .sign(privateKey);

    await expect(jwtVerify(jwt, publicKey)).rejects.toThrow('expirado');
  });
});

📚 Tipos TypeScript

A biblioteca exporta todos os tipos necessários:

import type {
  JWTPayload,
  JWTHeaderParameters,
  JWTVerifyResult,
  JWTVerifyOptions
} from '@purecore/one-jwt-4-all';

🔄 Exemplos Avançados

1. Self-Healing Agentic Conversational System

Sistema onde dois agentes se identificam usando JWTs do mesmo servidor e regeneram automaticamente seus tokens quando expiram, mantendo a conversa contínua sem interrupção.

Características:

• ✅ Auto-Renovação: Tokens renovados automaticamente antes de expirar
• ✅ Contexto Preservado: Conversa continua mesmo após renovação
• ✅ Verificação Mútua: Agentes verificam identidade uns dos outros
• ✅ Self-Healing: Sistema se recupera automaticamente de falhas

Exemplo Rápido:

import { TokenAuthority, SelfHealingAgent } from './examples/self-healing-agents';

const authority = new TokenAuthority();
const agentA = new SelfHealingAgent('agent-alpha', 'primary', authority);
const agentB = new SelfHealingAgent('agent-beta', 'secondary', authority);

await agentA.initialize();
await agentB.initialize();
agentA.startAutoRenewal(30000);
agentB.startAutoRenewal(30000);

await agentA.sendMessage(agentB, 'Olá! Vamos trabalhar juntos?');
await agentB.sendMessage(agentA, 'Perfeito! Estou pronto.');

📖 Documentação: examples/SELF_HEALING_AGENTS.md

2. Self-Healing Agents com mTLS (Mutual TLS)

Extensão do sistema anterior que adiciona mTLS para segurança em duas camadas: transporte (certificados) + aplicação (JWT).

Características:

• 🔒 mTLS: Autenticação mútua via certificados X.509
• 🔐 JWT: Autenticação de identidade e contexto
• 🛡️ Prevenção MITM: Certificados validam identidade do transporte
• 🔄 Self-Healing: Auto-renovação de tokens mantendo conexão mTLS

Exemplo Rápido:

import { mTLSAgent, CertificateAuthority, TokenAuthority } from './examples/mtls-agents';

const ca = new CertificateAuthority();
const tokenAuthority = new TokenAuthority();

const certA = ca.generateAgentCertificate('agent-alpha');
const certB = ca.generateAgentCertificate('agent-beta');
const caCert = ca.getCACertificate();

const agentA = new mTLSAgent('agent-alpha', 'primary', tokenAuthority, certA, caCert);
const agentB = new mTLSAgent('agent-beta', 'secondary', tokenAuthority, certB, caCert);

await agentA.initialize();
await agentB.initialize();

await agentA.startTLSServer(8443);
await agentB.startTLSServer(8444);

await agentA.connectToPeer('localhost', 8444, 'agent-beta');
await agentB.connectToPeer('localhost', 8443, 'agent-alpha');

// Comunicação segura via mTLS + JWT
await agentA.sendMessage('agent-beta', 'Mensagem segura!');

📖 Documentação: examples/MTLS_AGENTS.md

3. Signal Protocol E2EE (End-to-End Encryption)

Implementação do Double Ratchet Algorithm do Signal Protocol para criptografia end-to-end entre agentes com Perfect Forward Secrecy.

Características:

• 🔐 X3DH: Extended Triple Diffie-Hellman para key agreement
• 🔄 Double Ratchet: Rotação contínua de chaves por mensagem
• 🛡️ Perfect Forward Secrecy (PFS): Comprometimento não afeta passado
• 🔓 Post-Compromise Security (PCS): Recuperação após comprometimento
• 🤫 Deniability: Negabilidade criptográfica

Exemplo Rápido:

import { SignalE2EEAgent, TokenAuthority } from './examples/signal-e2ee-agents';

const tokenAuthority = new TokenAuthority();

const alice = new SignalE2EEAgent('alice', tokenAuthority);
const bob = new SignalE2EEAgent('bob', tokenAuthority);

await alice.initialize();
await bob.initialize();

// Trocar bundles públicos
alice.registerPeerBundle('bob', bob.getPublicKeyBundle());
bob.registerPeerBundle('alice', alice.getPublicKeyBundle());

// Estabelecer sessão E2EE
await alice.establishSession('bob');
await bob.acceptSession('alice', alice.getIdentityPublicKey(), alice.getPublicKeyBundle().signedPreKey);

// Enviar mensagem encriptada
const msg = await alice.sendMessage('bob', 'Hello, secure world!');
const plaintext = await bob.receiveMessage(msg);
// plaintext = "Hello, secure world!"

📖 Documentação: examples/SIGNAL_E2EE.md

4. Combinando Signal E2EE + mTLS (Defesa em Profundidade)

Para máxima segurança, combine ambos os protocolos:

| Camada | Protocolo | Proteção | |--------|-----------|----------| | Transporte | mTLS | Anti-MITM, autenticação mútua | | Aplicação | Signal E2EE | Forward secrecy, conteúdo encriptado | | Contexto | JWT | Claims, autorização, expiração |

📖 Documentação Completa: examples/SIGNAL_E2EE.md#usando-ambos-em-conjunto

🛠️ Requisitos

• Node.js: >= 18.0.0 (suporte nativo a Ed25519)
• TypeScript: >= 4.0.0 (recomendado)

📄 Licença

Este projeto é licenciado sob a Cogfulness Ethical License (CEL) - uma licença open source focada em uso ético e responsável de tecnologia cognitiva.

🤝 Contribuindo

Contribuições são bem-vindas! Este projeto segue uma filosofia de zero dependencies e simplicidade arquitetural.

🔗 Links Úteis

• RFC 7519 - JSON Web Token (JWT)
• RFC 8037 - Edwards-Curve Digital Signature Algorithm (EdDSA)
• Node.js Crypto Documentation
• JWT.io - Debugger de Tokens

📝 Changelog

Veja todas as mudanças em CHANGELOG.md

Desenvolvido com ❤️ para promover segurança através de simplicidade e opiniões fortes.