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.
11.7 KiB
Raw
/**
* DAG-CBOR, the binary encoding of the atproto data model, as the DRISL
* specification restricts it (https://dasl.ing/drisl.html).
*
* The encoding of a value is unique: integers and lengths use the
* shortest head, map keys are sorted by length and then byte by byte, and
* a link is tag 42 holding a byte string of a zero byte followed by the
* binary CID. Because the encoding is unique, two encoders produce the same
* bytes and the same CID for the same value.
*
* `decodeCbor` accepts only that encoding: it rejects a longer head than
* needed, unsorted or repeated map keys, indefinite lengths, tags other
* than 42, invalid UTF-8, trailing bytes, and floats, which the atproto
* data model does not have. It checks the structure of the data model and
* not the `$type` rules that `fromJson` applies.
*/
import {ByteBuffer, Encoding} from 'zena:core';
import {OrderedHashMap} from 'zena:collections';
import {isValidUtf8} from 'zena:encoding';
import {Cid} from './cid.zena';
import {
BoolValue,
BytesValue,
IntValue,
LinkValue,
ListValue,
MapValue,
NullValue,
StringValue,
Value
} from './data.zena';
/** Bytes that are not DRISL DAG-CBOR, or a value that cannot be encoded. */
export class CborError extends Error {
new(message: String) : super(message);
}
/**
* How deeply lists and maps may nest. Deeper input is rejected before the
* decoder's recursion can exhaust the stack.
*/
let MAX_DEPTH = 256;
/** The major type in a head's top three bits. */
enum Major {
Unsigned = 0,
Negative = 1,
Bytes = 2,
Text = 3,
List = 4,
Map = 5,
Tag = 6,
Simple = 7
}
let TAG_CID: i64 = 42;
let LIMIT_8: i64 = 0x100;
let LIMIT_16: i64 = 0x10000;
let LIMIT_32: i64 = 0x100000000;
/** The DAG-CBOR encoding of `value`. */
export function encodeCbor(value: Value): FixedArray<u8> {
let out = new ByteBuffer();
writeValue(out, value);
return out.toByteArray() as FixedArray<u8>;
}
/** The CID of `value`'s DAG-CBOR encoding. */
export function cidForValue(value: Value): Cid {
return Cid.forDagCbor(encodeCbor(value));
}
/** The value DAG-CBOR `bytes` encode. */
export function decodeCbor(bytes: FixedArray<u8>): Value {
return decodeCborRange(bytes, 0, bytes.length);
}
/** The value `bytes[start..end]` encode. */
export function decodeCborRange(bytes: FixedArray<u8>, start: i32, end: i32): Value {
let decoder = new Decoder(bytes, start, end);
let value = decoder.readValue(0);
decoder.finish();
return value;
}
function writeHead(out: ByteBuffer, major: Major, n: i64) {
let m = (major as i32) << 5;
if (n < 24) {
out.writeByte(m | (n as i32));
} else if (n < LIMIT_8) {
out.writeByte(m | 24);
out.writeByte(n as i32);
} else if (n < LIMIT_16) {
out.writeByte(m | 25);
out.writeByte(((n >> 8) as i32) & 0xff);
out.writeByte((n as i32) & 0xff);
} else if (n < LIMIT_32) {
out.writeByte(m | 26);
for (var shift = 24; shift >= 0; shift -= 8) {
out.writeByte(((n >> (shift as i64)) as i32) & 0xff);
}
} else {
out.writeByte(m | 27);
for (var shift = 56; shift >= 0; shift -= 8) {
out.writeByte(((n >> (shift as i64)) as i32) & 0xff);
}
}
}
function writeText(out: ByteBuffer, text: String) {
let bytes = text.toBytes();
if (!isValidUtf8(bytes)) {
throw new CborError('string is not valid UTF-8');
}
writeHead(out, Major.Text, bytes.length as i64);
out.writeBytes(bytes as ByteArray);
}
function writeValue(out: ByteBuffer, value: Value): void {
match (value) {
case NullValue: {
out.writeByte(0xf6);
}
case BoolValue {value as b}: {
out.writeByte(if (b) 0xf5 else 0xf4);
}
case IntValue {value as n}: {
if (n >= 0) {
writeHead(out, Major.Unsigned, n);
} else {
writeHead(out, Major.Negative, -1 - n);
}
}
case StringValue {value as text}: {
writeText(out, text);
}
case BytesValue {value as bytes}: {
writeHead(out, Major.Bytes, bytes.length as i64);
out.writeBytes(bytes as ByteArray);
}
case LinkValue {cid}: {
let cidBytes = cid.toBytes();
writeHead(out, Major.Tag, TAG_CID);
writeHead(out, Major.Bytes, (cidBytes.length + 1) as i64);
out.writeByte(0);
out.writeBytes(cidBytes as ByteArray);
}
case ListValue {items}: {
writeHead(out, Major.List, items.length as i64);
for (let item in items) {
writeValue(out, item);
}
}
case MapValue {entries}: {
let keys = sortedKeys(entries);
writeHead(out, Major.Map, keys.length as i64);
for (let key in keys) {
writeText(out, key);
writeValue(out, entries[key]);
}
}
}
}
/**
* The order DAG-CBOR sorts map keys in: shorter keys first, and keys of the
* same length byte by byte. Negative when `a` comes first.
*/
export function compareKeys(a: String, b: String): i32 {
if (a.length != b.length) {
return a.length - b.length;
}
for (var i = 0; i < a.length; i += 1) {
let diff = a.getByteAt(i) - b.getByteAt(i);
if (diff != 0) {
return diff;
}
}
return 0;
}
/** The keys of `entries` in DAG-CBOR order, the order `encodeCbor` writes them in. */
export function sortedKeys(entries: OrderedHashMap<String, Value>): FixedArray<String> {
let keys = new FixedArray<String>(entries.size, '');
var i = 0;
var sorted = true;
for (let key in entries.keys()) {
keys[i] = key;
if (i > 0 && compareKeys(keys[i - 1], key) > 0) {
sorted = false;
}
i += 1;
}
if (!sorted) {
keys.sort(compareKeys);
}
return keys;
}
/** Reads one value from a byte range, checking every DRISL rule. */
final class Decoder {
#bytes: FixedArray<u8>;
var #pos: i32;
#end: i32;
/** The major type of the head `#readHead` read last. */
var #major: Major = Major.Unsigned;
/** Its argument: the integer, length or tag number. */
var #arg: i64 = 0;
new(bytes: FixedArray<u8>, start: i32, end: i32) : #bytes = bytes, #pos = start, #end = end;
/** Throws unless the value read so far ended exactly at the range's end. */
finish(): void {
if (this.#pos != this.#end) {
throw new CborError(`${this.#end - this.#pos} bytes after the value`);
}
}
#error(message: String): CborError {
return new CborError(`${message} at offset ${this.#pos}`);
}
#readByte(): i32 {
if (this.#pos >= this.#end) {
throw this.#error('truncated');
}
let b = this.#bytes[this.#pos] as i32;
this.#pos += 1;
return b;
}
#readUint(size: i32): i64 {
if (this.#end - this.#pos < size) {
throw this.#error('truncated');
}
var n: i64 = 0;
for (var i = 0; i < size; i += 1) {
n = (n << 8) | (this.#bytes[this.#pos + i] as i64);
}
this.#pos += size;
return n;
}
/**
* Reads a head into `#major` and `#arg`. For major type 7, `#arg` is the
* additional information itself.
*/
#readHead(): void {
let b = this.#readByte();
let major = (b >> 5) as Major;
let info = b & 0x1f;
this.#major = major;
if (major == Major.Simple) {
this.#arg = info as i64;
return;
}
if (info < 24) {
this.#arg = info as i64;
} else if (info == 24) {
let n = this.#readUint(1);
if (n < 24) {
throw this.#error('a one-byte argument below 24');
}
this.#arg = n;
} else if (info == 25) {
let n = this.#readUint(2);
if (n < LIMIT_8) {
throw this.#error('a two-byte argument below 256');
}
this.#arg = n;
} else if (info == 26) {
let n = this.#readUint(4);
if (n < LIMIT_16) {
throw this.#error('a four-byte argument below 65536');
}
this.#arg = n;
} else if (info == 27) {
let n = this.#readUint(8);
// An argument of 2^63 or more reads as negative, and no value in the
// data model needs one.
if (n >= 0 && n < LIMIT_32) {
throw this.#error('an eight-byte argument below 2^32');
}
this.#arg = n;
} else if (info == 31) {
throw this.#error('an indefinite length');
} else {
throw this.#error(`reserved additional information ${info}`);
}
}
/** `#arg` as a length, checked against the bytes left. */
#length(minBytesEach: i32): i32 {
let n = this.#arg;
let left = (this.#end - this.#pos) as i64;
if (n < 0 || n * (minBytesEach as i64) > left) {
throw this.#error('a length longer than the input');
}
return n as i32;
}
#readBytes(): FixedArray<u8> {
let length = this.#length(1);
let bytes = this.#bytes.slice(this.#pos, this.#pos + length);
this.#pos += length;
return bytes;
}
#readText(): String {
let length = this.#length(1);
let start = this.#pos;
if (!isValidUtf8(this.#bytes, start, start + length)) {
throw this.#error('invalid UTF-8');
}
this.#pos += length;
let copy = this.#bytes.slice(start, start + length);
return String.fromByteArray(copy as ByteArray, 0, length, Encoding.WTF8);
}
readValue(depth: i32): Value {
if (depth > MAX_DEPTH) {
throw this.#error(`lists and maps nested more than ${MAX_DEPTH} deep`);
}
this.#readHead();
return match (this.#major) {
case Major.Unsigned: this.#readInteger(false)
case Major.Negative: this.#readInteger(true)
case Major.Bytes: this.#readByteString()
case Major.Text: this.#readTextString()
case Major.List: this.#readList(depth)
case Major.Map: this.#readMap(depth)
case Major.Tag: this.#readLink()
case Major.Simple: this.#readSimple()
};
}
#readInteger(negative: boolean): Value {
// An argument of 2^63 or more reads as negative.
if (this.#arg < 0) {
throw this.#error(if (negative) 'an integer below -2^63' else 'an integer of 2^63 or more');
}
return new IntValue(if (negative) -1 - this.#arg else this.#arg);
}
#readByteString(): Value {
return new BytesValue(this.#readBytes());
}
#readTextString(): Value {
return new StringValue(this.#readText());
}
#readList(depth: i32): Value {
let count = this.#length(1);
let items = new FixedArray<Value>(count, new NullValue());
for (var i = 0; i < count; i += 1) {
items[i] = this.readValue(depth + 1);
}
return new ListValue(items);
}
#readMap(depth: i32): Value {
let count = this.#length(2);
let entries = new OrderedHashMap<String, Value>(count);
var previous: String | null = null;
for (var i = 0; i < count; i += 1) {
this.#readHead();
if (this.#major != Major.Text) {
throw this.#error('a map key that is not a string');
}
let key = this.#readText();
if (previous != null && compareKeys(previous, key) >= 0) {
throw this.#error(`map key '${key}' out of order or repeated`);
}
previous = key;
entries[key] = this.readValue(depth + 1);
}
return new MapValue(entries);
}
#readLink(): Value {
if (this.#arg != TAG_CID) {
throw this.#error(`tag ${this.#arg}; DAG-CBOR allows only tag 42`);
}
this.#readHead();
if (this.#major != Major.Bytes) {
throw this.#error('tag 42 on something other than bytes');
}
let bytes = this.#readBytes();
if (bytes.length == 0 || bytes[0] != 0) {
throw this.#error('a CID without its leading zero byte');
}
let cid = Cid.fromBytes(bytes.slice(1, bytes.length));
if (cid.version != 1) {
throw this.#error('a version 0 CID');
}
return new LinkValue(cid);
}
#readSimple(): Value {
let info = this.#arg;
if (info == 20) {
return new BoolValue(false);
}
if (info == 21) {
return new BoolValue(true);
}
if (info == 22) {
return new NullValue();
}
if (info >= 25 && info <= 27) {
throw this.#error('a float, which the atproto data model does not allow');
}
throw this.#error(`simple value ${info}`);
}
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|