@superblocksteam/telemetry 2.0.83-next.1

package/dist-esm/common/contracts/tier2-traces.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Tier 2 Traces Contract
+ *
+ * This file defines the Tier 2 telemetry contract:
+ * - Forbidden attributes (removed by Collector)
+ * - Hashed attributes (pseudonymized by Collector)
+ * - Dropped attributes (removed by Collector)
+ * - Forbidden value patterns (for lint-time detection)
+ *
+ * ENFORCEMENT: The OTEL Collector handles runtime enforcement.
+ * These definitions are used for:
+ * - ESLint rules (static analysis at CI time)
+ * - Development warnings (guardrails.ts)
+ * - Collector config generation
+ *
+ * See: obs/otel-collector/config-tiered.yaml
+ * Source of truth: engineering/projects/o11y-refactor/contracts/tier2-traces.v0.3.0.json
+ */
+/**
+ * Attributes that are FORBIDDEN in Tier 2 telemetry.
+ * These contain sensitive data that should never leave the customer's environment.
+ * The Collector strips these entirely (not hashed, not present in Tier 2).
+ */
+export declare const TIER2_FORBIDDEN_ATTRIBUTES: Set<string>;
+/**
+ * Attributes that should be HASHED (pseudonymized) in Tier 2 telemetry.
+ * The Collector replaces these with SHA256 hashes for privacy.
+ * Hashes enable aggregate analysis without exposing plaintext identifiers.
+ *
+ * Mapping:
+ *   user-email, user.email, etc. → user.hash
+ *   organization-id, organization_id → organization.hash
+ *   application-id, application_id → application.hash
+ *   session.id → session.hash
+ *   enduser.id → enduser.pseudo.id
+ */
+export declare const TIER2_HASHED_ATTRIBUTES: Set<string>;
+/**
+ * Attributes that should be DROPPED entirely in Tier 2.
+ * These are correlation IDs that don't provide operational value.
+ */
+export declare const TIER2_DROPPED_ATTRIBUTES: Set<string>;
+/**
+ * Spans that should ALWAYS be sampled (never dropped by rate limiting).
+ */
+export declare const ALWAYS_SAMPLE_SPANS: Set<string>;
+/**
+ * Patterns that indicate forbidden content in attribute values.
+ * Used for secondary filtering when attribute names aren't explicit.
+ *
+ * IMPORTANT: Patterns should NOT use ^ and $ anchors so they match
+ * secrets embedded anywhere in a string (e.g., in query params, headers).
+ */
+export declare const FORBIDDEN_VALUE_PATTERNS: RegExp[];
+/**
+ * Check if an attribute name is forbidden in Tier 2.
+ */
+export declare function isForbiddenAttribute(name: string): boolean;
+/**
+ * Check if an attribute should be hashed in Tier 2.
+ */
+export declare function isHashedAttribute(name: string): boolean;
+/**
+ * Check if an attribute should be dropped in Tier 2.
+ */
+export declare function isDroppedAttribute(name: string): boolean;
+/**
+ * Check if a value contains forbidden patterns (like tokens, keys).
+ */
+export declare function containsForbiddenPattern(value: unknown): boolean;
+/**
+ * Check if a span should always be sampled.
+ */
+export declare function shouldAlwaysSample(spanName: string): boolean;
+//# sourceMappingURL=tier2-traces.d.ts.map

package/dist-esm/common/contracts/tier2-traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier2-traces.d.ts","sourceRoot":"","sources":["../../../src/common/contracts/tier2-traces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,aAsDrC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,aAmBlC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB,aAQnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB,aAE9B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,UAuBpC,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist-esm/common/contracts/tier2-traces.js

