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.8 KiB Raw
/**
 * The syntax of atproto identifiers and string formats
 * (https://atproto.com/specs/did, /handle, /nsid, /record-key, /tid,
 * /lexicon#string-formats).
 *
 * Each `isValid*` function checks syntax only. A valid DID may not
 * resolve, and a valid handle may not be registered to anyone.
 */

import {StringBuilder} from 'zena:core';

function isLower(b: i32) {
  return b >= 97 && b <= 122;
}

function isUpper(b: i32) {
  return b >= 65 && b <= 90;
}

function isLetter(b: i32) {
  return isLower(b) || isUpper(b);
}

function isDigit(b: i32) {
  return b >= 48 && b <= 57;
}

function isAlphanumeric(b: i32) {
  return isLetter(b) || isDigit(b);
}

/**
 * A DID: `did:`, a method of lowercase letters, `:`, and an identifier of
 * letters, digits and `._:%-` that does not end in `:` or `%`. At most 2048
 * characters.
 */
export function isValidDid(text: String): boolean {
  if (text.length > 2048 || !text.startsWith('did:')) {
    return false;
  }
  var i = 4;
  while (i < text.length && isLower(text.getByteAt(i))) {
    i += 1;
  }
  if (i == 4 || i >= text.length || text.getByteAt(i) != 58) {
    return false;
  }
  i += 1;
  if (i >= text.length) {
    return false;
  }
  for (var j = i; j < text.length; j += 1) {
    let b = text.getByteAt(j);
    // . _ : % -
    if (!isAlphanumeric(b) && b != 46 && b != 95 && b != 58 && b != 37 && b != 45) {
      return false;
    }
  }
  let last = text.getByteAt(text.length - 1);
  return last != 58 && last != 37;
}

/**
 * Whether `text[start..end]` is a DNS label of letters, digits and hyphens,
 * 1 to 63 characters, not starting or ending with a hyphen.
 */
function isLabel(text: String, start: i32, end: i32): boolean {
  let length = end - start;
  if (length < 1 || length > 63) {
    return false;
  }
  if (text.getByteAt(start) == 45 || text.getByteAt(end - 1) == 45) {
    return false;
  }
  for (var i = start; i < end; i += 1) {
    let b = text.getByteAt(i);
    if (!isAlphanumeric(b) && b != 45) {
      return false;
    }
  }
  return true;
}

/**
 * A handle: a domain name of at least two labels, at most 253 characters,
 * whose last label starts with a letter. Handles are case-insensitive;
 * `normalizeHandle` gives the lowercase form.
 */
export function isValidHandle(text: String): boolean {
  if (text.length > 253) {
    return false;
  }
  var labels = 0;
  var start = 0;
  for (var i = 0; i <= text.length; i += 1) {
    if (i == text.length || text.getByteAt(i) == 46) {
      if (!isLabel(text, start, i)) {
        return false;
      }
      labels += 1;
      if (i == text.length && !isLetter(text.getByteAt(start))) {
        return false;
      }
      start = i + 1;
    }
  }
  return labels >= 2;
}

/** The lowercase form of a handle. */
export function normalizeHandle(handle: String): String {
  let sb = new StringBuilder(handle.length);
  for (var i = 0; i < handle.length; i += 1) {
    let b = handle.getByteAt(i);
    sb.appendByte(if (isUpper(b)) b + 32 else b);
  }
  return sb.toString();
}

/**
 * A DID or a handle, as an `at://` URI's authority or an XRPC parameter
 * names an account.
 */
export function isValidAtIdentifier(text: String): boolean {
  if (text.startsWith('did:')) {
    return isValidDid(text);
  }
  return isValidHandle(text);
}

/**
 * An NSID: a reversed domain name and a name, at least three segments in
 * all, at most 317 characters. The first segment starts with a letter, and
 * the name has only letters and digits and starts with a letter.
 */
export function isValidNsid(text: String): boolean {
  if (text.length > 253 + 1 + 63) {
    return false;
  }
  var segments = 0;
  var start = 0;
  for (var i = 0; i <= text.length; i += 1) {
    if (i == text.length || text.getByteAt(i) == 46) {
      if (!isLabel(text, start, i)) {
        return false;
      }
      if (segments == 0 && !isLetter(text.getByteAt(start))) {
        return false;
      }
      if (i == text.length) {
        // The name.
        if (!isLetter(text.getByteAt(start))) {
          return false;
        }
        for (var j = start; j < i; j += 1) {
          if (!isAlphanumeric(text.getByteAt(j))) {
            return false;
          }
        }
      }
      segments += 1;
      start = i + 1;
    }
  }
  return segments >= 3;
}

/**
 * A record key: 1 to 512 characters of letters, digits and `_~.:-`, other
 * than `.` and `..`.
 */
export function isValidRecordKey(text: String): boolean {
  if (text.length < 1 || text.length > 512 || text == '.' || text == '..') {
    return false;
  }
  for (var i = 0; i < text.length; i += 1) {
    let b = text.getByteAt(i);
    // _ ~ . : -
    if (!isAlphanumeric(b) && b != 95 && b != 126 && b != 46 && b != 58 && b != 45) {
      return false;
    }
  }
  return true;
}

