@atproto/oauth-provider 0.1.0

package/src/lib/html/tags.ts

@@ -0,0 +1,58 @@
+import {
+  HtmlValue,
+  cssEscaper,
+  htmlEscaper,
+  javascriptEscaper,
+  jsonEscaper,
+} from './escapers.js'
+import { Html } from './html.js'
+
+export { type HtmlValue }
+export const html = (
+  tpl: TemplateStringsArray,
+  ...val: readonly HtmlValue[]
+) =>
+  tpl.length === 1 && val.length === 0
+    ? // Optimization for static HTML, avoid creating an iterable
+      Html.dangerouslyCreate(tpl)
+    : Html.dangerouslyCreate(htmlEscaper(tpl, val))
+
+/**
+ * Escapes code to use as a JavaScript string inside a `<script>` tag.
+ */
+export const javascriptCode = (code: string) =>
+  Html.dangerouslyCreate(javascriptEscaper(code))
+
+/**
+ * Creates an HTML safe JavaScript code block, with JSON serialization of the
+ * injected variables.
+ *
+ * @example
+ * ```js
+ * const dataOnTheServer = { foo: 'bar' };
+ * const clientScript = js`
+ *   const data = ${dataOnTheServer};
+ *   console.log(data);
+ * `
+ * console.log(clientScript.toString()); // Output: 'const data = {"foo":"bar"};console.log(data);'
+ * ```
+ */
+export const js = (tpl: TemplateStringsArray, ...val: readonly unknown[]) =>
+  tpl.length === 1 && val.length === 0
+    ? // Optimization for static JavaScript, avoid un-necessary serialization
+      javascriptCode(tpl[0])
+    : javascriptCode(String.raw({ raw: tpl }, ...val.map(jsonCode)))
+
+/**
+ * Escapes a value to be used as a JSON string inside a `<script>` tag.
+ *
+ * @see {@link https://redux.js.org/usage/server-rendering#security-considerations}
+ */
+export const jsonCode = (value: unknown) =>
+  Html.dangerouslyCreate(jsonEscaper(value))
+
+/**
+ * Escapes a value to be uses as CSS styles inside a `<style>` tag.
+ */
+export const cssCode = (code: string) =>
+  Html.dangerouslyCreate(cssEscaper(code))

package/src/lib/html/util.ts

@@ -0,0 +1,21 @@
+export type NestedIterable<V> = V | Iterable<NestedIterable<V>>
+
+export function* stringReplacer(
+  source: string,
+  searchValue: string,
+  replaceValue: string,
+): Generator<string, void, undefined> {
+  let previousIndex = 0
+  let index = source.indexOf(searchValue)
+  while (index !== -1) {
+    yield source.slice(previousIndex, index)
+    yield replaceValue
+    previousIndex = index + searchValue.length
+    index = source.indexOf(searchValue, previousIndex)
+  }
+  yield source.slice(previousIndex)
+}
+
+export function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}

package/src/lib/http/README.md

@@ -0,0 +1,11 @@
+# utilities for generating middlewares to work with Node's http module or Express / Connect frameworks
+
+This library uses a functional programming style to generate middleware
+functions that can be used with Node's http module or Express / Connect
+frameworks.
+
+This code _could_ be used as a standalone library, but the Bluesky dev team does
+not want to maintain it as such. As it is currently only used by the
+`@atproto/oauth-provider` package, it is included here. Future development
+should aim to keep this library independent of the rest of the
+`@atproto/oauth-provider` package, so that it can be extracted and published.

package/src/lib/http/accept.ts