@@ -0,0 +1,178 @@
+/**
+ * Tier 2 Traces Contract
+ *
+ * This file defines the Tier 2 telemetry contract:
+ * - Forbidden attributes (removed by Collector)
+ * - Hashed attributes (pseudonymized by Collector)
+ * - Dropped attributes (removed by Collector)
+ * - Forbidden value patterns (for lint-time detection)
+ *
+ * ENFORCEMENT: The OTEL Collector handles runtime enforcement.
+ * These definitions are used for:
+ * - ESLint rules (static analysis at CI time)
+ * - Development warnings (guardrails.ts)
+ * - Collector config generation
+ *
+ * See: obs/otel-collector/config-tiered.yaml
+ * Source of truth: engineering/projects/o11y-refactor/contracts/tier2-traces.v0.3.0.json
+ */
+/**
+ * Attributes that are FORBIDDEN in Tier 2 telemetry.
+ * These contain sensitive data that should never leave the customer's environment.
+ * The Collector strips these entirely (not hashed, not present in Tier 2).
+ */
+export const TIER2_FORBIDDEN_ATTRIBUTES = new Set([
+    // LLM/AI content
+    'llmobs.input',
+    'llmobs.output',
+    'prompt',
+    'code',
+    'tool_input',
+    'tool_output',
+    // File content
+    'file_path',
+    'file_content',
+    // Database content
+    'db.statement',
+    'db.query_text',
+    'db.query.text',
+    // HTTP bodies and URLs
+    'http.request.body',
+    'http.response.body',
+    'url.full',
+    'url.query',
+    'http.url',
+    'http.target',
+    // Resource identifiers (names are customer-specific)
+    'api-id',
+    'api_id',
+    'api-name',
+    'api_name',
+    'resource-id',
+    'resource_id',
+    'resource-name',
+    'resource_name',
+    'integration-id',
+    'integration_id',
+    'widget-type',
+    'branch',
+    'commit-id',
+    'commit_id',
+    'profile-id',
+    'profile_id',
+    // Stack traces
+    'error.stack',
+    'exception.stacktrace',
+    // Auth/secrets
+    'auth_token',
+    'api_key',
+    'authorization',
+    'cookie',
+    'x-api-key',
+]);
+/**
+ * Attributes that should be HASHED (pseudonymized) in Tier 2 telemetry.
+ * The Collector replaces these with SHA256 hashes for privacy.
+ * Hashes enable aggregate analysis without exposing plaintext identifiers.
+ *
+ * Mapping:
+ *   user-email, user.email, etc. → user.hash
+ *   organization-id, organization_id → organization.hash
+ *   application-id, application_id → application.hash
+ *   session.id → session.hash
+ *   enduser.id → enduser.pseudo.id
+ */
+export const TIER2_HASHED_ATTRIBUTES = new Set([
+    // User identity (hashed to user.hash)
+    'user-email',
+    'user.email',
+    'user_email',
+    'user.id',
+    'enduser.email',
+    // Organization identity (hashed to organization.hash)
+    'organization-id',
+    'organization_id',
+    // Application identity (hashed to application.hash)
+    'application-id',
+    'application_id',
+    // Session/enduser identity
+    'session.id',
+    'enduser.id',
+]);
+/**
+ * Attributes that should be DROPPED entirely in Tier 2.
+ * These are correlation IDs that don't provide operational value.
+ */
+export const TIER2_DROPPED_ATTRIBUTES = new Set([
+    'correlation-id',
+    'correlation_id',
+    'request-id',
+    'request_id',
+    'trace-id',
+    'execution_id',
+    'binding_keys',
+]);
+/**
+ * Spans that should ALWAYS be sampled (never dropped by rate limiting).
+ */
+export const ALWAYS_SAMPLE_SPANS = new Set([
+    'api.execute',
+]);
+/**
+ * Patterns that indicate forbidden content in attribute values.
+ * Used for secondary filtering when attribute names aren't explicit.
+ *
+ * IMPORTANT: Patterns should NOT use ^ and $ anchors so they match
+ * secrets embedded anywhere in a string (e.g., in query params, headers).
+ */
+export const FORBIDDEN_VALUE_PATTERNS = [
+    // JWT tokens (anywhere in string)
+    // Header (eyJ...) and payload (eyJ...) must be base64url encoded JSON
+    // Signature can be any length (even short for test tokens)
+    /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+/,
+    // API keys (sk-/pk- prefix patterns with word boundaries)
+    /\b(sk|pk)-[a-zA-Z0-9]{32,}\b/,
+    // Bearer tokens (anywhere in string)
+    /Bearer\s+[A-Za-z0-9._-]{20,}/,
+    // PEM blocks (anywhere in string)
+    /-----BEGIN\s+(RSA\s+)?(PRIVATE|PUBLIC)\s+KEY-----/,
+    // AWS access key IDs
+    /\bAKIA[A-Z0-9]{16}\b/,
+    // GitHub tokens
+    /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/,
+    // Generic API key patterns (key=value or key:value with long alphanumeric)
+    /\b(api[_-]?key|apikey|secret[_-]?key|access[_-]?token)[=:]\s*[A-Za-z0-9_-]{20,}\b/i,
+];
+/**
+ * Check if an attribute name is forbidden in Tier 2.
+ */
+export function isForbiddenAttribute(name) {
+    return TIER2_FORBIDDEN_ATTRIBUTES.has(name);
+}
+/**
+ * Check if an attribute should be hashed in Tier 2.
+ */
+export function isHashedAttribute(name) {
+    return TIER2_HASHED_ATTRIBUTES.has(name);
+}
+/**
+ * Check if an attribute should be dropped in Tier 2.
+ */
+export function isDroppedAttribute(name) {
+    return TIER2_DROPPED_ATTRIBUTES.has(name);
+}
+/**
+ * Check if a value contains forbidden patterns (like tokens, keys).
+ */
+export function containsForbiddenPattern(value) {
+    if (typeof value !== 'string')
+        return false;
+    return FORBIDDEN_VALUE_PATTERNS.some(pattern => pattern.test(value));
+}
+/**
+ * Check if a span should always be sampled.
+ */
+export function shouldAlwaysSample(spanName) {
+    return ALWAYS_SAMPLE_SPANS.has(spanName);
+}
+//# sourceMappingURL=tier2-traces.js.map

