velocious 1.0.430 → 1.0.432

package/src/http-server/cookie.js

@@ -0,0 +1,245 @@
+// @ts-check
+
+import crypto from "crypto"
+
+export default class Cookie {
+  /**
+   * CookieOptions type.
+   * @typedef {object} CookieOptions
+   * @property {string} [domain] - Domain.
+   * @property {Date} [expires] - Expires date.
+   * @property {boolean} [httpOnly] - HttpOnly flag.
+   * @property {number} [maxAge] - Max-Age in seconds.
+   * @property {string} [path] - Path.
+   * @property {boolean} [secure] - Secure flag.
+   * @property {"Lax" | "Strict" | "None"} [sameSite] - SameSite value.
+   */
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} args.name - Cookie name.
+   * @param {string | undefined | null} args.value - Cookie value.
+   * @param {string | undefined | null} [args.rawValue] - Raw cookie value.
+   * @param {CookieOptions} [args.options] - Cookie options.
+   * @param {boolean} [args.encrypted] - Whether cookie is encrypted.
+   * @param {Error | undefined} [args.error] - Decryption error.
+   */
+  constructor({name, value, rawValue, options, encrypted = false, error}) {
+    this._name = name
+    this._value = value ?? ""
+    this._rawValue = rawValue ?? this._value
+    this._options = options || {}
+    this._encrypted = encrypted
+    this._error = error
+  }
+
+  /**
+   * Runs name.
+   * @returns {string} - Cookie name.
+   */
+  name() { return this._name }
+
+  /**
+   * Runs value.
+   * @returns {string} - Cookie value (decrypted when available).
+   */
+  value() { return String(this._value ?? "") }
+
+  /**
+   * Runs raw value.
+   * @returns {string} - Raw cookie value.
+   */
+  rawValue() { return String(this._rawValue ?? "") }
+
+  /**
+   * Runs is encrypted.
+   * @returns {boolean} - Whether cookie is encrypted.
+   */
+  isEncrypted() { return Boolean(this._encrypted) }
+
+  /**
+   * Runs error.
+   * @returns {Error | undefined} - Decryption error.
+   */
+  error() { return this._error }
+
+  /**
+   * Runs to header.
+   * @returns {string} - Set-Cookie header value.
+   */
+  toHeader() {
+    const parts = []
+    const value = encodeURIComponent(this.rawValue())
+
+    parts.push(`${this._name}=${value}`)
+
+    if (this._options.domain) parts.push(`Domain=${this._options.domain}`)
+    if (this._options.path) parts.push(`Path=${this._options.path}`)
+    if (this._options.expires instanceof Date) parts.push(`Expires=${this._options.expires.toUTCString()}`)
+    if (typeof this._options.maxAge === "number") parts.push(`Max-Age=${this._options.maxAge}`)
+    if (this._options.httpOnly) parts.push("HttpOnly")
+    if (this._options.secure) parts.push("Secure")
+    if (this._options.sameSite) parts.push(`SameSite=${this._options.sameSite}`)
+
+    return parts.join("; ")
+  }
+
+  /**
+   * Runs parse header.
+   * @param {string | undefined | null} headerValue - Cookie header.
+   * @param {string | undefined} secret - Encryption secret.
+   * @returns {Cookie[]} - Cookie list.
+   */
+  static parseHeader(headerValue, secret) {
+    if (!headerValue) return []
+
+    return headerValue.split(";").map((pair) => pair.trim()).filter(Boolean).map((pair) => {
+      const [name, ...rest] = pair.split("=")
+      const rawValue = rest.join("=")
+      let value = rawValue
+
+      try {
+        value = decodeURIComponent(rawValue)
+      } catch {
+        // Use raw value when decoding fails.
+      }
+
+      if (value.startsWith("enc:v1:")) {
+        if (!secret) {
+          return new Cookie({name, value: "", rawValue: value, encrypted: true, error: new Error("No cookie secret configured")})
+        }
+
+        try {
+          const decryptedValue = this.decryptValue(value, secret)
+          return new Cookie({name, value: decryptedValue, rawValue: value, encrypted: true})
+        } catch (error) {
+          const ensuredError = error instanceof Error ? error : new Error(String(error))
+          return new Cookie({name, value: "", rawValue: value, encrypted: true, error: ensuredError})
+        }
+      }
+
+      return new Cookie({name, value, rawValue: value})
+    })
+  }
+
+  /**
+   * Runs encrypt value.
+   * @param {?} value - Value to encrypt.
+   * @param {string} secret - Encryption secret.
+   * @returns {string} - Encrypted value.
+   */
+  static encryptValue(value, secret) {
+    if (!secret) throw new Error("No cookie secret configured")
+
+    const {payload, type} = this._serializeEncryptedValue(value)
+    const iv = crypto.randomBytes(12)
+    const key = this._deriveKey(secret)
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv)
+    const encrypted = Buffer.concat([cipher.update(payload, "utf8"), cipher.final()])
+    const authTag = cipher.getAuthTag()
+
+    return `enc:v1:${type}.${this._toBase64Url(iv)}.${this._toBase64Url(authTag)}.${this._toBase64Url(encrypted)}`
+  }
+
+  /**
+   * Runs decrypt value.
+   * @param {string} value - Encrypted value.
+   * @param {string} secret - Encryption secret.
+   * @returns {string} - Decrypted value.
+   */
+  static decryptValue(value, secret) {
+    if (!secret) throw new Error("No cookie secret configured")
+    if (!value.startsWith("enc:v1:")) return value
+
+    const payload = value.slice("enc:v1:".length)
+    const [type, ivEncoded, tagEncoded, dataEncoded] = payload.split(".")
+
+    if (!type || !ivEncoded || !tagEncoded || !dataEncoded) {
+      throw new Error("Invalid encrypted cookie format")
+    }
+
+    const iv = this._fromBase64Url(ivEncoded)
+    const authTag = this._fromBase64Url(tagEncoded)
+    const data = this._fromBase64Url(dataEncoded)
+    const key = this._deriveKey(secret)
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv)
+
+    decipher.setAuthTag(authTag)
+
+    const decrypted = Buffer.concat([decipher.update(data), decipher.final()]).toString("utf8")
+
+    return this._deserializeEncryptedValue(type, decrypted)
+  }
+
+  /**
+   * Runs serialize encrypted value.
+   * @param {?} value - Value to serialize.
+   * @returns {{payload: string, type: string}} - Serialized payload.
+   */
+  static _serializeEncryptedValue(value) {
+    if (typeof value === "string") return {payload: value, type: "s"}
+    if (value === undefined) return {payload: "", type: "s"}
+
+    try {
+      const payload = JSON.stringify(value)
+
+      if (payload === undefined) {
+        return {payload: String(value), type: "s"}
+      }
+
+      return {payload, type: "j"}
+    } catch {
+      return {payload: String(value), type: "s"}
+    }
+  }
+
+  /**
+   * Runs deserialize encrypted value.
+   * @param {string} type - Serialized type.
+   * @param {string} payload - Payload.
+   * @returns {string} - Deserialized value.
+   */
+  static _deserializeEncryptedValue(type, payload) {
+    if (type === "j") {
+      try {
+        const parsed = JSON.parse(payload)
+        return typeof parsed === "string" ? parsed : JSON.stringify(parsed)
+      } catch {
+        return payload
+      }
+    }
+
+    return payload
+  }
+
+  /**
+   * Runs derive key.
+   * @param {string} secret - Secret.
+   * @returns {Buffer} - Key.
+   */
+  static _deriveKey(secret) {
+    return crypto.createHash("sha256").update(secret).digest()
+  }
+
+  /**
+   * Runs to base64 url.
+   * @param {Buffer} buffer - Buffer.
+   * @returns {string} - Base64 URL encoded string.
+   */
+  static _toBase64Url(buffer) {
+    return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "")
+  }
+
+  /**
+   * Runs from base64 url.
+   * @param {string} value - Base64 URL encoded string.
+   * @returns {Buffer} - Buffer.
+   */
+  static _fromBase64Url(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/")
+    const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - (normalized.length % 4))
+
+    return Buffer.from(`${normalized}${padding}`, "base64")
+  }
+}

