@atproto/oauth-provider 0.1.0

package/src/lib/http/response.ts

@@ -0,0 +1,133 @@
+import { PassThrough, Readable, Transform } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { constants, createBrotliCompress, createGzip } from 'node:zlib'
+
+import { Handler, ServerResponse } from './types.js'
+
+export function appendHeader(
+  res: ServerResponse,
+  header: string,
+  value: string | readonly string[],
+): void {
+  const existing = res.getHeader(header)
+  if (existing == null) {
+    res.setHeader(header, value)
+  } else {
+    const arr = Array.isArray(existing) ? existing : [String(existing)]
+    res.setHeader(header, arr.concat(value))
+  }
+}
+
+export function writeRedirect(
+  res: ServerResponse,
+  url: string,
+  status = 302,
+): void {
+  res.writeHead(status, { Location: url }).end()
+}
+
+function negotiateEncoding(accept?: string | string[]) {
+  if (accept?.includes('br')) return 'br'
+  if (accept?.includes('gzip')) return 'gzip'
+  return 'identity'
+}
+
+function getEncoder(encoding: string): Transform {
+  switch (encoding) {
+    case 'br':
+      return createBrotliCompress({
+        // Default quality is too slow
+        params: { [constants.BROTLI_PARAM_QUALITY]: 5 },
+      })
+    case 'gzip':
+      return createGzip()
+    case 'identity':
+      return new PassThrough()
+    default:
+      throw new Error(`Unsupported encoding: ${encoding}`)
+  }
+}
+
+const ifString = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined
+
+export async function writeStream(
+  res: ServerResponse,
+  stream: Readable,
+  contentType = ifString((stream as any).headers?.['content-type']) ||
+    'application/octet-stream',
+  status = 200,
+): Promise<void> {
+  res.statusCode = status
+  res.setHeader('content-type', contentType)
+  appendHeader(res, 'vary', 'accept-encoding')
+
+  const encoding = negotiateEncoding(res.req.headers['accept-encoding'])
+
+  res.setHeader('content-encoding', encoding)
+  res.setHeader('transfer-encoding', 'chunked')
+
+  if (res.req.method === 'HEAD') {
+    res.end()
+    stream.destroy()
+    return
+  }
+
+  try {
+    await pipeline(stream, getEncoder(encoding), res)
+  } catch (err) {
+    // Prevent the socket from being left open in a bad state
+    res.socket?.destroy()
+
+    if (err != null && typeof err === 'object') {
+      // If an abort signal is used, we can consider this function's job successful
+      if ('name' in err && err.name === 'AbortError') return
+
+      // If the client closes the connection, we don't care about the error
+      if ('code' in err && err.code === 'ERR_STREAM_PREMATURE_CLOSE') return
+    }
+
+    throw err
+  }
+}
+
+export async function writeBuffer(
+  res: ServerResponse,
+  buffer: Buffer,
+  contentType?: string,
+  status = 200,
+): Promise<void> {
+  const stream = Readable.from([buffer])
+  return writeStream(res, stream, contentType, status)
+}
+
+export async function writeJson(
+  res: ServerResponse,
+  payload: unknown,
+  status = 200,
+  contentType = 'application/json',
+): Promise<void> {
+  const buffer = Buffer.from(JSON.stringify(payload))
+  return writeBuffer(res, buffer, contentType, status)
+}
+
+export function staticJsonHandler(
+  value: unknown,
+  contentType = 'application/json',
+  status = 200,
+): Handler<unknown> {
+  const buffer = Buffer.from(JSON.stringify(value))
+  return function (req, res, next) {
+    void writeBuffer(res, buffer, contentType, status).catch(next)
+  }
+}
+
+export async function writeHtml(
+  res: ServerResponse,
+  html: Buffer | string,
+  status = 200,
+  contentType = 'text/html',
+): Promise<void> {
+  const buffer = Buffer.isBuffer(html) ? html : Buffer.from(html)
+  return writeBuffer(res, buffer, contentType, status)
+}

package/src/lib/http/route.ts