package/dist-esm/common/contracts/tier2-traces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier2-traces.js","sourceRoot":"","sources":["../../../src/common/contracts/tier2-traces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC;IAChD,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,QAAQ;IACR,MAAM;IACN,YAAY;IACZ,aAAa;IAEb,eAAe;IACf,WAAW;IACX,cAAc;IAEd,mBAAmB;IACnB,cAAc;IACd,eAAe;IACf,eAAe;IAEf,uBAAuB;IACvB,mBAAmB;IACnB,oBAAoB;IACpB,UAAU;IACV,WAAW;IACX,UAAU;IACV,aAAa;IAEb,qDAAqD;IACrD,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,UAAU;IACV,aAAa;IACb,aAAa;IACb,eAAe;IACf,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,aAAa;IACb,QAAQ;IACR,WAAW;IACX,WAAW;IACX,YAAY;IACZ,YAAY;IAEZ,eAAe;IACf,aAAa;IACb,sBAAsB;IAEtB,eAAe;IACf,YAAY;IACZ,SAAS;IACT,eAAe;IACf,QAAQ;IACR,WAAW;CACZ,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC;IAC7C,sCAAsC;IACtC,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,SAAS;IACT,eAAe;IAEf,sDAAsD;IACtD,iBAAiB;IACjB,iBAAiB;IAEjB,oDAAoD;IACpD,gBAAgB;IAChB,gBAAgB;IAEhB,2BAA2B;IAC3B,YAAY;IACZ,YAAY;CACb,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC;IAC9C,gBAAgB;IAChB,gBAAgB;IAChB,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,cAAc;IACd,cAAc;CACf,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IACzC,aAAa;CACd,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,kCAAkC;IAClC,sEAAsE;IACtE,2DAA2D;IAC3D,8DAA8D;IAE9D,0DAA0D;IAC1D,8BAA8B;IAE9B,qCAAqC;IACrC,8BAA8B;IAE9B,kCAAkC;IAClC,mDAAmD;IAEnD,qBAAqB;IACrB,sBAAsB;IAEtB,gBAAgB;IAChB,4CAA4C;IAE5C,2EAA2E;IAC3E,oFAAoF;CACrF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,0BAA0B,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,uBAAuB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC3C,CAAC"}

