@nifrajs/core 0.1.0-alpha.1

package/src/server/cookies.ts

@@ -0,0 +1,198 @@
+/**
+ * Cookie primitives — parse a request `Cookie` header, serialize a `Set-Cookie`, and sign/verify a
+ * value with HMAC-SHA256 via **WebCrypto** (`crypto.subtle`), so they're portable across Bun, Node,
+ * Deno, and workerd with no `node:crypto` dependency. Pure + runtime-agnostic: `c.cookies` (read) and
+ * `c.set.cookie` (write) build on these, and `@nifrajs/auth` builds sessions on top.
+ */
+
+import { requireSecretBytes } from "../internal/secret.ts"
+
+/** Attributes for a `Set-Cookie`. `expires` is a `Date`; `maxAge` is in **seconds**. */
+export interface CookieOptions {
+  /** Lifetime in seconds. `0` (with a past `expires`) deletes the cookie. */
+  readonly maxAge?: number
+  readonly expires?: Date
+  readonly path?: string
+  readonly domain?: string
+  readonly secure?: boolean
+  readonly httpOnly?: boolean
+  readonly sameSite?: "strict" | "lax" | "none"
+  readonly partitioned?: boolean
+}
+
+// RFC 6265 cookie-name token: visible ASCII minus separators/whitespace/controls.
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+const MAX_COOKIE_BYTES = 4096 // browsers cap a cookie near 4 KB — reject oversized before the wire
+
+/** True if `v` contains a character illegal in a cookie attribute (control char or `;` separator) —
+ * the header-injection guard for dev-supplied `Path`/`Domain`. */
+const hasIllegalChar = (v: string): boolean => {
+  for (let i = 0; i < v.length; i++) {
+    const code = v.charCodeAt(i)
+    if (code < 0x20 || code === 0x7f || code === 0x3b /* ; */) return true
+  }
+  return false
+}
+
+const safeDecode = (v: string): string => {
+  // No `%` ⇒ nothing to decode — skip the call AND its try frame (profiled: cookie values are
+  // overwhelmingly plain; this was ~3% of a realistic request).
+  if (!v.includes("%")) return v
+  try {
+    return decodeURIComponent(v)
+  } catch {
+    return v // a malformed %-escape from a hostile/garbage cookie must not throw (it'd 500 the request)
+  }
+}
+
+/** Parse a request `Cookie` header into a name→value map (values URL-decoded). Unparseable pairs are
+ * skipped rather than throwing — a junk `Cookie` header shouldn't fail the request.
+ *
+ * Hand-rolled index walk instead of `split(";")` + `trim()` chains: those allocated an array + up
+ * to three substrings per pair and showed up at ~6% of a realistic (auth + cookie) request. Same
+ * semantics, two slices per pair, no intermediate array. */
+export function parseCookies(header: string | null | undefined): Record<string, string> {
+  // Null-prototype: cookie NAMES come straight from the untrusted header, so a cookie named
+  // `constructor`/`__proto__`/`toString` must be an inert own key, not a shadow of a prototype
+  // member. Matches the query/form/params parsers (all `Object.create(null)`); values are always
+  // strings so global pollution was never possible, but this keeps the whole request-parse layer
+  // consistent and safe to treat as a plain dictionary.
+  const out: Record<string, string> = Object.create(null)
+  if (!header) return out
+  const len = header.length
+  let pos = 0
+  while (pos < len) {
+    let end = header.indexOf(";", pos)
+    if (end === -1) end = len
+    // trim() equivalent on the segment, without allocating the untrimmed slice
+    let start = pos
+    while (start < end && header.charCodeAt(start) === 32) start++
+    let stop = end
+    while (stop > start && header.charCodeAt(stop - 1) === 32) stop--
+    const eq = header.indexOf("=", start)
+    if (eq > start && eq < stop) {
+      // name: trim trailing spaces before '='; value: trim leading spaces after it
+      let nameEnd = eq
+      while (nameEnd > start && header.charCodeAt(nameEnd - 1) === 32) nameEnd--
+      let valueStart = eq + 1
+      while (valueStart < stop && header.charCodeAt(valueStart) === 32) valueStart++
+      if (nameEnd > start) {
+        const name = header.slice(start, nameEnd)
+        let value: string
+        if (
+          stop - valueStart >= 2 &&
+          header.charCodeAt(valueStart) === 34 /* " */ &&
+          header.charCodeAt(stop - 1) === 34
+        ) {
+          value = header.slice(valueStart + 1, stop - 1)
+        } else {
+          value = header.slice(valueStart, stop)
+        }
+        out[name] = safeDecode(value)
+      }
+    }
+    pos = end + 1
+  }
+  return out
+}
+
+/**
+ * Serialize a `Set-Cookie` header value. Pure — applies **no** security defaults (the caller, e.g.
+ * `c.set.cookie`, layers `HttpOnly`/`Secure`/`SameSite` on). Throws on an invalid cookie name, a
+ * header-injecting `Path`/`Domain`, a non-integer `maxAge`, or an oversized result — a serialization
+ * bug should fail loudly, not silently emit a cookie the browser drops.
+ */
+export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  if (!COOKIE_NAME.test(name)) {
+    throw new Error(
+      `[nifra] invalid cookie name ${JSON.stringify(name)}: must be an RFC 6265 token`,
+    )
+  }
+  let str = `${name}=${encodeURIComponent(value)}`
+  if (options.maxAge !== undefined) {
+    if (!Number.isInteger(options.maxAge)) {
+      throw new Error("[nifra] cookie maxAge must be an integer number of seconds")
+    }
+    str += `; Max-Age=${options.maxAge}`
+  }
+  if (options.domain !== undefined) {
+    if (hasIllegalChar(options.domain))
+      throw new Error("[nifra] cookie Domain contains an illegal character")
+    str += `; Domain=${options.domain}`
+  }
+  if (options.path !== undefined) {
+    if (hasIllegalChar(options.path))
+      throw new Error("[nifra] cookie Path contains an illegal character")
+    str += `; Path=${options.path}`
+  }
+  if (options.expires !== undefined) str += `; Expires=${options.expires.toUTCString()}`
+  if (options.httpOnly === true) str += "; HttpOnly"
+  if (options.secure === true) str += "; Secure"
+  if (options.partitioned === true) str += "; Partitioned"
+  if (options.sameSite !== undefined) {
+    str += `; SameSite=${options.sameSite === "strict" ? "Strict" : options.sameSite === "none" ? "None" : "Lax"}`
+  }
+  if (str.length > MAX_COOKIE_BYTES) {
+    throw new Error(
+      `[nifra] cookie ${JSON.stringify(name)} is ${str.length}B, over the ${MAX_COOKIE_BYTES}B limit`,
+    )
+  }
+  return str
+}
+
+const TEXT = new TextEncoder()
+
+const importHmacKey = (secret: string): Promise<CryptoKey> => {
+  // Reject a weak secret at the choke point both signing and verification flow through (so signed
+  // cookies AND @nifrajs/auth sessions, which delegate here via signValue/unsignValue, are covered).
+  requireSecretBytes(secret, "signed-cookie")
+  return crypto.subtle.importKey(
+    "raw",
+    TEXT.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  )
+}
+
+const toBase64Url = (buf: ArrayBuffer): string => {
+  let bin = ""
+  for (const b of new Uint8Array(buf)) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+// Returns `Uint8Array<ArrayBuffer>` (not the generic `Uint8Array<ArrayBufferLike>`) so it satisfies
+// WebCrypto's `BufferSource` parameter under TS 5.7+'s typed-array generics.
+const fromBase64Url = (s: string): Uint8Array<ArrayBuffer> | null => {
+  try {
+    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"))
+    const bytes = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+    return bytes
+  } catch {
+    return null // not valid base64 — treat as a bad signature
+  }
+}
+
+/** Append an HMAC-SHA256 signature to a value → `value.signature` (base64url). For signed cookies. */
+export async function signValue(value: string, secret: string): Promise<string> {
+  const key = await importHmacKey(secret)
+  const sig = await crypto.subtle.sign("HMAC", key, TEXT.encode(value))
+  return `${value}.${toBase64Url(sig)}`
+}
+
+/**
+ * Verify a `value.signature` produced by {@link signValue} and return the value, or `null` if the
+ * signature is missing, malformed, or doesn't match. Verification is **constant-time**
+ * (`crypto.subtle.verify`), so a wrong signature can't be discovered byte-by-byte via timing.
+ */
+export async function unsignValue(signed: string, secret: string): Promise<string | null> {
+  const dot = signed.lastIndexOf(".")
+  if (dot < 1) return null // no signature segment (or empty value)
+  const value = signed.slice(0, dot)
+  const sig = fromBase64Url(signed.slice(dot + 1))
+  if (sig === null) return null
+  const key = await importHmacKey(secret)
+  const ok = await crypto.subtle.verify("HMAC", key, sig, TEXT.encode(value))
+  return ok ? value : null
+}

package/src/server/logger.ts

@@ -0,0 +1,167 @@
+/**
+ * Structured, redacting logger. The framework logs through this interface so
+ * secrets/PII are scrubbed once, centrally (per the project's logging rule), not at
+ * each call site. Bring your own by passing `logger` to `server()`.
+ */
+
+export type LogFields = Record<string, unknown>
+
+export interface Logger {
+  debug(message: string, fields?: LogFields): void
+  info(message: string, fields?: LogFields): void
+  warn(message: string, fields?: LogFields): void
+  error(message: string, fields?: LogFields): void
+}
+
+const REDACTED = "[REDACTED]"
+
+/**
+ * Field-name fragments whose values are replaced with `[REDACTED]` (case-insensitive
+ * substring match). Key-name redaction is the default + always on.
+ */
+const SENSITIVE_KEY_PARTS: ReadonlyArray<string> = [
+  "authorization",
+  "cookie",
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "apikey",
+  "api_key",
+  "api-key",
+  "credential",
+  "ssn",
+]
+
+/**
+ * Tunes redaction. Key-name redaction always runs; the rest is **opt-in**:
+ * - `keyParts` — extra case-insensitive key fragments, added to the built-in denylist.
+ * - `valuePatterns` — regexes matched against string **values** *and* the log message; each match is
+ *   replaced with the placeholder. This is the value-scanning hook for secrets that land in a value or
+ *   message (e.g. `err.message`), which key-name redaction can't catch. Off unless provided — the
+ *   default path does no value scanning, so it stays allocation-light. See {@link commonSecretPatterns}.
+ * - `placeholder` — the replacement string (default `[REDACTED]`).
+ */
+export interface RedactOptions {
+  readonly keyParts?: readonly string[]
+  readonly valuePatterns?: readonly RegExp[]
+  readonly placeholder?: string
+}
+
+/**
+ * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} — opt in by
+ * passing it (or a subset) to `jsonLogger`/`redactLogFields`. Covers bearer tokens, JWTs, emails, and a
+ * few well-known key formats (Stripe, GitHub, AWS access-key ids). Chosen to minimize false positives;
+ * add your own (e.g. internal id formats) as needed. Every pattern is global so all matches are scrubbed.
+ */
+export const commonSecretPatterns: ReadonlyArray<RegExp> = [
+  /Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, // Authorization: Bearer <token>
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, // JWT (header.payload.signature)
+  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, // email
+  /\b[sprk]k_(?:live|test)_[A-Za-z0-9]{8,}/g, // Stripe-style secret/restricted keys
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub personal/OAuth/refresh tokens
+  /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id
+]
+
+interface RedactConfig {
+  readonly keyParts: readonly string[]
+  readonly valuePatterns: readonly RegExp[]
+  readonly placeholder: string
+}
+
+// `String.replace` with a global regex replaces every match and is stateless across calls; a
+// non-global pattern would only scrub the first occurrence, so normalize to global once up front.
+const ensureGlobal = (re: RegExp): RegExp =>
+  re.flags.includes("g") ? re : new RegExp(re.source, `${re.flags}g`)
+
+function buildConfig(options?: RedactOptions): RedactConfig {
+  const extra = options?.keyParts
+  return {
+    keyParts:
+      extra !== undefined && extra.length > 0
+        ? [...SENSITIVE_KEY_PARTS, ...extra.map((k) => k.toLowerCase())]
+        : SENSITIVE_KEY_PARTS,
+    valuePatterns: (options?.valuePatterns ?? []).map(ensureGlobal),
+    placeholder: options?.placeholder ?? REDACTED,
+  }
+}
+
+function isSensitiveKey(key: string, parts: readonly string[]): boolean {
+  const lower = key.toLowerCase()
+  return parts.some((part) => lower.includes(part))
+}
+
+function redactString(value: string, config: RedactConfig): string {
+  if (config.valuePatterns.length === 0) return value // default fast path: no value scanning
+  let out = value
+  for (const pattern of config.valuePatterns) out = out.replace(pattern, config.placeholder)
+  return out
+}
+
+function redactValue(value: unknown, seen: WeakSet<object>, config: RedactConfig): unknown {
+  if (typeof value === "string") return redactString(value, config)
+  if (value === null || typeof value !== "object") return value
+  if (seen.has(value)) return "[Circular]"
+  seen.add(value)
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, seen, config))
+  const out: Record<string, unknown> = {}
+  for (const [key, val] of Object.entries(value)) {
+    // A sensitive key wins outright (don't scan it) — the whole value is replaced.
+    out[key] = isSensitiveKey(key, config.keyParts)
+      ? config.placeholder
+      : redactValue(val, seen, config)
+  }
+  return out
+}
+
+/**
+ * Deep-copy `fields`, replacing values under sensitive keys with the placeholder; cycle-safe. With
+ * `options.valuePatterns`, also scans string values for those patterns (opt-in). Without options, this
+ * is pure key-name redaction (the long-standing default).
+ */
+export function redactLogFields(fields: LogFields, options?: RedactOptions): LogFields {
+  return redactValue(fields, new WeakSet(), buildConfig(options)) as LogFields
+}
+
+function writeToStderr(line: string): void {
+  process.stderr.write(`${line}\n`)
+}
+
+/**
+ * The default logger: one redacted JSON object per line. `write` is injectable for tests or
+ * alternative sinks (defaults to stderr). `options` tunes redaction — pass `valuePatterns` (e.g.
+ * {@link commonSecretPatterns}) to also scrub secrets embedded in values + the message. Framework keys
+ * (`level`, `message`, `time`) always win over user fields of the same name.
+ */
+export function jsonLogger(
+  write: (line: string) => void = writeToStderr,
+  options?: RedactOptions,
+): Logger {
+  const config = buildConfig(options) // normalize patterns once, reuse per entry
+  const emit = (level: string, message: string, fields?: LogFields): void => {
+    const entry: Record<string, unknown> =
+      fields === undefined
+        ? {}
+        : (redactValue(fields, new WeakSet(), config) as Record<string, unknown>)
+    entry.level = level
+    entry.message = redactString(message, config) // scan the message too (no-op without valuePatterns)
+    entry.time = new Date().toISOString()
+    write(JSON.stringify(entry))
+  }
+  return {
+    debug: (message, fields) => emit("debug", message, fields),
+    info: (message, fields) => emit("info", message, fields),
+    warn: (message, fields) => emit("warn", message, fields),
+    error: (message, fields) => emit("error", message, fields),
+  }
+}
+
+const noop = (): void => undefined
+
+/** Discards everything — for tests, or when log output is handled elsewhere. */
+export const silentLogger: Logger = {
+  debug: noop,
+  info: noop,
+  warn: noop,
+  error: noop,
+}