package/src/http-server/development-reloader.js

@@ -0,0 +1,240 @@
+// @ts-check
+
+import {watch as fsWatch} from "fs"
+import fs from "fs/promises"
+import Logger from "../logger.js"
+import path from "path"
+
+const RELOADABLE_EXTENSIONS = new Set([
+  ".cjs",
+  ".ejs",
+  ".js",
+  ".json",
+  ".mjs"
+])
+
+/**
+ * Development-only file watcher that asks the HTTP server to recycle workers
+ * when application source files change.
+ */
+export default class VelociousHttpServerDevelopmentReloader {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+   * @param {function({changedPath: string}) : Promise<void>} args.onReload - Reload callback.
+   * @param {number} [args.debounceMs] - Debounce window for grouped changes.
+   * @param {typeof fsWatch} [args.watchFactory] - File watch factory.
+   * @param {typeof fs.readdir} [args.readdir] - Directory reader.
+   * @param {typeof fs.stat} [args.stat] - Stat reader.
+   */
+  constructor({configuration, onReload, debounceMs = 75, watchFactory = fsWatch, readdir = fs.readdir, stat = fs.stat}) {
+    this.configuration = configuration
+    this.debounceMs = debounceMs
+    this.logger = new Logger("DevelopmentReloader", {configuration})
+    this.onReload = onReload
+    this.readdir = readdir
+    this.stat = stat
+    this.watchFactory = watchFactory
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {ReturnType<typeof setTimeout> | undefined} */
+    this.reloadTimer = undefined
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {string | undefined} */
+    this.pendingChangedPath = undefined
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Map<string, import("fs").FSWatcher>} */
+    this.watchers = new Map()
+  }
+
+  /**
+   * Runs start.
+   * @returns {Promise<void>} - Resolves when watching has started.
+   */
+  async start() {
+    for (const rootPath of this.watchRootPaths()) {
+      await this.watchDirectoryRecursive(rootPath)
+    }
+  }
+
+  /**
+   * Runs watch root paths.
+   * @returns {string[]} - Source directories to watch.
+   */
+  watchRootPaths() {
+    const rootPaths = new Set()
+    const configurationDirectory = this.configuration.getDirectory()
+
+    rootPaths.add(path.join(configurationDirectory, "src"))
+
+    for (const backendProject of this.configuration.getBackendProjects()) {
+      if (!backendProject?.path) continue
+      rootPaths.add(path.join(backendProject.path, "src"))
+    }
+
+    return Array.from(rootPaths)
+  }
+
+  /**
+   * Runs watch directory recursive.
+   * @param {string} directoryPath - Directory path.
+   * @returns {Promise<void>} - Resolves when child directories are watched.
+   */
+  async watchDirectoryRecursive(directoryPath) {
+    const resolvedDirectoryPath = path.resolve(directoryPath)
+
+    if (this.watchers.has(resolvedDirectoryPath)) return
+
+    let entries
+
+    try {
+      entries = await this.readdir(resolvedDirectoryPath, {withFileTypes: true})
+    } catch (error) {
+      if (/**
+           * Narrows the runtime value to the documented type.
+            @type {{code?: string}} */ (error)?.code === "ENOENT") return
+      throw error
+    }
+
+    const watcher = this.watchFactory(resolvedDirectoryPath, (eventType, fileName) => {
+      void this.onWatcherEvent({
+        directoryPath: resolvedDirectoryPath,
+        eventType,
+        fileName
+      })
+    })
+
+    watcher.on("error", this.onWatcherError)
+    this.watchers.set(resolvedDirectoryPath, watcher)
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+
+      await this.watchDirectoryRecursive(path.join(resolvedDirectoryPath, entry.name))
+    }
+  }
+
+  /**
+   * Runs on watcher event.
+   * @param {object} args - Options object.
+   * @param {string} args.directoryPath - Watched directory path.
+   * @param {string} args.eventType - Watch event type.
+   * @param {string | Buffer | null} args.fileName - Relative changed filename.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async onWatcherEvent({directoryPath, eventType, fileName}) {
+    const changedPath = fileName
+      ? path.join(directoryPath, fileName.toString())
+      : directoryPath
+
+    await this.watchPotentialDirectory(changedPath)
+
+    if (!this.shouldReloadPath({changedPath, fileName})) return
+
+    this.scheduleReload(changedPath)
+
+    await this.logger.debug(() => ["Queued development hot reload", {changedPath, eventType}])
+  }
+
+  /**
+   * Runs should reload path.
+   * @param {object} args - Options object.
+   * @param {string} args.changedPath - Changed path.
+   * @param {string | Buffer | null} args.fileName - Raw filename from fs.watch.
+   * @returns {boolean} - Whether the path should trigger reload.
+   */
+  shouldReloadPath({changedPath, fileName}) {
+    if (!fileName) return true
+
+    const extension = path.extname(changedPath).toLowerCase()
+
+    return RELOADABLE_EXTENSIONS.has(extension)
+  }
+
+  /**
+   * Runs watch potential directory.
+   * @param {string} changedPath - Candidate directory path.
+   * @returns {Promise<void>} - Resolves when any new directory watchers are added.
+   */
+  async watchPotentialDirectory(changedPath) {
+    try {
+      const stat = await this.stat(changedPath)
+
+      if (stat.isDirectory()) {
+        await this.watchDirectoryRecursive(changedPath)
+      }
+    } catch (error) {
+      if (/**
+           * Narrows the runtime value to the documented type.
+            @type {{code?: string}} */ (error)?.code !== "ENOENT") {
+        throw error
+      }
+    }
+  }
+
+  /**
+   * Runs schedule reload.
+   * @param {string} changedPath - Changed path.
+   * @returns {void} - No return value.
+   */
+  scheduleReload(changedPath) {
+    this.pendingChangedPath = changedPath
+
+    if (this.reloadTimer) {
+      clearTimeout(this.reloadTimer)
+    }
+
+    this.reloadTimer = setTimeout(() => {
+      void this.flushReload()
+    }, this.debounceMs)
+  }
+
+  /**
+   * Runs flush reload.
+   * @returns {Promise<void>} - Resolves when the queued reload is handled.
+   */
+  async flushReload() {
+    this.reloadTimer = undefined
+
+    const changedPath = this.pendingChangedPath
+
+    if (!changedPath) return
+
+    this.pendingChangedPath = undefined
+    await this.onReload({changedPath})
+  }
+
+  /**
+   * On watcher error.
+   * @param {Error} error - Watcher error.
+   * @returns {void} - No return value.
+   */
+  onWatcherError = (error) => {
+    void this.logger.warn("Development hot reload watcher error", error)
+  }
+
+  /**
+   * Runs stop.
+   * @returns {Promise<void>} - Resolves when watchers are closed.
+   */
+  async stop() {
+    if (this.reloadTimer) {
+      clearTimeout(this.reloadTimer)
+      this.reloadTimer = undefined
+    }
+
+    this.pendingChangedPath = undefined
+
+    for (const watcher of this.watchers.values()) {
+      watcher.close()
+    }
+
+    this.watchers.clear()
+  }
+}