package/dist-esm/common/deployment-type.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Deployment Type Parsing
+ *
+ * Shared utility for validating and parsing deployment type values.
+ * Used by both the server and CLI telemetry initialization.
+ */
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+/**
+ * Parse and validate a deployment type string.
+ *
+ * Returns CLOUD if not specified. Throws if an invalid value is provided.
+ *
+ * @param value - Raw deployment type string (typically from env var)
+ * @returns Valid DeploymentTypeEnum value
+ * @throws Error if value is not a valid DeploymentTypeEnum
+ */
+export declare function parseDeploymentType(value: string | undefined): DeploymentTypeEnum;
+//# sourceMappingURL=deployment-type.d.ts.map

package/dist-esm/common/deployment-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-type.d.ts","sourceRoot":"","sources":["../../src/common/deployment-type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,kBAAkB,CAapB"}

package/dist-esm/common/deployment-type.js

@@ -0,0 +1,27 @@
+/**
+ * Deployment Type Parsing
+ *
+ * Shared utility for validating and parsing deployment type values.
+ * Used by both the server and CLI telemetry initialization.
+ */
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+/**
+ * Parse and validate a deployment type string.
+ *
+ * Returns CLOUD if not specified. Throws if an invalid value is provided.
+ *
+ * @param value - Raw deployment type string (typically from env var)
+ * @returns Valid DeploymentTypeEnum value
+ * @throws Error if value is not a valid DeploymentTypeEnum
+ */
+export function parseDeploymentType(value) {
+    if (!value || value === "") {
+        return DeploymentTypeEnum.CLOUD;
+    }
+    if (!Object.values(DeploymentTypeEnum).includes(value)) {
+        throw new Error(`Invalid SUPERBLOCKS_DEPLOYMENT_TYPE: "${value}". ` +
+            `Valid values are: ${Object.values(DeploymentTypeEnum).join(", ")}.`);
+    }
+    return value;
+}
+//# sourceMappingURL=deployment-type.js.map

package/dist-esm/common/deployment-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-type.js","sourceRoot":"","sources":["../../src/common/deployment-type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAyB;IAEzB,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QAC3B,OAAO,kBAAkB,CAAC,KAAK,CAAC;IAClC,CAAC;IACD,IACE,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,QAAQ,CAAC,KAA2B,CAAC,EACxE,CAAC;QACD,MAAM,IAAI,KAAK,CACb,yCAAyC,KAAK,KAAK;YACjD,qBAAqB,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,KAA2B,CAAC;AACrC,CAAC"}

