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.

9.2 KiB Raw
/**
 * DPoP (RFC 9449), which atproto's OAuth profile requires of every client:
 * proof that whoever presents an access token holds the private key the
 * token is bound to. With each request to the authorization server or the
 * PDS, the client sends a short JWT signed with that key, its proof, in a
 * `DPoP` header:
 *
 * ```json
 * {"typ": "dpop+jwt", "alg": "ES256", "jwk": {"kty": "EC", "crv": "P-256", "x": "…", "y": "…"}}
 * {"jti": "…", "htm": "POST", "htu": "https://pds.example/xrpc/…", "iat": 1792800000,
 *  "nonce": "…", "ath": "…"}
 * ```
 *
 * `htm` and `htu` are the request's method and URL, without its query.
 * `nonce` is the one the server last sent in a `DPoP-Nonce` header, and
 * `ath` the SHA-256 of the access token, on requests that carry one. A
 * token is bound to the key whose thumbprint (RFC 7638) its `cnf.jkt`
 * names.
 *
 * atproto requires ES256, the P-256 curve. This library has no imports
 * from the host: whoever makes a key or a proof supplies the randomness
 * and the time.
 */

import {EcdsaError, p256, sha256} from 'zena:crypto';
import {base64Url} from 'zena:encoding';
import {JsonObject, JsonValue, parseJson, stringify} from 'zena:json';

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

/** How far a proof's `iat` may be from the checker's clock, in seconds. */
export let DPOP_CLOCK_SKEW = 300 as i64;

/** `bytes` as base64url, without padding. */
function encoded(bytes: FixedArray<u8>) {
  return base64Url.encode(bytes, false);
}

/** The JWK of a P-256 public key in SEC1 form, compressed or not. */
function publicJwk(publicKey: FixedArray<u8>) {
  let full = if (publicKey.length == 65) publicKey else p256.decompressPublicKey(publicKey);
  let jwk = new JsonObject();
  jwk['kty'] = 'EC';
  jwk['crv'] = 'P-256';
  jwk['x'] = encoded(full.slice(1, 33));
  jwk['y'] = encoded(full.slice(33, 65));
  return jwk;
}

/**
 * The thumbprint of a P-256 JWK (RFC 7638): base64url of the SHA-256 of
 * its required members, in order, with no spaces.
 */
export function jwkThumbprint(jwk: JsonObject): String {
  let canonical = new JsonObject();
  canonical['crv'] = jwk['crv'];
  canonical['kty'] = jwk['kty'];
  canonical['x'] = jwk['x'];
  canonical['y'] = jwk['y'];
  return encoded(sha256(stringify(canonical).toBytes()));
}

/** The `ath` of a proof: base64url of the SHA-256 of the access token. */
export function accessTokenHash(accessToken: String): String {
  return encoded(sha256(accessToken.toBytes()));
}

/** A URL without its query and fragment, as `htu` names it. */
export function proofTarget(url: String): String {
  var end = url.length;
  for (var i = 0; i < url.length; i += 1) {
    let b = url.getByteAt(i);
    if (b == 63 || b == 35) { // '?' or '#'
      end = i;
      break;
    }
  }
  return url.sliceBytes(0, end);
}

/** A session's DPoP key: a P-256 private key, which proves possession of its tokens. */
export final class DpopKey {
  #privateKey: FixedArray<u8>;
  /** The public key, in uncompressed SEC1 form. */
  publicKey: FixedArray<u8>;

  /** The key for the 32-byte scalar `privateKey`. Throws `EcdsaError` for one out of range. */
  new(privateKey: FixedArray<u8>)
      : #privateKey = privateKey,
        publicKey = p256.publicKey(privateKey, false);

  /**
   * A key from `random`, which gives 32 random bytes each time it is
   * called. Bytes that are not a scalar of the curve, about one draw in
   * 2^32, are drawn again, up to eight times.
   */
  static generate(random: () => FixedArray<u8>): DpopKey {
    for (var attempt = 0; attempt < 8; attempt += 1) {
      try {
        return new DpopKey(random());
      } catch (e) {
        if (!(e is EcdsaError)) {
          throw e;
        }
      }
    }
    throw new DpopError('the random bytes were never a P-256 key');
  }

  /** The public key as a JWK. */
  jwk(): JsonObject {
    return publicJwk(this.publicKey);
  }

  /** The thumbprint a token bound to this key names in `cnf.jkt`. */
  thumbprint(): String {
    return jwkThumbprint(this.jwk());
  }