@@ -0,0 +1,91 @@
+import { mediaType } from '@hapi/accept'
+
+import { SubCtx, subCtx } from './context.js'
+import {
+  IncomingMessage,
+  Middleware,
+  NextFunction,
+  ServerResponse,
+} from './types.js'
+
+type View<
+  T,
+  D,
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+> = (
+  this: SubCtx<T, { data: D }>,
+  req: Req,
+  res: Res,
+  next: NextFunction,
+) => void | PromiseLike<void>
+
+/**
+ * @example
+ * ```ts
+ *  app.use(
+ *    acceptMiddleware(
+ *      async function (req, res) {
+ *        return { hello: 'world' }
+ *      },
+ *      {
+ *        '': 'application/json', // Fallback to JSON
+ *        'text/plain': function (req, res) {
+ *           res.writeHead(200).end(this.data.hello)
+ *         },
+ *        'application/json': function (req, res) {
+ *          res.writeHead(200).end(JSON.stringify(this.data))
+ *        }
+ *      }
+ *    )
+ *  )
+ */
+export function acceptMiddleware<
+  D,
+  T = void,
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+>(
+  controller: (this: T, req: Req, res: Res) => D | PromiseLike<D>,
+  views: Record<string, string | View<T, D, Req, Res>>,
+  fallback: Middleware<T> = (req, res, _next) => void res.writeHead(406).end(),
+): (this: T, req: Req, res: Res, next: NextFunction) => Promise<void> {
+  const viewsMap = new Map(Object.entries(views))
+  const preferences = Array.from(viewsMap.keys()).filter(Boolean)
+
+  // Make sure that every view is either a function or a string that points to a
+  // function.
+  for (const type of viewsMap.keys()) {
+    const view = viewsMap.get(type)
+    if (typeof view === 'string' && typeof viewsMap.get(view) !== 'function') {
+      throw new Error(`Invalid view "${view}" for media type "${type}"`)
+    }
+  }
+
+  return async function (req, res, next) {
+    try {
+      const type = req.headers['accept']
+        ? mediaType(req.headers['accept'], preferences) || undefined
+        : '' // indicate that the client accepts anything
+
+      let view = type != null ? viewsMap.get(type) : undefined
+
+      if (typeof view === 'string') view = viewsMap.get(view)
+      if (typeof view === 'string') throw new Error('Invalid view') // should not happen
+
+      if (view) {
+        const data = await controller.call(this, req, res)
+        const ctx = subCtx(this, 'data', data)
+        if (type) res.setHeader('Content-Type', type)
+
+        await view.call(ctx, req, res, next)
+      } else {
+        // media negotiation failed
+        await fallback.call(this, req, res, next)
+      }
+    } catch (err) {
+      if (!res.headersSent) res.removeHeader('Content-Type')
+      next(err)
+    }
+  }
+}

package/src/lib/http/context.ts

@@ -0,0 +1,11 @@
+export type SubCtx<Parent, Child> = Child & Omit<Parent, keyof Child>
+
+export function subCtx<T, K extends string, V>(
+  ctx: T,
+  key: K,
+  value: V,
+): SubCtx<T, { [_ in K]: V }> {
+  return Object.create(typeof ctx === 'object' ? ctx : null, {
+    [key]: { value, enumerable: true, writable: false },
+  })
+}

package/src/lib/http/index.ts

@@ -0,0 +1,9 @@
+export * from './accept.js'
+export * from './context.js'
+export * from './middleware.js'
+export * from './parser.js'
+export * from './request.js'
+export * from './response.js'
+export * from './router.js'
+export * from './stream.js'
+export * from './types.js'

package/src/lib/http/method.ts

@@ -0,0 +1,18 @@
+import { IncomingMessage } from './types.js'
+
+export type MethodMatcherInput = string | Iterable<string> | MethodMatcher
+export type MethodMatcher = (req: IncomingMessage) => boolean
+
+export function createMethodMatcher(method: MethodMatcherInput): MethodMatcher {
+  if (method === '*') return () => true
+  if (typeof method === 'function') return method
+
+  if (typeof method === 'string') {
+    method = method.toUpperCase()
+    return (req) => req.method === method
+  }
+
+  const set = new Set(Array.from(method, (m) => m.toUpperCase()))
+  if (set.size === 0) return () => false
+  return (req) => req.method != null && set.has(req.method)
+}

