@atproto/did 0.1.0

package/src/did.ts

@@ -0,0 +1,258 @@
+import { z } from 'zod'
+import { DidError, InvalidDidError } from './did-error.js'
+
+const DID_PREFIX = 'did:'
+const DID_PREFIX_LENGTH = DID_PREFIX.length
+export { DID_PREFIX }
+
+/**
+ * Type representation of a Did, with method.
+ *
+ * ```bnf
+ * did                = "did:" method-name ":" method-specific-id
+ * method-name        = 1*method-char
+ * method-char        = %x61-7A / DIGIT
+ * method-specific-id = *( *idchar ":" ) 1*idchar
+ * idchar             = ALPHA / DIGIT / "." / "-" / "_" / pct-encoded
+ * pct-encoded        = "%" HEXDIG HEXDIG
+ * ```
+ *
+ * @example
+ * ```ts
+ * type DidWeb = Did<'web'> // `did:web:${string}`
+ * type DidCustom = Did<'web' | 'plc'> // `did:${'web' | 'plc'}:${string}`
+ * type DidNever = Did<' invalid 🥴 '> // never
+ * type DidFoo = Did<'foo' | ' invalid 🥴 '> // `did:foo:${string}`
+ * ```
+ *
+ * @see {@link https://www.w3.org/TR/did-core/#did-syntax}
+ */
+export type Did<M extends string = string> = `did:${AsDidMethod<M>}:${string}`
+
+/**
+ * DID Method
+ */
+export type AsDidMethod<M> = string extends M
+  ? string // can't know...
+  : AsDidMethodInternal<M, ''>
+
+type AlphanumericChar = DigitChar | LowerAlphaChar
+type DigitChar = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+type LowerAlphaChar =
+  | 'a'
+  | 'b'
+  | 'c'
+  | 'd'
+  | 'e'
+  | 'f'
+  | 'g'
+  | 'h'
+  | 'i'
+  | 'j'
+  | 'k'
+  | 'l'
+  | 'm'
+  | 'n'
+  | 'o'
+  | 'p'
+  | 'q'
+  | 'r'
+  | 's'
+  | 't'
+  | 'u'
+  | 'v'
+  | 'w'
+  | 'x'
+  | 'y'
+  | 'z'
+
+type AsDidMethodInternal<
+  S,
+  Acc extends string,
+> = S extends `${infer H}${infer T}`
+  ? H extends AlphanumericChar
+    ? AsDidMethodInternal<T, `${Acc}${H}`>
+    : never
+  : Acc extends ''
+    ? never
+    : Acc
+
+/**
+ * DID Method-name check function.
+ *
+ * Check if the input is a valid DID method name, at the position between
+ * `start` (inclusive) and `end` (exclusive).
+ */
+export function checkDidMethod(
+  input: string,
+  start = 0,
+  end = input.length,
+): void {
+  if (
+    !Number.isFinite(end) ||
+    !Number.isFinite(start) ||
+    end < start ||
+    end > input.length
+  ) {
+    throw new TypeError('Invalid start or end position')
+  }
+  if (end === start) {
+    throw new InvalidDidError(input, `Empty method name`)
+  }
+
+  let c: number
+  for (let i = start; i < end; i++) {
+    c = input.charCodeAt(i)
+    if (
+      (c < 0x61 || c > 0x7a) && // a-z
+      (c < 0x30 || c > 0x39) // 0-9
+    ) {
+      throw new InvalidDidError(
+        input,
+        `Invalid character at position ${i} in DID method name`,
+      )
+    }
+  }
+}
+
+/**
+ * This method assumes the input is a valid Did
+ */
+export function extractDidMethod<D extends Did>(did: D) {
+  const msidSep = did.indexOf(':', DID_PREFIX_LENGTH)
+  const method = did.slice(DID_PREFIX_LENGTH, msidSep)
+  return method as D extends Did<infer M> ? M : string
+}
+
+/**
+ * DID Method-specific identifier check function.
+ *
+ * Check if the input is a valid DID method-specific identifier, at the position
+ * between `start` (inclusive) and `end` (exclusive).
+ */
+export function checkDidMsid(
+  input: string,
+  start = 0,
+  end = input.length,
+): void {
+  if (
+    !Number.isFinite(end) ||
+    !Number.isFinite(start) ||
+    end < start ||
+    end > input.length
+  ) {
+    throw new TypeError('Invalid start or end position')
+  }
+  if (end === start) {
+    throw new InvalidDidError(input, `DID method-specific id must not be empty`)
+  }
+
+  let c: number
+  for (let i = start; i < end; i++) {
+    c = input.charCodeAt(i)
+
+    // Check for frequent chars first
+    if (
+      (c < 0x61 || c > 0x7a) && // a-z
+      (c < 0x41 || c > 0x5a) && // A-Z
+      (c < 0x30 || c > 0x39) && // 0-9
+      c !== 0x2e && // .
+      c !== 0x2d && // -
+      c !== 0x5f // _
+    ) {
+      // Less frequent chars are checked here
+
+      // ":"
+      if (c === 0x3a) {
+        if (i === end - 1) {
+          throw new InvalidDidError(input, `DID cannot end with ":"`)
+        }
+        continue
+      }
+
+      // pct-encoded
+      if (c === 0x25) {
+        c = input.charCodeAt(++i)
+        if ((c < 0x30 || c > 0x39) && (c < 0x41 || c > 0x46)) {
+          throw new InvalidDidError(
+            input,
+            `Invalid pct-encoded character at position ${i}`,
+          )
+        }
+
+        c = input.charCodeAt(++i)
+        if ((c < 0x30 || c > 0x39) && (c < 0x41 || c > 0x46)) {
+          throw new InvalidDidError(
+            input,
+            `Invalid pct-encoded character at position ${i}`,
+          )
+        }
+
+        // There must always be 2 HEXDIG after a "%"
+        if (i >= end) {
+          throw new InvalidDidError(
+            input,
+            `Incomplete pct-encoded character at position ${i - 2}`,
+          )
+        }
+
+        continue
+      }
+
+      throw new InvalidDidError(
+        input,
+        `Disallowed character in DID at position ${i}`,
+      )
+    }
+  }
+}
+
+export function checkDid(input: unknown): asserts input is Did {
+  if (typeof input !== 'string') {
+    throw new InvalidDidError(typeof input, `DID must be a string`)
+  }
+
+  const { length } = input
+  if (length > 2048) {
+    throw new InvalidDidError(input, `DID is too long (2048 chars max)`)
+  }
+
+  if (!input.startsWith(DID_PREFIX)) {
+    throw new InvalidDidError(input, `DID requires "${DID_PREFIX}" prefix`)
+  }
+
+  const idSep = input.indexOf(':', DID_PREFIX_LENGTH)
+  if (idSep === -1) {
+    throw new InvalidDidError(input, `Missing colon after method name`)
+  }
+
+  checkDidMethod(input, DID_PREFIX_LENGTH, idSep)
+  checkDidMsid(input, idSep + 1, length)
+}
+
+export function isDid(input: unknown): input is Did {
+  try {
+    checkDid(input)
+    return true
+  } catch (err) {
+    if (err instanceof DidError) {
+      return false
+    }
+    throw err
+  }
+}
+
+export const didSchema = z
+  .string()
+  .superRefine((value: string, ctx: z.RefinementCtx): value is Did => {
+    try {
+      checkDid(value)
+      return true
+    } catch (err) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: err instanceof Error ? err.message : 'Unexpected error',
+      })
+      return false
+    }
+  })

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './did-document.js'
+export * from './did-error.js'
+export * from './did.js'
+export * from './methods.js'

