/** * `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; /** `did:key`s by name; `atproto` is the repository signing key. */ verificationMethods: OrderedHashMap; /** URIs such as `at://`. */ alsoKnownAs: Array; /** Services by name; `atproto_pds` is the account's PDS. */ services: OrderedHashMap; /** 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, verificationMethods: OrderedHashMap, alsoKnownAs: Array, services: OrderedHashMap, 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) => FixedArray): 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 { return encodeCbor(this.#unsigned()); } /** The operation with `signature`, 64 bytes of low-S r and s, as its `sig`. */ withSignature(signature: FixedArray): 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(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(); membersOf(object, 'verificationMethods').forEach((name, value) => { methods[name] = stringOf(value, 'a verification method'); }); let services = new OrderedHashMap(); 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, handle: String, pdsEndpoint: String): PlcOperation { let rotation = new GrowableArray(); for (let key in rotationKeys) { rotation.push(formatDidKey(key)); } let methods = new OrderedHashMap(); methods['atproto'] = formatDidKey(signingKey); let services = new OrderedHashMap(); services['atproto_pds'] = new PlcService('AtprotoPersonalDataServer', pdsEndpoint); let aka = new GrowableArray(); 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, 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, 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): FixedArray { let nullified = new FixedArray(entries.length, false); // The DID's operations after each entry, as indexes into `entries`. let chain = new FixedArray(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): Array { let nullified = nullifiedEntries(entries); let operations = new GrowableArray(); 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, operation: PlcOperation, now: i64): void { let nullified = nullifiedEntries(entries); let active = new GrowableArray(); let operations = new GrowableArray(); 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 { 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> { 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(); for (var i = 0; i < list.length; i += 1) { log.push(PlcOperation.fromJson(list[i])); } return log; } function stringArray(items: Array): JsonArray { let array = new JsonArray(); for (let item in items) { array.push(item); } return array; } function stringList(items: Array): ListValue { let values = new FixedArray(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 { 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(); 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; }