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.
8.6 KiB
Raw
/**
* The atproto data model (https://atproto.com/specs/data-model): the
* values a record, a commit or a repository node can hold, and their JSON
* form.
*
* A value is null, a boolean, a 64-bit integer, a string, bytes, a link to
* other data by CID, a list, or a map with string keys. There are no
* floats. A blob reference is an ordinary map with `$type: "blob"`.
*
* In JSON, bytes are `{"$bytes": "<base64>"}` and links are
* `{"$link": "<cid>"}`. `fromJson` reads JSON strictly, the way the
* reference implementation does: a `$bytes` or `$link` object must have no
* other keys, `$type` must be a non-empty string, a blob reference must
* have exactly the blob keys with a raw CID, and a number must be an
* integer no larger than 2^53 - 1 in magnitude.
*/
import {OrderedHashMap} from 'zena:collections';
import {floor} from 'zena:math';
import {JsonArray, JsonObject, JsonValue} from 'zena:json';
import {CODEC_RAW, Cid} from './cid.zena';
import {base64} from 'zena:encoding';
/** Data outside the atproto data model, or JSON that does not map to it. */
export class DataError extends Error {
new(message: String) : super(message);
}
/** The largest integer JSON carries exactly: 2^53 - 1. */
let MAX_SAFE_INTEGER: i64 = 0x1fffffffffffff;
/** A value in the atproto data model. */
export sealed class Value {
case NullValue
case BoolValue(value: boolean)
case IntValue(value: i64)
case StringValue(value: String)
case BytesValue(value: FixedArray<u8>)
case LinkValue(cid: Cid)
case ListValue(items: FixedArray<Value>)
case MapValue(entries: OrderedHashMap<String, Value>)
}
/** The value at `key` in `map`, or null when the key is absent. */
export function field(map: MapValue, key: String): Value | null {
if (let (true, value) = map.entries.get(key)) {
return value;
}
return null;
}
/** The string at `key`, or null when it is absent or not a string. */
export function stringField(map: MapValue, key: String): String | null {
let value = field(map, key);
if (value is StringValue) {
return value.value;
}
return null;
}
/** The map at `key`, or null when it is absent or not a map. */
export function mapField(map: MapValue, key: String): MapValue | null {
let value = field(map, key);
if (value is MapValue) {
return value;
}
return null;
}
/** The list at `key`, or null when it is absent or not a list. */
export function listField(map: MapValue, key: String): ListValue | null {
let value = field(map, key);
if (value is ListValue) {
return value;
}
return null;
}
/** The link at `key`, or null when it is absent or not a link. */
export function linkField(map: MapValue, key: String): Cid | null {
let value = field(map, key);
if (value is LinkValue) {
return value.cid;
}
return null;
}
/** A map with no entries yet, for building a value. */
export function newMap(): MapValue {
return new MapValue(new OrderedHashMap<String, Value>());
}
/**
* A reference to a blob: its raw CID, MIME type and size. In the data
* model it is a map, `{$type: "blob", ref, mimeType, size}`.
*/
export final class BlobRef {
cid: Cid;
mimeType: String;
size: i64;
new(cid: Cid, mimeType: String, size: i64) : cid = cid, mimeType = mimeType, size = size;
/**
* Reads a blob reference, from JSON or DAG-CBOR alike. Throws
* `DataError` for any other value.
*/
static fromValue(value: Value): BlobRef {
if (!(value is MapValue)) {
throw new DataError('blob reference is not a map');
}
let map = value;
if (stringField(map, '$type') != 'blob') {
throw new DataError("blob reference does not have $type 'blob'");
}
checkBlob(map);
let size = field(map, 'size') as IntValue;
return new BlobRef(linkField(map, 'ref') as Cid, stringField(map, 'mimeType') as String, size.value);
}
toValue(): MapValue {
let map = newMap();
map.entries['$type'] = new StringValue('blob');
map.entries['ref'] = new LinkValue(this.cid);
map.entries['mimeType'] = new StringValue(this.mimeType);
map.entries['size'] = new IntValue(this.size);
return map;
}
}
/**
* Reads atproto JSON. Throws `DataError` for JSON outside the data model;
* see the module comment for the rules.
*/
export function fromJson(json: JsonValue): Value {
if (json == null) {
return new NullValue();
}
if (json is String) {
return new StringValue(json);
}
if (json is Box<boolean>) {
return new BoolValue(json.value);
}
if (json is Box<f64>) {
return new IntValue(integerOf(json.value));
}
if (json is JsonArray) {
let items = new FixedArray<Value>(json.length, new NullValue());
for (var i = 0; i < json.length; i += 1) {
items[i] = fromJson(json[i]);
}
return new ListValue(items);
}
return objectFromJson(json);
}
function integerOf(n: f64): i64 {
if (floor(n) != n) {
throw new DataError(`not an integer: ${n}`);
}
let limit = MAX_SAFE_INTEGER as f64;
if (n > limit || n < 0.0 - limit) {
throw new DataError(`integer too large for JSON: ${n}`);
}
return n as i64;
}
function objectFromJson(json: JsonObject): Value {
if (json.has('$link')) {
return new LinkValue(linkFromJson(json));
}
if (json.has('$bytes')) {
return new BytesValue(bytesFromJson(json));
}
let entries = new OrderedHashMap<String, Value>(json.size);
json.forEach((key, value) => {
entries[key] = fromJson(value);
});
let map = new MapValue(entries);
checkType(map);
return map;
}
function linkFromJson(json: JsonObject): Cid {
if (json.size != 1) {
throw new DataError('a $link object has other keys');
}
let text = json['$link'];
if (!(text is String)) {
throw new DataError('$link is not a string');
}
try {
return Cid.parse(text);
} catch (e) {
throw new DataError(`$link is not a CID: ${e.message}`);
}
}
function bytesFromJson(json: JsonObject): FixedArray<u8> {
if (json.size != 1) {
throw new DataError('a $bytes object has other keys');
}
let text = json['$bytes'];
if (!(text is String)) {
throw new DataError('$bytes is not a string');
}
try {
return base64.decode(text);
} catch (e) {
throw new DataError(`$bytes is not base64: ${e.message}`);
}
}
/** Checks the `$type` of a map, and the shape of a blob reference. */
function checkType(map: MapValue): void {
let type = field(map, '$type');
if (type == null) {
return;
}
if (!(type is StringValue)) {
throw new DataError('$type is not a string');
}
let name = type.value;
if (name.length == 0) {
throw new DataError('$type is empty');
}
if (name == 'blob') {
checkBlob(map);
}
}
function checkBlob(map: MapValue): void {
var keys = 0;
map.entries.forEach((key, value) => {
if (key != '$type' && key != 'ref' && key != 'mimeType' && key != 'size') {
throw new DataError(`blob reference has an unknown key '${key}'`);
}
keys += 1;
});
if (keys != 4) {
throw new DataError('blob reference is missing a key');
}
let ref = linkField(map, 'ref');
if (ref == null || ref.codec != CODEC_RAW) {
throw new DataError('blob reference has no raw CID');
}
let mimeType = stringField(map, 'mimeType');
if (mimeType == null || !mimeType.contains('/')) {
throw new DataError('blob reference has no MIME type');
}
let size = field(map, 'size');
if (!(size is IntValue) || size.value < 0) {
throw new DataError('blob reference size is not a non-negative integer');
}
}
/** The atproto JSON form of `value`. */
export function toJson(value: Value): JsonValue {
return match (value) {
case NullValue: null
case BoolValue {value}: new Box<boolean>(value)
case IntValue {value}: intToJson(value)
case StringValue {value}: value
case BytesValue {value}: bytesToJson(value)
case LinkValue {cid}: linkToJson(cid)
case ListValue {items}: listToJson(items)
case MapValue {entries}: mapToJson(entries)
};
}
function intToJson(n: i64): JsonValue {
if (n > MAX_SAFE_INTEGER || n < 0 - MAX_SAFE_INTEGER) {
throw new DataError(`integer too large for JSON: ${n}`);
}
return new Box<f64>(n as f64);
}
function bytesToJson(bytes: FixedArray<u8>): JsonValue {
let json = new JsonObject();
json['$bytes'] = base64.encode(bytes, false);
return json;
}
function linkToJson(cid: Cid): JsonValue {
let json = new JsonObject();
json['$link'] = cid.toString();
return json;
}
function listToJson(items: FixedArray<Value>): JsonValue {
let json = new JsonArray();
for (let item in items) {
json.push(toJson(item));
}
return json;
}
function mapToJson(entries: OrderedHashMap<String, Value>): JsonValue {
let json = new JsonObject();
entries.forEach((key, item) => {
json[key] = toJson(item);
});
return json;
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|