package/dist-esm/common/guardrails.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Telemetry Guardrails
+ *
+ * Lint-time guardrails to detect forbidden or high-cardinality attributes.
+ *
+ * NOTE: In the tiered telemetry architecture, the OTEL Collector handles
+ * runtime filtering and sanitization. These guardrails are for:
+ * - ESLint rules (static analysis)
+ * - Development warnings (not enforcement)
+ * - CI validation
+ *
+ * See obs/otel-collector/config-tiered.yaml for runtime enforcement.
+ */
+import type { Attributes } from '@opentelemetry/api';
+/**
+ * Guardrail violation types.
+ */
+export declare enum ViolationType {
+    /** Attribute is forbidden in Tier 2 */
+    FORBIDDEN_ATTRIBUTE = "forbidden_attribute",
+    /** Attribute should be a resource attribute, not span attribute */
+    RESOURCE_ONLY = "resource_only",
+    /** Value contains forbidden pattern (JWT, API key, etc.) */
+    FORBIDDEN_VALUE = "forbidden_value",
+    /** Attribute value has too high cardinality */
+    HIGH_CARDINALITY = "high_cardinality"
+}
+/**
+ * Guardrail violation record.
+ */
+export interface GuardrailViolation {
+    /** Type of violation */
+    type: ViolationType;
+    /** Attribute key that violated */
+    attributeKey: string;
+    /** Human-readable message */
+    message: string;
+    /** Severity level */
+    severity: 'error' | 'warning';
+}
+/**
+ * Mode for guardrail reporting.
+ *
+ * NOTE: Runtime filtering is handled by the OTEL Collector.
+ * These modes are for lint-time/development feedback only.
+ */
+export declare enum GuardrailMode {
+    /** Log violations as warnings (development) */
+    WARN = "warn",
+    /** Throw on violations (CI/strict mode) */
+    STRICT = "strict"
+}
+/**
+ * Options for guardrail validation.
+ */
+export interface GuardrailOptions {
+    /** Reporting mode */
+    mode: GuardrailMode;
+    /** Whether to check for high-cardinality values */
+    checkCardinality?: boolean;
+    /** Maximum allowed cardinality for string values */
+    maxCardinalityLength?: number;
+}
+/**
+ * Validate span attributes against Tier 2 guardrails.
+ *
+ * This is for lint-time validation. Runtime filtering is handled by Collector.
+ *
+ * @param attributes - Attributes to validate
+ * @param options - Guardrail options
+ * @returns Array of violations found
+ */
+export declare function validateSpanAttributes(attributes: Attributes, options?: Partial<GuardrailOptions>): GuardrailViolation[];
+/**
+ * Validate metric labels against Tier 2 guardrails.
+ *
+ * @param labels - Metric labels to validate
+ * @param options - Guardrail options
+ * @returns Array of violations found
+ */
+export declare function validateMetricLabels(labels: Record<string, string | number | boolean>, options?: Partial<GuardrailOptions>): GuardrailViolation[];
+/**
+ * Report guardrail violations.
+ *
+ * NOTE: This is for development feedback only. Runtime filtering
+ * is handled by the OTEL Collector.
+ *
+ * @param attributes - Attributes to check
+ * @param options - Guardrail options
+ * @throws Error in STRICT mode if violations found
+ */
+export declare function reportViolations(attributes: Attributes, options?: Partial<GuardrailOptions>): void;
+/**
+ * Check if an attribute key is allowed in Tier 2.
+ * Convenience function for quick checks.
+ *
+ * @param key - Attribute key
+ * @returns true if allowed
+ */
+export declare function isTier2Allowed(key: string): boolean;
+/**
+ * Check if an attribute should be hashed (by Collector).
+ *
+ * @param key - Attribute key
+ * @returns true if should be hashed
+ */
+export declare function shouldHash(key: string): boolean;
+/**
+ * Get all forbidden attribute names (for documentation/linting).
+ */
+export declare function getForbiddenAttributes(): string[];
+/**
+ * Get all hashed attribute names (for documentation/linting).
+ */
+export declare function getHashedAttributes(): string[];
+//# sourceMappingURL=guardrails.d.ts.map

package/dist-esm/common/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/common/guardrails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AASrD;;GAEG;AACH,oBAAY,aAAa;IACvB,uCAAuC;IACvC,mBAAmB,wBAAwB;IAC3C,mEAAmE;IACnE,aAAa,kBAAkB;IAC/B,4DAA4D;IAC5D,eAAe,oBAAoB;IACnC,+CAA+C;IAC/C,gBAAgB,qBAAqB;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;GAKG;AACH,oBAAY,aAAa;IACvB,+CAA+C;IAC/C,IAAI,SAAS;IACb,2CAA2C;IAC3C,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAQD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM,GACtC,kBAAkB,EAAE,CAqDtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACjD,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM,GACtC,kBAAkB,EAAE,CAGtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM,GACtC,IAAI,CAuBN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C"}

package/dist-esm/common/guardrails.js

