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.

11.4 KiB Raw
/**
 * Service auth (https://atproto.com/specs/xrpc#inter-service-authentication-jwt):
 * the short-lived JWT an account presents to a service other than its own
 * PDS. The account's PDS signs it with the account's signing key, when the
 * account asks with `com.atproto.server.getServiceAuth` or when the PDS
 * forwards a call that names another service in `atproto-proxy`. The
 * service checks it against the issuer's DID document.
 *
 * A token is `<header>.<payload>.<signature>`, each part base64url without
 * padding:
 *
 * ```json
 * {"typ": "JWT", "alg": "ES256K"}
 * {
 *   "iss": "did:plc:alicealicealicealicealic",
 *   "aud": "did:web:pkg.zena-lang.dev",
 *   "exp": 1792800060,
 *   "iat": 1792800000,
 *   "lxm": "dev.zena-lang.registry.publish",
 *   "jti": "9f2c4e7a1b3d5f60"
 * }
 * ```
 *
 * `alg` is `ES256K` for a secp256k1 key and `ES256` for a P-256 key, and the
 * signature is the 64-byte low-S ECDSA signature of the first two parts.
 * `lxm` names the one method the token is for, and `jti` is a nonce, so that
 * a service can refuse a token presented twice (`ReplayGuard`).
 *
 * This library has no imports from the host: whoever creates a token
 * supplies its nonce, and whoever checks one supplies the time and a way
 * to find the issuer's key.
 */

import {HashMap} from 'zena:collections';
import {base64Url} from 'zena:encoding';
import {JsonObject, JsonValue, parseJson, stringify} from 'zena:json';
import {KeyType, PublicKey, curveOf, verifySignature} from './didkey.zena';
import {isValidDid, isValidNsid} from './syntax.zena';

/** A token that is malformed, or that does not pass a check. */
export class ServiceAuthError extends Error {
  new(message: String) : super(message);
}

/** What a token says. Times are seconds since the Unix epoch. */
export final class ServiceAuthClaims {
  /** The account the token is from. */
  iss: String;
  /** The service it is for: a DID, with a service fragment or without. */
  aud: String;
  /** When it expires. */
  exp: i64;
  /** When it was issued, if it says. */
  iat: i64;
  /** The one XRPC method it is for, or null for any. */
  lxm: String | null;
  /** Its nonce, or null. */
  jti: String | null;

  new(iss: String, aud: String, exp: i64, iat: i64 = 0 as i64, lxm: String | null = null,
      jti: String | null = null)
      : iss = iss, aud = aud, exp = exp, iat = iat, lxm = lxm, jti = jti;
}

/**
 * The longest a token may have left to live when it is checked, in
 * seconds. `com.atproto.server.getServiceAuth` grants up to an hour for a
 * token bound to a method.
 */
export let MAX_LIFETIME = 3600 as i64;

/** How far ahead of the checker's clock a token's `iat` may be, in seconds. */
export let CLOCK_SKEW = 300 as i64;

/** A token for `claims`, signed with `privateKey`, a key of type `type`. */
export function createServiceAuthToken(claims: ServiceAuthClaims, type: KeyType,
    privateKey: FixedArray<u8>): String {
  let signingInput = signingInputOf(claims, type);
  return withSignature(signingInput, curveOf(type).sign(privateKey, signingInput.toBytes()));
}

/**
 * A token for `claims`, signed by `sign` with a key of type `type`, for a
 * key that is not held here, such as one in a key management service.
 * `sign` gives the 64-byte low-S signature of the SHA-256 hash of the
 * bytes it is given.
 */
export async function signServiceAuthToken(claims: ServiceAuthClaims, type: KeyType,
    sign: (bytes: FixedArray<u8>) => Future<FixedArray<u8>>): Future<String> {
  let signingInput = signingInputOf(claims, type);
  return withSignature(signingInput, await sign(signingInput.toBytes()));
}

