Безпечна конфігурація Node.js API

const https = require('node:https');
const fs = require('node:fs');

const tlsOptions = {
  key: fs.readFileSync(process.env.TLS_KEY_FILE),
  cert: fs.readFileSync(process.env.TLS_CERT_FILE),
  minVersion: 'TLSv1.2'
};

const server = https.createServer(tlsOptions, requestHandler);

TLS_KEY_FILE=/etc/my-api/tls/server.key
TLS_CERT_FILE=/etc/my-api/tls/server.crt

mkdir -p certs

openssl req -x509 -newkey rsa:2048 \
  -keyout certs/server.key \
  -out certs/server.crt \
  -days 1 \
  -nodes \
  -subj "/CN=localhost"

function positiveInteger(value, fallback) {
  if (value === undefined || value === '') {
    return fallback;
  }

  const number = Number(value);

  if (!Number.isInteger(number) || number <= 0) {
    throw new Error(`Некоректне додатне ціле число: ${value}`);
  }

  return number;
}

const config = {
  // Локальне прослуховування є безпечнішим значенням за замовчуванням.
  host: process.env.HOST || '127.0.0.1',
  port: positiveInteger(process.env.PORT, 8443),
  requestTimeout: positiveInteger(process.env.REQUEST_TIMEOUT_MS, 30_000),
  tlsKeyFile: process.env.TLS_KEY_FILE || './certs/server.key',
  tlsCertFile: process.env.TLS_CERT_FILE || './certs/server.crt',
  environment: process.env.NODE_ENV || 'development'
};

HOST=0.0.0.0

{"level":"info","event":"request.completed","requestId":"...","statusCode":200}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Внутрішня помилка сервера",
    "requestId": "..."
  }
}

'use strict';

const fs = require('node:fs');
const https = require('node:https');
const crypto = require('node:crypto');

function positiveInteger(value, fallback) {
  if (value === undefined || value === '') {
    return fallback;
  }

  const number = Number(value);

  if (!Number.isInteger(number) || number <= 0) {
    throw new Error(`Некоректне додатне ціле число: ${value}`);
  }

  return number;
}

const config = {
  // Безпечне значення за замовчуванням: доступ лише з локальної машини.
  host: process.env.HOST || '127.0.0.1',
  port: positiveInteger(process.env.PORT, 8443),
  requestTimeout: positiveInteger(process.env.REQUEST_TIMEOUT_MS, 30_000),
  headersTimeout: positiveInteger(process.env.HEADERS_TIMEOUT_MS, 10_000),
  keepAliveTimeout: positiveInteger(process.env.KEEP_ALIVE_TIMEOUT_MS, 5_000),
  tlsKeyFile: process.env.TLS_KEY_FILE || './certs/server.key',
  tlsCertFile: process.env.TLS_CERT_FILE || './certs/server.crt',
  environment: process.env.NODE_ENV || 'development',
  runAsUser: process.env.RUN_AS_USER || ''
};

function writeLog(level, event, metadata = {}) {
  const entry = {
    timestamp: new Date().toISOString(),
    level,
    event,
    ...metadata
  };

  process.stderr.write(`${JSON.stringify(entry)}\n`);
}

function sendJson(response, statusCode, payload, requestId) {
  const body = JSON.stringify(payload);

  response.statusCode = statusCode;
  response.setHeader('Content-Type', 'application/json; charset=utf-8');
  response.setHeader('Content-Length', Buffer.byteLength(body));
  response.setHeader('X-Request-Id', requestId);
  response.setHeader('X-Content-Type-Options', 'nosniff');
  response.setHeader('Referrer-Policy', 'no-referrer');

  if (config.environment === 'production') {
    response.setHeader(
      'Strict-Transport-Security',
      'max-age=31536000'
    );
  }

  response.end(body);
}

function sendError(response, statusCode, code, message, requestId) {
  sendJson(
    response,
    statusCode,
    {
      error: {
        code,
        message,
        requestId
      }
    },
    requestId
  );
}

