was-teaching-server 0.9.1

package/src/corsProxy.ts

@@ -0,0 +1,326 @@
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify'
+import type { LookupFunction } from 'node:net'
+import net from 'node:net'
+import { lookup as dnsLookup } from 'node:dns/promises'
+import { fetch, Agent } from 'undici'
+
+const PROXY_TIMEOUT_MS = 10_000
+const MAX_REDIRECTS = 5
+
+/**
+ * Upper bound on the response body the proxy will buffer and relay. Caps memory
+ * use per proxied request and refuses to relay an oversized upstream response
+ * (enforced both from a declared `content-length` and while streaming).
+ */
+const PROXY_MAX_RESPONSE_BYTES = 10 * 1024 * 1024
+
+interface CorsProxyQuery {
+  url?: string
+}
+
+/**
+ * True for an IPv4 address in a private, loopback, link-local, or otherwise
+ * non-public range -- the SSRF-sensitive destinations the proxy must refuse
+ * (RFC 1918 private space, `127.0.0.0/8` loopback, `169.254.0.0/16` link-local
+ * -- which covers the `169.254.169.254` cloud-metadata endpoint -- CGNAT, and
+ * multicast/reserved). A syntactically invalid address is treated as blocked.
+ * @param ip {string}
+ * @returns {boolean}
+ */
+function isBlockedIpv4(ip: string): boolean {
+  const parts = ip.split('.').map(Number)
+  if (
+    parts.length !== 4 ||
+    parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return true
+  }
+  const [a, b] = parts as [number, number, number, number]
+  return (
+    a === 0 || // 0.0.0.0/8 "this network"
+    a === 10 || // private
+    a === 127 || // loopback
+    (a === 169 && b === 254) || // link-local (incl. cloud metadata)
+    (a === 172 && b >= 16 && b <= 31) || // private
+    (a === 192 && b === 168) || // private
+    (a === 100 && b >= 64 && b <= 127) || // CGNAT (RFC 6598)
+    (a === 192 && b === 0) || // 192.0.0.0/24 IETF protocol assignments
+    a >= 224 // multicast / reserved
+  )
+}
+
+/**
+ * True for an IPv6 address in a loopback, unspecified, unique-local (`fc00::/7`),
+ * or link-local (`fe80::/10`) range, or an IPv4-mapped/embedded address whose
+ * IPv4 form is blocked. A syntactically invalid address is treated as blocked.
+ * @param ip {string}
+ * @returns {boolean}
+ */
+function isBlockedIpv6(ip: string): boolean {
+  const lower = ip.toLowerCase()
+  const mapped = lower.match(/(?:^|:)(\d+\.\d+\.\d+\.\d+)$/)
+  if (mapped) {
+    return isBlockedIpv4(mapped[1]!)
+  }
+  return (
+    lower === '::' ||
+    lower === '::1' ||
+    lower.startsWith('fe8') || // fe80::/10 link-local
+    lower.startsWith('fe9') ||
+    lower.startsWith('fea') ||
+    lower.startsWith('feb') ||
+    lower.startsWith('fc') || // fc00::/7 unique-local
+    lower.startsWith('fd')
+  )
+}
+
+/**
+ * True for an IP the proxy must not reach. Unparseable input is blocked
+ * defensively.
+ * @param ip {string}
+ * @returns {boolean}
+ */
+function isBlockedIp(ip: string): boolean {
+  const family = net.isIP(ip)
+  if (family === 4) {
+    return isBlockedIpv4(ip)
+  }
+  if (family === 6) {
+    return isBlockedIpv6(ip)
+  }
+  return true
+}
+
+/**
+ * Parses and validates a single proxy target: `http`/`https` scheme only, and
+ * the host must not resolve to a blocked (private / loopback / link-local)
+ * address. Runs once for the client-supplied URL and again for every redirect
+ * hop, so an allowed public host cannot bounce the proxy to an internal one.
+ * Returns the exact addresses it validated so the caller can pin the upstream
+ * connection to them (closing the DNS-rebinding TOCTOU).
+ * @param target {string}
+ * @returns {Promise<{url: URL, addresses: {address: string, family: number}[]} | {status: number, error: string}>}
+ *   the parsed URL plus its validated addresses when allowed, or the HTTP
+ *   status + message to reject with.
+ */
+async function checkProxyTarget(
+  target: string
+): Promise<
+  | { url: URL; addresses: { address: string; family: number }[] }
+  | { status: number; error: string }
+> {
+  let parsed: URL
+  try {
+    parsed = new URL(target)
+  } catch {
+    return { status: 400, error: 'Invalid url query parameter' }
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return {
+      status: 400,
+      error: 'Only http and https URLs may be proxied.'
+    }
+  }
+
+  // Resolve the host and refuse private / loopback / link-local destinations
+  // (SSRF). `dns.lookup` returns the literal itself for an IP host, so
+  // IP-literal targets are covered too.
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, '')
+  let addresses: { address: string; family: number }[]
+  try {
+    addresses = await dnsLookup(hostname, { all: true })
+  } catch {
+    return { status: 502, error: 'Unable to resolve proxied host.' }
+  }
+  if (
+    addresses.length === 0 ||
+    addresses.some(({ address }) => isBlockedIp(address))
+  ) {
+    return { status: 403, error: 'Proxying to this host is not allowed.' }
+  }
+  return { url: parsed, addresses }
+}
+
+/**
+ * Builds the undici `connect.lookup` function that pins each upstream socket to
+ * the exact addresses `checkProxyTarget` already validated, keyed by hostname.
+ * The `fetch` still connects using the original hostname (so TLS certificate
+ * validation and SNI keep working) but resolves it only via this map, so a
+ * rebinding attacker cannot swap in a fresh, private address between validation
+ * and connection. A hostname absent from the map is refused (defense in depth:
+ * the agent must never resolve an unpinned host).
+ * @param pins {Map<string, {address: string, family: number}[]>} validated
+ *   addresses keyed by lower-cased hostname.
+ * @returns {LookupFunction} an undici/`net`-compatible lookup callback.
+ */
+export function createPinnedLookup(
+  pins: Map<string, { address: string; family: number }[]>
+): LookupFunction {
+  return function pinnedLookup(
+    hostname: string,
+    options: { all?: boolean },
+    callback: (
+      err: NodeJS.ErrnoException | null,
+      addressOrAddresses?: string | { address: string; family: number }[],
+      family?: number
+    ) => void
+  ): void {
+    const entries = pins.get(hostname.toLowerCase())
+    if (!entries || entries.length === 0) {
+      callback(new Error(`Refusing to resolve unpinned host: ${hostname}`))
+      return
+    }
+    if (options.all) {
+      callback(null, entries)
+      return
+    }
+    const first = entries[0]!
+    callback(null, first.address, first.family)
+  } as unknown as LookupFunction
+}
+
+/**
+ * Registers a server-side CORS proxy at `/api/cors`.
+ *
+ * Example:
+ * `/api/cors?url=https%3A%2F%2Fregistry.dcconsortium.org%2F.well-known%2Fopenid-federation`
+ *
+ * SSRF guard: only `http`/`https` URLs are proxied, and the target host is
+ * resolved and rejected when it maps to a private, loopback, or link-local
+ * address (e.g. `http://169.254.169.254/...` cloud-metadata, or an internal
+ * service). Redirects are followed manually (up to `MAX_REDIRECTS` hops) and
+ * every hop is re-validated the same way, so a public host cannot 3xx the
+ * proxy into an internal one. The addresses each hop validated are then pinned
+ * for the actual upstream connection (via a per-request undici `Agent` whose
+ * `connect.lookup` resolves only from that pin map), so a DNS-rebinding
+ * attacker cannot pass validation with a public IP and have the subsequent
+ * `fetch` re-resolve to a private one (closing the TOCTOU). The relayed
+ * response body is capped at `PROXY_MAX_RESPONSE_BYTES`, both from a declared
+ * `content-length` and while streaming. This is an unauthenticated open
+ * endpoint; adding a lightweight auth gate (a shared secret header, an
+ * allowlist of caller origins, or the server's own capability-invocation
+ * check) is a reasonable follow-up.
+ *
+ * @param app - Fastify instance
+ * @param _options - Fastify plugin options
+ */
+export async function initCorsProxyRoutes(
+  app: FastifyInstance,
+  _options: FastifyPluginOptions
+): Promise<void> {
+  app.get<{ Querystring: CorsProxyQuery }>(
+    '/api/cors',
+    async (request, reply) => {
+      const target = request.query.url
+
+      if (!target) {
+        return reply.code(400).send({ error: 'Missing url query parameter' })
+      }
+
+      const checked = await checkProxyTarget(target)
+      if (!('url' in checked)) {
+        return reply.code(checked.status).send({ error: checked.error })
+      }
+      let current = checked.url
+
+      const headers: Record<string, string> = {}
+      if (typeof request.headers.accept === 'string') {
+        headers.accept = request.headers.accept
+      }
+
+      // One undici Agent per proxied request, resolving each hop only via the
+      // addresses that hop already validated. The Agent must stay alive until
+      // the body is fully read, so it is torn down once in the finally below.
+      const pins = new Map<string, { address: string; family: number }[]>()
+      const pinKey = (url: URL) =>
+        url.hostname.replace(/^\[|\]$/g, '').toLowerCase()
+      pins.set(pinKey(current), checked.addresses)
+      const agent = new Agent({ connect: { lookup: createPinnedLookup(pins) } })
+
+      try {
+        for (let hop = 0; ; hop++) {
+          const upstream = await fetch(current.href, {
+            headers,
+            redirect: 'manual',
+            signal: AbortSignal.timeout(PROXY_TIMEOUT_MS),
+            dispatcher: agent
+          })
+
+          const location = upstream.headers.get('location')
+          if (upstream.status >= 300 && upstream.status < 400 && location) {
+            if (hop >= MAX_REDIRECTS) {
+              return reply
+                .code(502)
+                .send({ error: 'Too many proxied redirects.' })
+            }
+            let next: URL
+            try {
+              next = new URL(location, current)
+            } catch {
+              return reply
+                .code(502)
+                .send({ error: 'Invalid redirect from proxied URL.' })
+            }
+            const nextChecked = await checkProxyTarget(next.toString())
+            if (!('url' in nextChecked)) {
+              return reply
+                .code(nextChecked.status)
+                .send({ error: nextChecked.error })
+            }
+            current = nextChecked.url
+            pins.set(pinKey(current), nextChecked.addresses)
+            continue
+          }
+
+          // Refuse an upstream that declares a body larger than the cap before
+          // reading any of it.
+          const declaredLength = Number(upstream.headers.get('content-length'))
+          if (
+            Number.isFinite(declaredLength) &&
+            declaredLength > PROXY_MAX_RESPONSE_BYTES
+          ) {
+            return reply
+              .code(502)
+              .send({ error: 'Proxied response too large.' })
+          }
+
+          // Read incrementally so an undeclared (or lying) oversized body is
+          // stopped mid-stream rather than fully buffered. Upstream headers
+          // are copied only after the body is fully read, so a mid-stream
+          // rejection does not carry the upstream's content-type /
+          // content-length on the JSON error response.
+          const chunks: Buffer[] = []
+          if (upstream.body) {
+            const reader = upstream.body.getReader()
+            let total = 0
+            for (;;) {
+              const { done, value } = await reader.read()
+              if (done) {
+                break
+              }
+              total += value.byteLength
+              if (total > PROXY_MAX_RESPONSE_BYTES) {
+                await reader.cancel()
+                return reply
+                  .code(502)
+                  .send({ error: 'Proxied response too large.' })
+              }
+              chunks.push(Buffer.from(value))
+            }
+          }
+          upstream.headers.forEach((value, name) => reply.header(name, value))
+          return reply.code(upstream.status).send(Buffer.concat(chunks))
+        }
+      } catch (error) {
+        request.log.warn({ error, target }, 'CORS proxy fetch failed')
+        return reply.code(502).send({ error: 'Unable to fetch proxied URL' })
+      } finally {
+        // destroy(), not close(): early-exit paths (blocked redirect, too
+        // many redirects, oversized content-length) leave upstream bodies
+        // unconsumed, and close() would wait on them. Everything the reply
+        // sends is already buffered, so tearing down the sockets is safe.
+        await agent.destroy()
+      }
+    }
+  )
+}