package/src/lib/http/middleware.ts

@@ -0,0 +1,183 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { writeJson } from './response.js'
+import { Middleware, Handler, NextFunction } from './types.js'
+
+export function combineMiddlewares<M extends Middleware<any, any, any>>(
+  middlewares: Iterable<null | undefined | M>,
+  options?: { skipKeyword?: string },
+): M
+
+/**
+ * Combine express/connect like middlewares (that can be async) into a single
+ * middleware.
+ */
+export function combineMiddlewares(
+  middlewares: Iterable<null | undefined | Middleware<unknown>>,
+  { skipKeyword }: { skipKeyword?: string } = {},
+): Middleware<unknown> {
+  const middlewaresArray = Array.from(middlewares).filter(
+    (x): x is NonNullable<typeof x> => x != null,
+  )
+
+  // Optimization: if there are no middlewares, return a noop middleware.
+  if (middlewaresArray.length === 0) return (req, res, next) => void next()
+
+  return function (req, res, next) {
+    let i = 0
+    const nextMiddleware = (err?: unknown) => {
+      if (err) {
+        if (skipKeyword && err === skipKeyword) next()
+        else next(err)
+      } else if (i >= middlewaresArray.length) {
+        next()
+      } else {
+        const currentMiddleware = middlewaresArray[i++]!
+        const currentNext = once(nextMiddleware)
+        try {
+          const result = currentMiddleware.call(this, req, res, currentNext)
+          Promise.resolve(result).catch(currentNext)
+        } catch (err) {
+          currentNext(err)
+        }
+      }
+    }
+    nextMiddleware()
+  }
+}
+
+export type AsHandler<M extends Middleware<any, any, any>> =
+  M extends Middleware<infer T, infer Req, infer Res>
+    ? Handler<T, Req, Res>
+    : never
+
+/**
+ * Convert a middleware in a function that can be used as both a middleware and
+ * and handler.
+ */
+export function asHandler<M extends Middleware<any, any, any>>(
+  middleware: M,
+  options?: FinalHandlerOptions,
+) {
+  return function (
+    this,
+    req,
+    res,
+    next = once(createFinalHandler(req, res, options)),
+  ) {
+    return middleware.call(this, req, res, next)
+  } as AsHandler<M>
+}
+
+export type FinalHandlerOptions = {
+  debug?: boolean
+}
+
+export function createFinalHandler(
+  req: IncomingMessage,
+  res: ServerResponse,
+  options?: FinalHandlerOptions,
+): NextFunction {
+  return (err) => {
+    if (err && (options?.debug ?? process.env['NODE_ENV'] === 'development')) {
+      console.error(err)
+    }
+
+    if (res.headersSent) {
+      // If an error occurred, and headers were sent, we can't know that the
+      // whole response body was sent. So we can't safely reuse the socket.
+      if (err) req.socket.destroy()
+
+      return
+    }
+
+    const { status, ...payload } = buildFallbackPayload(req, err)
+
+    res.setHeader('Content-Security-Policy', "default-src 'none'")
+    res.setHeader('X-Content-Type-Options', 'nosniff')
+
+    writeJson(res, payload, status)
+  }
+}
+
+function buildFallbackPayload(
+  req: IncomingMessage,
+  err: unknown,
+): {
+  status: number
+  error: string
+  error_description: string
+  stack?: undefined | string
+} {
+  const status = err ? getErrorStatusCode(err) : 404
+  const expose = getProp(err, 'expose', 'boolean') ?? status < 500
+
+  return {
+    status,
+    error: err
+      ? expose
+        ? getProp(err, 'code', 'string') ??
+          getProp(err, 'error', 'string') ??
+          'unknown_error'
+        : 'system_error'
+      : 'not_found',
+    error_description:
+      err instanceof Error
+        ? expose
+          ? getProp(err, 'error_description', 'string') ||
+            String(err.message) ||
+            'Unknown error'
+          : 'System error'
+        : `Cannot ${req.method} ${req.url}`,
+    stack:
+      err instanceof Error && process.env['NODE_ENV'] === 'development'
+        ? err.stack
+        : undefined,
+  }
+}
+
+function getErrorStatusCode(err: NonNullable<unknown>): number {
+  const status =
+    getProp(err, 'status', 'number') ?? getProp(err, 'statusCode', 'number')
+  return status != null && status >= 400 && status < 600 ? status : 500
+}
+
+export function once<T extends NextFunction>(next: T): T {
+  let nextNullable: T | null = next
+  return function (err) {
+    if (!nextNullable) throw new Error('next() called multiple times')
+    const next = nextNullable
+    nextNullable = null
+    return next(err)
+  } as T
+}
+
+// eslint-disable-next-line
+function getProp(obj: unknown, key: string, t: 'function'): Function | undefined
+function getProp(obj: unknown, key: string, t: 'string'): string | undefined
+function getProp(obj: unknown, key: string, t: 'number'): number | undefined
+function getProp(obj: unknown, key: string, t: 'boolean'): boolean | undefined
+function getProp(obj: unknown, key: string, t: 'object'): object | undefined
+function getProp(obj: unknown, key: string, t: 'symbol'): symbol | undefined
+function getProp(obj: unknown, key: string, t: 'bigint'): bigint | undefined
+function getProp(obj: unknown, key: string, t: 'undefined'): undefined
+function getProp(
+  obj: unknown,
+  key: string,
+  type:
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'object'
+    | 'function'
+    | 'symbol'
+    | 'bigint'
+    | 'undefined',
+): unknown
+
+function getProp(obj: unknown, key: string, type: string): unknown {
+  if (obj != null && typeof obj === 'object' && key in obj) {
+    const value = (obj as Record<string, unknown>)[key]
+    if (typeof value === type) return value
+  }
+  return undefined
+}

