@open-xchange/fastify-sdk 0.1.0

package/lib/config/read.js

@@ -0,0 +1,38 @@
+import { access, readFile } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import yaml from 'js-yaml'
+
+export function getConfigPath () {
+  return process.env.CONFIG_PATH || '/app/config'
+}
+
+export async function fileExists (filename = '') {
+  try {
+    await access(`${getConfigPath()}/${filename}`, constants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function readConfigurationFile (filename = '', schema = null, callback = () => {}, { logger } = {}) {
+  const content = await readFile(`${getConfigPath()}/${filename}`, 'utf8')
+  try {
+    const data = await validateAndUpdateConfiguration(content, schema)
+    if (logger) logger.info(`Config "${filename}" has been read/refreshed`)
+    try {
+      callback(data)
+    } catch (err) {
+      if (logger) logger.error({ err }, `Runtime error in callback for "${filename}": ${err.message}`)
+    }
+    return data
+  } catch (err) {
+    if (logger) logger.error({ err }, `Failed to parse/validate configuration from "${filename}": ${err.message}`)
+    throw err
+  }
+}
+
+export async function validateAndUpdateConfiguration (content = '', schema = null) {
+  const parsed = yaml.load(content)
+  return schema ? schema.validateAsync(parsed) : parsed
+}

package/lib/config/registry.js

@@ -0,0 +1,57 @@
+import chokidar from 'chokidar'
+import { readConfigurationFile, getConfigPath, fileExists } from './read.js'
+
+export function createConfigRegistry ({ logger, onShutdown } = {}) {
+  const configPath = getConfigPath()
+  const watcher = chokidar.watch(configPath, { persistent: true })
+  const current = {}
+
+  try {
+    watcher.on('ready', async () => {
+      const watchedPaths = await watcher.getWatched()
+      if (logger) logger.info({ watchedPaths }, 'Chokidar is watching these paths')
+    })
+    watcher.on('change', (changedPath) => {
+      if (logger) logger.info({ path: changedPath }, `Configuration file at ${changedPath} changed`)
+    })
+    if (onShutdown) {
+      onShutdown(async () => {
+        if (watcher) await watcher.close()
+      })
+    }
+  } catch (err) {
+    if (logger) logger.error({ err }, `Failed to initialize watcher for configuration (${configPath}/**): ${err.message}`)
+  }
+
+  async function registerConfigurationFile (filename = '', { optional = false, watch = true, schema = null } = {}, callback = () => {}) {
+    if (optional && !(await fileExists(filename))) return {}
+    return readConfigurationFile(filename, schema, callback, { logger })
+      .catch(err => {
+        if (logger) logger.fatal({ err }, `Failed to read configuration file "${filename}"`)
+        throw err
+      })
+      .then(data => {
+        current[filename] = data
+        if (watch) {
+          watcher.on('change', async (changedPath) => {
+            try {
+              if (changedPath.endsWith(filename)) await readConfigurationFile(filename, schema, callback, { logger })
+            } catch {
+              // readConfigurationFile() already logged an error
+            }
+          })
+        }
+        return data
+      })
+  }
+
+  function getCurrent (filename = 'config') {
+    return current[filename] ?? {}
+  }
+
+  async function close () {
+    if (watcher) await watcher.close()
+  }
+
+  return { registerConfigurationFile, getCurrent, close }
+}

package/lib/config/util.js

@@ -0,0 +1,28 @@
+import Joi from 'joi'
+
+export const defaultTrue = Joi.boolean().default(true)
+export const defaultFalse = Joi.boolean().default(false)
+
+export const customString = Joi
+  .object({
+    en: Joi.string().allow('').required()
+  })
+  .unknown(true)
+  .required()
+
+export const optionalCustomString = Joi
+  .object({
+    en: Joi.string().allow('').required()
+  })
+  .unknown(true)
+  .optional()
+
+export const customURL = Joi.object()
+  .pattern(
+    Joi.string(),
+    Joi.string().allow('').uri()
+  )
+  .custom((value, helpers) => {
+    return 'en' in value ? value : helpers.error('any.custom', { message: '"en" is a required key' })
+  })
+  .required()

package/lib/database/migrations.js

@@ -0,0 +1,37 @@
+import { Umzug } from 'umzug'
+
+export function createMigrationRunner ({ pool, migrationsGlob, tableName = 'migrations', logger, context = {} }) {
+  return new Umzug({
+    migrations: {
+      glob: migrationsGlob,
+      resolve: ({ path, name, context }) => {
+        return {
+          name,
+          path,
+          up: async () => (await import(path)).up({ context }),
+          down: async () => (await import(path)).down({ context })
+        }
+      }
+    },
+    context: { pool, config: context },
+    storage: {
+      async executed ({ context: { pool } }) {
+        await pool.query(`CREATE TABLE IF NOT EXISTS \`${tableName}\` (name VARCHAR(255) NOT NULL, PRIMARY KEY (name))`)
+        const [results] = await pool.query(`SELECT name FROM \`${tableName}\``)
+        return [].concat(results).map(result => result.name)
+      },
+      async logMigration ({ name, context: { pool } }) {
+        await pool.query(`INSERT INTO \`${tableName}\` (name) VALUES (:name)`, { name })
+      },
+      async unlogMigration ({ name, context: { pool } }) {
+        await pool.query(`DELETE FROM \`${tableName}\` WHERE name = :name`, { name })
+      }
+    },
+    logger
+  })
+}
+
+export async function executeMigrations (runner, config = {}) {
+  const { pool } = runner.options.context
+  await runner.up({ pool, config })
+}

package/lib/database/mysql.js

@@ -0,0 +1,81 @@
+import mysql from 'mysql2/promise'
+
+const defaults = {
+  dateStrings: ['DATE', 'DATETIME'],
+  timezone: 'Z',
+  namedPlaceholders: true
+}
+
+export function createMySQLPool (options = {}) {
+  const pool = mysql.createPool({ ...defaults, ...options })
+  pool.on('connection', (connection) => {
+    connection.query('SET SESSION time_zone="+00:00"')
+  })
+  return pool
+}
+
+export function createMySQLPoolFromEnv ({ prefix = 'SQL', names } = {}) {
+  if (names) {
+    const dbNames = typeof names === 'string'
+      ? names.split(',').map(n => n.trim().toLowerCase()).filter(Boolean)
+      : names
+
+    const pools = {}
+    for (const name of dbNames) {
+      const envPrefix = `DB_${name.toUpperCase()}`
+      pools[name] = createMySQLPool({
+        host: process.env[`${envPrefix}_HOST`],
+        port: Number(process.env[`${envPrefix}_PORT`]) || 3306,
+        database: process.env[`${envPrefix}_NAME`],
+        user: process.env[`${envPrefix}_USER`],
+        password: process.env[`${envPrefix}_PASSWORD`],
+        connectionLimit: Number(process.env[`${envPrefix}_CONNECTIONS`] || 10),
+        multipleStatements: true
+      })
+    }
+    return pools
+  }
+
+  return createMySQLPool({
+    host: process.env[`${prefix}_HOST`],
+    port: Number(process.env[`${prefix}_PORT`]) || 3306,
+    database: process.env[`${prefix}_DB`],
+    user: process.env[`${prefix}_USER`],
+    password: process.env[`${prefix}_PASS`],
+    connectionLimit: Number(process.env[`${prefix}_CONNECTIONS`] || 10)
+  })
+}
+
+export async function mysqlReadyCheck (pool, { retries = 12, delay = 10_000, logger } = {}) {
+  for (let i = 1; i <= retries; i++) {
+    try {
+      await pool.query('SELECT 1')
+      if (logger) logger.info('Database is ready')
+      return
+    } catch (err) {
+      if (logger) logger.warn(`Database not ready (attempt ${i}/${retries}): ${err.code} ${err.message}`)
+      if (i === retries) throw err
+      await new Promise(resolve => setTimeout(resolve, delay))
+    }
+  }
+}
+
+let _pools
+
+/**
+ * Returns a singleton pool map created from the `DATABASES` env var.
+ * Calls `createMySQLPoolFromEnv({ names: process.env.DATABASES })` on first access.
+ * @returns {Record<string, import('mysql2/promise').Pool>}
+ */
+export function getMySQLPools () {
+  if (!_pools) {
+    const names = process.env.DATABASES
+    _pools = names ? createMySQLPoolFromEnv({ names }) : {}
+  }
+  return _pools
+}
+
+export async function createUUID (pool) {
+  const [[{ uuid }]] = await pool.query('SELECT uuid() as uuid')
+  return uuid
+}

package/lib/database/postgres.js

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs'
+import pg from 'pg'
+
+export function createPostgresPool (options = {}) {
+  return new pg.Pool(options)
+}
+
+export function createPostgresPoolFromEnv () {
+  let ca, cert, key
+
+  if (process.env.DATABASE_SSL !== 'false') {
+    try { ca = readFileSync(process.env.DATABASE_SSL_CA_PATH) } catch {}
+    try { cert = readFileSync(process.env.DATABASE_SSL_CERT_PATH) } catch {}
+    try { key = readFileSync(process.env.DATABASE_SSL_KEY_PATH) } catch {}
+  }
+
+  const options = {
+    host: process.env.DATABASE_HOST,
+    port: Number(process.env.DATABASE_PORT) || 5432,
+    database: process.env.DATABASE_NAME,
+    user: process.env.DATABASE_USER,
+    password: process.env.DATABASE_PASSWORD,
+    ssl: process.env.DATABASE_SSL !== 'false'
+      ? {
+          rejectUnauthorized: process.env.DATABASE_SSL === 'secure' && !!ca,
+          ca,
+          cert,
+          key
+        }
+      : false
+  }
+
+  return createPostgresPool(options)
+}

package/lib/dotenv.js

@@ -0,0 +1,6 @@
+export function loadEnv () {
+  // .env first (higher precedence), then .env.defaults fills in gaps.
+  // process.loadEnvFile() does not overwrite existing vars.
+  try { process.loadEnvFile('.env') } catch {}
+  try { process.loadEnvFile('.env.defaults') } catch {}
+}

package/lib/health.js

@@ -0,0 +1,36 @@
+const readinessChecks = []
+const healthChecks = []
+
+export function registerReadinessCheck (fn) {
+  readinessChecks.push(fn)
+}
+
+export function registerHealthCheck (fn) {
+  healthChecks.push(fn)
+}
+
+export function getReadinessChecks () {
+  return readinessChecks
+}
+
+export function getHealthChecks () {
+  return healthChecks
+}
+
+export function clearChecks () {
+  readinessChecks.length = 0
+  healthChecks.length = 0
+}
+
+export async function mysqlHealthCheck (pool) {
+  await pool.query('SELECT 1')
+}
+
+export async function postgresHealthCheck (pool) {
+  await pool.query('SELECT 1')
+}
+
+export async function redisHealthCheck (client) {
+  const rawClient = client.getClient ? client.getClient() : client
+  await rawClient.ping()
+}

package/lib/index.js

@@ -0,0 +1,28 @@
+export { createApp } from './app.js'
+export { createMetricsServer } from './metrics-server.js'
+export { createLogger, getLogger, pinoConfig } from './logger.js'
+export { loadEnv } from './dotenv.js'
+export { registerHealthCheck, registerReadinessCheck, clearChecks, mysqlHealthCheck, postgresHealthCheck, redisHealthCheck } from './health.js'
+export { default as metricsPlugin } from './plugins/metrics.js'
+
+/**
+ * Autohook that requires a valid JWT on every request in the encapsulated scope.
+ * Use as the default export of an `autohooks.js` file to protect all routes in that directory.
+ *
+ * @example
+ * // src/routes/api/autohooks.js
+ * export { jwtAuthHook as default } from '@open-xchange/fastify-sdk'
+ *
+ * @param {import('fastify').FastifyInstance} app
+ */
+export async function jwtAuthHook (app) {
+  app.addHook('onRequest', app.verifyJWT)
+}
+
+// Re-exports so consuming projects don't need to install these separately
+export { default as fastify } from 'fastify'
+export { default as fp } from 'fastify-plugin'
+export { default as pino } from 'pino'
+export { default as promClient } from 'prom-client'
+export { default as createError } from 'http-errors'
+export * as jose from 'jose'

package/lib/lint/index.js

@@ -0,0 +1,5 @@
+import config from '@open-xchange/lint'
+
+export default [
+  ...config
+]

package/lib/logger.js

@@ -0,0 +1,60 @@
+import pino from 'pino'
+import { loadEnv } from './dotenv.js'
+
+const pinoConfig = {
+  base: undefined,
+  redact: {
+    paths: ['headers.authorization', 'headers.cookie', 'headers.host', 'key', 'password', 'salt', 'hash'],
+    censor: '**REDACTED**',
+    remove: true
+  },
+  level: process.env.LOG_LEVEL || 'info',
+  timestamp: () => `,"timestamp":${Date.now()}`,
+  formatters: {
+    level (label, number) {
+      switch (number) {
+        case 10: return { level: 8 } // trace
+        case 20: return { level: 7 } // debug
+        case 30: return { level: 6 } // info
+        case 40: return { level: 4 } // warn
+        case 50: return { level: 3 } // error
+        case 60: return { level: 0 } // fatal
+      }
+    }
+  }
+}
+
+const pretty = process.env.LOG_PRETTY !== undefined
+  ? process.env.LOG_PRETTY === 'true'
+  : process.stdout.isTTY
+
+if (pretty) {
+  pinoConfig.transport = {
+    target: 'pino-pretty',
+    options: {
+      translateTime: 'SYS:mm/dd HH:MM:ss.l',
+      customLevels: 'fatal:0,error:3,warn:4,info:6,debug:7,trace:8',
+      customColors: 'fatal:red,error:red,warn:yellow,info:green,debug:blue,trace:gray'
+    }
+  }
+}
+
+export function createLogger (options = {}) {
+  return pino({ ...pinoConfig, ...options })
+}
+
+let _defaultLogger
+
+/**
+ * Returns a shared logger singleton. Creates it on first call
+ * (calling loadEnv() to ensure env vars like LOG_LEVEL are loaded).
+ */
+export function getLogger () {
+  if (!_defaultLogger) {
+    loadEnv()
+    _defaultLogger = createLogger()
+  }
+  return _defaultLogger
+}
+
+export { pinoConfig }

package/lib/metrics-server.js

@@ -0,0 +1,33 @@
+import fastify from 'fastify'
+import promClient from 'prom-client'
+import { getReadinessChecks, getHealthChecks } from './health.js'
+
+export function createMetricsServer () {
+  const app = fastify({ logger: false })
+
+  app.get('/ready', async (request, reply) => {
+    return handleChecks(reply, getReadinessChecks())
+  })
+
+  app.get('/live', async (request, reply) => {
+    return handleChecks(reply, getHealthChecks())
+  })
+
+  app.get('/metrics', async (request, reply) => {
+    const metrics = await promClient.register.metrics()
+    reply.type(promClient.register.contentType)
+    return metrics
+  })
+
+  return app
+}
+
+async function handleChecks (reply, checks) {
+  try {
+    await Promise.all(checks.map(fn => fn()))
+    return { status: 'ok' }
+  } catch {
+    reply.code(503)
+    return { status: 'error' }
+  }
+}

package/lib/plugins/cors.js

@@ -0,0 +1,16 @@
+import cors from '@fastify/cors'
+import fp from 'fastify-plugin'
+
+export default fp(async function corsPlugin (fastify, opts) {
+  const originsFromEnv = (process.env.ORIGINS || '').split(',').filter(Boolean)
+  const origin = originsFromEnv.length === 1 ? originsFromEnv[0] : originsFromEnv.length > 1 ? originsFromEnv : false
+
+  const defaults = {
+    origin,
+    methods: ['GET', 'POST'],
+    maxAge: 86400
+  }
+
+  const options = opts === true ? defaults : { ...defaults, ...opts }
+  fastify.register(cors, options)
+})

package/lib/plugins/helmet.js

@@ -0,0 +1,14 @@
+import helmet from '@fastify/helmet'
+import fp from 'fastify-plugin'
+
+export default fp(async function helmetPlugin (fastify, opts) {
+  const defaults = {
+    contentSecurityPolicy: false,
+    crossOriginEmbedderPolicy: false,
+    originAgentCluster: false,
+    crossOriginOpenerPolicy: { policy: 'same-origin-allow-popups' }
+  }
+
+  const options = opts === true ? defaults : { ...defaults, ...opts }
+  fastify.register(helmet, options)
+})

package/lib/plugins/jwt.js

@@ -0,0 +1,88 @@
+import jwt from '@fastify/jwt'
+import fp from 'fastify-plugin'
+import createError from 'http-errors'
+import * as jose from 'jose'
+
+const getUrl = (domain) => /^https?:\/\//.test(domain) ? domain : `https://${domain}`
+
+function isAllowed (issuer = '', allowedIssuers = []) {
+  for (const allowed of allowedIssuers) {
+    if (issuer === allowed) return true
+    if (allowed.startsWith('https://*.') && issuer.endsWith(allowed.substring(9))) return true
+  }
+  return false
+}
+
+async function discoverJwksUri (domain) {
+  try {
+    const discoveryUrl = new URL('.well-known/openid-configuration', domain.endsWith('/') ? domain : `${domain}/`)
+    const response = await fetch(discoveryUrl)
+    if (response.ok) {
+      const config = await response.json()
+      if (config.jwks_uri) return new URL(config.jwks_uri)
+    }
+  } catch {
+    // OIDC discovery not available, fall back to direct JWKS URI
+  }
+  return new URL('.well-known/jwks.json', domain.endsWith('/') ? domain : `${domain}/`)
+}
+
+export default fp(async function jwtPlugin (fastify, opts) {
+  const allowedIssuers = (process.env.OIDC_ISSUER || '')
+    .trim().split(/\s*,\s*/).filter(Boolean).map(getUrl)
+
+  if (!allowedIssuers.length && !opts.key) {
+    fastify.log.warn('JWT plugin registered but OIDC_ISSUER is not configured')
+    fastify.decorate('verifyJWT', async (request, reply) => {
+      throw createError(401, 'OIDC_ISSUER is not configured')
+    })
+    return
+  }
+
+  if (!allowedIssuers.length && opts.key) {
+    fastify
+      .register(jwt, {
+        decode: { complete: true },
+        secret: opts.key
+      })
+      .decorate('verifyJWT', async (request, reply) => {
+        await request.jwtVerify()
+      })
+    return
+  }
+
+  // Per-domain remote JWK sets — jose handles caching and key rotation internally
+  const jwksSets = new Map()
+
+  async function getRemotePublicKey (token) {
+    const {
+      header: { kid, alg },
+      payload: { iss }
+    } = token
+    try {
+      const domain = getUrl(iss)
+      if (!isAllowed(domain, allowedIssuers)) {
+        throw new Error(`Issuer "${iss}" not in allowlist: [${allowedIssuers.join(', ')}]`)
+      }
+      if (!jwksSets.has(domain)) {
+        const jwksUri = await discoverJwksUri(domain)
+        jwksSets.set(domain, jose.createRemoteJWKSet(jwksUri))
+      }
+      const getKey = jwksSets.get(domain)
+      const key = await getKey({ kid, alg }, {})
+      return jose.exportSPKI(key)
+    } catch (err) {
+      fastify.log.error({ err }, `Failed to get public key for token: ${err.message}`)
+      return {}
+    }
+  }
+
+  fastify
+    .register(jwt, {
+      decode: { complete: true },
+      secret: (request, token) => getRemotePublicKey(token)
+    })
+    .decorate('verifyJWT', async (request, reply) => {
+      await request.jwtVerify()
+    })
+})

package/lib/plugins/logging.js

@@ -0,0 +1,15 @@
+import fp from 'fastify-plugin'
+
+export default fp(async function loggingPlugin (fastify) {
+  fastify.addHook('preHandler', function (req, reply, done) {
+    if (req.body) req.log.trace({ body: req.body }, 'parsed body')
+    done()
+  })
+
+  fastify.addHook('onResponse', (req, reply, done) => {
+    const loggingOptions = { url: req.raw.url, res: reply, responseTime: reply.elapsedTime }
+    if (process.env.LOG_LEVEL === 'trace') loggingOptions.headers = req.headers
+    reply.log.debug(loggingOptions, 'request completed')
+    done()
+  })
+})

package/lib/plugins/metrics.js

@@ -0,0 +1,8 @@
+import fp from 'fastify-plugin'
+import fastifyMetrics from 'fastify-metrics'
+
+export default fp(async function metricsPlugin (fastify) {
+  await fastify.register(fastifyMetrics, {
+    endpoint: null
+  })
+})

package/lib/plugins/swagger.js

@@ -0,0 +1,31 @@
+import fp from 'fastify-plugin'
+import fastifySwagger from '@fastify/swagger'
+import fastifySwaggerUi from '@fastify/swagger-ui'
+
+export default fp(async function swaggerPlugin (fastify, opts) {
+  const { openapi = {}, routePrefix = '/api-docs', prefix } = opts
+
+  const config = {
+    routePrefix,
+    prefix: prefix || process.env.APP_ROOT,
+    openapi
+  }
+
+  await fastify.register(fastifySwagger, config)
+
+  await fastify.register(fastifySwaggerUi, {
+    routePrefix,
+    uiConfig: {
+      docExpansion: 'full',
+      deepLinking: false
+    },
+    uiHooks: {
+      onRequest: function (request, reply, next) { next() },
+      preHandler: function (request, reply, next) { next() }
+    },
+    staticCSP: true,
+    transformStaticCSP: (header) => header,
+    transformSpecification: (swaggerObject) => swaggerObject,
+    transformSpecificationClone: true
+  })
+})