@atcute/did-plc 0.1.0

package/dist/utils.js

@@ -0,0 +1,51 @@
+import * as CBOR from '@atcute/cbor';
+import { verifySigWithDidKey } from '@atcute/crypto';
+import { fromBase64Url } from '@atcute/multibase';
+import * as t from './types.js';
+export const wrapHttpPrefix = (str) => {
+    if (str.startsWith('http://') || str.startsWith('https://')) {
+        return str;
+    }
+    return `https://${str}`;
+};
+export const wrapAtprotoPrefix = (str) => {
+    if (str.startsWith('at://')) {
+        return str;
+    }
+    const stripped = str.replace('http://', '').replace('https://', '');
+    return `at://${stripped}`;
+};
+export const normalizeOp = (op) => {
+    if (op.type === 'create') {
+        return {
+            type: 'plc_operation',
+            prev: op.prev,
+            sig: op.sig,
+            rotationKeys: [op.recoveryKey, op.signingKey],
+            verificationMethods: {
+                atproto: op.signingKey,
+            },
+            alsoKnownAs: [wrapAtprotoPrefix(op.handle)],
+            services: {
+                atproto_pds: {
+                    type: 'AtprotoPersonalDataServer',
+                    endpoint: wrapHttpPrefix(op.service),
+                },
+            },
+        };
+    }
+    return op;
+};
+export const isSignedOperationValid = async (allowedKeys, op) => {
+    const { sig, ...unsignedOp } = op;
+    const sigBytes = fromBase64Url(sig);
+    const opBytes = CBOR.encode(unsignedOp);
+    for (const key of allowedKeys) {
+        const ok = await verifySigWithDidKey(key, sigBytes, opBytes);
+        if (ok) {
+            return key;
+        }
+    }
+    return null;
+};
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../lib/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,CAAC,MAAM,YAAY,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAW,EAAU,EAAE;IACrD,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7D,OAAO,GAAG,CAAC;IACZ,CAAC;IAED,OAAO,WAAW,GAAG,EAAE,CAAC;AACzB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAW,EAAU,EAAE;IACxD,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAEpE,OAAO,QAAQ,QAAQ,EAAE,CAAC;AAC3B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAyB,EAAe,EAAE;IACrE,IAAI,EAAE,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO;YACN,IAAI,EAAE,eAAe;YACrB,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,GAAG,EAAE,EAAE,CAAC,GAAG;YACX,YAAY,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,UAAU,CAAC;YAC7C,mBAAmB,EAAE;gBACpB,OAAO,EAAE,EAAE,CAAC,UAAU;aACtB;YACD,WAAW,EAAE,CAAC,iBAAiB,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;YAC3C,QAAQ,EAAE;gBACT,WAAW,EAAE;oBACZ,IAAI,EAAE,2BAA2B;oBACjC,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC,OAAO,CAAC;iBACpC;aACD;SACD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC;AACX,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,EAC1C,WAA6B,EAC7B,EAAoC,EACH,EAAE;IACnC,MAAM,EAAE,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,CAAC;IAElC,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAExC,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,EAAE,GAAG,MAAM,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAE7D,IAAI,EAAE,EAAE,CAAC;YACR,OAAO,GAAG,CAAC;QACZ,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC,CAAC"}

package/lib/constants.ts

@@ -0,0 +1,5 @@
+const SECOND = 1e3;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+
+export const DISPUTE_WINDOW = 72 * HOUR;

package/lib/data.ts

