@ciq-dev/neoiq-foundation-node 1.0.1-beta.1 → 1.0.1-beta.3

package/dist/index.mjs

@@ -1,12 +1,9 @@
-import { z } from "zod";
-import { AsyncLocalStorage } from "async_hooks";
-import pino from "pino";
-import { SpanStatusCode, SpanStatusCode as SpanStatusCode$1, context, context as context$1, metrics, propagation, propagation as propagation$1, trace, trace as trace$1 } from "@opentelemetry/api";
-import { NodeSDK } from "@opentelemetry/sdk-node";
-import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+import { AutoInstrumentationConfigSchema, FeaturesConfigSchema, FoundationConfigSchema, LoggingConfigSchema, OtelConfigSchema, RedactionConfigSchema, RequestLoggingConfigSchema, ShutdownConfigSchema, SpanStatusCode, context, getActiveSpan, getDefaultOtelEndpoint, getTraceContext, getTracer, isTracingEnabled, parseConfig, propagation, setupTracing, shutdownTracing, trace } from "./tracing-Cv-Y3fZx.mjs";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { SpanStatusCode as SpanStatusCode$1, context as context$1, metrics, propagation as propagation$1, trace as trace$1 } from "@opentelemetry/api";
+import { AsyncLocalStorage } from "async_hooks";
+import pino from "pino";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-grpc";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import fp from "fastify-plugin";
@@ -14,106 +11,251 @@ import { randomUUID } from "crypto";
 import axios from "axios";
 import axiosRetry from "axios-retry";
 import CircuitBreaker from "opossum";
+import { createHash } from "node:crypto";
+import { Readable } from "node:stream";
 
