La lectura pública de un documento trae un layout: las instrucciones para dibujar la hoja A4 con el diseño del emisor. Dibujarla es trabajo de tu aplicación: la API te da los datos, no la hoja. Para no empezar de cero hay un boilerplate de referencia.
El layout se diseña en el dashboard, al crear el esquema.
Qué tenés que dibujar
- Los elementos del layout, en el orden en que vienen.
- Los valores de los campos, sacados del
credential. - Una franja de procedencia al pie: quién emitió, la transacción on-chain, el digest y un QR con el
credential. Es lo que le permite a quien tiene la hoja ir a verificarla en vez de creerle.
Las tres cosas que el JSON no trae
| Lo que falta | De dónde sale |
|---|---|
| Los valores de los campos | schema.claims[] trae solo definiciones. Los valores están dentro del credential. |
El digest |
Se calcula: es el SHA-256 de header.payload del credential. |
| El ancho de cada elemento | El layout trae x e y, no el ancho. Se deriva: page.width - 48 - x. |
El objeto layout
Tiene dos partes: page, con el tamaño de la hoja (794 × 1123 px, la proporción A4 a 96 dpi), y elements, la lista de cosas a dibujar. Cada elemento trae su type, su posición (x, y) y su estilo (size, color, bold, align).
{
"page": { "width": 794, "height": 1123 },
"elements": [
{ "id": "title", "type": "text", "value": "Document Example",
"x": 283, "y": 56, "size": 26, "bold": true, "color": "#111827" },
{ "id": "emt25542s1", "type": "field", "bind": "date",
"x": 648, "y": 128, "size": 14, "color": "#111827" }
]
}No hay z-index: el orden del array es el orden de pintado. Un box de fondo va antes que lo que se apoya encima. Y el layout no está firmado: es presentación, y puede cambiar sin que el documento cambie.
type |
Qué dibuja |
|---|---|
text |
Su value: títulos, etiquetas. |
field |
El valor del claim que dice su bind. |
line |
Una regla de 1 px. |
box |
Un rectángulo de fondo, con radius opcional. |
image |
Un logo o un sello, en src como data URI. |
Si llega un type desconocido, dibujá su value como texto: mejor dibujar algo que romper el renderizador.
Los valores salen del credential
Recorré las keys del esquema y tomá cada valor del payload del credential. Filtrando en esa dirección, los claims internos del JWT (iss, vct, jti, iat, exp) nunca llegan a la hoja.
Cómo leer los valores del credential (código)
Abrir el credential:
const [jwt] = credential.split("~");
const [header, payload, signature] = jwt.split(".");
const signingInput = `${header}.${payload}`; // sobre esto se firma y se anclaCada segmento es base64url (- y _ en vez de + y /, sin padding). En el navegador, atob solo entiende base64 común, así que hay que traducir esos dos caracteres, y pasar por Uint8Array + TextDecoder para que los acentos y las eñes salgan bien:
function decodeSegment(segment) {
const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
const bytes = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
return JSON.parse(new TextDecoder().decode(bytes));
}Filtrar por las keys del esquema, no por las del payload:
const claims = {};
for (const claim of schema.claims) {
if (claim.key in payload) claims[claim.key] = payload[claim.key];
}Así, un layout que bindea a iss dibuja vacío en lugar de filtrar el emisor por la ventana.
Cómo calcular el digest
El digest anclado on-chain es el SHA-256 del signing input (header.payload), que ya tenés:
export async function digestOf(signingInput) {
const bytes = new TextEncoder().encode(signingInput);
const hash = await crypto.subtle.digest("SHA-256", bytes);
return [...new Uint8Array(hash)]
.map((b) => b.toString(16).padStart(2, "0"))
.join("");
}Se calcula sobre header.payload, no sobre el credential completo: incluir la firma o la ~ da otro hash, que no coincide con nada de lo que hay en la cadena. Al compararlo con el digest que devuelve la emisión, compará en minúsculas e ignorando un eventual prefijo 0x.
La geometría: cómo calcular el ancho
El ancho se calcula con un margen de 48 px:
const MARGIN = 48;
const room = Math.max(0, page.width - MARGIN - element.x);
const width = element.width
? `width:${Math.min(element.width, room)}px`
: `max-width:${room}px`;room es el espacio desde la x del elemento hasta el margen derecho, y hace que un texto largo corte en el margen en vez de salirse de la hoja. El título en x = 283 da 794 - 48 - 283 = 463, o sea max-width: 463px.
Un ancho fijo mantiene la caja quieta sea cual sea el valor. Sin uno, el elemento se ajusta a su texto, y dos documentos del mismo esquema quedan maquetados distinto.
El saneo, regla por regla
El layout lo controla el emisor, pero termina en atributos style y nodos del DOM. Un layout roto u hostil tiene que costar un elemento, nunca la página.
| Regla | Sin ella |
|---|---|
color solo si matchea /^#[0-9a-fA-F]{3,8}$/ |
Un valor como "#fff; position:fixed; top:0" despega el elemento de la hoja. |
src solo data:image/(png|jpeg);base64,… |
Un src: "javascript:…", o una URL a un tracker. |
Lo que no es objeto en elements[] se descarta |
Un null en el array tira la página entera. |
align solo left / center / right |
Cualquier string entra al CSS. |
page.width / page.height tienen que ser números |
Un "794" string rompe la aritmética del margen. |
| Todo texto se escapa | Un claim con <img src=x onerror=…> se ejecuta. |
El texto entra por textContent, nunca por innerHTML |
El escapado pasa a ser la única defensa en vez de la segunda. |
La franja de procedencia y el QR, en detalle
La franja no es un elemento del layout, y el emisor no la puede mover ni sacar: si fuera opcional, el documento no serviría para verificar nada.
| Fila | Qué lleva |
|---|---|
| Issued by | issuer.name · issuer.did. El nombre no está firmado; el DID sí (sale de iss). Van juntos: el nombre es lo que un humano reconoce y el DID es lo que se puede comprobar. |
| Transaction | El tx_hash, enlazado al explorer y con el hash completo escrito, para que en papel también se pueda seguir. Sin tx_hash: escribí not anchored y no inventes un link. |
| Digest | El calculado, o unavailable. |
| QR | El credential completo, no un link a la página. |
Por qué el QR lleva el credential: quien tiene la hoja escanea y verifica la firma contra la cadena, y si el servicio desapareció el QR impreso sigue sirviendo. Un link solo prueba que el servicio está en línea.
El costo es tamaño: el credential del ejemplo pesa 520 bytes, que es la versión 15 del QR (77 × 77 módulos); un link pesaría ~90 bytes. El techo en corrección nivel L es ~2953 bytes. Arriba de eso, devolvé null en vez de lanzar: perder el QR es mejor que perder la página. Dibujalo a varias veces el tamaño de display, en PNG (un SVG es un <rect> por módulo), para que impreso quede nítido.
Degradar sin romper. Leer el credential no debería lanzar nunca:
| Qué falla | Qué se pierde | Qué se sigue viendo |
|---|---|---|
El credential no parsea |
Los field y el digest (unavailable) |
Los text del layout y la franja |
| El QR no entra | El QR | Toda la hoja |
| El documento no está anclado | El link al explorer | not anchored en la franja |
| Un elemento no pasa el saneo | Ese elemento | El resto de la página |
Registrá lo que se degradó: una hoja sin QR se ve casi igual a una completa, y el QR es justamente la parte que permite no creerle a la página.
Boilerplate de referencia
El repositorio document-render-boilerplate dibuja la hoja A4 a partir del JSON de GET /api/v1/documents/{id}, en HTML + CSS + JS vanilla, sin build ni dependencias. Incluye el saneo de esta página y 20 tests, uno de ellos un golden que compara la salida byte a byte.
Lo que no hace:
- No verifica la firma. Dibuja lo que dice el
credential, así que un documento adulterado se ve igual que uno legítimo. Para eso está la verificación. - No emite. Emitir requiere la API key, que no puede vivir en el navegador.