Verificar una cadena de auditoría de StandardOS

Cada exportación de StandardOS contiene un array audit_trail. Este documento especifica exactamente cómo se calcula el hash de cada entrada, para que usted pueda recalcular la cadena por su cuenta, en cualquier lenguaje, sin ejecutar StandardOS y sin confiar en nosotros.

Una implementación completa, en unas cien líneas de JavaScript sin dependencias, está publicada junto a este documento en https://getstandardos.com/verify-chain.mjs. Está escrita para leerse, pero si prefiere implementarla usted mismo, este documento basta.

Lo que la cadena garantiza

Cada entrada sella la anterior. Cambie cualquier campo de cualquier entrada histórica y su row_hash deja de coincidir, y como el prev_hash de la entrada siguiente es ese hash, todas las entradas posteriores se rompen también. Borrar una entrada rompe el enlace a través del hueco. Añadir una entrada fabricada solo exige conocer la cabeza actual, lo cual es aceptable. La cadena demuestra que la historia no ha sido reescrita, no que un evento concreto haya ocurrido.

Lo que no garantiza por sí sola

La regla de hash es pública y sin clave, y es deliberado: una regla con clave solo podría verificarla quien tuviera la clave, y ese seríamos nosotros. La consecuencia es que cualquiera que pueda escribir en la base de datos puede también recalcular todos los hashes posteriores, y la cadena por sí sola no lo mostrará.

Para eso están las anclas. Véase «Anclas» más abajo. Verifique la cadena contra un recibo de ancla que ya tenga y el ataque por recálculo queda cerrado, porque no podemos alterar un recibo que ya está en su buzón.

La preimagen

Para cada entrada, el hash es:

row_hash = lowercase_hex( sha256( utf8( preimage ) ) )

La preimagen es la concatenación de las partes siguientes, sin separadores salvo donde se indica:

La preimagen de cada versión es una extensión estricta por prefijo de la anterior, así que una entrada v1 se hashea exactamente igual que antes de que existiera v2. Aplique la regla que nombra la hash_version de cada fila. La historia nunca se vuelve a hashear cuando cambia la regla; por eso existe la columna.

Formato de occurred_at

Esta es la parte en la que la gente se equivoca. La marca de tiempo se representa en UTC como:

YYYY-MM-DDTHH:MM:SS.ffffffZ

Exactamente seis dígitos de fracción de segundo, siempre presentes, siempre rellenados con ceros, por ejemplo 2026-07-30T17:41:39.558458Z. Postgres lo produce con to_char(occurred_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"').

Tenga en cuenta que Date.toISOString() de JavaScript emite tres dígitos de fracción, no seis, y por tanto producirá el hash equivocado. El occurred_at exportado es una cadena ISO con precisión de microsegundos; use sus dígitos directamente en lugar de pasarlos por un tipo de fecha que no puede contenerlos.

old_data / new_data

Se exportan como cadenas, no como objetos, deliberadamente. Los bytes que se hashean son la representación jsonb canónica de Postgres: claves de objeto ordenadas por longitud y después byte a byte, un espacio tras cada : y ,. JSON.stringify no reproduce eso. Hashee la cadena exactamente como se exporta. Analícela solo si quiere leerla.

Un INSERT no tiene old_data; un DELETE no tiene new_data. Ambos son null en la exportación y aportan la cadena vacía a la preimagen.

Comprobar la cadena

1. Ordene las entradas por id ascendente, dentro de un mismo org_id.
2. El prev_hash de la primera entrada debe ser igual a la semilla de génesis: sha256(utf8(org_id)) en hexadecimal minúsculo, donde org_id es el UUID en su forma canónica con guiones y en minúsculas.
3. Para cada entrada: recalcule row_hash a partir de la preimagen y compare; después confirme que el prev_hash de la entrada siguiente es igual al row_hash de esta.

Si falla el paso 2, se han eliminado entradas al principio. Si falla el paso 3 en la entrada n, la cadena está intacta en las primeras n−1 entradas y algo en n no coincide con lo que se registró.

Anclas

Cada día StandardOS registra la cabeza de la cadena de cada organización y le envía por correo un recibo con el hash de cabeza, el número de entradas y la fecha. Esos recibos son la parte independiente: están en su buzón, no en nuestra base de datos.

Para usar uno, tome el hash de cabeza de un recibo anterior al periodo que le interesa, busque la entrada con ese row_hash en su exportación y verifique la cadena hasta ese punto. Un recálculo hecho después de enviar el recibo no puede volver a producir ese hash de cabeza.

Conserve los recibos. Son la razón por la que «ni siquiera nosotros podemos alterarlo sin que se note» es una afirmación matemática y no una declaración de buenas intenciones.

Lo que un ancla no cubre

Un ancla tomada a las 03:40 no dice nada de los eventos escritos a las 09:00. Entre dos pasadas de anclaje hay una ventana en la que un evento puede escribirse y retirarse sin que nada lo contradiga: la cadena de hash no lo nota, porque borrar las entradas más recientes no rompe ningún enlace, y ningún ancla las cubrió nunca.

Dos cosas estrechan esa ventana sin cerrarla. Cada pasada nocturna comprueba que el ancla anterior sigue siendo válida, es decir, que el evento que registró sigue presente con el mismo hash y que la cadena no ha menguado por debajo del recuento anclado, y registra una alarma si no es así. Así que todo lo que sobrevive a un ancla queda protegido desde entonces. Y el barrido profundo vuelve a derivar cada cadena desde el génesis a diario, lo que detecta contenido alterado sin recálculo.

Lo que queda sin cubrir es un intervalo de anclaje, para los eventos creados y destruidos dentro de él. Preferimos dejarlo escrito antes que permitir que un lector suponga lo contrario.

Lo que cubre la regla de hash, por versión

La regla se ha ampliado dos veces, y cada fila registra qué versión la escribió.

La historia nunca se vuelve a hashear cuando cambia la regla. Reescribir un registro de solo adición para que se verifique bajo una regla nueva es exactamente la operación que el registro existe para hacer detectable. La consecuencia es que en una entrada v1 o v2 las columnas de atribución están registradas pero no selladas: pueden alterarse sin romper la verificación. La exportación lo marca por fila (principal_attested, actor_attested), y verify-chain.mjs imprime cuántas entradas están afectadas. Trate una atribución no atestiguada como una afirmación, no como prueba de quién actuó. El contenido, el orden y el momento de cada entrada se verifican sea cual sea la versión.

Vectores de prueba

Si ha implementado la regla anterior, compruébela contra estos vectores antes de confiar en su implementación con una exportación real. Cada entrada es una fila completa de la pista de auditoría con el row_hash que debe producir. Cubren las tres versiones de hash, old_data/new_data tanto nulos como rellenos, y una fracción de segundo que no tiene ya seis dígitos.

No son decoración. Nuestra CI recalcula cada uno de ellos en cada push con el verificador publicado, de modo que un cambio en la regla de hash que olvidara actualizar este documento hace fallar nuestra compilación y no su auditoría.

[
  {
    "hash_version": 1,
    "prev_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "old_data": null,
    "new_data": "{\"id\":1}",
    "action": "INSERT",
    "table_name": "risks",
    "actor": null,
    "record_id": null,
    "principal": null,
    "occurred_at": "2026-07-30T17:41:39.558458Z",
    "row_hash": "62586c3fab919870dc2a5eec406fde33ddc31f73b92d5d851acbf3e822b15704"
  },
  {
    "hash_version": 2,
    "prev_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "old_data": "{\"id\":1}",
    "new_data": "{\"id\":2}",
    "action": "UPDATE",
    "table_name": "soa_entries",
    "actor": "11111111-1111-1111-1111-111111111111",
    "record_id": "22222222-2222-2222-2222-222222222222",
    "principal": null,
    "occurred_at": "2026-07-30T17:41:39.5Z",
    "row_hash": "6aad0bb2c1edf6053b297d5a38b88bcc9146fcfb6caa4e0f47dd009bcda60674"
  },
  {
    "hash_version": 3,
    "prev_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "old_data": "{\"id\":3}",
    "new_data": null,
    "action": "DELETE",
    "table_name": "documents",
    "actor": null,
    "record_id": "33333333-3333-3333-3333-333333333333",
    "principal": "job:soa-justification-source",
    "occurred_at": "2026-08-03T09:00:00Z",
    "row_hash": "d895d6280468e1a0600034f15dc3a884a123333a5b73a2df7cf8e470c6cf2fe4"
  }
]

Informar de una discrepancia

Si una verificación falla y usted cree que los datos son auténticos, escríbanos a security@getstandardos.com con el id de la entrada y lo que ha calculado. Una cadena que no verifica es o bien una manipulación o bien un error en nuestro hash, y queremos saber cuál con la misma urgencia que usted.