atproto 0.0.1-preview.1

AT Protocol data model, repositories, identity, XRPC, OAuth and sessions

Readme Files Dependencies Versions

atproto#

Libraries for the AT Protocol in Zena: its data model, encodings, cryptography, identity resolution, and repositories.

Usage#

import {cidForValue, decodeCbor, encodeCbor} from 'atproto/cbor';
import {StringValue, newMap, stringField} from 'atproto/data';

let record = newMap([
  ('$type', new StringValue('app.bsky.feed.post')),
  ('text', new StringValue('Hello from Zena!')),
]);

let bytes = encodeCbor(record);
let cid = cidForValue(record);
let decoded = decodeCbor(bytes);

Libraries#

  • atproto/varint: multiformats unsigned varints.
  • atproto/multibase: multibase strings, and base58btc. The other base encodings are in zena:encoding.
  • atproto/cid: CIDs, their binary and string forms, and the CIDs atproto gives records and blobs.
  • atproto/data: the data model (Value and its cases), its JSON form, and blob references (BlobRef).
  • atproto/cbor: DAG-CBOR encoding and strict decoding, cidForValue, and sortedKeys, the order DAG-CBOR writes map keys in.
  • atproto/syntax: DIDs, handles, NSIDs, record keys, TIDs, datetimes, and CID strings.
  • atproto/car: CAR files and BlockMap, checking every block against its CID.
  • atproto/mst: the Merkle search tree: key heights, nodes, building a tree, and looking a key up through the nodes of a proof.
  • atproto/repo: commits, signing them, and verifying com.atproto.sync.getRecord proofs.
  • atproto/tid: timestamp identifiers, and a clock that hands out increasing ones.
  • atproto/didkey: public keys as multikeys, did:keys, and DID document verification methods, and checking atproto signatures with them.
  • atproto/did: what atproto reads from a DID document: the signing key, the PDS, and the claimed handle.
  • atproto/service-auth: service-auth JWTs, which an account's PDS signs so the account can call another service: creating them, checking them against the issuer's key, the audience, the method, and the time, and refusing a token presented twice (ReplayGuard).
  • atproto/session: signing in to an account's PDS with a password, refreshing and ending the session, and asking the PDS for service-auth tokens, with a password session or an OAuth one (AccountSession).
  • atproto/oauth: signing in with atproto OAuth as a public client, such as a command-line tool: finding the PDS's authorization server, the authorization request with PKCE and DPoP, trading the code for tokens, and a session that signs each request, follows the servers' nonces, refreshes and revokes its tokens.
  • atproto/dpop: DPoP keys and proofs: ES256 proofs for each request, checking them, and JWK thumbprints.
  • atproto/xrpc: an XRPC client, whose requests a RequestSigner can authorize one by one.
  • atproto/methods: the NSIDs of standard com.atproto methods, and xrpcPath, a method's path on a server.
  • atproto/plc: did:plc operations: building and signing them, the DID a genesis operation makes, and sending an operation to a PLC directory.
  • atproto/identity: resolving DIDs (did:plc, did:web) and handles (DNS over HTTPS, then HTTPS), checking handles in both directions.
  • atproto/sync: fetching a record and checking its proof against the DID document's key, fetching a blob and checking it against its CID, and listing a collection's records, which comes with no proof.

atproto/xrpc, atproto/identity, atproto/sync, atproto/session, atproto/oauth, and atproto/plc send requests with zena:fetch; atproto/oauth also reads the clock and draws random bytes. The other libraries have no imports from the host.

5.0 KiB Raw
/**
 * Fetching records and blobs from an account's PDS and checking them, so
 * that what is returned is what the account published, whoever served it.
 *
 * A record comes from `com.atproto.sync.getRecord` with a proof: the
 * commit, signed with the key in the account's DID document, and the tree
 * nodes from the commit to the record. A blob comes from
 * `com.atproto.sync.getBlob` and is checked against its CID.
 *
 * `listRecords` is the exception: `com.atproto.repo.listRecords` answers
 * with no proof, so it is for finding records, and anything relied on is
 * fetched again with `getVerifiedRecord`.
 */