@@ -0,0 +1,56 @@
+import { SubCtx, subCtx } from './context.js'
+import { MethodMatcherInput, createMethodMatcher } from './method.js'
+import { combineMiddlewares } from './middleware.js'
+import { Params, Path, createPathMatcher } from './path.js'
+import { IncomingMessage, Middleware, ServerResponse } from './types.js'
+
+export type RouteCtx<T, P extends Params> = SubCtx<T, { params: Readonly<P> }>
+export type RouteMiddleware<
+  T,
+  P extends Params,
+  Req = IncomingMessage,
+  Res = ServerResponse,
+> = Middleware<RouteCtx<T, P>, Req, Res>
+
+/**
+ * @example
+ * ```ts
+ * createRoute<{ foo: string }>('GET', '/foo/:foo', function (req, res) {
+ *   console.log(this.params.foo) // OK
+ *   console.log(this.params.bar) // Error
+ * })
+ *
+ * createRoute<{ foo: string }>(['POST', 'PUT'], '/foo/:foo', function (req, res) {
+ *   console.log(this.params.foo) // OK
+ *   console.log(this.params.bar) // Error
+ * })
+ * ```
+ */
+export function createRoute<
+  P extends Params,
+  T = void,
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+>(
+  method: MethodMatcherInput,
+  path: Path<P>,
+  ...mw: RouteMiddleware<T, P, Req, Res>[]
+): Middleware<T, Req, Res> {
+  const paramsMatcher = createPathMatcher<P>(path)
+  const methodMatcher = createMethodMatcher(method)
+
+  const middleware = combineMiddlewares(mw, { skipKeyword: 'route' })
+
+  return function (req, res, next) {
+    if (methodMatcher(req)) {
+      const pathname = req.url?.split('?')[0] ?? '/'
+      const params = paramsMatcher(pathname)
+      if (params) {
+        const context = subCtx(this, 'params', params)
+        return middleware.call(context, req, res, next)
+      }
+    }
+
+    return next()
+  }
+}

package/src/lib/http/router.ts

@@ -0,0 +1,118 @@
+import { SubCtx, subCtx } from './context.js'
+import { MethodMatcherInput } from './method.js'
+import { asHandler, combineMiddlewares } from './middleware.js'
+import { Params, Path } from './path.js'
+import { RouteMiddleware, createRoute } from './route.js'
+import { IncomingMessage, Middleware, ServerResponse } from './types.js'
+
+export type RouterCtx<T> = SubCtx<T, { url: Readonly<URL> }>
+export type RouterMiddleware<
+  T = void,
+  Req = IncomingMessage,
+  Res = ServerResponse,
+> = Middleware<RouterCtx<T>, Req, Res>
+
+export class Router<
+  T = void,
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+> {
+  private readonly middlewares: RouterMiddleware<T, Req, Res>[] = []
+
+  constructor(
+    private readonly url?: {
+      /** Used to build the origin of the {@link RouterCtx['url']} context property */
+      protocol?: string
+      /** Used to build the origin of the {@link RouterCtx['url']} context property */
+      host?: string
+    },
+  ) {}
+
+  use(...middlewares: RouterMiddleware<T, Req, Res>[]) {
+    this.middlewares.push(...middlewares)
+    return this
+  }
+
+  all<P extends Params = Params>(
+    path: Path<P>,
+    ...mw: RouteMiddleware<RouterCtx<T>, P, Req, Res>[]
+  ) {
+    return this.addRoute<P>('*', path, ...mw)
+  }
+
+  get<P extends Params = Params>(
+    path: Path<P>,
+    ...mw: RouteMiddleware<RouterCtx<T>, P, Req, Res>[]
+  ) {
+    return this.addRoute<P>('GET', path, ...mw)
+  }
+
+  post<P extends Params = Params>(
+    path: Path<P>,
+    ...mw: RouteMiddleware<RouterCtx<T>, P, Req, Res>[]
+  ) {
+    return this.addRoute<P>('POST', path, ...mw)
+  }
+
+  options<P extends Params = Params>(
+    path: Path<P>,
+    ...mw: RouteMiddleware<RouterCtx<T>, P, Req, Res>[]
+  ) {
+    return this.addRoute<P>('OPTIONS', path, ...mw)
+  }
+
+  addRoute<P extends Params>(
+    method: MethodMatcherInput,
+    path: Path<P>,
+    ...mw: RouteMiddleware<RouterCtx<T>, P, Req, Res>[]
+  ) {
+    return this.use(createRoute(method, path, ...mw))
+  }
+
+  /**
+   * @returns router middleware which dispatches a route matching the request.
+   */
+  buildHandler() {
+    const routerUrl = this.url
+
+    // Calling next('router') from a middleware will skip all the remaining
+    // middlewares in the stack.
+    const middleware = combineMiddlewares(this.middlewares, {
+      skipKeyword: 'router',
+    })
+
+    return asHandler<Middleware<T, Req, Res>>(function (this, req, res, next) {
+      // Make sure that the context contains a "url". This will allow the add()
+      // method to match routes based on the pathname and will allow routes to
+      // access the query params (through this.url.searchParams).
+      let url: URL
+
+      if (
+        !routerUrl &&
+        this != null &&
+        typeof this === 'object' &&
+        'url' in this &&
+        this.url instanceof URL
+      ) {
+        // If the context already contains a "url" (router inside router), let's
+        // use it.
+        url = this.url
+      } else {
+        // Parse the URL using node's URL parser.
+        try {
+          const protocol = routerUrl?.protocol || 'https:'
+          const host = req.headers.host || routerUrl?.host || 'localhost'
+          const pathname = req.url || '/'
+          url = new URL(pathname, `${protocol}//${host}`)
+        } catch (err) {
+          return next(
+            Object.assign(err as Error, { status: 400, statusCode: 400 }),
+          )
+        }
+      }
+
+      const context = subCtx(this, 'url', url)
+      middleware.call(context, req, res, next)
+    })
+  }
+}

