@atproto/identity 0.0.1

package/src/did/base-resolver.ts

@@ -0,0 +1,91 @@
+import * as crypto from '@atproto/crypto'
+import { check } from '@atproto/common-web'
+import { DidCache, AtprotoData, DidDocument, didDocument } from '../types'
+import * as atprotoData from './atproto-data'
+import { DidNotFoundError, PoorlyFormattedDidDocumentError } from '../errors'
+
+export abstract class BaseResolver {
+  constructor(public cache?: DidCache) {}
+
+  abstract resolveNoCheck(did: string): Promise<unknown | null>
+
+  validateDidDoc(did: string, val: unknown): DidDocument {
+    if (!check.is(val, didDocument)) {
+      throw new PoorlyFormattedDidDocumentError(did, val)
+    }
+    if (val.id !== did) {
+      throw new PoorlyFormattedDidDocumentError(did, val)
+    }
+    return val
+  }
+
+  async resolveNoCache(did: string): Promise<DidDocument | null> {
+    const got = await this.resolveNoCheck(did)
+    if (got === null) return null
+    return this.validateDidDoc(did, got)
+  }
+
+  async refreshCache(did: string): Promise<void> {
+    await this.cache?.refreshCache(did, () => this.resolveNoCache(did))
+  }
+
+  async resolve(
+    did: string,
+    forceRefresh = false,
+  ): Promise<DidDocument | null> {
+    if (this.cache && !forceRefresh) {
+      const fromCache = await this.cache.checkCache(did)
+      if (fromCache?.stale) {
+        await this.refreshCache(did)
+      }
+      if (fromCache) {
+        return fromCache.doc
+      }
+    }
+
+    const got = await this.resolveNoCache(did)
+    if (got === null) {
+      await this.cache?.clearEntry(did)
+      return null
+    }
+    await this.cache?.cacheDid(did, got)
+    return got
+  }
+
+  async ensureResolve(did: string, forceRefresh = false): Promise<DidDocument> {
+    const result = await this.resolve(did, forceRefresh)
+    if (result === null) {
+      throw new DidNotFoundError(did)
+    }
+    return result
+  }
+
+  async resolveAtprotoData(
+    did: string,
+    forceRefresh = false,
+  ): Promise<AtprotoData> {
+    const didDocument = await this.ensureResolve(did, forceRefresh)
+    return atprotoData.ensureAtpDocument(didDocument)
+  }
+
+  async resolveAtprotoKey(did: string, forceRefresh = false): Promise<string> {
+    if (did.startsWith('did:key:')) {
+      return did
+    } else {
+      const data = await this.resolveAtprotoData(did, forceRefresh)
+      return data.signingKey
+    }
+  }
+
+  async verifySignature(
+    did: string,
+    data: Uint8Array,
+    sig: Uint8Array,
+    forceRefresh = false,
+  ): Promise<boolean> {
+    const signingKey = await this.resolveAtprotoKey(did, forceRefresh)
+    return crypto.verifySignature(signingKey, data, sig)
+  }
+}
+
+export default BaseResolver

package/src/did/did-resolver.ts

@@ -0,0 +1,33 @@
+import { DidWebResolver } from './web-resolver'
+import { DidPlcResolver } from './plc-resolver'
+import { DidResolverOpts } from '../types'
+import BaseResolver from './base-resolver'
+import { PoorlyFormattedDidError, UnsupportedDidMethodError } from '../errors'
+
+export class DidResolver extends BaseResolver {
+  methods: Record<string, BaseResolver>
+
+  constructor(opts: DidResolverOpts) {
+    super(opts.didCache)
+    const { timeout = 3000, plcUrl = 'https://plc.directory' } = opts
+    // do not pass cache to sub-methods or we will be double caching
+    this.methods = {
+      plc: new DidPlcResolver(plcUrl, timeout),
+      web: new DidWebResolver(timeout),
+    }
+  }
+
+  async resolveNoCheck(did: string): Promise<unknown> {
+    const split = did.split(':')
+    if (split[0] !== 'did') {
+      throw new PoorlyFormattedDidError(did)
+    }
+    const method = this.methods[split[1]]
+    if (!method) {
+      throw new UnsupportedDidMethodError(did)
+    }
+    return method.resolveNoCheck(did)
+  }
+}
+
+export default DidResolver

package/src/did/index.ts

@@ -0,0 +1,5 @@
+export * from './web-resolver'
+export * from './plc-resolver'
+export * from './did-resolver'
+export * from './atproto-data'
+export * from './memory-cache'

package/src/did/memory-cache.ts

