@nifrajs/core 5.5.1 → 5.7.0

package/src/binary.ts

@@ -51,6 +51,23 @@ declare const NIFRA_RAW: unique symbol
  */
 export type RawResponse<T> = Response & { readonly [NIFRA_RAW]: T }
 
+/**
+ * Marker on a `t.bytes()` field's TYPE. Declared OPTIONAL, unlike the two above: the handler returns a
+ * plain `Uint8Array` (or a `Buffer`), so the field's type has to accept one. Every `Uint8Array` meets an
+ * optional brand, so `extends` cannot test it; `Jsonify` asks whether the key is present instead, which
+ * only the declared field's type answers yes to.
+ */
+declare const NIFRA_BASE64: unique symbol
+
+/** The key `Jsonify` looks for to tell a {@link Base64Bytes} field from any other `Uint8Array`. */
+export type Base64BytesBrand = typeof NIFRA_BASE64
+
+/** A `t.bytes()` field: a `Uint8Array` in the handler, a base64 string on the wire and in the client. */
+export type Base64Bytes = Uint8Array & { readonly [NIFRA_BASE64]?: true }
+
+export type { AnswerStages, AnswerStep, JsonReplyContext } from "./server/answer-step.ts"
+export { withBase64Bytes } from "./server/base64-answers.ts"
+
 /** What can be sent as bytes without being re-encoded on the way out. */
 export type BinaryBody = ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>
 

package/src/edge-kit.ts

@@ -24,6 +24,7 @@ export { type ErrorLogDetail, emitRequestErrorLog } from "./server/bare-error-la
 export { assertByteLimit, capBodyBytes } from "./server/body.ts"
 export { type FormOrigins, readBodyFramed } from "./server/body-lane.ts"
 export { plainError } from "./server/http.ts"
+export { jsonResponse } from "./server/json-response.ts"
 export {
   answerNotFound,
   type NotFoundHandler,

package/src/errors.ts

@@ -30,6 +30,7 @@ export type RouteConfigErrorCode =
   | "INVALID_WIRE"
   | "INVALID_VALIDATION_ORDER"
   | "INVALID_BODY_LIMIT"
+  | "RESPONSE_ONLY_SCHEMA"
   | "PLUGIN_RECONFIGURED"
   | "MOUNT_CYCLE"
 

package/src/evidence.ts

@@ -31,6 +31,8 @@ export interface ProjectEvidenceSchemaPart {
   readonly fields?: readonly ReflectedSchemaField[]
   /** The media types a body schema reads through a parser of its own. */
   readonly mediaTypes?: readonly string[]
+  /** Set when the schema reads text values with `t.query`'s string coercion. */
+  readonly coerces?: true
 }
 
 export interface ProjectEvidenceSchema {
@@ -46,6 +48,8 @@ export interface ProjectEvidenceSchema {
   readonly response?: ProjectEvidenceSchemaPart
   readonly errors?: Readonly<Record<string, ProjectEvidenceSchemaPart>>
   readonly sse?: ProjectEvidenceSchemaPart
+  /** Set when an `onValidationError` hook answers the route's validation failures. */
+  readonly validationErrorHook?: true
 }
 
 export interface ProjectEvidenceSourceLocation {
@@ -143,6 +147,7 @@ function schemaPart(value: SchemaReflection | undefined): ProjectEvidenceSchemaP
     ...(value.mediaTypes !== undefined
       ? { mediaTypes: Object.freeze([...value.mediaTypes].sort()) }
       : {}),
+    ...(value.coerces === true ? { coerces: true as const } : {}),
   })
 }
 
@@ -173,6 +178,7 @@ function schemaOf(route: ReflectedRoute): ProjectEvidenceSchema | undefined {
     ...(response !== undefined ? { response } : {}),
     ...(Object.keys(errors).length > 0 ? { errors: Object.freeze(errors) } : {}),
     ...(sse !== undefined ? { sse } : {}),
+    ...(source.validationErrorHook === true ? { validationErrorHook: true as const } : {}),
   }
   return Object.freeze(schema)
 }
@@ -488,6 +494,7 @@ function schemaPartToReflection(
         jsonSchema: value.jsonSchema,
         fields: value.fields,
         ...(value.mediaTypes !== undefined ? { mediaTypes: value.mediaTypes } : {}),
+        ...(value.coerces === true ? { coerces: true as const } : {}),
       }
 }
 
@@ -518,6 +525,7 @@ function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): Reflecte
     ...(response !== undefined ? { response } : {}),
     ...(Object.keys(errors).length > 0 ? { errors } : {}),
     ...(sse !== undefined ? { sse } : {}),
