@getsoda/core 0.1.1 → 0.2.0

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],
+    }
+  }
+}

package/src/jwt/service.ts

@@ -0,0 +1,216 @@
+/**
+ * @module
+ * Signing and verifying JSON Web Tokens (RFC 7519) with WebCrypto.
+ */
+
+import { parseJson } from '../http/body.ts'
+import { importKey, isHmac, isJwtAlgorithm, signBytes, verifyBytes } from './algorithms.ts'
+import type { JwtAlgorithm, JwtKey } from './algorithms.ts'
+import { JwtError } from './errors.ts'
+
+/** Claims of a token: the registered ones (RFC 7519, section 4.1) and any other. */
+export interface JwtPayload {
+  readonly iss?: string
+  readonly sub?: string
+  readonly aud?: string | readonly string[]
+  /** Expiration time, in seconds since the epoch. */
+  readonly exp?: number
+  /** Not before, in seconds since the epoch. */
+  readonly nbf?: number
+  /** Issued at, in seconds since the epoch. */
+  readonly iat?: number
+  readonly jti?: string
+  readonly [claim: string]: unknown
+}
+
+export interface JwtOptions {
+  /** Defaults to `HS256`. The only algorithm accepted when verifying. */
+  readonly algorithm?: JwtAlgorithm
+  /** Secret of an `HS*` algorithm. Random and at least as long as the hash: `openssl rand -base64 32`. */
+  readonly secret?: string
+  /** Key signing with an asymmetric algorithm. */
+  readonly privateKey?: JwtKey
+  /** Key verifying with an asymmetric algorithm. */
+  readonly publicKey?: JwtKey
+  /** Lifetime of signed tokens, in seconds: sets `exp`. */
+  readonly expiresIn?: number
+  /** Sets `iss` when signing; required when verifying. */
+  readonly issuer?: string
+  /** Sets `aud` when signing; when verifying, `aud` must hold one of these. */
+  readonly audience?: string | readonly string[]
+  /** Seconds of clock difference allowed when checking `exp` and `nbf`. Defaults to 0. */
+  readonly clockTolerance?: number
+}
+
+export interface JwtSignOptions {
+  /** Lifetime of this token, in seconds, instead of the configured one. */
+  readonly expiresIn?: number
+}
+
+const BASE64URL = /^[\w-]+$/
+const TIME_CLAIMS = ['exp', 'nbf', 'iat'] as const
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8', { fatal: true })
+
+const encodePart = (bytes: Uint8Array): string => bytes.toBase64({ alphabet: 'base64url', omitPadding: true })
+
+const decodeBytes = (part: string): Uint8Array<ArrayBuffer> => Uint8Array.fromBase64(part, { alphabet: 'base64url' })
+
+/** The JSON object in a part of a token. */
+const decodeObject = (part: string, name: string): Record<string, unknown> => {
+  let value: unknown
+
+  try {
+    value = parseJson(decoder.decode(decodeBytes(part)))
+  } catch {
+    value = undefined
+  }
+
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new JwtError('malformed', `Token ${name} is not a JSON object`)
+  }
+
+  return value as Record<string, unknown>
+}
+
+const seconds = (): number => Math.floor(Date.now() / 1000)
+
+/**
+ * Signs and verifies tokens with one algorithm and its keys, imported once.
+ *
+ * ```ts
+ * const jwt = new JwtService({ secret: process.env.JWT_SECRET!, expiresIn: 15 * 60 })
+ * const token = await jwt.sign({ sub: user.id })
+ * const payload = await jwt.verify(token) // throws JwtError
+ * ```
+ *
+ * The algorithm comes from the options, never from the token: a token signed
+ * otherwise, or not signed (`alg: none`), is refused. The signature is
+ * checked before any claim is trusted.
+ */
+export class JwtService {
+  readonly #options: JwtOptions
+  readonly #algorithm: JwtAlgorithm
+  #signingKey: Promise<CryptoKey> | undefined
+  #verifyingKey: Promise<CryptoKey> | undefined
+
+  constructor(options: JwtOptions) {
+    const algorithm = options.algorithm ?? 'HS256'
+
+    if (!isJwtAlgorithm(algorithm)) {
+      throw new TypeError(`Unsupported JWT algorithm: ${String(algorithm)}`)
+    }
+
+    const hasKeys = options.privateKey !== undefined || options.publicKey !== undefined
+
+    if (isHmac(algorithm) && (options.secret === undefined || options.secret === '' || hasKeys)) {
+      throw new TypeError(`${algorithm} takes a non-empty secret, not keys`)
+    }
+
+    if (!isHmac(algorithm) && (options.secret !== undefined || !hasKeys)) {
+      throw new TypeError(`${algorithm} takes privateKey to sign and publicKey to verify, not a secret`)
+    }
+
+    this.#options = options
+    this.#algorithm = algorithm
+  }
+
+  /**
+   * Signs `payload`, adding `iat`, and `exp`, `iss`, `aud` from the options.
+   * Claims in `payload` win over the added ones.
+   */
+  async sign(payload: JwtPayload, options?: JwtSignOptions): Promise<string> {
+    const now = seconds()
+    const expiresIn = options?.expiresIn ?? this.#options.expiresIn
+    const { issuer, audience } = this.#options
+    const claims = {
+      iat: now,
+      ...(expiresIn === undefined ? {} : { exp: now + expiresIn }),
+      ...(issuer === undefined ? {} : { iss: issuer }),
+      ...(audience === undefined ? {} : { aud: audience }),
+      ...payload,
+    }
+    const input = `${encodePart(encoder.encode(JSON.stringify({ alg: this.#algorithm, typ: 'JWT' })))}.${encodePart(encoder.encode(JSON.stringify(claims)))}`
+
+    this.#signingKey ??= importKey(this.#key('privateKey'), this.#algorithm, 'sign')
+
+    return `${input}.${encodePart(await signBytes(this.#algorithm, await this.#signingKey, encoder.encode(input)))}`
+  }
+
+  /** The payload of a valid token; throws a {@link JwtError} otherwise. */
+  async verify<T extends JwtPayload = JwtPayload>(token: string): Promise<T> {
+    const parts = token.split('.')
+
+    if (parts.length !== 3 || !parts.every((part) => BASE64URL.test(part))) {
+      throw new JwtError('malformed', 'Token is not three base64url parts')
+    }
+
+    const [header, body, signature] = parts as [string, string, string]
+    const { alg, crit } = decodeObject(header, 'header')
+
+    if (alg !== this.#algorithm) {
+      throw new JwtError('algorithm', `Token is signed with ${String(alg)}, ${this.#algorithm} is expected`)
+    }
+
+    if (crit !== undefined) {
+      throw new JwtError('algorithm', 'Token has critical header extensions, which are not supported')
+    }
+
+    this.#verifyingKey ??= importKey(this.#key('publicKey'), this.#algorithm, 'verify')
+
+    const valid = await verifyBytes(this.#algorithm, await this.#verifyingKey, decodeBytes(signature), encoder.encode(`${header}.${body}`))
+
+    if (!valid) {
+      throw new JwtError('signature', 'Token signature does not match')
+    }
+
+    const payload = decodeObject(body, 'payload')
+
+    this.#checkClaims(payload)
+
+    return payload as T
+  }
+
+  #key(kind: 'privateKey' | 'publicKey'): JwtKey {
+    const key = isHmac(this.#algorithm) ? this.#options.secret : this.#options[kind]
+
+    if (key === undefined) {
+      throw new TypeError(`${this.#algorithm} needs ${kind} to ${kind === 'privateKey' ? 'sign' : 'verify'}`)
+    }
+
+    return key
+  }
+
+  #checkClaims(payload: Record<string, unknown>): void {
+    for (const claim of TIME_CLAIMS) {
+      if (payload[claim] !== undefined && !Number.isFinite(payload[claim])) {
+        throw new JwtError('claims', `Token claim "${claim}" is not a number`)
+      }
+    }
+
+    const { exp, nbf, iss, aud } = payload as JwtPayload
+    const { issuer, audience, clockTolerance = 0 } = this.#options
+    const now = seconds()
+
+    if (exp !== undefined && now >= exp + clockTolerance) {
+      throw new JwtError('expired', 'Token expired')
+    }
+
+    if (nbf !== undefined && now + clockTolerance < nbf) {
+      throw new JwtError('not-active', 'Token is not active yet')
+    }
+
+    if (issuer !== undefined && iss !== issuer) {
+      throw new JwtError('claims', `Token issuer is not "${issuer}"`)
+    }
+
+    if (audience !== undefined) {
+      const expected: readonly string[] = typeof audience === 'string' ? [audience] : audience
+      const actual: readonly unknown[] = typeof aud === 'string' ? [aud] : Array.isArray(aud) ? aud : []
+
+      if (!actual.some((value) => expected.includes(value as string))) {
+        throw new JwtError('claims', `Token audience is not ${expected.map((value) => `"${value}"`).join(' or ')}`)
+      }
+    }
+  }
+}