@@ -0,0 +1,55 @@
+import { DAY, HOUR } from '@atproto/common-web'
+import { DidCache, CacheResult, DidDocument } from '../types'
+
+type CacheVal = {
+  doc: DidDocument
+  updatedAt: number
+}
+
+export class MemoryCache implements DidCache {
+  public staleTTL: number
+  public maxTTL: number
+  constructor(staleTTL?: number, maxTTL?: number) {
+    this.staleTTL = staleTTL ?? HOUR
+    this.maxTTL = maxTTL ?? DAY
+  }
+
+  public cache: Map<string, CacheVal> = new Map()
+
+  async cacheDid(did: string, doc: DidDocument): Promise<void> {
+    this.cache.set(did, { doc, updatedAt: Date.now() })
+  }
+
+  async refreshCache(
+    did: string,
+    getDoc: () => Promise<DidDocument | null>,
+  ): Promise<void> {
+    const doc = await getDoc()
+    if (doc) {
+      await this.cacheDid(did, doc)
+    }
+  }
+
+  async checkCache(did: string): Promise<CacheResult | null> {
+    const val = this.cache.get(did)
+    if (!val) return null
+    const now = Date.now()
+    const expired = now > val.updatedAt + this.maxTTL
+    if (expired) return null
+
+    const stale = now > val.updatedAt + this.staleTTL
+    return {
+      ...val,
+      did,
+      stale,
+    }
+  }
+
+  async clearEntry(did: string): Promise<void> {
+    this.cache.delete(did)
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear()
+  }
+}

package/src/did/plc-resolver.ts

@@ -0,0 +1,27 @@
+import axios, { AxiosError } from 'axios'
+import BaseResolver from './base-resolver'
+import { DidCache } from '../types'
+
+export class DidPlcResolver extends BaseResolver {
+  constructor(
+    public plcUrl: string,
+    public timeout: number,
+    public cache?: DidCache,
+  ) {
+    super(cache)
+  }
+
+  async resolveNoCheck(did: string): Promise<unknown> {
+    try {
+      const res = await axios.get(`${this.plcUrl}/${encodeURIComponent(did)}`, {
+        timeout: this.timeout,
+      })
+      return res.data
+    } catch (err) {
+      if (err instanceof AxiosError && err.response?.status === 404) {
+        return null // Positively not found, versus due to e.g. network error
+      }
+      throw err
+    }
+  }
+}

package/src/did/web-resolver.ts