@@ -0,0 +1,179 @@
+/**
+ * Telemetry Guardrails
+ *
+ * Lint-time guardrails to detect forbidden or high-cardinality attributes.
+ *
+ * NOTE: In the tiered telemetry architecture, the OTEL Collector handles
+ * runtime filtering and sanitization. These guardrails are for:
+ * - ESLint rules (static analysis)
+ * - Development warnings (not enforcement)
+ * - CI validation
+ *
+ * See obs/otel-collector/config-tiered.yaml for runtime enforcement.
+ */
+import { TIER2_FORBIDDEN_ATTRIBUTES, TIER2_HASHED_ATTRIBUTES, TIER2_DROPPED_ATTRIBUTES, containsForbiddenPattern, } from './contracts/tier2-traces.js';
+import { RESOURCE_ONLY_ATTRIBUTES } from './resource.js';
+/**
+ * Guardrail violation types.
+ */
+export var ViolationType;
+(function (ViolationType) {
+    /** Attribute is forbidden in Tier 2 */
+    ViolationType["FORBIDDEN_ATTRIBUTE"] = "forbidden_attribute";
+    /** Attribute should be a resource attribute, not span attribute */
+    ViolationType["RESOURCE_ONLY"] = "resource_only";
+    /** Value contains forbidden pattern (JWT, API key, etc.) */
+    ViolationType["FORBIDDEN_VALUE"] = "forbidden_value";
+    /** Attribute value has too high cardinality */
+    ViolationType["HIGH_CARDINALITY"] = "high_cardinality";
+})(ViolationType || (ViolationType = {}));
+/**
+ * Mode for guardrail reporting.
+ *
+ * NOTE: Runtime filtering is handled by the OTEL Collector.
+ * These modes are for lint-time/development feedback only.
+ */
+export var GuardrailMode;
+(function (GuardrailMode) {
+    /** Log violations as warnings (development) */
+    GuardrailMode["WARN"] = "warn";
+    /** Throw on violations (CI/strict mode) */
+    GuardrailMode["STRICT"] = "strict";
+})(GuardrailMode || (GuardrailMode = {}));
+const DEFAULT_OPTIONS = {
+    mode: GuardrailMode.WARN,
+    checkCardinality: true,
+    maxCardinalityLength: 200,
+};
+/**
+ * Validate span attributes against Tier 2 guardrails.
+ *
+ * This is for lint-time validation. Runtime filtering is handled by Collector.
+ *
+ * @param attributes - Attributes to validate
+ * @param options - Guardrail options
+ * @returns Array of violations found
+ */
+export function validateSpanAttributes(attributes, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const violations = [];
+    for (const [key, value] of Object.entries(attributes)) {
+        // Check for forbidden attributes
+        if (TIER2_FORBIDDEN_ATTRIBUTES.has(key)) {
+            violations.push({
+                type: ViolationType.FORBIDDEN_ATTRIBUTE,
+                attributeKey: key,
+                message: `Attribute '${key}' is forbidden in Tier 2 telemetry. ` +
+                    `Collector will filter this at runtime.`,
+                severity: 'warning',
+            });
+        }
+        // Check for resource-only attributes
+        if (RESOURCE_ONLY_ATTRIBUTES.has(key)) {
+            violations.push({
+                type: ViolationType.RESOURCE_ONLY,
+                attributeKey: key,
+                message: `Attribute '${key}' should be a RESOURCE attribute, not a span attribute. ` +
+                    `Set it in initNodeTelemetry() config, not per-span.`,
+                severity: 'warning',
+            });
+        }
+        // Check for forbidden value patterns
+        if (containsForbiddenPattern(value)) {
+            violations.push({
+                type: ViolationType.FORBIDDEN_VALUE,
+                attributeKey: key,
+                message: `Attribute '${key}' contains a forbidden pattern (JWT, API key, etc.). ` +
+                    `Collector will filter this at runtime.`,
+                severity: 'warning',
+            });
+        }
+        // Check for high cardinality
+        if (opts.checkCardinality && typeof value === 'string') {
+            if (value.length > opts.maxCardinalityLength) {
+                violations.push({
+                    type: ViolationType.HIGH_CARDINALITY,
+                    attributeKey: key,
+                    message: `Attribute '${key}' has a very long value (${value.length} chars). ` +
+                        `This may cause high cardinality. Consider using a shorter, normalized value.`,
+                    severity: 'warning',
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Validate metric labels against Tier 2 guardrails.
+ *
+ * @param labels - Metric labels to validate
+ * @param options - Guardrail options
+ * @returns Array of violations found
+ */
+export function validateMetricLabels(labels, options = {}) {
+    // Metric labels use the same rules as span attributes
+    return validateSpanAttributes(labels, options);
+}
+/**
+ * Report guardrail violations.
+ *
+ * NOTE: This is for development feedback only. Runtime filtering
+ * is handled by the OTEL Collector.
+ *
+ * @param attributes - Attributes to check
+ * @param options - Guardrail options
+ * @throws Error in STRICT mode if violations found
+ */
+export function reportViolations(attributes, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const violations = validateSpanAttributes(attributes, opts);
+    if (violations.length === 0) {
+        return;
+    }
+    switch (opts.mode) {
+        case GuardrailMode.STRICT: {
+            throw new Error(`Guardrail violations found:\n` +
+                violations.map(v => `  - ${v.message}`).join('\n'));
+        }
+        case GuardrailMode.WARN: {
+            violations.forEach(v => {
+                console.warn(`[Guardrail] ${v.message}`);
+            });
+            break;
+        }
+    }
+}
+/**
+ * Check if an attribute key is allowed in Tier 2.
+ * Convenience function for quick checks.
+ *
+ * @param key - Attribute key
+ * @returns true if allowed
+ */
+export function isTier2Allowed(key) {
+    return (!TIER2_FORBIDDEN_ATTRIBUTES.has(key) &&
+        !TIER2_DROPPED_ATTRIBUTES.has(key) &&
+        !RESOURCE_ONLY_ATTRIBUTES.has(key));
+}
+/**
+ * Check if an attribute should be hashed (by Collector).
+ *
+ * @param key - Attribute key
+ * @returns true if should be hashed
+ */
+export function shouldHash(key) {
+    return TIER2_HASHED_ATTRIBUTES.has(key);
+}
+/**
+ * Get all forbidden attribute names (for documentation/linting).
+ */
+export function getForbiddenAttributes() {
+    return [...TIER2_FORBIDDEN_ATTRIBUTES];
+}
+/**
+ * Get all hashed attribute names (for documentation/linting).
+ */
+export function getHashedAttributes() {
+    return [...TIER2_HASHED_ATTRIBUTES];
+}
+//# sourceMappingURL=guardrails.js.map

package/dist-esm/common/guardrails.js.map

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

package/dist-esm/common/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Common Telemetry Utilities
+ *
+ * Shared utilities for resource building and policy evaluation.
+ *
+ * NOTE: Sanitization and routing are handled by the OTEL Collector
+ * in the tiered telemetry architecture. See obs/otel-collector/config-tiered.yaml.
+ */
+export * from "./deployment-type.js";
+export * from "./resource.js";
+export * from "./policy-evaluator.js";
+export * from "./guardrails.js";
+export * from "./contracts/tier2-traces.js";
+export * from "./log-sanitizer.js";
+export * from "./tier-hints.js";
+//# sourceMappingURL=index.d.ts.map

package/dist-esm/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist-esm/common/index.js

@@ -0,0 +1,16 @@
+/**
+ * Common Telemetry Utilities
+ *
+ * Shared utilities for resource building and policy evaluation.
+ *
+ * NOTE: Sanitization and routing are handled by the OTEL Collector
+ * in the tiered telemetry architecture. See obs/otel-collector/config-tiered.yaml.
+ */
+export * from "./deployment-type.js";
+export * from "./resource.js";
+export * from "./policy-evaluator.js";
+export * from "./guardrails.js";
+export * from "./contracts/tier2-traces.js";
+export * from "./log-sanitizer.js";
+export * from "./tier-hints.js";
+//# sourceMappingURL=index.js.map

package/dist-esm/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}