@atproto/oauth-provider 0.3.1 → 0.5.0

package/src/lib/hcaptcha.ts

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import {
+  Fetch,
+  FetchBound,
+  bindFetch,
+  fetchJsonProcessor,
+  fetchJsonZodProcessor,
+  fetchOkProcessor,
+} from '@atproto-labs/fetch'
+import { pipe } from '@atproto-labs/pipe'
+
+export const hcaptchaTokenSchema = z.string().min(1)
+export type HcaptchaToken = z.infer<typeof hcaptchaTokenSchema>
+
+export const hcaptchaConfigSchema = z.object({
+  /**
+   * The hCaptcha site key to use for the sign-up form.
+   */
+  siteKey: z.string().min(1),
+  /**
+   * The hCaptcha secret key to use for the sign-up form.
+   */
+  secretKey: z.string().min(1),
+  /**
+   * A salt to use when hashing client tokens.
+   */
+  tokenSalt: z.string().min(1),
+  /**
+   * The risk score over which the user is considered a threat and will be
+   * denied access. This will be ignored if the enterprise features are not
+   * available.
+   */
+  scoreThreshold: z.number().optional(),
+})
+export type HcaptchaConfig = z.infer<typeof hcaptchaConfigSchema>
+
+/**
+ * @see {@link https://docs.hcaptcha.com/#verify-the-user-response-server-side hCaptcha API}
+ */
+export const hcaptchaVerifyResultSchema = z.object({
+  /**
+   * is the passcode valid, and does it meet security criteria you specified, e.g. sitekey?
+   */
+  success: z.boolean(),
+  /**
+   * timestamp of the challenge (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
+   */
+  challenge_ts: z.string(),
+  /**
+   * the hostname of the site where the challenge was passed
+   */
+  hostname: z.string(),
+  /**
+   * optional: any error codes
+   */
+  'error-codes': z.array(z.string()),
+  /**
+   * ENTERPRISE feature: a score denoting malicious activity. Value ranges from
+   * 0.0 (no risk) to 1.0 (confirmed threat).
+   */
+  score: z.number().optional(),
+  /**
+   * ENTERPRISE feature: reason(s) for score.
+   */
+  score_reason: z.array(z.string()).optional(),
+  /**
+   * sitekey of the request
+   */
+  sitekey: z.string().optional(),
+  /**
+   * obj of form: {'ip_device': 1, .. etc}
+   */
+  behavior_counts: z.record(z.unknown()).optional(),
+  /**
+   * how similar is this? (0.0 - 1.0, -1 on err)
+   */
+  similarity: z.number().optional(),
+  /**
+   * count of similar_tokens not processed
+   */
+  similarity_failures: z.number().optional(),
+  /**
+   * array of strings for any similarity errors
+   */
+  similarity_error_details: z.array(z.string()).optional(),
+  /**
+   * encoded clientID
+   */
+  scoped_uid_0: z.string().optional(),
+  /**
+   * encoded IP
+   */
+  scoped_uid_1: z.string().optional(),
+  /**
+   * encoded IP (APT)
+   */
+  scoped_uid_2: z.string().optional(),
+  /**
+   * Risk Insights (APT + RI)
+   */
+  risk_insights: z.record(z.unknown()).optional(),
+  /**
+   * Advanced Threat Signatures (APT)
+   */
+  sigs: z.record(z.unknown()).optional(),
+  /**
+   * tags added via Rules
+   */
+  tags: z.array(z.string()).optional(),
+})
+
+export type HcaptchaVerifyResult = z.infer<typeof hcaptchaVerifyResultSchema>
+
+const fetchSuccessHandler = pipe(
+  fetchOkProcessor(),
+  fetchJsonProcessor(),
+  fetchJsonZodProcessor(hcaptchaVerifyResultSchema),
+)
+
+export class HCaptchaClient {
+  protected readonly fetch: FetchBound
+  constructor(
+    private readonly hostname: string,
+    private readonly config: HcaptchaConfig,
+    fetch: Fetch = globalThis.fetch,
+  ) {
+    this.fetch = bindFetch(fetch)
+  }
+
+  async verify(
+    behaviorType: 'login' | 'signup',
+    response: string,
+    remoteip: string,
+    handle: string,
+    userAgent?: string,
+  ) {
+    const result = await this.fetch('https://api.hcaptcha.com/siteverify', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        secret: this.config.secretKey,
+        sitekey: this.config.siteKey,
+        behavior_type: behaviorType,
+        response,
+        remoteip,
+        client_tokens: JSON.stringify({
+          hashedIp: this.hashToken(remoteip),
+          hashedHandle: this.hashToken(handle),
+          hashedUserAgent: userAgent ? this.hashToken(userAgent) : undefined,
+        }),
+      }).toString(),
+    }).then(fetchSuccessHandler)
+
+    return {
+      allowed: this.isAllowed(result),
+      result,
+    }
+  }
+
+  isAllowed({ success, hostname, score }: HcaptchaVerifyResult) {
+    return (
+      success &&
+      // Fool-proofing: If this is false, the user is trying to use a token
+      // generated for the same siteKey, but on another domain.
+      hostname === this.hostname &&
+      // Ignore if enterprise feature is not enabled
+      score != null &&
+      this.config.scoreThreshold != null &&
+      score < this.config.scoreThreshold
+    )
+  }
+
+  hashToken(value: string) {
+    const hash = createHash('sha256')
+    hash.update(this.config.tokenSalt)
+    hash.update(value)
+    return hash.digest().toString('base64')
+  }
+}