+    ...(schema.validationErrorHook === true ? { validationErrorHook: true as const } : {}),
   }
 }
 

package/src/file-type.ts

@@ -0,0 +1,130 @@
+/**
+ * Magic-byte file-type detection - trust the bytes, not the `Content-Type` header (which a client
+ * sets freely). Reads only the leading bytes; imports nothing, so it is edge-safe. Covers the common
+ * upload types; returns `null` for anything unrecognized (incl. text formats like SVG/CSV that have no
+ * magic number - handle those explicitly if you accept them).
+ *
+ * The shared owner for every type-by-bytes check: `@nifrajs/schema/form`'s `t.file({ accept })` and
+ * `@nifrajs/uploads`'s `validateUpload` must give one file one verdict, so both read this module.
+ */
+
+export interface FileType {
+  /** Detected MIME type, e.g. `"image/png"`. */
+  readonly mime: string
+  /** Canonical extension (no dot), e.g. `"png"`. */
+  readonly ext: string
+}
+
+/**
+ * How many leading bytes {@link detectFileType} looks at. Reading this many from the start of a file
+ * (`file.slice(0, FILE_TYPE_PREFIX_BYTES)`) is enough for every type it knows: it reaches the first four
+ * compatible brands of an ISO-BMFF `ftyp` box, where an AVIF with the generic `mif1` brand says `avif`.
+ */
+export const FILE_TYPE_PREFIX_BYTES = 32
+
+/**
+ * Every MIME type {@link detectFileType} can return. An allow-list entry outside this set (and
+ * outside a `type/*` wildcard that covers one of them) can never match, so check a configured
+ * allow-list against it up front instead of rejecting every upload at request time.
+ */
+export const DETECTABLE_MIME_TYPES: readonly string[] = [
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  "audio/wav",
+  "video/x-msvideo",
+  "image/avif",
+  "image/heic",
+  "audio/mp4",
+  "video/mp4",
+  "video/webm",
+  "audio/ogg",
+  "audio/mpeg",
+  "application/pdf",
+  "application/zip",
+  "application/gzip",
+]
+
+/**
+ * An MPEG audio frame header: an 11-bit frame sync, then a version, layer, bitrate and sample rate that
+ * are not reserved values. An MP3 needs no ID3 tag, so this is how an untagged one starts. AAC's ADTS
+ * sync shares the first 12 bits, but its layer is always the reserved `00`.
+ */
+function mpegAudioFrame(bytes: Uint8Array): boolean {
+  const [b0 = 0, b1 = 0, b2 = 0] = bytes
+  if (bytes.length < 4 || b0 !== 0xff || (b1 & 0xe0) !== 0xe0) return false
+  const version = (b1 >> 3) & 0b11
+  const layer = (b1 >> 1) & 0b11
+  const bitrate = b2 >> 4
+  const sampleRate = (b2 >> 2) & 0b11
+  return version !== 0b01 && layer !== 0b00 && bitrate !== 0b1111 && sampleRate !== 0b11
+}
+
+/** Detect a file's type from its magic bytes, or `null` if unrecognized. */
+export function detectFileType(bytes: Uint8Array): FileType | null {
+  const at = (offset: number, ...sig: number[]): boolean =>
+    sig.every((byte, i) => bytes[offset + i] === byte)
+
+  // Images
+  if (at(0, 0xff, 0xd8, 0xff)) return { mime: "image/jpeg", ext: "jpg" }
+  if (at(0, 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a))
+    return { mime: "image/png", ext: "png" }
+  if (at(0, 0x47, 0x49, 0x46, 0x38)) return { mime: "image/gif", ext: "gif" }
+
+  // RIFF container (bytes 0-3 "RIFF", 8-11 the form type)
+  if (at(0, 0x52, 0x49, 0x46, 0x46)) {
+    if (at(8, 0x57, 0x45, 0x42, 0x50)) return { mime: "image/webp", ext: "webp" }
+    if (at(8, 0x57, 0x41, 0x56, 0x45)) return { mime: "audio/wav", ext: "wav" }
+    if (at(8, 0x41, 0x56, 0x49, 0x20)) return { mime: "video/x-msvideo", ext: "avi" }
+  }
+
+  // ISO-BMFF (`ftyp` box at offset 4) - mp4 / avif / heic / m4a, disambiguated by the major brand.
+  if (at(4, 0x66, 0x74, 0x79, 0x70)) {
+    const brandAt = (offset: number): string =>
+      String.fromCharCode(
+        bytes[offset] ?? 0,
+        bytes[offset + 1] ?? 0,
+        bytes[offset + 2] ?? 0,
+        bytes[offset + 3] ?? 0,
+      )
+    const brand = brandAt(8)
+    // The compatible brands follow the minor version, to the end of the ftyp box. Only those inside the
+    // prefix count: the box size is the sender's claim, and a verdict must not depend on bytes a caller
+    // that sniffs `FILE_TYPE_PREFIX_BYTES` never reads.
+    const boxEnd = Math.min(
+      bytes.length,
+      FILE_TYPE_PREFIX_BYTES,
+      ((bytes[0] ?? 0) << 24) | ((bytes[1] ?? 0) << 16) | ((bytes[2] ?? 0) << 8) | (bytes[3] ?? 0),
+    )
+    const compatible: string[] = []
+    for (let offset = 16; offset + 4 <= boxEnd; offset += 4) compatible.push(brandAt(offset))
+    // A HEIF-family file whose major brand is the generic `mif1`/`msf1`/`miaf` names its codec among
+    // the compatible brands: AVIF says `avif`/`avis`.
+    const avif = (name: string): boolean => name === "avif" || name === "avis"
+    const generic = brand === "mif1" || brand === "msf1" || brand === "miaf"
+    if (avif(brand) || (generic && compatible.some(avif)))
+      return { mime: "image/avif", ext: "avif" }
+    if (brand.startsWith("hei") || brand.startsWith("hev") || generic) {
+      return { mime: "image/heic", ext: "heic" }
+    }
+    // Audio brands share the ISO-BMFF container but are NOT video - labeling them `video/mp4` would
+    // both reject real audio under an `audio/*` allow-list and admit it under `video/*`. `M4A `/`M4B `
+    // are AAC audio / audiobooks.
+    if (brand === "M4A " || brand === "M4B ") return { mime: "audio/mp4", ext: "m4a" }
+    return { mime: "video/mp4", ext: "mp4" }
+  }
+
+  // A/V + archives
+  if (at(0, 0x1a, 0x45, 0xdf, 0xa3)) return { mime: "video/webm", ext: "webm" } // Matroska/WebM
+  if (at(0, 0x4f, 0x67, 0x67, 0x53)) return { mime: "audio/ogg", ext: "ogg" }
+  if (at(0, 0x49, 0x44, 0x33)) return { mime: "audio/mpeg", ext: "mp3" } // ID3 tag
+  if (mpegAudioFrame(bytes)) return { mime: "audio/mpeg", ext: "mp3" } // an untagged MP3
+  if (at(0, 0x25, 0x50, 0x44, 0x46)) return { mime: "application/pdf", ext: "pdf" } // "%PDF"
+  if (at(0, 0x50, 0x4b, 0x03, 0x04) || at(0, 0x50, 0x4b, 0x05, 0x06)) {
+    return { mime: "application/zip", ext: "zip" } // also docx/xlsx/odt containers
+  }
+  if (at(0, 0x1f, 0x8b)) return { mime: "application/gzip", ext: "gz" }
+
+  return null
+}

