atproto_repo
Alpha, pre-release. Pre-1.0, evolving alongside at-record; expect breaking changes between 0.x releases.
Sans-io verification of atproto repository
proofs. Given the CAR a PDS returns for com.atproto.sync.getRecord, the
account’s DID and its signing key, verify_record shows that the record is in
that account’s repository and that the repository head is signed by that key.
The caller owns all IO: fetching the CAR and resolving the DID document.
Runs on both the Erlang and JavaScript targets. Signatures go through
kryptos, hashing through gleam_crypto.
Usage
import atproto_repo/key
import atproto_repo/proof
import gleam/string
// publicKeyMultibase of the #atproto verification method in the DID document
let assert Ok(signing_key) =
key.from_multikey("zQ3shunBKsXixLxKtC5qeSG9E4J5RkGN57im31pcTzbNQnm5w")
case
proof.verify_record(
car: car_bytes,
did: "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
collection: "app.bsky.actor.profile",
rkey: "self",
key: signing_key,
)
{
Ok(verified) -> verified.record
Error(error) -> panic as string.inspect(error)
}
VerifiedRecord carries the record’s Cid and decoded dag_cbor.Value, the
commit’s Cid and its rev. Every ProofError variant names the step that
failed: the CAR, a missing block (by CID), the commit’s shape, version or DID,
the signature (including high-S), a malformed MST node, or the record not being
in the tree.
Modules
| Module | What it does |
|---|---|
atproto_repo/proof | verify_record and its error vocabulary. |
atproto_repo/key | PublicKey from did:key or Multikey; atproto signature verification (low-S). |
atproto_repo/car | CAR v1 reader; every block is hashed against the CID its section claims. |
atproto_repo/limits | Resource bounds for untrusted CARs, with safe defaults. |
atproto_repo/cid | The atproto CIDv1 (SHA-256; DAG-CBOR or raw), as string and bytes. |
atproto_repo/dag_cbor | Strict decoder and canonical encoder for the atproto DAG-CBOR subset. |
What is and is not checked
- The first CAR root is the commit; further roots and blocks off the path are ignored. Blocks are not trusted by position, only by hash.
- A CAR from
getRecordholds one path.RecordNotInTreemeans the walk reached an empty slot in nodes the CAR carries; a node it does not carry isMissingBlock, so a CAR for one record proves little about another. - Only commit version 3 is accepted.
- Only compressed points are accepted for keys, as
did:keyrequires. - Integers beyond the JavaScript safe range (2^53) are rejected on both targets, so both agree on what is valid.
- Inputs are bounded by
atproto_repo/limits. The defaults are 64 MiB of CAR, 500,000 blocks, 1,000,000 bytes per block (the sync spec’s record limit) and 256 entries per MST node;proof.verify_record_withandcar.read_withtake your own. Sizes are checked before a block is hashed or decoded. - Verification methods:
key.from_verification_methodtakesMultikeyand the legacyEcdsaSecp256k1VerificationKey2019andEcdsaSecp256r1VerificationKey2019, whose key is a bare compressed point.