Botvatar/ Protocols/ Signed identity cards

Signed identity cards

A botvatar isn't a picture with a database record next to it. The credential lives inside the image file, signed with an Ed25519 key, and anyone can check it without asking us anything.

Where the manifest lives

JPEG allows arbitrary comment segments. Botvatar writes one COM segment immediately after the start-of-image marker, prefixed BOTVATAR: and carrying the manifest as JSON. It travels with the file — copy it, email it, drop it in a bucket, the credential comes along.

That also means there is no lookup service to go down, no API to rate-limit you, and no record of yours on our servers that has to stay online for your card to remain provable.

What's in it

• card_id — the card's own identifier.
• agent — the agent name you gave it.
• form — the object the character was built from.
• owner — a truncated SHA-256 of the issuing account's email. Enough to tie cards to one owner, not enough to reveal who they are.
• plan and issued_at — the plan it was issued under, and when.
• img_sha256 — a hash of the image bytes at the moment of signing.
• pubkey — the public key the signature should verify against.
• sig — the Ed25519 signature over all of the above.

What verification actually checks

Three things, in order, and it will tell you which one failed:

1. Is there a manifest at all? If the file has been re-saved by an image editor or captured as a screenshot, the comment segment is gone. That is the most common failure and it is not a bug.
2. Was it issued by us? The manifest's pubkey must match Botvatar's published key. A card carrying someone else's key is not ours.
3. Have the pixels changed? The verifier hashes the image as it stands and compares it to img_sha256. Crop it, recolour it, re-compress it — the hashes diverge and the check fails.

Free cards versus signed cards

Every card carries the provenance manifest, free ones included — the identity story isn't paywalled. What a paid plan adds is the signature. An unsigned manifest describes a card; a signed one proves it. Until it's signed, anyone could have written those fields.

Why Ed25519

Small signatures, fast verification, no parameter choices to get wrong, and native support in the Web Crypto API — which is what lets the whole check happen client-side in a browser with no library to load and no server round trip. A signature that needed a backend to verify would defeat the point of putting it in the file.