  /**
   * A proof for a request of `method` to `url`, made at `iat`, in seconds
   * since the epoch, with the unique `jti`. It carries the server's latest
   * `nonce` and, for a request with an access token, its hash.
   */
  proof(method: String, url: String, iat: i64, jti: String, nonce: String | null = null,
      accessToken: String | null = null): String {
    let header = new JsonObject();
    header['typ'] = 'dpop+jwt';
    header['alg'] = 'ES256';
    header['jwk'] = this.jwk();
    let payload = new JsonObject();
    payload['jti'] = jti;
    payload['htm'] = method;
    payload['htu'] = proofTarget(url);
    payload['iat'] = new Box<f64>(iat as f64);
    if (nonce != null) {
      payload['nonce'] = nonce;
    }
    if (accessToken != null) {
      payload['ath'] = accessTokenHash(accessToken);
    }
    let signingInput = `${encoded(stringify(header).toBytes())}.${encoded(stringify(payload).toBytes())}`;
    let signature = p256.sign(this.#privateKey, signingInput.toBytes());
    return `${signingInput}.${encoded(signature)}`;
  }

  /** The key as a private JWK, for keeping with a session. It is a secret. */
  toJson(): JsonObject {
    let jwk = this.jwk();
    jwk['d'] = encoded(this.#privateKey);
    return jwk;
  }

  /** Reads a key `toJson` wrote. Throws `DpopError`. */
  static fromJson(json: JsonValue): DpopKey {
    if (json is JsonObject) {
      let d = json['d'];
      if (d is String && json['crv'] == 'P-256') {
        try {
          return new DpopKey(base64Url.decode(d));
        } catch (e) {
          throw new DpopError('a stored DPoP key is not a P-256 key');
        }
      }
    }
    throw new DpopError('a stored DPoP key is not a P-256 private JWK');
  }
}

/** What a valid proof says. */
export final class DpopProof {
  /** The thumbprint of the key that signed it. */
  thumbprint: String;
  jti: String;
  iat: i64;
  /** The nonce it carries, or null. */
  nonce: String | null;
  /** The access token hash it carries, or null. */
  ath: String | null;

  new(this.thumbprint, this.jti, this.iat, this.nonce, this.ath);
}

/**
 * Checks the proof `proof` for a request of `method` to `url` at `now`, in
 * seconds since the epoch: its form, its signature by the key it carries,
 * its method, its URL and its time. The caller checks the nonce, the
 * token's binding and that the `jti` is new. Throws `DpopError`.
 */
export function verifyDpopProof(proof: String, method: String, url: String, now: i64): DpopProof {
  let parts = proof.split('.');
  if (parts.length != 3) {
    throw new DpopError('a DPoP proof is three base64url parts');
  }
  let header = decodePart(parts[0], 'header');
  let payload = decodePart(parts[1], 'payload');
  if (header['typ'] != 'dpop+jwt' || header['alg'] != 'ES256') {
    throw new DpopError('a DPoP proof is a dpop+jwt signed with ES256');
  }
  let jwk = header['jwk'];
  if (!(jwk is JsonObject) || jwk['kty'] != 'EC' || jwk['crv'] != 'P-256' || jwk.has('d')) {
    throw new DpopError('a DPoP proof carries a public P-256 JWK');
  }
  let x = jwk['x'];
  let y = jwk['y'];
  if (!(x is String) || !(y is String)) {
    throw new DpopError('a DPoP proof carries a public P-256 JWK');
  }
  var signature = new FixedArray<u8>(0, 0 as u8);
  var publicKey = signature;
  try {
    signature = base64Url.decode(parts[2]);
    publicKey = uncompressed(base64Url.decode(x), base64Url.decode(y));
  } catch (e) {
    throw new DpopError('a DPoP proof is not base64url');
  }
  if (!p256.verify(publicKey, `${parts[0]}.${parts[1]}`.toBytes(), signature, true)) {
    throw new DpopError('a DPoP proof is not signed by the key it carries');
  }
  if (payload['htm'] != method) {
    throw new DpopError(`a DPoP proof is for ${stringify(payload['htm'])}, not ${method}`);
  }
  if (payload['htu'] != proofTarget(url)) {
    throw new DpopError(`a DPoP proof is for ${stringify(payload['htu'])}, not ${proofTarget(url)}`);
  }
  let jti = payload['jti'];
  if (!(jti is String) || jti == '') {
    throw new DpopError('a DPoP proof has no jti');
  }
  let iatValue = payload['iat'];
  if (!(iatValue is Box<f64>)) {
    throw new DpopError('a DPoP proof has no iat');
  }
  let iat = iatValue.value as i64;
  if (iat > now + DPOP_CLOCK_SKEW || iat < now - DPOP_CLOCK_SKEW) {
    throw new DpopError('a DPoP proof is too old or too new');
  }
  let nonce = payload['nonce'];
  let ath = payload['ath'];
  return new DpopProof(jwkThumbprint(jwk), jti, iat, if (nonce is String) nonce else null,
      if (ath is String) ath else null);
}

/** The uncompressed SEC1 key with the coordinates `x` and `y`. */
function uncompressed(x: FixedArray<u8>, y: FixedArray<u8>): FixedArray<u8> {
  if (x.length != 32 || y.length != 32) {
    throw new DpopError('a P-256 coordinate is 32 bytes');
  }
  let key = new FixedArray<u8>(65, 4 as u8);
  for (var i = 0; i < 32; i += 1) {
    key[1 + i] = x[i];
    key[33 + i] = y[i];
  }
  return key;
}

function decodePart(part: String, what: String): JsonObject {
  var json: JsonValue = null;
  try {
    json = parseJson(String.fromBytes(base64Url.decode(part)));
  } catch (e) {
    throw new DpopError(`a DPoP proof's ${what} is not base64url JSON`);
  }
  if (!(json is JsonObject)) {
    throw new DpopError(`a DPoP proof's ${what} is not a JSON object`);
  }
  return json;
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none