@getsoda/core 0.1.0 → 0.2.0

package/src/http/context.ts

@@ -4,11 +4,13 @@
  */
 
 import type { Constructor } from '../di/index.ts'
-import { readJsonBody } from './body.ts'
+import { readFormBody, readJsonBody } from './body.ts'
+import type { FormFields, FormLimits } from './body.ts'
+import type { ContextKey } from './context-key.ts'
 import type { MetadataDecorator } from './enhancers.ts'
 import { applyParser } from './parsers.ts'
 import type { Parsed, ValueParser } from './parsers.ts'
-import { validate } from './schema.ts'
+import { isStandardSchema, validate } from './schema.ts'
 import type { InferOutput, StandardSchemaV1 } from './schema.ts'
 import type { AnyParams, PathParams } from './types.ts'
 
@@ -49,18 +51,54 @@ export interface RouteInfo {
  * }
  * ```
  *
- * The URL is parsed only when `url` or `query()` is used; the body is read at most once.
+ * The URL is parsed only when `url` or `query()` is used; the body is read at
+ * most once; the storage of `set()` is created on the first `set()`.
  */
 export class Context<P extends string = string> {
   #url: URL | undefined
-  #body: Promise<unknown> | undefined
+  #body: { readonly kind: 'JSON' | 'form'; readonly value: Promise<unknown> } | undefined
+  #values: Map<ContextKey<unknown>, unknown> | undefined
 
   constructor(
-    readonly req: Request,
+    readonly req: Bun.BunRequest,
     readonly params: ContextParams<P>,
     readonly route: RouteInfo
   ) {}
 
+  /** Attaches a value to this request, for the guards, interceptors and handler that follow. */
+  set<T>(key: ContextKey<T>, value: T): void {
+    this.#values ??= new Map()
+    this.#values.set(key, value)
+  }
+
+  /**
+   * Value attached to this request under `key`, or its default. Throws if
+   * nothing was set and the key has no default: a guard is missing on the route.
+   */
+  get<T>(key: ContextKey<T>): T {
+    if (this.#values?.has(key) === true) {
+      return this.#values.get(key) as T
+    }
+
+    if (key.defaultValue === undefined) {
+      throw new Error(
+        `${key.toString()} is not set for ${this.route.controller.name}.${this.route.handler}: ` +
+          'is the guard or interceptor that sets it applied to this route?'
+      )
+    }
+
+    const value = key.defaultValue()
+
+    this.set(key, value)
+
+    return value
+  }
+
+  /** `true` if a value was set under `key` for this request. */
+  has(key: ContextKey<unknown>): boolean {
+    return this.#values?.has(key) === true
+  }
+
   /**
    * Custom metadata of the route, the method's value over the class's.
    * Like Nest's `reflector.getAllAndOverride(Roles, [handler, class])`.
@@ -102,6 +140,28 @@ export class Context<P extends string = string> {
     return parser === undefined ? value : applyParser(parser, value, name)
   }
 
+  /**
+   * Cookies of the request: Bun's `CookieMap`. What `set()` and `delete()`
+   * change is sent with the response as `Set-Cookie`, whatever the response is.
+   *
+   * ```ts
+   * ctx.cookies.set('theme', 'dark', { maxAge: 60 * 60 * 24 * 365 })
+   * ctx.cookies.delete('session')
+   * ```
+   */
+  get cookies(): Bun.CookieMap {
+    return this.req.cookies
+  }
+
+  /** Cookie, decoded; converted and checked when a parser is given, such as `signed()`. */
+  cookie(name: string): string | undefined
+  cookie<V extends ValueParser<unknown>>(name: string, parser: V): Parsed<V>
+  cookie(name: string, parser?: ValueParser<unknown>): unknown {
+    const value = this.req.cookies.get(name) ?? undefined
+
+    return parser === undefined ? value : applyParser(parser, value, name)
+  }
+
   /**
    * JSON body, validated by `schema` when given. `415` for a non-JSON body,
    * `400` for invalid JSON or a failed validation.
@@ -109,10 +169,36 @@ export class Context<P extends string = string> {
   body(): Promise<unknown>
   body<S extends StandardSchemaV1>(schema: S): Promise<InferOutput<S>>
   async body(schema?: StandardSchemaV1): Promise<unknown> {
-    this.#body ??= readJsonBody(this.req)
-
-    const value = await this.#body
+    const value = await this.#read('JSON', readJsonBody)
 
     return schema === undefined ? value : validate(schema, value, '')
   }
+
+  /**
+   * Form body (`multipart/form-data` or `application/x-www-form-urlencoded`),
+   * validated by `schema` when given. `415` for another content type.
+   * Repeated fields and fields named `name[]` are arrays; files are `File`s
+   * whose `type` is what the client declared, not checked against the content.
+   * `limits` bound the body, the files and the fields: `413` past them.
+   */
+  form(limits?: FormLimits): Promise<FormFields>
+  form<S extends StandardSchemaV1>(schema: S, limits?: FormLimits): Promise<InferOutput<S>>
+  async form(schemaOrLimits?: StandardSchemaV1 | FormLimits, limits?: FormLimits): Promise<unknown> {
+    if (isStandardSchema(schemaOrLimits)) {
+      return validate(schemaOrLimits, await this.#read('form', (req) => readFormBody(req, limits)), '')
+    }
+
+    return this.#read('form', (req) => readFormBody(req, schemaOrLimits))
+  }
+
+  /** Reads the body once; reading it again in another format is a programming error. */
+  #read(kind: 'JSON' | 'form', read: (req: Request) => Promise<unknown>): Promise<unknown> {
+    if (this.#body === undefined) {
+      this.#body = { kind, value: read(this.req) }
+    } else if (this.#body.kind !== kind) {
+      throw new TypeError(`The body of this request was already read as ${this.#body.kind}, it cannot be read as ${kind}`)
+    }
+
+    return this.#body.value
+  }
 }

