@tumbaland/backend-core 1.16.0

package/dist/middleware/security.d.ts

@@ -0,0 +1,26 @@
+import { Options as RateLimitOptions } from 'express-rate-limit';
+/**
+ * Standard security headers (helmet) for all services.
+ *
+ * - `contentSecurityPolicy` is off: these are JSON APIs, not HTML apps, and a
+ *   couple of services serve a static Swagger docs page under `/api/docs`
+ *   whose inline scripts a default CSP would break.
+ * - `crossOriginResourcePolicy` is relaxed to `cross-origin`: helmet's default
+ *   (`same-origin`) makes browsers refuse to read the response from a
+ *   different origin — which every frontend is, since each front and backend
+ *   service runs on its own port. CORS (see `createCorsMiddleware`) already
+ *   does origin enforcement; this header must not fight it.
+ */
+export declare const securityHeaders: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, next: (err?: unknown) => void) => void;
+/**
+ * Build a rate limiter with sane JSON error output. Counts per client IP.
+ */
+export declare function createRateLimiter(options?: Partial<RateLimitOptions>): import("express-rate-limit").RateLimitRequestHandler;
+/** Baseline limiter for authenticated/general routes. */
+export declare const standardRateLimiter: import("express-rate-limit").RateLimitRequestHandler;
+/**
+ * Tighter limiter for brute-force-prone unauthenticated routes (token
+ * issuance, public endpoints with no auth in front of them).
+ */
+export declare const strictRateLimiter: import("express-rate-limit").RateLimitRequestHandler;
+//# sourceMappingURL=security.d.ts.map

package/dist/middleware/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/middleware/security.ts"],"names":[],"mappings":"AACA,OAAkB,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,gGA4Bi/H,CAAC,2BAxB5gI,CAAC;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM,wDASxE;AAED,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,sDAAsB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,sDAAiC,CAAC"}

package/dist/middleware/security.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.strictRateLimiter = exports.standardRateLimiter = exports.securityHeaders = void 0;
+exports.createRateLimiter = createRateLimiter;
+const helmet_1 = __importDefault(require("helmet"));
+const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
+/**
+ * Standard security headers (helmet) for all services.
+ *
+ * - `contentSecurityPolicy` is off: these are JSON APIs, not HTML apps, and a
+ *   couple of services serve a static Swagger docs page under `/api/docs`
+ *   whose inline scripts a default CSP would break.
+ * - `crossOriginResourcePolicy` is relaxed to `cross-origin`: helmet's default
+ *   (`same-origin`) makes browsers refuse to read the response from a
+ *   different origin — which every frontend is, since each front and backend
+ *   service runs on its own port. CORS (see `createCorsMiddleware`) already
+ *   does origin enforcement; this header must not fight it.
+ */
+exports.securityHeaders = (0, helmet_1.default)({
+    contentSecurityPolicy: false,
+    crossOriginResourcePolicy: { policy: 'cross-origin' },
+    crossOriginEmbedderPolicy: false
+});
+/**
+ * Build a rate limiter with sane JSON error output. Counts per client IP.
+ */
+function createRateLimiter(options = {}) {
+    return (0, express_rate_limit_1.default)({
+        windowMs: 15 * 60 * 1000,
+        max: 300,
+        standardHeaders: true,
+        legacyHeaders: false,
+        message: { success: false, message: 'Too many requests, please try again later' },
+        ...options
+    });
+}
+/** Baseline limiter for authenticated/general routes. */
+exports.standardRateLimiter = createRateLimiter();
+/**
+ * Tighter limiter for brute-force-prone unauthenticated routes (token
+ * issuance, public endpoints with no auth in front of them).
+ */
+exports.strictRateLimiter = createRateLimiter({ max: 20 });
+//# sourceMappingURL=security.js.map