@@ -0,0 +1,45 @@
+import axios, { AxiosError } from 'axios'
+import BaseResolver from './base-resolver'
+import { DidCache } from '../types'
+import { PoorlyFormattedDidError, UnsupportedDidWebPathError } from '../errors'
+
+export const DOC_PATH = '/.well-known/did.json'
+
+export class DidWebResolver extends BaseResolver {
+  constructor(public timeout: number, public cache?: DidCache) {
+    super(cache)
+  }
+
+  async resolveNoCheck(did: string): Promise<unknown> {
+    const parsedId = did.split(':').slice(2).join(':')
+    const parts = parsedId.split(':').map(decodeURIComponent)
+    let path: string
+    if (parts.length < 1) {
+      throw new PoorlyFormattedDidError(did)
+    } else if (parts.length === 1) {
+      path = parts[0] + DOC_PATH
+    } else {
+      // how we *would* resolve a did:web with path, if atproto supported it
+      //path = parts.join('/') + '/did.json'
+      throw new UnsupportedDidWebPathError(did)
+    }
+
+    const url = new URL(`https://${path}`)
+    if (url.hostname === 'localhost') {
+      url.protocol = 'http'
+    }
+
+    try {
+      const res = await axios.get(url.toString(), {
+        responseType: 'json',
+        timeout: this.timeout,
+      })
+      return res.data
+    } catch (err) {
+      if (err instanceof AxiosError && err.response) {
+        return null // Positively not found, versus due to e.g. network error
+      }
+      throw err
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,29 @@
+export class DidNotFoundError extends Error {
+  constructor(public did: string) {
+    super(`Could not resolve DID: ${did}`)
+  }
+}
+
+export class PoorlyFormattedDidError extends Error {
+  constructor(public did: string) {
+    super(`Poorly formatted DID: ${did}`)
+  }
+}
+
+export class UnsupportedDidMethodError extends Error {
+  constructor(public did: string) {
+    super(`Unsupported DID method: ${did}`)
+  }
+}
+
+export class PoorlyFormattedDidDocumentError extends Error {
+  constructor(public did: string, public doc: unknown) {
+    super(`Poorly formatted DID Document: ${doc}`)
+  }
+}
+
+export class UnsupportedDidWebPathError extends Error {
+  constructor(public did: string) {
+    super(`Unsupported did:web paths: ${did}`)
+  }
+}

package/src/handle/index.ts

@@ -0,0 +1,60 @@
+import dns from 'dns/promises'
+import { HandleResolverOpts } from '../types'
+
+const SUBDOMAIN = '_atproto'
+const PREFIX = 'did='
+
+export class HandleResolver {
+  public timeout: number
+
+  constructor(opts: HandleResolverOpts = {}) {
+    this.timeout = opts.timeout ?? 3000
+  }
+
+  async resolve(handle: string): Promise<string | undefined> {
+    const dnsPromise = this.resolveDns(handle)
+    const httpAbort = new AbortController()
+    const httpPromise = this.resolveHttp(handle, httpAbort.signal).catch(
+      () => undefined,
+    )
+
+    const dnsRes = await dnsPromise
+    if (dnsRes) {
+      httpAbort.abort()
+      return dnsRes
+    }
+    return httpPromise
+  }
+
+  async resolveDns(handle: string): Promise<string | undefined> {
+    let chunkedResults: string[][]
+    try {
+      chunkedResults = await dns.resolveTxt(`${SUBDOMAIN}.${handle}`)
+    } catch (err) {
+      return undefined
+    }
+    const results = chunkedResults.map((chunks) => chunks.join(''))
+    const found = results.filter((i) => i.startsWith(PREFIX))
+    if (found.length !== 1) {
+      return undefined
+    }
+    return found[0].slice(PREFIX.length)
+  }
+
+  async resolveHttp(
+    handle: string,
+    signal?: AbortSignal,
+  ): Promise<string | undefined> {
+    const url = new URL('/.well-known/atproto-did', `https://${handle}`)
+    try {
+      const res = await fetch(url, { signal })
+      const did = await res.text()
+      if (typeof did === 'string' && did.startsWith('did:')) {
+        return did
+      }
+      return undefined
+    } catch (err) {
+      return undefined
+    }
+  }
+}

package/src/id-resolver.ts

@@ -0,0 +1,14 @@
+import { HandleResolver } from './handle'
+import DidResolver from './did/did-resolver'
+import { IdentityResolverOpts } from './types'
+
+export class IdResolver {
+  public handle: HandleResolver
+  public did: DidResolver
+
+  constructor(opts: IdentityResolverOpts = {}) {
+    const { timeout = 3000, plcUrl, didCache } = opts
+    this.handle = new HandleResolver({ timeout })
+    this.did = new DidResolver({ timeout, plcUrl, didCache })
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './did'
+export * from './handle'
+export * from './id-resolver'
+export * from './errors'
+export * from './types'

package/src/types.ts

@@ -0,0 +1,64 @@
+import * as z from 'zod'
+
+export type IdentityResolverOpts = {
+  timeout?: number
+  plcUrl?: string
+  didCache?: DidCache
+}
+
+export type HandleResolverOpts = {
+  timeout?: number
+}
+
+export type DidResolverOpts = {
+  timeout?: number
+  plcUrl?: string
+  didCache?: DidCache
+}
+
+export type AtprotoData = {
+  did: string
+  signingKey: string
+  handle: string
+  pds: string
+}
+
+export type CacheResult = {
+  did: string
+  doc: DidDocument
+  updatedAt: number
+  stale: boolean
+}
+
+export interface DidCache {
+  cacheDid(did: string, doc: DidDocument): Promise<void>
+  checkCache(did: string): Promise<CacheResult | null>
+  refreshCache(
+    did: string,
+    getDoc: () => Promise<DidDocument | null>,
+  ): Promise<void>
+  clearEntry(did: string): Promise<void>
+  clear(): Promise<void>
+}
+
+export const verificationMethod = z.object({
+  id: z.string(),
+  type: z.string(),
+  controller: z.string(),
+  publicKeyMultibase: z.string().optional(),
+})
+
+export const service = z.object({
+  id: z.string(),
+  type: z.string(),
+  serviceEndpoint: z.union([z.string(), z.record(z.unknown())]),
+})
+
+export const didDocument = z.object({
+  id: z.string(),
+  alsoKnownAs: z.array(z.string()).optional(),
+  verificationMethod: z.array(verificationMethod).optional(),
+  service: z.array(service).optional(),
+})
+
+export type DidDocument = z.infer<typeof didDocument>

package/test.env

@@ -0,0 +1,2 @@
+LOG_ENABLED=true
+LOG_DESTINATION=test.log