@@ -0,0 +1,245 @@
+import * as CBOR from '@atcute/cbor';
+import * as CID from '@atcute/cid';
+import { toBase32 } from '@atcute/multibase';
+import { toSha256 } from '@atcute/uint8array';
+
+import { DISPUTE_WINDOW } from './constants.js';
+import * as err from './errors.js';
+import * as t from './types.js';
+import { isSignedOperationValid, normalizeOp } from './utils.js';
+
+/**
+ * Process an indexed entry by validating it and integrating it into the canonical log.
+ */
+export const processIndexedEntry = async (
+	did: t.DidPlcString,
+	canonical: t.IndexedEntryWithSigner[],
+	proposed: t.IndexedEntry,
+): Promise<{
+	prev: string | null;
+	ops: t.IndexedEntryWithSigner[];
+	nullified: t.IndexedEntryWithSigner[];
+}> => {
+	if (canonical.length === 0) {
+		if (proposed.operation.type === 'plc_tombstone') {
+			throw new err.ImproperOperationError(proposed, `expected genesis op to not be tombstone`);
+		}
+
+		if (proposed.operation.prev !== null) {
+			throw new err.ImproperOperationError(proposed, `expected null prev on genesis op`);
+		}
+
+		// Check if CID and DID matches
+		{
+			const opBytes = CBOR.encode(proposed.operation);
+
+			const expectedDid = `did:plc:${toBase32(await toSha256(opBytes)).slice(0, 24)}`;
+			if (expectedDid !== did) {
+				throw new err.GenesisHashError(proposed, did);
+			}
+
+			const expectedCid = CID.toString(await CID.create(CID.CODEC_DCBOR, opBytes));
+			if (expectedCid !== proposed.cid) {
+				throw new err.InvalidHashError(proposed, expectedCid);
+			}
+		}
+
+		// Check if signature is valid
+		let allowedSigners: t.DidKeyString[];
+		let signedBy: t.DidKeyString;
+
+		{
+			const { rotationKeys } = normalizeOp(proposed.operation);
+			const ok = await isSignedOperationValid(rotationKeys, proposed.operation);
+
+			if (!ok) {
+				throw new err.InvalidSignatureError(proposed);
+			}
+
+			allowedSigners = rotationKeys;
+			signedBy = ok;
+		}
+
+		return {
+			prev: null,
+			nullified: [],
+			ops: [{ ...proposed, allowedSigners, signedBy }],
+		};
+	}
+
+	// Grab the previous reference
+	const proposedPrev = proposed.operation.prev;
+	if (!proposedPrev) {
+		throw new err.ImproperOperationError(proposed, `expected prev op`);
+	}
+
+	const indexOfPrev = canonical.findIndex((op) => op.cid === proposedPrev);
+	if (indexOfPrev === -1) {
+		throw new err.ImproperOperationError(proposed, `prev op not in history`);
+	}
+
+	// Check if the CID matches
+	{
+		const opBytes = CBOR.encode(proposed.operation);
+		const expectedCid = CID.toString(await CID.create(CID.CODEC_DCBOR, opBytes));
+		if (expectedCid !== proposed.cid) {
+			throw new err.InvalidHashError(proposed, expectedCid);
+		}
+	}
+
+	// Get the proposed canonical history
+	const alteredHistory = canonical.slice(0, indexOfPrev + 1);
+
+	const nullified = canonical.slice(indexOfPrev + 1);
+	const lastOp = alteredHistory.at(-1);
+
+	if (!lastOp) {
+		throw new err.ImproperOperationError(proposed, `missing last op`);
+	}
+	if (lastOp.operation.type === 'plc_tombstone') {
+		throw new err.ImproperOperationError(proposed, `did is tombstoned`);
+	}
+
+	const lastOpNormalized = normalizeOp(lastOp.operation);
+	const firstNullified = nullified[0];
+
+	// We're not nullifying, check if the signature is valid and move on
+	if (!firstNullified) {
+		const allowedSigners = lastOpNormalized.rotationKeys;
+		const signedBy = await isSignedOperationValid(allowedSigners, proposed.operation);
+		if (!signedBy) {
+			throw new err.InvalidSignatureError(proposed);
+		}
+
+		return {
+			prev: proposedPrev,
+			nullified: [],
+			ops: [...canonical, { ...proposed, allowedSigners, signedBy }],
+		};
+	}
+
+	// The indexed log should say that all of the nullified has `nullified: true`
+	// for (let idx = 0, len = nullified.length; idx < len; idx++) {
+	// 	const op = nullified[idx];
+
+	// 	if (!op.nullified) {
+	// 		throw new err.ImproperOperationError(op, `expected nullified prop to be true`);
+	// 	}
+	// }
+
+	// Check if operation within the recovery window
+	{
+		const lapsed = new Date(proposed.createdAt).getTime() - new Date(firstNullified.createdAt).getTime();
+
+		if (lapsed > DISPUTE_WINDOW) {
+			throw new err.LateDisputeError(proposed, lapsed);
+		}
+	}
+
+	// Check if the dispute is valid
+	{
+		let allowedSigners: t.DidKeyString[];
+		let signedBy: t.DidKeyString;
+
+		{
+			const disputedSigner = firstNullified.signedBy;
+
+			const indexOfSigner = lastOpNormalized.rotationKeys.indexOf(disputedSigner);
+			const morePowerfulKeys = lastOpNormalized.rotationKeys.slice(0, indexOfSigner);
+
+			const ok = await isSignedOperationValid(morePowerfulKeys, proposed.operation);
+			if (!ok) {
+				throw new err.InvalidSignatureError(proposed);
+			}
+
+			allowedSigners = morePowerfulKeys;
+			signedBy = ok;
+		}
+
+		return {
+			prev: proposedPrev,
+			nullified: nullified,
+			ops: [...alteredHistory, { ...proposed, allowedSigners, signedBy }],
+		};
+	}
+};
+
+/**
+ * Process an indexed entry log by sequentially processing each operation.
+ */
+export const processIndexedEntryLog = async (
+	did: t.DidPlcString,
+	ops: t.IndexedEntryLog,
+): Promise<{ canonical: t.IndexedEntryWithSigner[]; nullified: t.IndexedEntryWithSigner[] }> => {
+	let nullified: t.IndexedEntryWithSigner[] = [];
+	let canonical: t.IndexedEntryWithSigner[] = [];
+
+	for (const operation of ops) {
+		const result = await processIndexedEntry(did, canonical, operation);
+		canonical = result.ops;
+
+		if (result.nullified.length > 0) {
+			nullified = nullified.concat(result.nullified);
+		}
+	}
+
+	return { canonical, nullified };
+};
+
+/**
+ * Check whether an operation can still be disputed
+ */
+export const isDisputePeriodActive = (disputed: t.IndexedEntry, now = Date.now()): boolean => {
+	const lapsed = now - new Date(disputed.createdAt).getTime();
+	return lapsed <= DISPUTE_WINDOW;
+};
+
+/**
+ * Check if a key is authorized to dispute an operation
+ */
+export const isAuthorizedForDispute = (
+	base: t.IndexedEntryWithSigner<t.CompatibleOperation>,
+	disputed: t.IndexedEntryWithSigner,
+	key: t.DidKeyString,
+): boolean => {
+	const { rotationKeys } = normalizeOp(base.operation);
+
+	const disputedSigner = disputed.signedBy;
+	const disputedIndex = rotationKeys.indexOf(disputedSigner);
+	if (disputedIndex === -1) {
+		return false;
+	}
+
+	const didKeyIndex = rotationKeys.indexOf(key);
+	return didKeyIndex !== -1 && didKeyIndex < disputedIndex;
+};
+
+export interface DisputeCandidate {
+	base: t.IndexedEntryWithSigner<t.CompatibleOperation>;
+	disputed: t.IndexedEntryWithSigner;
+}
+
+/**
+ * Finds operations that can be disputed by a given key
+ */
+export const getDisputeCandidates = (canonical: t.IndexedEntryWithSigner[], key: t.DidKeyString) => {
+	const candidates: DisputeCandidate[] = [];
+	const now = Date.now();
+
+	for (let idx = 1, len = canonical.length; idx < len; idx++) {
+		const base = canonical[idx - 1] as t.IndexedEntryWithSigner<t.CompatibleOperation>;
+		const disputed = canonical[idx];
+
+		// Only consider if it's still within the recovery window.
+		if (!isDisputePeriodActive(disputed, now)) {
+			continue;
+		}
+
+		// Check if the provided key is allowed to dispute this operation.
+		if (isAuthorizedForDispute(base, disputed, key)) {
+			candidates.push({ base, disputed });
+		}
+	}
+
+	return candidates;
+};

