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.
20.0 KiB
Raw
/**
* `did:plc` operations (https://web.plc.directory/spec/v0.1/did-plc): what
* a PLC directory records for a DID, and how a new DID is made.
*
* An operation sets the whole of a DID's state:
*
* ```json
* {
* "type": "plc_operation",
* "rotationKeys": ["did:key:zQ3sh...", "did:key:zDnae..."],
* "verificationMethods": {"atproto": "did:key:zDnae..."},
* "alsoKnownAs": ["at://router.acme.pkg.zena-lang.dev"],
* "services": {
* "atproto_pds": {"type": "AtprotoPersonalDataServer", "endpoint": "https://pkg.zena-lang.dev"}
* },
* "prev": null,
* "sig": "..."
* }
* ```
*
* `rotationKeys` may sign the next operation, the first ranked highest.
* `prev` is the CID of the operation this one follows, as a string, or null
* for the first, the genesis operation. `sig` is the base64url signature,
* without padding, of the operation's DAG-CBOR encoding without `sig`, by
* one of the rotation keys: for a genesis operation one of its own, and
* otherwise one of the previous operation's.
*
* A DID is made by its genesis operation: `did:plc:` followed by the first
* 24 characters of the lowercase base32 SHA-256 hash of the signed
* operation's DAG-CBOR encoding. `submitPlcOperation` sends an operation
* to a PLC directory. `checkOperation` is what a directory checks before
* it records one, `nullifiedEntries` which of its records a later one
* replaced, and `didDocument` the document it serves.
*/
import {Future} from 'zena:async';
import {OrderedHashMap} from 'zena:collections';
import {sha256} from 'zena:crypto';
import {base32Lower, base64Url} from 'zena:encoding';
import {fetch} from 'zena:fetch';
import {JsonArray, JsonObject, JsonValue, parseJson, stringify} from 'zena:json';
import {encodeCbor} from './cbor.zena';
import {Cid} from './cid.zena';
import {ListValue, MapValue, NullValue, StringValue, Value, newMap} from './data.zena';
import {PublicKey, formatDidKey, parseDidKey, verifySignature} from './didkey.zena';
/** An operation that is malformed, or that a PLC directory refused. */
export class PlcError extends Error {
new(message: String) : super(message);
}
/** A service a DID document lists, such as the account's PDS. */
export final class PlcService {
/** Such as `AtprotoPersonalDataServer`. */
kind: String;
endpoint: String;
new(kind: String, endpoint: String) : kind = kind, endpoint = endpoint;
}
/** A `plc_operation`, signed or not. */
export final class PlcOperation {
/** `did:key`s, highest ranked first. */
rotationKeys: Array<String>;
/** `did:key`s by name; `atproto` is the repository signing key. */
verificationMethods: OrderedHashMap<String, String>;
/** URIs such as `at://<handle>`. */
alsoKnownAs: Array<String>;
/** Services by name; `atproto_pds` is the account's PDS. */
services: OrderedHashMap<String, PlcService>;
/** The CID of the operation this follows, or null for a genesis operation. */
prev: String | null;
/** The base64url signature, or null before signing. */
sig: String | null;
new(rotationKeys: Array<String>, verificationMethods: OrderedHashMap<String, String>,
alsoKnownAs: Array<String>, services: OrderedHashMap<String, PlcService>,
prev: String | null, sig: String | null = null)
: rotationKeys = rotationKeys, verificationMethods = verificationMethods,
alsoKnownAs = alsoKnownAs, services = services, prev = prev, sig = sig;
/** The operation in the data model, with `sig` when it is signed. */
toValue(): MapValue {
let map = this.#unsigned();
let sig = this.sig;
if (sig != null) {
map.entries['sig'] = new StringValue(sig);
}
return map;
}
/** The operation signed by `sign`, which signs with a rotation key. */
signedWith(sign: (bytes: FixedArray<u8>) => FixedArray<u8>): PlcOperation {
return this.withSignature(sign(this.signingBytes()));
}
/**
* The bytes a rotation key signs: the operation without `sig`, as
* DAG-CBOR. For a signer that answers later, such as a key management
* service, with `withSignature` after.
*/
signingBytes(): FixedArray<u8> {
return encodeCbor(this.#unsigned());
}
/** The operation with `signature`, 64 bytes of low-S r and s, as its `sig`. */
withSignature(signature: FixedArray<u8>): PlcOperation {
return new PlcOperation(this.rotationKeys, this.verificationMethods, this.alsoKnownAs,
this.services, this.prev, base64Url.encode(signature, false));
}
/** Whether `key` made the operation's signature. */
isSignedBy(key: PublicKey): boolean {
let sig = this.sig;
if (sig == null) {
return false;
}
var signature = new FixedArray<u8>(0, 0 as u8);
try {
signature = base64Url.decode(sig);
} catch (e) {
return false;
}
return verifySignature(key, encodeCbor(this.#unsigned()), signature);
}
/** The CID of the signed operation, which the next operation names as `prev`. */
cid(): Cid {
return Cid.forDagCbor(encodeCbor(this.toValue()));
}
toJson(): JsonObject {
let json = new JsonObject();
json['type'] = 'plc_operation';
json['rotationKeys'] = stringArray(this.rotationKeys);
let methods = new JsonObject();
this.verificationMethods.forEach((name, key) => {
methods[name] = key;
});
json['verificationMethods'] = methods;
json['alsoKnownAs'] = stringArray(this.alsoKnownAs);
let services = new JsonObject();
this.services.forEach((name, service) => {
let entry = new JsonObject();
entry['type'] = service.kind;
entry['endpoint'] = service.endpoint;
services[name] = entry;
});
json['services'] = services;
json['prev'] = this.prev;
let sig = this.sig;
if (sig != null) {
json['sig'] = sig;
}
return json;
}
/** Reads an operation's JSON form. Throws `PlcError`. */
static fromJson(json: JsonValue): PlcOperation {
if (!(json is JsonObject)) {
throw new PlcError('an operation is not a JSON object');
}
let object = json;
if (object['type'] != 'plc_operation') {
throw new PlcError('the operation is not a plc_operation');
}
let methods = new OrderedHashMap<String, String>();
membersOf(object, 'verificationMethods').forEach((name, value) => {
methods[name] = stringOf(value, 'a verification method');
});
let services = new OrderedHashMap<String, PlcService>();
membersOf(object, 'services').forEach((name, value) => {
if (!(value is JsonObject)) {
throw new PlcError(`service ${name} is not an object`);
}
let entry = value;
services[name] = new PlcService(stringOf(entry['type'], 'a service type'),
stringOf(entry['endpoint'], 'a service endpoint'));
});
let prev = object['prev'];
let sig = object['sig'];
return new PlcOperation(
stringsOf(object, 'rotationKeys'), methods, stringsOf(object, 'alsoKnownAs'), services,
if (prev == null) null else stringOf(prev, 'prev'),
if (sig == null) null else stringOf(sig, 'sig'));
}
#unsigned(): MapValue {
let map = newMap();
map.entries['type'] = new StringValue('plc_operation');
map.entries['rotationKeys'] = stringList(this.rotationKeys);
let methods = newMap();
this.verificationMethods.forEach((name, key) => {
methods.entries[name] = new StringValue(key);
});
map.entries['verificationMethods'] = methods;
map.entries['alsoKnownAs'] = stringList(this.alsoKnownAs);
let services = newMap();
this.services.forEach((name, service) => {
let entry = newMap();
entry.entries['type'] = new StringValue(service.kind);
entry.entries['endpoint'] = new StringValue(service.endpoint);
services.entries[name] = entry;
});
map.entries['services'] = services;
let prev = this.prev;
map.entries['prev'] = if (prev == null) new NullValue() else new StringValue(prev);
return map;
}
}
/**
* An unsigned genesis operation for an account whose repository is signed
* by `signingKey`, named `handle`, at the PDS `pdsEndpoint`, which
* `rotationKeys` may change, the first ranked highest.
*/
export function genesisOperation(signingKey: PublicKey, rotationKeys: Array<PublicKey>,
handle: String, pdsEndpoint: String): PlcOperation {
let rotation = new GrowableArray<String>();
for (let key in rotationKeys) {
rotation.push(formatDidKey(key));
}
let methods = new OrderedHashMap<String, String>();
methods['atproto'] = formatDidKey(signingKey);
let services = new OrderedHashMap<String, PlcService>();
services['atproto_pds'] = new PlcService('AtprotoPersonalDataServer', pdsEndpoint);
let aka = new GrowableArray<String>();
aka.push(`at://${handle}`);
return new PlcOperation(rotation, methods, aka, services, null);
}
/**
* The DID a signed genesis operation makes. Throws `PlcError` when the
* operation is not a signed genesis operation, or no rotation key it lists
* signed it.
*/
export function didOfGenesis(operation: PlcOperation): String {
if (operation.prev != null) {
throw new PlcError('the operation follows another, so it makes no DID');
}
if (operation.sig == null) {
throw new PlcError('the operation is not signed');
}
var signed = false;
for (let key in operation.rotationKeys) {
signed = signed || operation.isSignedBy(parseDidKey(key));
}
if (!signed) {
throw new PlcError('none of the operation\'s rotation keys signed it');
}
let hash = sha256(encodeCbor(operation.toValue()));
return `did:plc:${base32Lower.encode(hash, false).sliceBytes(0, 24)}`;
}
/**
* The unsigned operation that undoes every operation after the one whose
* CID is `cid` in `log`, oldest first: a copy of that operation, naming it
* as `prev`. Signed by `key`, a PLC directory takes it in place of the
* operations after `cid` when it comes within 72 hours of the first of
* them, and `key` is one of `cid`'s rotation keys ranked above the key
* that signed that first one. Throws `PlcError` when `cid` is not in
* `log`, is its last operation, or `key` does not rank high enough.
*/
export function undoOperation(log: Array<PlcOperation>, cid: String, key: PublicKey): PlcOperation {
var at = -1;
for (var i = 0; i < log.length; i += 1) {
if (log[i].cid().toString() == cid) {
at = i;
}
}
if (at < 0) {
throw new PlcError(`${cid} is not in the log`);
}
if (at == log.length - 1) {
throw new PlcError(`${cid} is the last operation; there is nothing after it to undo`);
}
let kept = log[at];
let wanted = formatDidKey(key);
var rank = -1;
for (var i = 0; i < kept.rotationKeys.length; i += 1) {
if (kept.rotationKeys[i] == wanted) {
rank = i;
}
}
let signerRank = rankOfSigner(kept, log[at + 1]);
if (rank < 0) {
throw new PlcError(`${wanted} is not one of ${cid}'s rotation keys`);
}
if (signerRank >= 0 && rank >= signerRank) {
throw new PlcError(`${wanted} ranks ${rank + 1}, not above the key that signed the operation after ${cid}, which ranks ${signerRank + 1}`);
}
return new PlcOperation(kept.rotationKeys, kept.verificationMethods, kept.alsoKnownAs, kept.services, cid);
}
/**
* Checks that `operation` may follow `log`, the operations a directory has
* recorded for `did`, oldest first. Throws `PlcError` when it may not.
*
* The first must be a genesis operation that makes `did`. Each after it
* must name the last as `prev` and be signed by one of the last one's
* rotation keys. The specification also lets a higher-ranked rotation key
* replace operations from the last 72 hours; this does not, so it suits a
* directory whose operations only go forward, such as a test's.
* `checkOperation` does.
*/
export function checkNextOperation(did: String, log: Array<PlcOperation>, operation: PlcOperation): void {
if (log.length == 0) {
let made = didOfGenesis(operation);
if (made != did) {
throw new PlcError(`the genesis operation makes ${made}, not ${did}`);
}
return;
}
let last = log[log.length - 1];
let prev = operation.prev;
let lastCid = last.cid().toString();
if (prev == null || prev != lastCid) {
throw new PlcError(`the operation must follow ${lastCid}`);
}
for (let key in last.rotationKeys) {
if (operation.isSignedBy(parseDidKey(key))) {
return;
}
}
throw new PlcError('none of the previous operation\'s rotation keys signed the operation');
}
/** How long a higher-ranked rotation key may replace an operation after a directory records it: 72 hours, in microseconds. */
export let NULLIFY_WINDOW_MICROS = 259200000000 as i64;
/** An operation as a directory recorded it, with when, in microseconds since the epoch. */
export final class PlcLogEntry {
operation: PlcOperation;
createdAt: i64;
new(this.operation, this.createdAt);
}
/**
* Which of `entries`, every operation a directory recorded for a DID,
* oldest first, a later one replaced: each after the operation a later one
* names as `prev`, when that was not the last then. The specification
* calls them nullified. The rest, in order, are the DID's operations
* (`activeOperations`).
*/
export function nullifiedEntries(entries: Array<PlcLogEntry>): FixedArray<boolean> {
let nullified = new FixedArray<boolean>(entries.length, false);
// The DID's operations after each entry, as indexes into `entries`.
let chain = new FixedArray<i32>(entries.length, 0);
var length = 0;
for (var i = 0; i < entries.length; i += 1) {
let prev = entries[i].operation.prev;
if (prev != null) {
while (length > 0 && entries[chain[length - 1]].operation.cid().toString() != prev) {
nullified[chain[length - 1]] = true;
length -= 1;
}
}
chain[length] = i;
length += 1;
}
return nullified;
}
/** The operations of `entries` no later one replaced (`nullifiedEntries`), oldest first. */
export function activeOperations(entries: Array<PlcLogEntry>): Array<PlcOperation> {
let nullified = nullifiedEntries(entries);
let operations = new GrowableArray<PlcOperation>();
for (var i = 0; i < entries.length; i += 1) {
if (!nullified[i]) {
operations.push(entries[i].operation);
}
}
return operations;
}
/**
* Checks that a directory may record `operation` for `did` at `now`, in
* microseconds, after `entries`, every operation it recorded for `did`,
* oldest first, replaced ones included. Throws `PlcError` when it may not.
*
* It takes what `checkNextOperation` takes: an operation that follows the
* last of the DID's operations. It also takes one that follows an earlier
* one, replacing those after it, as the specification does: when it is
* signed by one of that earlier operation's rotation keys ranked above the
* key that signed the first operation it replaces, and the directory
* recorded that one no more than 72 hours before `now`.
*/
export function checkOperation(did: String, entries: Array<PlcLogEntry>, operation: PlcOperation, now: i64): void {
let nullified = nullifiedEntries(entries);
let active = new GrowableArray<PlcLogEntry>();
let operations = new GrowableArray<PlcOperation>();
for (var i = 0; i < entries.length; i += 1) {
if (!nullified[i]) {
active.push(entries[i]);
operations.push(entries[i].operation);
}
}
let prev = operation.prev;
if (active.length == 0 || prev == null || prev == active[active.length - 1].operation.cid().toString()) {
checkNextOperation(did, operations, operation);
return;
}
var at = -1;
for (var i = 0; i < active.length; i += 1) {
if (active[i].operation.cid().toString() == prev) {
at = i;
}
}
if (at < 0) {
throw new PlcError(`the operation follows ${prev}, which is not one of ${did}'s operations`);
}
let kept = active[at].operation;
let first = active[at + 1];
let rank = rankOfSigner(kept, operation);
if (rank < 0) {
throw new PlcError(`none of ${prev}'s rotation keys signed the operation`);
}
let signerRank = rankOfSigner(kept, first.operation);
if (signerRank >= 0 && rank >= signerRank) {
throw new PlcError(`the operation is signed by ${prev}'s rotation key ranked ${rank + 1}, not above the one ranked ${signerRank + 1}, which signed the operation it would replace`);
}
if (now - first.createdAt > NULLIFY_WINDOW_MICROS) {
throw new PlcError(`the operations after ${prev} were recorded more than 72 hours ago, too long to replace`);
}
}
/** Where the key that signed `operation` ranks among `previous`'s rotation keys, from 0, or -1 for none of them. */
function rankOfSigner(previous: PlcOperation, operation: PlcOperation): i32 {
for (var i = 0; i < previous.rotationKeys.length; i += 1) {
if (operation.isSignedBy(parseDidKey(previous.rotationKeys[i]))) {
return i;
}
}
return -1;
}
/** The DID document `operation` gives `did`, as a PLC directory serves it. */
export function didDocument(did: String, operation: PlcOperation): JsonObject {
let doc = new JsonObject();
let context = new JsonArray();
context.push('https://www.w3.org/ns/did/v1');
context.push('https://w3id.org/security/multikey/v1');
doc['@context'] = context;
doc['id'] = did;
doc['alsoKnownAs'] = stringArray(operation.alsoKnownAs);
let methods = new JsonArray();
operation.verificationMethods.forEach((name, key) => {
let method = new JsonObject();
method['id'] = `${did}#${name}`;
method['type'] = 'Multikey';
method['controller'] = did;
method['publicKeyMultibase'] = key.sliceBytes('did:key:'.length, key.length);
methods.push(method);
});
doc['verificationMethod'] = methods;
let services = new JsonArray();
operation.services.forEach((name, service) => {
let entry = new JsonObject();
entry['id'] = `#${name}`;
entry['type'] = service.kind;
entry['serviceEndpoint'] = service.endpoint;
services.push(entry);
});
doc['service'] = services;
return doc;
}
/**
* Sends `operation` for `did` to the PLC directory at `directory`, such as
* `https://plc.directory`. Throws `PlcError` when the directory refuses it.
*/
export async function submitPlcOperation(directory: String, did: String, operation: PlcOperation)
: Future<void> {
let response = await fetch(`${directory}/${did}`, {
method: 'POST',
headers: [('content-type', 'application/json')],
body: stringify(operation.toJson()),
});
if (!response.ok) {
throw new PlcError(`${directory} refused the operation for ${did}: HTTP ${response.status} ${await response.text()}`);
}
}
/**
* The operations the PLC directory at `directory` has recorded for `did`,
* oldest first, the genesis operation among them. Throws `PlcError` when
* the directory has no log for it.
*/
export async function fetchOperations(directory: String, did: String): Future<Array<PlcOperation>> {
let response = await fetch(`${directory}/${did}/log`);
if (!response.ok) {
throw new PlcError(`${directory} has no log for ${did}: HTTP ${response.status}`);
}
let list = parseJson(await response.text());
if (!(list is JsonArray)) {
throw new PlcError(`${directory} answered ${did}'s log with something other than a list`);
}
let log = new GrowableArray<PlcOperation>();
for (var i = 0; i < list.length; i += 1) {
log.push(PlcOperation.fromJson(list[i]));
}
return log;
}
function stringArray(items: Array<String>): JsonArray {
let array = new JsonArray();
for (let item in items) {
array.push(item);
}
return array;
}
function stringList(items: Array<String>): ListValue {
let values = new FixedArray<Value>(items.length, new NullValue());
for (var i = 0; i < items.length; i += 1) {
values[i] = new StringValue(items[i]);
}
return new ListValue(values);
}
function membersOf(object: JsonObject, name: String): JsonObject {
let value = object[name];
if (!(value is JsonObject)) {
throw new PlcError(`the operation's ${name} is not an object`);
}
return value;
}
function stringsOf(object: JsonObject, name: String): GrowableArray<String> {
let value = object[name];
if (!(value is JsonArray)) {
throw new PlcError(`the operation's ${name} is not a list`);
}
let list = value;
let strings = new GrowableArray<String>();
for (var i = 0; i < list.length; i += 1) {
strings.push(stringOf(list[i], name));
}
return strings;
}
function stringOf(value: JsonValue, what: String): String {
if (!(value is String)) {
throw new PlcError(`${what} is not a string`);
}
return value;
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|