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.

4.7 KiB Raw
/**
 * Public keys as atproto writes them (https://atproto.com/specs/cryptography).
 *
 * atproto uses two curves: NIST P-256 and secp256k1. A public key is the
 * 33-byte compressed point, and it is written three ways:
 *
 * - As a multikey: base58btc multibase (`z...`) of a multicodec prefix
 *   (`0x1200` for P-256, `0xe7` for secp256k1, both as varints) followed by
 *   the point. DID documents use this with type `Multikey`.
 * - As a `did:key`: `did:key:` followed by the multikey.
 * - In older DID documents, with type `EcdsaSecp256r1VerificationKey2019`
 *   or `EcdsaSecp256k1VerificationKey2019`: base58btc multibase of the
 *   point alone.
 *
 * `verifySignature` checks a signature the way atproto checks commits and
 * JWTs: ECDSA over the SHA-256 hash of the data, with a 64-byte low-S
 * signature.
 */

import {ByteBuffer} from 'zena:core';
import {EcdsaCurve, p256, secp256k1} from 'zena:crypto';
import {decodeMultibase, encodeBase58btc} from './multibase.zena';
import {readVarint, writeVarint} from './varint.zena';

/** A key that cannot be read. */
export class KeyError extends Error {
  new(message: String) : super(message);
}

/** The curves atproto keys use. */
export enum KeyType {
  P256,
  Secp256k1
}

let CODEC_P256: i64 = 0x1200;
let CODEC_SECP256K1: i64 = 0xe7;

/** A public key: its curve and its compressed point. */
export final class PublicKey {
  type: KeyType;
  /** The 33-byte compressed point. */
  bytes: FixedArray<u8>;

  new(type: KeyType, bytes: FixedArray<u8>) : type = type, bytes = bytes;

  /** The JWT algorithm name of signatures with this key: ES256 or ES256K. */
  jwtAlgorithm(): String {
    return if (this.type == KeyType.P256) 'ES256' else 'ES256K';
  }
}

function codecOf(type: KeyType) {
  return if (type == KeyType.P256) CODEC_P256 else CODEC_SECP256K1;
}

function checkPoint(bytes: FixedArray<u8>) {
  if (bytes.length != 33 || (bytes[0] != 2 && bytes[0] != 3)) {
    throw new KeyError(`not a compressed point: ${bytes.length} bytes`);
  }
}

function decodeBase58Multibase(text: String): FixedArray<u8> {
  if (text.length == 0 || text.getByteAt(0) != 122) {
    throw new KeyError('key is not base58btc multibase');
  }
  try {
    return decodeMultibase(text);
  } catch (e) {
    throw new KeyError(`key is not base58btc: ${e.message}`);
  }
}

/** Reads a multikey (`z...` with a multicodec prefix). */
export function parseMultikey(text: String): PublicKey {
  let bytes = decodeBase58Multibase(text);
  let (codec, start) = readVarint(bytes, 0, bytes.length);
  let point = bytes.slice(start, bytes.length);
  checkPoint(point);
  if (codec == CODEC_P256) {
    return new PublicKey(KeyType.P256, point);
  }
  if (codec == CODEC_SECP256K1) {
    return new PublicKey(KeyType.Secp256k1, point);
  }
  throw new KeyError(`unsupported key type: multicodec ${codec}`);
}

/** Reads a `did:key`. */
export function parseDidKey(did: String): PublicKey {
  if (!did.startsWith('did:key:')) {
    throw new KeyError(`not a did:key: ${did}`);
  }
  return parseMultikey(did.sliceBytes(8, did.length));
}

/**
 * Reads a key from a verification method of a DID document, by its `type`:
 * `Multikey`, or one of the two older types that name the curve.
 */
export function parseVerificationMethod(type: String, publicKeyMultibase: String): PublicKey {
  if (type == 'Multikey') {
    return parseMultikey(publicKeyMultibase);
  }
  let keyType = if (type == 'EcdsaSecp256r1VerificationKey2019') {
    KeyType.P256
  } else if (type == 'EcdsaSecp256k1VerificationKey2019') {
    KeyType.Secp256k1
  } else {
    throw new KeyError(`unsupported verification method type ${type}`)
  };
  let point = decodeBase58Multibase(publicKeyMultibase);
  checkPoint(point);
  return new PublicKey(keyType, point);
}

/** `key` as a multikey. */
export function formatMultikey(key: PublicKey): String {
  let out = new ByteBuffer(40);
  writeVarint(out, codecOf(key.type));
  out.writeBytes(key.bytes as ByteArray);
  return `z${encodeBase58btc(out.toByteArray() as FixedArray<u8>)}`;
}

/** `key` as a `did:key`. */
export function formatDidKey(key: PublicKey): String {
  return `did:key:${formatMultikey(key)}`;
}

/** The ECDSA curve keys of `type` are on. */
export function curveOf(type: KeyType): EcdsaCurve {
  return if (type == KeyType.P256) p256 else secp256k1;
}

/** The public key for a 32-byte private key on the curve of `type`. */
export function publicKeyFor(type: KeyType, privateKey: FixedArray<u8>): PublicKey {
  return new PublicKey(type, curveOf(type).publicKey(privateKey));
}

/**
 * Whether `signature` is `key`'s signature of `data`: ECDSA over the
 * SHA-256 hash of `data`, 64 bytes of r then s, with s in the low half.
 */
export function verifySignature(key: PublicKey, data: FixedArray<u8>, signature: FixedArray<u8>): boolean {
  return curveOf(key.type).verify(key.bytes, data, signature);
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none