@foam-ai/node 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/redaction.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setActiveRedactionConfig = setActiveRedactionConfig;
+exports.getActiveRedactionConfig = getActiveRedactionConfig;
+exports.normalizeKey = normalizeKey;
+exports.isFloorKey = isFloorKey;
+exports.isSensitiveQueryKey = isSensitiveQueryKey;
+exports.keyMatch = keyMatch;
+exports.tailMask = tailMask;
+exports.maskForMatch = maskForMatch;
+exports.redactQueryPairs = redactQueryPairs;
+exports.redactUrlLike = redactUrlLike;
+exports.redactString = redactString;
+exports.redactDeep = redactDeep;
+exports.redactAttributeValue = redactAttributeValue;
+exports.redactAttributesCopy = redactAttributesCopy;
+exports.resolveRedactionConfig = resolveRedactionConfig;
+const constants_js_1 = require("./constants.js");
+const redaction_keys_js_1 = require("./redaction-keys.js");
+const EMPTY_CONFIG = {
+    secretKeys: new Set(),
+    piiKeys: new Set(),
+};
+const FLOOR_KEYS = new Set(redaction_keys_js_1.SENSITIVE_KEYS);
+const HTTP_HEADERS = new Set(redaction_keys_js_1.SENSITIVE_HTTP_HEADERS);
+const QUERY_KEYS = new Set(redaction_keys_js_1.SENSITIVE_QUERY_KEYS);
+const HEADER_PREFIXES = ["http.request.header.", "http.response.header."];
+const BARE_QUERY_KEYS = new Set(["url.query"]);
+const BODY_KEYS = new Set([
+    "http.request.body.content",
+    "http.response.body.content",
+]);
+const MAX_DEPTH = 10;
+const QUERY_PAIR_CAP = 256;
+let activeConfig = EMPTY_CONFIG;
+function setActiveRedactionConfig(config) {
+    activeConfig = config;
+}
+function getActiveRedactionConfig() {
+    return activeConfig;
+}
+function normalizeKey(key) {
+    return key
+        .trim()
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/-/g, "_")
+        .toLowerCase();
+}
+function isFloorKey(key) {
+    return FLOOR_KEYS.has(normalizeKey(key));
+}
+function isSensitiveHeader(key) {
+    return HTTP_HEADERS.has(normalizeKey(key));
+}
+function isSensitiveQueryKey(key) {
+    const normalized = normalizeKey(key);
+    return FLOOR_KEYS.has(normalized) || QUERY_KEYS.has(normalized);
+}
+function keyMatch(key, config = activeConfig) {
+    const normalized = normalizeKey(key);
+    if (FLOOR_KEYS.has(normalized))
+        return "floor";
+    if (config.piiKeys.has(normalized))
+        return "pii";
+    if (config.secretKeys.has(normalized))
+        return "secret";
+    return undefined;
+}
+function tailMask(value) {
+    if (value === constants_js_1.REDACTED_VALUE)
+        return constants_js_1.REDACTED_VALUE;
+    if (typeof value === "string" || typeof value === "number") {
+        const text = String(value);
+        if (text.length >= constants_js_1.TAIL_MASK_THRESHOLD)
+            return constants_js_1.FULL_MASK + text.slice(-4);
+    }
+    return constants_js_1.FULL_MASK;
+}
+function maskForMatch(kind, value) {
+    return kind === "secret" ? tailMask(value) : constants_js_1.REDACTED_VALUE;
+}
+function decodeKey(value) {
+    try {
+        return decodeURIComponent(value.replace(/\+/g, " "));
+    }
+    catch {
+        return value;
+    }
+}
+function redactPair(pair, config) {
+    const separator = pair.indexOf("=");
+    if (separator < 0)
+        return pair;
+    const key = decodeKey(pair.slice(0, separator));
+    if (keyMatch(key, config) || isSensitiveQueryKey(key)) {
+        return `${pair.slice(0, separator)}=${constants_js_1.REDACTED_VALUE}`;
+    }
+    return pair;
+}
+function redactQueryPairs(query, config = activeConfig) {
+    const result = [];
+    let start = 0;
+    let count = 0;
+    while (start <= query.length) {
+        if (count >= QUERY_PAIR_CAP) {
+            result.push(constants_js_1.REDACTED_VALUE);
+            break;
+        }
+        const next = query.indexOf("&", start);
+        result.push(redactPair(next < 0 ? query.slice(start) : query.slice(start, next), config));
+        count += 1;
+        if (next < 0)
+            break;
+        start = next + 1;
+    }
+    return result.join("&");
+}
+function redactSegment(segment, config) {
+    return segment.includes("=") ? redactQueryPairs(segment, config) : segment;
+}
+function redactUrlLike(text, config = activeConfig) {
+    const hash = text.indexOf("#");
+    const head = hash < 0 ? text : text.slice(0, hash);
+    const fragment = hash < 0 ? undefined : text.slice(hash + 1);
+    const query = head.indexOf("?");
+    const redactedHead = query < 0
+        ? redactSegment(head, config)
+        : `${head.slice(0, query + 1)}${redactQueryPairs(head.slice(query + 1), config)}`;
+    if (fragment === undefined)
+        return redactedHead;
+    const fragmentQuery = fragment.indexOf("?");
+    const redactedFragment = fragmentQuery < 0
+        ? redactSegment(fragment, config)
+        : `${redactSegment(fragment.slice(0, fragmentQuery), config)}?${redactQueryPairs(fragment.slice(fragmentQuery + 1), config)}`;
+    return `${redactedHead}#${redactedFragment}`;
+}
+function redactString(text, config = activeConfig) {
+    return text.includes("=") ? redactUrlLike(text, config) : text;
+}
+function redactNode(value, config, depth, ancestors) {
+    if (depth > MAX_DEPTH)
+        return constants_js_1.FULL_MASK;
+    if (typeof value === "string")
+        return redactString(value, config);
+    if (value === null ||
+        value === undefined ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value !== "object")
+        return constants_js_1.FULL_MASK;
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer)
+        return value;
+    if (ancestors.has(value))
+        return constants_js_1.FULL_MASK;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => redactNode(item, config, depth + 1, ancestors));
+        }
+        const result = {};
+        for (const [key, item] of Object.entries(value)) {
+            const match = keyMatch(key, config);
+            result[key] = match
+                ? maskForMatch(match, item)
+                : redactNode(item, config, depth + 1, ancestors);
+        }
+        return result;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function redactDeep(value, config = activeConfig) {
+    try {
+        return redactNode(value, config, 0, new Set());
+    }
+    catch {
+        return constants_js_1.FULL_MASK;
+    }
+}
+function headerSuffix(key) {
+    const lower = key.toLowerCase();
+    for (const prefix of HEADER_PREFIXES) {
+        if (lower.startsWith(prefix) && key.length > prefix.length) {
+            return key.slice(prefix.length);
+        }
+    }
+    return undefined;
+}
+function maskElements(kind, value) {
+    return Array.isArray(value)
+        ? value.map((item) => maskForMatch(kind, item))
+        : maskForMatch(kind, value);
+}
+function redactAttributeValue(key, value, config = activeConfig) {
+    try {
+        const match = keyMatch(key, config);
+        if (match)
+            return maskElements(match, value);
+        const header = headerSuffix(key);
+        if (header) {
+            const headerMatch = keyMatch(header, config);
+            if (headerMatch)
+                return maskElements(headerMatch, value);
+            if (isSensitiveHeader(header))
+                return maskElements("floor", value);
+        }
+        if (BARE_QUERY_KEYS.has(key.toLowerCase()) && typeof value === "string") {
+            return redactQueryPairs(value, config);
+        }
+        if (BODY_KEYS.has(key))
+            return value;
+        if (typeof value === "string")
+            return redactString(value, config);
+        if (Array.isArray(value) ||
+            (value !== null && typeof value === "object" && !ArrayBuffer.isView(value))) {
+            return redactDeep(value, config);
+        }
+        if (value === null ||
+            value === undefined ||
+            typeof value === "number" ||
+            typeof value === "boolean" ||
+            ArrayBuffer.isView(value)) {
+            return value;
+        }
+        return constants_js_1.FULL_MASK;
+    }
+    catch {
+        return constants_js_1.FULL_MASK;
+    }
+}
+function redactAttributesCopy(attributes, config = activeConfig) {
+    const result = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        result[key] = redactAttributeValue(key, value, config);
+    }
+    return result;
+}
+const REDACT_FIELDS = ["secrets", "pii"];
+function keyList(field, value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        throw new TypeError(`[foam] redact.${field} must be an array of strings`);
+    }
+    return value;
+}
+function resolveRedactionConfig(redact) {
+    if (redact === undefined || redact === null)
+        return EMPTY_CONFIG;
+    if (typeof redact !== "object" || Array.isArray(redact)) {
+        throw new TypeError("[foam] redact must be an object");
+    }
+    const record = redact;
+    const unknown = Object.keys(record).filter((field) => !REDACT_FIELDS.includes(field));
+    if (unknown.length) {
+        throw new TypeError(`[foam] redact contains unknown fields: ${unknown.join(", ")}`);
+    }
+    return {
+        secretKeys: new Set(keyList("secrets", record.secrets)
+            .map(normalizeKey)
+            .filter(Boolean)),
+        piiKeys: new Set(keyList("pii", record.pii)
+            .map(normalizeKey)
+            .filter(Boolean)),
+    };
+}