package/src/lib/http/stream.ts

@@ -0,0 +1,78 @@
+import { PassThrough, Readable } from 'node:stream'
+import { createGunzip, createInflate } from 'node:zlib'
+
+import createHttpError from 'http-errors'
+
+import {
+  KnownNames,
+  KnownParser,
+  KnownTypes,
+  ParserForType,
+  ParserResult,
+  parsers,
+} from './parser.js'
+
+export async function readStream(req: Readable): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  let totalLength = 0
+  for await (const chunk of req) {
+    chunks.push(chunk)
+    totalLength += chunk.length
+  }
+  return Buffer.concat(chunks, totalLength)
+}
+
+export function decodeStream(
+  req: Readable,
+  encoding: string = 'identity',
+): Readable {
+  switch (encoding) {
+    case 'deflate':
+      return req.compose(createInflate())
+    case 'gzip':
+      return req.compose(createGunzip())
+    case 'identity':
+      return req.compose(new PassThrough())
+    default:
+      throw createHttpError(415, 'Unsupported content-encoding')
+  }
+}
+
+export async function parseStream<
+  T extends KnownTypes,
+  A extends readonly KnownNames[] = readonly KnownNames[],
+>(
+  req: Readable,
+  contentType: T,
+  allow?: A,
+): Promise<
+  ParserResult<ParserForType<Extract<KnownParser, { name: A[number] }>, T>>
+>
+export async function parseStream<
+  A extends readonly KnownNames[] = readonly KnownNames[],
+>(
+  req: Readable,
+  contentType: unknown,
+  allow?: A,
+): Promise<ParserResult<Extract<KnownParser, { name: A[number] }>>>
+export async function parseStream(
+  req: Readable,
+  contentType: unknown = 'application/octet-stream',
+  allow?: string[],
+): Promise<ParserResult<KnownParser>> {
+  if (typeof contentType !== 'string') {
+    throw createHttpError(400, 'Invalid content-type')
+  }
+
+  const parser = parsers.find(
+    (parser) =>
+      allow?.includes(parser.name) !== false && parser.test(contentType),
+  )
+
+  if (!parser) {
+    throw createHttpError(400, 'Unsupported content-type')
+  }
+
+  const buffer = await readStream(req)
+  return parser.parse(buffer)
+}

