@nifrajs/web 4.0.2 → 5.0.0

package/src/server-components/definition.ts

@@ -0,0 +1,125 @@
+import { narrowCapabilityContext } from "@nifrajs/core/capabilities"
+import { validateStandard } from "@nifrajs/core/schema"
+import { outputGuard, runGuard } from "../internal/output-guard.ts"
+import { isControlFlow, isStatusSignal } from "../internal/render-document.ts"
+import { ServerComponentError } from "./error.ts"
+import { assertComponentSchema, componentValue } from "./schema.ts"
+import type {
+  PreparedServerComponent,
+  ServerComponent,
+  ServerComponentContext,
+  ServerComponentDefinition,
+} from "./types.ts"
+
+interface RuntimeDefinition {
+  readonly authorize: (ctx: ServerComponentContext, input: never) => void | Promise<void>
+  readonly load: (ctx: ServerComponentContext, input: never) => unknown | Promise<unknown>
+  readonly guard: ReturnType<typeof outputGuard>
+  readonly capabilities: readonly string[]
+}
+const definitions = new WeakMap<object, RuntimeDefinition>()
+const authorizations = new WeakMap<
+  object,
+  {
+    component: ServerComponent
+    definition: RuntimeDefinition
+    input: unknown
+    scope: ServerComponentContext
+  }
+>()
+
+export function defineServerComponent<Input, Props, View>(
+  definition: ServerComponentDefinition<Input, Props, View>,
+  reference?: string,
+): ServerComponent<Input, Props, View> {
+  if (typeof definition.authorize !== "function" || typeof definition.load !== "function")
+    throw new ServerComponentError("component_contract")
+  assertComponentSchema(definition.input)
+  assertComponentSchema(definition.props)
+  const component: ServerComponent<Input, Props, View> = {
+    view: definition.view,
+    input: definition.input,
+    props: definition.props,
+  }
+  if (reference !== undefined) Object.assign(component, { reference })
+  Object.freeze(component)
+  definitions.set(component, {
+    authorize: definition.authorize,
+    load: definition.load,
+    guard: outputGuard(definition.props, "server component", "props"),
+    capabilities: Object.freeze([...(definition.capabilities ?? [])]),
+  })
+  return component
+}
+
+export function isServerComponent(value: unknown): value is ServerComponent {
+  return typeof value === "object" && value !== null && definitions.has(value)
+}
+
+export function serverComponentCapabilities(component: object): readonly string[] {
+  const definition = definitions.get(component)
+  if (definition === undefined) throw new ServerComponentError("component_contract")
+  return definition.capabilities
+}
+
+export function inheritOwnerAuthorization(): void {}
+
+/** Used for whole-owner preflight so an invalid sibling cannot follow successful work. */
+export async function validateServerComponentInput(
+  component: ServerComponent,
+  input: unknown,
+): Promise<void> {
+  if (!definitions.has(component)) throw new ServerComponentError("component_unavailable", 404)
+  componentValue(input, 1024)
+  const parsed = await validateStandard(component.input, input)
+  if (!parsed.ok) throw new ServerComponentError("component_input", 422)
+  componentValue(parsed.value, 1024)
+}
+
+export async function prepareServerComponent<Input, Props, View>(
+  component: ServerComponent<Input, Props, View>,
+  input: unknown,
+  ctx: ServerComponentContext,
+): Promise<PreparedServerComponent<Props, View>> {
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The private definition registry binds each schema to its callbacks; validation and authorization precede this erased generic invocation.
+  return (await prepareAuthorizedServerComponent(
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The private definition registry binds each schema to its callbacks; validation and authorization precede this erased generic invocation.
+    await authorizeServerComponent(component as ServerComponent, input, ctx),
+  )) as PreparedServerComponent<Props, View>
+}
+export async function authorizeServerComponent(
+  component: ServerComponent,
+  input: unknown,
+  ctx: ServerComponentContext,
+): Promise<object> {
+  const definition = definitions.get(component)
+  if (definition === undefined) throw new ServerComponentError("component_unavailable", 404)
+  if (ctx.signal.aborted) throw new ServerComponentError("component_cancelled", 499)
+  componentValue(input, 1024)
+  const parsed = await validateStandard(component.input, input)
+  if (!parsed.ok) throw new ServerComponentError("component_input", 422)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The private definition registry binds each schema to its callbacks; validation and authorization precede this erased generic invocation.
+  const scope = narrowCapabilityContext(ctx, definition.capabilities) as ServerComponentContext
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The private definition registry binds each schema to its callbacks; validation and authorization precede this erased generic invocation.
+  await definition.authorize(scope, parsed.value as never)
+  if (ctx.signal.aborted) throw new ServerComponentError("component_cancelled", 499)
+  const token = Object.freeze({})
+  authorizations.set(token, { component, definition, input: parsed.value, scope })
+  return token
+}
+export async function prepareAuthorizedServerComponent(
+  token: object,
+): Promise<PreparedServerComponent> {
+  const authorized = authorizations.get(token)
+  if (authorized === undefined) throw new ServerComponentError("component_contract")
+  authorizations.delete(token)
+  const { component, definition, scope, input } = authorized
+  if (scope.signal.aborted) throw new ServerComponentError("component_cancelled", 499)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The private definition registry binds each schema to its callbacks; validation and authorization precede this erased generic invocation.
+  const data = await definition.load(scope, input as never)
+  if (isControlFlow(data) || isStatusSignal(data)) throw data
+  if (scope.signal.aborted) throw new ServerComponentError("component_cancelled", 499)
+  const props = await runGuard(definition.guard, data, "server component props")
+  const publicProps = componentValue(props)
+  return { props: publicProps, view: component.view }
+}