package/src/logger/console-logger.ts

@@ -0,0 +1,119 @@
+/**
+ * @module
+ * Logger writing to stdout and stderr, readable for people or as JSON lines.
+ *
+ * ```
+ * 2026-11-13T17:20:03.120Z  LOG   [UsersService] User created {"id":7}
+ * {"time":"2026-11-13T17:20:03.120Z","level":"log","context":"UsersService","message":"User created","id":7}
+ * ```
+ *
+ * Like Nest's `ConsoleLogger`: a minimum level, a JSON mode for log
+ * collectors; `error` and `fatal` go to stderr, the rest to stdout.
+ */
+
+import { Logger } from './logger.ts'
+import type { LogEntry, LogLevel } from './logger.ts'
+
+export interface ConsoleLoggerOptions {
+  /** Least severe level written. Defaults to `log`. */
+  readonly level?: LogLevel
+  /** One JSON object per line, for log collectors. Defaults to `false`. */
+  readonly json?: boolean
+  /** Where lines go. Defaults to stderr for `error` and `fatal`, stdout otherwise. */
+  readonly output?: (line: string, level: LogLevel) => void
+}
+
+const SEVERITY: Readonly<Record<LogLevel, number>> = { verbose: 0, debug: 1, log: 2, warn: 3, error: 4, fatal: 5 }
+
+const writeToConsole = (line: string, level: LogLevel): void => {
+  const stream = level === 'error' || level === 'fatal' ? process.stderr : process.stdout
+
+  stream.write(`${line}\n`)
+}
+
+const serializeError = (error: Error): Record<string, unknown> => {
+  const serialized: Record<string, unknown> = { name: error.name, message: error.message, stack: error.stack }
+
+  if (error.cause !== undefined) {
+    serialized.cause = error.cause instanceof Error ? serializeError(error.cause) : error.cause
+  }
+
+  return serialized
+}
+
+/**
+ * `JSON.stringify` that never throws: bigints become strings, an object met a
+ * second time (a cycle) becomes `"[Circular]"`. Errors are serialized in full
+ * (stack and cause) for JSON lines, or as `Name: message` when their stack is
+ * printed on its own lines.
+ */
+const stringify = (value: unknown, errors: 'full' | 'brief'): string => {
+  const seen = new WeakSet<object>()
+
+  return JSON.stringify(value, (_key, current: unknown) => {
+    if (typeof current === 'bigint') {
+      return current.toString()
+    }
+
+    if (current instanceof Error) {
+      return errors === 'full' ? serializeError(current) : `${current.name}: ${current.message}`
+    }
+
+    if (typeof current === 'object' && current !== null) {
+      if (seen.has(current)) {
+        return '[Circular]'
+      }
+
+      seen.add(current)
+    }
+
+    return current
+  })
+}
+
+export class ConsoleLogger extends Logger {
+  readonly #minimum: number
+  readonly #json: boolean
+  readonly #output: (line: string, level: LogLevel) => void
+
+  constructor(options: ConsoleLoggerOptions = {}) {
+    super()
+    this.#minimum = SEVERITY[options.level ?? 'log']
+    this.#json = options.json === true
+    this.#output = options.output ?? writeToConsole
+  }
+
+  write(entry: LogEntry): void {
+    if (SEVERITY[entry.level] < this.#minimum) {
+      return
+    }
+
+    const time = new Date().toISOString()
+
+    this.#output(this.#json ? this.#formatJson(entry, time) : this.#formatText(entry, time), entry.level)
+  }
+
+  #formatJson(entry: LogEntry, time: string): string {
+    // Fixed fields last: data cannot overwrite them.
+    return stringify({ ...entry.data, time, level: entry.level, context: entry.context, message: entry.message }, 'full')
+  }
+
+  #formatText(entry: LogEntry, time: string): string {
+    const context = entry.context === undefined ? '' : `[${entry.context}] `
+    let line = `${time}  ${entry.level.toUpperCase().padEnd(7)} ${context}${entry.message}`
+    let stacks = ''
+
+    if (entry.data !== undefined) {
+      line += ` ${stringify(entry.data, 'brief')}`
+
+      // Stacks are read better on their own lines than inside the JSON.
+      for (const value of Object.values(entry.data)) {
+        if (value instanceof Error && value.stack !== undefined) {
+          stacks += `\n${value.stack}`
+        }
+      }
+    }
+
+    return line + stacks
+  }
+}