package/src/lib/http/parser.ts

@@ -0,0 +1,64 @@
+import { parse as parseJson } from '@hapi/bourne'
+import createHttpError from 'http-errors'
+
+export type JsonScalar = string | number | boolean | null
+export type Json = JsonScalar | Json[] | { [_ in string]?: Json }
+
+export type Parser<T extends string = string, R = unknown> = {
+  readonly name: string
+  readonly test: (type: string) => type is T
+  readonly parse: (buffer: Buffer) => R
+}
+
+export type ParserName<P extends Parser> = P extends { readonly name: infer N }
+  ? N
+  : never
+export type ParserType<P extends Parser> = P extends Parser<infer T> ? T : never
+export type ParserResult<P extends Parser> = ReturnType<P['parse']>
+
+export type ParserForType<P extends Parser, T> =
+  P extends Parser<infer U> ? (U extends T ? P : never) : never
+
+export const parsers = [
+  {
+    name: 'json',
+    test: (
+      type: string,
+    ): type is `application/json` | `application/${string}+json` => {
+      return /^application\/(?:.+\+)?json$/.test(type)
+    },
+    parse: (buffer: Buffer): Json => {
+      try {
+        return parseJson(buffer.toString())
+      } catch (err) {
+        throw createHttpError(400, 'Invalid JSON', { cause: err })
+      }
+    },
+  },
+  {
+    name: 'urlencoded',
+    test: (type: string): type is 'application/x-www-form-urlencoded' => {
+      return type === 'application/x-www-form-urlencoded'
+    },
+    parse: (buffer: Buffer): Partial<Record<string, string>> => {
+      try {
+        if (!buffer.length) return {}
+        return Object.fromEntries(new URLSearchParams(buffer.toString()))
+      } catch (err) {
+        throw createHttpError(400, 'Invalid URL-encoded data', { cause: err })
+      }
+    },
+  },
+  {
+    name: 'bytes',
+    test: (type: string): type is 'application/octet-stream' => {
+      return type === 'application/octet-stream'
+    },
+    parse: (buffer: Buffer): Buffer => buffer,
+  },
+] as const satisfies Parser[]
+
+export type KnownParser = (typeof parsers)[number]
+
+export type KnownNames = KnownParser['name']
+export type KnownTypes = ParserType<KnownParser>

