acrylblends 0.2.0 → 0.4.0

package/plugins/acryl-router/src/core/validator/validator.ts

@@ -0,0 +1,185 @@
+import type { Context } from '../context.ts'
+import { getCookie } from '../helper/cookie/index.ts'
+import { HTTPException } from '../http-exception.ts'
+import type { Env, MiddlewareHandler, TypedResponse, ValidationTargets, FormValue } from '../types.ts'
+import type { BodyData } from '../utils/body.ts'
+import { bufferToFormData } from '../utils/buffer.ts'
+import type { InferInput } from './utils.ts'
+
+type ValidationTargetKeysWithBody = 'form' | 'json'
+type ValidationTargetByMethod<M> = M extends 'get' | 'head' // GET and HEAD request must not have a body content.
+  ? Exclude<keyof ValidationTargets, ValidationTargetKeysWithBody>
+  : keyof ValidationTargets
+
+export type ValidationFunction<
+  InputType,
+  OutputType,
+  E extends Env = {},
+  P extends string = string,
+> = (
+  value: InputType,
+  c: Context<E, P>
+) => OutputType | TypedResponse | Promise<OutputType> | Promise<TypedResponse>
+
+const jsonRegex = /^application\/([a-z-\.]+\+)?json(;\s*[a-zA-Z0-9\-]+\=([^;]+))*$/i
+const multipartRegex = /^multipart\/form-data(;\s?boundary=[a-zA-Z0-9'"()+_,\-./:=?]+)?$/i
+const urlencodedRegex = /^application\/x-www-form-urlencoded(;\s*[a-zA-Z0-9\-]+\=([^;]+))*$/i
+
+export type ExtractValidationResponse<VF> = VF extends (value: any, c: any) => infer R
+  ? R extends Promise<infer PR>
+    ? PR extends TypedResponse<infer T, infer S, infer F>
+      ? TypedResponse<T, S, F>
+      : PR extends Response
+        ? PR
+        : PR extends undefined
+          ? never // undefined → never
+          : never // anything else → never
+    : R extends TypedResponse<infer T, infer S, infer F>
+      ? TypedResponse<T, S, F>
+      : R extends Response
+        ? R
+        : R extends undefined
+          ? never // undefined → never
+          : never // anything else → never
+  : never // Can't extract → never
+
+export const validator = <
+  InputType,
+  P extends string,
+  M extends string,
+  U extends ValidationTargetByMethod<M>,
+  P2 extends string = P,
+  // Capture the actual validation function as a type
+  VF extends (
+    value: unknown extends InputType ? ValidationTargets[U] : InputType,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    c: Context<any, P2>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ) => any = (
+    value: unknown extends InputType ? ValidationTargets[U] : InputType,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    c: Context<any, P2>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ) => any,
+  V extends {
+    in: {
+      [K in U]: K extends 'json'
+        ? unknown extends InputType
+          ? ExtractValidatorOutput<VF>
+          : InputType
+        : InferInput<ExtractValidatorOutput<VF>, K, FormValue>
+    }
+    out: { [K in U]: ExtractValidatorOutput<VF> }
+  } = {
+    in: {
+      [K in U]: K extends 'json'
+        ? unknown extends InputType
+          ? ExtractValidatorOutput<VF>
+          : InputType
+        : InferInput<ExtractValidatorOutput<VF>, K, FormValue>
+    }
+    out: { [K in U]: ExtractValidatorOutput<VF> }
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  E extends Env = any,
+>(
+  target: U,
+  validationFunc: VF
+): MiddlewareHandler<E, P, V, ExtractValidationResponse<VF>> => {
+  return async (c, next) => {
+    let value = {}
+    const contentType = c.req.header('Content-Type')
+
+    switch (target) {
+      case 'json':
+        if (!contentType || !jsonRegex.test(contentType)) {
+          break
+        }
+        try {
+          value = await c.req.json()
+        } catch {
+          const message = 'Malformed JSON in request body'
+          throw new HTTPException(400, { message })
+        }
+        break
+      case 'form': {
+        if (
+          !contentType ||
+          !(multipartRegex.test(contentType) || urlencodedRegex.test(contentType))
+        ) {
+          break
+        }
+
+        let formData: FormData
+
+        if (c.req.bodyCache.formData) {
+          formData = await c.req.bodyCache.formData
+        } else {
+          try {
+            const arrayBuffer = await c.req.arrayBuffer()
+            formData = await bufferToFormData(arrayBuffer, contentType)
+            c.req.bodyCache.formData = formData
+          } catch (e) {
+            let message = 'Malformed FormData request.'
+            message += e instanceof Error ? ` ${e.message}` : ` ${String(e)}`
+            throw new HTTPException(400, { message })
+          }
+        }
+
+        const form: BodyData<{ all: true }> = Object.create(null)
+        formData.forEach((value, key) => {
+          if (key.endsWith('[]')) {
+            ;((form[key] ??= []) as unknown[]).push(value)
+          } else if (Array.isArray(form[key])) {
+            ;(form[key] as unknown[]).push(value)
+          } else if (Object.hasOwn(form, key)) {
+            form[key] = [form[key] as string | File, value]
+          } else {
+            form[key] = value
+          }
+        })
+        value = form
+        break
+      }
+      case 'query':
+        value = Object.fromEntries(
+          Object.entries(c.req.queries()).map(([k, v]) => {
+            return v.length === 1 ? [k, v[0]] : [k, v]
+          })
+        )
+        break
+      case 'param':
+        value = c.req.param() as Record<string, string>
+        break
+      case 'header':
+        value = c.req.header()
+        break
+      case 'cookie':
+        value = getCookie(c)
+        break
+    }
+
+    const res = await validationFunc(value as never, c as never)
+
+    if (res instanceof Response) {
+      return res as ExtractValidationResponse<VF>
+    }
+
+    c.req.addValidatedData(target, res as never)
+
+    return (await next()) as ExtractValidationResponse<VF>
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ExtractValidatorOutput<VF> = VF extends (value: any, c: any) => infer R
+  ? R extends Promise<infer PR>
+    ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      PR extends Response | TypedResponse<any, any, any>
+      ? never
+      : PR
+    : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      R extends Response | TypedResponse<any, any, any>
+      ? never
+      : R
+  : never

package/plugins/acryl-router/src/helpers/index.ts

@@ -0,0 +1,13 @@
+export { getConnInfo, connectionOf } from '../connection.ts'
+export type { AddressType, ConnInfo, GetConnInfo, NetAddrInfo } from '../core/helper/conninfo/index.ts'
+export { accepts } from '../core/helper/accepts/index.ts'
+export { createFactory, createMiddleware, Factory } from '../core/helper/factory/index.ts'
+export { deleteCookie, generateCookie, generateSignedCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from '../core/helper/cookie/index.ts'
+export { getExtension, getMimeType, mimes, type BaseMime } from '../core/utils/mime.ts'
+export { html, raw } from '../core/helper/html/index.ts'
+export { matchedRoutes, routePath, baseRoutePath, basePath } from '../core/helper/route/index.ts'
+export { testClient } from '../core/helper/testing/index.ts'
+export { stream, streamSSE, streamText, SSEStreamingApi, type SSEMessage } from '../core/helper/streaming/index.ts'
+export { validator, type ValidationFunction } from '../core/validator/index.ts'
+export { schemaValidator, type StandardSchema } from './schema-validator.ts'
+export { createWSMessageEvent, defineWebSocketHelper, WSContext, type SendOptions, type UpgradeWebSocket, type WSContextInit, type WSEvents, type WSMessageReceive, type WSReadyState } from '../core/helper/websocket/index.ts'

package/plugins/acryl-router/src/helpers/schema-validator.ts

@@ -0,0 +1,35 @@
+import type { Env, MiddlewareHandler, ValidationTargets } from '../core/types.ts'
+import { validator } from '../core/validator/index.ts'
+
+/** The slice of the Standard Schema interface this needs; Schemastery (what Cordis uses), Zod and Valibot all implement it. */
+export interface StandardSchema<T = unknown> {
+  readonly '~standard': {
+    validate(value: unknown): StandardResult<T> | Promise<StandardResult<T>>
+  }
+}
+
+type StandardResult<T> =
+  | { readonly value: T, readonly issues?: undefined }
+  | { readonly issues: readonly { readonly message: string, readonly path?: readonly unknown[] | undefined }[] }
+
+const pathOf = (path: readonly unknown[] | undefined): string =>
+  (path ?? []).map(part => String(typeof part === 'object' && part !== null && 'key' in part ? (part as { key: unknown }).key : part)).join('.')
+
+/**
+ * The core `validator` driven by a Standard Schema. A failure answers 400 with `{ error, issues }`; success makes the parsed value the
+ * handler's `c.req.valid(target)`, typed by the schema.
+ */
+export function schemaValidator<Target extends keyof ValidationTargets, Out, E extends Env = Env, P extends string = string>(
+  target: Target,
+  schema: StandardSchema<Out>,
+): MiddlewareHandler<E, P, { in: { [K in Target]: Out }, out: { [K in Target]: Out } }> {
+  const middleware = validator(target, async (value, c) => {
+    const result = await schema['~standard'].validate(value)
+    if (result.issues !== undefined) {
+      return c.json({ error: `invalid ${target}`, issues: result.issues.map(issue => ({ message: issue.message, path: pathOf(issue.path) })) }, 400)
+    }
+    return result.value
+  })
+  // The core infers its own input and output types from the function; the schema's output type is the one a handler should see.
+  return middleware as unknown as MiddlewareHandler<E, P, { in: { [K in Target]: Out }, out: { [K in Target]: Out } }>
+}

package/plugins/acryl-router/src/index.ts

@@ -0,0 +1,6 @@
+export { Router, Config, apply, name, type MountableApp, type RouterHttpService, type TrailingSlash } from './service.ts'
+export { connectionOf, getConnInfo, type ConnectionInfo, type RouterBindings, type RouterEnv } from './connection.ts'
+export { App, Context } from './core/index.ts'
+export type { AppRequest, ContextRenderer, ContextVariableMap, Env, ErrorHandler, ExecutionContext, Handler, Input, MiddlewareHandler, Next, NotFoundHandler, NotFoundResponse, Schema, ToSchema, TypedResponse, ValidationTargets } from './core/index.ts'
+export { HTTPException } from './core/http-exception.ts'
+export type { ContentfulStatusCode, StatusCode } from './core/utils/http-status.ts'

package/plugins/acryl-router/src/middleware/index.ts

@@ -0,0 +1,25 @@
+export { basicAuth } from '../core/middleware/basic-auth/index.ts'
+export { bearerAuth } from '../core/middleware/bearer-auth/index.ts'
+export { bodyLimit } from '../core/middleware/body-limit/index.ts'
+export { every, except, some } from '../core/middleware/combine/index.ts'
+export { compress } from '../core/middleware/compress/index.ts'
+export { contextStorage, getContext, tryGetContext } from '../core/middleware/context-storage/index.ts'
+export { cors } from '../core/middleware/cors/index.ts'
+export { csrf } from '../core/middleware/csrf/index.ts'
+export { etag } from '../core/middleware/etag/index.ts'
+export { jwk } from '../core/middleware/jwk/index.ts'
+export { AlgorithmTypes, decode, jwt, sign, verify, verifyWithJwks, type JwtVariables } from '../core/middleware/jwt/index.ts'
+export { ipRestriction, type IPRestrictionRule, type IPRestrictionRules } from '../core/middleware/ip-restriction/index.ts'
+export { detectFromCookie, detectFromHeader, detectFromPath, detectFromQuery, languageDetector } from '../core/middleware/language/index.ts'
+export { logger } from '../core/middleware/logger/index.ts'
+export { methodNotAllowed } from '../core/middleware/method-not-allowed/index.ts'
+export { methodOverride } from '../core/middleware/method-override/index.ts'
+export { poweredBy } from '../core/middleware/powered-by/index.ts'
+export { prettyJSON } from '../core/middleware/pretty-json/index.ts'
+export { requestId, type RequestIdVariables } from '../core/middleware/request-id/index.ts'
+export { serveStatic, type ServeStaticOptions } from '../core/middleware/serve-static/index.ts'
+export { NONCE, secureHeaders, type SecureHeadersVariables } from '../core/middleware/secure-headers/index.ts'
+export { timeout } from '../core/middleware/timeout/index.ts'
+export { endTime, setMetric, startTime, timing, wrapTime, type TimingVariables } from '../core/middleware/timing/index.ts'
+export { appendTrailingSlash, trimTrailingSlash } from '../core/middleware/trailing-slash/index.ts'
+export { LOOPBACK_HOSTNAMES, loopbackAuthority, loopbackOnly, sameOrigin, type LoopbackOptions } from './loopback-only.ts'

package/plugins/acryl-router/src/middleware/loopback-only.ts

@@ -0,0 +1,88 @@
+import { BlockList, isIP } from 'node:net'
+import { connectionOf } from '../connection.ts'
+import type { Context } from '../core/context.ts'
+import type { MiddlewareHandler } from '../core/types.ts'
+
+export interface LoopbackOptions {
+  /** Hostnames a `Host` header may name. Default: the loopback names `127.0.0.1`, `localhost` and `[::1]`. */
+  readonly hostnames?: readonly string[]
+  /**
+   * What a request that changes things (not GET, HEAD or OPTIONS) must show: `same-origin` (default) refuses an `Origin` header that is not this same
+   * authority (including `null`), which stops another web page from driving a local app. A browser always sends `Origin` on a cross-origin change, so a
+   * request with no `Origin` (curl, a script) is allowed: the `Host` it names is already checked to be a loopback address with this server's port, which
+   * is what stops DNS rebinding. `none` checks only the peer and the `Host`.
+   */
+  readonly mutations?: 'same-origin' | 'none'
+  /**
+   * A call made inside the process (the terminal UI, a test) has no socket, so no peer to check. `deny` (default) refuses it, the safe choice for a route
+   * that guards something; `allow` lets it through for routes whose in-process caller is the host's own code. A request that came over a socket is always
+   * checked in full: only a call with no connection facts at all counts as in process.
+   */
+  readonly inProcess?: 'deny' | 'allow'
+}
+
+const loopback = new BlockList()
+loopback.addSubnet('127.0.0.0', 8, 'ipv4')
+loopback.addSubnet('::1', 128, 'ipv6')
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * The authority a loopback request addressed: the `Host` header as a URL, or `undefined` when the request does not come from a loopback peer to the
+ * real local port, names another host, or is marked cross-site by the browser. The peer and the port come from the transport (`connectionOf(c)`), never
+ * from a header; an in-process call has neither and is refused.
+ */
+export const LOOPBACK_HOSTNAMES: readonly string[] = ['127.0.0.1', 'localhost', '[::1]']
+
+export function loopbackAuthority(c: Context, hostnames: readonly string[] = LOOPBACK_HOSTNAMES): URL | undefined {
+  const { remoteAddress, localPort } = connectionOf(c)
+  const host = c.req.header('host')
+  if (remoteAddress === undefined || localPort === undefined || host === undefined) return undefined
+  const address = (remoteAddress.replace(/^\[|\]$/gu, '').split('%', 1)[0] ?? '').replace(/^::ffff:/iu, '')
+  const family = isIP(address)
+  if (family === 0 || !loopback.check(address, family === 4 ? 'ipv4' : 'ipv6')) return undefined
+  let authority: URL
+  try {
+    authority = new URL(`http://${host}`)
+  } catch {
+    return undefined
+  }
+  if (
+    authority.protocol !== 'http:'
+    || Number(authority.port || '80') !== localPort
+    || !hostnames.includes(authority.hostname)
+    || c.req.header('sec-fetch-site') === 'cross-site'
+  ) return undefined
+  return authority
+}
+
+/** Whether a changing request is acceptable by its `Origin`: absent (not a browser cross-origin change) or naming this same authority. `null` and any other origin are not. */
+export function sameOrigin(c: Context, authority: URL): boolean {
+  const origin = c.req.header('origin')
+  if (origin === undefined) return true
+  try {
+    const parsed = new URL(origin)
+    return parsed.protocol === 'http:' && parsed.host === authority.host && parsed.pathname === '/'
+  } catch {
+    return false
+  }
+}
+
+/** Only requests from this machine to this app: loopback peer, the real port, an allowed `Host`, and for mutations a matching `Origin`. Everything else gets a 403. */
+export function loopbackOnly(options: LoopbackOptions = {}): MiddlewareHandler {
+  const mutations = options.mutations ?? 'same-origin'
+  const inProcess = options.inProcess ?? 'deny'
+  return async (c, next) => {
+    const connection = connectionOf(c)
+    if (inProcess === 'allow' && connection.remoteAddress === undefined && connection.localPort === undefined) {
+      await next()
+      return
+    }
+    const authority = loopbackAuthority(c, options.hostnames)
+    if (authority === undefined) return c.json({ error: 'request authority rejected' }, 403)
+    if (mutations === 'same-origin' && !SAFE_METHODS.has(c.req.method) && !sameOrigin(c, authority)) {
+      return c.json({ error: 'a change must come from this app\'s own origin' }, 403)
+    }
+    await next()
+  }
+}