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.

8.6 KiB Raw
/**
 * The atproto data model (https://atproto.com/specs/data-model): the
 * values a record, a commit or a repository node can hold, and their JSON
 * form.
 *
 * A value is null, a boolean, a 64-bit integer, a string, bytes, a link to
 * other data by CID, a list, or a map with string keys. There are no
 * floats. A blob reference is an ordinary map with `$type: "blob"`.
 *
 * In JSON, bytes are `{"$bytes": "<base64>"}` and links are
 * `{"$link": "<cid>"}`. `fromJson` reads JSON strictly, the way the
 * reference implementation does: a `$bytes` or `$link` object must have no
 * other keys, `$type` must be a non-empty string, a blob reference must
 * have exactly the blob keys with a raw CID, and a number must be an
 * integer no larger than 2^53 - 1 in magnitude.
 */

import {OrderedHashMap} from 'zena:collections';
import {floor} from 'zena:math';
import {JsonArray, JsonObject, JsonValue} from 'zena:json';
import {CODEC_RAW, Cid} from './cid.zena';
import {base64} from 'zena:encoding';

/** Data outside the atproto data model, or JSON that does not map to it. */
export class DataError extends Error {
  new(message: String) : super(message);
}

/** The largest integer JSON carries exactly: 2^53 - 1. */
let MAX_SAFE_INTEGER: i64 = 0x1fffffffffffff;

/** A value in the atproto data model. */
export sealed class Value {
  case NullValue
  case BoolValue(value: boolean)
  case IntValue(value: i64)
  case StringValue(value: String)
  case BytesValue(value: FixedArray<u8>)
  case LinkValue(cid: Cid)
  case ListValue(items: FixedArray<Value>)
  case MapValue(entries: OrderedHashMap<String, Value>)
}

/** The value at `key` in `map`, or null when the key is absent. */
export function field(map: MapValue, key: String): Value | null {
  if (let (true, value) = map.entries.get(key)) {
    return value;
  }
  return null;
}

/** The string at `key`, or null when it is absent or not a string. */
export function stringField(map: MapValue, key: String): String | null {
  let value = field(map, key);
  if (value is StringValue) {
    return value.value;
  }
  return null;
}

/** The map at `key`, or null when it is absent or not a map. */
export function mapField(map: MapValue, key: String): MapValue | null {
  let value = field(map, key);
  if (value is MapValue) {
    return value;
  }
  return null;
}

/** The list at `key`, or null when it is absent or not a list. */
export function listField(map: MapValue, key: String): ListValue | null {
  let value = field(map, key);
  if (value is ListValue) {
    return value;
  }
  return null;
}

/** The link at `key`, or null when it is absent or not a link. */
export function linkField(map: MapValue, key: String): Cid | null {
  let value = field(map, key);
  if (value is LinkValue) {
    return value.cid;
  }
  return null;
}

/** A map with no entries yet, for building a value. */
export function newMap(): MapValue {
  return new MapValue(new OrderedHashMap<String, Value>());
}

/**
 * A reference to a blob: its raw CID, MIME type and size. In the data
 * model it is a map, `{$type: "blob", ref, mimeType, size}`.
 */
export final class BlobRef {
  cid: Cid;
  mimeType: String;
  size: i64;

  new(cid: Cid, mimeType: String, size: i64) : cid = cid, mimeType = mimeType, size = size;

  /**
   * Reads a blob reference, from JSON or DAG-CBOR alike. Throws
   * `DataError` for any other value.
   */
  static fromValue(value: Value): BlobRef {
    if (!(value is MapValue)) {
      throw new DataError('blob reference is not a map');
    }
    let map = value;
    if (stringField(map, '$type') != 'blob') {
      throw new DataError("blob reference does not have $type 'blob'");
    }
    checkBlob(map);
    let size = field(map, 'size') as IntValue;
    return new BlobRef(linkField(map, 'ref') as Cid, stringField(map, 'mimeType') as String, size.value);
  }

  toValue(): MapValue {
    let map = newMap();
    map.entries['$type'] = new StringValue('blob');
    map.entries['ref'] = new LinkValue(this.cid);
    map.entries['mimeType'] = new StringValue(this.mimeType);
    map.entries['size'] = new IntValue(this.size);
    return map;
  }
}

/**
 * Reads atproto JSON. Throws `DataError` for JSON outside the data model;
 * see the module comment for the rules.
 */
