@atproto/lex-resolver 0.0.13 → 0.0.14

package/dist/lex-resolver.js

@@ -13,6 +13,80 @@ Object.defineProperty(exports, "NSID", { enumerable: true, get: function () { re
 const did_resolver_1 = require("@atproto-labs/did-resolver");
 const lex_resolver_error_js_1 = require("./lex-resolver-error.js");
 const index_js_1 = require("./lexicons/index.js");
+/**
+ * Resolves Lexicon documents from the AT Protocol network.
+ *
+ * The {@link LexResolver} handles the complete process of resolving a lexicon
+ * by NSID:
+ * 1. **Authority Resolution**: Looks up the `_lexicon.<authority>` DNS TXT record
+ *    to find the DID that controls lexicons for that namespace
+ * 2. **DID Resolution**: Resolves the DID document to find the PDS endpoint and
+ *    signing key
+ * 3. **Record Fetch**: Fetches the lexicon record from the PDS with cryptographic
+ *    proof verification
+ * 4. **Validation**: Validates the lexicon document structure
+ *
+ * @example Basic usage - resolve a lexicon by NSID
+ * ```typescript
+ * import { LexResolver } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * // Get a lexicon document by its NSID
+ * const result = await resolver.get('app.bsky.feed.post')
+ * console.log(result.lexicon) // The parsed lexicon document
+ * console.log(result.uri)     // AT URI where it was found
+ * console.log(result.cid)     // Content identifier for verification
+ * ```
+ *
+ * @example Two-step resolution for more control
+ * ```typescript
+ * import { LexResolver } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * // Step 1: Resolve the authority to get the AT URI
+ * const uri = await resolver.resolve('app.bsky.feed.post')
+ * console.log(uri.toString()) // 'at://did:plc:xxx/com.atproto.lexicon.schema/app.bsky.feed.post'
+ *
+ * // Step 2: Fetch the lexicon from the URI
+ * const result = await resolver.fetch(uri)
+ * console.log(result.lexicon)
+ * ```
+ *
+ * @example Using hooks for caching
+ * ```typescript
+ * import { LexResolver, LexResolverFetchResult } from '@atproto/lex-resolver'
+ *
+ * const cache = new Map<string, LexResolverFetchResult>()
+ *
+ * const resolver = new LexResolver({
+ *   hooks: {
+ *     onFetch({ uri }) {
+ *       return cache.get(uri.toString())
+ *     },
+ *     onFetchResult({ uri, cid, lexicon }) {
+ *       cache.set(uri.toString(), { cid, lexicon })
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * import { LexResolver, LexResolverError } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * try {
+ *   const result = await resolver.get('com.example.unknown')
+ * } catch (error) {
+ *   if (error instanceof LexResolverError) {
+ *     console.error(`Failed to resolve ${error.nsid}: ${error.description}`)
+ *   }
+ * }
+ * ```
+ */
 class LexResolver {
     options;
     didResolver;
@@ -20,10 +94,66 @@ class LexResolver {
         this.options = options;
         this.didResolver = (0, did_resolver_1.createDidResolver)(options);
     }
+    /**
+     * Gets a lexicon document by its NSID.
+     *
+     * This is the primary method for resolving lexicons. It combines
+     * {@link resolve} and {@link fetch} into a single operation, handling
+     * authority resolution, DID lookup, and record fetching.
+     *
+     * @param nsidStr - The NSID to resolve, either as a string or NSID object
+     * @param options - Optional DID resolution options (e.g., signal for cancellation)
+     * @returns The resolved lexicon result containing URI, CID, and lexicon document
+     * @throws {LexResolverError} If resolution fails at any stage
+     *
+     * @example
+     * ```typescript
+     * // Resolve using string NSID
+     * const result = await resolver.get('app.bsky.feed.post')
+     *
+     * // Resolve using NSID object
+     * import { NSID } from '@atproto/syntax'
+     * const nsid = NSID.from('app.bsky.feed.post')
+     * const result = await resolver.get(nsid)
+     *
+     * // With abort signal for cancellation
+     * const controller = new AbortController()
+     * const result = await resolver.get('app.bsky.feed.post', {
+     *   signal: controller.signal
+     * })
+     * ```
+     */
     async get(nsidStr, options) {
         const uri = await this.resolve(nsidStr);
         return this.fetch(uri, options);
     }
+    /**
+     * Resolves the authority for an NSID and returns the AT URI for the lexicon.
+     *
+     * This method performs the first stage of lexicon resolution:
+     * 1. Parses the NSID to extract the authority domain
+     * 2. Looks up the `_lexicon.<authority>` DNS TXT record
+     * 3. Extracts the DID from the TXT record (format: `did=<did>`)
+     * 4. Constructs the AT URI for the lexicon record
+     *
+     * Use this when you need the URI without fetching the actual document,
+     * or when you want to implement custom fetching logic.
+     *
+     * @param nsidStr - The NSID to resolve, either as a string or NSID object
+     * @returns The AT URI pointing to the lexicon record
+     * @throws {LexResolverError} If authority resolution fails (e.g., DNS lookup fails)
+     *
+     * @example
+     * ```typescript
+     * // Resolve to get the AT URI
+     * const uri = await resolver.resolve('app.bsky.feed.post')
+     * console.log(uri.toString())
+     * // Output: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/com.atproto.lexicon.schema/app.bsky.feed.post'
+     *
+     * // The URI can then be used with fetch() or stored for later use
+     * const result = await resolver.fetch(uri)
+     * ```
+     */
     async resolve(nsidStr) {
         const nsid = syntax_1.NSID.from(nsidStr);
         const did = (await this.options.hooks?.onResolveAuthority?.({ nsid })) ??
@@ -48,6 +178,39 @@ class LexResolver {
             throw new lex_resolver_error_js_1.LexResolverError(nsid, `Failed to resolve lexicon DID authority for ${nsid}`, { cause });
         }
     }
+    /**
+     * Fetches a lexicon document from a specific AT URI.
+     *
+     * This method performs the second stage of lexicon resolution:
+     * 1. Resolves the DID from the URI to find the PDS endpoint
+     * 2. Fetches the record from the PDS using `com.atproto.sync.getRecord`
+     * 3. Verifies the cryptographic proof (commit signature)
+     * 4. Validates the lexicon document structure
+     * 5. Ensures the document ID matches the URI rkey
+     *
+     * Use this when you already have an AT URI (e.g., from {@link resolve})
+     * and want to fetch the lexicon document.
+     *
+     * @param uriStr - The AT URI to fetch, either as a string or AtUri object
+     * @param options - Optional DID resolution options (e.g., signal for cancellation, noCache)
+     * @returns The resolved lexicon result containing URI, CID, and lexicon document
+     * @throws {LexResolverError} If fetching or validation fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch from a known URI
+     * const result = await resolver.fetch(
+     *   'at://did:plc:xyz/com.atproto.lexicon.schema/app.bsky.feed.post'
+     * )
+     *
+     * // Fetch with no-cache to bypass any upstream caching
+     * const result = await resolver.fetch(uri, { noCache: true })
+     *
+     * // Fetch with abort signal
+     * const controller = new AbortController()
+     * const result = await resolver.fetch(uri, { signal: controller.signal })
+     * ```
+     */
     async fetch(uriStr, options) {
         const uri = typeof uriStr === 'string' ? new syntax_1.AtUri(uriStr) : uriStr;
         const { lexicon, cid } = (await this.options.hooks?.onFetch?.({ uri })) ??

package/dist/lex-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"lex-resolver.js","sourceRoot":"","sources":["../src/lex-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["import { resolveTxt } from 'node:dns/promises'\nimport * as crypto from '@atproto/crypto'\nimport { buildAgent, xrpc } from '@atproto/lex-client'\nimport { Cid } from '@atproto/lex-data'\nimport { LexiconDocument, lexiconDocumentSchema } from '@atproto/lex-document'\nimport {\n  MST,\n  MemoryBlockstore,\n  def as repoDef,\n  readCarWithRoot,\n  verifyCommitSig,\n} from '@atproto/repo'\nimport { AtUri, NSID, NsidString } from '@atproto/syntax'\nimport {\n  AtprotoVerificationMethod,\n  CreateDidResolverOptions,\n  Did,\n  DidResolver,\n  ResolveDidOptions,\n  assertDid,\n  createDidResolver,\n  extractAtprotoData,\n} from '@atproto-labs/did-resolver'\nimport { LexResolverError } from './lex-resolver-error.js'\nimport { com } from './lexicons/index.js'\n\nexport type LexResolverResult = {\n  uri: AtUri\n  cid: Cid\n  lexicon: LexiconDocument\n}\n\nexport type LexResolverFetchResult = {\n  cid: Cid\n  lexicon: LexiconDocument\n}\n\ntype Awaitable<T> = T | Promise<T>\n\nexport type LexResolverHooks = {\n  /**\n   * Hook called before resolving a lexicon authority DID. If a DID is returned,\n   * it will be used instead of performing the default resolution. In that case,\n   * the `onResolveAuthorityResult` and `onResolveAuthorityError` hooks will\n   * not be called.\n   */\n  onResolveAuthority?(data: { nsid: NSID }): Awaitable<void | Did>\n  onResolveAuthorityResult?(data: { nsid: NSID; did: Did }): Awaitable<void>\n  onResolveAuthorityError?(data: { nsid: NSID; err: unknown }): Awaitable<void>\n\n  /**\n   * Hook called before fetching a lexicon URI. If a result is returned, it will\n   * be used instead of performing the default fetch. In that case, the\n   * `onFetchResult` and `onFetchError` hooks will not be called.\n   */\n  onFetch?(data: { uri: AtUri }): Awaitable<void | LexResolverFetchResult>\n  onFetchResult?(data: {\n    uri: AtUri\n    cid: Cid\n    lexicon: LexiconDocument\n  }): Awaitable<void>\n  onFetchError?(data: { uri: AtUri; err: unknown }): Awaitable<void>\n}\n\nexport type LexResolverOptions = CreateDidResolverOptions & {\n  hooks?: LexResolverHooks\n}\n\nexport { AtUri, type Cid, NSID }\nexport type { LexiconDocument, ResolveDidOptions }\n\nexport class LexResolver {\n  protected readonly didResolver: DidResolver<'plc' | 'web'>\n\n  constructor(protected readonly options: LexResolverOptions) {\n    this.didResolver = createDidResolver(options)\n  }\n\n  async get(\n    nsidStr: NSID | string,\n    options?: ResolveDidOptions,\n  ): Promise<LexResolverResult> {\n    const uri = await this.resolve(nsidStr)\n    return this.fetch(uri, options)\n  }\n\n  async resolve(nsidStr: NSID | string): Promise<AtUri> {\n    const nsid = NSID.from(nsidStr)\n\n    const did =\n      (await this.options.hooks?.onResolveAuthority?.({ nsid })) ??\n      (await this.resolveLexiconAuthority(nsid).then(\n        async (did) => {\n          await this.options.hooks?.onResolveAuthorityResult?.({ nsid, did })\n          return did\n        },\n        async (err) => {\n          await this.options.hooks?.onResolveAuthorityError?.({ nsid, err })\n          throw err\n        },\n      ))\n\n    return AtUri.make(did, 'com.atproto.lexicon.schema', nsid.toString())\n  }\n\n  // @TODO This class could be made compatible with browsers by making the\n  // following method abstract and/or by allowing the caller to inject a DNS\n  // resolver implementation (based on DNS-over-HTTPS or similar), instead of\n  // using the Node.js built-in resolver.\n  protected async resolveLexiconAuthority(nsid: NSID): Promise<Did> {\n    try {\n      return await getDomainTxtDid(`_lexicon.${nsid.authority}`)\n    } catch (cause) {\n      throw new LexResolverError(\n        nsid,\n        `Failed to resolve lexicon DID authority for ${nsid}`,\n        { cause },\n      )\n    }\n  }\n\n  async fetch(\n    uriStr: AtUri | string,\n    options?: ResolveDidOptions,\n  ): Promise<LexResolverResult> {\n    const uri = typeof uriStr === 'string' ? new AtUri(uriStr) : uriStr\n\n    const { lexicon, cid } =\n      (await this.options.hooks?.onFetch?.({ uri })) ??\n      (await this.fetchLexiconUri(uri, options).then(\n        async (res) => {\n          await this.options.hooks?.onFetchResult?.({ uri, ...res })\n          return res\n        },\n        async (err) => {\n          await this.options.hooks?.onFetchError?.({ uri, err })\n          throw err\n        },\n      ))\n\n    return { uri, cid, lexicon }\n  }\n\n  protected async fetchLexiconUri(\n    uri: AtUri,\n    options?: ResolveDidOptions,\n  ): Promise<LexResolverFetchResult> {\n    const { did, nsid } = parseLexiconUri(uri)\n\n    const { pds, key } = await this.didResolver\n      .resolve(did, options)\n      .then(extractAtprotoData)\n      .catch((cause) => {\n        throw new LexResolverError(\n          nsid,\n          `Failed to resolve DID document for ${did}`,\n          { cause },\n        )\n      })\n\n    if (!key || !pds || !URL.canParse(pds.serviceEndpoint)) {\n      throw new LexResolverError(\n        nsid,\n        `No atproto PDS service endpoint or signing key found in ${did} DID document`,\n      )\n    }\n\n    const agent = buildAgent({\n      service: pds.serviceEndpoint,\n      fetch: this.options.fetch,\n    })\n\n    const collection = 'com.atproto.lexicon.schema'\n    const rkey = nsid.toString()\n\n    const { cid, record } = await xrpc(agent, com.atproto.sync.getRecord, {\n      signal: options?.signal,\n      headers: options?.noCache ? { 'Cache-Control': 'no-cache' } : undefined,\n      params: { did, collection, rkey },\n    }).then(\n      ({ body }) => {\n        return verifyRecordProof(body, did, key, collection, rkey).catch(\n          (cause) => {\n            throw new LexResolverError(\n              nsid,\n              `Failed to verify Lexicon record proof at ${uri}`,\n              { cause },\n            )\n          },\n        )\n      },\n      (cause) => {\n        throw new LexResolverError(nsid, `Failed to fetch Record ${uri}`, {\n          cause,\n        })\n      },\n    )\n\n    const validationResult = lexiconDocumentSchema.safeParse(record)\n    if (!validationResult.success) {\n      throw new LexResolverError(nsid, `Invalid Lexicon document at ${uri}`, {\n        cause: validationResult.reason,\n      })\n    }\n\n    const lexicon = validationResult.value\n    if (lexicon.id !== uri.rkey) {\n      throw new LexResolverError(\n        nsid,\n        `Invalid document id \"${lexicon.id}\" at ${uri}`,\n      )\n    }\n\n    return { lexicon, cid }\n  }\n}\n\nfunction parseLexiconUri(uri: AtUri): {\n  did: Did\n  nsid: NSID\n} {\n  // Validate input URI\n  const nsid = NSID.from(uri.rkey)\n  try {\n    const did = uri.host\n    assertDid(did)\n    return { did, nsid }\n  } catch (cause) {\n    throw new LexResolverError(nsid, `URI host is not a DID ${uri}`, { cause })\n  }\n}\n\nasync function getDomainTxtDid(domain: string): Promise<Did> {\n  const didLines = (await resolveTxt(domain))\n    .map((chunks) => chunks.join(''))\n    .filter((i) => i.startsWith('did='))\n\n  if (didLines.length === 1) {\n    const did = didLines[0].slice(4)\n    assertDid(did)\n    return did\n  }\n\n  throw didLines.length > 1\n    ? new Error('Multiple DIDs found in DNS TXT records')\n    : new Error('No DID found in DNS TXT records')\n}\n\nasync function verifyRecordProof(\n  car: Uint8Array,\n  did: Did,\n  key: AtprotoVerificationMethod,\n  collection: NsidString,\n  rkey: string,\n) {\n  const { root, blocks } = await readCarWithRoot(car)\n  const blockstore = new MemoryBlockstore(blocks)\n\n  const commit = await blockstore.readObj(root, repoDef.commit)\n  if (commit.did !== did) {\n    throw new Error(`Invalid repo did: ${commit.did}`)\n  }\n\n  const signingKey = getDidKeyFromMultibase(key)\n  const validSig = await verifyCommitSig(commit, signingKey)\n  if (!validSig) {\n    throw new Error(`Invalid signature on commit: ${root.toString()}`)\n  }\n\n  const mst = MST.load(blockstore, commit.data)\n\n  const cid = await mst.get(`${collection}/${rkey}`)\n  if (!cid) throw new Error('Record not found in proof')\n\n  const record = await blockstore.readRecord(cid)\n  if (record?.$type !== collection) {\n    throw new Error(\n      `Invalid record type: expected ${collection}, got ${record?.$type}`,\n    )\n  }\n\n  return { cid, record }\n}\n\nfunction getDidKeyFromMultibase(key: AtprotoVerificationMethod) {\n  switch (key.type) {\n    case 'EcdsaSecp256r1VerificationKey2019': {\n      const keyBytes = crypto.multibaseToBytes(key.publicKeyMultibase)\n      return crypto.formatDidKey(crypto.P256_JWT_ALG, keyBytes)\n    }\n    case 'EcdsaSecp256k1VerificationKey2019': {\n      const keyBytes = crypto.multibaseToBytes(key.publicKeyMultibase)\n      return crypto.formatDidKey(crypto.SECP256K1_JWT_ALG, keyBytes)\n    }\n    case 'Multikey': {\n      const { jwtAlg, keyBytes } = crypto.parseMultikey(key.publicKeyMultibase)\n      return crypto.formatDidKey(jwtAlg, keyBytes)\n    }\n    default: {\n      // Should never happen\n      throw new Error(`Unsupported verification method type: ${key.type}`)\n    }\n  }\n}\n"]}
+{"version":3,"file":"lex-resolver.js","sourceRoot":"","sources":["../src/lex-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["import { resolveTxt } from 'node:dns/promises'\nimport * as crypto from '@atproto/crypto'\nimport { buildAgent, xrpc } from '@atproto/lex-client'\nimport { Cid } from '@atproto/lex-data'\nimport { LexiconDocument, lexiconDocumentSchema } from '@atproto/lex-document'\nimport {\n  MST,\n  MemoryBlockstore,\n  def as repoDef,\n  readCarWithRoot,\n  verifyCommitSig,\n} from '@atproto/repo'\nimport { AtUri, NSID, NsidString } from '@atproto/syntax'\nimport {\n  AtprotoVerificationMethod,\n  CreateDidResolverOptions,\n  Did,\n  DidResolver,\n  ResolveDidOptions,\n  assertDid,\n  createDidResolver,\n  extractAtprotoData,\n} from '@atproto-labs/did-resolver'\nimport { LexResolverError } from './lex-resolver-error.js'\nimport { com } from './lexicons/index.js'\n\n/**\n * Result returned when successfully resolving a lexicon document.\n *\n * Contains the full AT URI where the lexicon was found, the content-addressed\n * identifier (CID) for integrity verification, and the parsed lexicon document.\n */\nexport type LexResolverResult = {\n  /** The AT URI where the lexicon document was found */\n  uri: AtUri\n  /** Content identifier (CID) of the lexicon record for integrity verification */\n  cid: Cid\n  /** The parsed and validated lexicon document */\n  lexicon: LexiconDocument\n}\n\n/**\n * Result returned when fetching a lexicon document from a specific URI.\n *\n * This is a subset of {@link LexResolverResult} used internally and by hooks,\n * containing only the CID and lexicon document (without the URI, which is\n * already known from the fetch request).\n */\nexport type LexResolverFetchResult = {\n  /** Content identifier (CID) of the lexicon record */\n  cid: Cid\n  /** The parsed and validated lexicon document */\n  lexicon: LexiconDocument\n}\n\nexport type Awaitable<T> = T | Promise<T>\n\n/**\n * Callback hooks for customizing the lexicon resolution process.\n *\n * Hooks allow you to intercept, cache, or override the default resolution\n * behavior at various stages. Each hook can be synchronous or asynchronous.\n *\n * @example Implementing a cache with hooks\n * ```typescript\n * import { LexResolver, LexResolverHooks, LexResolverFetchResult } from '@atproto/lex-resolver'\n * import { AtUri } from '@atproto/syntax'\n *\n * const cache = new Map<string, LexResolverFetchResult>()\n *\n * const hooks: LexResolverHooks = {\n *   // Return cached result if available, bypassing network fetch\n *   onFetch({ uri }) {\n *     return cache.get(uri.toString())\n *   },\n *   // Cache successful fetches\n *   onFetchResult({ uri, cid, lexicon }) {\n *     cache.set(uri.toString(), { cid, lexicon })\n *   },\n *   // Log errors for monitoring\n *   onFetchError({ uri, err }) {\n *     console.error(`Failed to fetch ${uri}:`, err)\n *   }\n * }\n *\n * const resolver = new LexResolver({ hooks })\n * ```\n *\n * @example Overriding authority resolution for testing\n * ```typescript\n * const hooks: LexResolverHooks = {\n *   // Always resolve to a test DID\n *   onResolveAuthority({ nsid }) {\n *     if (nsid.authority === 'test.example') {\n *       return 'did:plc:test123'\n *     }\n *     // Return undefined to use default resolution\n *   }\n * }\n * ```\n */\nexport type LexResolverHooks = {\n  /**\n   * Hook called before resolving a lexicon authority DID. If a DID is returned,\n   * it will be used instead of performing the default resolution. In that case,\n   * the `onResolveAuthorityResult` and `onResolveAuthorityError` hooks will\n   * not be called.\n   *\n   * @param data - Object containing the NSID being resolved\n   * @returns A DID to use instead of default resolution, or void/undefined to proceed normally\n   */\n  onResolveAuthority?(data: { nsid: NSID }): Awaitable<void | Did>\n\n  /**\n   * Hook called after successfully resolving a lexicon authority DID.\n   *\n   * @param data - Object containing the NSID and resolved DID\n   */\n  onResolveAuthorityResult?(data: { nsid: NSID; did: Did }): Awaitable<void>\n\n  /**\n   * Hook called when authority resolution fails.\n   *\n   * @param data - Object containing the NSID and error that occurred\n   */\n  onResolveAuthorityError?(data: { nsid: NSID; err: unknown }): Awaitable<void>\n\n  /**\n   * Hook called before fetching a lexicon URI. If a result is returned, it will\n   * be used instead of performing the default fetch. In that case, the\n   * `onFetchResult` and `onFetchError` hooks will not be called.\n   *\n   * @param data - Object containing the URI being fetched\n   * @returns A fetch result to use instead of default fetch, or void/undefined to proceed normally\n   */\n  onFetch?(data: { uri: AtUri }): Awaitable<void | LexResolverFetchResult>\n\n  /**\n   * Hook called after successfully fetching a lexicon document.\n   *\n   * @param data - Object containing the URI, CID, and parsed lexicon document\n   */\n  onFetchResult?(data: {\n    uri: AtUri\n    cid: Cid\n    lexicon: LexiconDocument\n  }): Awaitable<void>\n\n  /**\n   * Hook called when fetching fails.\n   *\n   * @param data - Object containing the URI and error that occurred\n   */\n  onFetchError?(data: { uri: AtUri; err: unknown }): Awaitable<void>\n}\n\n/**\n * Configuration options for the {@link LexResolver}.\n *\n * Extends DID resolver options with lexicon-specific hooks for customizing\n * the resolution process.\n *\n * @see {@link CreateDidResolverOptions} for DID resolver configuration\n */\nexport type LexResolverOptions = CreateDidResolverOptions & {\n  /**\n   * Optional hooks for customizing the resolution process.\n   * See {@link LexResolverHooks} for available callbacks.\n   */\n  hooks?: LexResolverHooks\n}\n\nexport { AtUri, type Cid, NSID }\nexport type { LexiconDocument, ResolveDidOptions }\n\n/**\n * Resolves Lexicon documents from the AT Protocol network.\n *\n * The {@link LexResolver} handles the complete process of resolving a lexicon\n * by NSID:\n * 1. **Authority Resolution**: Looks up the `_lexicon.<authority>` DNS TXT record\n *    to find the DID that controls lexicons for that namespace\n * 2. **DID Resolution**: Resolves the DID document to find the PDS endpoint and\n *    signing key\n * 3. **Record Fetch**: Fetches the lexicon record from the PDS with cryptographic\n *    proof verification\n * 4. **Validation**: Validates the lexicon document structure\n *\n * @example Basic usage - resolve a lexicon by NSID\n * ```typescript\n * import { LexResolver } from '@atproto/lex-resolver'\n *\n * const resolver = new LexResolver({})\n *\n * // Get a lexicon document by its NSID\n * const result = await resolver.get('app.bsky.feed.post')\n * console.log(result.lexicon) // The parsed lexicon document\n * console.log(result.uri)     // AT URI where it was found\n * console.log(result.cid)     // Content identifier for verification\n * ```\n *\n * @example Two-step resolution for more control\n * ```typescript\n * import { LexResolver } from '@atproto/lex-resolver'\n *\n * const resolver = new LexResolver({})\n *\n * // Step 1: Resolve the authority to get the AT URI\n * const uri = await resolver.resolve('app.bsky.feed.post')\n * console.log(uri.toString()) // 'at://did:plc:xxx/com.atproto.lexicon.schema/app.bsky.feed.post'\n *\n * // Step 2: Fetch the lexicon from the URI\n * const result = await resolver.fetch(uri)\n * console.log(result.lexicon)\n * ```\n *\n * @example Using hooks for caching\n * ```typescript\n * import { LexResolver, LexResolverFetchResult } from '@atproto/lex-resolver'\n *\n * const cache = new Map<string, LexResolverFetchResult>()\n *\n * const resolver = new LexResolver({\n *   hooks: {\n *     onFetch({ uri }) {\n *       return cache.get(uri.toString())\n *     },\n *     onFetchResult({ uri, cid, lexicon }) {\n *       cache.set(uri.toString(), { cid, lexicon })\n *     }\n *   }\n * })\n * ```\n *\n * @example Error handling\n * ```typescript\n * import { LexResolver, LexResolverError } from '@atproto/lex-resolver'\n *\n * const resolver = new LexResolver({})\n *\n * try {\n *   const result = await resolver.get('com.example.unknown')\n * } catch (error) {\n *   if (error instanceof LexResolverError) {\n *     console.error(`Failed to resolve ${error.nsid}: ${error.description}`)\n *   }\n * }\n * ```\n */\nexport class LexResolver {\n  protected readonly didResolver: DidResolver<'plc' | 'web'>\n\n  constructor(protected readonly options: LexResolverOptions) {\n    this.didResolver = createDidResolver(options)\n  }\n\n  /**\n   * Gets a lexicon document by its NSID.\n   *\n   * This is the primary method for resolving lexicons. It combines\n   * {@link resolve} and {@link fetch} into a single operation, handling\n   * authority resolution, DID lookup, and record fetching.\n   *\n   * @param nsidStr - The NSID to resolve, either as a string or NSID object\n   * @param options - Optional DID resolution options (e.g., signal for cancellation)\n   * @returns The resolved lexicon result containing URI, CID, and lexicon document\n   * @throws {LexResolverError} If resolution fails at any stage\n   *\n   * @example\n   * ```typescript\n   * // Resolve using string NSID\n   * const result = await resolver.get('app.bsky.feed.post')\n   *\n   * // Resolve using NSID object\n   * import { NSID } from '@atproto/syntax'\n   * const nsid = NSID.from('app.bsky.feed.post')\n   * const result = await resolver.get(nsid)\n   *\n   * // With abort signal for cancellation\n   * const controller = new AbortController()\n   * const result = await resolver.get('app.bsky.feed.post', {\n   *   signal: controller.signal\n   * })\n   * ```\n   */\n  async get(\n    nsidStr: NSID | string,\n    options?: ResolveDidOptions,\n  ): Promise<LexResolverResult> {\n    const uri = await this.resolve(nsidStr)\n    return this.fetch(uri, options)\n  }\n\n  /**\n   * Resolves the authority for an NSID and returns the AT URI for the lexicon.\n   *\n   * This method performs the first stage of lexicon resolution:\n   * 1. Parses the NSID to extract the authority domain\n   * 2. Looks up the `_lexicon.<authority>` DNS TXT record\n   * 3. Extracts the DID from the TXT record (format: `did=<did>`)\n   * 4. Constructs the AT URI for the lexicon record\n   *\n   * Use this when you need the URI without fetching the actual document,\n   * or when you want to implement custom fetching logic.\n   *\n   * @param nsidStr - The NSID to resolve, either as a string or NSID object\n   * @returns The AT URI pointing to the lexicon record\n   * @throws {LexResolverError} If authority resolution fails (e.g., DNS lookup fails)\n   *\n   * @example\n   * ```typescript\n   * // Resolve to get the AT URI\n   * const uri = await resolver.resolve('app.bsky.feed.post')\n   * console.log(uri.toString())\n   * // Output: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/com.atproto.lexicon.schema/app.bsky.feed.post'\n   *\n   * // The URI can then be used with fetch() or stored for later use\n   * const result = await resolver.fetch(uri)\n   * ```\n   */\n  async resolve(nsidStr: NSID | string): Promise<AtUri> {\n    const nsid = NSID.from(nsidStr)\n\n    const did =\n      (await this.options.hooks?.onResolveAuthority?.({ nsid })) ??\n      (await this.resolveLexiconAuthority(nsid).then(\n        async (did) => {\n          await this.options.hooks?.onResolveAuthorityResult?.({ nsid, did })\n          return did\n        },\n        async (err) => {\n          await this.options.hooks?.onResolveAuthorityError?.({ nsid, err })\n          throw err\n        },\n      ))\n\n    return AtUri.make(did, 'com.atproto.lexicon.schema', nsid.toString())\n  }\n\n  // @TODO This class could be made compatible with browsers by making the\n  // following method abstract and/or by allowing the caller to inject a DNS\n  // resolver implementation (based on DNS-over-HTTPS or similar), instead of\n  // using the Node.js built-in resolver.\n  protected async resolveLexiconAuthority(nsid: NSID): Promise<Did> {\n    try {\n      return await getDomainTxtDid(`_lexicon.${nsid.authority}`)\n    } catch (cause) {\n      throw new LexResolverError(\n        nsid,\n        `Failed to resolve lexicon DID authority for ${nsid}`,\n        { cause },\n      )\n    }\n  }\n\n  /**\n   * Fetches a lexicon document from a specific AT URI.\n   *\n   * This method performs the second stage of lexicon resolution:\n   * 1. Resolves the DID from the URI to find the PDS endpoint\n   * 2. Fetches the record from the PDS using `com.atproto.sync.getRecord`\n   * 3. Verifies the cryptographic proof (commit signature)\n   * 4. Validates the lexicon document structure\n   * 5. Ensures the document ID matches the URI rkey\n   *\n   * Use this when you already have an AT URI (e.g., from {@link resolve})\n   * and want to fetch the lexicon document.\n   *\n   * @param uriStr - The AT URI to fetch, either as a string or AtUri object\n   * @param options - Optional DID resolution options (e.g., signal for cancellation, noCache)\n   * @returns The resolved lexicon result containing URI, CID, and lexicon document\n   * @throws {LexResolverError} If fetching or validation fails\n   *\n   * @example\n   * ```typescript\n   * // Fetch from a known URI\n   * const result = await resolver.fetch(\n   *   'at://did:plc:xyz/com.atproto.lexicon.schema/app.bsky.feed.post'\n   * )\n   *\n   * // Fetch with no-cache to bypass any upstream caching\n   * const result = await resolver.fetch(uri, { noCache: true })\n   *\n   * // Fetch with abort signal\n   * const controller = new AbortController()\n   * const result = await resolver.fetch(uri, { signal: controller.signal })\n   * ```\n   */\n  async fetch(\n    uriStr: AtUri | string,\n    options?: ResolveDidOptions,\n  ): Promise<LexResolverResult> {\n    const uri = typeof uriStr === 'string' ? new AtUri(uriStr) : uriStr\n\n    const { lexicon, cid } =\n      (await this.options.hooks?.onFetch?.({ uri })) ??\n      (await this.fetchLexiconUri(uri, options).then(\n        async (res) => {\n          await this.options.hooks?.onFetchResult?.({ uri, ...res })\n          return res\n        },\n        async (err) => {\n          await this.options.hooks?.onFetchError?.({ uri, err })\n          throw err\n        },\n      ))\n\n    return { uri, cid, lexicon }\n  }\n\n  protected async fetchLexiconUri(\n    uri: AtUri,\n    options?: ResolveDidOptions,\n  ): Promise<LexResolverFetchResult> {\n    const { did, nsid } = parseLexiconUri(uri)\n\n    const { pds, key } = await this.didResolver\n      .resolve(did, options)\n      .then(extractAtprotoData)\n      .catch((cause) => {\n        throw new LexResolverError(\n          nsid,\n          `Failed to resolve DID document for ${did}`,\n          { cause },\n        )\n      })\n\n    if (!key || !pds || !URL.canParse(pds.serviceEndpoint)) {\n      throw new LexResolverError(\n        nsid,\n        `No atproto PDS service endpoint or signing key found in ${did} DID document`,\n      )\n    }\n\n    const agent = buildAgent({\n      service: pds.serviceEndpoint,\n      fetch: this.options.fetch,\n    })\n\n    const collection = 'com.atproto.lexicon.schema'\n    const rkey = nsid.toString()\n\n    const { cid, record } = await xrpc(agent, com.atproto.sync.getRecord, {\n      signal: options?.signal,\n      headers: options?.noCache ? { 'Cache-Control': 'no-cache' } : undefined,\n      params: { did, collection, rkey },\n    }).then(\n      ({ body }) => {\n        return verifyRecordProof(body, did, key, collection, rkey).catch(\n          (cause) => {\n            throw new LexResolverError(\n              nsid,\n              `Failed to verify Lexicon record proof at ${uri}`,\n              { cause },\n            )\n          },\n        )\n      },\n      (cause) => {\n        throw new LexResolverError(nsid, `Failed to fetch Record ${uri}`, {\n          cause,\n        })\n      },\n    )\n\n    const validationResult = lexiconDocumentSchema.safeParse(record)\n    if (!validationResult.success) {\n      throw new LexResolverError(nsid, `Invalid Lexicon document at ${uri}`, {\n        cause: validationResult.reason,\n      })\n    }\n\n    const lexicon = validationResult.value\n    if (lexicon.id !== uri.rkey) {\n      throw new LexResolverError(\n        nsid,\n        `Invalid document id \"${lexicon.id}\" at ${uri}`,\n      )\n    }\n\n    return { lexicon, cid }\n  }\n}\n\nfunction parseLexiconUri(uri: AtUri): {\n  did: Did\n  nsid: NSID\n} {\n  // Validate input URI\n  const nsid = NSID.from(uri.rkey)\n  try {\n    const did = uri.host\n    assertDid(did)\n    return { did, nsid }\n  } catch (cause) {\n    throw new LexResolverError(nsid, `URI host is not a DID ${uri}`, { cause })\n  }\n}\n\nasync function getDomainTxtDid(domain: string): Promise<Did> {\n  const didLines = (await resolveTxt(domain))\n    .map((chunks) => chunks.join(''))\n    .filter((i) => i.startsWith('did='))\n\n  if (didLines.length === 1) {\n    const did = didLines[0].slice(4)\n    assertDid(did)\n    return did\n  }\n\n  throw didLines.length > 1\n    ? new Error('Multiple DIDs found in DNS TXT records')\n    : new Error('No DID found in DNS TXT records')\n}\n\nasync function verifyRecordProof(\n  car: Uint8Array,\n  did: Did,\n  key: AtprotoVerificationMethod,\n  collection: NsidString,\n  rkey: string,\n) {\n  const { root, blocks } = await readCarWithRoot(car)\n  const blockstore = new MemoryBlockstore(blocks)\n\n  const commit = await blockstore.readObj(root, repoDef.commit)\n  if (commit.did !== did) {\n    throw new Error(`Invalid repo did: ${commit.did}`)\n  }\n\n  const signingKey = getDidKeyFromMultibase(key)\n  const validSig = await verifyCommitSig(commit, signingKey)\n  if (!validSig) {\n    throw new Error(`Invalid signature on commit: ${root.toString()}`)\n  }\n\n  const mst = MST.load(blockstore, commit.data)\n\n  const cid = await mst.get(`${collection}/${rkey}`)\n  if (!cid) throw new Error('Record not found in proof')\n\n  const record = await blockstore.readRecord(cid)\n  if (record?.$type !== collection) {\n    throw new Error(\n      `Invalid record type: expected ${collection}, got ${record?.$type}`,\n    )\n  }\n\n  return { cid, record }\n}\n\nfunction getDidKeyFromMultibase(key: AtprotoVerificationMethod) {\n  switch (key.type) {\n    case 'EcdsaSecp256r1VerificationKey2019': {\n      const keyBytes = crypto.multibaseToBytes(key.publicKeyMultibase)\n      return crypto.formatDidKey(crypto.P256_JWT_ALG, keyBytes)\n    }\n    case 'EcdsaSecp256k1VerificationKey2019': {\n      const keyBytes = crypto.multibaseToBytes(key.publicKeyMultibase)\n      return crypto.formatDidKey(crypto.SECP256K1_JWT_ALG, keyBytes)\n    }\n    case 'Multikey': {\n      const { jwtAlg, keyBytes } = crypto.parseMultikey(key.publicKeyMultibase)\n      return crypto.formatDidKey(jwtAlg, keyBytes)\n    }\n    default: {\n      // Should never happen\n      throw new Error(`Unsupported verification method type: ${key.type}`)\n    }\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-resolver",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "license": "MIT",
   "description": "Lexicon document resolver utility for AT Lexicons",
   "keywords": [
@@ -30,24 +30,25 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "tslib": "^2.8.1",
     "@atproto-labs/did-resolver": "^0.2.6",
     "@atproto/crypto": "^0.4.5",
-    "@atproto/lex-client": "^0.0.11",
-    "@atproto/lex-data": "^0.0.10",
-    "@atproto/lex-document": "^0.0.12",
-    "@atproto/lex-schema": "^0.0.11",
+    "@atproto/lex-client": "^0.0.12",
+    "@atproto/lex-data": "^0.0.11",
+    "@atproto/lex-document": "^0.0.13",
+    "@atproto/lex-schema": "^0.0.12",
     "@atproto/repo": "^0.8.12",
     "@atproto/syntax": "^0.4.3"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-builder": "^0.0.13"
+    "@atproto/lex-builder": "^0.0.14"
   },
   "scripts": {
     "prebuild": "node ./scripts/lex-build.mjs",

package/src/lex-resolver-error.ts

@@ -1,16 +1,105 @@
+import { LexError } from '@atproto/lex-data'
 import { NSID } from '@atproto/syntax'
 
-export class LexResolverError extends Error {
+/**
+ * Error class for lexicon resolution failures.
+ *
+ * This error is thrown when the {@link LexResolver} encounters issues during
+ * the resolution process, such as DNS lookup failures, DID resolution errors,
+ * invalid lexicon documents, or network failures.
+ *
+ * @example Catching resolution errors
+ * ```typescript
+ * import { LexResolver, LexResolverError } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * try {
+ *   const result = await resolver.get('com.example.myLexicon')
+ * } catch (error) {
+ *   if (error instanceof LexResolverError) {
+ *     console.error(`Failed to resolve ${error.nsid}: ${error.description}`)
+ *     // Access the original cause if available
+ *     if (error.cause) {
+ *       console.error('Caused by:', error.cause)
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Creating errors with the factory method
+ * ```typescript
+ * import { LexResolverError } from '@atproto/lex-resolver'
+ *
+ * // Create from string NSID
+ * const error = LexResolverError.from(
+ *   'com.example.myLexicon',
+ *   'Custom error description'
+ * )
+ * ```
+ */
+export class LexResolverError extends LexError {
   name = 'LexResolverError'
 
+  /**
+   * Creates a new LexResolverError instance.
+   *
+   * @param nsid - The NSID that failed to resolve
+   * @param description - Human-readable description of the error. Defaults to
+   *   a generic message if not provided.
+   * @param options - Standard error options including `cause` for error chaining
+   *
+   * @example
+   * ```typescript
+   * import { NSID } from '@atproto/syntax'
+   * import { LexResolverError } from '@atproto/lex-resolver'
+   *
+   * const nsid = NSID.from('com.example.myLexicon')
+   * const error = new LexResolverError(
+   *   nsid,
+   *   'DNS lookup failed',
+   *   { cause: originalError }
+   * )
+   * ```
+   */
   constructor(
+    /**
+     * The NSID that failed to resolve.
+     */
     public readonly nsid: NSID,
+    /**
+     * Human-readable description of what went wrong during resolution.
+     */
     public readonly description = `Could not resolve Lexicon for NSID`,
     options?: ErrorOptions,
   ) {
-    super(`${description} (${nsid})`, options)
+    super('LexiconResolutionFailure', `${description} (${nsid})`, options)
   }
 
+  /**
+   * Factory method to create a LexResolverError from a string or NSID.
+   *
+   * This is a convenience method that handles the conversion of string NSIDs
+   * to NSID objects automatically.
+   *
+   * @param nsid - The NSID as a string or NSID object
+   * @param description - Optional human-readable description of the error
+   * @returns A new LexResolverError instance
+   *
+   * @example
+   * ```typescript
+   * import { LexResolverError } from '@atproto/lex-resolver'
+   *
+   * // Create from string
+   * const error1 = LexResolverError.from('com.example.myLexicon')
+   *
+   * // Create with description
+   * const error2 = LexResolverError.from(
+   *   'com.example.myLexicon',
+   *   'Authority not found in DNS'
+   * )
+   * ```
+   */
   static from(nsid: NSID | string, description?: string) {
     return new LexResolverError(
       typeof nsid === 'string' ? NSID.from(nsid) : nsid,