Skip to content

Client Sybil Proofs

Freebird issuance accepts an optional sybil_proof object on V4 and V7 native bearer issuance requests. If the issuer is configured with a Sybil mode, issuance requires a matching proof. V5 public bearer issuance is retired.

The local freebird-interface binary can attach proofs in two ways:

cargo run -p freebird-interface -- --pow-difficulty 20
cargo run -p freebird-interface -- --sybil-proof-json proof.json

Environment variables are also supported:

FREEBIRD_ISSUER_URL=http://127.0.0.1:8081 \
FREEBIRD_VERIFIER_URL=http://127.0.0.1:8082 \
FREEBIRD_POW_DIFFICULTY=20 \
cargo run -p freebird-interface

Proof Of Work

For single V4 issuance, the proof input is bound to the blinded request:

freebird:issue:v1:<issuer_id>:<blinded_element_b64>

The interface computes this automatically when --pow-difficulty or FREEBIRD_POW_DIFFICULTY is set.

V7 native bearer issuance uses the same request-bound proof model, but the binding is the exact canonical V7 request body and route. A client must mine against the bytes it sends to /v7/native-bearer/issue; changing the body, token-key ID, or V7 descriptor requires a fresh proof.

JSON Proof Input

--sybil-proof-json reads one JSON object matching the common SybilProof schema. Examples:

{
  "type": "invitation",
  "code": "invite-code",
  "signature": "base64url-signature"
}

{
  "type": "webauthn",
  "subject_hash": "opaque-subject-hash",
  "auth_proof": "base64url-proof",
  "timestamp": 1777920000
}

{
  "type": "multi_party_vouching",
  "vouchee_id_hash": "hash",
  "vouches": [],
  "hmac_proof": "base64url-proof",
  "timestamp": 1777920000
}

For combined and or threshold modes, wrap proofs in:

{
  "type": "multi",
  "proofs": []
}

WebAuthn

WebAuthn proofs are produced by the issuer WebAuthn authentication flow. The proof is bound to an opaque subject_hash, not the local passkey label used to find a credential.

A browser client is served at /webauthn/, with distinct pages at /webauthn/register and /webauthn/authenticate. The normal browser flow hands proofs back to a requesting client by callback or postMessage; proof JSON is only shown when no requesting client is present.

Custom clients should authenticate through /webauthn/authenticate/start and /webauthn/authenticate/finish, then pass the returned proof as the webauthn Sybil proof for issuance.

Multi-Party Vouching

Vouching proofs are generated from server-side vouching state. Operators manage trusted vouchers and pending vouches through /admin/vouching/*; clients submit the final multi_party_vouching proof object during issuance.