package/dist/middleware/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/middleware/security.ts"],"names":[],"mappings":";;;;;;AAwBA,8CASC;AAjCD,oDAA4B;AAC5B,4EAA4E;AAE5E;;;;;;;;;;;GAWG;AACU,QAAA,eAAe,GAAG,IAAA,gBAAM,EAAC;IACpC,qBAAqB,EAAE,KAAK;IAC5B,yBAAyB,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE;IACrD,yBAAyB,EAAE,KAAK;CACjC,CAAC,CAAC;AAEH;;GAEG;AACH,SAAgB,iBAAiB,CAAC,UAAqC,EAAE;IACvE,OAAO,IAAA,4BAAS,EAAC;QACf,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;QACxB,GAAG,EAAE,GAAG;QACR,eAAe,EAAE,IAAI;QACrB,aAAa,EAAE,KAAK;QACpB,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,2CAA2C,EAAE;QACjF,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC;AAED,yDAAyD;AAC5C,QAAA,mBAAmB,GAAG,iBAAiB,EAAE,CAAC;AAEvD;;;GAGG;AACU,QAAA,iBAAiB,GAAG,iBAAiB,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC"}

package/dist/middleware/validate.d.ts

@@ -0,0 +1,11 @@
+import { RequestHandler } from 'express';
+import { ZodType } from 'zod';
+/**
+ * Validates `req.body` against a zod schema before the route handler runs.
+ * On failure, throws a `BadRequestError` (caught by the shared errorHandler)
+ * instead of letting controllers hand-roll their own field checks. On
+ * success, `req.body` is replaced with the parsed result so handlers get
+ * zod's inferred, coerced types rather than raw untyped input.
+ */
+export declare function validate(schema: ZodType): RequestHandler;
+//# sourceMappingURL=validate.d.ts.map

package/dist/middleware/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/middleware/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAG9B;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAWxD"}

