@getsoda/core 0.1.1 → 0.2.1

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,163 @@
+/**
+ * @module
+ * Logger writing to stdout and stderr, readable for people or as JSON lines.
+ *
+ * ```
+ * [Soda] 41250  - 11/14/2026, 12:22:09 AM     LOG [UsersService] User created {"id":7} +3ms
+ * {"time":"2026-11-13T21:22:09.120Z","level":"log","context":"UsersService","message":"User created","id":7}
+ * ```
+ *
+ * Like Nest's `ConsoleLogger`: the same line layout, colored by level in a
+ * terminal, with the time since the previous line; 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
+  /**
+   * Colors by level. Defaults to on when writing to a terminal without
+   * `NO_COLOR`, off with a custom `output`.
+   */
+  readonly colors?: boolean
+  /** Name starting each readable line. Defaults to `Soda`. */
+  readonly prefix?: string
+}
+
+const SEVERITY: Readonly<Record<LogLevel, number>> = { verbose: 0, debug: 1, log: 2, warn: 3, error: 4, fatal: 5 }
+
+const color =
+  (code: string) =>
+  (text: string): string =>
+    `\u001B[${code}m${text}\u001B[0m`
+
+const LEVEL_COLORS: Readonly<Record<LogLevel, (text: string) => string>> = {
+  verbose: color('96'),
+  debug: color('95'),
+  log: color('32'),
+  warn: color('33'),
+  error: color('31'),
+  fatal: color('1;31'),
+}
+const yellow = color('38;5;3')
+const plain = (text: string): string => text
+
+const dateTime = new Intl.DateTimeFormat(undefined, {
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: 'numeric',
+  minute: '2-digit',
+  second: '2-digit',
+})
+
+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
+  readonly #colors: boolean
+  readonly #prefix: string
+  /** When the previous line was written, for the `+3ms` at the end of the next. */
+  #last: number | undefined
+
+  constructor(options: ConsoleLoggerOptions = {}) {
+    super()
+    this.#minimum = SEVERITY[options.level ?? 'log']
+    this.#json = options.json === true
+    this.#output = options.output ?? writeToConsole
+    this.#colors = options.colors ?? (options.output === undefined && process.stdout.isTTY === true && process.env.NO_COLOR === undefined)
+    this.#prefix = options.prefix ?? 'Soda'
+  }
+
+  write(entry: LogEntry): void {
+    if (SEVERITY[entry.level] < this.#minimum) {
+      return
+    }
+
+    const now = Date.now()
+
+    this.#output(this.#json ? this.#formatJson(entry, now) : this.#formatText(entry, now), entry.level)
+    this.#last = now
+  }
+
+  #formatJson(entry: LogEntry, now: number): string {
+    const time = new Date(now).toISOString()
+
+    // 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, now: number): string {
+    const level = this.#colors ? LEVEL_COLORS[entry.level] : plain
+    const accent = this.#colors ? yellow : plain
+    const context = entry.context === undefined ? '' : accent(`[${entry.context}] `)
+    const since = this.#last === undefined ? '' : accent(` +${now - this.#last}ms`)
+    const data = entry.data === undefined ? '' : ` ${stringify(entry.data, 'brief')}`
+    const line =
+      `${level(`[${this.#prefix}] ${process.pid}  - `)}${dateTime.format(now)} ${level(entry.level.toUpperCase().padStart(7))} ` +
+      `${context}${level(entry.message)}${data}${since}`
+    let stacks = ''
+
+    // 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.