/** Whether `b` is a digit of the sortable base32 alphabet `234567a-z`. */
function isTidDigit(b: i32) {
  return (b >= 50 && b <= 55) || isLower(b);
}

/**
 * A TID: 13 characters of sortable base32 (`234567abcdefghijklmnopqrstuvwxyz`),
 * the first of them `2`-`7` or `a`-`j`, since the top bit is always zero.
 */
export function isValidTid(text: String): boolean {
  if (text.length != 13) {
    return false;
  }
  let first = text.getByteAt(0);
  if (!((first >= 50 && first <= 55) || (first >= 97 && first <= 106))) {
    return false;
  }
  for (var i = 1; i < 13; i += 1) {
    if (!isTidDigit(text.getByteAt(i))) {
      return false;
    }
  }
  return true;
}

/**
 * A CID as the lexicon `cid` string format checks it: 8 to 256 characters
 * of letters, digits, `+` and `=`, not starting with `Qmb`, which marks a
 * version 0 CID. This is a loose check; `Cid.parse` reads the CID itself.
 */
export function isValidCidSyntax(text: String): boolean {
  if (text.length < 8 || text.length > 256 || text.startsWith('Qmb')) {
    return false;
  }
  for (var i = 0; i < text.length; i += 1) {
    let b = text.getByteAt(i);
    if (!isAlphanumeric(b) && b != 43 && b != 61) {
      return false;
    }
  }
  return true;
}

/** The value of `count` digits at `text[start]`, or -1 if any is not a digit. */
function digits(text: String, start: i32, count: i32): i32 {
  var value = 0;
  for (var i = start; i < start + count; i += 1) {
    let b = text.getByteAt(i);
    if (!isDigit(b)) {
      return -1;
    }
    value = value * 10 + (b - 48);
  }
  return value;
}

function isLeapYear(year: i32) {
  return (year % 4 == 0 && year % 100 != 0) || year % 400 == 0;
}

function daysInMonth(year: i32, month: i32): i32 {
  if (month == 2) {
    return if (isLeapYear(year)) 29 else 28;
  }
  if (month == 4 || month == 6 || month == 9 || month == 11) {
    return 30;
  }
  return 31;
}

/**
 * A datetime as the lexicon `datetime` format requires: RFC 3339 with
 * uppercase `T`, seconds, an optional fraction, and `Z` or a `±hh:mm`
 * offset other than `-00:00`. At most 64 characters. The date must exist,
 * and the time in UTC must fall within years 0000 to 9999.
 */
export function isValidDatetime(text: String): boolean {
  if (text.length > 64 || text.length < 20) {
    return false;
  }
  // YYYY-MM-DDTHH:MM:SS
  let year = digits(text, 0, 4);
  let month = digits(text, 5, 2);
  let day = digits(text, 8, 2);
  let hour = digits(text, 11, 2);
  let minute = digits(text, 14, 2);
  let second = digits(text, 17, 2);
  if (text.getByteAt(4) != 45 || text.getByteAt(7) != 45 || text.getByteAt(10) != 84
      || text.getByteAt(13) != 58 || text.getByteAt(16) != 58) {
    return false;
  }
  if (year < 0 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)
      || hour < 0 || hour > 23 || minute < 0 || minute > 59 || second < 0 || second > 59) {
    return false;
  }
  var i = 19;
  if (text.getByteAt(i) == 46) {
    i += 1;
    let fractionStart = i;
    while (i < text.length && isDigit(text.getByteAt(i))) {
      i += 1;
    }
    if (i == fractionStart) {
      return false;
    }
  }
  if (i >= text.length) {
    return false;
  }
  var offsetMinutes = 0;
  let sign = text.getByteAt(i);
  if (sign == 90) {
    i += 1;
  } else if (sign == 43 || sign == 45) {
    if (text.length - i != 6 || text.getByteAt(i + 3) != 58) {
      return false;
    }
    let offsetHour = digits(text, i + 1, 2);
    let offsetMinute = digits(text, i + 4, 2);
    if (offsetHour < 0 || offsetHour > 23 || offsetMinute < 0 || offsetMinute > 59) {
      return false;
    }
    if (sign == 45 && offsetHour == 0 && offsetMinute == 0) {
      return false;
    }
    offsetMinutes = offsetHour * 60 + offsetMinute;
    if (sign == 45) {
      offsetMinutes = 0 - offsetMinutes;
    }
    i += 6;
  } else {
    return false;
  }
  if (i != text.length) {
    return false;
  }
  // Converting to UTC can only leave the year range from its first or last day.
  let minuteOfDay = hour * 60 + minute - offsetMinutes;
  let beforeYear0 = year == 0 && month == 1 && day == 1 && minuteOfDay < 0;
  let afterYear9999 = year == 9999 && month == 12 && day == 31 && minuteOfDay >= 24 * 60;
  return !beforeYear0 && !afterYear9999;
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none