@senad-d/observme 0.1.0

package/src/pi/subagent-types.ts

@@ -0,0 +1,29 @@
+import type { Span } from "@opentelemetry/api";
+import type { AgentWaitReason, SubagentSpawnReason } from "../semconv/values.ts";
+
+export type TestableSpan = Span & {
+  readonly name?: string;
+  readonly attributes?: Record<string, unknown>;
+  readonly parentSpan?: Span;
+};
+
+export interface SubagentSpawnState {
+  readonly span: TestableSpan;
+  readonly childAgentId: string;
+  readonly startedAtMs: number;
+  readonly labels: Record<string, string>;
+  readonly spawnReason: SubagentSpawnReason;
+  readonly traceContextPropagated: boolean;
+}
+
+export interface AgentWaitJoinState {
+  readonly span: TestableSpan;
+  readonly startedAtMs: number;
+  readonly labels: Record<string, string>;
+  readonly reason: AgentWaitReason;
+}
+
+export interface ChildFailureAccountingState {
+  readonly failureRecorded: boolean;
+  readonly recoveryRecorded: boolean;
+}

package/src/privacy/content-capture.ts

@@ -0,0 +1,104 @@
+import type { ObservMeConfig } from "../config/schema.ts";
+import { COMMON_SPAN_ATTRIBUTES } from "../semconv/attributes.ts";
+import { createEnvTenantSaltSource } from "./hash.ts";
+import { redactValue } from "./redact.ts";
+import type { ContentLimitKind, TruncationAttributes } from "./truncate.ts";
+import { limitForContentKind, truncateContent } from "./truncate.ts";
+
+export type ContentCaptureMode = "omitted" | "redacted" | "unsafe" | "dropped";
+
+export interface ContentCapturePolicyRequest {
+  readonly captureEnabled: boolean;
+  readonly value?: string;
+  readonly kind: ContentLimitKind;
+  readonly config: ObservMeConfig;
+}
+
+export interface ContentCapturePolicyResult {
+  readonly mode: ContentCaptureMode;
+  readonly value?: string;
+  readonly captured: boolean;
+  readonly redactionFailures: number;
+  readonly truncated: boolean;
+  readonly originalLength?: number;
+  readonly attributes: TruncationAttributes;
+  readonly errors: readonly string[];
+}
+
+export function applyContentCapturePolicy(request: ContentCapturePolicyRequest): ContentCapturePolicyResult {
+  if (!request.captureEnabled || request.value === undefined || request.value.length === 0) return omittedContentCapture();
+  if (request.config.privacy.redactionEnabled) return redactedContentCapture(request.value, request.kind, request.config);
+  if (request.config.privacy.allowUnsafeCapture) return unsafeContentCapture(request.value, request.kind, request.config);
+  return droppedContentCapture(["content capture requires redaction unless privacy.allowUnsafeCapture is true"], 1);
+}
+
+export function redactedContentCapture(value: string, kind: ContentLimitKind, config: ObservMeConfig): ContentCapturePolicyResult {
+  const result = redactValue(value, {
+    pathMode: config.privacy.pathMode,
+    customRedactionPatterns: config.privacy.customRedactionPatterns,
+    maxOutputChars: limitForContentKind(kind, config.limits),
+    tenantSaltSource: createEnvTenantSaltSource(config),
+  });
+
+  if (result.dropped || result.value === undefined) return droppedContentCapture(result.errors, result.failureMetrics.redactionFailures || 1);
+
+  return {
+    mode: "redacted",
+    value: result.value,
+    captured: true,
+    redactionFailures: 0,
+    truncated: result.truncated,
+    originalLength: result.originalLength,
+    attributes: truncationAttributes(result.truncated, result.originalLength),
+    errors: [],
+  };
+}
+
+export function unsafeContentCapture(value: string, kind: ContentLimitKind, config: ObservMeConfig): ContentCapturePolicyResult {
+  const result = truncateContent(value, kind, config.limits);
+  return {
+    mode: "unsafe",
+    value: result.value,
+    captured: true,
+    redactionFailures: 0,
+    truncated: result.truncated,
+    originalLength: result.originalLength,
+    attributes: result.attributes,
+    errors: [],
+  };
+}
+
+export function omittedContentCapture(): ContentCapturePolicyResult {
+  return {
+    mode: "omitted",
+    captured: false,
+    redactionFailures: 0,
+    truncated: false,
+    attributes: {},
+    errors: [],
+  };
+}
+
+export function droppedContentCapture(errors: readonly string[], redactionFailures: number): ContentCapturePolicyResult {
+  return {
+    mode: "dropped",
+    captured: false,
+    redactionFailures: normalizeRedactionFailures(redactionFailures),
+    truncated: false,
+    attributes: {},
+    errors,
+  };
+}
+
+function truncationAttributes(truncated: boolean, originalLength: number | undefined): TruncationAttributes {
+  if (!truncated) return {};
+  return {
+    [COMMON_SPAN_ATTRIBUTES.OBSERVME_TRUNCATED]: true,
+    [COMMON_SPAN_ATTRIBUTES.OBSERVME_ORIGINAL_LENGTH]: originalLength,
+  };
+}
+
+function normalizeRedactionFailures(value: number): number {
+  if (!Number.isFinite(value) || value < 1) return 1;
+  return Math.trunc(value);
+}