package/src/methods/plc.ts

@@ -0,0 +1,40 @@
+import { InvalidDidError } from '../did-error.js'
+import { Did } from '../did.js'
+
+const DID_PLC_PREFIX = `did:plc:`
+const DID_PLC_PREFIX_LENGTH = DID_PLC_PREFIX.length
+const DID_PLC_LENGTH = 32
+
+export { DID_PLC_PREFIX }
+
+export function isDidPlc(input: unknown): input is Did<'plc'> {
+  if (typeof input !== 'string') return false
+  try {
+    checkDidPlc(input)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function checkDidPlc(input: string): asserts input is Did<'plc'> {
+  if (input.length !== DID_PLC_LENGTH) {
+    throw new InvalidDidError(
+      input,
+      `did:plc must be ${DID_PLC_LENGTH} characters long`,
+    )
+  }
+
+  if (!input.startsWith(DID_PLC_PREFIX)) {
+    throw new InvalidDidError(input, `Invalid did:plc prefix`)
+  }
+
+  let c: number
+  for (let i = DID_PLC_PREFIX_LENGTH; i < DID_PLC_LENGTH; i++) {
+    c = input.charCodeAt(i)
+    // Base32 encoding ([a-z2-7])
+    if ((c < 0x61 || c > 0x7a) && (c < 0x32 || c > 0x37)) {
+      throw new InvalidDidError(input, `Invalid character at position ${i}`)
+    }
+  }
+}

package/src/methods/web.ts

@@ -0,0 +1,78 @@
+import { InvalidDidError } from '../did-error.js'
+import { Did, checkDidMsid } from '../did.js'
+
+export const DID_WEB_PREFIX = `did:web:`
+
+/**
+ * This function checks if the input is a valid Web DID, as per DID spec.
+ * ATPROTO adds additional constraints to allowed DID values for the `did:web`
+ * method. Use {@link isAtprotoDidWeb} if that's what you need.
+ */
+export function isDidWeb(input: unknown): input is Did<'web'> {
+  if (typeof input !== 'string') return false
+  try {
+    didWebToUrl(input)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @see {@link https://atproto.com/specs/did#blessed-did-methods}
+ */
+export function isAtprotoDidWeb(input: unknown): input is Did<'web'> {
+  // Optimization: make cheap checks first
+  if (typeof input !== 'string') {
+    return false
+  }
+
+  // Path are not allowed
+  if (input.includes(':', DID_WEB_PREFIX.length)) {
+    return false
+  }
+
+  // Port numbers are not allowed, except for localhost
+  if (
+    input.includes('%3A', DID_WEB_PREFIX.length) &&
+    !input.startsWith('did:web:localhost%3A')
+  ) {
+    return false
+  }
+
+  return isDidWeb(input)
+}
+
+export function checkDidWeb(input: string): asserts input is Did<'web'> {
+  didWebToUrl(input)
+}
+
+export function didWebToUrl(did: string): URL {
+  if (!did.startsWith(DID_WEB_PREFIX)) {
+    throw new InvalidDidError(did, `did:web must start with ${DID_WEB_PREFIX}`)
+  }
+
+  if (did.charAt(DID_WEB_PREFIX.length) === ':') {
+    throw new InvalidDidError(did, 'did:web MSID must not start with a colon')
+  }
+
+  // Make sure every char is valid (per DID spec)
+  checkDidMsid(did, DID_WEB_PREFIX.length)
+
+  try {
+    const msid = did.slice(DID_WEB_PREFIX.length)
+    const parts = msid.split(':').map(decodeURIComponent)
+    return new URL(`https://${parts.join('/')}`)
+  } catch (cause) {
+    throw new InvalidDidError(did, 'Invalid Web DID', cause)
+  }
+}
+
+export function urlToDidWeb(url: URL): Did<'web'> {
+  const path =
+    url.pathname === '/'
+      ? ''
+      : url.pathname.slice(1).split('/').map(encodeURIComponent).join(':')
+
+  return `did:web:${encodeURIComponent(url.host)}${path ? `:${path}` : ''}`
+}

package/src/methods.ts

@@ -0,0 +1,2 @@
+export * from './methods/plc.js'
+export * from './methods/web.js'

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig/isomorphic.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "include": [],
+  "references": [{ "path": "./tsconfig.build.json" }]
+}