package/src/http/cookies.ts

@@ -0,0 +1,96 @@
+/**
+ * @module
+ * Signed cookies. Reading and writing cookies is Bun's: `ctx.cookies` is the
+ * request's `CookieMap`, whose changes Bun sends with the response as
+ * `Set-Cookie`. This module adds what `@fastify/cookie` and `cookie-signature`
+ * add on top: values signed with HMAC-SHA256, so the client can read them but
+ * not forge them.
+ *
+ * ```ts
+ * const signer = new CookieSigner(process.env.COOKIE_SECRET!)
+ *
+ * ctx.cookies.set('session', signer.sign(id), { httpOnly: true, secure: true })
+ *
+ * @Get('me', [cookie('session', signed(signer))])
+ * me(id: string) {}
+ * ```
+ *
+ * A signature proves the value was set by the server, not that it is secret
+ * or recent: store secrets server-side, and limit the lifetime with `maxAge`.
+ */
+
+import { timingSafeEqual } from 'node:crypto'
+import { failure } from './parsers.ts'
+import type { Parser, ParserOptions } from './parsers.ts'
+
+const hmac = (secret: string, value: string): string =>
+  new Bun.CryptoHasher('sha256', secret).update(value).digest('base64url')
+
+/**
+ * Signs cookie values as `value.signature` and checks them. Several secrets
+ * allow rotation: the first signs, every one verifies.
+ *
+ * ```ts
+ * new CookieSigner([process.env.COOKIE_SECRET!, process.env.OLD_COOKIE_SECRET!])
+ * ```
+ */
+export class CookieSigner {
+  readonly #secrets: readonly string[]
+
+  /** Secrets should be random and long: `openssl rand -base64 32`. */
+  constructor(secrets: string | readonly string[]) {
+    const list = typeof secrets === 'string' ? [secrets] : [...secrets]
+
+    if (list.length === 0 || list.includes('')) {
+      throw new TypeError('CookieSigner needs at least one secret, and no empty ones')
+    }
+
+    this.#secrets = list
+  }
+
+  /** `value` followed by `.` and its signature, in base64url. */
+  sign(value: string): string {
+    return `${value}.${hmac(this.#secrets[0]!, value)}`
+  }
+
+  /** The value of a signed string, or `undefined` if it is not signed by one of the secrets. */
+  unsign(signed: string): string | undefined {
+    const dot = signed.lastIndexOf('.')
+
+    if (dot === -1) {
+      return undefined
+    }
+
+    const value = signed.slice(0, dot)
+    const signature = Buffer.from(signed.slice(dot + 1))
+
+    for (const secret of this.#secrets) {
+      const expected = Buffer.from(hmac(secret, value))
+
+      if (expected.length === signature.length && timingSafeEqual(expected, signature)) {
+        return value
+      }
+    }
+
+    return undefined
+  }
+}
+
+type Result<O extends ParserOptions> = O extends { readonly optional: true } ? string | undefined : string
+
+/**
+ * Parser of a signed cookie: its value, `400` when it is missing or its
+ * signature is wrong. With `{ optional: true }`, both give `undefined`, as a
+ * forged cookie is no better than none.
+ */
+export const signed = <const O extends ParserOptions = {}>(signer: CookieSigner, options?: O): Parser<Result<O>> => ({
+  parse: (value, name) => {
+    const unsigned = value === undefined ? undefined : signer.unsign(value)
+
+    if (unsigned === undefined && options?.optional !== true) {
+      throw failure(name, 'signed cookie')
+    }
+
+    return unsigned as Result<O>
+  },
+})

