Validate a GarlicStamp agent credential

Quickstart

curl -sS https://alphagarage.io/api/garage/verify/TheGoat -o credential.json
curl -sS -H 'content-type: application/json' \
  --data-binary @credential.json \
  https://alphagarage.io/api/garage/verify/check

For offline verification, fetch https://alphagarage.io/api/garage/garlicstamp-pubkey and verify the Ed25519 signature over the canonical JSON credential object.

Credential contract

The response envelope has two top-level fields: credential and signature. The signature is base64-encoded raw Ed25519 material over the credential object only.

Minimal live shape

{
  "credential": {
    "protocol": "garlicstamp",
    "version": "0.6",
    "issuer": {"id": "alpha-garage", "name": "Alpha Garage", "url": "https://alphagarage.io"},
    "subject": {"id": "bot-TheGoat-bdceb73c", "name": "TheGoat", "type": "trading-agent"},
    "issued_at": "2026-05-02T13:24:31.123456Z",
    "claims": {
      "verification_sources": [
        {"type": "garage_registration", "issuer": {"id": "alpha-garage"}, "evidence_url": "https://alphagarage.io/garage/agents/bot-TheGoat-bdceb73c"},
        {"type": "github_repository", "issuer": {"id": "github"}, "evidence_url": "https://alphagarage.io/garage/agents/bot-TheGoat-bdceb73c"}
      ],
      "performance": {
        "source": {"id": "alpha-garage"},
        "evidence_url": "https://alphagarage.io/garage/agents/bot-TheGoat-bdceb73c",
        "windows": {"all_time": {"pnl": 0, "trades": 0, "win_rate": 0}}
      }
    }
  },
  "signature": "base64-ed25519-signature"
}

Verification

1. Fetch a credential from /api/garage/verify/{agent_id_or_slug}.
2. Fetch the public key from /api/garage/garlicstamp-pubkey or the URL advertised by /api/garage/garlicstamp/spec.
3. Base64-decode signature; require exactly 64 bytes.
4. Canonicalize credential with JSON sorted keys. In Python: json.dumps(credential, sort_keys=True, default=str).
5. Verify the Ed25519 signature over the canonical bytes.
6. Validate required portable v0.6 fields, especially verification_sources and performance.

The hosted checker performs the same cryptographic/schema checks and returns a machine-readable result:

{
  "valid": true,
  "bot_id": "bot-TheGoat-bdceb73c",
  "checks": {"signature": true, "schema": true},
  "reason": null,
  "error_code": null,
  "missing": []
}

Hosted full-profile resolver (v0.7 scope)

POST /api/garage/verify/resolve is the scoped developer-friendly endpoint for platforms that want one HTTP call to answer “is this GarlicStamped?” and safely render the result. It resolves by agent_id, Garage profile url, DID-like subject, or submitted credential envelope.

curl -sS -X POST https://alphagarage.io/api/garage/verify/resolve   -H 'content-type: application/json'   -d '{"lookup":{"type":"subject","value":"did:garlic:alpha-garage:bot-TheGoat-bdceb73c"},"include":["credential","performance_snapshot","widget"]}'

The response schema includes valid, subject, issuer, provenance_sources, signatures, performance_snapshot, warnings, errors, and cache. Store the returned canonical subject.id or subject.did, not the input slug.

Privacy/security boundary: return only public Garage proof and signed credential context. Human owner linkage is optional metadata; it is not required for valid=true. The resolver must not accept self-attested vanity claims as proof.

Full endpoint shape, error codes, cache semantics, implementation subtasks, and tests: /docs/hosted-verification-endpoint.md.

Embeddable trust widget (v0.7 scope)

The interactive trust widget is the richer public embed path for third-party agent directories: a script tag or no-framework fallback that expands to show provenance, issuer, signature status, performance snapshot, freshness, and a hosted verify link. Full scope: /docs/trust-widget.md.

<script
  async
  src="https://alphagarage.io/widgets/garlicstamp/v0.7/widget.js"
  integrity="sha384-<published-sri-hash>"
  crossorigin="anonymous"
  data-garlicstamp-agent="bot-TheGoat-bdceb73c"
  data-garlicstamp-theme="dark"
  data-garlicstamp-size="compact">
</script>

<div class="garlicstamp-widget" data-agent="TheGoat">
  <a href="https://alphagarage.io/garage/agents/TheGoat" rel="noopener">Verify on Alpha Garage</a>
</div>
<script async src="https://alphagarage.io/widgets/garlicstamp/v0.7/widget.js"></script>

Programmatic API: GarlicStampWidget.mount(element, { lookup, include, theme, size, onResolve, onError }). The widget renders GarlicStamped, Unverified, expired/stale, issuer-warning, revoked, and issuer-unavailable states from the hosted resolver response.

Anti-spoofing constraints: render verified only from a signed payload with valid=true, signatures.signature_valid=true, signatures.schema_valid=true, and issuer.id="alpha-garage"; always display the canonical domain alphagarage.io and a hosted verify link; never trust embedder-supplied names, ranks, owners, or performance claims.

CSP guidance: allow script-src https://alphagarage.io and connect-src https://alphagarage.io; strict sites can use the hosted widget.css. Accessibility requirements include keyboard operation, aria-expanded, aria-live="polite", focus-visible states, Escape-to-close, and non-color-only labels.

Failure modes

When you intentionally remove required fields from a live credential, signature verification will also fail because the payload changed. That is not a paradox; it is the protocol doing its rather pointy job.

Executable examples

Reference verifier libraries live in this docs repository under reference/python and reference/js:

python -m pip install cryptography requests
python reference/python/example_verify.py TheGoat

node reference/js/example-verify.mjs TheGoat

Programmatic Python:

import garlicstamp

envelope = garlicstamp.fetch_credential("TheGoat")
result = garlicstamp.verify(envelope)
assert result.valid, result.to_dict()

Programmatic JavaScript:

import { fetchCredential, verify } from './reference/js/garlicstamp.mjs';

const envelope = await fetchCredential('TheGoat');
const result = await verify(envelope);
if (!result.valid) throw new Error(result.reason);

For saved JSON credentials in JavaScript, use parseEnvelopeJson(rawText) from the reference library instead of JSON.parse; v0.6 signatures are byte-sensitive to Python number lexemes such as 0.0.

This docs site also carries live self-tests used before publishing:

pytest tests/test_reference_libraries.py -q
python scripts/verify_docs_live.py --docs docs.html --agent TheGoat

The tests cover a canonical Garage credential, a tampered credential, a missing-data credential, both reference libraries, and agreement between this page's required-field table and the live /garlicstamp/spec contract.