> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Formato del paquete de prueba

> Especificación para el formato criptográfico Truthlocks Proof Bundle versión 1.0.

Un **Paquete de Prueba de Truthlocks** contiene evidencia para las comprobaciones criptográficas soportadas de un registro. La verificación offline requiere la carga útil correspondiente, el formato soportado y las claves de emisor y de registro de confianza independiente. No establece el estado de revocación actual, la autoridad del emisor, la verdad fáctica o si ocurrió una acción en el mundo real.

ESPECIFICACIÓN v1.0

## 1. Resumen

Un Paquete de Prueba de Truthlocks es un documento de evidencia portátil. Utilice el formato y el verificador documentados para el punto final que lo produjo. El soporte CBOR se enumera a continuación como una extensión futura, no una garantía para las exportaciones actuales.

La evidencia puede incluir datos de atestación, referencias de claves y pruebas de registro de transparencia. Verifique la firma y la inclusión en el registro por separado; la ausencia de evidencia no debe reportarse como una verificación aprobada. Nunca confíe en una clave pública únicamente porque está incluida en el paquete: establezca la clave autorizada a través de un canal confiable. El esquema a continuación es una descripción de referencia; haga coincidir la versión de exportación real y su contrato de bytes firmados antes de implementar un verificador.

## 2. Estructura del Paquete

Los paquetes de prueba se serializan como objetos JSON y siguen este esquema:

```json theme={null}
{
  "header": {
    "version": "1.0",
    "bundle_id": "bun_a1b2c3d4...",
    "generated_at": "2026-03-12T14:30:00Z",
    "format": "json",
    "tenant_id": "ten_x9y8z7..."
  },
  "attestation": {
    "id": "att_k7x2m9...",
    "type": "content_protection",
    "subject": "main.ts",
    "subject_type": "file",
    "content_hash": "sha256:a1b2c3d4e5f6...",
    "metadata": {
      "title": "My Project",
      "category": "code",
      "file_size": 4096
    },
    "issued_at": "2026-03-12T14:28:00Z",
    "issuer_id": "iss_p4q5r6...",
    "issuer_key_id": "key_m1n2o3...",
    "signature": "base64url-encoded-signature",
    "signature_format": "Ed25519",
    "status": "active"
  },
  "proofs": [
    {
      "log_id": "log_main",
      "tree_size": 42857,
      "leaf_index": 42856,
      "leaf_hash": "sha256:...",
      "inclusion_proof": ["sha256:...", "sha256:...", "..."],
      "root_hash": "sha256:...",
      "timestamp": "2026-03-12T14:28:01Z"
    }
  ],
  "issuer_certificate": {
    "issuer_id": "iss_p4q5r6...",
    "issuer_did": "did:truthlock:iss_p4q5r6...",
    "key_id": "key_m1n2o3...",
    "algorithm": "Ed25519",
    "public_key_der": "base64-encoded-public-key",
    "valid_from": "2026-01-01T00:00:00Z",
    "trust_anchor": "truthlocks-root-2026"
  },
  "bundle_hash_b64url": "base64url-encoded-sha256-of-bundle",
  "bundle_signature": {
    "key_id": "truthlocks-signing-key-2026",
    "algorithm": "Ed25519",
    "value": "base64-encoded-bundle-signature"
  }
}
```

## 3. Definiciones de Campo

### 3.1 Encabezado

| Campo | Tipo | Requerido | Descripción |
| :- | :- | :- | :- |
| `version` | string | Sí | Versión del formato del paquete (actualmente "1.0") |
| `bundle_id` | string | Sí | Identificador único para este paquete |
| `generated_at` | datetime | Sí | Marca de tiempo ISO 8601 de la generación del paquete |
| `format` | string | Sí | Formato de codificación: "json" o "cbor" |
| `tenant_id` | string | Sí | Inquilino propietario de la atestación |

### 3.1.1 Hash de integridad del paquete

| Campo | Tipo | Requerido | Descripción |
| :- | :- | :- | :- |
| `bundle_hash_b64url` | string | Sí | Hash SHA-256 codificado en Base64url de todos los campos del paquete (excluyendo `bundle_hash_b64url` y `bundle_signature`). Se utiliza para la detección de manipulaciones: cualquier modificación del contenido del paquete invalida este hash. |

### 3.2 Atestación

| Campo | Tipo | Requerido | Descripción |
| :- | :- | :- | :- |
| `id` | string | Sí | Identificador de atestación |
| `type` | string | Sí | Tipo de atestación (ej. content\_protection, identity.kyc) |
| `subject` | string | Sí | Asunto de la atestación (nombre de archivo, persona, etc.) |
| `subject_type` | string | No | Sugerencia de tipo para el sujeto (archivo, persona, organización) |
| `content_hash` | string | Sí | Hash SHA-256 del contenido atestiguado (prefijo sha256:) |
| `document_hash` | string | No | Hash SHA-256 precalculado pasado en el momento de la acuñación. Cuando se proporciona, la plataforma utiliza este valor en lugar de calcular el hash internamente. |
| `metadata` | object | No | Metadatos adicionales sobre la atestación |
| `issued_at` | datetime | Sí | Cuando se acuñó la atestación |
| `valid_from` | datetime | No | Inicio del período de validez |
| `valid_until` | datetime | No | Fin del período de validez (nulo = sin vencimiento) |
| `issuer_id` | string | Sí | ID de la entidad emisora |
| `issuer_key_id` | string | Sí | ID de clave utilizado para firmar la atestación |
| `signature` | string | Sí | Firma codificada en Base64url sobre la carga útil de la atestación |
| `signature_format` | string | Sí | Algoritmo utilizado: Ed25519, ES256, RS256 |
| `status` | string | Sí | Instantánea de estado al exportar; actualizar para la aceptación actual |