package/src/server/registry.ts

@@ -0,0 +1,63 @@
+import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
+import type { Params, RouteSchema } from "./context.ts"
+
+/**
+ * One route's input/output shape as the **client** will consume it. `query`/`body`
+ * are `never` when the route declares no schema for them, so the client can detect
+ * "this route takes no body" via `[body] extends [never]`. `output` is the
+ * handler's raw return type (the client applies `Jsonify` when reading it).
+ */
+export interface RouteInfo {
+  // `object` is the *bound*; each route stores its precise `Params<Path>` (e.g.
+  // `{ id: string }`), which a generic `Path` can't be proven to fit into
+  // `Record<string, string>`. The precise type survives in the accumulated
+  // registry, so exact param-key checking is preserved downstream.
+  readonly params: object
+  readonly query: unknown
+  readonly body: unknown
+  readonly output: unknown
+}
+
+/** The accumulated, type-level map of every route on a Server: path → method → RouteInfo. */
+export type Registry = Record<string, Record<string, RouteInfo>>
+
+/** The empty registry (no routes). `NonNullable<unknown>` is `{}` without tripping noBannedTypes. */
+export type EmptyRegistry = NonNullable<unknown>
+
+type RegistryBody<S extends RouteSchema> = S extends { body: infer B extends StandardSchemaV1 }
+  ? InferOutput<B>
+  : never
+
+type RegistryQuery<S extends RouteSchema> = S extends { query: infer Q extends StandardSchemaV1 }
+  ? InferOutput<Q>
+  : never
+
+/** The client-visible output: the declared `response` contract when present (so the client sees the
+ * contract, not the handler's incidental return), otherwise the inferred handler output. */
+type RegistryOutput<S extends RouteSchema, Output> = S extends {
+  response: infer R extends StandardSchemaV1
+}
+  ? InferOutput<R>
+  : Output
+
+/** Build a {@link RouteInfo} from a route's path, schema, and handler output type. */
+export type RouteInfoFor<Path extends string, S extends RouteSchema, Output> = {
+  readonly params: Params<Path>
+  readonly query: RegistryQuery<S>
+  readonly body: RegistryBody<S>
+  readonly output: RegistryOutput<S, Output>
+}
+
+/** The client-visible output of a handler: its awaited return, minus raw `Response`. */
+export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
+  Awaited<ReturnType<H>>,
+  Response
+>
+
+/** Merge a new route into the registry, combining methods that share a path. */
+export type AddRoute<
+  R extends Registry,
+  Method extends string,
+  Path extends string,
+  Info extends RouteInfo,
+> = R & { [P in Path]: { [M in Method]: Info } }