@atcute/repo 0.1.0

package/lib/utils/queue.ts

@@ -0,0 +1,148 @@
+interface Node<T> {
+	value: T;
+	next: Node<T> | undefined;
+}
+
+const createNode = <T>(value: T, next: Node<T> | undefined): Node<T> => {
+	return { value, next };
+};
+
+/** a queue data structure (fifo) */
+class Queue<T> implements Iterable<T> {
+	#head: Node<T> | undefined;
+	#tail: Node<T> | undefined;
+	#size: number = 0;
+
+	/** size of the queue */
+	get size(): number {
+		return this.#size;
+	}
+
+	/**
+	 * clear the queue
+	 */
+	clear(): void {
+		this.#head = undefined;
+		this.#tail = undefined;
+		this.#size = 0;
+	}
+
+	/**
+	 * adds a value to the end of the queue
+	 * @param value value to add
+	 * @returns the queue instance
+	 */
+	enqueue(value: T): this {
+		const tail = this.#tail;
+		const node = createNode(value, undefined);
+
+		if (tail !== undefined) {
+			tail.next = node;
+		} else {
+			this.#head = node;
+		}
+
+		this.#tail = node;
+		this.#size++;
+		return this;
+	}
+
+	/**
+	 * adds a value to the front of the queue
+	 * @param value value to add
+	 * @returns the queue instance
+	 */
+	enqueueFront(value: T): this {
+		const head = this.#head;
+		const node = createNode(value, head);
+
+		if (head === undefined) {
+			this.#tail = node;
+		}
+
+		this.#head = node;
+		this.#size++;
+		return this;
+	}
+
+	/**
+	 * removes the first value from the queue
+	 * @returns first queued value, or undefined if empty
+	 */
+	dequeue(): T | undefined {
+		const head = this.#head;
+		if (!head) {
+			return;
+		}
+
+		const next = head.next;
+
+		this.#head = next;
+		if (next === undefined) {
+			this.#tail = undefined;
+		}
+
+		this.#size--;
+		return head.value;
+	}
+
+	/**
+	 * get the first value without removing from queue
+	 * @returns first queued value, or undefined if empty
+	 */
+	peek(): T | undefined {
+		return this.#head?.value;
+	}
+
+	/**
+	 * returns an iterator that drains all values from the queue
+	 */
+	drain(): IterableIterator<T, undefined, undefined> {
+		// deno-lint-ignore no-this-alias
+		const self = this;
+
+		return {
+			next() {
+				const head = self.#head;
+				if (!head) {
+					return { done: true, value: undefined };
+				}
+
+				const next = head.next;
+
+				self.#head = next;
+				if (next === undefined) {
+					self.#tail = undefined;
+				}
+
+				self.#size--;
+				return { done: false, value: head.value };
+			},
+			[Symbol.iterator]() {
+				return this;
+			},
+		};
+	}
+
+	/**
+	 * iterates over the queue without draining
+	 */
+	[Symbol.iterator](): Iterator<T, undefined, undefined> {
+		let current = this.#head;
+
+		return {
+			next() {
+				if (current === undefined) {
+					return { done: true, value: undefined };
+				}
+
+				const value = current.value;
+				current = current.next;
+
+				return { done: false, value: value };
+			},
+		};
+	}
+}
+
+export default Queue;

package/lib/utils.ts

@@ -0,0 +1,7 @@
+export const assert: {
+	(condition: boolean, message: string): asserts condition;
+} = (condition, message) => {
+	if (!condition) {
+		throw new Error(message);
+	}
+};

package/lib/verify.ts

