@adonisjs/http-server 6.8.2-4 → 6.8.2-6

package/src/cookies/client.ts

@@ -0,0 +1,98 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { Encryption } from '@adonisjs/encryption'
+
+import * as plainCookiesDriver from './drivers/plain.js'
+import * as signedCookiesDriver from './drivers/signed.js'
+import * as encryptedCookiesDriver from './drivers/encrypted.js'
+
+/**
+ * Cookie client exposes the API to parse/set AdonisJS cookies
+ * as a client.
+ */
+export class CookieClient {
+  #encryption: Encryption
+
+  constructor(encryption: Encryption) {
+    this.#encryption = encryption
+  }
+
+  /**
+   * Encrypt a key value pair to be sent in the cookie header
+   */
+  encrypt(key: string, value: any): string | null {
+    return encryptedCookiesDriver.pack(key, value, this.#encryption)
+  }
+
+  /**
+   * Sign a key value pair to be sent in the cookie header
+   */
+  sign(key: string, value: any): string | null {
+    return signedCookiesDriver.pack(key, value, this.#encryption)
+  }
+
+  /**
+   * Encode a key value pair to be sent in the cookie header
+   */
+  encode(_: string, value: any): string | null {
+    return plainCookiesDriver.pack(value)
+  }
+
+  /**
+   * Unsign a signed cookie value
+   */
+  unsign(key: string, value: string) {
+    return signedCookiesDriver.canUnpack(value)
+      ? signedCookiesDriver.unpack(key, value, this.#encryption)
+      : null
+  }
+
+  /**
+   * Decrypt an encrypted cookie value
+   */
+  decrypt(key: string, value: string) {
+    return encryptedCookiesDriver.canUnpack(value)
+      ? encryptedCookiesDriver.unpack(key, value, this.#encryption)
+      : null
+  }
+
+  /**
+   * Decode an encoded cookie value
+   */
+  decode(_: string, value: string) {
+    return plainCookiesDriver.canUnpack(value) ? plainCookiesDriver.unpack(value) : null
+  }
+
+  /**
+   * Parse response cookie
+   */
+  parse(key: string, value: any) {
+    /**
+     * Unsign signed cookie
+     */
+    if (signedCookiesDriver.canUnpack(value)) {
+      return signedCookiesDriver.unpack(key, value, this.#encryption)
+    }
+
+    /**
+     * Decrypted encrypted cookie
+     */
+    if (encryptedCookiesDriver.canUnpack(value)) {
+      return encryptedCookiesDriver.unpack(key, value, this.#encryption)
+    }
+
+    /**
+     * Decode encoded cookie
+     */
+    if (plainCookiesDriver.canUnpack(value)) {
+      return plainCookiesDriver.unpack(value)
+    }
+  }
+}

package/src/cookies/drivers/encrypted.ts

@@ -0,0 +1,42 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { Encryption } from '@adonisjs/encryption'
+
+/**
+ * Encrypt a value to be set as cookie
+ */
+export function pack(key: string, value: any, encryption: Encryption): null | string {
+  if (value === undefined || value === null) {
+    return null
+  }
+  return `e:${encryption.encrypt(value, undefined, key)}`
+}
+
+/**
+ * Returns a boolean, if the unpack method from this module can attempt
+ * to unpack encrypted value.
+ */
+export function canUnpack(encryptedValue: string) {
+  return typeof encryptedValue === 'string' && encryptedValue.substring(0, 2) === 'e:'
+}
+
+/**
+ * Attempts to unpack the encrypted cookie value. Returns null, when fails to do so.
+ * Only call this method, when `canUnpack` returns true, otherwise runtime
+ * exceptions can be raised.
+ */
+export function unpack(key: string, encryptedValue: string, encryption: Encryption): null | any {
+  const value = encryptedValue.slice(2)
+  if (!value) {
+    return null
+  }
+
+  return encryption.decrypt(value, key)
+}

package/src/cookies/drivers/plain.ts

@@ -0,0 +1,37 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { base64, MessageBuilder } from '@poppinss/utils'
+
+/**
+ * Encodes a value into a base64 url encoded string to
+ * be set as cookie
+ */
+export function pack(value: any): null | string {
+  if (value === undefined || value === null) {
+    return null
+  }
+  return base64.urlEncode(new MessageBuilder().build(value))
+}
+
+/**
+ * Returns true when this `unpack` method of this module can attempt
+ * to unpack the encode value.
+ */
+export function canUnpack(encodedValue: string) {
+  return typeof encodedValue === 'string'
+}
+
+/**
+ * Attempts to unpack the value by decoding it. Make sure to call, `canUnpack`
+ * before calling this method
+ */
+export function unpack(encodedValue: string): null | any {
+  return new MessageBuilder().verify(base64.urlDecode(encodedValue, 'utf-8', false))
+}

package/src/cookies/drivers/signed.ts

@@ -0,0 +1,42 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { Encryption } from '@adonisjs/encryption'
+
+/**
+ * Signs a value to be shared as a cookie. The signed output has a
+ * hash to verify tampering with the original value
+ */
+export function pack(key: string, value: any, encryption: Encryption): null | string {
+  if (value === undefined || value === null) {
+    return null
+  }
+  return `s:${encryption.verifier.sign(value, undefined, key)}`
+}
+
+/**
+ * Returns a boolean, if the unpack method from this module can attempt
+ * to unpack the signed value.
+ */
+export function canUnpack(signedValue: string) {
+  return typeof signedValue === 'string' && signedValue.substring(0, 2) === 's:'
+}
+
+/**
+ * Attempts to unpack the signed value. Make sure to call `canUnpack` before
+ * calling this method.
+ */
+export function unpack(key: string, signedValue: string, encryption: Encryption): null | any {
+  const value = signedValue.slice(2)
+  if (!value) {
+    return null
+  }
+
+  return encryption.verifier.unsign(value, key)
+}

package/src/cookies/parser.ts

@@ -0,0 +1,196 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import cookie from 'cookie'
+import type { Encryption } from '@adonisjs/encryption'
+
+import { CookieClient } from './client.js'
+
+/**
+ * Cookie parser parses the HTTP `cookie` header and collects all cookies
+ * inside an object of `key-value` pair, but doesn't attempt to decrypt
+ * or unsign or decode the individual values.
+ *
+ * The cookie values are lazily decrypted, or unsigned to avoid unncessary
+ * processing, which infact can be used as a means to burden the server
+ * by sending too many cookies which even doesn't belongs to the
+ * server.
+ */
+export class CookieParser {
+  #client: CookieClient
+
+  /**
+   * A copy of cached cookies, they are cached during a request after
+   * initial decoding, unsigning or decrypting.
+   */
+  #cachedCookies: {
+    encryptedCookies: Record<string, any>
+    signedCookies: Record<string, any>
+    plainCookies: Record<string, any>
+  } = {
+    signedCookies: {},
+    plainCookies: {},
+    encryptedCookies: {},
+  }
+
+  /**
+   * An object of key-value pair collected by parsing
+   * the request cookie header.
+   */
+  #cookies: Record<string, any>
+
+  constructor(cookieHeader: string, encryption: Encryption) {
+    this.#client = new CookieClient(encryption)
+    this.#cookies = this.#parse(cookieHeader)
+  }
+
+  /**
+   * Parses the request `cookie` header
+   */
+  #parse(cookieHeader?: string) {
+    /*
+     * Set to empty object when cookie header is empty string
+     */
+    if (!cookieHeader) {
+      return {}
+    }
+
+    /*
+     * Parse and store reference
+     */
+    return cookie.parse(cookieHeader)
+  }
+
+  /**
+   * Attempts to decode a cookie by the name. When calling this method,
+   * you are assuming that the cookie was just encoded in the first
+   * place and not signed or encrypted.
+   */
+  decode(key: string, encoded = true): any | null {
+    /*
+     * Ignore when initial value is not defined or null
+     */
+    const value = this.#cookies[key]
+    if (value === null || value === undefined) {
+      return null
+    }
+
+    /*
+     * Reference to the cache object. Mainly done to avoid typos,
+     * since this object is referenced a handful of times inside
+     * this method.
+     */
+    const cache = this.#cachedCookies.plainCookies
+
+    /*
+     * Return from cache, when already parsed
+     */
+    if (cache[key] !== undefined) {
+      return cache[key]
+    }
+
+    /*
+     * Attempt to unpack and cache it for future. The value is only
+     * when value it is not null.
+     */
+    const parsed = encoded ? this.#client.decode(key, value) : value
+    if (parsed !== null) {
+      cache[key] = parsed
+    }
+
+    return parsed
+  }
+
+  /**
+   * Attempts to unsign a cookie by the name. When calling this method,
+   * you are assuming that the cookie was signed in the first place.
+   */
+  unsign(key: string): null | any {
+    /*
+     * Ignore when initial value is not defined or null
+     */
+    const value = this.#cookies[key]
+    if (value === null || value === undefined) {
+      return null
+    }
+
+    /*
+     * Reference to the cache object. Mainly done to avoid typos,
+     * since this object is referenced a handful of times inside
+     * this method.
+     */
+    const cache = this.#cachedCookies.signedCookies
+
+    /*
+     * Return from cache, when already parsed
+     */
+    if (cache[key] !== undefined) {
+      return cache[key]
+    }
+
+    /*
+     * Attempt to unpack and cache it for future. The value is only
+     * when value it is not null.
+     */
+    const parsed = this.#client.unsign(key, value)
+    if (parsed !== null) {
+      cache[key] = parsed
+    }
+
+    return parsed
+  }
+
+  /**
+   * Attempts to decrypt a cookie by the name. When calling this method,
+   * you are assuming that the cookie was encrypted in the first place.
+   */
+  decrypt(key: string): null | any {
+    /*
+     * Ignore when initial value is not defined or null
+     */
+    const value = this.#cookies[key]
+    if (value === null || value === undefined) {
+      return null
+    }
+
+    /*
+     * Reference to the cache object. Mainly done to avoid typos,
+     * since this object is referenced a handful of times inside
+     * this method.
+     */
+    const cache = this.#cachedCookies.encryptedCookies
+
+    /*
+     * Return from cache, when already parsed
+     */
+    if (cache[key] !== undefined) {
+      return cache[key]
+    }
+
+    /*
+     * Attempt to unpack and cache it for future. The value is only
+     * when value it is not null.
+     */
+    const parsed = this.#client.decrypt(key, value)
+    if (parsed !== null) {
+      cache[key] = parsed
+    }
+
+    return parsed
+  }
+
+  /**
+   * Returns an object of cookies key-value pair. Do note, the
+   * cookies are not decoded, unsigned or decrypted inside this
+   * list.
+   */
+  list() {
+    return this.#cookies
+  }
+}

package/src/cookies/serializer.ts

@@ -0,0 +1,98 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import cookie from 'cookie'
+import string from '@poppinss/utils/string'
+import type { Encryption } from '@adonisjs/encryption'
+
+import { CookieClient } from './client.js'
+import type { CookieOptions } from '../types/response.js'
+
+/**
+ * Cookies serializer is used to serialize a value to be set on the `Set-Cookie`
+ * header. You can `encode`, `sign` on `encrypt` cookies using the serializer
+ * and then set them individually using the `set-cookie` header.
+ */
+export class CookieSerializer {
+  #client: CookieClient
+
+  constructor(encryption: Encryption) {
+    this.#client = new CookieClient(encryption)
+  }
+
+  /**
+   * Serializes the key-value pair to a string, that can be set on the
+   * `Set-Cookie` header.
+   */
+  #serializeAsCookie(key: string, value: string, options?: Partial<CookieOptions>) {
+    /**
+     * Invoked expires method to get the date
+     */
+    let expires = options?.expires
+    if (typeof expires === 'function') {
+      expires = expires()
+    }
+
+    /**
+     * Parse string based max age to seconds
+     */
+    let maxAge = options?.maxAge ? string.seconds.parse(options?.maxAge) : undefined
+
+    const parsedOptions = Object.assign({}, options, { maxAge, expires })
+    return cookie.serialize(key, value, parsedOptions)
+  }
+
+  /**
+   * Encodes value as a plain cookie. By default, the plain value will be converted
+   * to a string using "JSON.stringify" method and then encoded as a base64 string.
+   *
+   * You can disable encoding of the cookie by setting `options.encoded = false`.
+   *
+   * ```ts
+   *  serializer.encode('name', 'virk')
+   * ```
+   */
+  encode(
+    key: string,
+    value: any,
+    options?: Partial<CookieOptions & { encode: boolean }>
+  ): string | null {
+    const packedValue = options?.encode === false ? value : this.#client.encode(key, value)
+    if (packedValue === null || packedValue === undefined) {
+      return null
+    }
+
+    return this.#serializeAsCookie(key, packedValue, options)
+  }
+
+  /**
+   * Sign a key-value pair to a signed cookie. The signed value has a
+   * verification hash attached to it to detect data tampering.
+   */
+  sign(key: string, value: any, options?: Partial<CookieOptions>): string | null {
+    const packedValue = this.#client.sign(key, value)
+    if (packedValue === null) {
+      return null
+    }
+
+    return this.#serializeAsCookie(key, packedValue, options)
+  }
+
+  /**
+   * Encrypts a key-value pair to an encrypted cookie.
+   */
+  encrypt(key: string, value: any, options?: Partial<CookieOptions>): string | null {
+    const packedValue = this.#client.encrypt(key, value)
+    if (packedValue === null) {
+      return null
+    }
+
+    return this.#serializeAsCookie(key, packedValue, options)
+  }
+}

package/src/debug.ts

@@ -0,0 +1,11 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { debuglog } from 'node:util'
+export default debuglog('adonisjs:http')

package/src/define_config.ts

@@ -0,0 +1,56 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import proxyAddr from 'proxy-addr'
+import string from '@poppinss/utils/string'
+import type { ServerConfig } from './types/server.js'
+
+/**
+ * Define configuration for the HTTP server
+ */
+export function defineConfig(config: Partial<ServerConfig>): ServerConfig {
+  const normalizedConfig = {
+    allowMethodSpoofing: false,
+    trustProxy: proxyAddr.compile('loopback'),
+    subdomainOffset: 2,
+    generateRequestId: false,
+    useAsyncLocalStorage: false,
+    etag: false,
+    jsonpCallbackName: 'callback',
+    cookie: {
+      maxAge: '2h',
+      path: '/',
+      httpOnly: true,
+      secure: false,
+      sameSite: false,
+    },
+    qs: {
+      parse: {
+        depth: 5,
+        parameterLimit: 1000,
+        allowSparse: false,
+        arrayLimit: 20,
+        comma: true,
+      },
+      stringify: {
+        encode: true,
+        encodeValuesOnly: false,
+        arrayFormat: 'indices' as const,
+        skipNulls: false,
+      },
+    },
+    ...config,
+  }
+
+  if (normalizedConfig.cookie.maxAge) {
+    normalizedConfig.cookie.maxAge = string.seconds.parse(normalizedConfig.cookie.maxAge)
+  }
+
+  return normalizedConfig
+}

package/src/define_middleware.ts

@@ -0,0 +1,61 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { moduleImporter } from '@adonisjs/fold'
+import type { LazyImport, UnWrapLazyImport } from './types/base.js'
+import type {
+  GetMiddlewareArgs,
+  MiddlewareAsClass,
+  ParsedGlobalMiddleware,
+} from './types/middleware.js'
+
+/**
+ * Converts a middleware name and its lazy import to a factory function. The function
+ * can than later be used to reference the middleware with different arguments
+ * every time.
+ */
+function middlewareReferenceBuilder(
+  name: string | number | symbol,
+  middleware: LazyImport<MiddlewareAsClass>
+) {
+  const handler = moduleImporter(middleware, 'handle').toHandleMethod()
+  return function (...args: any[]) {
+    return {
+      name,
+      args: args[0],
+      ...handler,
+    }
+  }
+}
+
+/**
+ * Define an collection of named middleware. The collection gets converted
+ * into a collection of factory functions. Calling the function returns
+ * a reference to the executable middleware.
+ */
+export function defineNamedMiddleware<
+  NamedMiddleware extends Record<string | number | symbol, LazyImport<MiddlewareAsClass>>
+>(collection: NamedMiddleware) {
+  return Object.keys(collection).reduce(
+    (result, key: keyof NamedMiddleware) => {
+      result[key] = middlewareReferenceBuilder(key, collection[key])
+      return result
+    },
+    {} as {
+      [K in keyof NamedMiddleware]: <
+        Args extends GetMiddlewareArgs<UnWrapLazyImport<NamedMiddleware[K]>>
+      >(
+        ...args: Args
+      ) => {
+        name: K
+        args: Args[0]
+      } & ParsedGlobalMiddleware
+    }
+  )
+}