package/src/lib/html/build-document.ts

@@ -8,7 +8,43 @@ export type AssetRef = {
 }
 
 export type Attrs = Record<string, boolean | string | undefined>
-export type LinkAttrs = { href: string } & Attrs
+
+/**
+ * @see {@link https://developer.mozilla.org/fr/docs/Web/HTML/Attributes/rel}
+ */
+const ALLOWED_LINK_REL_VALUES = Object.freeze([
+  'alternate',
+  'author',
+  'canonical',
+  'dns-prefetch',
+  'external',
+  'expect',
+  'help',
+  'icon',
+  'license',
+  'manifest',
+  'me',
+  'modulepreload',
+  'next',
+  'pingback',
+  'preconnect',
+  'prefetch',
+  'preload',
+  'prerender',
+  'prev',
+  'privacy-policy',
+  'search',
+  'stylesheet',
+  'terms-of-service',
+] as const)
+export type LinkRel = (typeof ALLOWED_LINK_REL_VALUES)[number]
+export const isLinkRel = (rel: unknown): rel is LinkRel =>
+  (ALLOWED_LINK_REL_VALUES as readonly unknown[]).includes(rel)
+
+export type LinkAttrs = Attrs & {
+  href: string
+  rel: LinkRel
+}
 export type MetaAttrs =
   | { name: string; content: string }
   | { 'http-equiv': string; content: string }
@@ -27,7 +63,7 @@ export type BuildDocumentOptions = {
   title?: HtmlValue
   scripts?: readonly (Html | AssetRef)[]
   styles?: readonly (Html | AssetRef)[]
-  body: HtmlValue
+  body?: HtmlValue
   bodyAttrs?: Attrs
 }
 