package/src/server-components/dev-http.ts

@@ -0,0 +1,75 @@
+import { Readable } from "node:stream"
+import { pipeline } from "node:stream/promises"
+import type { ViteDevServer } from "vite"
+import type { ComponentPipelineOptions } from "./build.ts"
+
+/** The native dev path serves the same factory and Fetch handler as production. */
+export function installComponentDevHandler(
+  server: ViteDevServer,
+  options: ComponentPipelineOptions,
+): void {
+  if (options.adapter === "react") return // plugin-rsc owns the SSR request entry in React dev.
+  server.middlewares.use(async (req, res, next) => {
+    const path = req.url ?? "/"
+    if (
+      path.startsWith("/@") ||
+      path.startsWith("/node_modules/") ||
+      /\.(?:[cm]?[jt]sx?|vue|svelte|css)(?:\?|$)/.test(path)
+    ) {
+      next()
+      return
+    }
+    const abort = new AbortController()
+    const close = (): void => {
+      if (!res.writableEnded) abort.abort()
+    }
+    res.on("close", close)
+    try {
+      const module = await server.ssrLoadModule(options.entries.ssr)
+      if (typeof module.createApp !== "function")
+        throw new Error(
+          "[nifra/components] The SSR entry must export createApp(clientEntry, assets)",
+        )
+      const app = await module.createApp(`/${options.entries.client.replace(/^\.\//, "")}`, {
+        styles: [],
+      })
+      if (typeof app?.fetch !== "function") throw new Error("component_contract")
+      const headers = new Headers()
+      for (let i = 0; i < req.rawHeaders.length; i += 2)
+        headers.append(req.rawHeaders[i]!, req.rawHeaders[i + 1]!)
+      const method = req.method ?? "GET"
+      const init: RequestInit & { duplex?: "half" } = { method, headers, signal: abort.signal }
+      if (!["GET", "HEAD"].includes(method)) {
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion lint/plugin/noChainedTypeAssertions: Node and Bun name the same WHATWG stream API differently; this zero-copy bridge preserves that ABI.
+        init.body = Readable.toWeb(req) as unknown as ReadableStream<Uint8Array>
+        init.duplex = "half"
+      }
+      const request = new Request(new URL(path, `http://${req.headers.host ?? "localhost"}`), init)
+      const response: Response = await app.fetch(request)
+      if (abort.signal.aborted || res.destroyed) {
+        await response.body?.cancel()
+        return
+      }
+      res.statusCode = response.status
+      for (const [name, value] of response.headers)
+        if (name !== "set-cookie") res.setHeader(name, value)
+      const cookies = response.headers.getSetCookie()
+      if (cookies.length > 0) res.setHeader("set-cookie", cookies)
+      // The runtime stream implements Node's Web Streams API despite the distinct TS declarations.
+      if (response.body !== null && method !== "HEAD")
+        await pipeline(
+          Readable.fromWeb(
+            // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion lint/plugin/noChainedTypeAssertions: Node and Bun name the same WHATWG stream API differently; this bridge preserves the stream without copying or decoding.
+            response.body as unknown as import("node:stream/web").ReadableStream<Uint8Array>,
+          ),
+          res,
+        )
+      else res.end()
+    } catch (error) {
+      // A disconnected read has no response destination and must not broadcast a Vite error overlay.
+      if (!abort.signal.aborted && !res.destroyed) next(error)
+    } finally {
+      res.off("close", close)
+    }
+  })
+}