package/src/lib/http/path.ts

@@ -0,0 +1,82 @@
+export type PathMatcher<P extends Params> = (pathname: string) => P | undefined
+
+type StringPath<P extends Params> = string extends keyof P
+  ? `/${string}`
+  : keyof P extends never
+    ? `/${string}` | ``
+    : {
+        [K in keyof P]: K extends string
+          ?
+              | `${`/:${K}` | `/${string}/:${K}`}${StringPath<Omit<P, K>>}`
+              | `${StringPath<Omit<P, K>>}${`/:${K}` | `/:${K}/${string}`}`
+          : never
+      }[keyof P]
+
+export type Path<P extends Params> =
+  | string
+  | StringPath<P>
+  | RegExp
+  | PathMatcher<P>
+export type Params = Record<string, undefined | string>
+
+export function createPathMatcher<P extends Params = Params>(
+  refPath: Path<P>,
+): PathMatcher<P> {
+  if (typeof refPath === 'string') {
+    // Create a path matcher for a path with parameters (like /foo/:fooId/bar/:barId).
+    if (refPath.includes('/:')) {
+      const refParts = refPath
+        .slice(1)
+        .split('/')
+        .map((part, i) => [part, i] as const)
+      const refPartsLength = refParts.length
+
+      const staticParts = refParts.filter(([p]) => !p.startsWith(':'))
+      const paramParts = refParts
+        // Extract parameters, ignoring those with no name (like /foo/:/bar).
+        .filter(([p]) => p.startsWith(':') && p.length > 1)
+        .map(([p, i]) => [p.slice(1), i] as const)
+
+      return (reqPath: string) => {
+        const reqParts = reqPath.slice(1).split('/')
+
+        if (reqParts.length !== refPartsLength) return undefined
+
+        // Make sure all static parts match.
+        for (let i = 0; i < staticParts.length; i++) {
+          const value = staticParts[i]![0]
+          const idx = staticParts[i]![1]
+
+          if (value !== reqParts[idx]) return undefined
+        }
+
+        // Then extract the parameters.
+        const params: Record<string, string> = {}
+        for (let i = 0; i < paramParts.length; i++) {
+          const name = paramParts[i]![0]
+          const idx = paramParts[i]![1]
+
+          const value = reqParts[idx]
+
+          // Empty parameter values are not allowed.
+          if (!value) return undefined
+
+          params[name] = value
+        }
+
+        return params as P
+      }
+    }
+
+    return (reqPath: string) => (reqPath === refPath ? ({} as P) : undefined)
+  }
+
+  if (refPath instanceof RegExp) {
+    return (reqPath: string) => {
+      const match = reqPath.match(refPath)
+      return match ? ((match.groups || {}) as P) : undefined
+    }
+  }
+
+  return refPath
+}

package/src/lib/http/request.ts