package/lib/errors.ts

@@ -0,0 +1,57 @@
+import * as t from './types.js';
+
+export class PlcError extends Error {
+	override name = 'PlcError';
+}
+
+export class ImproperOperationError extends PlcError {
+	override name = 'ImproperOperationError';
+
+	constructor(
+		public operation: t.IndexedEntry,
+		public reason: string,
+	) {
+		super(`improper operation; cid=${operation.cid}; reason=${reason}`);
+	}
+}
+
+export class InvalidSignatureError extends PlcError {
+	override name = 'InvalidSignatureError';
+
+	constructor(public operation: t.IndexedEntry) {
+		super(`invalid signature; cid=${operation.cid}`);
+	}
+}
+
+export class InvalidHashError extends PlcError {
+	override name = 'InvalidHashError';
+
+	constructor(
+		public operation: t.IndexedEntry,
+		public expected: string,
+	) {
+		super(`invalid hash; expected=${expected}; got=${operation.cid}`);
+	}
+}
+
+export class GenesisHashError extends PlcError {
+	override name = 'GenesisHashError';
+
+	constructor(
+		public operation: t.IndexedEntry,
+		public did: t.DidPlcString,
+	) {
+		super(`mismatching genesis hash; did=${did}; cid=${operation.cid}`);
+	}
+}
+
+export class LateDisputeError extends PlcError {
+	override name = 'LateDisputeError';
+
+	constructor(
+		public operation: t.IndexedEntry,
+		public lapsed: number,
+	) {
+		super(`dispute occured outside of permitted window; cid=${operation.cid}; lapsed=${lapsed}`);
+	}
+}