package/src/lib/http/types.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+export { IncomingMessage, ServerResponse }
+
+export type NextFunction = (err?: unknown) => void
+
+export type Middleware<
+  T = void,
+  Req = IncomingMessage,
+  Res = ServerResponse,
+> = (
+  this: T,
+  req: Req,
+  res: Res,
+  next: NextFunction,
+) => void | PromiseLike<void>
+
+export type Handler<T = void, Req = IncomingMessage, Res = ServerResponse> = (
+  this: T,
+  req: Req,
+  res: Res,
+  next?: NextFunction,
+) => void

package/src/lib/http/url.ts

@@ -0,0 +1,23 @@
+export type UrlReference = {
+  origin?: string
+  pathname?: string
+  searchParams?: Iterable<readonly [string, string]> // compatible with URLSearchParams
+}
+
+export function urlMatch(url: URL, reference: UrlReference) {
+  if (reference.origin !== undefined) {
+    if (url.origin !== reference.origin) return false
+  }
+
+  if (reference.pathname !== undefined) {
+    if (url.pathname !== reference.pathname) return false
+  }
+
+  if (reference.searchParams !== undefined) {
+    for (const [key, value] of reference.searchParams) {
+      if (url.searchParams.get(key) !== value) return false
+    }
+  }
+
+  return true
+}

package/src/lib/redis.ts

@@ -0,0 +1,23 @@
+import { Redis, type RedisOptions } from 'ioredis'
+
+export type { Redis, RedisOptions }
+
+export type CreateRedisOptions = Redis | RedisOptions | string
+
+export function createRedis(options: CreateRedisOptions): Redis {
+  if (options instanceof Redis) {
+    return options
+  } else if (typeof options === 'string') {
+    const url = new URL(
+      options.startsWith('redis://') ? options : `redis://${options}`,
+    )
+
+    return new Redis({
+      host: url.hostname,
+      port: parseInt(url.port, 10),
+      password: url.password,
+    })
+  } else {
+    return new Redis(options)
+  }
+}

package/src/lib/util/authorization-header.ts

@@ -0,0 +1,26 @@
+import { accessTokenSchema, oauthTokenTypeSchema } from '@atproto/oauth-types'
+import { z } from 'zod'
+
+import { InvalidRequestError } from '../../errors/invalid-request-error.js'
+import { WWWAuthenticateError } from '../../errors/www-authenticate-error.js'
+
+export const authorizationHeaderSchema = z.tuple([
+  oauthTokenTypeSchema,
+  accessTokenSchema,
+])
+
+export const parseAuthorizationHeader = (header?: string) => {
+  if (header == null) {
+    throw new WWWAuthenticateError(
+      'invalid_request',
+      'Authorization header required',
+      { Bearer: {}, DPoP: {} },
+    )
+  }
+
+  const parsed = authorizationHeaderSchema.safeParse(header.split(' ', 2))
+  if (!parsed.success) {
+    throw new InvalidRequestError('Invalid authorization header')
+  }
+  return parsed.data
+}

package/src/lib/util/cast.ts

@@ -0,0 +1,4 @@
+export function asArray<T>(value: T | T[]): T[] {
+  if (value == null) return []
+  return Array.isArray(value) ? value : [value]
+}

package/src/lib/util/crypto.ts

@@ -0,0 +1,27 @@
+import { randomBytes } from 'node:crypto'
+
+export async function randomHexId(bytesLength = 16) {
+  return new Promise<string>((resolve, reject) => {
+    randomBytes(bytesLength, (err, buf) => {
+      if (err) return reject(err)
+      resolve(buf.toString('hex'))
+    })
+  })
+}
+
+// Basically all algorithms supported by "jose"'s jwtVerify().
+// @TODO: Is there a way to get this list from the runtime instead of hardcoding it?
+export const VERIFY_ALGOS = [
+  'RS256',
+  'RS384',
+  'RS512',
+
+  'PS256',
+  'PS384',
+  'PS512',
+
+  'ES256',
+  'ES256K',
+  'ES384',
+  'ES512',
+] as const

package/src/lib/util/date.ts

@@ -0,0 +1,7 @@
+export function dateToEpoch(date: Date = new Date()) {
+  return Math.floor(date.getTime() / 1000)
+}
+
+export function dateToRelativeSeconds(date: Date) {
+  return Math.floor((date.getTime() - Date.now()) / 1000)
+}

