Por qué 12 etapas
Cuando empecé a diseñar el Universal Trust Adapter (UTA), pensé: "verificar una credencial es verificar la firma criptográfica y punto." Error.
Una credencial puede tener la firma criptográfica correcta y aún asà ser:
- Expirada (firmada correctamente, pero hace 3 años)
- Revocada (firmada correctamente, pero el issuer la revocó)
- Mal scope (firmada correctamente, pero pide permisos que el issuer no pretendÃa otorgar)
- Issuer desconocido (firmada correctamente, pero ¿quién es el issuer?)
- Sin proof-of-possession (firmada correctamente, pero ¿quién la está presentando?)
- Sin provenance (firmada correctamente, pero ¿de dónde salió?)
Cada uno de estos casos requiere una etapa de verificación separada. De ahà el pipeline de 12 etapas:
PARSER → DETECT → SCHEMA → CRYPTO → ISSUER → KEY_BINDING
→ POP → PROVENANCE → LIFECYCLE → EVIDENCE → POLICY → DECISION
Cada etapa, explicada
1. PARSER
Recibe bytes crudos (JSON, CBOR, PEM, DER) y los convierte a un formato interno. Si los bytes no parsean, fail.
2. DETECT
Identifica el formato de la credencial: ¿es JWT? ¿W3C VC? ¿ATC v3? ¿MCP Card? UTA soporta 8 formatos.
3. SCHEMA
Valida que la credencial tenga los campos obligatorios del formato detectado. Un JWT sin alg falla aquÃ.
4. CRYPTO
Verifica la firma criptográfica. Si la firma no cuadra con la clave pública del issuer, fail.
5. ISSUER
Resuelve la identidad del issuer. ¿Es una CA conocida? ¿Es un issuer en una lista de confianza? ¿Es desconocido?
6. KEY_BINDING
Verifica que la clave usada para firmar la credencial esté vinculada al issuer declarado. Previene suplantación.
7. POP (Proof of Possession)
Verifica que quien presenta la credencial realmente posee la clave privada vinculada. Esto previene el robo de credenciales.
8. PROVENANCE
Traza el origen de la credencial. ¿Viene del issuer directo? ¿De un cache? ¿De un tercero? Esto afecta la confianza.
9. LIFECYCLE
Verifica vigencia: not_before, expires_at, revocation_status. Una credencial expirada falla aquÃ.
10. EVIDENCE
Recopila evidencia criptográfica (logs, timestamps, receipts) que justifica la decisión. Útil para auditorÃa.
11. POLICY
Aplica polÃticas especÃficas del sistema: "solo issuers en esta lista", "solo scopes que empiecen con read:", etc.
12. DECISION
Combina los resultados de las 11 etapas anteriores y emite un veredicto: PERMIT, DENY, o UNDETERMINED.
Por qué separar las etapas
Si todo fuera una función verify(card), no podrÃas:
- Debuggear qué etapa falló
- Cachear resultados parciales (si la firma ya se verificó, no hay que re-verificar)
- Personalizar polÃticas sin tocar la criptografÃa
- Auditar qué etapa tomó qué decisión
Separar las etapas te da observabilidad y flexibilidad.
Implementación
El pipeline está implementado en TypeScript y publicado como @marketnow/trust-core:
import { verify, getStageResult } from '@marketnow/trust-core';
const result = await verify(card);
console.log(result.decision); // 'PERMIT' | 'DENY' | 'UNDETERMINED'
console.log(result.failed_stage); // 'LIFECYCLE' si expiró
console.log(getStageResult('CRYPTO')); // detalle de la verificación criptográfica
Cada etapa expone su resultado individual para que puedas inspeccionar.
Benchmarks
- 6,744 verificaciones por segundo (pipeline completo, single core)
- Etapa más lenta: CRYPTO (~0.08ms promedio, Ed25519)
- Etapa más rápida: PARSER (~0.01ms)
Conclusión
La verificación de credenciales no es un paso, es un pipeline. Si lo tratas como un paso, vas a tener falsos positivos (credeniales inválidas que pasan) o falsos negativos (credenciales válidas que no pasan).
UTA implementa los 12 pasos. Tú decides cuáles activar.
Repo: alicelabs-llc/universal-trust-adapter · API: marketnow.site/api/trust