@@ -0,0 +1,244 @@
+import * as CAR from '@atcute/car';
+import * as CBOR from '@atcute/cbor';
+import * as CID from '@atcute/cid';
+import type { PublicKey } from '@atcute/crypto';
+import type { AtprotoDid } from '@atcute/lexicons/syntax';
+import { isNodeData, type NodeData } from '@atcute/mst';
+import { decodeUtf8From, encodeUtf8, toSha256 } from '@atcute/uint8array';
+
+import { isCommit, type Commit } from './types.js';
+
+type BlockMap = Map<string, Uint8Array>;
+
+export interface VerifiedRecord {
+	/** CID of the record */
+	cid: string;
+	/** Record data */
+	record: unknown;
+}
+
+export interface VerifyRecordOptions {
+	did?: AtprotoDid;
+	collection: string;
+	rkey: string;
+	publicKey?: PublicKey;
+	carBytes: Uint8Array;
+}
+
+export const verifyRecord = async ({
+	did,
+	collection,
+	rkey,
+	publicKey,
+	carBytes,
+}: VerifyRecordOptions): Promise<VerifiedRecord> => {
+	// read the car
+	let blockmap: BlockMap;
+	let commit: Commit;
+	{
+		const reader = CAR.fromUint8Array(carBytes);
+		if (reader.header.data.roots.length !== 1) {
+			throw new Error(`car must have exactly one root`);
+		}
+
+		blockmap = new Map();
+		for (const entry of reader) {
+			const cidString = CID.toString(entry.cid);
+
+			// Verify that `bytes` matches its associated CID
+			const expectedCid = CID.toString(await CID.create(entry.cid.codec as 85 | 113, entry.bytes));
+			if (cidString !== expectedCid) {
+				throw new Error(`cid does not match bytes`);
+			}
+
+			blockmap.set(cidString, entry.bytes);
+		}
+
+		if (blockmap.size === 0) {
+			throw new Error(`car must have at least one block`);
+		}
+
+		commit = readBlock(blockmap, reader.header.data.roots[0].$link, isCommit);
+	}
+
+	// verify did in commit matches the did
+	if (did !== undefined && commit.did !== did) {
+		throw new Error(`did in commit does not match expected did`);
+	}
+
+	// verify signature contained in commit is valid (if publicKey provided)
+	if (publicKey) {
+		const { sig, ...unsigned } = commit;
+
+		const data = CBOR.encode(unsigned);
+		const valid = await publicKey.verify(
+			CBOR.fromBytes(sig) as Uint8Array<ArrayBuffer>,
+			data as Uint8Array<ArrayBuffer>,
+		);
+
+		if (!valid) {
+			throw new Error(`signature verification failed`);
+		}
+	}
+
+	// find and verify the record in the commit
+	const targetKey = `${collection}/${rkey}`;
+	const { found } = await dfs(blockmap, commit.data.$link, targetKey);
+	if (!found) {
+		throw new Error(`could not find record in car`);
+	}
+
+	return {
+		cid: found.cid,
+		record: found.record,
+	};
+};
+
+const readBlock = <T>(blockmap: BlockMap, cid: string, validate: (value: unknown) => value is T): T => {
+	const bytes = blockmap.get(cid);
+	if (!bytes) {
+		throw new Error(`cid not found in blockmap; cid=${cid}`);
+	}
+
+	const decoded = CBOR.decode(bytes);
+	if (!validate(decoded)) {
+		throw new Error(`validation failed for cid=${cid}`);
+	}
+
+	return decoded;
+};
+
+interface DfsResult {
+	found: false | { cid: string; record: unknown };
+	min?: string;
+	max?: string;
+	depth?: number;
+}
+
+const dfs = async (
+	blockmap: BlockMap,
+	from: string | undefined,
+	targetKey: string,
+	visited = new Set<string>(),
+): Promise<DfsResult> => {
+	// If there's no starting point, return empty state
+	if (from == null) {
+		return { found: false };
+	}
+
+	// Check for cycles
+	{
+		if (visited.has(from)) {
+			throw new Error(`cycle detected; cid=${from}`);
+		}
+
+		visited.add(from);
+	}
+
+	// Get the block data
+	let node: NodeData;
+	{
+		const bytes = blockmap.get(from);
+		if (!bytes) {
+			return { found: false };
+		}
+
+		const decoded = CBOR.decode(bytes);
+		if (!isNodeData(decoded)) {
+			throw new Error(`invalid mst node; cid=${from}`);
+		}
+
+		node = decoded;
+	}
+
+	// Recursively process the left child
+	const left = await dfs(blockmap, node.l?.$link, targetKey, visited);
+
+	let key = '';
+	let found = left.found;
+	let depth: number | undefined;
+	let firstKey: string | undefined;
+	let lastKey: string | undefined;
+
+	// Process all entries in this node
+	for (const entry of node.e) {
+		// Construct the key by truncating and appending
+		key = key.substring(0, entry.p) + decodeUtf8From(CBOR.fromBytes(entry.k));
+
+		// Check if this is our target key
+		if (key === targetKey) {
+			const recordBytes = blockmap.get(entry.v.$link);
+			if (recordBytes) {
+				const record = CBOR.decode(recordBytes);
+				found = { cid: entry.v.$link, record };
+			}
+		}
+
+		// Calculate depth based on leading zeros in the hash
+		const keyDigest = await toSha256(encodeUtf8(key));
+		let zeroCount = 0;
+
+		outerLoop: for (const byte of keyDigest) {
+			for (let bit = 7; bit >= 0; bit--) {
+				if (((byte >> bit) & 1) !== 0) {
+					break outerLoop;
+				}
+				zeroCount++;
+			}
+		}
+
+		const thisDepth = Math.floor(zeroCount / 2);
+
+		// Ensure consistent depth
+		if (depth === undefined) {
+			depth = thisDepth;
+		} else if (depth !== thisDepth) {
+			throw new Error(`node has entries with different depths; cid=${from}`);
+		}
+
+		// Track first and last keys
+		if (lastKey === undefined) {
+			firstKey = key;
+			lastKey = key;
+		}
+
+		// Check key ordering
+		if (lastKey > key) {
+			throw new Error(`entries are out of order; cid=${from}`);
+		}
+
+		// Process right child
+		const right = await dfs(blockmap, entry.t?.$link, targetKey, visited);
+
+		// Check ordering with right subtree
+		if (right.min && right.min < lastKey) {
+			throw new Error(`entries are out of order; cid=${from}`);
+		}
+
+		found = found || right.found;
+
+		// Check depth ordering
+		if (left.depth !== undefined && left.depth >= thisDepth) {
+			throw new Error(`depths are out of order; cid=${from}`);
+		}
+
+		if (right.depth !== undefined && right.depth >= thisDepth) {
+			throw new Error(`depths are out of order; cid=${from}`);
+		}
+
+		// Update last key based on right subtree
+		lastKey = right.max ?? key;
+	}
+
+	// Check ordering with left subtree
+	if (left.max && firstKey && left.max > firstKey) {
+		throw new Error(`entries are out of order; cid=${from}`);
+	}
+
+	return {
+		found,
+		min: firstKey,
+		max: lastKey,
+		depth,
+	};
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "type": "module",
+  "name": "@atcute/repo",
+  "version": "0.1.0",
+  "description": "AT Protocol repository decoder for AT Protocol.",
+  "keywords": [
+    "atproto",
+    "repo"
+  ],
+  "license": "0BSD",
+  "repository": {
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/utilities/repo"
+  },
+  "files": [
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.2.4",
+    "@atcute/multibase": "^1.1.6"
+  },
+  "dependencies": {
+    "@atcute/car": "^5.0.0",
+    "@atcute/cbor": "^2.2.7",
+    "@atcute/cid": "^2.2.6",
+    "@atcute/crypto": "^2.2.5",
+    "@atcute/lexicons": "^1.2.2",
+    "@atcute/mst": "^0.1.0",
+    "@atcute/uint8array": "^1.0.5"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "vitest run --coverage",
+    "prepublish": "rm -rf dist; pnpm run build"
+  }
+}