package/dist/report.d.ts

@@ -0,0 +1,9 @@
+import { SeverityNumber } from "@opentelemetry/api-logs";
+export declare function report({ name, environment, token, severity, message, error, }: {
+    name?: string;
+    environment?: string;
+    token?: string;
+    severity: SeverityNumber;
+    message: string;
+    error?: string;
+}): Promise<void>;

package/dist/report.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.report = report;
+const api_1 = require("@opentelemetry/api");
+const api_logs_1 = require("@opentelemetry/api-logs");
+const core_1 = require("@opentelemetry/core");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const constants_js_1 = require("./constants.js");
+const otlp_js_1 = require("./otlp.js");
+const state_js_1 = require("./state.js");
+const logger = api_1.diag.createComponentLogger({ namespace: constants_js_1.FOAM_IDENTIFIER_NAME });
+// pcga11: Guarded so repeat report() calls don't trigger diag's "logger will be overwritten" warning.
+let reportingConfigured = false;
+function ensureReportingConfigured() {
+    if (reportingConfigured) {
+        return;
+    }
+    reportingConfigured = true;
+    const fromEnv = (0, core_1.diagLogLevelFromString)((0, core_1.getStringFromEnv)(constants_js_1.DIAG_LOG_LEVEL));
+    api_1.diag.setLogger(new api_1.DiagConsoleLogger(), fromEnv ?? api_1.DiagLogLevel.INFO);
+}
+// pcga11: State reports go to Foam's OTLP endpoint directly instead of through the
+// logger provider or exporter, since those may themselves be broken or unregistered.
+async function report({ name, environment, token, severity, message, error, }) {
+    ensureReportingConfigured();
+    // pcga11: Local diag logging happens before the token check so misconfiguration
+    // is visible in the console even when nothing can be sent.
+    if (severity >= api_logs_1.SeverityNumber.ERROR) {
+        logger.error(message);
+    }
+    else if (severity >= api_logs_1.SeverityNumber.WARN) {
+        logger.warn(message);
+    }
+    else {
+        logger.info(message);
+    }
+    // pcga11: Token is the only hard requirement (nothing can be sent without auth).
+    // name/environment fall back to "unknown" so misconfiguration reports still arrive.
+    if (!token) {
+        return;
+    }
+    await (0, otlp_js_1.sendOtlpLog)({
+        token: token,
+        resourceAttributes: {
+            [semantic_conventions_1.ATTR_SERVICE_NAME]: name?.trim() || "unknown",
+            [semantic_conventions_1.ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: environment?.trim() || "unknown",
+        },
+        scopeName: constants_js_1.FOAM_IDENTIFIER_NAME,
+        severityNumber: severity,
+        body: JSON.stringify({
+            state: { ...(0, state_js_1.getState)() },
+            message: `${constants_js_1.FOAM_IDENTIFIER_NAME} ${message}`,
+            error: error,
+        }),
+    });
+}

package/dist/state.d.ts

@@ -5,15 +5,22 @@ export declare enum Signals {
     baggage = "baggage",
     profile = "profile"
 }
-/** Read-only view of the SDK state; mutated only via the setters in state.ts. */
+export declare enum SignalSources {
+    none = "none",
+    global = "global",
+    ingest = "ingest",
+    local = "local"
+}
 export interface State {
     readonly initialized: boolean;
     readonly instrumentations: readonly string[];
-    readonly signals: Readonly<Record<Signals, boolean>>;
+    readonly signals: Readonly<Record<Signals, SignalSources>>;
+    readonly params: Readonly<Record<string, unknown>>;
 }
 export declare const setInstrumentations: (names: readonly string[]) => void;
-export declare const setSignal: (signal: Signals, enabled: boolean) => void;
-export declare const getSignal: (signal: Signals) => boolean;
+export declare const setSignal: (signal: Signals, source: SignalSources) => void;
+export declare const getSignal: (signal: Signals) => SignalSources;
 export declare const setInitialized: (initialized: boolean) => void;
 export declare const getInitialized: () => boolean;
+export declare const setParams: (params: Record<string, unknown>) => void;
 export declare const getState: () => State;

package/dist/state.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getState = exports.getInitialized = exports.setInitialized = exports.getSignal = exports.setSignal = exports.setInstrumentations = exports.Signals = void 0;
+exports.getState = exports.setParams = exports.getInitialized = exports.setInitialized = exports.getSignal = exports.setSignal = exports.setInstrumentations = exports.SignalSources = exports.Signals = void 0;
 var Signals;
 (function (Signals) {
     Signals["traces"] = "traces";
@@ -9,23 +9,31 @@ var Signals;
     Signals["baggage"] = "baggage";
     Signals["profile"] = "profile";
 })(Signals || (exports.Signals = Signals = {}));
+var SignalSources;
+(function (SignalSources) {
+    SignalSources["none"] = "none";
+    SignalSources["global"] = "global";
+    SignalSources["ingest"] = "ingest";
+    SignalSources["local"] = "local";
+})(SignalSources || (exports.SignalSources = SignalSources = {}));
 const state = {
     initialized: false,
-    instrumentations: [],
+    instrumentations: [], // pcga11: The registered instrumentations that are enabled in the current application.
     signals: {
-        traces: false,
-        metrics: false,
-        logs: false,
-        baggage: false,
-        profile: false,
+        traces: SignalSources.none,
+        metrics: SignalSources.none,
+        logs: SignalSources.none,
+        baggage: SignalSources.none,
+        profile: SignalSources.none,
     },
+    params: {},
 };
 const setInstrumentations = (names) => {
     state.instrumentations = [...names];
 };
 exports.setInstrumentations = setInstrumentations;
-const setSignal = (signal, enabled) => {
-    state.signals[signal] = enabled;
+const setSignal = (signal, source) => {
+    state.signals[signal] = source;
 };
 exports.setSignal = setSignal;
 const getSignal = (signal) => state.signals[signal];
@@ -36,9 +44,18 @@ const setInitialized = (initialized) => {
 exports.setInitialized = setInitialized;
 const getInitialized = () => state.initialized;
 exports.getInitialized = getInitialized;
+const setParams = (params) => {
+    // pcga11: Safety precaution: never store tokens in the state.
+    if (params.token) {
+        delete params.token;
+    }
+    state.params = { ...params };
+};
+exports.setParams = setParams;
 const getState = () => ({
     initialized: state.initialized,
     instrumentations: [...state.instrumentations],
     signals: { ...state.signals },
+    params: { ...state.params },
 });
 exports.getState = getState;

package/dist/traces.d.ts

@@ -0,0 +1 @@
+export declare function recordException(error: unknown): void;

package/dist/traces.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordException = recordException;
+const api_1 = require("@opentelemetry/api");
+const utils_js_1 = require("./utils.js");
+// pcga11: Not gated on the traces signal on purpose: the active span belongs to
+// whichever SDK owns tracing, and the exception should land on that span either way.
+function recordException(error) {
+    (0, utils_js_1.safely)(() => {
+        const span = api_1.trace.getActiveSpan();
+        if (!span?.isRecording()) {
+            return;
+        }
+        const exception = error instanceof Error ? error : String(error);
+        span.recordException(exception);
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error instanceof Error ? error.message : String(error),
+        });
+    });
+}

package/dist/utils.js

@@ -13,7 +13,7 @@ function safely(operation, fallback) {
 }
 function whenInitialized(signal, operation) {
     return (...args) => {
-        if (!(0, state_js_1.getSignal)(signal))
+        if ((0, state_js_1.getSignal)(signal) === state_js_1.SignalSources.none)
             return;
         safely(() => operation(...args));
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foam-ai/node",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "description": "Foam JavaScript Node.js SDK",
   "license": "Apache-2.0",
   "repository": {

package/dist/diagnostics.d.ts

@@ -1,13 +0,0 @@
-import { SeverityNumber } from "@opentelemetry/api-logs";
-export declare function configureDiagnostics(): void;
-export declare const info: (message: string) => void;
-export declare const warn: (message: string) => void;
-export declare const error: (message: string) => void;
-export declare function sendStateDiagnosticLog({ name, environment, token, tier, severity, error, }: {
-    name: string;
-    environment: string;
-    token: string;
-    tier: "internal" | "external";
-    severity: SeverityNumber;
-    error?: string;
-}): Promise<void>;

package/dist/diagnostics.js

@@ -1,83 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.error = exports.warn = exports.info = void 0;
-exports.configureDiagnostics = configureDiagnostics;
-exports.sendStateDiagnosticLog = sendStateDiagnosticLog;
-const api_1 = require("@opentelemetry/api");
-const core_1 = require("@opentelemetry/core");
-const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
-const constants_js_1 = require("./constants.js");
-const state_js_1 = require("./state.js");
-const logger = api_1.diag.createComponentLogger({ namespace: constants_js_1.FOAM_IDENTIFIER_NAME });
-function configureDiagnostics() {
-    const fromEnv = (0, core_1.diagLogLevelFromString)((0, core_1.getStringFromEnv)(constants_js_1.DIAG_LOG_LEVEL));
-    api_1.diag.setLogger(new api_1.DiagConsoleLogger(), fromEnv ?? api_1.DiagLogLevel.INFO);
-}
-const info = (message) => {
-    logger.info(message);
-};
-exports.info = info;
-const warn = (message) => {
-    logger.warn(message);
-};
-exports.warn = warn;
-const error = (message) => {
-    logger.error(message);
-};
-exports.error = error;
-// pcga11: We send the diagnostic log to Foam's OTLP endpoint directly instead of using the logger provider or exporter to deliver diagnostics.
-// We do not want to rely on the logger provider or exporter to deliver diagnostics. As they themselves may not be instrumented.
-async function sendStateDiagnosticLog({ name, environment, token, tier, severity, error, }) {
-    if (!name?.trim() || !environment?.trim() || !token) {
-        return;
-    }
-    try {
-        await fetch(`${constants_js_1.FOAM_ENDPOINT}${constants_js_1.FOAM_OTLP_LOGS_PATH}`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-                resourceLogs: [
-                    {
-                        resource: {
-                            attributes: [
-                                { key: semantic_conventions_1.ATTR_SERVICE_NAME, value: { stringValue: name } },
-                                {
-                                    key: semantic_conventions_1.ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
-                                    value: { stringValue: environment },
-                                },
-                                { key: constants_js_1.FOAM_INGEST_TIER, value: { stringValue: tier } },
-                            ],
-                        },
-                        scopeLogs: [
-                            {
-                                scope: { name: constants_js_1.FOAM_IDENTIFIER_NAME },
-                                logRecords: [
-                                    {
-                                        timeUnixNano: String(BigInt(Date.now()) * 1000000n),
-                                        severityNumber: severity,
-                                        severityText: constants_js_1.SEVERITY_TEXT[severity],
-                                        body: {
-                                            stringValue: JSON.stringify({
-                                                ...(0, state_js_1.getState)(),
-                                                [constants_js_1.FOAM_INGEST_TIER]: tier,
-                                                ...(error === undefined
-                                                    ? {}
-                                                    : { error }),
-                                            }),
-                                        },
-                                    },
-                                ],
-                            },
-                        ],
-                    },
-                ],
-            }),
-        });
-    }
-    catch {
-        // pcga11: do not remove this catch block. Ingest must never throw into application code.
-    }
-}