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.

6.1 KiB Raw
/**
 * CAR files, version 1 (https://ipld.io/specs/transport/car/carv1/): the
 * archive format atproto uses for repositories and proofs.
 *
 * A CAR file is a header and then blocks, each preceded by its length as a
 * varint. The header is DAG-CBOR, `{version: 1, roots: [cid, ...]}`, and a
 * block is a binary CID followed by the bytes it names.
 *
 * `readCar` checks every block against its CID, so a block map read from a
 * CAR file holds only data whose hashes match.
 */

import {ByteBuffer} from 'zena:core';
import {HashMap} from 'zena:collections';
import {sha256} from 'zena:crypto';
import {decodeCborRange, encodeCbor} from './cbor.zena';
import {Cid, HASH_SHA256} from './cid.zena';
import {IntValue, LinkValue, ListValue, MapValue, Value, field, newMap} from './data.zena';
import {readVarint, writeVarint} from './varint.zena';

/** Fills arrays of CIDs before their elements are set. */
let NO_CID = new Cid(1, 0 as i64, 0 as i64, new FixedArray<u8>(0, 0 as u8));

/** A CAR file that cannot be read, or a block that does not match its CID. */
export class CarError extends Error {
  new(message: String) : super(message);
}

/** Blocks by CID. */
export final class BlockMap {
  #blocks = new HashMap<String, FixedArray<u8>>();
  #cids = new HashMap<String, Cid>();

  /** The bytes `cid` names, or null when the map does not have them. */
  get(cid: Cid): FixedArray<u8> | null {
    if (let (true, bytes) = this.#blocks.get(cid.toString())) {
      return bytes;
    }
    return null;
  }

  has(cid: Cid): boolean {
    return this.#blocks.has(cid.toString());
  }

  /** Stores `bytes` under `cid`. The caller vouches that they match. */
  set(cid: Cid, bytes: FixedArray<u8>): void {
    let key = cid.toString();
    this.#blocks[key] = bytes;
    this.#cids[key] = cid;
  }

  /** Stores `bytes` under the CID of their DAG-CBOR encoding, and returns it. */
  add(value: Value): Cid {
    let bytes = encodeCbor(value);
    let cid = Cid.forDagCbor(bytes);
    this.set(cid, bytes);
    return cid;
  }

  size: i32 {
    get {
      return this.#blocks.size;
    }
  }

  /** Calls `callback` with each block, in no particular order. */
  forEach(callback: (cid: Cid, bytes: FixedArray<u8>) => void): void {
    this.#cids.forEach((key, cid) => {
      callback(cid, this.#blocks[key]);
    });
  }
}

/** A CAR file's roots and blocks. */
export final class Car {
  roots: FixedArray<Cid>;
  blocks: BlockMap;
  /** Where each block's data starts in the file read, by CID. */
  #offsets: HashMap<String, i32>;

  new(roots: FixedArray<Cid>, blocks: BlockMap, offsets: HashMap<String, i32> | null = null)
      : roots = roots, blocks = blocks, #offsets = offsets ?? new HashMap<String, i32>();

  /**
   * Where the data of block `cid` starts in the bytes `readCar` read, or
   * -1 when it holds no such block.
   */
  offsetOf(cid: Cid): i32 {
    if (let (true, offset) = this.#offsets.get(cid.toString())) {
      return offset;
    }
    return -1;
  }
}

/**
 * Reads a CAR file and checks each block against its CID. Only SHA-256
 * CIDs can be checked, so a block with any other hash is rejected.
 */
export function readCar(bytes: FixedArray<u8>): Car {
  let (headerLength, headerStart) = readVarint(bytes, 0, bytes.length);
  let headerEnd = headerStart + (headerLength as i32);
  if (headerLength > (bytes.length - headerStart) as i64) {
    throw new CarError('truncated header');
  }
  let roots = readHeader(decodeCborRange(bytes, headerStart, headerEnd));
  let blocks = new BlockMap();
  let offsets = new HashMap<String, i32>();
  var pos = headerEnd;
  while (pos < bytes.length) {
    let (length, start) = readVarint(bytes, pos, bytes.length);
    if (length > (bytes.length - start) as i64) {
      throw new CarError(`truncated block at offset ${pos}`);
    }
    let end = start + (length as i32);
    let (cid, dataStart) = Cid.decode(bytes, start, end);
    let data = bytes.slice(dataStart, end);
    if (cid.hashType != HASH_SHA256 || !sha256(data).contentEquals(cid.digest)) {
      throw new CarError(`block ${cid.toString()} does not match its CID`);
    }
    blocks.set(cid, data);
    offsets[cid.toString()] = dataStart;
    pos = end;
  }
  return new Car(roots, blocks, offsets);
}

function readHeader(header: Value): FixedArray<Cid> {
  if (!(header is MapValue)) {
    throw new CarError('header is not a map');
  }
  let map = header;
  let version = field(map, 'version');
  if (!(version is IntValue) || version.value != 1) {
    throw new CarError('not a version 1 CAR file');
  }
  let list = field(map, 'roots');
  if (!(list is ListValue)) {
    throw new CarError('header has no roots');
  }
  let items = list.items;
  let roots = new FixedArray<Cid>(items.length, NO_CID);
  for (var i = 0; i < items.length; i += 1) {
    let item = items[i];
    if (!(item is LinkValue)) {
      throw new CarError('a root is not a CID');
    }
    roots[i] = item.cid;
  }
  return roots;
}

/**
 * Writes a CAR file with these roots and blocks. Blocks are written in the
 * order `order` lists them, or in no particular order when it is null.
 */
export function writeCar(roots: FixedArray<Cid>, blocks: BlockMap, order: FixedArray<Cid> | null = null): FixedArray<u8> {
  let rootValues = new FixedArray<Value>(roots.length, new IntValue(0 as i64));
  for (var i = 0; i < roots.length; i += 1) {
    rootValues[i] = new LinkValue(roots[i]);
  }
  let header = newMap();
  header.entries['version'] = new IntValue(1 as i64);
  header.entries['roots'] = new ListValue(rootValues);
  let headerBytes = encodeCbor(header);

  let out = new ByteBuffer();
  writeVarint(out, headerBytes.length as i64);
  out.writeBytes(headerBytes as ByteArray);
  let writeBlock = (cid: Cid, data: FixedArray<u8>) => {
    let cidBytes = cid.toBytes();
    writeVarint(out, (cidBytes.length + data.length) as i64);
    out.writeBytes(cidBytes as ByteArray);
    out.writeBytes(data as ByteArray);
  };
  if (order == null) {
    blocks.forEach(writeBlock);
  } else {
    for (let cid in order) {
      let data = blocks.get(cid);
      if (data == null) {
        throw new CarError(`no block for ${cid.toString()}`);
      }
      writeBlock(cid, data);
    }
  }
  return out.toByteArray() as FixedArray<u8>;
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none