@getsoda/core 0.1.1 → 0.2.1

package/src/http/middleware.ts

@@ -0,0 +1,124 @@
+/**
+ * @module
+ * Application middleware: runs around every request, before routing.
+ *
+ * Unlike guards and interceptors, which belong to a route, middleware sees
+ * every request: unknown paths (404), wrong methods (405), CORS preflights.
+ * That is where CORS, request ids, access logs or compression belong.
+ *
+ * ```ts
+ * const requestId: MiddlewareFunction = async (req, next) => {
+ *   const response = await next()
+ *
+ *   response.headers.set('x-request-id', crypto.randomUUID())
+ *
+ *   return response
+ * }
+ *
+ * await createApp(AppModule, { middleware: [cors({ origin: 'https://app.example.com' }), requestId] })
+ * ```
+ *
+ * As guards: a class is created once by the container (root module) and gets
+ * lifecycle hooks, a function runs where `inject()` works, an instance is used as is.
+ */
+
+import type { Constructor } from '../di/index.ts'
+import type { NativeHandler } from '../routing/index.ts'
+
+/** Continues with the next middleware, then the route. */
+export type Next = () => Promise<Response>
+
+/** Class middleware. Like Nest's `NestMiddleware`, for the Fetch API. */
+export interface NestMiddleware {
+  use(req: Request, next: Next): Response | Promise<Response>
+}
+
+/** Function middleware; `inject()` works inside it, before the first `await`. */
+export type MiddlewareFunction = (req: Request, next: Next) => Response | Promise<Response>
+
+/** What `middleware` accepts. */
+export type Middleware = Constructor<NestMiddleware> | NestMiddleware | MiddlewareFunction
+
+type Step = (req: Request, next: Next) => Response | Promise<Response>
+
+/** Runs a step, turning a synchronous throw into a rejection. */
+const settle = (step: () => Response | Promise<Response>): Promise<Response> => {
+  try {
+    return Promise.resolve(step())
+  } catch (error) {
+    return Promise.reject(error)
+  }
+}
+
+/**
+ * Turns middleware declarations into steps. Classes are created now, inside
+ * `runInContext`, and passed to `onCreate` for their lifecycle hooks.
+ */
+export const resolveMiddleware = (
+  middleware: readonly Middleware[],
+  runInContext: <R>(fn: () => R) => R,
+  onCreate: (instance: unknown) => void
+): Step[] => {
+  const steps: Step[] = []
+
+  for (const entry of middleware) {
+    if (typeof entry === 'function' && typeof (entry.prototype as Record<string, unknown> | undefined)?.use === 'function') {
+      const instance = runInContext(() => new (entry as Constructor<NestMiddleware>)())
+
+      onCreate(instance)
+      steps.push((req, next) => instance.use(req, next))
+    } else if (typeof entry === 'function') {
+      const fn = entry as MiddlewareFunction
+
+      steps.push((req, next) => runInContext(() => fn(req, next)))
+    } else if (typeof entry === 'object' && entry !== null && typeof entry.use === 'function') {
+      steps.push((req, next) => entry.use(req, next))
+    } else {
+      throw new TypeError(`Invalid middleware: ${String(entry)} is neither a function nor an object with use()`)
+    }
+  }
+
+  return steps
+}
+
+/**
+ * Wraps `handler` with the middleware steps, first one outermost.
+ * Errors of middleware go to `onError`, which builds the response.
+ */
+export const withMiddleware = <R extends Request>(
+  steps: readonly Step[],
+  handler: (req: R) => Response | Promise<Response>,
+  onError: (error: unknown, req: Request) => Response
+): ((req: R) => Promise<Response>) => {
+  const count = steps.length
+
+  return (req) => {
+    const call = (index: number): Promise<Response> =>
+      index === count ? settle(() => handler(req)) : settle(() => steps[index]!(req, () => call(index + 1)))
+
+    return call(0).catch((error: unknown) => onError(error, req))
+  }
+}
+
+/**
+ * Applies middleware to every native route and to the fallback of a compiled table.
+ * Without middleware, the table is returned unchanged: no wrapper on the request path.
+ */
+export const applyMiddleware = (
+  steps: readonly Step[],
+  routes: Record<string, NativeHandler>,
+  fetch: (req: Request) => Response | Promise<Response>,
+  onError: (error: unknown, req: Request) => Response
+): { routes: Record<string, NativeHandler>; fetch: (req: Request) => Response | Promise<Response> } => {
+  if (steps.length === 0) {
+    return { routes, fetch }
+  }
+
+  const wrapped: Record<string, NativeHandler> = {}
+
+  for (const key of Object.keys(routes)) {
+    wrapped[key] = withMiddleware(steps, routes[key]!, onError)
+  }
+
+  return { routes: wrapped, fetch: withMiddleware(steps, fetch, onError) }
+}