package/lib/index.ts

@@ -0,0 +1,7 @@
+export * as defs from './typedefs.js';
+export * from './types.js';
+
+export * from './constants.js';
+export * from './data.js';
+export * from './errors.js';
+export * from './utils.js';

package/lib/typedefs.ts

@@ -0,0 +1,201 @@
+import * as v from '@badrap/valita';
+
+import * as CID from '@atcute/cid';
+import { parseDidKey } from '@atcute/crypto';
+
+import * as t from './types.js';
+
+// #region Strings
+const DID_PLC_RE = /^did:plc:([a-z2-7]{24})$/;
+
+export const didPlcString = v
+	.string()
+	.assert((input): input is t.DidPlcString => DID_PLC_RE.test(input), `must be a did:plc`);
+
+export const didKeyString = v.string().chain((input) => {
+	try {
+		parseDidKey(input);
+	} catch (err) {
+		if (err instanceof SyntaxError) {
+			return v.err(`did:key can't be parsed`);
+		}
+
+		return v.err(`invalid did:key`);
+	}
+
+	return v.ok(input as t.DidKeyString);
+});
+
+const cidString = v.string().chain((input) => {
+	try {
+		CID.fromString(input);
+	} catch {
+		return v.err(`invalid cid`);
+	}
+
+	return v.ok(input);
+});
+// #endregion
+
+// #region create
+const _unsignedLegacyCreateOperation = v.object({
+	type: v.literal('create'),
+	prev: v.null(),
+	signingKey: didKeyString,
+	recoveryKey: didKeyString,
+	handle: v.string().assert((input) => input.length <= 256, `handle too long (max 256 characters)`),
+	service: v
+		.string()
+		.assert((input) => input.length <= 512, `service endpoint too long (max 512 characters)`),
+}) satisfies v.Type<t.UnsignedLegacyCreateOperation>;
+
+export const unsignedLegacyCreateOperation: v.Type<t.UnsignedLegacyCreateOperation> =
+	_unsignedLegacyCreateOperation;
+
+export const legacyCreateOperation: v.Type<t.LegacyCreateOperation> = _unsignedLegacyCreateOperation.extend({
+	sig: v.string(),
+});
+// #endregion
+
+// #region plc_operation
+export const service: v.Type<t.Service> = v.object({
+	type: v.string().assert((input) => input.length <= 256, `service type too long (max 256 characters)`),
+	endpoint: v
+		.string()
+		.assert((input) => input.length <= 512, `service endpoint too long (max 512 characters)`),
+});
+
+const _unsignedOperation = v.object({
+	type: v.literal('plc_operation'),
+	prev: v.string().nullable(),
+	rotationKeys: v.array(didKeyString).chain((input) => {
+		const length = input.length;
+
+		if (length === 0) {
+			return v.err(`missing rotation keys`);
+		} else if (length > 10) {
+			return v.err(`too many rotation keys (max 10 keys)`);
+		}
+
+		for (let i = 0; i < length; i++) {
+			const key = input[i];
+
+			for (let j = 0; j < i; j++) {
+				if (input[j] === key) {
+					return v.err({
+						message: `duplicate "${key}" rotation key`,
+						path: [i],
+					});
+				}
+			}
+		}
+
+		return v.ok(input);
+	}),
+	verificationMethods: v.record(didKeyString).chain((input) => {
+		for (const id in input) {
+			if (id.length > 32) {
+				return v.err({
+					message: `verification method id too long (max 32 characters)`,
+					path: [id],
+				});
+			}
+		}
+
+		return v.ok(input);
+	}),
+	alsoKnownAs: v
+		.array(v.string().assert((input) => input.length <= 256, `aka entry too long (max 256 characters)`))
+		.chain((input) => {
+			const length = input.length;
+
+			if (length > 10) {
+				return v.err(`too many aka entries (max 10)`);
+			}
+
+			for (let i = 0; i < length; i++) {
+				const aka = input[i];
+
+				for (let j = 0; j < i; j++) {
+					if (input[j] === aka) {
+						return v.err({
+							message: `duplicate "${aka}" aka entry`,
+							path: [i],
+						});
+					}
+				}
+			}
+
+			return v.ok(input);
+		}),
+	services: v.record(service).chain((input) => {
+		const length = Object.keys(input).length;
+
+		if (length > 10) {
+			return v.err(`too many service entries (max 10)`);
+		}
+
+		for (const id in input) {
+			if (id.length > 32) {
+				return v.err({
+					message: `service id too long (max 32 characters)`,
+					path: [id],
+				});
+			}
+		}
+
+		return v.ok(input);
+	}),
+}) satisfies v.Type<t.UnsignedOperation>;
+
+export const unsignedOperation: v.Type<t.UnsignedOperation> = _unsignedOperation;
+
+export const operation: v.Type<t.Operation> = _unsignedOperation.extend({
+	sig: v.string(),
+});
+// #endregion
+
+// #region plc_tombstone
+const _unsignedTombstone = v.object({
+	type: v.literal('plc_tombstone'),
+	prev: v.string(),
+}) satisfies v.Type<t.UnsignedTombstone>;
+
+export const unsignedTombstone: v.Type<t.UnsignedTombstone> = _unsignedTombstone;
+
+export const tombstone: v.Type<t.Tombstone> = _unsignedTombstone.extend({
+	sig: v.string(),
+});
+// #endregion
+
+// #region Entry
+export const compatibleOperation: v.Type<t.CompatibleOperation> = v.union(operation, legacyCreateOperation);
+
+export const compatibleOperationOrTombstone: v.Type<t.CompatibleOperationOrTombstone> = v.union(
+	operation,
+	legacyCreateOperation,
+	tombstone,
+);
+
+export const operationOrTombstone: v.Type<t.OperationOrTombstone> = v.union(operation, tombstone);
+
+export const operationLog: v.Type<t.OperationLog> = v
+	.tuple([compatibleOperation])
+	.concat(v.array(operationOrTombstone));
+// #endregion
+
+// #region Indexed entry
+const _indexedEntry = v.object({
+	did: didPlcString,
+	operation: compatibleOperationOrTombstone,
+	cid: cidString,
+	nullified: v.boolean(),
+	createdAt: v.string().assert((input) => !Number.isNaN(new Date(input).getTime()), `invalid timestamp`),
+}) satisfies v.Type<t.IndexedEntry>;
+
+export const indexedEntry: v.Type<t.IndexedEntry> = _indexedEntry;
+
+export const indexedEntryLog: v.Type<t.IndexedEntryLog> = v
+	.tuple([_indexedEntry.extend({ operation: compatibleOperation })])
+	.concat(v.array(_indexedEntry.extend({ operation: operationOrTombstone })));
+// #endregion

