@atcute/lexicon-resolver 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+import type { LexiconDoc } from '@atcute/lexicon-doc';
+import type { AtprotoDid, Nsid } from '@atcute/lexicons/syntax';
+export interface ResolveLexiconAuthorityOptions {
+    signal?: AbortSignal;
+    noCache?: boolean;
+}
+export interface LexiconAuthorityResolver {
+    resolve(nsid: Nsid, options?: ResolveLexiconAuthorityOptions): Promise<AtprotoDid>;
+}
+export interface ResolveLexiconRecordOptions {
+    signal?: AbortSignal;
+    noCache?: boolean;
+}
+export interface ResolvedSchema {
+    /** AT-URI of the lexicon record */
+    uri: string;
+    /** CID of the lexicon record */
+    cid: string;
+    /** Parsed lexicon schema document */
+    schema: LexiconDoc;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+import type { Nsid } from '@atcute/lexicons/syntax';
+export declare const nsidToLookupDomain: (nsid: Nsid) => string;

package/dist/utils.js

@@ -0,0 +1,6 @@
+export const nsidToLookupDomain = (nsid) => {
+    const segments = nsid.split('.');
+    // Remove the last segment (method name) and reverse to get domain format
+    return segments.slice(0, -1).reverse().join('.');
+};
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../lib/utils.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAU,EAAU,EAAE;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,yEAAyE;IACzE,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC,CAAC"}

package/lib/authority/doh-json.ts

@@ -0,0 +1,142 @@
+import * as v from '@badrap/valita';
+
+import { isAtprotoDid } from '@atcute/identity';
+import type { AtprotoDid, Nsid } from '@atcute/lexicons/syntax';
+import { isResponseOk, parseResponseAsJson, pipe, validateJsonWith } from '@atcute/util-fetch';
+
+import * as err from '../errors.js';
+import type { LexiconAuthorityResolver, ResolveLexiconAuthorityOptions } from '../types.js';
+import { nsidToLookupDomain } from '../utils.js';
+
+const uint32 = v.number().assert((input) => Number.isInteger(input) && input >= 0 && input <= 2 ** 32 - 1);
+
+const question = v.object({
+	name: v.string(),
+	type: v.literal(16), // TXT
+});
+
+const answer = v.object({
+	name: v.string(),
+	type: v.literal(16), // TXT
+	TTL: uint32,
+	data: v.string().chain((input) => {
+		return v.ok(input.replace(/^"|"$/g, '').replace(/\\"/g, '"'));
+	}),
+});
+
+const authority = v.object({
+	name: v.string(),
+	type: uint32,
+	TTL: uint32,
+	data: v.string(),
+});
+
+const result = v.object({
+	/** DNS response code */
+	Status: uint32,
+	/** Whether response is truncated */
+	TC: v.boolean(),
+	/** Whether recursive desired bit is set, always true for Google and Cloudflare DoH */
+	RD: v.boolean(),
+	/** Whether recursive available bit is set, always true for Google and Cloudflare DoH */
+	RA: v.boolean(),
+	/** Whether response data was validated with DNSSEC */
+	AD: v.boolean(),
+	/** Whether client asked to disable DNSSEC validation */
+	CD: v.boolean(),
+	/** Requested records */
+	Question: v.tuple([question]),
+	/** Answers */
+	Answer: v.array(answer).optional(() => []),
+	/** Authority */
+	Authority: v.array(authority).optional(),
+	/** Comment from the DNS server */
+	Comment: v.string().optional(),
+});
+
+const SUBDOMAIN = '_lexicon';
+const PREFIX = 'did=';
+
+const fetchDohJsonHandler = pipe(
+	isResponseOk,
+	parseResponseAsJson(/^application\/(dns-)?json$/, 16 * 1024),
+	validateJsonWith(result, { mode: 'passthrough' }),
+);
+
+export interface DohJsonLexiconAuthorityResolverOptions {
+	dohUrl: string;
+	fetch?: typeof fetch;
+}
+
+export class DohJsonLexiconAuthorityResolver implements LexiconAuthorityResolver {
+	readonly dohUrl: string;
+	#fetch: typeof fetch;
+
+	constructor({ dohUrl, fetch: fetchThis = fetch }: DohJsonLexiconAuthorityResolverOptions) {
+		this.dohUrl = dohUrl;
+		this.#fetch = fetchThis;
+	}
+
+	async resolve(nsid: Nsid, options?: ResolveLexiconAuthorityOptions): Promise<AtprotoDid> {
+		const lookupDomain = nsidToLookupDomain(nsid);
+
+		let json: v.Infer<typeof result>;
+
+		try {
+			const url = new URL(this.dohUrl);
+			url.searchParams.set('name', `${SUBDOMAIN}.${lookupDomain}`);
+			url.searchParams.set('type', 'TXT');
+
+			const response = await (0, this.#fetch)(url, {
+				signal: options?.signal,
+				cache: options?.noCache ? 'no-cache' : undefined,
+				headers: { accept: 'application/dns-json' },
+			});
+
+			const handled = await fetchDohJsonHandler(response);
+
+			json = handled.json;
+		} catch (cause) {
+			throw new err.FailedAuthorityResolutionError(nsid, { cause });
+		}
+
+		const status = json.Status;
+		const answers = json.Answer;
+
+		if (status !== 0 /* NOERROR */) {
+			if (status === 3 /* NXDOMAIN */) {
+				throw new err.AuthorityNotFoundError(nsid);
+			}
+
+			throw new err.FailedAuthorityResolutionError(nsid, {
+				cause: new TypeError(`dns returned ${status}`),
+			});
+		}
+
+		for (let i = 0, il = answers.length; i < il; i++) {
+			const answer = answers[i];
+			const data = answer.data;
+
+			if (!data.startsWith(PREFIX)) {
+				continue;
+			}
+
+			for (let j = i + 1; j < il; j++) {
+				const data = answers[j].data;
+				if (data.startsWith(PREFIX)) {
+					throw new err.AmbiguousAuthorityError(nsid);
+				}
+			}
+
+			const did = data.slice(PREFIX.length);
+			if (!isAtprotoDid(did)) {
+				throw new err.InvalidResolvedAuthorityError(nsid, did);
+			}
+
+			return did;
+		}
+
+		// theoretically this shouldn't happen, it should've returned NXDOMAIN
+		throw new err.AuthorityNotFoundError(nsid);
+	}
+}

package/lib/constants.ts

@@ -0,0 +1 @@
+export const LEXICON_SCHEMA_COLLECTION = 'com.atproto.lexicon.schema';

package/lib/errors.ts

@@ -0,0 +1,85 @@
+import type { Nsid } from '@atcute/lexicons/syntax';
+
+// #region Lexicon authority resolution errors
+export class LexiconAuthorityResolutionError extends Error {
+	override name = 'LexiconAuthorityResolutionError';
+}
+
+export class AuthorityNotFoundError extends LexiconAuthorityResolutionError {
+	override name = 'AuthorityNotFoundError';
+
+	constructor(public nsid: Nsid) {
+		super(`lexicon authority not found; nsid=${nsid}`);
+	}
+}
+
+export class FailedAuthorityResolutionError extends LexiconAuthorityResolutionError {
+	override name = 'FailedAuthorityResolutionError';
+
+	constructor(
+		public nsid: Nsid,
+		options?: ErrorOptions,
+	) {
+		super(`failed to resolve lexicon authority; nsid=${nsid}`, options);
+	}
+}
+
+export class InvalidResolvedAuthorityError extends LexiconAuthorityResolutionError {
+	override name = 'InvalidResolvedAuthorityError';
+
+	constructor(
+		public nsid: Nsid,
+		public did: string,
+	) {
+		super(`lexicon authority returned invalid did; nsid=${nsid}; did=${did}`);
+	}
+}
+
+export class AmbiguousAuthorityError extends LexiconAuthorityResolutionError {
+	override name = 'AmbiguousAuthorityError';
+
+	constructor(public nsid: Nsid) {
+		super(`lexicon authority returned multiple did values; nsid=${nsid}`);
+	}
+}
+// #endregion
+
+// #region Lexicon resolution errors
+export class LexiconResolutionError extends Error {
+	override name = 'LexiconResolutionError';
+}
+
+
+export class FailedLexiconResolutionError extends LexiconResolutionError {
+	override name = 'FailedLexiconResolutionError';
+
+	constructor(
+		public nsid: Nsid,
+		options?: ErrorOptions,
+	) {
+		super(`failed to resolve lexicon; nsid=${nsid}`, options);
+	}
+}
+
+export class InvalidLexiconSchemaError extends LexiconResolutionError {
+	override name = 'InvalidLexiconSchemaError';
+
+	constructor(
+		public nsid: Nsid,
+		options?: ErrorOptions,
+	) {
+		super(`invalid lexicon schema; nsid=${nsid}`, options);
+	}
+}
+
+export class InvalidLexiconProofError extends LexiconResolutionError {
+	override name = 'InvalidLexiconProofError';
+
+	constructor(
+		public nsid: Nsid,
+		options?: ErrorOptions,
+	) {
+		super(`invalid lexicon record proof; nsid=${nsid}`, options);
+	}
+}
+// #endregion

package/lib/index.ts

@@ -0,0 +1,5 @@
+export * from './authority/doh-json.js';
+export * from './errors.js';
+export * from './schemas/xrpc.js';
+export * from './types.js';
+export * from './utils.js';

package/lib/schemas/verify.ts

@@ -0,0 +1,245 @@
+import * as CAR from '@atcute/car';
+import { CarReader } from '@atcute/car/v4';
+import * as CBOR from '@atcute/cbor';
+import * as CID from '@atcute/cid';
+import { type FoundPublicKey, getPublicKeyFromDidController, verifySig } from '@atcute/crypto';
+import { type DidDocument, getAtprotoVerificationMaterial } from '@atcute/identity';
+import { type AtprotoDid } from '@atcute/lexicons/syntax';
+import { toSha256 } from '@atcute/uint8array';
+
+export interface VerifiedRecord {
+	/** AT-URI of the record */
+	uri: string;
+	/** CID of the record */
+	cid: string;
+	/** Record data */
+	record: unknown;
+}
+
+export interface VerifyRecordOptions {
+	did: AtprotoDid;
+	collection: string;
+	rkey: string;
+	didDocument: DidDocument;
+	carBytes: Uint8Array;
+}
+
+export const verifyRecord = async ({
+	did,
+	collection,
+	rkey,
+	didDocument,
+	carBytes,
+}: VerifyRecordOptions): Promise<VerifiedRecord> => {
+	// grab public key from did document
+	let publicKey: FoundPublicKey;
+	{
+		const controller = getAtprotoVerificationMaterial(didDocument);
+		if (!controller) {
+			throw new Error(`did document does not contain verification material`);
+		}
+
+		publicKey = getPublicKeyFromDidController(controller);
+	}
+
+	// read the car
+	let blockmap: CAR.BlockMap;
+	let commit: CAR.Commit;
+	{
+		const reader = CarReader.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);
+		}
+
+		if (blockmap.size === 0) {
+			throw new Error(`car must have at least one block`);
+		}
+
+		commit = CAR.readBlock(blockmap, reader.header.data.roots[0], CAR.isCommit);
+	}
+
+	// verify did in commit matches the did
+	if (commit.did !== did) {
+		throw new Error(`did in commit does not match expected did`);
+	}
+
+	// verify signature contained in commit is valid
+	{
+		const { sig, ...unsigned } = commit;
+
+		const data = CBOR.encode(unsigned);
+		const valid = await verifySig(
+			publicKey,
+			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 {
+		uri: `at://${did}/${collection}/${rkey}`,
+		cid: found.cid,
+		record: found.record,
+	};
+};
+
+interface DfsResult {
+	found: false | { cid: string; record: unknown };
+	min?: string;
+	max?: string;
+	depth?: number;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+const dfs = async (
+	blockmap: CAR.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: CAR.MstNode;
+	{
+		const entry = blockmap.get(from);
+		if (!entry) {
+			return { found: false };
+		}
+
+		const decoded = CBOR.decode(entry.bytes);
+		if (!CAR.isMstNode(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) + decoder.decode(CBOR.fromBytes(entry.k));
+
+		// Check if this is our target key
+		if (key === targetKey) {
+			const recordBlock = blockmap.get(entry.v.$link);
+			if (recordBlock) {
+				const record = CBOR.decode(recordBlock.bytes);
+				found = { cid: entry.v.$link, record };
+			}
+		}
+
+		// Calculate depth based on leading zeros in the hash
+		const keyDigest = await toSha256(encoder.encode(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/lib/schemas/xrpc.ts

@@ -0,0 +1,107 @@
+import { getPdsEndpoint } from '@atcute/identity';
+import type { DidDocumentResolver } from '@atcute/identity-resolver';
+import { lexiconDoc, type LexiconDoc } from '@atcute/lexicon-doc';
+import type { AtprotoDid, Nsid } from '@atcute/lexicons/syntax';
+
+import { FailedResponseError } from '@atcute/util-fetch';
+
+import { LEXICON_SCHEMA_COLLECTION } from '../constants.js';
+import * as err from '../errors.js';
+import type { ResolvedSchema, ResolveLexiconRecordOptions } from '../types.js';
+import { verifyRecord, type VerifiedRecord } from './verify.js';
+
+export interface LexiconSchemaResolverOptions {
+	didDocumentResolver: DidDocumentResolver;
+	fetch?: typeof fetch;
+}
+
+export class LexiconSchemaResolver {
+	readonly didDocumentResolver: DidDocumentResolver;
+	#fetch: typeof fetch;
+
+	constructor({ didDocumentResolver, fetch: fetchThis = fetch }: LexiconSchemaResolverOptions) {
+		this.didDocumentResolver = didDocumentResolver;
+		this.#fetch = fetchThis;
+	}
+
+	async resolve(
+		authority: AtprotoDid,
+		nsid: Nsid,
+		options?: ResolveLexiconRecordOptions,
+	): Promise<ResolvedSchema> {
+		// Step 1: Resolve DID to get PDS service endpoint
+		const didDocument = await this.didDocumentResolver.resolve(authority, {
+			signal: options?.signal,
+			noCache: options?.noCache,
+		});
+
+		const pdsEndpoint = getPdsEndpoint(didDocument);
+
+		if (!pdsEndpoint) {
+			throw new err.FailedLexiconResolutionError(nsid, {
+				cause: new TypeError(`no pds service in did document; did=${authority}`),
+			});
+		}
+
+		// Step 2: Fetch the record
+		let carBytes: Uint8Array;
+		try {
+			const url = new URL('/xrpc/com.atproto.sync.getRecord', pdsEndpoint);
+			url.searchParams.set('did', authority);
+			url.searchParams.set('collection', LEXICON_SCHEMA_COLLECTION);
+			url.searchParams.set('rkey', nsid);
+
+			const response = await (0, this.#fetch)(url, {
+				signal: options?.signal,
+				cache: options?.noCache ? 'no-cache' : undefined,
+				headers: { accept: 'application/vnd.ipld.car' },
+			});
+
+			if (!response.ok) {
+				throw new FailedResponseError(response.status, `got http ${response.status}`);
+			}
+
+			carBytes = await response.bytes();
+		} catch (cause) {
+			throw new err.FailedLexiconResolutionError(nsid, { cause });
+		}
+
+		// Step 3: Verify record and extract data
+		let verifiedRecord: VerifiedRecord;
+		try {
+			verifiedRecord = await verifyRecord({
+				did: authority,
+				collection: LEXICON_SCHEMA_COLLECTION,
+				rkey: nsid,
+				didDocument,
+				carBytes,
+			});
+		} catch (cause) {
+			throw new err.InvalidLexiconProofError(nsid, { cause });
+		}
+
+		// Step 4: Parse into lexicon schema
+		const rawSchema = verifiedRecord.record;
+		if (
+			typeof rawSchema !== 'object' ||
+			rawSchema === null ||
+			(rawSchema as any).$type !== LEXICON_SCHEMA_COLLECTION ||
+			(rawSchema as any).id !== nsid
+		) {
+			throw new err.InvalidLexiconSchemaError(nsid);
+		}
+
+		let schema: LexiconDoc;
+		try {
+			schema = lexiconDoc.parse(rawSchema, { mode: 'passthrough' });
+		} catch (cause) {
+			throw new err.InvalidLexiconSchemaError(nsid, { cause });
+		}
+
+		return {
+			uri: verifiedRecord.uri,
+			cid: verifiedRecord.cid,
+			schema,
+		};
+	}
+}

package/lib/types.ts

@@ -0,0 +1,25 @@
+import type { LexiconDoc } from '@atcute/lexicon-doc';
+import type { AtprotoDid, Nsid } from '@atcute/lexicons/syntax';
+
+export interface ResolveLexiconAuthorityOptions {
+	signal?: AbortSignal;
+	noCache?: boolean;
+}
+
+export interface LexiconAuthorityResolver {
+	resolve(nsid: Nsid, options?: ResolveLexiconAuthorityOptions): Promise<AtprotoDid>;
+}
+
+export interface ResolveLexiconRecordOptions {
+	signal?: AbortSignal;
+	noCache?: boolean;
+}
+
+export interface ResolvedSchema {
+	/** AT-URI of the lexicon record */
+	uri: string;
+	/** CID of the lexicon record */
+	cid: string;
+	/** Parsed lexicon schema document */
+	schema: LexiconDoc;
+}

package/lib/utils.ts

@@ -0,0 +1,7 @@
+import type { Nsid } from '@atcute/lexicons/syntax';
+
+export const nsidToLookupDomain = (nsid: Nsid): string => {
+	const segments = nsid.split('.');
+	// Remove the last segment (method name) and reverse to get domain format
+	return segments.slice(0, -1).reverse().join('.');
+};