### 3.3 Pruebas (Registro de Transparencia)

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `log_id` | string | Identificador del registro de transparencia |
| `tree_size` | integer | Tamaño del árbol Merkle en el momento de la inclusión |
| `leaf_index` | integer | Posición de esta entrada en el árbol |
| `leaf_hash` | string | Hash SHA-256 del nodo hoja |
| `inclusion_proof` | string\[] | Lista ordenada de hashes hermanos que forman la ruta de prueba de inclusión |
| `root_hash` | string | Hash raíz del encabezado del árbol firmado en el momento de la inclusión |
| `timestamp` | datetime | Cuando se añadió la entrada al registro |

### 3.4 Certificado del emisor

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `issuer_id` | string | UUID del emisor |
| `issuer_did` | string | Identificador Descentralizado W3C (did:truthlock:...) |
| `key_id` | string | Identificador de clave |
| `algorithm` | string | Algoritmo de clave: Ed25519, ES256, RS256 |
| `public_key_der` | string | Clave pública codificada en Base64 en formato DER |
| `valid_from` | datetime | Inicio de la validez de la clave |
| `valid_until` | datetime | Fin de validez de la clave (nulo = sin vencimiento) |
| `trust_anchor` | string | Referencia al ancla de confianza raíz |

## 4. Algoritmo de Verificación

Para verificar un paquete de prueba de Truthlocks, ejecute los siguientes pasos en orden. Si algún paso falla, el paquete no es válido.

### Paso 1: Validar la integridad del paquete

Calcule el hash SHA-256 de todos los campos del paquete excluyendo `bundle_hash_b64url` y `bundle_signature`. Decodifique en Base64url el valor `bundle_hash_b64url` y compárelo con su hash calculado. Si no coinciden, el paquete ha sido manipulado.

### Paso 2: Verificar la firma de la atestación

Usando la clave pública de `issuer_certificate.public_key_der` y el algoritmo especificado en `attestation.signature_format`, verifique `attestation.signature` contra la carga útil de atestación canónica (todos los campos de atestación excepto `signature` y `status`).

### Paso 3: Verificar hash de contenido

Si tiene el archivo original, calcule su hash SHA-256 y compárelo con `attestation.content_hash`. Esto confirma que el archivo no ha sido modificado desde la certificación.

Si un valor `document_hash` está presente, también puede compararlo con su hash calculado. El `document_hash` es un hash hexadecimal SHA-256 precalculado que el minter pasó en el momento de la acuñación, proporcionando una verificación de integridad adicional independiente de la codificación de la carga útil.

### Paso 4: Verificar inclusión en el registro de transparencia

Para cada entrada en `proofs`, verifique la prueba de inclusión de Merkle. Comenzando desde `leaf_hash` en la posición `leaf_index`, vuelva a calcular la raíz haciendo hash con cada hermano en `inclusion_proof`. El resultado debe coincidir con `root_hash`.

### Paso 5: Verificar validez de la clave

Confirme que `issuer_certificate.valid_from` ≤ `attestation.issued_at` ≤ `issuer_certificate.valid_until` (si está presente).

## 5. Algoritmos Soportados

| Algoritmo | Tipo de clave | Uso |
| :- | :- | :- |
| `Ed25519` | OKP (Curve25519) | Predeterminado para emisores de consumidores. Firmas rápidas y compactas. |
| `ES256` | EC (P-256) | ECDSA con SHA-256. Compatible con FIPS. |
| `RS256` | RSA (2048+) | RSA con SHA-256. Compatibilidad heredada. |

## 6. Herramientas de Verificación

Los paquetes de prueba se pueden verificar utilizando cualquiera de estos métodos:

* **CLI**: `truthlock verify -b bundle.json -f original-file --trusted-log-key "$TRUTHLOCKS_LOG_PUBLIC_KEY" --trusted-issuer-key "$TRUTHLOCKS_ISSUER_PUBLIC_KEY"`. Fije ambas claves públicas independientemente del paquete. Las comprobaciones sin conexión no establecen el estado de revocación actual.
* **Web**: Subir en `verify.truthlocks.com/proof/[id]`
* **SDK**: `client.verify.verifyBundle(bundleJson, fileBuffer)`
* **Manual**: Siga el algoritmo de verificación anterior con cualquier biblioteca Ed25519/ECDSA

## 7. Puntos de Extensión

El campo `metadata` en el objeto de atestación es extensible. Los esquemas personalizados pueden incluir campos adicionales sin romper la verificación. El algoritmo de verificación central solo depende de `content_hash`, `signature` y las pruebas del registro de transparencia.

Las futuras versiones de formato pueden introducir:

* Codificación CBOR para una representación binaria compacta
* Paquetes de múltiples atestaciones (verificación por lotes)
* Pruebas de consistencia entre registros
* Pruebas de estado de revocación (incrustadas)

## 8. Principios de Diseño

* **Autocontenido**: No se requiere acceso a la red para la verificación
* **Confianza minimizada**: Verificable incluso si Truthlocks deja de funcionar
* **Compatible con versiones futuras**: Los campos desconocidos son ignorados por los verificadores más antiguos
* **Determinista**: La codificación JSON canónica garantiza un hash consistente
* **Abierto**: Utiliza primitivas criptográficas estándar (sin formatos propietarios)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.