package/src/index.ts

@@ -16,7 +16,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "5.5.1" as const
+export const VERSION = "5.7.0" as const
 
 export type Version = typeof VERSION
 
@@ -58,6 +58,7 @@ export {
   markAuthenticatedRequest,
   rejected,
 } from "./server/auth.ts"
+export { beforeHandler } from "./server/before-handler.ts"
 export type {
   Context,
   Params,
@@ -119,6 +120,7 @@ export type {
 } from "./server/registry.ts"
 export { replacedRequestOf } from "./server/request-lineage.ts"
 export { writableResponse } from "./server/respond.ts"
+export { routeTemplateOf } from "./server/route-template.ts"
 export {
   type PlainRender,
   type ResponseResult,

package/src/internal/hook-origins.ts

@@ -112,6 +112,16 @@ export function tagSource(wrapper: unknown, source: unknown): void {
   if (isRef(wrapper)) sources.set(wrapper, source)
 }
 
+/** A wrapper that runs in `hook`'s place on one route, reported as `hook` is. */
+export function tagStandIn(wrapper: unknown, hook: unknown): void {
+  if (!isRef(wrapper) || !isRef(hook)) return
+  const origin = origins.get(hook)
+  if (origin !== undefined) origins.set(wrapper, origin)
+  const scope = scopes.get(hook)
+  if (scope !== undefined) scopes.set(wrapper, scope)
+  sources.set(wrapper, hook)
+}
+
 /** Pair each scoped wrapper with the hook it gates and the scope it gates it by. */
 export function tagScoped(
   originals: readonly unknown[],