package/src/privacy/hash.ts

@@ -0,0 +1,93 @@
+import { createHash, createHmac } from "node:crypto";
+
+export interface EnvTenantSaltSource {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly envName: string;
+}
+
+export interface TenantSaltConfig {
+  readonly privacy: {
+    readonly tenantSaltEnv: string;
+  };
+}
+
+export interface SecureRuntimeTenantSaltSource {
+  readonly secureRuntimeConfig: {
+    readonly tenantSalt: string;
+  };
+}
+
+export type TenantSaltSource = EnvTenantSaltSource | SecureRuntimeTenantSaltSource;
+
+const registeredTenantSaltEnvironments = new WeakMap<TenantSaltConfig, Readonly<Record<string, string | undefined>>>();
+
+export function registerTenantSaltEnvironment<T extends TenantSaltConfig>(
+  config: T,
+  env: Readonly<Record<string, string | undefined>>,
+): T {
+  registeredTenantSaltEnvironments.set(config, env);
+  return config;
+}
+
+export function inheritTenantSaltEnvironment<T extends TenantSaltConfig>(target: T, source: TenantSaltConfig): T {
+  return registerTenantSaltEnvironment(target, tenantSaltEnvironmentForConfig(source));
+}
+
+export function sha256(value: string, source: TenantSaltSource): string {
+  return createHash("sha256").update(`${resolveTenantSalt(source)}\0${value}`).digest("hex");
+}
+
+export function hmac_sha256(value: string, source: TenantSaltSource): string {
+  return createHmac("sha256", resolveTenantSalt(source)).update(value).digest("hex");
+}
+
+export function createEnvTenantSaltSource(
+  config: TenantSaltConfig,
+  env: Readonly<Record<string, string | undefined>> = tenantSaltEnvironmentForConfig(config),
+): EnvTenantSaltSource {
+  return { env, envName: config.privacy.tenantSaltEnv };
+}
+
+export function trySha256(
+  value: string,
+  config: TenantSaltConfig,
+  env: Readonly<Record<string, string | undefined>> = tenantSaltEnvironmentForConfig(config),
+): string | undefined {
+  const salt = readOptionalTenantSaltFromEnv(createEnvTenantSaltSource(config, env));
+  if (salt === undefined) return undefined;
+  return createHash("sha256").update(`${salt}\0${value}`).digest("hex");
+}
+
+function tenantSaltEnvironmentForConfig(config: TenantSaltConfig): Readonly<Record<string, string | undefined>> {
+  return registeredTenantSaltEnvironments.get(config) ?? process.env;
+}
+
+function readOptionalTenantSaltFromEnv(source: EnvTenantSaltSource): string | undefined {
+  if (source.envName.length === 0) return undefined;
+
+  const salt = source.env[source.envName];
+  if (salt === undefined || salt.length === 0) return undefined;
+  return salt;
+}
+
+export function resolveTenantSalt(source: TenantSaltSource): string {
+  const salt = readTenantSalt(source);
+  if (salt.length === 0) throw new Error("tenant salt must not be empty");
+  return salt;
+}
+
+export function readTenantSalt(source: TenantSaltSource): string {
+  if (isEnvTenantSaltSource(source)) return readTenantSaltFromEnv(source);
+  return source.secureRuntimeConfig.tenantSalt;
+}
+
+export function readTenantSaltFromEnv(source: EnvTenantSaltSource): string {
+  if (source.envName.length === 0) throw new Error("tenant salt env name must not be empty");
+  const salt = source.env[source.envName];
+  if (salt === undefined) throw new Error(`tenant salt env var ${source.envName} is not set`);
+  return salt;
+}
+
+export function isEnvTenantSaltSource(source: TenantSaltSource): source is EnvTenantSaltSource {
+  return "env" in source;
+}