Identity & Auth

Roadmap

How Yoshi turns the egg from a picture into a verifiable identity — and the security boundary that keeps it honest. (Roadmap: P0, the egg picture, ships today; the crypto layer below is cycle 57.)

Two layers, one hard rule

  REAL CRYPTO  (Ed25519 keypair)   ← does the auth. private signs, public verifies.
       │  public key
       ▼
  THE EGG       (a picture of it)   ← does recognition. never carries a secret.

The egg is a picture of a key, never the key. Same category as SSH randomart or GitHub identicons. You authenticate with the keypair behind it; the egg lets a human say "yep, that's mine" at a glance. Deriving a private key from a name is the brain-wallet anti-pattern — names are low-entropy and public, so anyone regenerates it. Real private keys come from a CSPRNG or a passkey, never a name.

The runtime / API boundary

Not everything belongs in the browser. The split:

runs in the browser (public, no secrets) behind the API (sensitive)
the egg picture (egg.js: fnv→SVG) keygen (Ed25519, CSPRNG)
the public key / did:key private-key custody + signing
match-verify (re-render egg from a did, compare) control-verify (the auth check)

The key insight: the verify API holds no secrets. Asymmetric crypto verifies a signature with the public key — so "authenticate this person → true/false" is a cheap public-key check, not a vault op. What must stay off the client is the other half: key generation, custody, signing, encryption.

Two verifies — only one is authentication

  • match — given a name/svg + a did, re-render the egg and compare. Pure public math; proves the picture is consistent. A tamper signal only — never sell it as auth.
  • control — challenge → the holder signs with their private key → the API checks the signature against the did. This is real authentication (the true/false API).

The picture is recognition; the signature is authentication.

Custody — hybrid

  • Users → passkeys / WebAuthn. The private key lives in the device's secure hardware and never touches us. We only ever verify.
  • Agents / projects → an Ed25519 key in a KMS-isolated server vault (they sign autonomously, with no human at the keyboard). This is the only secret-bearing surface — so we isolate it and own as little of it as possible.

Agent-ready, with a face

Because Yoshi generates sites, a generated site can ship — out of the box — an auth.md skill-manifest

  • /.well-known discovery (so agents can register with it, the WorkOS pattern) and its egg as the consent / claim / audit face. The protocol verifies the keys; the egg lets a human recognise which agent, and spot an impostor. Every Yoshi site, agent-ready with a human-legible identity, for free.

Status: roadmap (cycle 57). The egg picture (try it on The Egg) is live; the keypairs, the verify-Worker, and the auth.md emitter are scoped, built when an auth surface needs them.