package/src/server-components/error.ts

@@ -0,0 +1,24 @@
+export const COMPONENT_ERROR_CODES = [
+  "component_contract",
+  "component_input",
+  "component_protocol",
+  "component_limit",
+  "component_denied",
+  "component_unavailable",
+  "component_version",
+  "component_busy",
+  "component_timeout",
+  "component_failed",
+  "component_cancelled",
+] as const
+export type ComponentErrorCode = (typeof COMPONENT_ERROR_CODES)[number]
+
+export class ServerComponentError extends Error {
+  override readonly name = "ServerComponentError"
+  constructor(
+    readonly code: ComponentErrorCode,
+    readonly status: number = 500,
+  ) {
+    super(`[nifra/web] ${code}`)
+  }
+}

package/src/server-components/frames.ts

@@ -0,0 +1,181 @@
+import { ServerComponentError } from "./error.ts"
+import { COMPONENT_LIMITS } from "./protocol.ts"
+
+const magic = new Uint8Array([78, 83, 67, 49])
+const encoder = new TextEncoder()
+const decoder = new TextDecoder("utf-8", { fatal: true })
+
+function frame(type: number, data: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(data.length + 5)
+  bytes[0] = type
+  new DataView(bytes.buffer).setUint32(1, data.length)
+  bytes.set(data, 5)
+  return bytes
+}
+
+export function componentFrames(
+  metadata: unknown,
+  value: unknown,
+  maxBytes = COMPONENT_LIMITS.outputBytes,
+): ReadableStream<Uint8Array> {
+  const meta = encoder.encode(JSON.stringify(metadata))
+  const body = encoder.encode(JSON.stringify(value))
+  if (meta.length > COMPONENT_LIMITS.frameBytes || body.length + meta.length > maxBytes)
+    throw new ServerComponentError("component_limit", 413)
+  let position = -2
+  return new ReadableStream({
+    pull(controller) {
+      if (position === -2) {
+        controller.enqueue(magic)
+        position++
+        return
+      }
+      if (position === -1) {
+        controller.enqueue(frame(1, meta))
+        position++
+        return
+      }
+      if (position < body.length) {
+        const end = Math.min(body.length, position + 65536)
+        controller.enqueue(frame(2, body.subarray(position, end)))
+        position = end
+        return
+      }
+      controller.enqueue(frame(3, new Uint8Array()))
+      controller.close()
+    },
+  })
+}
+
+export interface DecodedComponentFrames {
+  readonly metadata: unknown
+  readonly value: unknown
+}
+
+export async function readComponentFrames(
+  stream: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+  maxBytes = COMPONENT_LIMITS.outputBytes,
+): Promise<DecodedComponentFrames> {
+  const reader = stream.getReader()
+  const header = new Uint8Array(5)
+  let magicOffset = 0
+  let headerOffset = 0
+  let payload: Uint8Array | undefined
+  let payloadOffset = 0
+  let type = 0
+  let metadata: unknown
+  let gotMetadata = false
+  let terminal = false
+  let bytes = 0
+  let bodyBytes = 0
+  let metadataBytes = 0
+  const body: Uint8Array[] = []
+  const deadline = AbortSignal.any([signal, AbortSignal.timeout(COMPONENT_LIMITS.operationMs)])
+  const cancel = (): void => {
+    void reader.cancel().catch(() => {
+      /* The original read failure is authoritative. */
+    })
+  }
+  deadline.addEventListener("abort", cancel, { once: true })
+  const consume = (data: Uint8Array): void => {
+    if (type === 1) {
+      if (gotMetadata || bodyBytes !== 0) throw new ServerComponentError("component_protocol", 400)
+      metadataBytes = data.length
+      metadata = JSON.parse(decoder.decode(data))
+      gotMetadata = true
+    } else if (type === 2) {
+      if (!gotMetadata || data.length === 0)
+        throw new ServerComponentError("component_protocol", 400)
+      bodyBytes += data.length
+      if (bodyBytes + metadataBytes > maxBytes)
+        throw new ServerComponentError("component_limit", 413)
+      body.push(data)
+    } else {
+      if (!gotMetadata || bodyBytes === 0 || data.length !== 0)
+        throw new ServerComponentError("component_protocol", 400)
+      terminal = true
+    }
+  }
+  try {
+    while (true) {
+      if (deadline.aborted)
+        throw new ServerComponentError(
+          signal.aborted ? "component_cancelled" : "component_timeout",
+          504,
+        )
+      let timeout: ReturnType<typeof setTimeout> | undefined
+      const next = await Promise.race([
+        reader.read(),
+        new Promise<never>((_, reject) => {
+          timeout = setTimeout(() => {
+            reject(new ServerComponentError("component_timeout", 504))
+            // Publish the timeout before cancellation can resolve reader.read() as ordinary EOF.
+            cancel()
+          }, COMPONENT_LIMITS.idleMs)
+        }),
+      ]).finally(() => clearTimeout(timeout))
+      if (next.done) break
+      if (terminal || next.value.length === 0)
+        throw new ServerComponentError("component_protocol", 400)
+      bytes += next.value.length
+      if (bytes > maxBytes + 4096) throw new ServerComponentError("component_limit", 413)
+      let offset = 0
+      while (offset < next.value.length) {
+        if (terminal) throw new ServerComponentError("component_protocol", 400)
+        if (magicOffset < magic.length) {
+          if (next.value[offset++] !== magic[magicOffset++])
+            throw new ServerComponentError("component_protocol", 400)
+          continue
+        }
+        if (headerOffset < header.length) {
+          const size = Math.min(header.length - headerOffset, next.value.length - offset)
+          header.set(next.value.subarray(offset, offset + size), headerOffset)
+          offset += size
+          headerOffset += size
+          if (headerOffset < header.length) continue
+          type = header[0]!
+          const length = new DataView(header.buffer).getUint32(1)
+          if (length > COMPONENT_LIMITS.frameBytes || ![1, 2, 3].includes(type))
+            throw new ServerComponentError("component_protocol", 400)
+          payload = new Uint8Array(length)
+          payloadOffset = 0
+        }
+        // A frame allocates once. Arbitrarily split transport chunks are copied exactly once.
+        const data = payload!
+        const size = Math.min(data.length - payloadOffset, next.value.length - offset)
+        data.set(next.value.subarray(offset, offset + size), payloadOffset)
+        offset += size
+        payloadOffset += size
+        if (payloadOffset === data.length) {
+          consume(data)
+          headerOffset = 0
+          payload = undefined
+        }
+      }
+    }
+    if (deadline.aborted)
+      throw new ServerComponentError(
+        signal.aborted ? "component_cancelled" : "component_timeout",
+        504,
+      )
+    if (!terminal || headerOffset !== 0 || payload !== undefined)
+      throw new ServerComponentError("component_protocol", 400)
+    const merged = new Uint8Array(bodyBytes)
+    let offset = 0
+    for (const chunk of body) {
+      merged.set(chunk, offset)
+      offset += chunk.length
+    }
+    return { metadata, value: JSON.parse(decoder.decode(merged)) }
+  } catch (error) {
+    await reader.cancel().catch(() => {
+      /* Preserve the first protocol/read failure. */
+    })
+    if (error instanceof ServerComponentError) throw error
+    throw new ServerComponentError("component_protocol", 400)
+  } finally {
+    deadline.removeEventListener("abort", cancel)
+    reader.releaseLock()
+  }
+}

