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.

20.0 KiB Raw
/**
 * `did:plc` operations (https://web.plc.directory/spec/v0.1/did-plc): what
 * a PLC directory records for a DID, and how a new DID is made.
 *
 * An operation sets the whole of a DID's state:
 *
 * ```json
 * {
 *   "type": "plc_operation",
 *   "rotationKeys": ["did:key:zQ3sh...", "did:key:zDnae..."],
 *   "verificationMethods": {"atproto": "did:key:zDnae..."},
 *   "alsoKnownAs": ["at://router.acme.pkg.zena-lang.dev"],
 *   "services": {
 *     "atproto_pds": {"type": "AtprotoPersonalDataServer", "endpoint": "https://pkg.zena-lang.dev"}
 *   },
 *   "prev": null,
 *   "sig": "..."
 * }
 * ```
 *
 * `rotationKeys` may sign the next operation, the first ranked highest.
 * `prev` is the CID of the operation this one follows, as a string, or null
 * for the first, the genesis operation. `sig` is the base64url signature,
 * without padding, of the operation's DAG-CBOR encoding without `sig`, by
 * one of the rotation keys: for a genesis operation one of its own, and
 * otherwise one of the previous operation's.
 *
 * A DID is made by its genesis operation: `did:plc:` followed by the first
 * 24 characters of the lowercase base32 SHA-256 hash of the signed
 * operation's DAG-CBOR encoding. `submitPlcOperation` sends an operation
 * to a PLC directory. `checkOperation` is what a directory checks before
 * it records one, `nullifiedEntries` which of its records a later one
 * replaced, and `didDocument` the document it serves.
 */

import {Future} from 'zena:async';
import {OrderedHashMap} from 'zena:collections';
import {sha256} from 'zena:crypto';
import {base32Lower, base64Url} from 'zena:encoding';
import {fetch} from 'zena:fetch';
import {JsonArray, JsonObject, JsonValue, parseJson, stringify} from 'zena:json';
import {encodeCbor} from './cbor.zena';
import {Cid} from './cid.zena';
import {ListValue, MapValue, NullValue, StringValue, Value, newMap} from './data.zena';
import {PublicKey, formatDidKey, parseDidKey, verifySignature} from './didkey.zena';

/** An operation that is malformed, or that a PLC directory refused. */
export class PlcError extends Error {
  new(message: String) : super(message);
}

/** A service a DID document lists, such as the account's PDS. */
export final class PlcService {
  /** Such as `AtprotoPersonalDataServer`. */
  kind: String;
  endpoint: String;

  new(kind: String, endpoint: String) : kind = kind, endpoint = endpoint;
}

/** A `plc_operation`, signed or not. */
export final class PlcOperation {
  /** `did:key`s, highest ranked first. */
  rotationKeys: Array<String>;
  /** `did:key`s by name; `atproto` is the repository signing key. */
  verificationMethods: OrderedHashMap<String, String>;
  /** URIs such as `at://<handle>`. */
  alsoKnownAs: Array<String>;
  /** Services by name; `atproto_pds` is the account's PDS. */
  services: OrderedHashMap<String, PlcService>;
  /** The CID of the operation this follows, or null for a genesis operation. */
  prev: String | null;
  /** The base64url signature, or null before signing. */
  sig: String | null;

  new(rotationKeys: Array<String>, verificationMethods: OrderedHashMap<String, String>,
      alsoKnownAs: Array<String>, services: OrderedHashMap<String, PlcService>,
      prev: String | null, sig: String | null = null)
      : rotationKeys = rotationKeys, verificationMethods = verificationMethods,
        alsoKnownAs = alsoKnownAs, services = services, prev = prev, sig = sig;

  /** The operation in the data model, with `sig` when it is signed. */
  toValue(): MapValue {
    let map = this.#unsigned();
    let sig = this.sig;
    if (sig != null) {
      map.entries['sig'] = new StringValue(sig);
    }
    return map;
  }

  /** The operation signed by `sign`, which signs with a rotation key. */
  signedWith(sign: (bytes: FixedArray<u8>) => FixedArray<u8>): PlcOperation {
    return this.withSignature(sign(this.signingBytes()));
  }