package/lib/types.ts

@@ -0,0 +1,71 @@
+export type DidPlcString = `did:plc:${string}`;
+
+export type DidKeyString = `did:key:${string}`;
+
+export interface UnsignedLegacyCreateOperation {
+	type: 'create';
+	prev: null;
+	signingKey: DidKeyString;
+	recoveryKey: DidKeyString;
+	handle: string;
+	service: string;
+}
+
+export interface LegacyCreateOperation extends UnsignedLegacyCreateOperation {
+	sig: string;
+}
+
+export interface Service {
+	type: string;
+	endpoint: string;
+}
+
+export interface UnsignedOperation {
+	type: 'plc_operation';
+	prev: string | null;
+	alsoKnownAs: string[];
+	rotationKeys: DidKeyString[];
+	verificationMethods: Record<string, DidKeyString>;
+	services: Record<string, Service>;
+}
+
+export interface Operation extends UnsignedOperation {
+	sig: string;
+}
+
+export interface UnsignedTombstone {
+	type: 'plc_tombstone';
+	prev: string;
+}
+
+export interface Tombstone extends UnsignedTombstone {
+	sig: string;
+}
+
+export type CompatibleOperation = Operation | LegacyCreateOperation;
+
+export type CompatibleOperationOrTombstone = CompatibleOperation | Tombstone;
+
+export type OperationOrTombstone = Operation | Tombstone;
+
+export type OperationLog = [genesis: CompatibleOperation, ...OperationOrTombstone[]];
+
+export interface IndexedEntry<T extends CompatibleOperationOrTombstone = CompatibleOperationOrTombstone> {
+	did: DidPlcString;
+	operation: T;
+	cid: string;
+	nullified: boolean;
+	createdAt: string;
+}
+
+export interface IndexedEntryWithSigner<
+	T extends CompatibleOperationOrTombstone = CompatibleOperationOrTombstone,
+> extends IndexedEntry<T> {
+	allowedSigners: DidKeyString[];
+	signedBy: DidKeyString;
+}
+
+export type IndexedEntryLog = [
+	genesis: IndexedEntry<CompatibleOperation>,
+	...IndexedEntry<OperationOrTombstone>[],
+];