package/src/server-components/html-policy.ts

@@ -0,0 +1,94 @@
+import { ServerComponentError } from "./error.ts"
+
+const forbidden = new Set([
+  "script",
+  "iframe",
+  "object",
+  "embed",
+  "applet",
+  "base",
+  "meta",
+  "link",
+  "style",
+  "template",
+  "noscript",
+  "xmp",
+  "noembed",
+  "noframes",
+  "plaintext",
+  "frame",
+  "frameset",
+  "animate",
+  "animatemotion",
+  "animatetransform",
+  "set",
+])
+const urls = new Set([
+  "href",
+  "src",
+  "xlink:href",
+  "action",
+  "formaction",
+  "poster",
+  "background",
+  "cite",
+  "data",
+  "codebase",
+])
+const fail = (): never => {
+  throw new ServerComponentError("component_protocol", 400)
+}
+
+function css(value: string): string {
+  return (
+    value
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(
+        /\\([0-9a-f]{1,6})\s?|\\([^\r\n])/gi,
+        (_all, hex: string | undefined, char: string | undefined) =>
+          hex === undefined
+            ? (char ?? "")
+            : String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff)),
+      )
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: URL/CSS schemes must be checked after stripping ASCII controls.
+      .replace(/[\u0000-\u0020\u007f]/g, "")
+      .toLowerCase()
+  )
+}
+
+/** The same decoded-attribute policy applies before SSR and before DOM insertion. */
+export function validateComponentTag(
+  tag: string,
+  attributes: readonly { name: string; value: string }[],
+  assets?: ReadonlySet<string>,
+): void {
+  if (tag.toLowerCase() === "link" && assets !== undefined) {
+    const attrs = new Map(
+      attributes.map((attribute) => [attribute.name.toLowerCase(), attribute.value]),
+    )
+    if (
+      !["preload", "modulepreload"].includes(attrs.get("rel") ?? "") ||
+      !assets.has(attrs.get("href") ?? "") ||
+      [...attrs.keys()].some(
+        (name) => !["rel", "href", "as", "crossorigin", "fetchpriority"].includes(name),
+      )
+    )
+      fail()
+    return
+  }
+  if (forbidden.has(tag.toLowerCase())) fail()
+  for (const attribute of attributes) {
+    const name = attribute.name.toLowerCase()
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Browsers discard these controls when interpreting URL schemes.
+    const value = attribute.value.replace(/[\u0000-\u0020\u007f]/g, "").toLowerCase()
+    if (name.startsWith("on") || ["srcdoc", "is", "srcset", "ping"].includes(name)) fail()
+    if (urls.has(name) && /^(?:javascript|vbscript|data):/.test(value)) fail()
+    if (
+      name === "style" &&
+      /expression\(|@import|(?:javascript|vbscript|data):|-moz-binding|behavior:/.test(
+        css(attribute.value),
+      )
+    )
+      fail()
+  }
+}

package/src/server-components/html.ts

@@ -0,0 +1,81 @@
+import { Tokenizer } from "parse5"
+import { ServerComponentError } from "./error.ts"
+import { validateComponentTag } from "./html-policy.ts"
+import { COMPONENT_LIMITS } from "./protocol.ts"
+
+/**
+ * A browser reads `title` and `textarea` content as RCDATA, where `<!--` and tags are text, but
+ * only in an HTML context; a bare tokenizer never switches. Content holding no `<` before its own
+ * end tag tokenizes the same either way, so requiring that keeps this check exact wherever the
+ * HTML is inserted. Every other text-mode element is forbidden outright.
+ */
+function closesAsText(html: string, tag: string, from: number): boolean {
+  const next = html.indexOf("<", from)
+  const after = next + 2 + tag.length
+  return (
+    next !== -1 &&
+    html.slice(next, after).toLowerCase() === `</${tag}` &&
+    /^[\t\n\f />]$/.test(html[after] ?? "")
+  )
+}
+
+/** Tokenization validates attributes even in SVG/table contexts a document parser may discard. */
+function tokenize(
+  html: string,
+  assets?: ReadonlySet<string>,
+  hints?: Array<{ start: number; end: number }>,
+): void {
+  if (new TextEncoder().encode(html).length > COMPONENT_LIMITS.outputBytes)
+    throw new ServerComponentError("component_limit", 413)
+  const tokenizer = new Tokenizer(
+    { sourceCodeLocationInfo: true },
+    {
+      onStartTag(token) {
+        validateComponentTag(token.tagName, token.attrs, assets)
+        if (
+          (token.tagName === "title" || token.tagName === "textarea") &&
+          (token.location === null || !closesAsText(html, token.tagName, token.location.endOffset))
+        )
+          throw new ServerComponentError("component_protocol", 400)
+        if (token.tagName === "link" && token.location !== null)
+          hints?.push({ start: token.location.startOffset, end: token.location.endOffset })
+      },
+      onEndTag() {},
+      onComment() {},
+      onEof() {},
+      onCharacter() {},
+      onWhitespaceCharacter() {},
+      onNullCharacter() {
+        throw new ServerComponentError("component_protocol", 400)
+      },
+      onDoctype() {
+        throw new ServerComponentError("component_protocol", 400)
+      },
+      onParseError(error) {
+        // `<!>` (Solid's template markers, `<!$>` and `<!/>` too) is a comment to the tokenizer and to
+        // every browser alike; any other parse error is refused.
+        if (error.code !== "incorrectly-opened-comment")
+          throw new ServerComponentError("component_protocol", 400)
+      },
+    },
+  )
+  tokenizer.write(html, true)
+}
+
+export function validateComponentHTML(html: string, assets?: ReadonlySet<string>): void {
+  tokenize(html, assets)
+}
+
+/** React may produce resource hints while decoding Flight. They are not owned range nodes. */
+export function componentRangeHTML(html: string, assets: ReadonlySet<string>): string {
+  const hints: Array<{ start: number; end: number }> = []
+  tokenize(html, assets, hints)
+  const parts: string[] = []
+  let offset = 0
+  for (const hint of hints) {
+    parts.push(html.slice(offset, hint.start))
+    offset = hint.end
+  }
+  parts.push(html.slice(offset))
+  return parts.join("")
+}