@@ -50,12 +86,13 @@ export const buildDocument = ({
     ${base && html`<base href="${base.href}" />`}
     ${meta?.some(isViewportMeta) ? null : defaultViewport}
     ${meta?.map(metaToHtml)}
+    ${styles?.map(linkPreload('style'))}
+    ${scripts?.map(linkPreload('script'))}
     ${links?.map(linkToHtml)}
-    ${head} ${styles?.map(styleToHtml)}
+    ${head}
+    ${styles?.map(styleToHtml)}
   </head>
-  <body${attrsToHtml(bodyAttrs)}>
-    ${body} ${scripts?.map(scriptToHtml)}
-  </body>
+  <body${attrsToHtml(bodyAttrs)}>${body}${scripts?.map(scriptToHtml)}</body>
 </html>`
 
 function isViewportMeta<T extends MetaAttrs>(
@@ -64,12 +101,12 @@ function isViewportMeta<T extends MetaAttrs>(
   return 'name' in attrs && attrs.name === 'viewport'
 }
 
-function* linkToHtml(attrs: LinkAttrs) {
-  yield html`<link${attrsToHtml(attrs)} />`
+function linkToHtml(attrs: LinkAttrs) {
+  return html`<link${attrsToHtml(attrs)} />`
 }
 
-function* metaToHtml(attrs: MetaAttrs) {
-  yield html`<meta${attrsToHtml(attrs)} />`
+function metaToHtml(attrs: MetaAttrs) {
+  return html`<meta${attrsToHtml(attrs)} />`
 }
 
 function* attrsToHtml(attrs?: Attrs) {
@@ -83,16 +120,23 @@ function* attrsToHtml(attrs?: Attrs) {
   }
 }
 
-function* scriptToHtml(script: Html | AssetRef) {
-  yield script instanceof Html
+function linkPreload(as: 'script' | 'style') {
+  return (style: Html | AssetRef) =>
+    style instanceof Html
+      ? undefined
+      : html`<link rel="preload" href="${style.url}" as="${as}" />`
+}
+
+function scriptToHtml(script: Html | AssetRef) {
+  return script instanceof Html
     ? // prettier-ignore
       html`<script>${script}</script>` // hash validity requires no space around the content
-    : html`<script type="module" src="${script.url}?${script.sha256}"></script>`
+    : html`<script type="module" src="${script.url}"></script>`
 }
 
-function* styleToHtml(style: Html | AssetRef) {
-  yield style instanceof Html
+function styleToHtml(style: Html | AssetRef) {
+  return style instanceof Html
     ? // prettier-ignore
       html`<style>${style}</style>` // hash validity requires no space around the content
-    : html`<link rel="stylesheet" href="${style.url}?${style.sha256}" />`
+    : html`<link rel="stylesheet" href="${style.url}" />`
 }

package/src/lib/http/middleware.ts

@@ -2,6 +2,8 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import { writeJson } from './response.js'
 import { Handler, Middleware, NextFunction } from './types.js'
 
+const isNonNullable = <X>(x: X): x is NonNullable<X> => x != null
+
 export function combineMiddlewares<M extends Middleware<any, any, any>>(
   middlewares: Iterable<null | undefined | M>,
   options?: { skipKeyword?: string },
@@ -15,12 +17,11 @@ 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,
-  )
+  const middlewaresArray = Array.from(middlewares).filter(isNonNullable)
 
   // Optimization: if there are no middlewares, return a noop middleware.
   if (middlewaresArray.length === 0) return (req, res, next) => void next()
+  if (middlewaresArray.length === 1) return middlewaresArray[0]
 
   return function (req, res, next) {
     let i = 0

package/src/lib/http/request.ts

@@ -1,6 +1,8 @@
 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 forwarded from 'forwarded'
 import createHttpError from 'http-errors'
 import { appendHeader } from './response.js'
 import { UrlReference, urlMatch } from './url.js'
@@ -78,6 +80,18 @@ export function validateFetchSite(
   validateHeaderValue(req, 'sec-fetch-site', expectedSite)
 }
 
+export function validateReferer(
+  req: IncomingMessage,
+  res: ServerResponse,
+  reference: UrlReference,
+  allowNull: true,
+): URL | null
+export function validateReferer(
+  req: IncomingMessage,
+  res: ServerResponse,
+  reference: UrlReference,
+  allowNull?: false,
+): URL
 export function validateReferer(
   req: IncomingMessage,
   res: ServerResponse,
@@ -89,6 +103,7 @@ export function validateReferer(
   if (refererUrl ? !urlMatch(refererUrl, reference) : !allowNull) {
     throw createHttpError(400, `Invalid referer ${referer}`)
   }
+  return refererUrl
 }
 
 export async function setupCsrfToken(
@@ -125,12 +140,13 @@ export function validateSameOrigin(
 export function validateCsrfToken(
   req: IncomingMessage,
   res: ServerResponse,
-  csrfToken: string,
+  csrfToken: unknown,
   cookieName = 'csrf_token',
   clearCookie = false,
 ) {
   const cookies = parseHttpCookies(req)
   if (
+    typeof csrfToken !== 'string' ||
     !csrfToken ||
     !cookies ||
     !cookieName ||
@@ -164,7 +180,19 @@ export function parseHttpCookies(
 }
 
 export type ExtractRequestMetadataOptions = {
-  trustProxy?: boolean
+  /**
+   * A function that determines whether a given IP address is trusted. The
+   * function is called with the IP addresses and its index in the list of
+   * forwarded addresses (starting from 0, 0 corresponding to the ip of the
+   * incoming HTTP connection, and the last item being the first proxied IP
+   * address in the proxy chain, deduced from the `X-Forwarded-For` header). The
+   * function should return `true` if the IP address is trusted, and `false`
+   * otherwise.
+   *
+   * @see {@link https://www.npmjs.com/package/proxy-addr} for a utility that
+   * allows you to create a trust function.
+   */
+  trustProxy?: (addr: string, i: number) => boolean
 }
 
 export type RequestMetadata = {
@@ -177,42 +205,49 @@ export function extractRequestMetadata(
   req: IncomingMessage,
   options?: ExtractRequestMetadataOptions,
 ): RequestMetadata {
-  const userAgent = req.headers['user-agent'] || undefined
-  const ipAddress = extractIpAddress(req, options) || null
-  const port = extractPort(req, options)
-
-  if (ipAddress == null || port == null) {
-    throw new Error('Could not determine IP address')
+  const ip = extractIp(req, options)
+  return {
+    userAgent: req.headers['user-agent'],
+    ipAddress: ip,
+    port: extractPort(req, ip),
   }
-
-  return { userAgent, ipAddress, port }
 }
 
-function extractIpAddress(
+function extractIp(
   req: IncomingMessage,
   options?: ExtractRequestMetadataOptions,
-): string | undefined {
-  // Express app compatibility
-  if ('ip' in req && typeof req.ip === 'string') {
-    return req.ip
+): string {
+  const trust = options?.trustProxy
+  if (trust) {
+    const ips = forwarded(req)
+    for (let i = 0; i < ips.length; i++) {
+      const isTrusted = trust(ips[i], i)
+      if (!isTrusted) return ips[i]
+    }
+    // Let's return the last ("furthest") IP address in the chain if all of them
+    // are trusted. Note that this may indicate an issue with either the trust
+    // function (too permissive), or the proxy configuration (one of them not
+    // setting the X-Forwarded-For header).
+    const ip = ips[ips.length - 1]
+    if (ip) return ip
   }
 
-  if (options?.trustProxy) {
-    const forwardedFor = req.headers['x-forwarded-for']
-    if (typeof forwardedFor === 'string') {
-      const firstForward = forwardedFor.split(',')[0]!.trim()
-      if (firstForward) return firstForward
-    }
+  // Express app compatibility (see "trust proxy" setting)
+  if ('ip' in req) {
+    const ip = req.ip
+    if (typeof ip === 'string') return ip
   }
 
-  return req.socket.remoteAddress
+  const ip = req.socket.remoteAddress
+  if (ip) return ip
+
+  throw new Error('Could not determine IP address')
 }
 
-function extractPort(
-  req: IncomingMessage,
-  options?: ExtractRequestMetadataOptions,
-): number | undefined {
-  if (options?.trustProxy) {
+function extractPort(req: IncomingMessage, ip: string): number {
+  if (ip !== req.socket.remoteAddress) {
+    // Trust the X-Forwarded-Port header only if the IP address was a trusted
+    // proxied IP.
     const forwardedPort = req.headers['x-forwarded-port']
     if (typeof forwardedPort === 'string') {
       const port = Number(forwardedPort.trim())
@@ -223,5 +258,23 @@ function extractPort(
     }
   }
 
-  return req.socket.remotePort
+  const port = req.socket.remotePort
+  if (port != null) return port
+
+  throw new Error('Could not determine port')
+}
+
+export function extractLocales(req: IncomingMessage) {
+  const acceptLanguage = req.headers['accept-language']
+  return acceptLanguage ? languages(acceptLanguage) : []
+}
+
+export function negotiateResponseContent<T extends string>(
+  req: IncomingMessage,
+  types: readonly T[],
+): T | undefined {
+  const type = mediaType(req.headers['accept'], types)
+  if (type) return type as T
+
+  return undefined
 }

package/src/lib/http/response.ts

@@ -1,6 +1,6 @@
 import type { ServerResponse } from 'node:http'
 import { type Readable, pipeline } from 'node:stream'
-import { Handler } from './types.js'
+import type { Handler, Middleware } from './types.js'
 
 export function appendHeader(
   res: ServerResponse,
@@ -53,22 +53,27 @@ export function writeStream(
 export function writeBuffer(
   res: ServerResponse,
   chunk: string | Buffer,
-  {
-    status = 200,
-    contentType = 'application/octet-stream',
-  }: WriteResponseOptions = {},
+  opts: WriteResponseOptions,
 ): void {
-  res.statusCode = status
-  res.setHeader('content-type', contentType)
+  if (opts?.status != null) res.statusCode = opts.status
+  res.setHeader('content-type', opts?.contentType || 'application/octet-stream')
   res.end(chunk)
 }
 
+export function toJsonBuffer(value: unknown): Buffer {
+  try {
+    return Buffer.from(JSON.stringify(value))
+  } catch (cause) {
+    throw new Error(`Failed to serialize as JSON`, { cause })
+  }
+}
+
 export function writeJson(
   res: ServerResponse,
   payload: unknown,
   { contentType = 'application/json', ...options }: WriteResponseOptions = {},
 ): void {
-  const buffer = Buffer.from(JSON.stringify(payload))
+  const buffer = toJsonBuffer(payload)
   writeBuffer(res, buffer, { ...options, contentType })
 }
 
@@ -76,7 +81,7 @@ export function staticJsonMiddleware(
   value: unknown,
   { contentType = 'application/json', ...options }: WriteResponseOptions = {},
 ): Handler<unknown> {
-  const buffer = Buffer.from(JSON.stringify(value))
+  const buffer = toJsonBuffer(value)
   const staticOptions: WriteResponseOptions = { ...options, contentType }
   return function (req, res) {
     writeBuffer(res, buffer, staticOptions)
@@ -90,3 +95,11 @@ export function writeHtml(
 ): void {
   writeBuffer(res, html, { ...options, contentType })
 }
+
+export function cacheControlMiddleware(maxAge: number): Middleware<void> {
+  const header = `max-age=${maxAge}`
+  return function (req, res, next) {
+    res.setHeader('Cache-Control', header)
+    next()
+  }
+}

package/src/lib/locale.ts

@@ -0,0 +1,21 @@
+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.union([z.string(), z.undefined()])),
+)
+export type MultiLangString = z.infer<typeof multiLangStringSchema>
+
+export const AVAILABLE_LOCALES = [
+  // TODO: Add more in this list as translations are added in the PO files
+  'en',
+  'fr',
+] as const satisfies readonly Locale[]
+export type AvailableLocale = (typeof AVAILABLE_LOCALES)[number]
+export const isAvailableLocale = (v: unknown): v is AvailableLocale =>
+  (AVAILABLE_LOCALES as readonly unknown[]).includes(v)

package/src/lib/util/function.ts

@@ -6,17 +6,14 @@
  *   particularly useful when the function is a member of a "private" object.
  */
 export async function callAsync<F extends (...args: any[]) => unknown>(
-  this: ThisParameterType<F>,
   fn: F,
   ...args: Parameters<F>
 ): Promise<Awaited<ReturnType<F>>>
 export async function callAsync<F extends (...args: any[]) => unknown>(
-  this: ThisParameterType<F>,
   fn?: F,
   ...args: Parameters<F>
 ): Promise<Awaited<ReturnType<F>> | undefined>
 export async function callAsync<F extends (...args: any[]) => unknown>(
-  this: ThisParameterType<F>,
   fn?: F,
   ...args: Parameters<F>
 ): Promise<Awaited<ReturnType<F>> | undefined> {