  /**
   * The bytes a rotation key signs: the operation without `sig`, as
   * DAG-CBOR. For a signer that answers later, such as a key management
   * service, with `withSignature` after.
   */
  signingBytes(): FixedArray<u8> {
    return encodeCbor(this.#unsigned());
  }

  /** The operation with `signature`, 64 bytes of low-S r and s, as its `sig`. */
  withSignature(signature: FixedArray<u8>): PlcOperation {
    return new PlcOperation(this.rotationKeys, this.verificationMethods, this.alsoKnownAs,
        this.services, this.prev, base64Url.encode(signature, false));
  }

  /** Whether `key` made the operation's signature. */
  isSignedBy(key: PublicKey): boolean {
    let sig = this.sig;
    if (sig == null) {
      return false;
    }
    var signature = new FixedArray<u8>(0, 0 as u8);
    try {
      signature = base64Url.decode(sig);
    } catch (e) {
      return false;
    }
    return verifySignature(key, encodeCbor(this.#unsigned()), signature);
  }

  /** The CID of the signed operation, which the next operation names as `prev`. */
  cid(): Cid {
    return Cid.forDagCbor(encodeCbor(this.toValue()));
  }

  toJson(): JsonObject {
    let json = new JsonObject();
    json['type'] = 'plc_operation';
    json['rotationKeys'] = stringArray(this.rotationKeys);
    let methods = new JsonObject();
    this.verificationMethods.forEach((name, key) => {
      methods[name] = key;
    });
    json['verificationMethods'] = methods;
    json['alsoKnownAs'] = stringArray(this.alsoKnownAs);
    let services = new JsonObject();
    this.services.forEach((name, service) => {
      let entry = new JsonObject();
      entry['type'] = service.kind;
      entry['endpoint'] = service.endpoint;
      services[name] = entry;
    });
    json['services'] = services;
    json['prev'] = this.prev;
    let sig = this.sig;
    if (sig != null) {
      json['sig'] = sig;
    }
    return json;
  }

  /** Reads an operation's JSON form. Throws `PlcError`. */
  static fromJson(json: JsonValue): PlcOperation {
    if (!(json is JsonObject)) {
      throw new PlcError('an operation is not a JSON object');
    }
    let object = json;
    if (object['type'] != 'plc_operation') {
      throw new PlcError('the operation is not a plc_operation');
    }
    let methods = new OrderedHashMap<String, String>();
    membersOf(object, 'verificationMethods').forEach((name, value) => {
      methods[name] = stringOf(value, 'a verification method');
    });
    let services = new OrderedHashMap<String, PlcService>();
    membersOf(object, 'services').forEach((name, value) => {
      if (!(value is JsonObject)) {
        throw new PlcError(`service ${name} is not an object`);
      }
      let entry = value;
      services[name] = new PlcService(stringOf(entry['type'], 'a service type'),
          stringOf(entry['endpoint'], 'a service endpoint'));
    });
    let prev = object['prev'];
    let sig = object['sig'];
    return new PlcOperation(
        stringsOf(object, 'rotationKeys'), methods, stringsOf(object, 'alsoKnownAs'), services,
        if (prev == null) null else stringOf(prev, 'prev'),
        if (sig == null) null else stringOf(sig, 'sig'));
  }

  #unsigned(): MapValue {
    let map = newMap();
    map.entries['type'] = new StringValue('plc_operation');
    map.entries['rotationKeys'] = stringList(this.rotationKeys);
    let methods = newMap();
    this.verificationMethods.forEach((name, key) => {
      methods.entries[name] = new StringValue(key);
    });
    map.entries['verificationMethods'] = methods;
    map.entries['alsoKnownAs'] = stringList(this.alsoKnownAs);
    let services = newMap();
    this.services.forEach((name, service) => {
      let entry = newMap();
      entry.entries['type'] = new StringValue(service.kind);
      entry.entries['endpoint'] = new StringValue(service.endpoint);
      services.entries[name] = entry;
    });
    map.entries['services'] = services;
    let prev = this.prev;
    map.entries['prev'] = if (prev == null) new NullValue() else new StringValue(prev);
    return map;
  }
}

/**
 * An unsigned genesis operation for an account whose repository is signed
 * by `signingKey`, named `handle`, at the PDS `pdsEndpoint`, which
 * `rotationKeys` may change, the first ranked highest.
 */
export function genesisOperation(signingKey: PublicKey, rotationKeys: Array<PublicKey>,
    handle: String, pdsEndpoint: String): PlcOperation {
  let rotation = new GrowableArray<String>();
  for (let key in rotationKeys) {
    rotation.push(formatDidKey(key));
  }
  let methods = new OrderedHashMap<String, String>();
  methods['atproto'] = formatDidKey(signingKey);
  let services = new OrderedHashMap<String, PlcService>();
  services['atproto_pds'] = new PlcService('AtprotoPersonalDataServer', pdsEndpoint);
  let aka = new GrowableArray<String>();
  aka.push(`at://${handle}`);
  return new PlcOperation(rotation, methods, aka, services, null);
}

/**
 * The DID a signed genesis operation makes. Throws `PlcError` when the
 * operation is not a signed genesis operation, or no rotation key it lists
 * signed it.
 */
export function didOfGenesis(operation: PlcOperation): String {
  if (operation.prev != null) {
    throw new PlcError('the operation follows another, so it makes no DID');
  }
  if (operation.sig == null) {
    throw new PlcError('the operation is not signed');
  }
  var signed = false;
  for (let key in operation.rotationKeys) {
    signed = signed || operation.isSignedBy(parseDidKey(key));
  }
  if (!signed) {
    throw new PlcError('none of the operation\'s rotation keys signed it');
  }
  let hash = sha256(encodeCbor(operation.toValue()));
  return `did:plc:${base32Lower.encode(hash, false).sliceBytes(0, 24)}`;
}

/**
 * The unsigned operation that undoes every operation after the one whose
 * CID is `cid` in `log`, oldest first: a copy of that operation, naming it
 * as `prev`. Signed by `key`, a PLC directory takes it in place of the
 * operations after `cid` when it comes within 72 hours of the first of
 * them, and `key` is one of `cid`'s rotation keys ranked above the key
 * that signed that first one. Throws `PlcError` when `cid` is not in
 * `log`, is its last operation, or `key` does not rank high enough.
 */
export function undoOperation(log: Array<PlcOperation>, cid: String, key: PublicKey): PlcOperation {
  var at = -1;
  for (var i = 0; i < log.length; i += 1) {
    if (log[i].cid().toString() == cid) {
      at = i;
    }
  }
  if (at < 0) {
    throw new PlcError(`${cid} is not in the log`);
  }
  if (at == log.length - 1) {
    throw new PlcError(`${cid} is the last operation; there is nothing after it to undo`);
  }
  let kept = log[at];
  let wanted = formatDidKey(key);
  var rank = -1;
  for (var i = 0; i < kept.rotationKeys.length; i += 1) {
    if (kept.rotationKeys[i] == wanted) {
      rank = i;
    }
  }
  let signerRank = rankOfSigner(kept, log[at + 1]);
  if (rank < 0) {
    throw new PlcError(`${wanted} is not one of ${cid}'s rotation keys`);
  }
  if (signerRank >= 0 && rank >= signerRank) {
    throw new PlcError(`${wanted} ranks ${rank + 1}, not above the key that signed the operation after ${cid}, which ranks ${signerRank + 1}`);
  }
  return new PlcOperation(kept.rotationKeys, kept.verificationMethods, kept.alsoKnownAs, kept.services, cid);
}

/**
 * Checks that `operation` may follow `log`, the operations a directory has
 * recorded for `did`, oldest first. Throws `PlcError` when it may not.
 *
 * The first must be a genesis operation that makes `did`. Each after it
 * must name the last as `prev` and be signed by one of the last one's
 * rotation keys. The specification also lets a higher-ranked rotation key
 * replace operations from the last 72 hours; this does not, so it suits a
 * directory whose operations only go forward, such as a test's.
 * `checkOperation` does.
 */
export function checkNextOperation(did: String, log: Array<PlcOperation>, operation: PlcOperation): void {
  if (log.length == 0) {
    let made = didOfGenesis(operation);
    if (made != did) {
      throw new PlcError(`the genesis operation makes ${made}, not ${did}`);
    }
    return;
  }
  let last = log[log.length - 1];
  let prev = operation.prev;
  let lastCid = last.cid().toString();
  if (prev == null || prev != lastCid) {
    throw new PlcError(`the operation must follow ${lastCid}`);
  }
  for (let key in last.rotationKeys) {
    if (operation.isSignedBy(parseDidKey(key))) {
      return;
    }
  }
  throw new PlcError('none of the previous operation\'s rotation keys signed the operation');
}

/** How long a higher-ranked rotation key may replace an operation after a directory records it: 72 hours, in microseconds. */
export let NULLIFY_WINDOW_MICROS = 259200000000 as i64;

/** An operation as a directory recorded it, with when, in microseconds since the epoch. */
export final class PlcLogEntry {
  operation: PlcOperation;
  createdAt: i64;

  new(this.operation, this.createdAt);
}

/**
 * Which of `entries`, every operation a directory recorded for a DID,
 * oldest first, a later one replaced: each after the operation a later one
 * names as `prev`, when that was not the last then. The specification
 * calls them nullified. The rest, in order, are the DID's operations
 * (`activeOperations`).
 */
export function nullifiedEntries(entries: Array<PlcLogEntry>): FixedArray<boolean> {
  let nullified = new FixedArray<boolean>(entries.length, false);
  // The DID's operations after each entry, as indexes into `entries`.
  let chain = new FixedArray<i32>(entries.length, 0);
  var length = 0;
  for (var i = 0; i < entries.length; i += 1) {
    let prev = entries[i].operation.prev;
    if (prev != null) {
      while (length > 0 && entries[chain[length - 1]].operation.cid().toString() != prev) {
        nullified[chain[length - 1]] = true;
        length -= 1;
      }
    }
    chain[length] = i;
    length += 1;
  }
  return nullified;
}

/** The operations of `entries` no later one replaced (`nullifiedEntries`), oldest first. */
export function activeOperations(entries: Array<PlcLogEntry>): Array<PlcOperation> {
  let nullified = nullifiedEntries(entries);
  let operations = new GrowableArray<PlcOperation>();
  for (var i = 0; i < entries.length; i += 1) {
    if (!nullified[i]) {
      operations.push(entries[i].operation);
    }
  }
  return operations;
}

/**
 * Checks that a directory may record `operation` for `did` at `now`, in
 * microseconds, after `entries`, every operation it recorded for `did`,
 * oldest first, replaced ones included. Throws `PlcError` when it may not.
 *
 * It takes what `checkNextOperation` takes: an operation that follows the
 * last of the DID's operations. It also takes one that follows an earlier
 * one, replacing those after it, as the specification does: when it is
 * signed by one of that earlier operation's rotation keys ranked above the
 * key that signed the first operation it replaces, and the directory
 * recorded that one no more than 72 hours before `now`.
 */
export function checkOperation(did: String, entries: Array<PlcLogEntry>, operation: PlcOperation, now: i64): void {
  let nullified = nullifiedEntries(entries);
  let active = new GrowableArray<PlcLogEntry>();
  let operations = new GrowableArray<PlcOperation>();
  for (var i = 0; i < entries.length; i += 1) {
    if (!nullified[i]) {
      active.push(entries[i]);
      operations.push(entries[i].operation);
    }
  }
  let prev = operation.prev;
  if (active.length == 0 || prev == null || prev == active[active.length - 1].operation.cid().toString()) {
    checkNextOperation(did, operations, operation);
    return;
  }
  var at = -1;
  for (var i = 0; i < active.length; i += 1) {
    if (active[i].operation.cid().toString() == prev) {
      at = i;
    }
  }
  if (at < 0) {
    throw new PlcError(`the operation follows ${prev}, which is not one of ${did}'s operations`);
  }
  let kept = active[at].operation;
  let first = active[at + 1];
  let rank = rankOfSigner(kept, operation);
  if (rank < 0) {
    throw new PlcError(`none of ${prev}'s rotation keys signed the operation`);
  }
  let signerRank = rankOfSigner(kept, first.operation);
  if (signerRank >= 0 && rank >= signerRank) {
    throw new PlcError(`the operation is signed by ${prev}'s rotation key ranked ${rank + 1}, not above the one ranked ${signerRank + 1}, which signed the operation it would replace`);
  }
  if (now - first.createdAt > NULLIFY_WINDOW_MICROS) {
    throw new PlcError(`the operations after ${prev} were recorded more than 72 hours ago, too long to replace`);
  }
}

/** Where the key that signed `operation` ranks among `previous`'s rotation keys, from 0, or -1 for none of them. */
function rankOfSigner(previous: PlcOperation, operation: PlcOperation): i32 {
  for (var i = 0; i < previous.rotationKeys.length; i += 1) {
    if (operation.isSignedBy(parseDidKey(previous.rotationKeys[i]))) {
      return i;
    }
  }
  return -1;
}

/** The DID document `operation` gives `did`, as a PLC directory serves it. */
export function didDocument(did: String, operation: PlcOperation): JsonObject {
  let doc = new JsonObject();
  let context = new JsonArray();
  context.push('https://www.w3.org/ns/did/v1');
  context.push('https://w3id.org/security/multikey/v1');
  doc['@context'] = context;
  doc['id'] = did;
  doc['alsoKnownAs'] = stringArray(operation.alsoKnownAs);
  let methods = new JsonArray();
  operation.verificationMethods.forEach((name, key) => {
    let method = new JsonObject();
    method['id'] = `${did}#${name}`;
    method['type'] = 'Multikey';
    method['controller'] = did;
    method['publicKeyMultibase'] = key.sliceBytes('did:key:'.length, key.length);
    methods.push(method);
  });
  doc['verificationMethod'] = methods;
  let services = new JsonArray();
  operation.services.forEach((name, service) => {
    let entry = new JsonObject();
    entry['id'] = `#${name}`;
    entry['type'] = service.kind;
    entry['serviceEndpoint'] = service.endpoint;
    services.push(entry);
  });
  doc['service'] = services;
  return doc;
}

/**
 * Sends `operation` for `did` to the PLC directory at `directory`, such as
 * `https://plc.directory`. Throws `PlcError` when the directory refuses it.
 */
export async function submitPlcOperation(directory: String, did: String, operation: PlcOperation)
    : Future<void> {
  let response = await fetch(`${directory}/${did}`, {
    method: 'POST',
    headers: [('content-type', 'application/json')],
    body: stringify(operation.toJson()),
  });
  if (!response.ok) {
    throw new PlcError(`${directory} refused the operation for ${did}: HTTP ${response.status} ${await response.text()}`);
  }
}

/**
 * The operations the PLC directory at `directory` has recorded for `did`,
 * oldest first, the genesis operation among them. Throws `PlcError` when
 * the directory has no log for it.
 */
export async function fetchOperations(directory: String, did: String): Future<Array<PlcOperation>> {
  let response = await fetch(`${directory}/${did}/log`);
  if (!response.ok) {
    throw new PlcError(`${directory} has no log for ${did}: HTTP ${response.status}`);
  }
  let list = parseJson(await response.text());
  if (!(list is JsonArray)) {
    throw new PlcError(`${directory} answered ${did}'s log with something other than a list`);
  }
  let log = new GrowableArray<PlcOperation>();
  for (var i = 0; i < list.length; i += 1) {
    log.push(PlcOperation.fromJson(list[i]));
  }
  return log;
}

function stringArray(items: Array<String>): JsonArray {
  let array = new JsonArray();
  for (let item in items) {
    array.push(item);
  }
  return array;
}

function stringList(items: Array<String>): ListValue {
  let values = new FixedArray<Value>(items.length, new NullValue());
  for (var i = 0; i < items.length; i += 1) {
    values[i] = new StringValue(items[i]);
  }
  return new ListValue(values);
}

function membersOf(object: JsonObject, name: String): JsonObject {
  let value = object[name];
  if (!(value is JsonObject)) {
    throw new PlcError(`the operation's ${name} is not an object`);
  }
  return value;
}

function stringsOf(object: JsonObject, name: String): GrowableArray<String> {
  let value = object[name];
  if (!(value is JsonArray)) {
    throw new PlcError(`the operation's ${name} is not a list`);
  }
  let list = value;
  let strings = new GrowableArray<String>();
  for (var i = 0; i < list.length; i += 1) {
    strings.push(stringOf(list[i], name));
  }
  return strings;
}

function stringOf(value: JsonValue, what: String): String {
  if (!(value is String)) {
    throw new PlcError(`${what} is not a string`);
  }
  return value;
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none