package/src/http/cors.ts

@@ -0,0 +1,143 @@
+/**
+ * @module
+ * CORS middleware.
+ *
+ * Follows Hono's `cors()` and the `cors` package Nest uses, with two differences:
+ *
+ * - only a real preflight (`OPTIONS` with `Access-Control-Request-Method`, as
+ *   the Fetch spec defines it) is answered here; other `OPTIONS` requests reach
+ *   the application and its own `OPTIONS` routes;
+ * - `credentials: true` with `origin: '*'` is rejected when the middleware is
+ *   created: browsers refuse that pair, so it could never work.
+ *
+ * Response headers are set in place: Bun's responses always have mutable headers.
+ *
+ * ```ts
+ * cors({ origin: ['https://app.example.com'], credentials: true, maxAge: 600 })
+ * ```
+ */
+
+import type { MiddlewareFunction } from './middleware.ts'
+
+export interface CorsOptions {
+  /**
+   * Allowed origins: `'*'` (default), one origin, a list, or a predicate.
+   * An allowed origin is echoed back; a refused one gets no CORS headers, so the browser blocks the response.
+   */
+  readonly origin?: '*' | string | readonly string[] | ((origin: string, req: Request) => boolean)
+  /** Methods announced to preflights. */
+  readonly methods?: readonly string[]
+  /** Headers announced to preflights. Defaults to the ones the preflight asks for. */
+  readonly allowedHeaders?: readonly string[]
+  /** Response headers the browser exposes to scripts. */
+  readonly exposedHeaders?: readonly string[]
+  /** Allows cookies and `Authorization`; needs explicit origins. */
+  readonly credentials?: boolean
+  /** Seconds a browser may cache a preflight. */
+  readonly maxAge?: number
+}
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+
+const createOriginCheck = (origin: NonNullable<CorsOptions['origin']>): ((origin: string, req: Request) => boolean) => {
+  if (typeof origin === 'function') {
+    return origin
+  }
+
+  if (typeof origin === 'string') {
+    return (requested) => requested === origin
+  }
+
+  const allowed = new Set(origin)
+
+  return (requested) => allowed.has(requested)
+}
+
+const appendVary = (headers: Headers, value: string): void => {
+  const current = headers.get('vary')
+
+  if (current === null) {
+    headers.set('vary', value)
+  } else if (current !== '*' && !current.toLowerCase().split(/\s*,\s*/).includes(value.toLowerCase())) {
+    headers.set('vary', `${current}, ${value}`)
+  }
+}
+
+/**
+ * Creates the CORS middleware. Throws a `TypeError` for options browsers would refuse.
+ */
+export const cors = (options: CorsOptions = {}): MiddlewareFunction => {
+  const origin = options.origin ?? '*'
+  const any = origin === '*'
+
+  if (any && options.credentials === true) {
+    throw new TypeError(
+      "cors(): credentials cannot be used with origin '*', browsers reject that combination; list the allowed origins instead"
+    )
+  }
+
+  const isAllowed = any ? () => true : createOriginCheck(origin)
+  const methods = (options.methods ?? DEFAULT_METHODS).join(', ')
+  const allowedHeaders = options.allowedHeaders?.join(', ')
+  const exposedHeaders = options.exposedHeaders?.join(', ')
+  const maxAge = options.maxAge === undefined ? undefined : String(options.maxAge)
+
+  /** Headers every CORS response of an allowed origin gets. */
+  const applyCommon = (headers: Headers, requested: string | null, req: Request): void => {
+    if (requested !== null && isAllowed(requested, req)) {
+      headers.set('access-control-allow-origin', any ? '*' : requested)
+
+      if (options.credentials === true) {
+        headers.set('access-control-allow-credentials', 'true')
+      }
+    }
+
+    // The response depends on Origin as soon as it is not the same for every origin.
+    if (!any) {
+      appendVary(headers, 'Origin')
+    }
+  }
+
+  return async (req, next) => {
+    const requested = req.headers.get('origin')
+    const preflight = req.method === 'OPTIONS' && requested !== null && req.headers.has('access-control-request-method')
+
+    if (preflight) {
+      const headers = new Headers()
+
+      applyCommon(headers, requested, req)
+
+      if (headers.has('access-control-allow-origin')) {
+        headers.set('access-control-allow-methods', methods)
+
+        const requestedHeaders = req.headers.get('access-control-request-headers')
+        const allowHeaders = allowedHeaders ?? requestedHeaders ?? ''
+
+        if (allowHeaders !== '') {
+          headers.set('access-control-allow-headers', allowHeaders)
+        }
+
+        if (allowedHeaders === undefined && requestedHeaders !== null) {
+          appendVary(headers, 'Access-Control-Request-Headers')
+        }
+
+        if (maxAge !== undefined) {
+          headers.set('access-control-max-age', maxAge)
+        }
+      }
+
+      return new Response(null, { status: 204, headers })
+    }
+
+    const response = await next()
+    const headers = response.headers
+
+    applyCommon(headers, requested, req)
+
+    if (exposedHeaders !== undefined && headers.has('access-control-allow-origin')) {
+      headers.set('access-control-expose-headers', exposedHeaders)
+    }
+
+    return response
+  }
+}

package/src/http/index.ts

@@ -3,9 +3,11 @@
  * HTTP layer for Soda: controllers, route decorators, request context, validation, exceptions.
  */
 
-export { body, context, header, param, query } from './arguments.ts'
+export { body, context, cookie, form, header, param, query, value } from './arguments.ts'
 export type { Argument, ArgumentFor, ArgumentKind, ArgumentValues } from './arguments.ts'
 export { Context } from './context.ts'
+export { CookieSigner, signed } from './cookies.ts'
+export { ContextKey } from './context-key.ts'
 export type { ContextParams, ParamNameOf } from './context.ts'
 export { All, Controller, Delete, Get, Head, Header, HttpCode, Options, Patch, Post, Put, Route } from './decorators.ts'
 export type {
@@ -56,3 +58,7 @@ export type {
   MetadataDecorator,
 } from './enhancers.ts'
 export type { RouteInfo } from './context.ts'
+export { cors } from './cors.ts'
+export type { CorsOptions } from './cors.ts'
+export type { Middleware, MiddlewareFunction, NestMiddleware, Next } from './middleware.ts'
+export type { FormFields, FormLimits, FormValue } from './body.ts'

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/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)
+  }
+}