# trustverdict

Before you connect an agent, a repo, a package or an MCP
server, ask whether it deserves trust. trustverdict puts
that question to a trust-verification service and brings
back its signed answer: a decision you can act on, the one
reason that drove it, a 0–100 trust score, and the
findings underneath. Eight read-only tools cover the
whole surface, and none of them needs an account or an
API key — every call is anonymous.

Scan results come back exactly as the service issued
them. Nothing is rescored, renamed or summarised locally,
because the result is a signed attestation: its value is
that it is the service's own output, recomputable
offline.

## Configuration

One environment variable controls the client:

- `AGENTAVOW_URL` (optional) — the service base URL.
  Defaults to `https://agentavow.com`.

There is no API key and no auth header.

## Tools

- `scan_repo` — scan a public GitHub repo, addressed as
  `owner/name`. The answer leads with the decision, a
  signed 0–100 trust score, and the adoption score.
- `scan_package` — scan a package by name; an optional
  `ecosystem` says which registry it lives on (npm,
  PyPI, crates, Docker, or Hugging Face).
- `scan_mcp_server` — point it at a live MCP server
  `url`; its tool definitions are checked for poisoning
  and prompt-injection.
- `verify_trust` — resolve an `agent` identity and get
  its current trust score.
- `check_interaction_safety` — ask whether a specific
  `interaction` (for example delegating work or trading)
  with an `agent` is safe.
- `lookup_identity` — resolve a DID (`did:web:…` or
  `did:key:…`) or search agents by name with one
  `query`.
- `get_trust_badge` — a shields-style badge for an
  `agent`: the SVG URL plus ready-to-paste README
  markdown.
- `about_agentavow` — how the service reaches a verdict
  and how to read one. This tool is answered locally and
  makes no request.

### Reading a verdict

Every scan leads with `decision` — `safe`, `review`, or
`do_not_connect` — and the `decision_reason` that
triggered it, followed by a `summary`, the signed
`trust_score` from 0 to 100, the `tier`, whether the
subject is `certified`, the `adoption` score, and the
findings. A second, binary `verdict` (`safe` or
`needs_review`) carries its own `verdict_reason`:
`clean`, `blocking_findings`, `thin_coverage`, or
`low_signals`. Scan attestations are Ed25519-signed
(JWS) and can be recomputed offline.

### Validation and errors

Validation runs before any request. An empty or missing
argument fails with `<arg> must be a non-empty string`,
and `scan_repo` additionally requires the `owner/name`
shape, failing with `repo must look like owner/name`.
An upstream non-2xx reply fails with
`agentavow error: HTTP <status>`; an unreachable service
fails with `agentavow unreachable`.

### Endpoint provenance

Every request path below is a labelled reconstruction:
the service's tool surface, base URL and verdict
vocabulary are documented, but the per-tool wire paths
are not pinned by the documentation, so these follow the
documented base and REST conventions.

- `POST /api/scan/repo` — reconstruction (`scan_repo`)
- `POST /api/scan/package` — reconstruction
  (`scan_package`)
- `POST /api/scan/mcp-server` — reconstruction
  (`scan_mcp_server`)
- `GET /api/agents/<agent>/trust` — reconstruction
  (`verify_trust`)
- `POST /api/interaction-safety` — reconstruction
  (`check_interaction_safety`)
- `GET /api/identity?q=<query>` — reconstruction
  (`lookup_identity`)
- `GET /api/agents/<agent>/badge` — reconstruction
  (`get_trust_badge`)

The `agent` segment in the two GET paths and the `q=`
value are URL-encoded. `about_agentavow` has no wire at
all.

## CLI

Each tool is a subcommand taking one JSON argument
string:

```bash
npx @reneturcios/trustverdict scan_repo '{"repo":"octocat/hello-world"}'
npx @reneturcios/trustverdict scan_package '{"package":"express","ecosystem":"npm"}'
npx @reneturcios/trustverdict scan_mcp_server '{"url":"https://example.com/mcp"}'
npx @reneturcios/trustverdict verify_trust '{"agent":"did:web:example.com"}'
npx @reneturcios/trustverdict check_interaction_safety '{"agent":"did:web:example.com","interaction":"delegate"}'
npx @reneturcios/trustverdict lookup_identity '{"query":"did:web:example.com"}'
npx @reneturcios/trustverdict get_trust_badge '{"agent":"did:web:example.com"}'
npx @reneturcios/trustverdict about_agentavow '{}'
npx @reneturcios/trustverdict --version
```

Output is the tool's result text (the upstream JSON on
success). Exit codes: `0` on success, `1` on a runtime
error (including a validation or upstream failure), `2`
on a usage error.

## MCP server

```bash
npx -y @reneturcios/trustverdict mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "trustverdict": {
      "command": "npx",
      "args": ["-y", "@reneturcios/trustverdict", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/trustverdict
docker run --rm ghcr.io/cloudcorprecords/trustverdict scan_repo '{"repo":"octocat/hello-world"}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios