# Paquetes de evidencias

> Descarga un registro firmado de cómo se hizo un cambio (tarea, modelos, aprobaciones, hallazgos, pruebas, entrega) y verifícalo en el navegador o sin conexión.

Fuente: https://aicodeops.dev/es/docs/evidence-packs

Un paquete de evidencias es un registro firmado de cómo se hizo un cambio en AI CodeOps. Es para auditores, revisiones de cumplimiento y clientes que necesitan mostrar cómo llegó a producción el código escrito por IA.

## Qué contiene un paquete

Para un cambio (**Develop → Changes**, y después un cambio):

- **La tarea:** el prompt que se dio a la IA, el modelo, el proveedor y el nivel, y los archivos de contexto.
- **Las ejecuciones:** la sesión y cada ejecución de seguimiento, con el estado, los tiempos, los tokens y el costo, además del proveedor y el modelo de cada paso de agente.
- **El resultado:** el resumen, los archivos modificados y un hash SHA-256 del diff. El código en sí no se incluye; el hash te permite cotejarlo con el pull request.
- **Aprobaciones:** cada solicitud de aprobación, quién la pidió (en la aprobación propia de una sesión, el miembro que lanzó la sesión), quién podía aprobar (`eligibleApprovers`: los aprobadores que nombraba y los roles autorizados a decidir), quién aprobó o rechazó (`approvedBy` y `rejectedBy`) y cada voto (`votes`).
- **Cada voto:** `votes` tiene una entrada por voto, en el orden en que se emitieron: la cuenta del votante (`accountID`), su rol en el espacio de trabajo (`role`), el voto (`approve` o `reject`), la hora (`decidedAt`) y la nota. `roleAsOf` indica de qué fecha es el rol: `vote` es el rol registrado cuando se emitió el voto; `export` es el rol que tenía cuando se generó el paquete, y se usa para los votos emitidos antes de que se registraran los roles, y `null` si el votante ha dejado desde entonces el espacio de trabajo. `selfApproval` es true cuando el votante aprobó un cambio que lanzó él mismo, y `selfApprovalAllowedBy` dice por qué se permitió. `gateOverride` lleva el motivo que dio el votante, y lo que dijo la comprobación de publicación, cuando aprobó un cambio cuya comprobación de publicación estaba fallando. La lista `decisions` sin procesar sigue ahí, sin cambios. Las dos contienen solo la ronda actual: cuando una aprobación se reabre, por ejemplo después de editar un cambio aprobado, se vacían, y los votos anteriores siguen en la sección `audit` del paquete como entradas `approval.decided`.
- **Decisiones de política:** cada allow, deny o ask que tomaron las políticas del espacio de trabajo durante el cambio.
- **Hallazgos y pruebas:** los hallazgos de la revisión con su triaje, y los resultados de las pruebas (superadas, fallidas, omitidas, cobertura).
- **Entrega:** el pull request, el despliegue y cualquier incidente vinculado al cambio.
- **El registro de auditoría:** las entradas del registro de auditoría sobre cualquiera de los puntos anteriores.
- **Personas:** la dirección de correo electrónico que hay detrás de cada ID de cuenta del paquete.

## Descargar un paquete

Abre **Changes**, elige un cambio y selecciona **Download evidence pack**. Necesitas acceso de auditoría en el espacio de trabajo: lo tienen los roles Owner, Admin y Security Admin. Cada descarga queda anotada en el registro de auditoría del espacio de trabajo.

## Verificar un paquete en el navegador

Abre [/evidence/verify](https://aicodeops.dev/evidence/verify) y elige el archivo. No hace falta ninguna cuenta. La página te dice si la firma coincide y qué clave lo firmó.

## Verificar un paquete sin conexión

No tienes que fiarte de nuestro verificador. La `signature` del paquete es Ed25519 sobre el JSON canónico de su `payload`: las claves de los objetos ordenadas en todos los niveles, sin espacios en blanco. Las claves públicas de la plataforma están en `/api/evidence?action=keys`. Con Node.js 20 o posterior:

```js
// verify-evidence.mjs <pack.json> <keys.json>
import { readFileSync } from "node:fs"
import { createPublicKey, verify } from "node:crypto"

const canonical = (v) =>
  v === null || typeof v !== "object"
    ? JSON.stringify(v)
    : Array.isArray(v)
      ? `[${v.map(canonical).join(",")}]`
      : `{${Object.keys(v)
          .sort()
          .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
          .join(",")}}`

const pack = JSON.parse(readFileSync(process.argv[2], "utf8"))
const { keys } = JSON.parse(readFileSync(process.argv[3], "utf8"))
const key = keys.find((k) => k.kid === pack.signature.kid)
if (!key) throw new Error(`unknown key ${pack.signature.kid}`)
const ok = verify(
  null,
  Buffer.from(canonical(pack.payload)),
  createPublicKey(key.publicKey),
  Buffer.from(pack.signature.value, "base64url"),
)
console.log(ok ? "VERIFIED" : "NOT VERIFIED: the pack was altered")
```

Guarda las claves una vez y después ejecuta el script:

```bash
curl -o keys.json "https://console.aicodeops.dev/api/evidence?action=keys"
node verify-evidence.mjs evidence-chg_....json keys.json
```

## Claves y rotación

Las claves nunca se eliminan. Cuando una clave se retira, deja de firmar paquetes nuevos, y los paquetes que firmó se siguen verificando. Guarda una copia de `keys.json` con tus registros de auditoría si quieres una verificación que no dependa de llegar a la plataforma.

## Siguientes pasos

- [Aprobaciones y políticas](https://aicodeops.dev/es/docs/approvals-and-policies)
- [Controles de calidad](https://aicodeops.dev/es/docs/quality-gates)
- [API](https://aicodeops.dev/es/docs/api)

## Preguntas frecuentes

### ¿El paquete contiene nuestro código fuente?

No. Lista los archivos modificados y un hash SHA-256 del diff, de modo que puedes cotejarlo con el pull request sin que el código salga de tu repositorio.

### ¿Los paquetes antiguos se siguen verificando después de retirar una clave?

Sí. Las claves nunca se eliminan. Una clave retirada deja de firmar paquetes nuevos, y los paquetes que firmó se siguen verificando.