-//#region src/config.ts
-const AutoInstrumentationConfigSchema = z.object({
-	http: z.boolean().default(true),
-	fastify: z.boolean().default(true),
-	express: z.boolean().default(true),
-	mongodb: z.boolean().default(true),
-	pg: z.boolean().default(true),
-	mysql: z.boolean().default(true),
-	redis: z.boolean().default(true),
-	ioredis: z.boolean().default(true),
-	grpc: z.boolean().default(true),
-	fs: z.boolean().default(false),
-	dns: z.boolean().default(false)
-}).partial();
-const FeaturesConfigSchema = z.object({
-	tracing: z.boolean().default(true),
-	metrics: z.boolean().default(true),
-	logging: z.boolean().default(true),
-	autoInstrumentation: AutoInstrumentationConfigSchema.default({})
-}).partial();
-const DEFAULT_OTEL_ENDPOINT = "http://otel-stack-deployment-collector.observability.svc.cluster.local:4317";
-const OtelConfigSchema = z.object({
-	endpoint: z.string().default(DEFAULT_OTEL_ENDPOINT),
-	metricsIntervalMs: z.number().min(1e3).default(5e3),
-	traceSampleRate: z.number().min(0).max(1).default(1)
-}).partial();
-const LoggingConfigSchema = z.object({
-	level: z.enum([
-		"debug",
-		"info",
-		"warn",
-		"error"
-	]).default("info"),
-	prettyPrint: z.boolean().optional()
-}).partial();
-const RequestLoggingConfigSchema = z.object({
-	logHeaders: z.boolean().default(true),
-	logBody: z.boolean().default(false),
-	logResponseBody: z.boolean().default(false),
-	maxBodySize: z.number().default(10 * 1024),
-	redactHeaders: z.array(z.string()).optional()
-}).partial();
-const FoundationConfigSchema = z.object({
-	serviceName: z.string().min(1, "serviceName is required"),
-	serviceVersion: z.string().default(process.env.SERVICE_VERSION || "1.0.0"),
-	environment: z.enum([
-		"development",
-		"staging",
-		"qa",
-		"production"
-	]).default(process.env.NODE_ENV || "development"),
-	features: FeaturesConfigSchema.default({}),
-	otel: OtelConfigSchema.default({}),
-	logging: LoggingConfigSchema.default({}),
-	requestLogging: RequestLoggingConfigSchema.default({})
-});
-/** Parse and validate configuration */
-function parseConfig(input) {
-	const result = FoundationConfigSchema.safeParse(input);
-	if (!result.success) {
-		const errors = result.error.errors.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
-		throw new Error(`Invalid foundation configuration:\n${errors}`);
-	}
-	return result.data;
+//#region src/features/context.ts
+const BAGGAGE_CORRELATION_KEY = "correlation.id";
+function setBaggageCorrelationId(correlationId) {
+	const currentBaggage = propagation$1.getBaggage(context$1.active());
+	const baggage = (currentBaggage ?? propagation$1.createBaggage()).setEntry(BAGGAGE_CORRELATION_KEY, { value: correlationId });
+	return propagation$1.setBaggage(context$1.active(), baggage);
 }
-/** Get default OTEL endpoint */
-function getDefaultOtelEndpoint() {
-	return process.env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_OTEL_ENDPOINT;
+function getBaggageCorrelationId() {
+	const baggage = propagation$1.getBaggage(context$1.active());
+	return baggage?.getEntry(BAGGAGE_CORRELATION_KEY)?.value;
 }
-
-//#endregion
-//#region src/features/context.ts
 /** Create a new context manager instance */
 function createContextManager() {
 	const als = new AsyncLocalStorage();
 	return {
-		getContext: () => als.getStore(),
+		getContext() {
+			const alsCtx = als.getStore();
+			if (!alsCtx) return void 0;
+			const baggageCorrelationId = getBaggageCorrelationId();
+			if (baggageCorrelationId && baggageCorrelationId !== alsCtx.correlationId) return {
+				...alsCtx,
+				correlationId: baggageCorrelationId
+			};
+			return alsCtx;
+		},
 		run(context$2, fn) {
+			if (context$2.correlationId) {
+				const otelCtx = setBaggageCorrelationId(context$2.correlationId);
+				return context$1.with(otelCtx, () => als.run(context$2, fn));
+			}
 			return als.run(context$2, fn);
 		},
 		get(key) {
+			if (key === "correlationId") return getBaggageCorrelationId() ?? als.getStore()?.correlationId;
 			return als.getStore()?.[key];
 		},
 		update(updates) {
 			const current = als.getStore();
 			if (!current) return void 0;
+			if (updates.correlationId) setBaggageCorrelationId(updates.correlationId);
 			Object.assign(current, updates);
 			return current;
+		},
+		setContextValue(key, value) {
+			const current = als.getStore();
+			if (!current) return;
+			if (!current.contextData) current.contextData = {};
+			current.contextData[key] = value;
+		},
+		getContextValue(key) {
+			return als.getStore()?.contextData?.[key];
+		},
+		getContextData() {
+			return als.getStore()?.contextData ?? {};
+		},
+		setContextData(data) {
+			const current = als.getStore();
+			if (!current) return;
+			current.contextData = {
+				...current.contextData ?? {},
+				...data
+			};
+		},
+		clearContextData() {
+			const current = als.getStore();
+			if (!current) return;
+			current.contextData = {};
 		}
 	};
 }
 
+//#endregion
+//#region src/features/redaction.ts
+/**
+* Log Redaction & PII Sanitization
+*
+* Two-layer approach:
+* - Layer A: Pino native `redact` (fast-redact) for key-based redaction on every log call.
+*   Compiled at init, near-zero runtime cost.
+* - Layer B: Deep-traverse sanitizer for value-pattern detection (JWTs, AWS keys, etc.).
+*   Only used for request/response body logging — NOT on every log call.
+*/
+const PLACEHOLDER = "[REDACTED]";
+/**
+* Key names that Pino's fast-redact will censor automatically.
+* Supports wildcards: '*.password' matches nested keys one level deep.
+*/
+const REDACT_PATHS = [
+	"password",
+	"passwd",
+	"pass",
+	"pwd",
+	"secret",
+	"secretKey",
+	"secret_key",
+	"token",
+	"accessToken",
+	"access_token",
+	"refreshToken",
+	"refresh_token",
+	"idToken",
+	"id_token",
+	"apiKey",
+	"api_key",
+	"apiSecret",
+	"api_secret",
+	"authorization",
+	"auth",
+	"credentials",
+	"privateKey",
+	"private_key",
+	"cookie",
+	"setCookie",
+	"set_cookie",
+	"creditCard",
+	"credit_card",
+	"cardNumber",
+	"card_number",
+	"ccNumber",
+	"cc_number",
+	"cvv",
+	"cvc",
+	"securityCode",
+	"security_code",
+	"accountNumber",
+	"account_number",
+	"ssn",
+	"socialSecurity",
+	"social_security",
+	"dateOfBirth",
+	"date_of_birth",
+	"dob",
+	"*.password",
+	"*.secret",
+	"*.token",
+	"*.apiKey",
+	"*.api_key",
+	"*.authorization",
+	"*.cookie",
+	"*.credentials",
+	"*.creditCard",
+	"*.cardNumber",
+	"*.cvv",
+	"*.ssn",
+	"*.privateKey",
+	"*.private_key"
+];
+/**
+* Value patterns that indicate a secret regardless of the key name.
+* Used only for body sanitization (Layer B).
+*/
+const VALUE_PATTERNS = [
+	{
+		label: "jwt",
+		pattern: /^eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+$/
+	},
+	{
+		label: "aws_access_key",
+		pattern: /(?:^|[^A-Za-z0-9])AKIA[0-9A-Z]{16}(?:$|[^A-Za-z0-9])/
+	},
+	{
+		label: "stripe_key",
+		pattern: /^[sr]k_(live|test)_[A-Za-z0-9]{10,}$/
+	},
+	{
+		label: "openai_key",
+		pattern: /^sk-[A-Za-z0-9_-]{20,}$/
+	},
+	{
+		label: "github_token",
+		pattern: /^gh[ps]_[A-Za-z0-9]{36,}$/
+	},
+	{
+		label: "pem_private_key",
+		pattern: /-----BEGIN\s+(RSA\s+|EC\s+)?PRIVATE\s+KEY-----/
+	},
+	{
+		label: "connection_string",
+		pattern: /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^:]+:[^@]+@/
+	},
+	{
+		label: "bearer_token",
+		pattern: /^Bearer\s+\S{10,}$/i
+	}
+];
+const SENSITIVE_KEYS = new Set(REDACT_PATHS.filter((p) => !p.includes("*")).map((k) => k.toLowerCase()));
+const MAX_DEPTH = 10;
+const MAX_KEYS = 200;
+function mask(value) {
+	if (typeof value !== "string" || value.length <= 8) return PLACEHOLDER;
+	return `${value.slice(0, 4)}${"*".repeat(Math.min(value.length - 8, 20))}${value.slice(-4)}`;
+}
+function isSensitiveValue(value) {
+	return VALUE_PATTERNS.some((p) => p.pattern.test(value));
+}
+function sanitizeValue(value, depth) {
+	if (depth > MAX_DEPTH) return value;
+	if (typeof value === "string" && isSensitiveValue(value)) return mask(value);
+	if (Array.isArray(value)) return value.map((item) => sanitizeValue(item, depth + 1));
+	if (value !== null && typeof value === "object") return sanitizeObject(value, depth + 1);
+	return value;
+}
+function sanitizeObject(obj, depth) {
+	if (depth > MAX_DEPTH) return obj;
+	const keys = Object.keys(obj);
+	if (keys.length > MAX_KEYS) return obj;
+	const result = {};
+	for (const key of keys) {
+		const value = obj[key];
+		if (SENSITIVE_KEYS.has(key.toLowerCase())) result[key] = typeof value === "string" ? mask(value) : PLACEHOLDER;
+		else result[key] = sanitizeValue(value, depth);
+	}
+	return result;
+}
+/**
+* Deep-traverse sanitizer for request/response bodies.
+* Checks both key names (deny-list) and value patterns (JWT, AWS keys, etc.).
+* NOT intended for every log call — use Pino native `redact` for that.
+*/
+function sanitizeBody(body) {
+	if (body === null || body === void 0) return body;
+	if (typeof body === "string") return isSensitiveValue(body) ? mask(body) : body;
+	if (typeof body !== "object") return body;
+	if (Array.isArray(body)) return body.map((item) => sanitizeValue(item, 0));
+	return sanitizeObject(body, 0);
+}
+/** Build the Pino `redact` config object for fast-redact integration */
+function buildPinoRedactConfig(additionalPaths = []) {
+	return {
+		paths: [...REDACT_PATHS, ...additionalPaths],
+		censor: PLACEHOLDER
+	};
+}
+
 //#endregion
 //#region src/features/logging.ts
 /** Create a structured logger with automatic trace context injection */
 function createLogger(options) {
-	const { serviceName, serviceVersion, environment, level, prettyPrint, contextManager } = options;
+	const { serviceName, serviceVersion, environment, level, prettyPrint, contextManager, additionalRedactPaths = [] } = options;
 	const pinoLogger = pino({
 		level,
+		redact: buildPinoRedactConfig(additionalRedactPaths),
 		base: {
 			service: serviceName,
 			version: serviceVersion,
@@ -126,11 +268,14 @@ function createLogger(options) {
 			const traceId = spanContext?.traceId || ctx?.traceId;
 			const spanId = spanContext?.spanId || ctx?.spanId;
 			const correlationId = ctx?.correlationId;
-			return {
+			const contextData = ctx?.contextData;
+			const result = {
 				trace_id: traceId,
 				span_id: spanId,
 				correlation_id: correlationId
 			};
+			if (contextData && Object.keys(contextData).length > 0) result.context = contextData;
+			return result;
 		},
 		formatters: { level: (label) => ({ level: label }) },
 		transport: prettyPrint ? {
@@ -155,12 +300,13 @@ function wrapPinoLogger(pinoLogger) {
 	};
 }
 /** Fallback logger when Pino is not available */
-function createFallbackLogger(serviceName = "unknown") {
+function createFallbackLogger(serviceName = "unknown", baseBindings = {}) {
 	const log = (level, obj, msg) => {
 		const logObj = {
 			timestamp: new Date().toISOString(),
 			level,
 			service: serviceName,
+			...baseBindings,
 			...obj,
 			msg
 		};
@@ -174,7 +320,10 @@ function createFallbackLogger(serviceName = "unknown") {
 		info: (obj, msg) => log("info", obj, msg),
 		warn: (obj, msg) => log("warn", obj, msg),
 		error: (obj, msg) => log("error", obj, msg),
-		child: () => fallback,
+		child: (bindings) => createFallbackLogger(serviceName, {
+			...baseBindings,
+			...bindings
+		}),
 		pino: null
 	};
 	return fallback;
@@ -187,84 +336,6 @@ function getGlobalLogger() {
 	return globalLogger || createFallbackLogger();
 }
 
-//#endregion
-//#region src/features/tracing.ts
-let sdk = null;
-let isInitialized$1 = false;
-/** Initialize OpenTelemetry tracing */
-function setupTracing(options) {
-	if (isInitialized$1) {
-		console.warn("[neoiq-foundation] Tracing already initialized");
-		return;
-	}
-	const { serviceName, serviceVersion, environment, endpoint = getDefaultOtelEndpoint(), autoInstrumentation = {} } = options;
-	const resource = resourceFromAttributes({
-		[ATTR_SERVICE_NAME]: serviceName,
-		[ATTR_SERVICE_VERSION]: serviceVersion,
-		"deployment.environment": environment
-	});
-	const traceExporter = new OTLPTraceExporter({ url: endpoint });
-	const instrumentationConfig = buildInstrumentationConfig(autoInstrumentation);
-	sdk = new NodeSDK({
-		resource,
-		traceExporter,
-		instrumentations: [getNodeAutoInstrumentations(instrumentationConfig)]
-	});
-	sdk.start();
-	isInitialized$1 = true;
-}
-function buildInstrumentationConfig(config) {
-	const mapping = {
-		http: "@opentelemetry/instrumentation-http",
-		fastify: "@opentelemetry/instrumentation-fastify",
-		express: "@opentelemetry/instrumentation-express",
-		mongodb: "@opentelemetry/instrumentation-mongodb",
-		pg: "@opentelemetry/instrumentation-pg",
-		mysql: "@opentelemetry/instrumentation-mysql",
-		redis: "@opentelemetry/instrumentation-redis",
-		ioredis: "@opentelemetry/instrumentation-ioredis",
-		grpc: "@opentelemetry/instrumentation-grpc",
-		fs: "@opentelemetry/instrumentation-fs",
-		dns: "@opentelemetry/instrumentation-dns"
-	};
-	const result = {};
-	for (const [key, instrumentationName] of Object.entries(mapping)) {
-		const userSetting = config[key];
-		const defaultValue = key !== "fs" && key !== "dns";
-		result[instrumentationName] = { enabled: userSetting ?? defaultValue };
-	}
-	return result;
-}
-/** Shutdown tracing gracefully */
-async function shutdownTracing() {
-	if (!sdk) return;
-	try {
-		await sdk.shutdown();
-		isInitialized$1 = false;
-		sdk = null;
-	} catch (error) {
-		console.error("[neoiq-foundation] Error shutting down tracing:", error);
-	}
-}
-function getTracer(name) {
-	return trace.getTracer(name);
-}
-function getActiveSpan() {
-	return trace.getActiveSpan();
-}
-function getTraceContext() {
-	const span = trace.getActiveSpan();
-	if (!span) return {};
-	const ctx = span.spanContext();
-	return {
-		traceId: ctx.traceId,
-		spanId: ctx.spanId
-	};
-}
-function isTracingEnabled() {
-	return isInitialized$1;
-}
-
 //#endregion
 //#region src/features/metrics.ts
 let meterProvider = null;
@@ -302,6 +373,7 @@ async function shutdownMetrics() {
 		meterProvider = null;
 	} catch (error) {
 		console.error("[neoiq-foundation] Error shutting down metrics:", error);
+		throw error;
 	}
 }
 function getMeter(name, version = "1.0.0") {
@@ -353,7 +425,6 @@ function createObservabilityPlugin(options) {
 		const maxBodySize = requestLogging.maxBodySize ?? 10 * 1024;
 		const headersToRedact = requestLogging.redactHeaders ?? DEFAULT_REDACT_HEADERS;
 		const runInContext = contextManager ? (ctx, fn) => contextManager.run(ctx, fn) : (_ctx, fn) => fn();
-		const tracer = tracingEnabled ? trace$1.getTracer("neoiq-foundation-node") : null;
 		let requestCounter;
 		let requestDuration;
 		let requestErrors;
@@ -370,22 +441,12 @@ function createObservabilityPlugin(options) {
 			}
 			const correlationId = request.headers["x-request-id"] || randomUUID();
 			reply.header("x-request-id", correlationId);
-			let span;
 			let traceId = "";
 			let spanId = "";
-			if (tracer) {
-				const parentContext = propagation$1.extract(context$1.active(), request.headers);
-				span = tracer.startSpan(`${request.method} ${request.routeOptions?.url || request.url}`, {
-					kind: 1,
-					attributes: {
-						"http.method": request.method,
-						"http.url": request.url,
-						"http.route": request.routeOptions?.url || request.url,
-						"http.user_agent": request.headers["user-agent"] || "",
-						"http.correlation_id": correlationId
-					}
-				}, parentContext);
-				const spanContext = span.spanContext();
+			const activeSpan = tracingEnabled ? trace$1.getActiveSpan() : void 0;
+			if (activeSpan) {
+				activeSpan.setAttribute("http.correlation_id", correlationId);
+				const spanContext = activeSpan.spanContext();
 				traceId = spanContext.traceId;
 				spanId = spanContext.spanId;
 			}
@@ -395,7 +456,6 @@ function createObservabilityPlugin(options) {
 				spanId,
 				startTime: Date.now()
 			};
-			request.__span = span;
 			request.__requestContext = requestContext;
 			runInContext(requestContext, () => {
 				const logData = {
@@ -421,7 +481,7 @@ function createObservabilityPlugin(options) {
 			runInContext(ctx, () => {
 				logger.debug({
 					correlation_id: ctx.correlationId,
-					body: truncateBody(request.body, maxBodySize)
+					body: sanitizeBody(truncateBody(request.body, maxBodySize))
 				}, "Request body");
 				done();
 			});
@@ -436,14 +496,13 @@ function createObservabilityPlugin(options) {
 				logger.debug({
 					correlation_id: ctx.correlationId,
 					statusCode: reply.statusCode,
-					body: truncateBody(payload, maxBodySize)
+					body: sanitizeBody(truncateBody(payload, maxBodySize))
 				}, "Response body");
 				done(null, payload);
 			});
 		});
 		fastify.addHook("onResponse", (request, reply, done) => {
 			const ctx = request.__requestContext;
-			const span = request.__span;
 			if (!ctx) {
 				done();
 				return;
@@ -467,18 +526,15 @@ function createObservabilityPlugin(options) {
 					requestDuration.record(durationMs, labels);
 					if (reply.statusCode >= 400) requestErrors.add(1, labels);
 				}
-				if (span) {
-					span.setStatus({ code: reply.statusCode < 400 ? SpanStatusCode$1.OK : SpanStatusCode$1.ERROR });
-					span.setAttribute("http.status_code", reply.statusCode);
-					span.setAttribute("http.response_time_ms", durationMs);
-					span.end();
+				if (tracingEnabled) {
+					const activeSpan = trace$1.getActiveSpan();
+					if (activeSpan) activeSpan.setAttribute("http.response_time_ms", durationMs);
 				}
 				done();
 			});
 		});
 		fastify.addHook("onError", (request, _reply, error, done) => {
 			const ctx = request.__requestContext;
-			const span = request.__span;
 			if (!ctx) {
 				done();
 				return;
@@ -490,12 +546,15 @@ function createObservabilityPlugin(options) {
 					url: request.url,
 					error: error.message
 				}, "Request failed");
-				if (span) {
-					span.setStatus({
-						code: SpanStatusCode$1.ERROR,
-						message: error.message
-					});
-					span.recordException(error);
+				if (tracingEnabled) {
+					const activeSpan = trace$1.getActiveSpan();
+					if (activeSpan) {
+						activeSpan.setStatus({
+							code: SpanStatusCode$1.ERROR,
+							message: error.message
+						});
+						activeSpan.recordException(error);
+					}
 				}
 				done();
 			});
@@ -592,31 +651,34 @@ function createHttpClient(options) {
 		}
 		return Promise.reject(error);
 	});
-	const retryConfig = {
-		retries: retry.retries ?? 3,
-		retryDelay: (retryCount) => (retry.retryDelay ?? 1e3) * Math.pow(2, retryCount - 1),
-		retryCondition: (error) => {
-			const retryStatusCodes = retry.retryStatusCodes ?? [
-				408,
-				429,
-				500,
-				502,
-				503,
-				504
-			];
-			return !error.response || retryStatusCodes.includes(error.response?.status || 0);
-		},
-		onRetry: (retryCount, error, requestConfig) => {
-			logger.warn({
-				retryCount,
-				url: `${requestConfig.baseURL || ""}${requestConfig.url}`,
-				error: error.message
-			}, "Retrying request");
-		}
-	};
-	axiosRetry(client, retryConfig);
-	if (cbOptions.enabled !== false) {
-		const breaker = new CircuitBreaker(async (config) => client.request(config), {
+	if (retry.enabled !== false) {
+		const retryConfig = {
+			retries: retry.retries ?? 3,
+			retryDelay: (retryCount) => (retry.retryDelay ?? 1e3) * Math.pow(2, retryCount - 1),
+			retryCondition: (error) => {
+				const retryStatusCodes = retry.retryStatusCodes ?? [
+					408,
+					429,
+					500,
+					502,
+					503,
+					504
+				];
+				return !error.response || retryStatusCodes.includes(error.response?.status || 0);
+			},
+			onRetry: (retryCount, error, requestConfig) => {
+				logger.warn({
+					retryCount,
+					url: `${requestConfig.baseURL || ""}${requestConfig.url}`,
+					error: error.message
+				}, "Retrying request");
+			}
+		};
+		axiosRetry(client, retryConfig);
+	}
+	if (cbOptions.enabled === true) {
+		const originalRequest = client.request.bind(client);
+		const breaker = new CircuitBreaker(async (config) => originalRequest(config), {
 			timeout,
 			resetTimeout: cbOptions.resetTimeout ?? 3e4,
 			errorThresholdPercentage: cbOptions.errorThresholdPercentage ?? 50,
@@ -625,17 +687,58 @@ function createHttpClient(options) {
 		breaker.on("open", () => logger.warn({ targetService: serviceName }, "Circuit breaker OPEN"));
 		breaker.on("halfOpen", () => logger.info({ targetService: serviceName }, "Circuit breaker HALF-OPEN"));
 		breaker.on("close", () => logger.info({ targetService: serviceName }, "Circuit breaker CLOSED"));
+		client.request = (config) => breaker.fire(config);
+		client.get = (url, config) => breaker.fire({
+			...config,
+			method: "GET",
+			url
+		});
+		client.post = (url, data, config) => breaker.fire({
+			...config,
+			method: "POST",
+			url,
+			data
+		});
+		client.put = (url, data, config) => breaker.fire({
+			...config,
+			method: "PUT",
+			url,
+			data
+		});
+		client.delete = (url, config) => breaker.fire({
+			...config,
+			method: "DELETE",
+			url
+		});
+		client.patch = (url, data, config) => breaker.fire({
+			...config,
+			method: "PATCH",
+			url,
+			data
+		});
+		client.__originalRequest = originalRequest;
 	}
 	return client;
 }
 
 //#endregion
 //#region src/foundation.ts
+const deprecationWarnings = new Set();
+function warnDeprecation(oldPath, newPath, logger) {
+	if (deprecationWarnings.has(oldPath)) return;
+	deprecationWarnings.add(oldPath);
+	const msg = `foundation.${oldPath}() is deprecated. Use foundation.${newPath}() instead. This alias will be removed in the next major version.`;
+	if (logger) logger.warn({
+		deprecated: oldPath,
+		replacement: newPath
+	}, msg);
+	else console.warn(`[neoiq-foundation] DEPRECATED: ${msg}`);
+}
 /** Create a fully configured observability foundation */
 function createFoundation(input) {
 	const startTime = Date.now();
 	const config = parseConfig(input);
-	const { serviceName, serviceVersion, environment, features: featuresConfig, otel, logging: loggingConfig, requestLogging: requestLoggingConfig } = config;
+	const { serviceName, serviceVersion, environment, features: featuresConfig, otel, logging: loggingConfig, requestLogging: requestLoggingConfig, redaction: redactionConfig, shutdown: shutdownConfig } = config;
 	const features = {
 		tracing: featuresConfig.tracing ?? true,
 		metrics: featuresConfig.metrics ?? true,
@@ -651,7 +754,8 @@ function createFoundation(input) {
 			environment,
 			level: loggingConfig.level ?? "info",
 			prettyPrint: loggingConfig.prettyPrint ?? environment === "development",
-			contextManager
+			contextManager,
+			additionalRedactPaths: redactionConfig.additionalPaths
 		});
 		setGlobalLogger(logger);
 	} catch (err) {
@@ -723,17 +827,139 @@ function createFoundation(input) {
 		environment,
 		features
 	}, "Foundation initialized");
-	const foundation = {
-		config,
+	if (shutdownConfig.flushOnCrash) {
+		const flushTimeoutMs = shutdownConfig.flushTimeoutMs ?? 5e3;
+		const crashFlush = (origin, err) => {
+			const error = err instanceof Error ? err : new Error(String(err));
+			logger.error({
+				error: error.message,
+				stack: error.stack,
+				origin
+			}, "Process crash detected, flushing telemetry");
+			const flushPromises = [];
+			if (features.tracing && isTracingEnabled()) flushPromises.push(shutdownTracing());
+			if (features.metrics && isMetricsEnabled()) flushPromises.push(shutdownMetrics());
+			const timeout = new Promise((resolve) => setTimeout(resolve, flushTimeoutMs));
+			Promise.race([Promise.allSettled(flushPromises), timeout]).finally(() => {
+				process.exit(1);
+			});
+		};
+		process.on("uncaughtException", (err) => crashFlush("uncaughtException", err));
+		process.on("unhandledRejection", (reason) => crashFlush("unhandledRejection", reason));
+		logger.info({ flushTimeoutMs }, "Crash-flush handlers registered");
+	}
+	const traceInSpan = async (name, fn) => {
+		const tracer = tracerInstance || getTracer(serviceName);
+		return new Promise((resolve, reject) => {
+			tracer.startActiveSpan(name, async (span) => {
+				try {
+					const result = await fn();
+					span.setStatus({ code: SpanStatusCode.OK });
+					span.end();
+					resolve(result);
+				} catch (err) {
+					const error = err;
+					span.setStatus({
+						code: SpanStatusCode.ERROR,
+						message: error.message
+					});
+					span.recordException(error);
+					span.end();
+					logger.error({
+						span: name,
+						error: error.message
+					}, "Span failed");
+					reject(error);
+				}
+			});
+		});
+	};
+	const observability = {
 		logger,
-		context: contextManager,
 		tracer: tracerInstance,
 		meter: meterInstance,
-		features,
 		getTracer: (name) => getTracer(name || serviceName),
 		getMeter: (name, version) => getMeter(name, version),
 		getTraceContext,
 		getActiveSpan,
+		trace: traceInSpan
+	};
+	const httpModule = { createClient: (options) => createHttpClient({
+		...options,
+		foundation
+	}) };
+	const buildHealthStatus = () => {
+		const tracingUp = !features.tracing || !tracingError && isTracingEnabled();
+		const metricsUp = !features.metrics || !metricsError && isMetricsEnabled();
+		const loggingUp = !loggingError;
+		const allUp = tracingUp && metricsUp && loggingUp;
+		const allDown = (!tracingUp || !features.tracing) && (!metricsUp || !features.metrics) && !loggingUp;
+		let status = "healthy";
+		if (!allUp) status = allDown ? "unhealthy" : "degraded";
+		return {
+			status,
+			timestamp: new Date().toISOString(),
+			service: serviceName,
+			version: serviceVersion,
+			uptime: Math.floor((Date.now() - startTime) / 1e3),
+			components: {
+				tracing: {
+					enabled: features.tracing,
+					status: !features.tracing ? "disabled" : tracingError ? "down" : "up",
+					message: tracingError
+				},
+				metrics: {
+					enabled: features.metrics,
+					status: !features.metrics ? "disabled" : metricsError ? "down" : "up",
+					message: metricsError
+				},
+				logging: {
+					enabled: features.logging,
+					status: loggingError ? "down" : "up",
+					message: loggingError
+				}
+			}
+		};
+	};
+	const shutdownFn = async () => {
+		logger.info({}, "Shutting down foundation...");
+		const promises = [];
+		if (features.tracing && isTracingEnabled()) promises.push(shutdownTracing());
+		if (features.metrics && isMetricsEnabled()) promises.push(shutdownMetrics());
+		await Promise.all(promises);
+		logger.info({}, "Foundation shutdown complete");
+	};
+	const isReadyFn = () => {
+		if (features.tracing && !tracingError && !isTracingEnabled()) return false;
+		if (features.metrics && !metricsError && !isMetricsEnabled()) return false;
+		return true;
+	};
+	const safeRunFn = async (fn, fallback) => {
+		try {
+			return await fn();
+		} catch (err) {
+			const error = err;
+			logger.error({
+				error: error.message,
+				stack: error.stack
+			}, "safeRun caught error");
+			return fallback;
+		}
+	};
+	const lifecycle = {
+		health: buildHealthStatus,
+		isReady: isReadyFn,
+		shutdown: shutdownFn,
+		safeRun: safeRunFn
+	};
+	const foundation = {
+		config,
+		features,
+		observability,
+		http: httpModule,
+		lifecycle,
+		logger,
+		context: contextManager,
 		fastifyPlugin: createObservabilityPlugin({
 			serviceName,
 			logger,
@@ -742,91 +968,47 @@ function createFoundation(input) {
 			metricsEnabled: features.metrics && !metricsError,
 			requestLogging: requestLoggingConfig
 		}),
-		createHttpClient: (options) => createHttpClient({
-			...options,
-			foundation
-		}),
-		shutdown: async () => {
-			logger.info({}, "Shutting down foundation...");
-			const promises = [];
-			if (features.tracing && isTracingEnabled()) promises.push(shutdownTracing());
-			if (features.metrics && isMetricsEnabled()) promises.push(shutdownMetrics());
-			await Promise.all(promises);
-			logger.info({}, "Foundation shutdown complete");
+		tracer: tracerInstance,
+		meter: meterInstance,
+		getTracer: (name) => {
+			warnDeprecation("getTracer", "observability.getTracer", logger);
+			return observability.getTracer(name);
+		},
+		getMeter: (name, version) => {
+			warnDeprecation("getMeter", "observability.getMeter", logger);
+			return observability.getMeter(name, version);
+		},
+		getTraceContext: () => {
+			warnDeprecation("getTraceContext", "observability.getTraceContext", logger);
+			return observability.getTraceContext();
+		},
+		getActiveSpan: () => {
+			warnDeprecation("getActiveSpan", "observability.getActiveSpan", logger);
+			return observability.getActiveSpan();
+		},
+		createHttpClient: (options) => {
+			warnDeprecation("createHttpClient", "http.createClient", logger);
+			return httpModule.createClient(options);
+		},
+		shutdown: () => {
+			warnDeprecation("shutdown", "lifecycle.shutdown", logger);
+			return lifecycle.shutdown();
 		},
 		isReady: () => {
-			if (features.tracing && !tracingError && !isTracingEnabled()) return false;
-			if (features.metrics && !metricsError && !isMetricsEnabled()) return false;
-			return true;
+			warnDeprecation("isReady", "lifecycle.isReady", logger);
+			return lifecycle.isReady();
 		},
 		health: () => {
-			const tracingUp = !features.tracing || !tracingError && isTracingEnabled();
-			const metricsUp = !features.metrics || !metricsError && isMetricsEnabled();
-			const loggingUp = !loggingError;
-			const allUp = tracingUp && metricsUp && loggingUp;
-			const anyDown = features.tracing && tracingError || features.metrics && metricsError || loggingError;
-			return {
-				status: allUp ? "healthy" : anyDown ? "degraded" : "unhealthy",
-				timestamp: new Date().toISOString(),
-				service: serviceName,
-				version: serviceVersion,
-				uptime: Math.floor((Date.now() - startTime) / 1e3),
-				components: {
-					tracing: {
-						enabled: features.tracing,
-						status: !features.tracing ? "disabled" : tracingError ? "down" : "up",
-						message: tracingError
-					},
-					metrics: {
-						enabled: features.metrics,
-						status: !features.metrics ? "disabled" : metricsError ? "down" : "up",
-						message: metricsError
-					},
-					logging: {
-						enabled: features.logging,
-						status: loggingError ? "down" : "up",
-						message: loggingError
-					}
-				}
-			};
+			warnDeprecation("health", "lifecycle.health", logger);
+			return lifecycle.health();
 		},
-		trace: async (name, fn) => {
-			const tracer = tracerInstance || getTracer(serviceName);
-			return new Promise((resolve, reject) => {
-				tracer.startActiveSpan(name, async (span) => {
-					try {
-						const result = await fn();
-						span.setStatus({ code: SpanStatusCode.OK });
-						span.end();
-						resolve(result);
-					} catch (err) {
-						const error = err;
-						span.setStatus({
-							code: SpanStatusCode.ERROR,
-							message: error.message
-						});
-						span.recordException(error);
-						span.end();
-						logger.error({
-							span: name,
-							error: error.message
-						}, "Span failed");
-						reject(error);
-					}
-				});
-			});
+		trace: (name, fn) => {
+			warnDeprecation("trace", "observability.trace", logger);
+			return observability.trace(name, fn);
 		},
-		safeRun: async (fn, fallback) => {
-			try {
-				return await fn();
-			} catch (err) {
-				const error = err;
-				logger.error({
-					error: error.message,
-					stack: error.stack
-				}, "safeRun caught error");
-				return fallback;
-			}
+		safeRun: (fn, fallback) => {
+			warnDeprecation("safeRun", "lifecycle.safeRun", logger);
+			return lifecycle.safeRun(fn, fallback);
 		}
 	};
 	return foundation;
@@ -835,5 +1017,289 @@ function createFoundation(input) {
 const setupObservability = createFoundation;
 
 //#endregion
-export { AutoInstrumentationConfigSchema, FeaturesConfigSchema, FoundationConfigSchema, LoggingConfigSchema, OtelConfigSchema, RequestLoggingConfigSchema, SpanStatusCode, context, createContextManager, createFallbackLogger, createFoundation, createHttpClient, createLogger, createObservabilityPlugin, getActiveSpan, getDefaultOtelEndpoint, getGlobalLogger, getMeter, getTraceContext, getTracer, isMetricsEnabled, isTracingEnabled, metrics, parseConfig, propagation, setGlobalLogger, setupMetrics, setupObservability, setupTracing, shutdownMetrics, shutdownTracing, trace };
+//#region src/integrations/object-store/aws-s3.ts
+function isAwsError(err) {
+	return typeof err === "object" && err !== null;
+}
+async function loadAwsS3() {
+	try {
+		const clientMod = await import("@aws-sdk/client-s3");
+		const presignerMod = await import("@aws-sdk/s3-request-presigner");
+		return {
+			S3Client: clientMod.S3Client,
+			PutObjectCommand: clientMod.PutObjectCommand,
+			GetObjectCommand: clientMod.GetObjectCommand,
+			HeadObjectCommand: clientMod.HeadObjectCommand,
+			DeleteObjectCommand: clientMod.DeleteObjectCommand,
+			ListObjectsV2Command: clientMod.ListObjectsV2Command,
+			getSignedUrl: presignerMod.getSignedUrl
+		};
+	} catch (err) {
+		const e = err instanceof Error ? err : new Error(String(err));
+		throw new Error(`AWS SDK not available. Install optional peer deps: @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner. Original error: ${e.message}`);
+	}
+}
+/**
+* AwsS3ObjectStore - wraps AWS S3 behind the provider-agnostic `ObjectStore` interface.
+*
+* This implementation uses dynamic imports so `neoiq-foundation-node` can be used without AWS SDK.
+*/
+var AwsS3ObjectStore = class {
+	provider = "aws-s3";
+	clientPromise;
+	awsPromise = loadAwsS3();
+	constructor(options = {}) {
+		if (options.client) {
+			this.clientPromise = Promise.resolve(options.client);
+			return;
+		}
+		this.clientPromise = (async () => {
+			const aws = await this.awsPromise;
+			return new aws.S3Client(options.clientOptions ?? {});
+		})();
+	}
+	async client() {
+		return this.clientPromise;
+	}
+	async putObject(ref, body, options = {}) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		const res = await s3.send(new aws.PutObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key,
+			Body: body,
+			ContentType: options.contentType,
+			CacheControl: options.cacheControl,
+			Metadata: options.metadata
+		}));
+		return {
+			etag: res?.ETag,
+			versionId: res?.VersionId
+		};
+	}
+	async getObject(ref) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		const res = await s3.send(new aws.GetObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key
+		}));
+		if (!res?.Body) {
+			const err = new Error(`S3 GetObject returned empty body: ${ref.bucket}/${ref.key}`);
+			err.code = "EMPTY_BODY";
+			throw err;
+		}
+		return {
+			body: res.Body,
+			contentType: res.ContentType,
+			contentLength: res.ContentLength,
+			etag: res.ETag,
+			versionId: res.VersionId,
+			metadata: res.Metadata,
+			lastModified: res.LastModified
+		};
+	}
+	async headObject(ref) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		try {
+			const res = await s3.send(new aws.HeadObjectCommand({
+				Bucket: ref.bucket,
+				Key: ref.key
+			}));
+			return {
+				exists: true,
+				contentType: res.ContentType,
+				contentLength: res.ContentLength,
+				etag: res.ETag,
+				versionId: res.VersionId,
+				metadata: res.Metadata,
+				lastModified: res.LastModified
+			};
+		} catch (err) {
+			if (isAwsError(err)) {
+				const name = String(err.name ?? "");
+				const httpStatus = err.$metadata?.httpStatusCode;
+				if (httpStatus === 404 || name.includes("NotFound") || name.includes("NoSuchKey")) return { exists: false };
+			}
+			throw err;
+		}
+	}
+	async deleteObject(ref) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		await s3.send(new aws.DeleteObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key
+		}));
+	}
+	async listObjects(options) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		const res = await s3.send(new aws.ListObjectsV2Command({
+			Bucket: options.bucket,
+			Prefix: options.prefix,
+			ContinuationToken: options.continuationToken,
+			MaxKeys: options.maxKeys
+		}));
+		const contents = res?.Contents ?? [];
+		return {
+			objects: contents.filter((o) => typeof o.Key === "string").map((o) => ({
+				key: o.Key,
+				size: o.Size,
+				etag: o.ETag,
+				lastModified: o.LastModified
+			})),
+			nextContinuationToken: res?.NextContinuationToken
+		};
+	}
+	async presignGetObject(ref, options) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		return aws.getSignedUrl(s3, new aws.GetObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key,
+			ResponseContentType: options.responseContentType
+		}), { expiresIn: options.expiresInSeconds });
+	}
+	async presignPutObject(ref, options) {
+		const aws = await this.awsPromise;
+		const s3 = await this.client();
+		return aws.getSignedUrl(s3, new aws.PutObjectCommand({
+			Bucket: ref.bucket,
+			Key: ref.key,
+			ContentType: options.contentType
+		}), { expiresIn: options.expiresInSeconds });
+	}
+};
+
+//#endregion
+//#region src/integrations/object-store/in-memory.ts
+const DEFAULT_MAX_OBJECTS = 1e4;
+const STREAM_TIMEOUT_MS = 3e4;
+function toBuffer(body) {
+	if (typeof body === "string") return Buffer.from(body);
+	if (Buffer.isBuffer(body)) return body;
+	if (body instanceof Uint8Array) return Buffer.from(body);
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		const timer = setTimeout(() => {
+			body.destroy(new Error("InMemoryObjectStore: stream read timed out"));
+			reject(new Error("InMemoryObjectStore: stream read timed out"));
+		}, STREAM_TIMEOUT_MS);
+		body.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+		body.on("end", () => {
+			clearTimeout(timer);
+			resolve(Buffer.concat(chunks));
+		});
+		body.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+function computeEtag(buf) {
+	return `"${createHash("md5").update(buf).digest("hex")}"`;
+}
+/**
+* InMemoryObjectStore - useful for local dev, unit tests, and as a safe default.
+* NOTE: presign* methods are not meaningful here and will throw.
+*/
+var InMemoryObjectStore = class {
+	provider = "in-memory";
+	buckets = new Map();
+	maxObjects;
+	objectCount = 0;
+	constructor(options = {}) {
+		this.maxObjects = options.maxObjects ?? DEFAULT_MAX_OBJECTS;
+	}
+	bucketMap(bucket) {
+		let m = this.buckets.get(bucket);
+		if (!m) {
+			m = new Map();
+			this.buckets.set(bucket, m);
+		}
+		return m;
+	}
+	async putObject(ref, body, options = {}) {
+		const map = this.bucketMap(ref.bucket);
+		const isNew = !map.has(ref.key);
+		if (isNew && this.objectCount >= this.maxObjects) throw new Error(`InMemoryObjectStore: max object limit reached (${this.maxObjects})`);
+		const buf = await toBuffer(body);
+		const obj = {
+			body: buf,
+			contentType: options.contentType,
+			cacheControl: options.cacheControl,
+			metadata: options.metadata,
+			etag: computeEtag(buf),
+			lastModified: new Date()
+		};
+		map.set(ref.key, obj);
+		if (isNew) this.objectCount++;
+		return { etag: obj.etag };
+	}
+	async getObject(ref) {
+		const obj = this.bucketMap(ref.bucket).get(ref.key);
+		if (!obj) {
+			const err = new Error(`Object not found: ${ref.bucket}/${ref.key}`);
+			err.code = "OBJECT_NOT_FOUND";
+			throw err;
+		}
+		return {
+			body: Readable.from(obj.body),
+			contentType: obj.contentType,
+			contentLength: obj.body.length,
+			etag: obj.etag,
+			metadata: obj.metadata,
+			lastModified: obj.lastModified
+		};
+	}
+	async headObject(ref) {
+		const obj = this.bucketMap(ref.bucket).get(ref.key);
+		if (!obj) return { exists: false };
+		return {
+			exists: true,
+			contentType: obj.contentType,
+			contentLength: obj.body.length,
+			etag: obj.etag,
+			metadata: obj.metadata,
+			lastModified: obj.lastModified
+		};
+	}
+	async deleteObject(ref) {
+		const map = this.bucketMap(ref.bucket);
+		if (map.delete(ref.key)) this.objectCount--;
+	}
+	async listObjects(options) {
+		const { bucket, prefix = "", continuationToken, maxKeys = 1e3 } = options;
+		const map = this.bucketMap(bucket);
+		const all = [...map.entries()].filter(([key]) => key.startsWith(prefix)).map(([key, obj]) => ({
+			key,
+			size: obj.body.length,
+			etag: obj.etag,
+			lastModified: obj.lastModified
+		})).sort((a, b) => a.key.localeCompare(b.key));
+		let startIndex = 0;
+		if (continuationToken) {
+			const idx = all.findIndex((o) => o.key === continuationToken);
+			if (idx === -1) throw new Error(`InMemoryObjectStore: invalid continuationToken "${continuationToken}"`);
+			startIndex = idx + 1;
+		}
+		const page = all.slice(startIndex, startIndex + maxKeys);
+		const hasMore = startIndex + maxKeys < all.length;
+		return {
+			objects: page,
+			nextContinuationToken: hasMore ? page[page.length - 1]?.key : void 0
+		};
+	}
+	async presignGetObject(_ref, _options) {
+		throw new Error("InMemoryObjectStore does not support presigned URLs");
+	}
+	async presignPutObject(_ref, _options) {
+		throw new Error("InMemoryObjectStore does not support presigned URLs");
+	}
+};
+
+//#endregion
+export { AutoInstrumentationConfigSchema, AwsS3ObjectStore, FeaturesConfigSchema, FoundationConfigSchema, InMemoryObjectStore, LoggingConfigSchema, OtelConfigSchema, REDACT_PATHS, RedactionConfigSchema, RequestLoggingConfigSchema, ShutdownConfigSchema, SpanStatusCode, buildPinoRedactConfig, context, createContextManager, createFallbackLogger, createFoundation, createHttpClient, createLogger, createObservabilityPlugin, getActiveSpan, getDefaultOtelEndpoint, getGlobalLogger, getMeter, getTraceContext, getTracer, isMetricsEnabled, isTracingEnabled, metrics, parseConfig, propagation, sanitizeBody, setGlobalLogger, setupMetrics, setupObservability, setupTracing, shutdownMetrics, shutdownTracing, trace };
 //# sourceMappingURL=index.mjs.map