@atproto/lexicon-resolver 0.1.0

package/src/client/util.ts

@@ -0,0 +1,82 @@
+/**
+ * GENERATED CODE - DO NOT MODIFY
+ */
+
+import { type ValidationResult } from '@atproto/lexicon'
+
+export type OmitKey<T, K extends keyof T> = {
+  [K2 in keyof T as K2 extends K ? never : K2]: T[K2]
+}
+
+export type $Typed<V, T extends string = string> = V & { $type: T }
+export type Un$Typed<V extends { $type?: string }> = OmitKey<V, '$type'>
+
+export type $Type<Id extends string, Hash extends string> = Hash extends 'main'
+  ? Id
+  : `${Id}#${Hash}`
+
+function isObject<V>(v: V): v is V & object {
+  return v != null && typeof v === 'object'
+}
+
+function is$type<Id extends string, Hash extends string>(
+  $type: unknown,
+  id: Id,
+  hash: Hash,
+): $type is $Type<Id, Hash> {
+  return hash === 'main'
+    ? $type === id
+    : // $type === `${id}#${hash}`
+      typeof $type === 'string' &&
+        $type.length === id.length + 1 + hash.length &&
+        $type.charCodeAt(id.length) === 35 /* '#' */ &&
+        $type.startsWith(id) &&
+        $type.endsWith(hash)
+}
+
+export type $TypedObject<
+  V,
+  Id extends string,
+  Hash extends string,
+> = V extends {
+  $type: $Type<Id, Hash>
+}
+  ? V
+  : V extends { $type?: string }
+    ? V extends { $type?: infer T extends $Type<Id, Hash> }
+      ? V & { $type: T }
+      : never
+    : V & { $type: $Type<Id, Hash> }
+
+export function is$typed<V, Id extends string, Hash extends string>(
+  v: V,
+  id: Id,
+  hash: Hash,
+): v is $TypedObject<V, Id, Hash> {
+  return isObject(v) && '$type' in v && is$type(v.$type, id, hash)
+}
+
+export function maybe$typed<V, Id extends string, Hash extends string>(
+  v: V,
+  id: Id,
+  hash: Hash,
+): v is V & object & { $type?: $Type<Id, Hash> } {
+  return (
+    isObject(v) &&
+    ('$type' in v ? v.$type === undefined || is$type(v.$type, id, hash) : true)
+  )
+}
+
+export type Validator<R = unknown> = (v: unknown) => ValidationResult<R>
+export type ValidatorParam<V extends Validator> =
+  V extends Validator<infer R> ? R : never
+
+/**
+ * Utility function that allows to convert a "validate*" utility function into a
+ * type predicate.
+ */
+export function asPredicate<V extends Validator>(validate: V) {
+  return function <T>(v: T): v is T & ValidatorParam<V> {
+    return validate(v).success
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './record.js'
+export * from './lexicon.js'

package/src/lexicon.ts

@@ -0,0 +1,147 @@
+import dns from 'node:dns/promises'
+import { CID } from 'multiformats/cid'
+import { LexiconDoc, parseLexiconDoc } from '@atproto/lexicon'
+import { Commit } from '@atproto/repo'
+import { AtUri, NSID, ensureValidDid } from '@atproto/syntax'
+import {
+  BuildRecordResolverOptions,
+  ResolveRecordOptions,
+  buildRecordResolver,
+} from './record.js'
+import { isValidDid } from './util.js'
+
+const DNS_SUBDOMAIN = '_lexicon'
+const DNS_PREFIX = 'did='
+export const LEXICON_SCHEMA_NSID = 'com.atproto.lexicon.schema'
+
+/**
+ * Resolve Lexicon from an NSID
+ */
+export type LexiconResolver = (
+  nsid: NSID | string,
+) => Promise<LexiconResolution>
+
+/**
+ * Resolve Lexicon from an NSID using Lexicon DID authority and record resolution
+ */
+export type AtprotoLexiconResolver = (
+  nsid: NSID | string,
+  options?: ResolveLexiconOptions,
+) => Promise<LexiconResolution>
+
+export type BuildLexiconResolverOptions = BuildRecordResolverOptions
+
+export type ResolveLexiconOptions = ResolveRecordOptions & {
+  didAuthority?: string
+}
+
+export type LexiconResolution = {
+  commit: Commit
+  uri: AtUri
+  cid: CID
+  nsid: NSID
+  lexicon: LexiconDoc & LexiconSchemaRecord
+}
+
+/**
+ * Build a Lexicon resolver function.
+ */
+export function buildLexiconResolver(
+  options: BuildLexiconResolverOptions = {},
+): AtprotoLexiconResolver {
+  const resolveRecord = buildRecordResolver(options)
+  return async function (
+    nsidStr: NSID | string,
+    opts: ResolveLexiconOptions = {},
+  ): Promise<LexiconResolution> {
+    const nsid = typeof nsidStr === 'string' ? NSID.parse(nsidStr) : nsidStr
+    const didAuthority = await getDidAuthority(nsid, opts)
+    const verified = await resolveRecord(
+      AtUri.make(didAuthority, LEXICON_SCHEMA_NSID, nsid.toString()),
+      { forceRefresh: opts.forceRefresh },
+    ).catch((err) => {
+      throw new LexiconResolutionError(
+        'Could not resolve Lexicon schema record',
+        { cause: err },
+      )
+    })
+    let lexicon: LexiconDoc
+    try {
+      lexicon = parseLexiconDoc(verified.record)
+    } catch (err) {
+      throw new LexiconResolutionError('Invalid Lexicon document', {
+        cause: err,
+      })
+    }
+    if (!isLexiconSchemaRecord(lexicon)) {
+      throw new LexiconResolutionError('Invalid Lexicon schema record')
+    }
+    if (lexicon.id !== nsid.toString()) {
+      throw new LexiconResolutionError(
+        `Lexicon schema record id does not match NSID: ${lexicon.id}`,
+      )
+    }
+    const { uri, cid, commit } = verified
+    return { commit, uri, cid, nsid, lexicon }
+  } satisfies LexiconResolver
+}
+
+export const resolveLexicon = buildLexiconResolver()
+
+/**
+ * Resolve the DID authority for a Lexicon from the network using DNS, based on its NSID.
+ * @param nsidStr NSID or string representing one for which to lookup its Lexicon DID authority.
+ */
+export async function resolveLexiconDidAuthority(
+  nsidStr: NSID | string,
+): Promise<string | undefined> {
+  const nsid = typeof nsidStr === 'string' ? NSID.parse(nsidStr) : nsidStr
+  const did = await resolveDns(nsid.authority)
+  if (did == null || !isValidDid(did)) return
+  return did
+}
+
+export class LexiconResolutionError extends Error {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'LexiconResolutionError'
+  }
+}
+
+async function getDidAuthority(nsid: NSID, options: ResolveLexiconOptions) {
+  if (options.didAuthority) {
+    ensureValidDid(options.didAuthority)
+    return options.didAuthority
+  }
+  const did = await resolveLexiconDidAuthority(nsid)
+  if (!did) {
+    throw new LexiconResolutionError(
+      `Could not resolve a DID authority for NSID: ${nsid}`,
+    )
+  }
+  return did
+}
+
+async function resolveDns(authority: string): Promise<string | undefined> {
+  let chunkedResults: string[][]
+  try {
+    chunkedResults = await dns.resolveTxt(`${DNS_SUBDOMAIN}.${authority}`)
+  } catch (err) {
+    return undefined
+  }
+  return parseDnsResult(chunkedResults)
+}
+
+function parseDnsResult(chunkedResults: string[][]): string | undefined {
+  const results = chunkedResults.map((chunks) => chunks.join(''))
+  const found = results.filter((i) => i.startsWith(DNS_PREFIX))
+  if (found.length !== 1) {
+    return undefined
+  }
+  return found[0].slice(DNS_PREFIX.length)
+}
+
+type LexiconSchemaRecord = { $type: typeof LEXICON_SCHEMA_NSID }
+function isLexiconSchemaRecord(v: unknown): v is LexiconSchemaRecord {
+  return v?.['$type'] === LEXICON_SCHEMA_NSID
+}

package/src/record.ts

@@ -0,0 +1,156 @@
+import { CID } from 'multiformats/cid'
+import { IdResolver } from '@atproto/identity'
+import { RepoRecord } from '@atproto/lexicon'
+import {
+  Commit,
+  MST,
+  MemoryBlockstore,
+  def as repoDef,
+  readCarWithRoot,
+  verifyCommitSig,
+} from '@atproto/repo'
+import { AtUri, ensureValidDid } from '@atproto/syntax'
+import { BuildFetchHandlerOptions, FetchHandler } from '@atproto/xrpc'
+import { safeFetchWrap } from '@atproto-labs/fetch-node'
+import { AtpBaseClient as Client } from './client/index.js'
+import { isValidDid } from './util.js'
+
+/**
+ * Resolve a record from the network.
+ */
+export type RecordResolver = (
+  uriStr: AtUri | string,
+) => Promise<RecordResolution>
+
+/**
+ * Resolve a record from the network, verifying its authenticity.
+ */
+export type AtprotoRecordResolver = (
+  uriStr: AtUri | string,
+  options?: ResolveRecordOptions,
+) => Promise<RecordResolution>
+
+export type BuildRecordResolverOptions = {
+  idResolver?: IdResolver
+  rpc?: Partial<BuildFetchHandlerOptions> | FetchHandler
+}
+
+export type ResolveRecordOptions = {
+  forceRefresh?: boolean
+}
+
+export type RecordResolution = {
+  commit: Commit
+  uri: AtUri
+  cid: CID
+  record: RepoRecord
+}
+
+/**
+ * Build a record resolver function.
+ */
+export function buildRecordResolver(
+  options: BuildRecordResolverOptions = {},
+): AtprotoRecordResolver {
+  const { idResolver = new IdResolver(), rpc } = options
+  return async function resolveRecord(
+    uriStr: AtUri | string,
+    opts: ResolveRecordOptions = {},
+  ): Promise<RecordResolution> {
+    const uri = typeof uriStr === 'string' ? new AtUri(uriStr) : uriStr
+    const did = await getDidFromUri(uri, { idResolver })
+    const identity = await idResolver.did
+      .resolveAtprotoData(did, opts.forceRefresh)
+      .catch((err) => {
+        throw new RecordResolutionError('Could not resolve DID identity data', {
+          cause: err,
+        })
+      })
+    const client = new Client(
+      typeof rpc === 'function'
+        ? rpc
+        : {
+            ...rpc,
+            service: rpc?.service ?? identity.pds,
+            fetch: rpc?.fetch ?? safeFetch,
+          },
+    )
+    const { data: proofBytes } = await client.com.atproto.sync
+      .getRecord({
+        did,
+        collection: uri.collection,
+        rkey: uri.rkey,
+      })
+      .catch((err) => {
+        throw new RecordResolutionError('Could not fetch record proof', {
+          cause: err,
+        })
+      })
+    const verified = await verifyRecordProof(proofBytes, {
+      uri: AtUri.make(did, uri.collection, uri.rkey),
+      signingKey: identity.signingKey,
+    })
+    return verified
+  }
+}
+
+export const resolveRecord = buildRecordResolver()
+
+export const safeFetch = safeFetchWrap({
+  allowIpHost: false,
+  allowImplicitRedirect: true,
+  responseMaxSize: (1024 + 10) * 1024, // 1MB + 10kB, just a bit larger than max record size
+})
+
+export class RecordResolutionError extends Error {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'RecordResolutionError'
+  }
+}
+
+async function getDidFromUri(
+  uri: AtUri,
+  { idResolver }: { idResolver: IdResolver },
+) {
+  if (uri.host.startsWith('did:')) {
+    ensureValidDid(uri.host)
+    return uri.host
+  }
+  const resolved = await idResolver.handle.resolve(uri.host)
+  if (!resolved || !isValidDid(resolved)) {
+    throw new RecordResolutionError('Could not resolve handle found in AT-URI')
+  }
+  return resolved
+}
+
+async function verifyRecordProof(
+  proofBytes: Uint8Array,
+  { uri, signingKey }: { uri: AtUri; signingKey: string },
+) {
+  const { root, blocks } = await readCarWithRoot(proofBytes).catch((err) => {
+    throw new RecordResolutionError('Malformed record proof', { cause: err })
+  })
+  const blockstore = new MemoryBlockstore(blocks)
+  const commit = await blockstore.readObj(root, repoDef.commit).catch((err) => {
+    throw new RecordResolutionError('Invalid commit in record proof', {
+      cause: err,
+    })
+  })
+  if (commit.did !== uri.host) {
+    throw new RecordResolutionError(`Invalid repo did: ${commit.did}`)
+  }
+  const validSig = await verifyCommitSig(commit, signingKey)
+  if (!validSig) {
+    throw new RecordResolutionError(
+      `Invalid signature on commit: ${root.toString()}`,
+    )
+  }
+  const mst = MST.load(blockstore, commit.data)
+  const cid = await mst.get(`${uri.collection}/${uri.rkey}`)
+  if (!cid) {
+    throw new RecordResolutionError('Record not found in proof')
+  }
+  const record = await blockstore.readRecord(cid)
+  return { commit, uri, cid, record }
+}