package/src/http/parsers.ts

@@ -39,7 +39,8 @@ const INTEGER = /^-?\d+$/
 const NUMBER = /^-?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
-const failure = (name: string, expected: string): BadRequestException =>
+/** The `400` of a value that is missing or not what a parser expects. */
+export const failure = (name: string, expected: string): BadRequestException =>
   new BadRequestException(`Validation failed for "${name}" (${expected} is expected)`)
 
 const createParser = <T>(

package/src/http/routes.ts

@@ -11,7 +11,7 @@
  * ```
  */
 
-import type { Container, ControllerEntry, ModuleClass } from '../di/index.ts'
+import type { Constructor, Container, ControllerEntry, ModuleClass } from '../di/index.ts'
 import type { RouteDefinition } from '../routing/index.ts'
 import { parsePath } from '../routing/path.ts'
 import { isThenable } from '../utils/promise.ts'
@@ -156,6 +156,7 @@ const resolveAll = <T, S>(
  */
 class RoutesBuilder {
   readonly routes: RouteDefinition[] = []
+  readonly controllers: MappedController[] = []
   /** Guards, interceptors and filters created from classes, in creation order. */
   readonly enhancers: unknown[] = []
   readonly #options: ControllerRoutesOptions
@@ -184,10 +185,14 @@ class RoutesBuilder {
 
     const basePath = joinPaths(this.#options.prefix ?? '', controllerPath)
 
+    const start = this.routes.length
+
     // The most derived function: an override without route decorators has no metadata.
     for (const name of methodNames(entry.instance as object)) {
       this.#addMethod(entry, basePath, name)
     }
+
+    this.controllers.push({ controller: entry.controller, path: basePath, routes: this.routes.slice(start) })
   }
 
   #resolverOf(entry: ControllerEntry): EnhancerResolver {
@@ -251,12 +256,22 @@ class RoutesBuilder {
   }
 }
 
+/** A controller and the routes made from it, as `createApp` logs them at startup. */
+export interface MappedController {
+  readonly controller: Constructor<unknown>
+  /** Path of the controller, with the global prefix. */
+  readonly path: string
+  readonly routes: readonly RouteDefinition[]
+}
+
 /**
  * Routes of every controller, and the guards, interceptors and filters created
  * for them from classes (whose lifecycle hooks the application runs).
  */
 export interface BuiltRoutes {
   readonly routes: RouteDefinition[]
+  /** In module order. */
+  readonly controllers: readonly MappedController[]
   /** In creation order. */
   readonly enhancers: readonly unknown[]
 }
@@ -271,7 +286,7 @@ export const buildRoutes = (container: Container, options: ControllerRoutesOptio
     builder.addController(entry)
   }
 
-  return { routes: builder.routes, enhancers: builder.enhancers }
+  return { routes: builder.routes, controllers: builder.controllers, enhancers: builder.enhancers }
 }
 
 /**

package/src/index.ts

@@ -34,4 +34,5 @@
 export * from './app/index.ts'
 export * from './di/index.ts'
 export * from './http/index.ts'
+export * from './logger/index.ts'
 export * from './routing/index.ts'

package/src/jwt/algorithms.ts

@@ -0,0 +1,113 @@
+/**
+ * @module
+ * JWS algorithms (RFC 7518) on WebCrypto, and the keys they take.
+ */
+
+import type { webcrypto } from 'node:crypto'
+
+/** Algorithms a token can be signed with. `none` is not one of them. */
+export type JwtAlgorithm =
+  | 'HS256'
+  | 'HS384'
+  | 'HS512'
+  | 'RS256'
+  | 'RS384'
+  | 'RS512'
+  | 'PS256'
+  | 'PS384'
+  | 'PS512'
+  | 'ES256'
+  | 'ES384'
+  | 'ES512'
+  | 'EdDSA'
+
+/**
+ * A key: a `CryptoKey`, a JWK, a PEM string (`PRIVATE KEY` in PKCS #8 or
+ * `PUBLIC KEY` in SPKI), or the secret of an HMAC algorithm.
+ */
+export type JwtKey = CryptoKey | webcrypto.JsonWebKey | string
+
+type KeyParams = webcrypto.HmacImportParams | webcrypto.RsaHashedImportParams | webcrypto.EcKeyImportParams | webcrypto.Algorithm
+type SignParams = webcrypto.Algorithm | webcrypto.EcdsaParams | webcrypto.RsaPssParams
+
+/** Import parameters, and the signing parameters where they differ. */
+const ALGORITHMS: Readonly<Record<JwtAlgorithm, { readonly key: KeyParams; readonly sign: SignParams }>> = {
+  HS256: hmac('SHA-256'),
+  HS384: hmac('SHA-384'),
+  HS512: hmac('SHA-512'),
+  RS256: rsa('RSASSA-PKCS1-v1_5', 'SHA-256'),
+  RS384: rsa('RSASSA-PKCS1-v1_5', 'SHA-384'),
+  RS512: rsa('RSASSA-PKCS1-v1_5', 'SHA-512'),
+  PS256: pss('SHA-256', 32),
+  PS384: pss('SHA-384', 48),
+  PS512: pss('SHA-512', 64),
+  ES256: ecdsa('P-256', 'SHA-256'),
+  ES384: ecdsa('P-384', 'SHA-384'),
+  ES512: ecdsa('P-521', 'SHA-512'),
+  EdDSA: { key: { name: 'Ed25519' }, sign: { name: 'Ed25519' } },
+}
+
+function hmac(hash: string) {
+  const params = { name: 'HMAC', hash }
+
+  return { key: params, sign: params }
+}
+
+function rsa(name: string, hash: string) {
+  return { key: { name, hash }, sign: { name } }
+}
+
+function pss(hash: string, saltLength: number) {
+  return { key: { name: 'RSA-PSS', hash }, sign: { name: 'RSA-PSS', saltLength } }
+}
+
+function ecdsa(namedCurve: string, hash: string) {
+  return { key: { name: 'ECDSA', namedCurve }, sign: { name: 'ECDSA', hash } }
+}
+
+export const isJwtAlgorithm = (value: unknown): value is JwtAlgorithm => typeof value === 'string' && Object.hasOwn(ALGORITHMS, value)
+
+export const isHmac = (algorithm: JwtAlgorithm): boolean => algorithm.startsWith('HS')
+
+const pemBody = (pem: string): Uint8Array<ArrayBuffer> =>
+  Uint8Array.fromBase64(pem.replace(/-----(?:BEGIN|END) [A-Z ]+-----/g, '').replace(/\s/g, ''))
+
+/** Imports `key` once for `usage` with `algorithm`. */
+export const importKey = async (key: JwtKey, algorithm: JwtAlgorithm, usage: 'sign' | 'verify'): Promise<CryptoKey> => {
+  const params = ALGORITHMS[algorithm].key
+
+  if (key instanceof CryptoKey) {
+    return key
+  }
+
+  if (typeof key === 'object') {
+    return crypto.subtle.importKey('jwk', key, params, false, [usage])
+  }
+
+  if (isHmac(algorithm)) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(key), params, false, [usage])
+  }
+
+  if (key.includes('-----BEGIN PRIVATE KEY-----') && usage === 'sign') {
+    return crypto.subtle.importKey('pkcs8', pemBody(key), params, false, [usage])
+  }
+
+  if (key.includes('-----BEGIN PUBLIC KEY-----') && usage === 'verify') {
+    return crypto.subtle.importKey('spki', pemBody(key), params, false, [usage])
+  }
+
+  throw new TypeError(
+    `A ${algorithm} key must be a CryptoKey, a JWK or a PEM string: ` +
+      (usage === 'sign' ? 'a PKCS #8 "PRIVATE KEY" to sign' : 'an SPKI "PUBLIC KEY" to verify')
+  )
+}
+
+export const signBytes = async (algorithm: JwtAlgorithm, key: CryptoKey, data: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>> =>
+  new Uint8Array(await crypto.subtle.sign(ALGORITHMS[algorithm].sign, key, data))
+
+export const verifyBytes = (
+  algorithm: JwtAlgorithm,
+  key: CryptoKey,
+  signature: Uint8Array<ArrayBuffer>,
+  data: Uint8Array<ArrayBuffer>
+): Promise<boolean> => crypto.subtle.verify(ALGORITHMS[algorithm].sign, key, signature, data)

package/src/jwt/errors.ts

@@ -0,0 +1,30 @@
+/**
+ * @module
+ * Why a token was refused.
+ */
+
+export type JwtErrorCode =
+  /** Not three base64url parts holding JSON objects. */
+  | 'malformed'
+  /** Signed with another algorithm than the one configured, or with critical extensions. */
+  | 'algorithm'
+  /** The signature does not match. */
+  | 'signature'
+  /** `exp` is past. */
+  | 'expired'
+  /** `nbf` is still to come. */
+  | 'not-active'
+  /** A registered claim has the wrong type, or `iss` or `aud` is not the expected one. */
+  | 'claims'
+
+/** A token that `JwtService.verify()` refused. */
+export class JwtError extends Error {
+  override readonly name = 'JwtError'
+
+  constructor(
+    readonly code: JwtErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}

package/src/jwt/guard.ts

@@ -0,0 +1,74 @@
+/**
+ * @module
+ * `JwtGuard`: lets in requests carrying a valid token, the way
+ * `AuthGuard('jwt')` of `@nestjs/passport` does.
+ */
+
+import { inject } from '../di/index.ts'
+import type { Context } from '../http/context.ts'
+import { ContextKey } from '../http/context-key.ts'
+import type { CanActivate } from '../http/enhancers.ts'
+import { UnauthorizedException } from '../http/exceptions.ts'
+import { JwtError } from './errors.ts'
+import { JWT_OPTIONS } from './module.ts'
+import { JwtService } from './service.ts'
+import type { JwtPayload } from './service.ts'
+
+/** Payload of the token `JwtGuard` accepted: `ctx.get(JWT_PAYLOAD)` or `value(JWT_PAYLOAD)`. */
+export const JWT_PAYLOAD = new ContextKey<JwtPayload>('jwtPayload')
+
+const BEARER = /^Bearer +(\S+) *$/i
+
+/** A 401 with the `WWW-Authenticate` challenge of RFC 6750. */
+const unauthorized = (message: string, challenge: string, cause?: unknown): UnauthorizedException =>
+  new UnauthorizedException(message, { cause, headers: { 'www-authenticate': challenge } })
+
+/**
+ * Accepts a request whose token `JwtService` verifies, read from
+ * `Authorization: Bearer <token>` or, without that header, from the cookie
+ * named by the `cookie` option of `JwtModule`. The payload goes to
+ * {@link JWT_PAYLOAD}; anything else is a `401`.
+ *
+ * ```ts
+ * @Get('me', [value(JWT_PAYLOAD)])
+ * @UseGuards(JwtGuard)
+ * me(payload: JwtPayload) {}
+ * ```
+ *
+ * Needs `JwtModule` imported in the controller's module, or registered as global.
+ */
+export class JwtGuard implements CanActivate {
+  readonly #jwt = inject(JwtService)
+  readonly #cookie = inject(JWT_OPTIONS).cookie
+
+  async canActivate(ctx: Context): Promise<boolean> {
+    const header = ctx.header('authorization')
+    let token: string | undefined
+
+    if (header !== undefined) {
+      token = BEARER.exec(header)?.[1]
+
+      if (token === undefined) {
+        throw unauthorized('Authorization is not a bearer token', 'Bearer error="invalid_request"')
+      }
+    } else if (this.#cookie !== undefined) {
+      token = ctx.cookie(this.#cookie)
+    }
+
+    if (token === undefined) {
+      throw unauthorized('Missing token', 'Bearer')
+    }
+
+    try {
+      ctx.set(JWT_PAYLOAD, await this.#jwt.verify(token))
+    } catch (error) {
+      if (error instanceof JwtError) {
+        throw unauthorized(error.message, 'Bearer error="invalid_token"', error)
+      }
+
+      throw error
+    }
+
+    return true
+  }
+}

package/src/jwt/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @module
+ * JSON Web Tokens: `JwtService` to sign and verify them, `JwtModule` to
+ * configure it, `JwtGuard` to protect routes with them.
+ */
+
+export type { JwtAlgorithm, JwtKey } from './algorithms.ts'
+export { JwtError } from './errors.ts'
+export type { JwtErrorCode } from './errors.ts'
+export { JWT_PAYLOAD, JwtGuard } from './guard.ts'
+export { JWT_OPTIONS, JwtModule } from './module.ts'
+export type { JwtModuleAsyncOptions, JwtModuleOptions } from './module.ts'
+export { JwtService } from './service.ts'
+export type { JwtOptions, JwtPayload, JwtSignOptions } from './service.ts'

package/src/jwt/module.ts

@@ -0,0 +1,58 @@
+/**
+ * @module
+ * `JwtModule`: provides a configured `JwtService`, like `@nestjs/jwt`.
+ */
+
+import { InjectionToken, Module, provide } from '../di/index.ts'
+import type { Dependency, DependencyValues, DynamicModule, ModuleImport } from '../di/index.ts'
+import { JwtService } from './service.ts'
+import type { JwtOptions } from './service.ts'
+
+export interface JwtModuleOptions extends JwtOptions {
+  /** Cookie `JwtGuard` reads the token from when the request has no `Authorization` header. */
+  readonly cookie?: string
+}
+
+export interface JwtModuleAsyncOptions<D extends readonly Dependency[]> {
+  /** Modules providing what `inject` names. */
+  readonly imports?: readonly ModuleImport[]
+  readonly inject?: D
+  readonly useFactory: (...args: DependencyValues<D>) => JwtModuleOptions | Promise<JwtModuleOptions>
+  /** Makes `JwtService` visible in every module. */
+  readonly global?: boolean
+}
+
+/** Options the module was registered with. */
+export const JWT_OPTIONS = new InjectionToken<JwtModuleOptions>('JWT_OPTIONS')
+
+const service = () => provide(JwtService, { inject: [JWT_OPTIONS], useFactory: (options) => new JwtService(options) })
+
+/**
+ * ```ts
+ * @Module({ imports: [JwtModule.register({ secret: process.env.JWT_SECRET!, expiresIn: 900, global: true })] })
+ * class AppModule {}
+ *
+ * JwtModule.registerAsync({ inject: [ConfigService], useFactory: (config) => ({ secret: config.get('JWT_SECRET') }) })
+ * ```
+ */
+@Module({})
+export class JwtModule {
+  static register(options: JwtModuleOptions & { readonly global?: boolean }): DynamicModule {
+    return {
+      module: JwtModule,
+      global: options.global ?? false,
+      providers: [provide(JWT_OPTIONS, { useValue: options }), service()],
+      exports: [JwtService, JWT_OPTIONS],
+    }
+  }
+
+  static registerAsync<const D extends readonly Dependency[] = []>(options: JwtModuleAsyncOptions<D>): DynamicModule {
+    return {
+      module: JwtModule,
+      global: options.global ?? false,
+      imports: options.imports ?? [],
+      providers: [provide<JwtModuleOptions, D>(JWT_OPTIONS, { inject: options.inject, useFactory: options.useFactory }), service()],
+      exports: [JwtService, JWT_OPTIONS],
+    }
+  }
+}