package/src/logger/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module
+ * Logging: the `Logger` contract and token, and the console implementation.
+ */
+
+export { ConsoleLogger } from './console-logger.ts'
+export type { ConsoleLoggerOptions } from './console-logger.ts'
+export { LOG_LEVELS, Logger, SilentLogger } from './logger.ts'
+export type { LogData, LogEntry, LogLevel } from './logger.ts'

package/src/logger/logger.ts

@@ -0,0 +1,96 @@
+/**
+ * @module
+ * The logger contract.
+ *
+ * `Logger` is both the type and the DI token: the application provides one
+ * (a `ConsoleLogger` unless told otherwise) and any class injects it.
+ *
+ * ```ts
+ * class UsersService {
+ *   readonly #logger = inject(Logger).child('UsersService')
+ *
+ *   create(user: User) {
+ *     this.#logger.log('User created', { id: user.id })
+ *   }
+ * }
+ * ```
+ *
+ * Levels are Nest's. Unlike Nest's `Logger`, it is not a static global: each
+ * application has its own, and tests replace it with `overrides`.
+ */
+
+/** Levels, from the most to the least verbose. */
+export const LOG_LEVELS = ['verbose', 'debug', 'log', 'warn', 'error', 'fatal'] as const
+
+export type LogLevel = (typeof LOG_LEVELS)[number]
+
+/** Structured data of an entry; `Error` values are serialized with their stack and cause. */
+export type LogData = Readonly<Record<string, unknown>>
+
+/**
+ * One log entry, as a `Logger` implementation receives it.
+ */
+export interface LogEntry {
+  readonly level: LogLevel
+  readonly message: string
+  readonly data: LogData | undefined
+  /** Where it comes from, as given to `child()`. */
+  readonly context: string | undefined
+}
+
+/**
+ * A logger. Implementations only write entries; levels and contexts are handled here.
+ */
+export abstract class Logger {
+  /** Writes one entry. Called for every level: filtering is up to the implementation. */
+  abstract write(entry: LogEntry): void
+
+  verbose(message: string, data?: LogData): void {
+    this.write({ level: 'verbose', message, data, context: undefined })
+  }
+
+  debug(message: string, data?: LogData): void {
+    this.write({ level: 'debug', message, data, context: undefined })
+  }
+
+  log(message: string, data?: LogData): void {
+    this.write({ level: 'log', message, data, context: undefined })
+  }
+
+  warn(message: string, data?: LogData): void {
+    this.write({ level: 'warn', message, data, context: undefined })
+  }
+
+  error(message: string, data?: LogData): void {
+    this.write({ level: 'error', message, data, context: undefined })
+  }
+
+  fatal(message: string, data?: LogData): void {
+    this.write({ level: 'fatal', message, data, context: undefined })
+  }
+
+  /** A logger writing through this one, with `context` on every entry. */
+  child(context: string): Logger {
+    return new ContextLogger(this, context)
+  }
+}
+
+class ContextLogger extends Logger {
+  readonly #parent: Logger
+  readonly #context: string
+
+  constructor(parent: Logger, context: string) {
+    super()
+    this.#parent = parent
+    this.#context = context
+  }
+
+  write(entry: LogEntry): void {
+    this.#parent.write({ ...entry, context: this.#context })
+  }
+}
+
+/** A logger that writes nothing: `createApp(AppModule, { logger: false })`. */
+export class SilentLogger extends Logger {
+  write(): void {}
+}

package/src/routing/types.ts

@@ -34,7 +34,7 @@ export type Params = Record<string, string>
  *
  * `params` may be the very object Bun put on `req.params`: treat it as read-only.
  */
-export type Handler = (req: Request, params: Params) => Response | Promise<Response>
+export type Handler = (req: Bun.BunRequest, params: Params) => Response | Promise<Response>
 
 /**
  * Route definition.