package/src/lib/util/hostname.ts

@@ -0,0 +1,19 @@
+import { parse, ParsedDomain } from 'psl'
+
+export function isInternetHost(host: string): boolean {
+  return parseDomain(host) !== null
+}
+
+export function parseUrlDomain(input: string | URL): ParsedDomain | null {
+  const url = new URL(input)
+  return parseDomain(url.hostname)
+}
+
+export function parseDomain(domain: string) {
+  const parsed = parse(domain)
+  if ('listed' in parsed && parsed.listed && parsed.domain) {
+    return parsed
+  } else {
+    return null
+  }
+}

package/src/lib/util/redirect-uri.ts

@@ -0,0 +1,46 @@
+import { isLoopbackHost } from '@atproto/oauth-types'
+
+/**
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8252#section-8.4}
+ * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-8.4.2}
+ */
+export function compareRedirectUri(
+  allowed_uri: string,
+  request_uri: string,
+): boolean {
+  // https://datatracker.ietf.org/doc/html/rfc8252#section-8.4
+  //
+  // > Authorization servers MUST require clients to register their complete
+  // > redirect URI (including the path component) and reject authorization
+  // > requests that specify a redirect URI that doesn't exactly match the
+  // > one that was registered; the exception is loopback redirects, where
+  // > an exact match is required except for the port URI component.
+  if (allowed_uri === request_uri) return true
+
+  // https://datatracker.ietf.org/doc/html/rfc8252#section-7.3
+  const allowedUri = new URL(allowed_uri)
+  if (isLoopbackHost(allowedUri.hostname)) {
+    const requestUri = new URL(request_uri)
+
+    return (
+      // > The authorization server MUST allow any port to be specified at the
+      // > time of the request for loopback IP redirect URIs, to accommodate
+      // > clients that obtain an available ephemeral port from the operating
+      // > system at the time of the request
+      //
+      // Note: We only apply this rule if the allowed URI does not have a port
+      // specified.
+      (!allowedUri.port || allowedUri.port === requestUri.port) &&
+      allowedUri.hostname === requestUri.hostname &&
+      allowedUri.pathname === requestUri.pathname &&
+      allowedUri.protocol === requestUri.protocol &&
+      allowedUri.search === requestUri.search &&
+      allowedUri.hash === requestUri.hash &&
+      allowedUri.username === requestUri.username &&
+      allowedUri.password === requestUri.password
+    )
+  }
+
+  return false
+}

package/src/lib/util/time.ts

@@ -0,0 +1,33 @@
+import { Awaitable } from './type.js'
+
+/**
+ * Utility function to protect against timing attacks.
+ */
+export async function constantTime<T>(
+  delay: number,
+  fn: () => Awaitable<T>,
+): Promise<T> {
+  if (!Number.isFinite(delay) || delay <= 0) {
+    throw new TypeError('Delay must be greater than 0')
+  }
+
+  const start = Date.now()
+  try {
+    return await fn()
+  } finally {
+    const delta = Date.now() - start
+
+    // Let's make sure we always wait for a multiple of `delay` milliseconds.
+    const n = Math.max(1, Math.ceil(delta / delay))
+
+    // Ideally, the multiple should always be 1 in order to to properly defend
+    // against timing attacks. Show a warning if it's not.
+    if (n > 1) {
+      console.warn(
+        `constantTime: execution time was ${delta}ms, waiting for the next multiple of ${delay}ms. You should increase the delay to properly defend against timing attacks.`,
+      )
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, n * delay))
+  }
+}

package/src/lib/util/type.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type Simplify<T> = { [K in keyof T]: T[K] } & {}
+export type Override<T, V> = Simplify<V & Omit<T, keyof V>>
+export type Awaitable<T> = T | Promise<T>

package/src/lib/util/well-known.ts

@@ -0,0 +1,8 @@
+export function buildWellknownUrl(url: URL, name: string): URL {
+  const path =
+    url.pathname === '/'
+      ? `/.well-known/${name}`
+      : `${url.pathname.replace(/\/+$/, '')}/${name}`
+
+  return new URL(path, url)
+}