@@ -0,0 +1,141 @@
+import { parse as parseCookie, serialize as serializeCookie } from 'cookie'
+import { randomBytes } from 'crypto'
+import createHttpError from 'http-errors'
+import { z } from 'zod'
+
+import { KnownNames } from './parser.js'
+import { appendHeader } from './response.js'
+import { decodeStream, parseStream } from './stream.js'
+import { IncomingMessage, ServerResponse } from './types.js'
+import { UrlReference, urlMatch } from './url.js'
+
+export function parseRequestPayload<
+  A extends readonly KnownNames[] = readonly KnownNames[],
+>(req: IncomingMessage, allow?: A) {
+  return parseStream(
+    decodeStream(req, req.headers['content-encoding']),
+    req.headers['content-type'],
+    allow,
+  )
+}
+
+export async function validateRequestPayload<S extends z.ZodTypeAny>(
+  req: IncomingMessage,
+  schema: S,
+  allow: readonly KnownNames[] = ['json', 'urlencoded'],
+): Promise<z.infer<S>> {
+  const payload = await parseRequestPayload(req, allow)
+  return schema.parseAsync(payload, { path: ['body'] })
+}
+
+export function validateFetchMode(
+  req: IncomingMessage,
+  res: ServerResponse,
+  expectedMode: readonly (
+    | null
+    | 'navigate'
+    | 'same-origin'
+    | 'no-cors'
+    | 'cors'
+  )[],
+) {
+  const reqMode = req.headers['sec-fetch-mode'] ?? null
+
+  if (Array.isArray(reqMode)) {
+    throw createHttpError(400, `Invalid sec-fetch-mode header`)
+  }
+
+  if (!(expectedMode as (string | null)[]).includes(reqMode)) {
+    throw createHttpError(
+      403,
+      reqMode
+        ? `Forbidden sec-fetch-mode "${reqMode}" (expected ${expectedMode})`
+        : `Missing sec-fetch-mode (expected ${expectedMode})`,
+    )
+  }
+}
+
+export function validateReferer(
+  req: IncomingMessage,
+  res: ServerResponse,
+  reference: UrlReference,
+  allowNull = false,
+) {
+  const referer = req.headers['referer']
+  const refererUrl = referer ? new URL(referer) : null
+  if (refererUrl ? !urlMatch(refererUrl, reference) : !allowNull) {
+    throw createHttpError(403, `Invalid referer ${referer}`)
+  }
+}
+
+export async function setupCsrfToken(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cookieName = 'csrf_token',
+) {
+  const csrfToken = randomBytes(8).toString('hex')
+  appendHeader(
+    res,
+    'Set-Cookie',
+    serializeCookie(cookieName, csrfToken, {
+      secure: true,
+      httpOnly: false,
+      sameSite: 'lax',
+      path: req.url?.split('?', 1)[0] || '/',
+    }),
+  )
+}
+
+// CORS ensure not cross origin
+export function validateSameOrigin(
+  req: IncomingMessage,
+  res: ServerResponse,
+  origin: string,
+  allowNull = true,
+) {
+  const reqOrigin = req.headers['origin']
+  if (reqOrigin ? reqOrigin !== origin : !allowNull) {
+    throw createHttpError(403, `Invalid origin ${reqOrigin}`)
+  }
+}
+
+export function validateCsrfToken(
+  req: IncomingMessage,
+  res: ServerResponse,
+  csrfToken: string,
+  cookieName = 'csrf_token',
+  clearCookie = false,
+) {
+  const cookies = parseHttpCookies(req)
+  if (
+    !csrfToken ||
+    !cookies ||
+    !cookieName ||
+    cookies[cookieName] !== csrfToken
+  ) {
+    throw createHttpError(403, `Invalid CSRF token`)
+  }
+
+  if (clearCookie) {
+    appendHeader(
+      res,
+      'Set-Cookie',
+      serializeCookie(cookieName, '', {
+        secure: true,
+        httpOnly: false,
+        sameSite: 'lax',
+        maxAge: 0,
+      }),
+    )
+  }
+}
+
+export function parseHttpCookies(
+  req: IncomingMessage,
+): null | Record<string, undefined | string> {
+  return 'cookies' in req && req.cookies // Already parsed by another middleware
+    ? (req.cookies as any)
+    : req.headers['cookie']
+      ? ((req as any).cookies = parseCookie(req.headers['cookie']))
+      : null
+}