/** What a token's signature covers: its header and payload, each base64url-encoded. */
function signingInputOf(claims: ServiceAuthClaims, type: KeyType): String {
  let header = new JsonObject();
  header['typ'] = 'JWT';
  header['alg'] = if (type == KeyType.P256) 'ES256' else 'ES256K';
  let payload = new JsonObject();
  payload['iss'] = claims.iss;
  payload['aud'] = claims.aud;
  payload['exp'] = new Box<f64>(claims.exp as f64);
  if (claims.iat != 0) {
    payload['iat'] = new Box<f64>(claims.iat as f64);
  }
  let lxm = claims.lxm;
  if (lxm != null) {
    payload['lxm'] = lxm;
  }
  let jti = claims.jti;
  if (jti != null) {
    payload['jti'] = jti;
  }
  return `${encodePart(stringify(header))}.${encodePart(stringify(payload))}`;
}

function withSignature(signingInput: String, signature: FixedArray<u8>): String {
  return `${signingInput}.${base64Url.encode(signature, false)}`;
}

/**
 * Finds the signing key in `did`'s DID document, or null when it has none.
 * With `fresh`, it must not answer from a cache: the checker asks again
 * that way when a signature does not verify, in case the key was rotated.
 */
export type SigningKeyLookup = (did: String, fresh: boolean) => Future<PublicKey | null>;

/**
 * The issuer `token` names, read without checking anything else about it.
 * A service that takes tokens only from issuers it knows refuses the others
 * with this before `verifyServiceAuth` looks up their keys, which an issuer
 * serves from wherever its DID says. Throws `ServiceAuthError` for a token
 * whose payload cannot be read.
 */
export function serviceAuthIssuer(token: String): String {
  let parts = token.split('.');
  if (parts.length != 3) {
    throw new ServiceAuthError('not a JWT: it does not have three parts');
  }
  return readClaims(decodeObject(parts[1], 'payload')).iss;
}

/**
 * Checks `token` and returns its claims. Throws `ServiceAuthError` unless:
 *
 * - its header names `ES256` or `ES256K`, and `typ`, if it has one, is `JWT`;
 * - `iss` is a DID with no fragment, and `aud` is `audience` with or
 *   without a service fragment;
 * - it has not expired at `now`, expires within `MAX_LIFETIME`, and was
 *   not issued more than `CLOCK_SKEW` ahead of `now`;
 * - `lxm` is `method`, when `method` is given;
 * - its signature verifies with the issuer's key, of the type `alg` names.
 *
 * It does not refuse a token presented twice; see `ReplayGuard`.
 */
export async function verifyServiceAuth(token: String, audience: String, method: String | null,
    now: i64, lookup: SigningKeyLookup): Future<ServiceAuthClaims> {
  let parts = token.split('.');
  if (parts.length != 3) {
    throw new ServiceAuthError('not a JWT: it does not have three parts');
  }
  let header = decodeObject(parts[0], 'header');
  let alg = header['alg'];
  if (!(alg is String) || (alg != 'ES256' && alg != 'ES256K')) {
    throw new ServiceAuthError('the algorithm is not ES256 or ES256K');
  }
  let typ = header['typ'];
  if (typ != null && typ != 'JWT') {
    throw new ServiceAuthError('the token type is not JWT');
  }

  let claims = readClaims(decodeObject(parts[1], 'payload'));
  if (claims.aud != audience && !claims.aud.startsWith(`${audience}#`)) {
    throw new ServiceAuthError(`the token is for ${claims.aud}, not ${audience}`);
  }
  if (claims.exp <= now) {
    throw new ServiceAuthError('the token has expired');
  }
  if (claims.exp - now > MAX_LIFETIME) {
    throw new ServiceAuthError('the token expires too far in the future');
  }
  if (claims.iat > now + CLOCK_SKEW) {
    throw new ServiceAuthError('the token was issued in the future');
  }
  if (method != null && claims.lxm != method) {
    throw new ServiceAuthError(`the token is not for ${method}`);
  }

  let signingInput = `${parts[0]}.${parts[1]}`.toBytes();
  var signature = new FixedArray<u8>(0, 0 as u8);
  try {
    signature = base64Url.decode(parts[2]);
  } catch (e) {
    throw new ServiceAuthError('the signature is not base64url');
  }
  let keyType = if (alg == 'ES256') KeyType.P256 else KeyType.Secp256k1;
  let key = await lookup(claims.iss, false);
  if (verifiesWith(key, keyType, signingInput, signature)) {
    return claims;
  }
  let freshKey = await lookup(claims.iss, true);
  if (freshKey != null && !sameKey(key, freshKey) &&
      verifiesWith(freshKey, keyType, signingInput, signature)) {
    return claims;
  }
  throw new ServiceAuthError(`the signature does not verify with ${claims.iss}'s signing key`);
}

