@atproto/oauth-provider 0.6.6 → 0.7.0

package/src/lib/http/request.ts

@@ -1,10 +1,13 @@
-import { randomBytes } from 'node:crypto'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { languages, mediaType } from '@hapi/accept'
-import { parse as parseCookie, serialize as serializeCookie } from 'cookie'
+import {
+  CookieSerializeOptions,
+  parse as parseCookie,
+  serialize as serializeCookie,
+} from 'cookie'
 import forwarded from 'forwarded'
 import createHttpError from 'http-errors'
-import { appendHeader } from './response.js'
+import { appendHeader } from './headers.js'
 import { UrlReference, urlMatch } from './url.js'
 
 export function validateHeaderValue(
@@ -30,7 +33,6 @@ export function validateHeaderValue(
 
 export function validateFetchMode(
   req: IncomingMessage,
-  res: ServerResponse,
   expectedMode: readonly (
     | null
     | 'navigate'
@@ -44,7 +46,6 @@ export function validateFetchMode(
 
 export function validateFetchDest(
   req: IncomingMessage,
-  res: ServerResponse,
   expectedDest: readonly (
     | null
     | 'document'
@@ -68,7 +69,6 @@ export function validateFetchDest(
 
 export function validateFetchSite(
   req: IncomingMessage,
-  res: ServerResponse,
   expectedSite: readonly (
     | null
     | 'same-origin'
@@ -80,103 +80,68 @@ export function validateFetchSite(
   validateHeaderValue(req, 'sec-fetch-site', expectedSite)
 }
 
-export function validateReferer(
+export function validateReferrer(
   req: IncomingMessage,
-  res: ServerResponse,
   reference: UrlReference,
   allowNull: true,
 ): URL | null
-export function validateReferer(
+export function validateReferrer(
   req: IncomingMessage,
-  res: ServerResponse,
   reference: UrlReference,
   allowNull?: false,
 ): URL
-export function validateReferer(
+export function validateReferrer(
   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(400, `Invalid referer ${referer}`)
+  // @NOTE The header name "referer" is actually a misspelling of the word
+  // "referrer". https://en.wikipedia.org/wiki/HTTP_referer
+  const referrer = req.headers['referer']
+  const referrerUrl = referrer ? new URL(referrer) : null
+  if (referrerUrl ? !urlMatch(referrerUrl, reference) : !allowNull) {
+    throw createHttpError(400, `Invalid referrer ${referrer}`)
   }
-  return refererUrl
+  return referrerUrl
 }
 
-export async function setupCsrfToken(
+export function validateOrigin(
   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,
+  expectedOrigin: string,
+  optional = true,
 ) {
   const reqOrigin = req.headers['origin']
-  if (reqOrigin ? reqOrigin !== origin : !allowNull) {
+  if (reqOrigin ? reqOrigin !== expectedOrigin : !optional) {
     throw createHttpError(400, `Invalid origin ${reqOrigin}`)
   }
 }
 
-export function validateCsrfToken(
-  req: IncomingMessage,
+export type { CookieSerializeOptions }
+
+export function setCookie(
   res: ServerResponse,
-  csrfToken: unknown,
-  cookieName = 'csrf_token',
-  clearCookie = false,
+  cookieName: string,
+  value: string,
+  options?: CookieSerializeOptions,
 ) {
-  const cookies = parseHttpCookies(req)
-  if (
-    typeof csrfToken !== 'string' ||
-    !csrfToken ||
-    !cookies ||
-    !cookieName ||
-    cookies[cookieName] !== csrfToken
-  ) {
-    throw createHttpError(400, `Invalid CSRF token`)
-  }
+  appendHeader(res, 'Set-Cookie', serializeCookie(cookieName, value, options))
+}
 
-  if (clearCookie) {
-    appendHeader(
-      res,
-      'Set-Cookie',
-      serializeCookie(cookieName, '', {
-        secure: true,
-        httpOnly: false,
-        sameSite: 'lax',
-        maxAge: 0,
-      }),
-    )
-  }
+export function clearCookie(
+  res: ServerResponse,
+  cookieName: string,
+  options?: Omit<CookieSerializeOptions, 'maxAge' | 'expires'>,
+) {
+  setCookie(res, cookieName, '', { ...options, 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
+  req: IncomingMessage & { cookies?: any },
+): Record<string, undefined | string> {
+  req.cookies ??= req.headers['cookie']
+    ? parseCookie(req.headers['cookie'])
+    : Object.create(null)
+  return req.cookies
 }
 
 export type ExtractRequestMetadataOptions = {

package/src/lib/http/response.ts

@@ -1,25 +1,14 @@
-import type { ServerResponse } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'node:http'
 import { type Readable, pipeline } from 'node:stream'
+import createHttpError from 'http-errors'
+import { Awaitable } from '../util/type.js'
+import { negotiateResponseContent } from './request.js'
 import {
   SecurityHeadersOptions,
   setSecurityHeaders,
 } from './security-headers.js'
 import type { Handler, Middleware } 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,
@@ -111,3 +100,38 @@ export function cacheControlMiddleware(maxAge: number): Middleware<void> {
     next()
   }
 }
+
+export function jsonHandler<
+  T,
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+>(
+  buildJson: (
+    this: T,
+    req: Req,
+    res: Res,
+  ) => Awaitable<{ payload: unknown; status?: number }>,
+): Middleware<T, Req, Res> {
+  return function (req, res, next) {
+    // Ensure we can agree on a content encoding & type before starting to
+    // build the JSON response.
+    if (negotiateResponseContent(req, ['application/json'])) {
+      // A middleware should not be async, so we wrap the async operation in a
+      // promise and return it.
+      void (async () => {
+        try {
+          const { payload, status = 200 } = await buildJson.call(this, req, res)
+          writeJson(res, payload, { status })
+        } catch (cause) {
+          const error =
+            cause instanceof Error
+              ? cause
+              : new Error('Failed to build JSON response', { cause })
+          next(error satisfies Error)
+        }
+      })()
+    } else {
+      next(createHttpError(406, 'Unsupported media type'))
+    }
+  }
+}

package/src/lib/http/route.ts

@@ -5,9 +5,12 @@ import { combineMiddlewares } from './middleware.js'
 import { Params, Path, createPathMatcher } from './path.js'
 import { Middleware } from './types.js'
 
-export type RouteCtx<T, P extends Params> = SubCtx<T, { params: Readonly<P> }>
+export type RouteCtx<
+  T extends object | void,
+  P extends Params = Params,
+> = SubCtx<T, { params: Readonly<P> }>
 export type RouteMiddleware<
-  T,
+  T extends object | void,
   P extends Params,
   Req = IncomingMessage,
   Res = ServerResponse,
@@ -28,8 +31,8 @@ export type RouteMiddleware<
  * ```
  */
 export function createRoute<
-  P extends Params,
-  T = void,
+  P extends Params = Params,
+  T extends object | void = void,
   Req extends IncomingMessage = IncomingMessage,
   Res extends ServerResponse = ServerResponse,
 >(
@@ -47,7 +50,7 @@ export function createRoute<
       const pathname = req.url?.split('?')[0] ?? '/'
       const params = paramsMatcher(pathname)
       if (params) {
-        const context = subCtx(this, 'params', params)
+        const context = subCtx(this, { params })
         return middleware.call(context, req, res, next)
       }
     }

package/src/lib/http/router.ts

@@ -1,33 +1,37 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { SubCtx, subCtx } from './context.js'
 import { MethodMatcherInput } from './method.js'
-import { asHandler, combineMiddlewares } from './middleware.js'
+import { combineMiddlewares } from './middleware.js'
 import { Params, Path } from './path.js'
 import { RouteMiddleware, createRoute } from './route.js'
 import { Middleware } from './types.js'
 
-export type RouterCtx<T> = SubCtx<T, { url: Readonly<URL> }>
+export type RouterCtx<T extends object | void = void> = SubCtx<
+  T,
+  { url: Readonly<URL> }
+>
+
 export type RouterMiddleware<
-  T = void,
+  T extends object | void = void,
   Req = IncomingMessage,
   Res = ServerResponse,
 > = Middleware<RouterCtx<T>, Req, Res>
 
+export type RouterConfig = {
+  /** 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
+}
+
 export class Router<
-  T = void,
+  T extends object | void = 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
-    },
-  ) {}
+  constructor(private readonly config?: RouterConfig) {}
 
   use(...middlewares: RouterMiddleware<T, Req, Res>[]) {
     this.middlewares.push(...middlewares)
@@ -73,8 +77,8 @@ export class Router<
   /**
    * @returns router middleware which dispatches a route matching the request.
    */
-  buildHandler() {
-    const routerUrl = this.url
+  buildMiddleware(): Middleware<T, Req, Res> {
+    const { config } = this
 
     // Calling next('router') from a middleware will skip all the remaining
     // middlewares in the stack.
@@ -82,38 +86,28 @@ export class Router<
       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 (cause) {
-          const error =
-            cause instanceof Error ? cause : new Error('Invalid URL', { cause })
-          return next(Object.assign(error, { status: 400, statusCode: 400 }))
-        }
-      }
-
-      const context = subCtx(this, 'url', url)
+    return function (this, req, res, next) {
+      // Parse the URL using node's URL parser.
+      const url = extractUrl(req, config)
+      if (url instanceof Error) return next(url)
+
+      // Any error thrown here will be uncaught/unhandled (a middleware should
+      // never throw)
+      const context = subCtx(this, { url })
       middleware.call(context, req, res, next)
-    })
+    }
+  }
+}
+
+function extractUrl(req: IncomingMessage, config?: RouterConfig): URL | Error {
+  try {
+    const protocol = config?.protocol || 'https:'
+    const host = config?.host || req.headers.host || 'localhost'
+    const pathname = req.url || '/'
+    return new URL(pathname, `${protocol}//${host}`)
+  } catch (cause) {
+    const error =
+      cause instanceof Error ? cause : new Error('Invalid URL', { cause })
+    return Object.assign(error, { status: 400, statusCode: 400 })
   }
 }

package/src/lib/http/security-headers.ts

@@ -75,7 +75,7 @@ export function setSecurityHeaders(
     res.setHeader('Strict-Transport-Security', buildHstsValue(hsts))
   }
 
-  // @TODO: make these headers configurable (?)
+  // @TODO make these headers configurable (?)
   res.setHeader('Permissions-Policy', 'otp-credentials=*, document-domain=()')
   res.setHeader('Referrer-Policy', 'same-origin')
   res.setHeader('X-Frame-Options', 'DENY')

package/src/lib/http/types.ts

@@ -6,12 +6,7 @@ export type Middleware<
   T = void,
   Req = IncomingMessage,
   Res = ServerResponse,
-> = (
-  this: T,
-  req: Req,
-  res: Res,
-  next: NextFunction,
-) => void | PromiseLike<void>
+> = (this: T, req: Req, res: Res, next: NextFunction) => void
 
 export type Handler<T = void, Req = IncomingMessage, Res = ServerResponse> = (
   this: T,

package/src/{output → lib}/send-web-page.ts

@@ -1,13 +1,13 @@
 import { createHash } from 'node:crypto'
 import type { ServerResponse } from 'node:http'
-import { CspConfig, CspValue, mergeCsp } from '../lib/csp/index.js'
+import { CspConfig, CspValue, mergeCsp } from './csp/index.js'
 import {
   AssetRef,
   BuildDocumentOptions,
   Html,
   buildDocument,
-} from '../lib/html/index.js'
-import { WriteHtmlOptions, writeHtml } from '../lib/http/response.js'
+} from './html/index.js'
+import { WriteHtmlOptions, writeHtml } from './http/response.js'
 
 export const DEFAULT_CSP: CspConfig = {
   'upgrade-insecure-requests': true,
@@ -16,10 +16,10 @@ export const DEFAULT_CSP: CspConfig = {
 
 export type SendWebPageOptions = BuildDocumentOptions & WriteHtmlOptions
 
-export async function sendWebPage(
+export function sendWebPage(
   res: ServerResponse,
   { csp: inputCsp, ...options }: SendWebPageOptions,
-): Promise<void> {
+): void {
   // @NOTE the csp string might be quite long. In that case it might be tempting
   // to set it through the http-equiv <meta> in the HTML. However, some
   // directives cannot be enforced by browsers when set through the meta tag
@@ -27,15 +27,16 @@ export async function sendWebPage(
   // HTTP header.
   const csp = mergeCsp(DEFAULT_CSP, inputCsp, {
     'base-uri': options.base?.origin as undefined | `https://${string}`,
-    'script-src': options.scripts?.map(assetToCsp),
-    'style-src': options.styles?.map(assetToCsp),
+    'script-src': options.scripts?.map(assetToCsp).filter((v) => v != null),
+    'style-src': options.styles?.map(assetToCsp).filter((v) => v != null),
   })
 
   const html = buildDocument(options).toString()
-  return writeHtml(res, html, { ...options, csp })
+  writeHtml(res, html, { ...options, csp })
 }
 
-function assetToCsp(asset: Html | AssetRef): CspValue {
+function assetToCsp(asset?: Html | AssetRef): undefined | CspValue {
+  if (asset == null) return undefined
   if (asset instanceof Html) {
     // Inline assets are "allowed" by their hash
     const hash = createHash('sha256')

package/src/lib/util/color.ts

@@ -0,0 +1,132 @@
+import { parseUi8Dec, parseUi8Hex } from './ui8.js'
+
+export type RgbColor = { r: number; g: number; b: number }
+export type HslColor = { h: number; s: number; l: number }
+export type RgbaColor = { r: number; g: number; b: number; a: number }
+export type HslaColor = { h: number; s: number; l: number; a: number }
+
+export function parseColor(color: string): RgbColor | RgbaColor {
+  if (color.startsWith('#')) {
+    return parseHexColor(color)
+  }
+
+  if (color.startsWith('rgba(')) {
+    return parseRgbaColor(color)
+  }
+
+  if (color.startsWith('rgb(')) {
+    return parseRgbColor(color)
+  }
+
+  // Should never happen (as long as the input is a validated WebColor)
+  throw new TypeError(`Invalid color value: ${color}`)
+}
+
+export function parseHexColor(v: string): RgbColor | RgbaColor {
+  // parseInt('az', 16) does not return NaN so we need to check the format
+  if (!/^#[0-9a-f]+$/i.test(v)) {
+    throw new TypeError(`Invalid hex color value: ${v}`)
+  }
+
+  if (v.length === 4 || v.length === 5) {
+    const r = parseUi8Hex(v[1].repeat(2))
+    const g = parseUi8Hex(v[2].repeat(2))
+    const b = parseUi8Hex(v[3].repeat(2))
+    const a = v.length > 4 ? parseUi8Hex(v[4].repeat(2)) : undefined
+    return a == null ? { r, g, b } : { r, g, b, a }
+  }
+
+  if (v.length === 7 || v.length === 9) {
+    const r = parseUi8Hex(v.slice(1, 3))
+    const g = parseUi8Hex(v.slice(3, 5))
+    const b = parseUi8Hex(v.slice(5, 7))
+    const a = v.length > 8 ? parseUi8Hex(v.slice(7, 9)) : undefined
+    return a == null ? { r, g, b } : { r, g, b, a }
+  }
+
+  throw new TypeError(`Invalid hex color value: ${v}`)
+}
+
+export function parseRgbColor(v: string): RgbColor {
+  const matches = v.match(/^\s*rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)\s*$/)
+  if (!matches) throw new TypeError(`Invalid rgb color value: ${v}`)
+
+  const r = parseUi8Dec(matches[1])
+  const g = parseUi8Dec(matches[2])
+  const b = parseUi8Dec(matches[3])
+  return { r, g, b }
+}
+
+export function parseRgbaColor(v: string): RgbaColor {
+  const matches = v.match(
+    /^\s*rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)\s*$/,
+  )
+  if (!matches) throw new TypeError(`Invalid rgba color value: ${v}`)
+
+  const r = parseUi8Dec(matches[1])
+  const g = parseUi8Dec(matches[2])
+  const b = parseUi8Dec(matches[3])
+  const a = parseUi8Dec(matches[4])
+  return { r, g, b, a }
+}
+
+/**
+ * Return the color that has the best contrast with the reference color.
+ */
+export function pickContrastColor(ref: RgbColor, a: RgbColor, b: RgbColor) {
+  return computeContrastRatio(ref, a) > computeContrastRatio(ref, b) ? a : b
+}
+
+/**
+ * @see {@link https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef}
+ */
+function relativeLuminance({ r, g, b }: RgbColor) {
+  return rgbLum(r) * 0.2126 + rgbLum(g) * 0.7152 + rgbLum(b) * 0.0722
+}
+
+function rgbLum(value) {
+  const rgb = value / 255
+  return rgb < 0.03928 ? rgb / 12.92 : Math.pow((rgb + 0.055) / 1.055, 2.4)
+}
+
+/**
+ * @see {@link https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef}
+ */
+function computeContrastRatio(a: RgbColor, b: RgbColor) {
+  const aLum = relativeLuminance(a)
+  const bLum = relativeLuminance(b)
+  const [lighter, darker] = aLum > bLum ? [aLum, bLum] : [bLum, aLum]
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+export function extractHue(input: RgbColor): number {
+  const r = input.r / 255
+  const g = input.g / 255
+  const b = input.b / 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+
+  const chroma = max - min
+
+  switch (max) {
+    case min:
+      return 0 // Achromatic
+    case r: {
+      const segment = (g - b) / chroma
+      const shift = segment < 0 ? 360 / 60 : 0 / 60
+      return 60 * (segment + shift)
+    }
+    case g: {
+      const segment = (b - r) / chroma
+      const shift = 120 / 60
+      return 60 * (segment + shift)
+    }
+    // "default" needed for type safety. In practice, should be same as "case b:"
+    default: {
+      const segment = (r - g) / chroma
+      const shift = 240 / 60
+      return 60 * (segment + shift)
+    }
+  }
+}

package/src/lib/util/crypto.ts

@@ -1,16 +1,21 @@
 import { randomBytes } from 'node:crypto'
 
-export async function randomHexId(bytesLength = 16) {
-  return new Promise<string>((resolve, reject) => {
+export async function randomBuffer(bytesLength = 16) {
+  return new Promise<Buffer>((resolve, reject) => {
     randomBytes(bytesLength, (err, buf) => {
       if (err) return reject(err)
-      resolve(buf.toString('hex'))
+      resolve(buf)
     })
   })
 }
 
+export async function randomHexId(bytesLength = 16) {
+  const buffer = await randomBuffer(bytesLength)
+  return buffer.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?
+// @TODO Is there a way to get this list from the runtime instead of hardcoding it?
 export const VERIFY_ALGOS = [
   'RS256',
   'RS384',

package/src/lib/util/function.ts

@@ -19,3 +19,17 @@ export async function callAsync<F extends (...args: any[]) => unknown>(
 ): Promise<Awaited<ReturnType<F>> | undefined> {
   return (await fn?.(...args)) as Awaited<ReturnType<F>> | undefined
 }
+
+export function invokeOnce<T extends (this: any, ...a: any[]) => any>(
+  fn: T,
+): T {
+  let fnNullable: T | null = fn
+  return function (...args) {
+    if (fnNullable) {
+      const fn = fnNullable
+      fnNullable = null
+      return fn.call(this, ...args)
+    }
+    throw new Error('Function called multiple times')
+  } as T
+}

package/src/lib/util/locale.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+
+export const localeSchema = z
+  .string()
+  .regex(/^[a-z]{2,3}(-[A-Z]{2})?$/, 'Invalid locale')
+export type Locale = z.infer<typeof localeSchema>
+
+export const multiLangStringSchema = z.intersection(
+  z.object({ en: z.string() }), // en is required
+  z.record(localeSchema, z.string().optional()),
+)
+export type MultiLangString = z.infer<typeof multiLangStringSchema>
+
+export const localizedStringSchema = z.union([
+  z.string(),
+  multiLangStringSchema,
+])
+export type LocalizedString = z.infer<typeof localizedStringSchema>