atproto 0.0.1-preview.1
AT Protocol data model, repositories, identity, XRPC, OAuth and sessions
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 inzena:encoding.atproto/cid: CIDs, their binary and string forms, and the CIDs atproto gives records and blobs.atproto/data: the data model (Valueand its cases), its JSON form, and blob references (BlobRef).atproto/cbor: DAG-CBOR encoding and strict decoding,cidForValue, andsortedKeys, the order DAG-CBOR writes map keys in.atproto/syntax: DIDs, handles, NSIDs, record keys, TIDs, datetimes, and CID strings.atproto/car: CAR files andBlockMap, 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 verifyingcom.atproto.sync.getRecordproofs.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 aRequestSignercan authorize one by one.atproto/methods: the NSIDs of standardcom.atprotomethods, andxrpcPath, a method's path on a server.atproto/plc:did:plcoperations: 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.
5.0 KiB
Raw
/**
* Fetching records and blobs from an account's PDS and checking them, so
* that what is returned is what the account published, whoever served it.
*
* A record comes from `com.atproto.sync.getRecord` with a proof: the
* commit, signed with the key in the account's DID document, and the tree
* nodes from the commit to the record. A blob comes from
* `com.atproto.sync.getBlob` and is checked against its CID.
*
* `listRecords` is the exception: `com.atproto.repo.listRecords` answers
* with no proof, so it is for finding records, and anything relied on is
* fetched again with `getVerifiedRecord`.
*/
import {readCar} from './car.zena';
import {Cid, HASH_SHA256} from './cid.zena';
import {DidDocument} from './did.zena';
import {PublicKey, verifySignature} from './didkey.zena';
import {RecordProof, verifyRecordProof} from './repo.zena';
import {Value, fromJson} from './data.zena';
import {XrpcClient} from './xrpc.zena';
import {JsonArray, JsonObject, JsonValue} from 'zena:json';
import {REPO_LIST_RECORDS, SYNC_GET_BLOB, SYNC_GET_RECORD} from './methods.zena';
/** A record or blob that could not be fetched or did not check out. */
export class SyncError extends Error {
new(message: String) : super(message);
}
function clientFor(document: DidDocument) {
let pds = document.pds;
if (pds == null) {
throw new SyncError(`${document.id} names no PDS`);
}
return new XrpcClient(pds);
}
/**
* Fetches `collection/rkey` from the repository of the account `document`
* describes, and checks its proof against the document's signing key. The
* result's `record` is null when the proof shows there is no such record.
*/
export async function getVerifiedRecord(document: DidDocument, collection: String, rkey: String): Future<RecordProof> {
if (document.signingKey == null) {
throw new SyncError(`${document.id} has no signing key`);
}
let key = document.signingKey as PublicKey;
let response = await clientFor(document).queryRaw(SYNC_GET_RECORD, [
('did', document.id),
('collection', collection),
('rkey', rkey),
]);
let car = readCar(await response.bytes());
return verifyRecordProof(car, document.id, collection, rkey, (signed, sig) => verifySignature(key, signed, sig));
}
/** Fetches a blob of the account `document` describes, and checks it against `cid`. */
export async function getVerifiedBlob(document: DidDocument, cid: Cid): Future<FixedArray<u8>> {
if (cid.hashType != HASH_SHA256) {
throw new SyncError(`cannot check blob ${cid.toString()}: not a SHA-256 CID`);
}
let response = await clientFor(document).queryRaw(SYNC_GET_BLOB, [
('did', document.id),
('cid', cid.toString()),
]);
let body = await response.bytes();
let actual = Cid.create(cid.codec, body);
if (!actual.digest.contentEquals(cid.digest)) {
throw new SyncError(`blob ${cid.toString()} does not match its CID`);
}
return body;
}
/** A record as `com.atproto.repo.listRecords` lists it. */
export final class ListedRecord {
/** The record key. */
rkey: String;
cid: Cid;
value: Value;
new(rkey: String, cid: Cid, value: Value) : rkey = rkey, cid = cid, value = value;
}
/**
* The records of `collection` in the repository of the account `document`
* describes, as its PDS lists them, every page of them. Nothing here is
* checked against the account's key: fetch a record with
* `getVerifiedRecord` before relying on it.
*/
export async function listRecords(document: DidDocument, collection: String): Future<GrowableArray<ListedRecord>> {
let client = clientFor(document);
let records = new GrowableArray<ListedRecord>();
var cursor: String | null = null;
while (true) {
let params = new GrowableArray<(String, String)>();
params.push(('repo', document.id));
params.push(('collection', collection));
params.push(('limit', '100'));
let after = cursor;
if (after != null) {
params.push(('cursor', after));
}
let answer = await client.query(REPO_LIST_RECORDS, params);
if (!(answer is JsonObject)) {
throw new SyncError('listRecords answered with something other than an object');
}
let page = answer;
let listed = page['records'];
if (!(listed is JsonArray)) {
throw new SyncError('listRecords answered with no records');
}
let items = listed;
for (var i = 0; i < items.length; i += 1) {
records.push(listedRecord(items[i]));
}
let next = page['cursor'];
if (!(next is String) || items.length == 0) {
return records;
}
cursor = next;
}
return records;
}
function listedRecord(item: JsonValue): ListedRecord {
if (!(item is JsonObject)) {
throw new SyncError('listRecords listed something other than a record');
}
let record = item;
let uri = record['uri'];
let cid = record['cid'];
if (!(uri is String) || !(cid is String)) {
throw new SyncError('listRecords listed a record with no URI or CID');
}
let text = uri;
var slash = -1;
for (var i = 0; i < text.length; i += 1) {
if (text.getByteAt(i) == 47) {
slash = i;
}
}
return new ListedRecord(text.sliceBytes(slash + 1, text.length), Cid.parse(cid),
fromJson(record['value']));
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|