/**
 * The nonces of tokens a service has accepted, kept until the tokens
 * expire, so that each token is accepted once.
 */
export final class ReplayGuard {
  #expiries = new HashMap<String, i64>();
  var #checks = 0;

  /**
   * Records `claims`' nonce. Throws `ServiceAuthError` when the token has
   * no nonce, or when a token from the same issuer with the same nonce was
   * accepted and has not expired.
   */
  accept(claims: ServiceAuthClaims, now: i64): void {
    let jti = claims.jti;
    if (jti == null) {
      throw new ServiceAuthError('the token has no nonce');
    }
    this.#checks += 1;
    if (this.#checks % 256 == 0) {
      this.#prune(now);
    }
    let key = `${claims.iss} ${jti}`;
    if (let (true, expiry) = this.#expiries.get(key)) {
      if (expiry > now) {
        throw new ServiceAuthError('the token was already used');
      }
    }
    this.#expiries[key] = claims.exp;
  }

  #prune(now: i64): void {
    let expired = new GrowableArray<String>();
    this.#expiries.forEach((key, expiry) => {
      if (expiry <= now) {
        expired.push(key);
      }
    });
    for (let key in expired) {
      this.#expiries.delete(key);
    }
  }
}

function verifiesWith(key: PublicKey | null, type: KeyType, data: FixedArray<u8>,
    signature: FixedArray<u8>): boolean {
  if (key == null) {
    return false;
  }
  let found = key;
  return found.type == type && verifySignature(found, data, signature);
}

function sameKey(a: PublicKey | null, b: PublicKey): boolean {
  if (a == null) {
    return false;
  }
  let first = a;
  if (first.type != b.type || first.bytes.length != b.bytes.length) {
    return false;
  }
  for (var i = 0; i < b.bytes.length; i += 1) {
    if (first.bytes[i] != b.bytes[i]) {
      return false;
    }
  }
  return true;
}

function readClaims(payload: JsonObject): ServiceAuthClaims {
  let iss = payload['iss'];
  if (!(iss is String) || !isValidDid(iss)) {
    throw new ServiceAuthError('iss is not a DID');
  }
  let aud = payload['aud'];
  if (!(aud is String) || !isValidDid(didPart(aud))) {
    throw new ServiceAuthError('aud is not a DID');
  }
  let exp = payload['exp'];
  if (!(exp is Box<f64>)) {
    throw new ServiceAuthError('exp is not a number');
  }
  var iat = 0 as i64;
  let issued = payload['iat'];
  if (issued != null) {
    if (!(issued is Box<f64>)) {
      throw new ServiceAuthError('iat is not a number');
    }
    iat = issued.value as i64;
  }
  var lxm: String | null = null;
  let method = payload['lxm'];
  if (method != null) {
    if (!(method is String) || !isValidNsid(method)) {
      throw new ServiceAuthError('lxm is not an NSID');
    }
    lxm = method;
  }
  var jti: String | null = null;
  let nonce = payload['jti'];
  if (nonce != null) {
    if (!(nonce is String)) {
      throw new ServiceAuthError('jti is not a string');
    }
    jti = nonce;
  }
  return new ServiceAuthClaims(iss, aud, exp.value as i64, iat, lxm, jti);
}

/** `did` without its fragment. */
function didPart(did: String): String {
  for (var i = 0; i < did.length; i += 1) {
    if (did.getByteAt(i) == 35) { // '#'
      return did.sliceBytes(0, i);
    }
  }
  return did;
}

function decodeObject(part: String, what: String): JsonObject {
  var json: JsonValue = null;
  try {
    json = parseJson(String.fromBytes(base64Url.decode(part)));
  } catch (e) {
    throw new ServiceAuthError(`the ${what} is not base64url JSON`);
  }
  if (!(json is JsonObject)) {
    throw new ServiceAuthError(`the ${what} is not a JSON object`);
  }
  return json;
}

function encodePart(json: String): String {
  return base64Url.encode(json.toBytes(), false);
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none