package/dist/middleware/validate.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate = validate;
+const HttpError_1 = require("../errors/HttpError");
+/**
+ * Validates `req.body` against a zod schema before the route handler runs.
+ * On failure, throws a `BadRequestError` (caught by the shared errorHandler)
+ * instead of letting controllers hand-roll their own field checks. On
+ * success, `req.body` is replaced with the parsed result so handlers get
+ * zod's inferred, coerced types rather than raw untyped input.
+ */
+function validate(schema) {
+    return (req, _res, next) => {
+        const result = schema.safeParse(req.body);
+        if (!result.success) {
+            const issue = result.error.issues[0];
+            const field = issue.path.length ? `${issue.path.join('.')}: ` : '';
+            throw new HttpError_1.BadRequestError(`${field}${issue.message}`);
+        }
+        req.body = result.data;
+        next();
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/middleware/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/middleware/validate.ts"],"names":[],"mappings":";;AAWA,4BAWC;AApBD,mDAAsD;AAEtD;;;;;;GAMG;AACH,SAAgB,QAAQ,CAAC,MAAe;IACtC,OAAO,CAAC,GAAY,EAAE,IAAc,EAAE,IAAkB,EAAQ,EAAE;QAChE,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACrC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,2BAAe,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACvB,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/tracing/index.d.ts

@@ -0,0 +1,13 @@
+import { Tracer } from '@opentelemetry/api';
+export declare const initTracer: (serviceName: string) => Tracer;
+export declare const getTracer: () => Tracer;
+export declare const startSpan: (operationName: string, parentSpan?: any) => import("@opentelemetry/api").Span;
+export declare const tracingMiddleware: (req: any, res: any, next: any) => void;
+export declare const createChildSpan: (operationName: string, parentSpan: any) => import("@opentelemetry/api").Span;
+export declare const logToSpan: (span: any, event: string, data?: any) => void;
+export declare const setSpanTag: (span: any, key: string, value: any) => void;
+export declare const injectHeaders: (span: any) => {
+    [key: string]: string;
+};
+export declare const extractSpanContext: (headers: any) => import("@opentelemetry/api").Context;
+//# sourceMappingURL=index.d.ts.map

package/dist/tracing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAQnF,eAAO,MAAM,UAAU,GAAI,aAAa,MAAM,KAAG,MAiBhD,CAAC;AAKF,eAAO,MAAM,SAAS,QAAO,MAK5B,CAAC;AAGF,eAAO,MAAM,SAAS,GAAI,eAAe,MAAM,EAAE,aAAa,GAAG,sCAShE,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAAI,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,SAmB9D,CAAC;AAGF,eAAO,MAAM,eAAe,GAAI,eAAe,MAAM,EAAE,YAAY,GAAG,sCAErE,CAAC;AAGF,eAAO,MAAM,SAAS,GAAI,MAAM,GAAG,EAAE,OAAO,MAAM,EAAE,OAAO,GAAG,SAE7D,CAAC;AAGF,eAAO,MAAM,UAAU,GAAI,MAAM,GAAG,EAAE,KAAK,MAAM,EAAE,OAAO,GAAG,SAE5D,CAAC;AAGF,eAAO,MAAM,aAAa,GAAI,MAAM,GAAG;;CAItC,CAAC;AAGF,eAAO,MAAM,kBAAkB,GAAI,SAAS,GAAG,yCAE9C,CAAC"}

package/dist/tracing/index.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSpanContext = exports.injectHeaders = exports.setSpanTag = exports.logToSpan = exports.createChildSpan = exports.tracingMiddleware = exports.startSpan = exports.getTracer = exports.initTracer = void 0;
+const api_1 = require("@opentelemetry/api");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+// Initialize OpenTelemetry tracer provider, exporting via OTLP/HTTP.
+// Endpoint resolution: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > JAEGER_ENDPOINT > in-cluster collector default.
+const initTracer = (serviceName) => {
+    const url = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
+        process.env.JAEGER_ENDPOINT ||
+        'http://jaeger-collector:4318/v1/traces';
+    const provider = new sdk_trace_node_1.NodeTracerProvider({
+        resource: (0, resources_1.resourceFromAttributes)({
+            [semantic_conventions_1.ATTR_SERVICE_NAME]: serviceName,
+            [semantic_conventions_1.ATTR_SERVICE_VERSION]: process.env.npm_package_version || '1.0.0',
+            'deployment.environment': process.env.NODE_ENV || 'development',
+        }),
+        spanProcessors: [new sdk_trace_node_1.BatchSpanProcessor(new exporter_trace_otlp_http_1.OTLPTraceExporter({ url }))],
+    });
+    provider.register();
+    return provider.getTracer(serviceName);
+};
+exports.initTracer = initTracer;
+// Global tracer instance
+let tracer = null;
+const getTracer = () => {
+    if (!tracer) {
+        tracer = (0, exports.initTracer)(process.env.SERVICE_NAME || 'unknown-service');
+    }
+    return tracer;
+};
+exports.getTracer = getTracer;
+// Start a new span. `parent` may be a Span or a Context (e.g. from extractSpanContext).
+const startSpan = (operationName, parentSpan) => {
+    if (!parentSpan) {
+        return (0, exports.getTracer)().startSpan(operationName);
+    }
+    const parentContext = typeof parentSpan.spanContext === 'function'
+        ? api_1.trace.setSpan(api_1.context.active(), parentSpan)
+        : parentSpan;
+    return (0, exports.getTracer)().startSpan(operationName, undefined, parentContext);
+};
+exports.startSpan = startSpan;
+// Middleware for Express to create spans for requests
+const tracingMiddleware = (req, res, next) => {
+    const parentContext = api_1.propagation.extract(api_1.context.active(), req.headers);
+    const span = (0, exports.getTracer)().startSpan(`${req.method} ${req.path}`, { kind: api_1.SpanKind.SERVER }, parentContext);
+    span.setAttribute('http.method', req.method);
+    span.setAttribute('http.url', req.url);
+    // Add span to request for use in handlers
+    req.span = span;
+    res.on('finish', () => {
+        span.setAttribute('http.status_code', res.statusCode);
+        span.end();
+    });
+    next();
+};
+exports.tracingMiddleware = tracingMiddleware;
+// Helper to create child spans
+const createChildSpan = (operationName, parentSpan) => {
+    return (0, exports.startSpan)(operationName, parentSpan);
+};
+exports.createChildSpan = createChildSpan;
+// Helper to log events to spans
+const logToSpan = (span, event, data) => {
+    span.addEvent(event, data);
+};
+exports.logToSpan = logToSpan;
+// Helper to set tags on spans
+const setSpanTag = (span, key, value) => {
+    span.setAttribute(key, value);
+};
+exports.setSpanTag = setSpanTag;
+// Helper to inject tracing headers (W3C traceparent) for downstream calls
+const injectHeaders = (span) => {
+    const headers = {};
+    api_1.propagation.inject(api_1.trace.setSpan(api_1.context.active(), span), headers);
+    return headers;
+};
+exports.injectHeaders = injectHeaders;
+// Helper to extract span context from incoming headers; pass the result to startSpan as parent
+const extractSpanContext = (headers) => {
+    return api_1.propagation.extract(api_1.context.active(), headers);
+};
+exports.extractSpanContext = extractSpanContext;
+//# sourceMappingURL=index.js.map

package/dist/tracing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":"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"}

package/dist/types/auth.d.ts

@@ -0,0 +1,32 @@
+export interface UserPayload {
+    id: string;
+    email: string;
+    name: string;
+    picture?: string;
+    groups?: string[];
+}
+/**
+ * Attaches `user`/`userGroups` to every Express `Request` across all
+ * services, replacing the ad-hoc `(req as any).user` casts and each
+ * service's own divergent local augmentation. Individual services may still
+ * carry additional request-scoped fields (e.g. auth-service's `dbUser`) —
+ * those stay local since they aren't meaningful outside that service.
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            user?: UserPayload;
+            userGroups?: string[];
+        }
+    }
+}
+export interface ServiceHealth {
+    status: 'ok' | 'error';
+    service: string;
+    type: 'backend' | 'frontend';
+    timestamp: string;
+    version: string;
+    description: string;
+    dependencies?: Record<string, any>;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE,WAAW,CAAC;YACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;SACvB;KACF;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC"}

package/dist/types/auth.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=auth.js.map

package/dist/types/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":""}

package/dist/utils/correlation.d.ts

@@ -0,0 +1,11 @@
+import { RequestHandler } from 'express';
+/**
+ * Generate a unique correlation ID for request tracing
+ */
+export declare function generateCorrelationId(): string;
+/**
+ * Middleware to add correlation ID to requests
+ * Adds correlation ID to request object and response headers
+ */
+export declare const correlationMiddleware: RequestHandler;
+//# sourceMappingURL=correlation.d.ts.map

package/dist/utils/correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../../src/utils/correlation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAG1E;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAOnC,CAAC"}

package/dist/utils/correlation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.correlationMiddleware = void 0;
+exports.generateCorrelationId = generateCorrelationId;
+const uuid_1 = require("uuid");
+/**
+ * Generate a unique correlation ID for request tracing
+ */
+function generateCorrelationId() {
+    return (0, uuid_1.v4)();
+}
+/**
+ * Middleware to add correlation ID to requests
+ * Adds correlation ID to request object and response headers
+ */
+const correlationMiddleware = (req, res, next) => {
+    const correlationId = req.headers['x-correlation-id'] || generateCorrelationId();
+    req.correlationId = correlationId;
+    res.setHeader('x-correlation-id', correlationId);
+    next();
+};
+exports.correlationMiddleware = correlationMiddleware;
+//# sourceMappingURL=correlation.js.map

package/dist/utils/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../../src/utils/correlation.ts"],"names":[],"mappings":";;;AAMA,sDAEC;AAPD,+BAAoC;AAEpC;;GAEG;AACH,SAAgB,qBAAqB;IACnC,OAAO,IAAA,SAAM,GAAE,CAAC;AAClB,CAAC;AAED;;;GAGG;AACI,MAAM,qBAAqB,GAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;IACvG,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAW,IAAI,qBAAqB,EAAE,CAAC;IAE1F,GAAW,CAAC,aAAa,GAAG,aAAa,CAAC;IAC3C,GAAG,CAAC,SAAS,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAEjD,IAAI,EAAE,CAAC;AACT,CAAC,CAAC;AAPW,QAAA,qBAAqB,yBAOhC"}

package/dist/utils/response.d.ts

@@ -0,0 +1,24 @@
+import { Response } from 'express';
+/**
+ * Standard API response format
+ */
+export interface ApiResponse<T = any> {
+    success: boolean;
+    data?: T;
+    message?: string;
+    error?: string;
+    correlationId?: string;
+}
+/**
+ * Create a standardized API response
+ */
+export declare function createApiResponse<T = any>(success: boolean, data?: T, message?: string, error?: string, correlationId?: string): ApiResponse<T>;
+/**
+ * Send a success response
+ */
+export declare function sendSuccess<T = any>(res: Response, data?: T, message?: string, statusCode?: number, correlationId?: string): void;
+/**
+ * Send an error response
+ */
+export declare function sendError(res: Response, message: string, statusCode?: number, error?: string, correlationId?: string): void;
+//# sourceMappingURL=response.d.ts.map

package/dist/utils/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,GAAG,EACvC,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,GACrB,WAAW,CAAC,CAAC,CAAC,CAShB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EACjC,GAAG,EAAE,QAAQ,EACb,IAAI,CAAC,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,GAAE,MAAY,EACxB,aAAa,CAAC,EAAE,MAAM,QAIvB;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAY,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,QAIvB"}

package/dist/utils/response.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiResponse = createApiResponse;
+exports.sendSuccess = sendSuccess;
+exports.sendError = sendError;
+/**
+ * Create a standardized API response
+ */
+function createApiResponse(success, data, message, error, correlationId) {
+    const response = { success };
+    if (data !== undefined)
+        response.data = data;
+    if (message)
+        response.message = message;
+    if (error)
+        response.error = error;
+    if (correlationId)
+        response.correlationId = correlationId;
+    return response;
+}
+/**
+ * Send a success response
+ */
+function sendSuccess(res, data, message, statusCode = 200, correlationId) {
+    const response = createApiResponse(true, data, message, undefined, correlationId);
+    res.status(statusCode).json(response);
+}
+/**
+ * Send an error response
+ */
+function sendError(res, message, statusCode = 500, error, correlationId) {
+    const response = createApiResponse(false, undefined, message, error, correlationId);
+    res.status(statusCode).json(response);
+}
+//# sourceMappingURL=response.js.map

package/dist/utils/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":";;AAgBA,8CAeC;AAKD,kCASC;AAKD,8BASC;AA9CD;;GAEG;AACH,SAAgB,iBAAiB,CAC/B,OAAgB,EAChB,IAAQ,EACR,OAAgB,EAChB,KAAc,EACd,aAAsB;IAEtB,MAAM,QAAQ,GAAmB,EAAE,OAAO,EAAE,CAAC;IAE7C,IAAI,IAAI,KAAK,SAAS;QAAE,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC;IAC7C,IAAI,OAAO;QAAE,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;IACxC,IAAI,KAAK;QAAE,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;IAClC,IAAI,aAAa;QAAE,QAAQ,CAAC,aAAa,GAAG,aAAa,CAAC;IAE1D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAgB,WAAW,CACzB,GAAa,EACb,IAAQ,EACR,OAAgB,EAChB,aAAqB,GAAG,EACxB,aAAsB;IAEtB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IAClF,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CACvB,GAAa,EACb,OAAe,EACf,aAAqB,GAAG,EACxB,KAAc,EACd,aAAsB;IAEtB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IACpF,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC"}

package/jest.config.js

@@ -0,0 +1,14 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/src/**/*.test.ts'],
+  clearMocks: true,
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { tsconfig: { types: ['jest', 'node'] } }]
+  },
+  coverageProvider: 'v8',
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts', '!src/index.ts', '!src/types/**'],
+  coverageReporters: ['text', 'json-summary'],
+  coverageThreshold: { global: { statements: 90, branches: 80, functions: 90, lines: 90 } }
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tumbaland/backend-core",
+  "version": "1.16.0",
+  "description": "Core shared functionality for Tumbaland backend services",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "release": "standard-version && npm run build && npm publish --access public",
+    "release:beta": "standard-version --prerelease beta && npm run build && npm publish --access public --tag beta",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "tumbaland",
+    "backend",
+    "shared",
+    "core",
+    "microservices"
+  ],
+  "author": "Tumbaland Team",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/cookie-parser": "^1.4.10",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/morgan": "^1.9.10",
+    "@types/node": "^26.1.0",
+    "standard-version": "^9.5.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
+    "@opentelemetry/resources": "^2.9.0",
+    "@opentelemetry/sdk-trace-node": "^2.9.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.5.2",
+    "helmet": "^8.0.0",
+    "jsonwebtoken": "^9.0.3",
+    "mongoose": "^9.7.3",
+    "morgan": "^1.11.0",
+    "prom-client": "^15.1.3",
+    "uuid": "^14.0.1",
+    "winston": "^3.19.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "express": "^5.1.0",
+    "mongoose": "^9.7.3"
+  }
+}

package/src/app/createBaseApp.test.ts

@@ -0,0 +1,69 @@
+import request from 'supertest';
+import { createBaseApp } from './createBaseApp';
+
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+describe('createBaseApp', () => {
+  it('parses JSON bodies and cookies by default', async () => {
+    const app = createBaseApp();
+    app.get('/echo-cookie', (req, res) => res.json({ cookies: req.cookies }));
+    app.post('/echo-body', (req, res) => res.json({ body: req.body }));
+
+    const cookieRes = await request(app).get('/echo-cookie').set('Cookie', 'foo=bar');
+    expect(cookieRes.body).toEqual({ cookies: { foo: 'bar' } });
+
+    const bodyRes = await request(app).post('/echo-body').send({ hello: 'world' });
+    expect(bodyRes.body).toEqual({ body: { hello: 'world' } });
+  });
+
+  it('applies security headers and rate limiting', async () => {
+    const app = createBaseApp();
+    app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    const res = await request(app).get('/ping');
+    expect(res.headers['x-content-type-options']).toBe('nosniff');
+  });
+
+  it('skips JSON parsing when parseJson is false', async () => {
+    const app = createBaseApp({ parseJson: false });
+    app.post('/echo-body', (req, res) => res.json({ body: req.body ?? null }));
+
+    const res = await request(app).post('/echo-body').set('Content-Type', 'application/json').send('{"hello":"world"}');
+    expect(res.body).toEqual({ body: null });
+  });
+
+  it('skips cookie parsing when parseCookies is false', async () => {
+    const app = createBaseApp({ parseCookies: false });
+    app.get('/echo-cookie', (req, res) => res.json({ cookies: req.cookies ?? null }));
+
+    const res = await request(app).get('/echo-cookie').set('Cookie', 'foo=bar');
+    expect(res.body).toEqual({ cookies: null });
+  });
+
+  it('honors a custom rate limiter', async () => {
+    const app = createBaseApp({ rateLimiter: (await import('../middleware/security')).createRateLimiter({ windowMs: 60_000, max: 1 }) });
+    app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    const first = await request(app).get('/ping');
+    const second = await request(app).get('/ping');
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(429);
+  });
+
+  it('mounts /health/live ahead of the rate limiter, so it never gets 429s a busy service would', async () => {
+    const app = createBaseApp({ rateLimiter: (await import('../middleware/security')).createRateLimiter({ windowMs: 60_000, max: 1 }) });
+    app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    await request(app).get('/ping'); // exhaust the max: 1 budget
+    const live1 = await request(app).get('/health/live');
+    const live2 = await request(app).get('/health/live');
+
+    expect(live1.status).toBe(200);
+    expect(live1.body).toEqual({ status: 'ok' });
+    expect(live2.status).toBe(200);
+  });
+});

package/src/app/createBaseApp.ts

@@ -0,0 +1,75 @@
+import express, { Express, RequestHandler } from 'express';
+import cookieParser from 'cookie-parser';
+import { correlationMiddleware } from '../utils/correlation';
+import { tracingMiddleware } from '../tracing';
+import { requestLogger, requestLoggerWithMetrics } from '../middleware/requestLogger';
+import { createCorsMiddleware, CorsMiddlewareOptions } from '../middleware/corsMiddleware';
+import { securityHeaders, standardRateLimiter } from '../middleware/security';
+import { healthLive } from '../health/healthController';
+
+export interface CreateBaseAppOptions {
+  /** Passed through to createCorsMiddleware. */
+  corsOptions?: CorsMiddlewareOptions;
+  /**
+   * Defaults to standardRateLimiter; pass strictRateLimiter or a custom one
+   * to override. Pass `false` to skip mounting one here entirely — e.g. when
+   * a route (like a webhook) must be registered, and therefore exempted,
+   * before the limiter, and the service applies it itself afterward.
+   */
+  rateLimiter?: RequestHandler | false;
+  /** Mount express.json() here. Set false when a route needs the raw body first (e.g. a webhook) or handles its own parsing. Default true. */
+  parseJson?: boolean;
+  /** Mount cookie-parser here. Set false for services that don't use cookies. Default true. */
+  parseCookies?: boolean;
+  /** Mount tracingMiddleware. Default true. */
+  tracing?: boolean;
+  /** Use requestLoggerWithMetrics (adds Prometheus histograms) instead of the plain requestLogger. Default true. */
+  metrics?: boolean;
+}
+
+/**
+ * Assembles the middleware stack every service was hand-rolling in its own
+ * index.ts (correlation → tracing → request logging → security → rate
+ * limiting → CORS → cookies → JSON body). Services still mount their own
+ * routes, `/health` (DB-aware readiness), `/metrics`, and
+ * `app.use(errorHandler)` last — this only owns the common prefix, not the
+ * whole app lifecycle.
+ *
+ * `/health/live` is the one exception: it's mounted here, first, ahead of
+ * every other middleware. It has zero per-service variation (it never
+ * touches a dependency, just confirms the process is up), so — unlike
+ * `/health` — there's nothing for a service to customize. Mounting it
+ * before the rate limiter also matters operationally: a service under
+ * heavy legitimate traffic shouldn't have its own liveness probe start
+ * getting 429s and get killed for being "unhealthy" at the exact moment
+ * it's just busy.
+ *
+ * Services with non-standard body parsing (a webhook needing the raw body,
+ * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
+ * false` and mount those themselves at the exact point they need to.
+ */
+export function createBaseApp(options: CreateBaseAppOptions = {}): Express {
+  const {
+    corsOptions,
+    rateLimiter = standardRateLimiter,
+    parseJson = true,
+    parseCookies = true,
+    tracing = true,
+    metrics = true
+  } = options;
+
+  const app = express();
+
+  app.get('/health/live', healthLive);
+
+  app.use(securityHeaders);
+  if (rateLimiter) app.use(rateLimiter);
+  app.use(correlationMiddleware);
+  if (tracing) app.use(tracingMiddleware);
+  app.use(metrics ? requestLoggerWithMetrics : requestLogger);
+  app.use(createCorsMiddleware(corsOptions));
+  if (parseCookies) app.use(cookieParser());
+  if (parseJson) app.use(express.json());
+
+  return app;
+}