import {readCar} from './car.zena';
import {Cid, HASH_SHA256} from './cid.zena';
import {DidDocument} from './did.zena';
import {PublicKey, verifySignature} from './didkey.zena';
import {RecordProof, verifyRecordProof} from './repo.zena';
import {Value, fromJson} from './data.zena';
import {XrpcClient} from './xrpc.zena';
import {JsonArray, JsonObject, JsonValue} from 'zena:json';
import {REPO_LIST_RECORDS, SYNC_GET_BLOB, SYNC_GET_RECORD} from './methods.zena';

/** A record or blob that could not be fetched or did not check out. */
export class SyncError extends Error {
  new(message: String) : super(message);
}

function clientFor(document: DidDocument) {
  let pds = document.pds;
  if (pds == null) {
    throw new SyncError(`${document.id} names no PDS`);
  }
  return new XrpcClient(pds);
}

/**
 * Fetches `collection/rkey` from the repository of the account `document`
 * describes, and checks its proof against the document's signing key. The
 * result's `record` is null when the proof shows there is no such record.
 */
export async function getVerifiedRecord(document: DidDocument, collection: String, rkey: String): Future<RecordProof> {
  if (document.signingKey == null) {
    throw new SyncError(`${document.id} has no signing key`);
  }
  let key = document.signingKey as PublicKey;
  let response = await clientFor(document).queryRaw(SYNC_GET_RECORD, [
    ('did', document.id),
    ('collection', collection),
    ('rkey', rkey),
  ]);
  let car = readCar(await response.bytes());
  return verifyRecordProof(car, document.id, collection, rkey, (signed, sig) => verifySignature(key, signed, sig));
}

/** Fetches a blob of the account `document` describes, and checks it against `cid`. */
export async function getVerifiedBlob(document: DidDocument, cid: Cid): Future<FixedArray<u8>> {
  if (cid.hashType != HASH_SHA256) {
    throw new SyncError(`cannot check blob ${cid.toString()}: not a SHA-256 CID`);
  }
  let response = await clientFor(document).queryRaw(SYNC_GET_BLOB, [
    ('did', document.id),
    ('cid', cid.toString()),
  ]);
  let body = await response.bytes();
  let actual = Cid.create(cid.codec, body);
  if (!actual.digest.contentEquals(cid.digest)) {
    throw new SyncError(`blob ${cid.toString()} does not match its CID`);
  }
  return body;
}

/** A record as `com.atproto.repo.listRecords` lists it. */
export final class ListedRecord {
  /** The record key. */
  rkey: String;
  cid: Cid;
  value: Value;

  new(rkey: String, cid: Cid, value: Value) : rkey = rkey, cid = cid, value = value;
}

/**
 * The records of `collection` in the repository of the account `document`
 * describes, as its PDS lists them, every page of them. Nothing here is
 * checked against the account's key: fetch a record with
 * `getVerifiedRecord` before relying on it.
 */
export async function listRecords(document: DidDocument, collection: String): Future<GrowableArray<ListedRecord>> {
  let client = clientFor(document);
  let records = new GrowableArray<ListedRecord>();
  var cursor: String | null = null;
  while (true) {
    let params = new GrowableArray<(String, String)>();
    params.push(('repo', document.id));
    params.push(('collection', collection));
    params.push(('limit', '100'));
    let after = cursor;
    if (after != null) {
      params.push(('cursor', after));
    }
    let answer = await client.query(REPO_LIST_RECORDS, params);
    if (!(answer is JsonObject)) {
      throw new SyncError('listRecords answered with something other than an object');
    }
    let page = answer;
    let listed = page['records'];
    if (!(listed is JsonArray)) {
      throw new SyncError('listRecords answered with no records');
    }
    let items = listed;
    for (var i = 0; i < items.length; i += 1) {
      records.push(listedRecord(items[i]));
    }
    let next = page['cursor'];
    if (!(next is String) || items.length == 0) {
      return records;
    }
    cursor = next;
  }
  return records;
}

function listedRecord(item: JsonValue): ListedRecord {
  if (!(item is JsonObject)) {
    throw new SyncError('listRecords listed something other than a record');
  }
  let record = item;
  let uri = record['uri'];
  let cid = record['cid'];
  if (!(uri is String) || !(cid is String)) {
    throw new SyncError('listRecords listed a record with no URI or CID');
  }
  let text = uri;
  var slash = -1;
  for (var i = 0; i < text.length; i += 1) {
    if (text.getByteAt(i) == 47) {
      slash = i;
    }
  }
  return new ListedRecord(text.sliceBytes(slash + 1, text.length), Cid.parse(cid),
      fromJson(record['value']));
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none