package/src/declarations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ambient module declarations for runtime dependencies that do not ship their
+ * own types and lack an `@types/*` package.
+ *
+ * Minimal ambient declarations covering only the surface this codebase uses,
+ * for runtime dependencies that do not ship their own types and lack an
+ * `@types/*` package.
+ */
+
+declare module 'fs-json-store' {
+  export interface StoreOptions {
+    file: string
+  }
+
+  /** Reads/writes a single JSON document atomically to `options.file`. */
+  export class Store<T = unknown> {
+    constructor(options: StoreOptions)
+    /** Resolves the parsed document, or `undefined` if the file is absent. */
+    read(): Promise<T | undefined>
+    /** Writes the document and resolves the written value. */
+    write(data: T): Promise<T>
+  }
+
+  const _default: { Store: typeof Store }
+  export default _default
+}
+
+export {}

package/src/digest.ts

@@ -0,0 +1,223 @@
+/**
+ * Request Body Integrity (spec "Request Body Integrity (Digest Header)"): binds
+ * a request body to its HTTP Signature via the `Digest` header. Two hooks,
+ * installed by every route group alongside the auth hooks:
+ *
+ * - `captureRawBody` (preParsing) tees the exact body bytes onto
+ *   `request.rawBody` for JSON/text bodies, so the digest can be recomputed
+ *   against what the client actually signed. Re-serializing the parsed body is
+ *   not guaranteed byte-identical, so we keep the raw bytes instead. Streamed
+ *   bodies (multipart uploads, tar imports, raw blobs) are not buffered; instead
+ *   they pass through a hashing transform that verifies the `Digest`
+ *   incrementally at end-of-stream, so large/binary uploads keep streaming yet
+ *   are still bound to the signature.
+ * - `verifyBodyDigest` (preValidation) enforces, for any request carrying a
+ *   `Content-Type`: that the signature covers the `digest` header (MUST), that a
+ *   `Digest` header is present, and -- when the raw body was captured --
+ *   independently recomputes the body digest and compares it (SHOULD). A
+ *   missing, malformed, uncovered, or non-matching digest is rejected with
+ *   `invalid-authorization-header` (400).
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { verifyHeaderValue } from '@interop/http-digest-header'
+import { PassThrough, Transform, type Readable } from 'node:stream'
+import { createHash } from 'node:crypto'
+import { isJson } from './lib/isJson.js'
+import { InvalidDigestError } from './errors.js'
+
+/**
+ * True for the body shapes `verifyBodyDigest` recomputes: JSON
+ * (`application/json` / `+json`) and text. These reach handlers fully parsed
+ * (object / string), so buffering their bytes is cheap; streamed bodies
+ * (multipart, `application/x-tar`) are deliberately excluded.
+ * @param contentType {string | undefined}
+ * @returns {boolean}
+ */
+function isBufferableBody(contentType: string | undefined): boolean {
+  return (
+    isJson({ contentType }) ||
+    (typeof contentType === 'string' && contentType.startsWith('text/'))
+  )
+}
+
+/**
+ * Compares an incrementally-computed SHA-256 digest against a `Digest` header
+ * value, mirroring `@interop/http-digest-header`'s encodings without buffering
+ * the body: the multihash form (`mh=u<base64url(0x12 0x20 <digest>)>`, what WAS
+ * clients send) and the RFC 9651 `SHA-256=<base64>` form (colons stripped).
+ * @param options {object}
+ * @param options.sha256Digest {Buffer}   the computed 32-byte SHA-256 digest
+ * @param options.headerValue {string}   the request's `Digest` header value
+ * @returns {boolean}
+ */
+function digestMatches({
+  sha256Digest,
+  headerValue
+}: {
+  sha256Digest: Buffer
+  headerValue: string
+}): boolean {
+  const [key = '', rawValue] = headerValue.split(/=(.+)/)
+  if (key === 'mh') {
+    const multihash = Buffer.concat([Buffer.from([0x12, 0x20]), sha256Digest])
+    return rawValue === `u${multihash.toString('base64url')}`
+  }
+  if (key.replace('-', '').toLowerCase() === 'sha256') {
+    const expected = (rawValue ?? '').replace(/^:(.*):$/, '$1')
+    return expected === sha256Digest.toString('base64')
+  }
+  // Only SHA-256 is supported (as in the library); anything else cannot match.
+  return false
+}
+
+/**
+ * A pass-through Transform that hashes the streamed bytes (SHA-256) and, at
+ * end-of-stream, verifies the accumulated digest against the request's `Digest`
+ * header -- erroring the stream (which fails the write) on a mismatch. This
+ * binds a streamed/binary body to its signed `Digest` without buffering it. A
+ * mismatch surfaces mid-write; consumers that persist the stream remove any
+ * partial output on the resulting error (see the filesystem backend's blob
+ * write).
+ */
+class DigestVerifyStream extends Transform {
+  private readonly _hash = createHash('sha256')
+  private readonly _digestHeader: string
+  constructor(digestHeader: string) {
+    super()
+    this._digestHeader = digestHeader
+  }
+  override _transform(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    callback: (error?: Error | null, data?: Buffer) => void
+  ): void {
+    this._hash.update(chunk)
+    callback(null, chunk)
+  }
+  override _flush(callback: (error?: Error | null) => void): void {
+    const matched = digestMatches({
+      sha256Digest: this._hash.digest(),
+      headerValue: this._digestHeader
+    })
+    callback(
+      matched
+        ? null
+        : new InvalidDigestError({
+            detail: 'The `Digest` header does not match the request body.'
+          })
+    )
+  }
+}
+
+/**
+ * preParsing hook: for JSON/text bodies, tees the incoming payload into
+ * `request.rawBody` while passing the same bytes through to Fastify's content-
+ * type parser (so `verifyBodyDigest` can recompute the digest). Other (streamed)
+ * bodies are not buffered; when the request is signed with a `Digest` they pass
+ * through a `DigestVerifyStream` that verifies that digest incrementally, so a
+ * swapped binary/large body under a valid signed `Digest` is still rejected.
+ * @param request {import('fastify').FastifyRequest}
+ * @param reply {import('fastify').FastifyReply}
+ * @param payload {Readable}   the raw request body stream
+ * @returns {Promise<Readable>}   the stream Fastify should parse
+ */
+export async function captureRawBody(
+  request: FastifyRequest,
+  _reply: FastifyReply,
+  payload: Readable
+): Promise<Readable> {
+  if (!isBufferableBody(request.headers['content-type'])) {
+    // Streamed (non-buffered) body. Bind it to the signature by hashing it as it
+    // flows; an unsigned/anonymous body (no `Digest`) has nothing to verify.
+    // `parseAuthHeaders` (onRequest) has already run, so `request.zcap` is set
+    // for a signed request.
+    const digestHeader = request.zcap?.digest
+    if (!digestHeader) {
+      return payload
+    }
+    const verify = new DigestVerifyStream(digestHeader)
+    payload.on('error', err => verify.destroy(err))
+    return payload.pipe(verify)
+  }
+  const chunks: Buffer[] = []
+  const passthrough = new PassThrough()
+  payload.on('data', chunk => {
+    chunks.push(chunk as Buffer)
+    passthrough.write(chunk)
+  })
+  payload.on('end', () => {
+    request.rawBody = Buffer.concat(chunks)
+    passthrough.end()
+  })
+  payload.on('error', err => passthrough.destroy(err))
+  return passthrough
+}
+
+/**
+ * preValidation hook: enforces the `Digest` header binding for any request that
+ * carries a `Content-Type`. Bodyless requests (no `Content-Type`) and anonymous
+ * reads (no parsed `request.zcap`) are passed through.
+ * @param request {import('fastify').FastifyRequest}
+ * @param reply {import('fastify').FastifyReply}
+ * @returns {Promise<void>}
+ */
+export async function verifyBodyDigest(
+  request: FastifyRequest,
+  _reply: FastifyReply
+): Promise<void> {
+  // A provisioning-authorized request (onboarding token) is not signed, so
+  // there is no signature to cover a `Digest` header -- nothing to bind.
+  if (request.provisioningAuthorized) {
+    return
+  }
+  const contentType = request.headers['content-type']
+  // Bodyless requests carry no Content-Type and no Digest -- nothing to bind.
+  if (!contentType) {
+    return
+  }
+  // No parsed auth headers: writes require auth (the auth hooks 401 first), so a
+  // bodied request reaching here without `zcap` is a safe method that happens to
+  // carry a Content-Type; leave it to the handler's policy decision.
+  const { zcap } = request
+  if (!zcap) {
+    return
+  }
+
+  // MUST: `digest` is among the signature's covered (signed) headers. Guard the
+  // `headers` param itself: an `Authorization` header that omits `headers="..."`
+  // leaves it undefined, and splitting that would be a 500 rather than the
+  // intended `invalid-authorization-header` (400).
+  if (!zcap.headers || !zcap.headers.split(/\s+/).includes('digest')) {
+    throw new InvalidDigestError({
+      detail:
+        'The request signature must cover the `digest` header when the ' +
+        'request carries a body.'
+    })
+  }
+  // The `Digest` header itself MUST be present.
+  if (!zcap.digest) {
+    throw new InvalidDigestError({
+      detail: 'A `Digest` header is required when the request carries a body.'
+    })
+  }
+
+  // SHOULD: independently recompute and compare, when the raw body was captured.
+  // Streamed bodies (multipart, tar import, raw blobs) are not buffered here;
+  // `captureRawBody` has already wrapped them in a `DigestVerifyStream` that
+  // verifies the digest incrementally as the body is consumed.
+  if (request.rawBody === undefined) {
+    return
+  }
+  const { verified, error } = await verifyHeaderValue({
+    data: request.rawBody,
+    headerValue: zcap.digest
+  })
+  if (!verified) {
+    throw new InvalidDigestError({
+      detail: error
+        ? 'The `Digest` header is malformed or uses an unsupported algorithm.'
+        : 'The `Digest` header does not match the request body.',
+      cause: error
+    })
+  }
+}