function requestHandler(request, response) {
  const requestId = crypto.randomUUID();
  const startedAt = process.hrtime.bigint();

  response.setHeader('X-Request-Id', requestId);

  try {
    const requestUrl = new URL(
      request.url || '/',
      `https://${request.headers.host || 'localhost'}`
    );

    if (requestUrl.pathname === '/healthz' && request.method === 'GET') {
      sendJson(
        response,
        200,
        {
          status: 'ok'
        },
        requestId
      );
      return;
    }

    if (requestUrl.pathname === '/api/hello' && request.method === 'GET') {
      sendJson(
        response,
        200,
        {
          message: 'Вітаємо в API'
        },
        requestId
      );
      return;
    }

    if (requestUrl.pathname === '/api/hello') {
      sendError(
        response,
        405,
        'METHOD_NOT_ALLOWED',
        'Метод не підтримується',
        requestId
      );
      return;
    }

    sendError(
      response,
      404,
      'NOT_FOUND',
      'Маршрут не знайдено',
      requestId
    );
  } catch (error) {
    writeLog('error', 'request.failed', {
      requestId,
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack
      }
    });

    if (!response.headersSent) {
      sendError(
        response,
        500,
        'INTERNAL_ERROR',
        'Внутрішня помилка сервера',
        requestId
      );
    } else {
      response.destroy();
    }
  } finally {
    const durationMs = Number(process.hrtime.bigint() - startedAt) / 1e6;

    writeLog('info', 'request.completed', {
      requestId,
      method: request.method,
      path: request.url,
      statusCode: response.statusCode,
      durationMs: Math.round(durationMs),
      remoteAddress: request.socket.remoteAddress
    });
  }
}

let server;

function dropPrivileges() {
  if (!config.runAsUser) {
    return;
  }

  if (typeof process.getuid !== 'function' || process.getuid() !== 0) {
    throw new Error(
      'RUN_AS_USER можна використовувати лише під час запуску від root у Unix-подібній системі'
    );
  }

  if (typeof process.setgid !== 'function' || typeof process.setuid !== 'function') {
    throw new Error('Поточна платформа не підтримує зміну Unix-привілеїв');
  }

  // Спочатку змінюємо групу, потім користувача.
  process.setgid(config.runAsUser);
  process.setuid(config.runAsUser);

  writeLog('info', 'process.privileges_dropped', {
    user: config.runAsUser
  });
}

function shutdown(signal) {
  writeLog('info', 'process.shutdown_started', { signal });

  server.close((error) => {
    if (error) {
      writeLog('error', 'process.shutdown_failed', {
        error: {
          name: error.name,
          message: error.message,
          stack: error.stack
        }
      });

      process.exitCode = 1;
      return;
    }

    writeLog('info', 'process.shutdown_completed');
    process.exitCode = 0;
  });

  setTimeout(() => {
    writeLog('error', 'process.shutdown_forced');
    process.exit(1);
  }, 10_000).unref();
}

process.on('uncaughtException', (error) => {
  writeLog('fatal', 'process.uncaught_exception', {
    error: {
      name: error.name,
      message: error.message,
      stack: error.stack
    }
  });

  process.exit(1);
});

process.on('unhandledRejection', (reason) => {
  writeLog('fatal', 'process.unhandled_rejection', {
    reason: reason instanceof Error
      ? {
          name: reason.name,
          message: reason.message,
          stack: reason.stack
        }
      : String(reason)
  });

  process.exit(1);
});

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

try {
  const tlsOptions = {
    key: fs.readFileSync(config.tlsKeyFile),
    cert: fs.readFileSync(config.tlsCertFile),
    minVersion: 'TLSv1.2'
  };

  server = https.createServer(tlsOptions, requestHandler);

  server.requestTimeout = config.requestTimeout;
  server.headersTimeout = config.headersTimeout;
  server.keepAliveTimeout = config.keepAliveTimeout;

  server.on('clientError', (error, socket) => {
    writeLog('warn', 'http.client_error', {
      error: {
        name: error.name,
        message: error.message
      }
    });

    socket.destroy();
  });

  server.on('error', (error) => {
    writeLog('fatal', 'server.error', {
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack
      }
    });

    process.exit(1);
  });

  server.listen(config.port, config.host, () => {
    try {
      // Для порту 8443 root не потрібен, тому зазвичай цей параметр не задають.
      dropPrivileges();

      writeLog('info', 'server.started', {
        host: config.host,
        port: config.port,
        environment: config.environment
      });
    } catch (error) {
      writeLog('fatal', 'process.privilege_change_failed', {
        error: {
          name: error.name,
          message: error.message,
          stack: error.stack
        }
      });

      server.close(() => process.exit(1));
    }
  });
} catch (error) {
  writeLog('fatal', 'server.start_failed', {
    error: {
      name: error.name,
      message: error.message,
      stack: error.stack
    }
  });

  process.exit(1);
}

NODE_ENV=development \
TLS_KEY_FILE=./certs/server.key \
TLS_CERT_FILE=./certs/server.crt \
node server.js

curl --insecure https://127.0.0.1:8443/healthz

RUN_AS_USER=my-api-user

const apiKey = 'production-secret';

response.end(JSON.stringify({
  error: error.stack
}));