package/src/util.ts

@@ -0,0 +1,10 @@
+import { ensureValidDid } from '@atproto/syntax'
+
+export function isValidDid(did: string) {
+  try {
+    ensureValidDid(did)
+    return true
+  } catch {
+    return false
+  }
+}

package/tests/lexicon.test.ts

@@ -0,0 +1,266 @@
+import { SeedClient, TestNetworkNoAppView, usersSeed } from '@atproto/dev-env'
+import { NSID } from '@atproto/syntax'
+import {
+  AtprotoLexiconResolver,
+  buildLexiconResolver,
+  resolveLexiconDidAuthority,
+} from '../src/index.js'
+
+const dnsEntries: [entry: string, ...result: string[][]][] = []
+
+jest.mock('node:dns/promises', () => {
+  return {
+    resolveTxt: (entry: string) => {
+      const found = dnsEntries.find(([e]) => e === entry)
+      if (found) return found.slice(1)
+      return []
+    },
+  }
+})
+
+describe('Lexicon resolution', () => {
+  let network: TestNetworkNoAppView
+  let sc: SeedClient
+  let resolveLexicon: AtprotoLexiconResolver
+
+  beforeAll(async () => {
+    network = await TestNetworkNoAppView.create({
+      dbPostgresSchema: 'lex_lexicon_resolution',
+    })
+    sc = network.getSeedClient()
+    await usersSeed(sc)
+    dnsEntries.push(['_lexicon.alice.example', [`did=${sc.dids.alice}`]])
+    resolveLexicon = buildLexiconResolver({
+      rpc: { fetch },
+      idResolver: network.pds.ctx.idResolver,
+    })
+  })
+
+  afterAll(async () => {
+    jest.unmock('node:dns/promises')
+    await network.close()
+  })
+
+  it('resolves Lexicon.', async () => {
+    const client = network.pds.getClient()
+    const lex = await client.com.atproto.lexicon.schema.create(
+      { repo: sc.dids.alice, rkey: 'example.alice.name1' },
+      { id: 'example.alice.name1', lexicon: 1, defs: {} },
+      sc.getHeaders(sc.dids.alice),
+    )
+    const result = await resolveLexicon('example.alice.name1', {
+      forceRefresh: true,
+    })
+    expect(result.commit.did).toEqual(sc.dids.alice)
+    expect(result.cid.toString()).toEqual(lex.cid)
+    expect(result.uri.toString()).toEqual(lex.uri)
+    expect(result.nsid.toString()).toEqual('example.alice.name1')
+    expect(result.lexicon).toEqual({
+      $type: 'com.atproto.lexicon.schema',
+      id: 'example.alice.name1',
+      lexicon: 1,
+      defs: {},
+    })
+  })
+
+  it('fails on mismatched id.', async () => {
+    const client = network.pds.getClient()
+    await client.com.atproto.lexicon.schema.create(
+      { repo: sc.dids.alice, rkey: 'example.alice.mismatch' },
+      { id: 'example.test1.mismatch.bad', lexicon: 1, defs: {} },
+      sc.getHeaders(sc.dids.alice),
+    )
+    await expect(
+      resolveLexicon('example.alice.mismatch', {
+        forceRefresh: true,
+      }),
+    ).rejects.toThrow('Lexicon schema record id does not match NSID')
+  })
+
+  it('fails on missing DNS entry.', async () => {
+    const client = network.pds.getClient()
+    await client.com.atproto.lexicon.schema.create(
+      { repo: sc.dids.bob, rkey: 'example.bob.name' },
+      { id: 'example.bob.name', lexicon: 1, defs: {} },
+      sc.getHeaders(sc.dids.bob),
+    )
+    await expect(
+      resolveLexicon('example.bob.name', {
+        forceRefresh: true,
+      }),
+    ).rejects.toThrow(
+      'Could not resolve a DID authority for NSID: example.bob.name',
+    )
+  })
+
+  it('fails on missing record.', async () => {
+    await expect(
+      resolveLexicon('example.alice.missing', {
+        forceRefresh: true,
+      }),
+    ).rejects.toThrow('Could not resolve Lexicon schema record')
+  })
+
+  it('fails on bad verification.', async () => {
+    const client = network.pds.getClient()
+    const alicekey = await network.pds.ctx.actorStore.keypair(sc.dids.alice)
+    const bobkey = await network.pds.ctx.actorStore.keypair(sc.dids.bob)
+    await client.com.atproto.lexicon.schema.create(
+      { repo: sc.dids.alice, rkey: 'example.alice.badsig' },
+      { id: 'example.alice.badsig', lexicon: 1, defs: {} },
+      sc.getHeaders(sc.dids.alice),
+    )
+    // switch alice's key away from the one used by her pds
+    await network.pds.ctx.plcClient.updateAtprotoKey(
+      sc.dids.alice,
+      network.pds.ctx.plcRotationKey,
+      bobkey.did(),
+    )
+    await expect(
+      resolveLexicon('example.alice.badsig', {
+        forceRefresh: true,
+      }),
+    ).rejects.toThrow(
+      expect.objectContaining({
+        name: 'LexiconResolutionError',
+        message: 'Could not resolve Lexicon schema record',
+        cause: expect.objectContaining({
+          name: 'RecordResolutionError',
+          message: expect.stringContaining('Invalid signature on commit'),
+        }),
+      }),
+    )
+    // reset alice's key
+    await network.pds.ctx.plcClient.updateAtprotoKey(
+      sc.dids.alice,
+      network.pds.ctx.plcRotationKey,
+      alicekey.did(),
+    )
+  })
+
+  it('fails on invalid Lexicon document.', async () => {
+    const client = network.pds.getClient()
+    await client.com.atproto.lexicon.schema.create(
+      { repo: sc.dids.alice, rkey: 'example.alice.baddoc' },
+      { id: 'example.alice.baddoc', lexicon: 999, defs: {} },
+      sc.getHeaders(sc.dids.alice),
+    )
+    await expect(
+      resolveLexicon('example.alice.baddoc', {
+        forceRefresh: true,
+      }),
+    ).rejects.toThrow(
+      expect.objectContaining({
+        name: 'LexiconResolutionError',
+        message: 'Invalid Lexicon document',
+        cause: expect.objectContaining({
+          name: 'ZodError',
+        }),
+      }),
+    )
+  })
+
+  it('resolves Lexicon based on override authority.', async () => {
+    const client = network.pds.getClient()
+    await client.com.atproto.lexicon.schema.create(
+      { repo: sc.dids.alice, rkey: 'example.alice.override' },
+      {
+        id: 'example.alice.override',
+        lexicon: 1,
+        defs: { alice: { type: 'string' } },
+      },
+      sc.getHeaders(sc.dids.alice),
+    )
+    const carolLex = await client.com.atproto.lexicon.schema.create(
+      { repo: sc.dids.carol, rkey: 'example.alice.override' },
+      {
+        id: 'example.alice.override',
+        lexicon: 1,
+        defs: { carol: { type: 'string' } },
+      },
+      sc.getHeaders(sc.dids.carol),
+    )
+    const result = await resolveLexicon('example.alice.override', {
+      didAuthority: sc.dids.carol,
+      forceRefresh: true,
+    })
+    expect(result.commit.did).toEqual(sc.dids.carol)
+    expect(result.cid.toString()).toEqual(carolLex.cid)
+    expect(result.uri.toString()).toEqual(carolLex.uri)
+    expect(result.nsid.toString()).toEqual('example.alice.override')
+    expect(result.lexicon).toEqual({
+      $type: 'com.atproto.lexicon.schema',
+      id: 'example.alice.override',
+      lexicon: 1,
+      defs: { carol: { type: 'string' } },
+    })
+  })
+
+  describe('DID authority', () => {
+    it('handles a simple DNS resolution', async () => {
+      dnsEntries.push(['_lexicon.simple.test', ['did=did:example:simpleDid']])
+      const did = await resolveLexiconDidAuthority('test.simple.name')
+      expect(did).toBe('did:example:simpleDid')
+    })
+
+    it('handles a noisy DNS resolution', async () => {
+      dnsEntries.push([
+        '_lexicon.noisy.test',
+        ['blah blah blah'],
+        ['did:example:fakeDid'],
+        ['atproto=did:example:fakeDid'],
+        ['did=did:example:noisyDid'],
+        [
+          'chunk long domain aspdfoiuwerpoaisdfupasodfiuaspdfoiuasdpfoiausdfpaosidfuaspodifuaspdfoiuasdpfoiasudfpasodifuaspdofiuaspdfoiuasd',
+          'apsodfiuweproiasudfpoasidfu',
+        ],
+      ])
+      const did = await resolveLexiconDidAuthority('test.noisy.name')
+      expect(did).toBe('did:example:noisyDid')
+    })
+
+    it('handles a bad DNS resolution', async () => {
+      dnsEntries.push([
+        '_lexicon.bad.test',
+        ['blah blah blah'],
+        ['did:example:fakeDid'],
+        ['atproto=did:example:fakeDid'],
+        [
+          'chunk long domain aspdfoiuwerpoaisdfupasodfiuaspdfoiuasdpfoiausdfpaosidfuaspodifuaspdfoiuasdpfoiasudfpasodifuaspdofiuaspdfoiuasd',
+          'apsodfiuweproiasudfpoasidfu',
+        ],
+      ])
+      const did = await resolveLexiconDidAuthority('test.bad.name')
+      expect(did).toBeUndefined()
+    })
+
+    it('throws on multiple dids under same domain', async () => {
+      dnsEntries.push([
+        '_lexicon.bad.test',
+        ['did=did:example:firstDid'],
+        ['did=did:example:secondDid'],
+      ])
+      const did = await resolveLexiconDidAuthority('test.multi.name')
+      expect(did).toBeUndefined()
+    })
+
+    it('fails on invalid NSID', async () => {
+      await expect(resolveLexiconDidAuthority('not an nsid')).rejects.toThrow(
+        'Disallowed characters in NSID',
+      )
+    })
+
+    it('fails on invalid DID result', async () => {
+      dnsEntries.push(['_lexicon.invalid.test', ['did=not:a:did']])
+      const did = await resolveLexiconDidAuthority('test.invalid.name')
+      expect(did).toBeUndefined()
+    })
+
+    it('accepts NSID object', async () => {
+      const did = await resolveLexiconDidAuthority(
+        NSID.parse('test.simple.name'),
+      )
+      expect(did).toBe('did:example:simpleDid')
+    })
+  })
+})