export function fromJson(json: JsonValue): Value {
  if (json == null) {
    return new NullValue();
  }
  if (json is String) {
    return new StringValue(json);
  }
  if (json is Box<boolean>) {
    return new BoolValue(json.value);
  }
  if (json is Box<f64>) {
    return new IntValue(integerOf(json.value));
  }
  if (json is JsonArray) {
    let items = new FixedArray<Value>(json.length, new NullValue());
    for (var i = 0; i < json.length; i += 1) {
      items[i] = fromJson(json[i]);
    }
    return new ListValue(items);
  }
  return objectFromJson(json);
}

function integerOf(n: f64): i64 {
  if (floor(n) != n) {
    throw new DataError(`not an integer: ${n}`);
  }
  let limit = MAX_SAFE_INTEGER as f64;
  if (n > limit || n < 0.0 - limit) {
    throw new DataError(`integer too large for JSON: ${n}`);
  }
  return n as i64;
}

function objectFromJson(json: JsonObject): Value {
  if (json.has('$link')) {
    return new LinkValue(linkFromJson(json));
  }
  if (json.has('$bytes')) {
    return new BytesValue(bytesFromJson(json));
  }
  let entries = new OrderedHashMap<String, Value>(json.size);
  json.forEach((key, value) => {
    entries[key] = fromJson(value);
  });
  let map = new MapValue(entries);
  checkType(map);
  return map;
}

function linkFromJson(json: JsonObject): Cid {
  if (json.size != 1) {
    throw new DataError('a $link object has other keys');
  }
  let text = json['$link'];
  if (!(text is String)) {
    throw new DataError('$link is not a string');
  }
  try {
    return Cid.parse(text);
  } catch (e) {
    throw new DataError(`$link is not a CID: ${e.message}`);
  }
}

function bytesFromJson(json: JsonObject): FixedArray<u8> {
  if (json.size != 1) {
    throw new DataError('a $bytes object has other keys');
  }
  let text = json['$bytes'];
  if (!(text is String)) {
    throw new DataError('$bytes is not a string');
  }
  try {
    return base64.decode(text);
  } catch (e) {
    throw new DataError(`$bytes is not base64: ${e.message}`);
  }
}

/** Checks the `$type` of a map, and the shape of a blob reference. */
function checkType(map: MapValue): void {
  let type = field(map, '$type');
  if (type == null) {
    return;
  }
  if (!(type is StringValue)) {
    throw new DataError('$type is not a string');
  }
  let name = type.value;
  if (name.length == 0) {
    throw new DataError('$type is empty');
  }
  if (name == 'blob') {
    checkBlob(map);
  }
}

function checkBlob(map: MapValue): void {
  var keys = 0;
  map.entries.forEach((key, value) => {
    if (key != '$type' && key != 'ref' && key != 'mimeType' && key != 'size') {
      throw new DataError(`blob reference has an unknown key '${key}'`);
    }
    keys += 1;
  });
  if (keys != 4) {
    throw new DataError('blob reference is missing a key');
  }
  let ref = linkField(map, 'ref');
  if (ref == null || ref.codec != CODEC_RAW) {
    throw new DataError('blob reference has no raw CID');
  }
  let mimeType = stringField(map, 'mimeType');
  if (mimeType == null || !mimeType.contains('/')) {
    throw new DataError('blob reference has no MIME type');
  }
  let size = field(map, 'size');
  if (!(size is IntValue) || size.value < 0) {
    throw new DataError('blob reference size is not a non-negative integer');
  }
}

/** The atproto JSON form of `value`. */
export function toJson(value: Value): JsonValue {
  return match (value) {
    case NullValue: null
    case BoolValue {value}: new Box<boolean>(value)
    case IntValue {value}: intToJson(value)
    case StringValue {value}: value
    case BytesValue {value}: bytesToJson(value)
    case LinkValue {cid}: linkToJson(cid)
    case ListValue {items}: listToJson(items)
    case MapValue {entries}: mapToJson(entries)
  };
}

function intToJson(n: i64): JsonValue {
  if (n > MAX_SAFE_INTEGER || n < 0 - MAX_SAFE_INTEGER) {
    throw new DataError(`integer too large for JSON: ${n}`);
  }
  return new Box<f64>(n as f64);
}

function bytesToJson(bytes: FixedArray<u8>): JsonValue {
  let json = new JsonObject();
  json['$bytes'] = base64.encode(bytes, false);
  return json;
}

function linkToJson(cid: Cid): JsonValue {
  let json = new JsonObject();
  json['$link'] = cid.toString();
  return json;
}

function listToJson(items: FixedArray<Value>): JsonValue {
  let json = new JsonArray();
  for (let item in items) {
    json.push(toJson(item));
  }
  return json;
}

function mapToJson(entries: OrderedHashMap<String, Value>): JsonValue {
  let json = new JsonObject();
  entries.forEach((key, item) => {
    json[key] = toJson(item);
  });
  return json;
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none