Hash Web Token (HWT)

documentación canónica issues discussions

Un protocolo de token sin estado y nativo de red para la delegación entre dominios.

Los tokens son firmados por un origen emisor, verificables por cualquier parte que pueda alcanzar el dominio del issuer (emisor), y llevan contexto de autorización ya sea de forma literal o por referencia.

Estado: Borrador v0.7.

Qué hace HWT

Lo que HWT no contempla

Formato del token

hwt.signature.key-id.expires-unix-seconds.format.payload

Seis campos separados por puntos. El punto es el separador de campos y NO DEBE aparecer en key-id, format ni en el nombre de nivel superior.

format declara el codec. j (JSON) es el único codec requerido. Codecs adicionales de la comunidad están documentados en CONVENTIONS.md.

La expiración es estructural — un token pasada su fecha expires es incondicionalmente inválido independientemente de la validez de la firma.

Ejemplo de delegation chain

Tres saltos: un usuario en un proveedor de identidad → un agente de orquestación → un servicio worker → el destino final de la API.

Token raíz (en poder del usuario, emitido por auth.example.com):

{
  "iss": "https://auth.example.com",
  "sub": "user:4503599627370495",
  "tid": "root-a1b2",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] }
}

Token intermedio (emitido por agent.example.com para el worker):

{
  "iss": "https://agent.example.com",
  "sub": "svc:orchestrator",
  "aud": "https://worker.example.com",
  "tid": "mid-c3d4",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] },
  "del": [
    { "iss": "https://auth.example.com", "sub": "user:4503599627370495", "tid": "root-a1b2" }
  ]
}

Token derivado final (emitido por worker.example.com para la API de destino):

{
  "iss": "https://worker.example.com",
  "sub": "svc:worker",
  "aud": "https://api.target.example.com",
  "tid": "final-e5f6",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] },
  "del": [
    { "iss": "https://auth.example.com", "sub": "user:4503599627370495", "tid": "root-a1b2" },
    { "iss": "https://agent.example.com", "sub": "svc:orchestrator", "tid": "mid-c3d4" }
  ]
}

La API de destino verifica la firma del token final contra las claves publicadas de worker.example.com, confirma que la cadena del está estructuralmente íntegra (está cubierta por la firma externa), y puede rastrear el linaje de autorización completo hasta el usuario original. La autorización no fue escalada en ningún salto — roles: ["editor"] en todo momento.

Key discovery

GET https://{issuer-domain}/.well-known/hwt-keys.json

Formato JWKS (RFC 7517). alg por clave es obligatorio. Se admiten múltiples claves concurrentes para rotación.

Metadatos del origen

GET https://{issuer-domain}/.well-known/hwt.json

Declara la URL del issuer, la versión del protocolo, los esquemas authz soportados, la configuración de audiencia, el límite de profundidad de delegación y las URLs de los endpoints.

Modelo de confianza

El ancla de confianza es el dominio del issuer, no una autoridad central. La verificación depende de que el DNS resuelva correctamente y TLS se conecte al endpoint well-known del issuer. La postura de producción recomendada es un allowlist de issuers pre-registrados — los verifiers rechazan tokens de issuers que no están en la lista, convirtiendo el key discovery en una búsqueda de caché local sin dependencia de DNS en tiempo de ejecución.

Documentación

Implementaciones

Biblioteca de referencia

Demostraciones

Licencia

Apache License 2.0