@peraflop/ws-commons

Paquete de utilidades compartidas para microservicios: autenticación JWT, control de acceso por grants, CORS, acceso a Neon (PostgreSQL) y Upstash Redis, y observabilidad con OpenTelemetry.

Instalación

npm install @peraflop/ws-commons

Observabilidad y datos sensibles

import { Observability } from "@peraflop/ws-commons";

Observability.init("mi-servicio", "1.0.0", {
  // default false: los spans NO incluyen bodies ni params de requests/queries
  verboseAttributes: process.env.API_ENV !== "PRO",
  // claves extra a redactar (se suman a las default: password, token, email, dni, birth, address, ...)
  redactKeys: ["historiaClinica"],
});

Comportamiento por defecto (seguro para PRO):

• Los spans de Gateway y NeonDB no registran bodies, query params ni parámetros SQL.
• El nombre de los spans usa la plantilla de ruta, no la URL real (sin query string, sin PII, baja cardinalidad en métricas).
• Los tokens Bearer nunca se registran, ni parcialmente.

Con verboseAttributes: true (pensado para DEV), bodies y params se incluyen en los spans pero pasando por Observability.redact(), que reemplaza los valores de claves sensibles por "[REDACTED]" (recursivo).

Errores y stacktraces

• Las excepciones dentro de Span.run, Gateway y NeonDB se registran con span.recordException(err), que incluye el stacktrace completo como evento del span (exception.stacktrace).
• Si pasás un Error en los atributos de un log, se serializa con su stacktrace:

Log.error("Falló la creación del turno", { error: err, appointmentId });

Route templates en Gateway

Los métodos HTTP aceptan un cuarto parámetro opcional:

await Gateway.get(url, filters, token, { routeTemplate: "/patients/:id" });

Si no se indica, el span usa el path sin query string como fallback.

Autenticación

import { mwAuthenticate, needs } from "@peraflop/ws-commons";

app.get("/appointments", mwAuthenticate, needs("appointments.search"), handler);

Requiere la variable de entorno JWT_SECRET (HMAC HS256/384/512).

Variables de entorno

| Variable | Uso | | ---------------------------------------------------- | ----------------------------------------------------- | | JWT_SECRET | Firma/verificación de tokens JWT | | DB_USER, DB_PASS, DB_HOST | Conexión a Neon (PostgreSQL) | | UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN | Redis (opcional; si faltan, se desactiva) | | OTEL_EXPORTER_URL, OTEL_AUTHORIZATION_TOKEN | Export OTLP (opcional; si falta la URL, se desactiva) |

Cambios en 3.0.0

• BREAKING: mwCorsHandler ahora es una factory que requiere { origins }.
• Los spans ya no incluyen bodies/params por defecto (nuevo verboseAttributes + redactKeys).
• Eliminado el logueo parcial del Bearer token en Gateway.
• Los nombres de span usan route templates en vez de la URL completa.
• Log.error serializa instancias de Error con su stacktrace.