# GitHub Showcase: Trust And Audit

The agent signs its findings (ed25519). `cw report verify-bundle` checks — offline,
with nothing but the public key — that every signed finding is in the report
**unaltered**. CW holds no private key: the agent signs, CW only verifies.

CW's trust story is intentionally narrow: it proves record integrity, signed
attribution, and that the signed findings are present and unaltered. It does not
prove that an executor's original self-report was true.

![cw demo tamper forges a signed report three ways — ledger, signature, result — and catches every one offline with only the public key](assets/cw-hero.svg)

## Try The Demo

```bash
npx cool-workflow demo tamper
```

The demo builds a signed report and forges it in **three ways** — each caught
offline with only the public key:

| Layer | Forgery | Expected result |
| --- | --- | --- |
| Ledger | Change a recorded verdict and recompute that record hash. | The downstream hash chain breaks. |
| Signature | Inflate reported tokens and reuse the old ed25519 signature. | Signature verification fails. |
| Result | Edit a signed finding after it was signed. | CW re-derives `sha256(result)`; the signature no longer matches. |

For automation:

```bash
npx cool-workflow demo tamper --json
```

The JSON includes `proven: true` when all three tamper cases are caught.

## Verify A Real Run

```bash
cw telemetry verify <run-id>
cw telemetry verify <run-id> --pubkey <public.pem>
cw audit verify <run-id>
```

| Command | What it checks |
| --- | --- |
| `cw telemetry verify <run-id>` | Recomputes the telemetry ledger chain and record hashes. |
| `cw telemetry verify <run-id> --pubkey <public.pem>` | Also re-runs ed25519 attribution checks for attested usage. |
| `cw audit verify <run-id>` | Re-proves the trust-audit event chain for sandbox, policy, and commit-gate decisions. |

## Verify A Portable Report Offline

Hand someone a sealed bundle — they need nothing but the file:

```bash
cw -q "…" --bundle                              # seal the run into one portable file
cw report verify-bundle report.cwrun.json       # they check it offline
cw report verify-bundle report.cwrun.json \
  --require-signatures                          # …and insist the findings are signed
```

`verify-bundle` re-proves the archive bytes, the telemetry chain, the trust-audit
chain, and the ed25519 signatures — **and** cross-checks that every signed finding
is present in `report.md` unaltered. Edit a finding, in the report or in the
agent's own result, and the check fails. It is the **forward** guarantee: each
signed finding is present and unaltered. It does **not** assert the report holds
*only* signed findings — CW has no key to sign the rendered report, and a
determined re-chainer can drop a signed finding — so verify the findings you act
on against the signed results.

## What A Green Check Means

A passing telemetry verification can support these claims:

- the recorded ledger is internally consistent,
- recorded attested usage was signed by the holder of the configured private key,
- the signature is bound to the recorded run, task, and prompt digest,
- the verification can be re-run offline with the public key.

It does not prove:

- the reported usage number was true at the source,
- the signer was honest,
- a single local party supplied independent third-party attestation,
- the agent output was correct, secure, or useful.

## Fail-Closed States

CW uses explicit states instead of silent promotion:

| State | Meaning |
| --- | --- |
| `attested` | Usage was signed and verified against the configured public key. |
| `unattested` | Usage exists but cannot be verified as signed by the expected key. |
| `absent` | No usage was reported. |
| `blocked` | Work could not proceed, for example because no agent is configured. |
| `parked` | A worker failed or retried to a stop point rather than being fabricated. |

## The Single-Party Limit

If the same operator runs CW, controls the machine, and holds the only signing
key, a green result proves internal consistency and attribution to that key. It
does not create an independent second party.

For stronger assurance, pair CW with an external anchor, a separate signer, or a
separate executor that the local operator cannot rewrite.

## Source Docs

The full trust statement lives in:

- `plugins/cool-workflow/docs/trust-model.md`
- `plugins/cool-workflow/docs/security-trust-hardening.7.md`
- `plugins/cool-workflow/docs/multi-agent-trust-policy-audit.7.md`