@peac/telemetry 0.10.8 → 0.10.10

package/src/provider.ts

@@ -1,64 +0,0 @@
-/**
- * @peac/telemetry - Provider registry
- *
- * Zero-throw provider ref pattern for hot-path performance.
- * When undefined, telemetry is disabled with NO function calls.
- */
-
-import type { TelemetryProvider } from './types.js';
-
-/**
- * Singleton provider reference for zero-overhead hot path.
- *
- * When undefined, telemetry is disabled with NO function calls
- * beyond the initial `if (!p)` check.
- *
- * @example
- * ```typescript
- * // In hot path (issue/verify)
- * const p = providerRef.current;
- * if (p) {
- *   try {
- *     p.onReceiptIssued({ receiptHash: '...' });
- *   } catch {
- *     // Telemetry MUST NOT break core flow
- *   }
- * }
- * ```
- */
-export const providerRef: { current?: TelemetryProvider } = {
-  current: undefined,
-};
-
-/**
- * Set the telemetry provider.
- *
- * Idempotent, no-throw, safe to call multiple times.
- * Pass undefined to disable telemetry.
- *
- * @param provider - The provider to use, or undefined to disable
- */
-export function setTelemetryProvider(provider: TelemetryProvider | undefined): void {
-  providerRef.current = provider;
-}
-
-/**
- * Get the current telemetry provider.
- *
- * Returns undefined if no provider is set (telemetry disabled).
- *
- * For hot paths, prefer direct access to `providerRef.current`
- * to avoid the function call overhead.
- */
-export function getTelemetryProvider(): TelemetryProvider | undefined {
-  return providerRef.current;
-}
-
-/**
- * Check if telemetry is enabled.
- *
- * Convenience function for conditional logic outside hot paths.
- */
-export function isTelemetryEnabled(): boolean {
-  return providerRef.current !== undefined;
-}

package/src/types.ts

@@ -1,163 +0,0 @@
-/**
- * @peac/telemetry - Telemetry types and interfaces
- *
- * This module defines the core telemetry interfaces for PEAC protocol.
- * These are runtime-portable and have no external dependencies.
- */
-
-/**
- * Telemetry decision outcome
- */
-export type TelemetryDecision = 'allow' | 'deny' | 'unknown';
-
-/**
- * Privacy mode for telemetry emission
- *
- * - strict: Hash all identifiers, emit minimal data (production default)
- * - balanced: Hash identifiers but include rail + amounts (debugging)
- * - custom: Use allowlist-based filtering
- */
-export type PrivacyMode = 'strict' | 'balanced' | 'custom';
-
-/**
- * Telemetry configuration
- */
-export interface TelemetryConfig {
-  /** Service name for resource identification */
-  serviceName: string;
-
-  /** Privacy mode: strict (hashes only), balanced, custom */
-  privacyMode?: PrivacyMode;
-
-  /** Allowlist for custom mode - only these attribute keys are emitted */
-  allowAttributes?: string[];
-
-  /** Custom redaction hook for edge cases */
-  redact?: (attrs: Record<string, unknown>) => Record<string, unknown>;
-
-  /** Enable experimental GenAI semantic conventions (default: false) */
-  enableExperimentalGenAI?: boolean;
-
-  /** Salt for privacy-preserving hashing (should be configured per deployment) */
-  hashSalt?: string;
-}
-
-/**
- * Input for receipt issued telemetry event
- */
-export interface ReceiptIssuedInput {
-  /** Hash of the receipt (never raw content) */
-  receiptHash: string;
-
-  /** Hash of the policy used */
-  policyHash?: string;
-
-  /** Issuer identifier (may be hashed based on privacy mode) */
-  issuer?: string;
-
-  /** Key ID used for signing */
-  kid?: string;
-
-  /** HTTP context (privacy-safe: path only, no query) */
-  http?: HttpContext;
-
-  /** Duration of issue operation in milliseconds */
-  durationMs?: number;
-}
-
-/**
- * Input for receipt verified telemetry event
- */
-export interface ReceiptVerifiedInput {
-  /** Hash of the receipt */
-  receiptHash: string;
-
-  /** Issuer identifier */
-  issuer?: string;
-
-  /** Key ID used */
-  kid?: string;
-
-  /** Whether verification succeeded */
-  valid: boolean;
-
-  /** Reason code if verification failed */
-  reasonCode?: string;
-
-  /** HTTP context */
-  http?: HttpContext;
-
-  /** Duration of verify operation in milliseconds */
-  durationMs?: number;
-}
-
-/**
- * Input for access decision telemetry event
- */
-export interface AccessDecisionInput {
-  /** Hash of the receipt (if present) */
-  receiptHash?: string;
-
-  /** Hash of the policy evaluated */
-  policyHash?: string;
-
-  /** Decision outcome */
-  decision: TelemetryDecision;
-
-  /** Reason code for the decision */
-  reasonCode?: string;
-
-  /** Payment context (balanced/custom mode only) */
-  payment?: PaymentContext;
-
-  /** HTTP context */
-  http?: HttpContext;
-}
-
-/**
- * HTTP context for telemetry (privacy-safe subset)
- */
-export interface HttpContext {
-  /** HTTP method */
-  method?: string;
-
-  /** URL path (no query string) */
-  path?: string;
-}
-
-/**
- * Payment context for telemetry (balanced/custom mode only)
- */
-export interface PaymentContext {
-  /** Payment rail identifier */
-  rail?: string;
-
-  /** Amount in minor units */
-  amount?: number;
-
-  /** Currency code */
-  currency?: string;
-}
-
-/**
- * Telemetry provider interface
- *
- * Implementations SHOULD be no-throw. PEAC guards all calls,
- * but well-behaved providers should not throw.
- */
-export interface TelemetryProvider {
-  /**
-   * Called when a receipt is issued
-   */
-  onReceiptIssued(input: ReceiptIssuedInput): void;
-
-  /**
-   * Called when a receipt is verified
-   */
-  onReceiptVerified(input: ReceiptVerifiedInput): void;
-
-  /**
-   * Called when an access decision is made
-   */
-  onAccessDecision(input: AccessDecisionInput): void;
-}

package/tests/attributes.test.ts

@@ -1,126 +0,0 @@
-/**
- * @peac/telemetry - Attribute constants tests
- */
-
-import { describe, it, expect } from 'vitest';
-import {
-  PEAC_ATTRS,
-  PEAC_EVENTS,
-  PEAC_METRICS,
-  TRACE_CONTEXT_EXTENSIONS,
-} from '../src/attributes.js';
-
-describe('PEAC_ATTRS', () => {
-  it('should define core attributes', () => {
-    expect(PEAC_ATTRS.VERSION).toBe('peac.version');
-    expect(PEAC_ATTRS.EVENT).toBe('peac.event');
-    expect(PEAC_ATTRS.RECEIPT_HASH).toBe('peac.receipt.hash');
-    expect(PEAC_ATTRS.POLICY_HASH).toBe('peac.policy.hash');
-    expect(PEAC_ATTRS.DECISION).toBe('peac.decision');
-    expect(PEAC_ATTRS.REASON_CODE).toBe('peac.reason_code');
-    expect(PEAC_ATTRS.ISSUER).toBe('peac.issuer');
-    expect(PEAC_ATTRS.ISSUER_HASH).toBe('peac.issuer_hash');
-    expect(PEAC_ATTRS.KID).toBe('peac.kid');
-    expect(PEAC_ATTRS.VALID).toBe('peac.valid');
-  });
-
-  it('should use stable OTel semconv for HTTP', () => {
-    // These are stable OTel semantic conventions
-    expect(PEAC_ATTRS.HTTP_METHOD).toBe('http.request.method');
-    expect(PEAC_ATTRS.HTTP_PATH).toBe('url.path');
-  });
-
-  it('should define HTTP hash attributes', () => {
-    expect(PEAC_ATTRS.HTTP_HOST_HASH).toBe('peac.http.host_hash');
-    expect(PEAC_ATTRS.HTTP_CLIENT_HASH).toBe('peac.http.client_hash');
-  });
-
-  it('should define payment attributes', () => {
-    expect(PEAC_ATTRS.PAYMENT_RAIL).toBe('peac.payment.rail');
-    expect(PEAC_ATTRS.PAYMENT_AMOUNT).toBe('peac.payment.amount');
-    expect(PEAC_ATTRS.PAYMENT_CURRENCY).toBe('peac.payment.currency');
-  });
-
-  it('should define duration attribute', () => {
-    expect(PEAC_ATTRS.DURATION_MS).toBe('peac.duration_ms');
-  });
-
-  it('should be readonly (const assertion)', () => {
-    // TypeScript ensures this at compile time
-    // Runtime test: object should be frozen-like
-    const keys = Object.keys(PEAC_ATTRS);
-    expect(keys.length).toBeGreaterThan(0);
-
-    // All values should be strings
-    for (const key of keys) {
-      expect(typeof PEAC_ATTRS[key as keyof typeof PEAC_ATTRS]).toBe('string');
-    }
-  });
-
-  it('should use peac. prefix consistently', () => {
-    const peacPrefixed = Object.values(PEAC_ATTRS).filter((v) => v.startsWith('peac.'));
-    const otherPrefixed = Object.values(PEAC_ATTRS).filter((v) => !v.startsWith('peac.'));
-
-    // Most should be peac. prefixed
-    expect(peacPrefixed.length).toBeGreaterThan(otherPrefixed.length);
-
-    // HTTP should use standard OTel conventions
-    expect(otherPrefixed).toContain('http.request.method');
-    expect(otherPrefixed).toContain('url.path');
-  });
-});
-
-describe('PEAC_EVENTS', () => {
-  it('should define all event names', () => {
-    expect(PEAC_EVENTS.RECEIPT_ISSUED).toBe('peac.receipt.issued');
-    expect(PEAC_EVENTS.RECEIPT_VERIFIED).toBe('peac.receipt.verified');
-    expect(PEAC_EVENTS.ACCESS_DECISION).toBe('peac.access.decision');
-  });
-
-  it('should use peac. prefix', () => {
-    for (const event of Object.values(PEAC_EVENTS)) {
-      expect(event.startsWith('peac.')).toBe(true);
-    }
-  });
-});
-
-describe('PEAC_METRICS', () => {
-  it('should define counter metrics', () => {
-    expect(PEAC_METRICS.RECEIPTS_ISSUED).toBe('peac.receipts.issued');
-    expect(PEAC_METRICS.RECEIPTS_VERIFIED).toBe('peac.receipts.verified');
-    expect(PEAC_METRICS.ACCESS_DECISIONS).toBe('peac.access.decisions');
-  });
-
-  it('should define histogram metrics', () => {
-    expect(PEAC_METRICS.ISSUE_DURATION).toBe('peac.issue.duration');
-    expect(PEAC_METRICS.VERIFY_DURATION).toBe('peac.verify.duration');
-  });
-
-  it('should use peac. prefix', () => {
-    for (const metric of Object.values(PEAC_METRICS)) {
-      expect(metric.startsWith('peac.')).toBe(true);
-    }
-  });
-});
-
-describe('TRACE_CONTEXT_EXTENSIONS', () => {
-  it('should use w3c/ namespace (vendor-neutral)', () => {
-    expect(TRACE_CONTEXT_EXTENSIONS.TRACEPARENT).toBe('w3c/traceparent');
-    expect(TRACE_CONTEXT_EXTENSIONS.TRACESTATE).toBe('w3c/tracestate');
-  });
-
-  it('should match extension key pattern', () => {
-    // Pattern: ^[a-z0-9_.-]+/[a-z0-9_.-]+$
-    const pattern = /^[a-z0-9_.-]+\/[a-z0-9_.-]+$/;
-
-    expect(pattern.test(TRACE_CONTEXT_EXTENSIONS.TRACEPARENT)).toBe(true);
-    expect(pattern.test(TRACE_CONTEXT_EXTENSIONS.TRACESTATE)).toBe(true);
-  });
-
-  it('should NOT use io.opentelemetry namespace', () => {
-    // Vendor-neutral: w3c/ not io.opentelemetry/
-    for (const key of Object.values(TRACE_CONTEXT_EXTENSIONS)) {
-      expect(key.startsWith('io.opentelemetry')).toBe(false);
-    }
-  });
-});

package/tests/noop.test.ts

@@ -1,109 +0,0 @@
-/**
- * @peac/telemetry - No-op provider tests
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { noopProvider } from '../src/noop.js';
-import type { TelemetryProvider } from '../src/types.js';
-
-describe('noopProvider', () => {
-  it('should implement TelemetryProvider interface', () => {
-    const provider: TelemetryProvider = noopProvider;
-
-    expect(typeof provider.onReceiptIssued).toBe('function');
-    expect(typeof provider.onReceiptVerified).toBe('function');
-    expect(typeof provider.onAccessDecision).toBe('function');
-  });
-
-  it('should not throw on onReceiptIssued', () => {
-    expect(() =>
-      noopProvider.onReceiptIssued({
-        receiptHash: 'sha256:test',
-      })
-    ).not.toThrow();
-  });
-
-  it('should not throw on onReceiptVerified', () => {
-    expect(() =>
-      noopProvider.onReceiptVerified({
-        receiptHash: 'sha256:test',
-        valid: true,
-      })
-    ).not.toThrow();
-  });
-
-  it('should not throw on onAccessDecision', () => {
-    expect(() =>
-      noopProvider.onAccessDecision({
-        decision: 'allow',
-      })
-    ).not.toThrow();
-  });
-
-  it('should return undefined from all methods', () => {
-    const issued = noopProvider.onReceiptIssued({
-      receiptHash: 'sha256:test',
-    });
-    const verified = noopProvider.onReceiptVerified({
-      receiptHash: 'sha256:test',
-      valid: true,
-    });
-    const decision = noopProvider.onAccessDecision({
-      decision: 'allow',
-    });
-
-    expect(issued).toBeUndefined();
-    expect(verified).toBeUndefined();
-    expect(decision).toBeUndefined();
-  });
-
-  it('should handle complex input without errors', () => {
-    expect(() =>
-      noopProvider.onReceiptIssued({
-        receiptHash: 'sha256:complex',
-        policyHash: 'sha256:policy',
-        issuer: 'https://api.example.com',
-        kid: '2025-01-01T00:00:00Z',
-        http: { method: 'POST', path: '/api/v1/resource' },
-        durationMs: 150,
-      })
-    ).not.toThrow();
-
-    expect(() =>
-      noopProvider.onReceiptVerified({
-        receiptHash: 'sha256:complex',
-        issuer: 'https://api.example.com',
-        kid: '2025-01-01',
-        valid: false,
-        reasonCode: 'SIGNATURE_INVALID',
-        http: { method: 'GET', path: '/verify' },
-        durationMs: 25,
-      })
-    ).not.toThrow();
-
-    expect(() =>
-      noopProvider.onAccessDecision({
-        receiptHash: 'sha256:complex',
-        policyHash: 'sha256:policy',
-        decision: 'deny',
-        reasonCode: 'INSUFFICIENT_PAYMENT',
-        payment: { rail: 'stripe', amount: 500, currency: 'USD' },
-        http: { method: 'POST', path: '/protected' },
-      })
-    ).not.toThrow();
-  });
-
-  it('should be usable as default provider', () => {
-    // Simulate setting as default
-    let currentProvider: TelemetryProvider | undefined = noopProvider;
-
-    // Should work without errors
-    currentProvider.onReceiptIssued({ receiptHash: 'sha256:test' });
-    currentProvider.onReceiptVerified({ receiptHash: 'sha256:test', valid: true });
-    currentProvider.onAccessDecision({ decision: 'allow' });
-
-    // Should be replaceable
-    currentProvider = undefined;
-    expect(currentProvider).toBeUndefined();
-  });
-});

package/tests/provider.test.ts

@@ -1,223 +0,0 @@
-/**
- * @peac/telemetry - Provider registry tests
- */
-
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import {
-  providerRef,
-  setTelemetryProvider,
-  getTelemetryProvider,
-  isTelemetryEnabled,
-} from '../src/provider.js';
-import { noopProvider } from '../src/noop.js';
-import type { TelemetryProvider } from '../src/types.js';
-
-describe('providerRef', () => {
-  beforeEach(() => {
-    // Reset provider before each test
-    providerRef.current = undefined;
-  });
-
-  it('should start with undefined (disabled)', () => {
-    expect(providerRef.current).toBeUndefined();
-  });
-
-  it('should allow direct assignment', () => {
-    providerRef.current = noopProvider;
-    expect(providerRef.current).toBe(noopProvider);
-  });
-
-  it('should allow setting to undefined', () => {
-    providerRef.current = noopProvider;
-    providerRef.current = undefined;
-    expect(providerRef.current).toBeUndefined();
-  });
-});
-
-describe('setTelemetryProvider', () => {
-  beforeEach(() => {
-    providerRef.current = undefined;
-  });
-
-  it('should set the provider', () => {
-    setTelemetryProvider(noopProvider);
-    expect(providerRef.current).toBe(noopProvider);
-  });
-
-  it('should allow undefined to disable', () => {
-    setTelemetryProvider(noopProvider);
-    setTelemetryProvider(undefined);
-    expect(providerRef.current).toBeUndefined();
-  });
-
-  it('should be idempotent', () => {
-    setTelemetryProvider(noopProvider);
-    setTelemetryProvider(noopProvider);
-    setTelemetryProvider(noopProvider);
-    expect(providerRef.current).toBe(noopProvider);
-  });
-
-  it('should allow replacing provider', () => {
-    const provider1: TelemetryProvider = {
-      onReceiptIssued: vi.fn(),
-      onReceiptVerified: vi.fn(),
-      onAccessDecision: vi.fn(),
-    };
-
-    const provider2: TelemetryProvider = {
-      onReceiptIssued: vi.fn(),
-      onReceiptVerified: vi.fn(),
-      onAccessDecision: vi.fn(),
-    };
-
-    setTelemetryProvider(provider1);
-    expect(providerRef.current).toBe(provider1);
-
-    setTelemetryProvider(provider2);
-    expect(providerRef.current).toBe(provider2);
-  });
-
-  it('should not throw', () => {
-    expect(() => setTelemetryProvider(noopProvider)).not.toThrow();
-    expect(() => setTelemetryProvider(undefined)).not.toThrow();
-  });
-});
-
-describe('getTelemetryProvider', () => {
-  beforeEach(() => {
-    providerRef.current = undefined;
-  });
-
-  it('should return undefined when no provider set', () => {
-    expect(getTelemetryProvider()).toBeUndefined();
-  });
-
-  it('should return the current provider', () => {
-    setTelemetryProvider(noopProvider);
-    expect(getTelemetryProvider()).toBe(noopProvider);
-  });
-
-  it('should return same value as providerRef.current', () => {
-    setTelemetryProvider(noopProvider);
-    expect(getTelemetryProvider()).toBe(providerRef.current);
-  });
-});
-
-describe('isTelemetryEnabled', () => {
-  beforeEach(() => {
-    providerRef.current = undefined;
-  });
-
-  it('should return false when disabled', () => {
-    expect(isTelemetryEnabled()).toBe(false);
-  });
-
-  it('should return true when provider set', () => {
-    setTelemetryProvider(noopProvider);
-    expect(isTelemetryEnabled()).toBe(true);
-  });
-
-  it('should return false after disabling', () => {
-    setTelemetryProvider(noopProvider);
-    setTelemetryProvider(undefined);
-    expect(isTelemetryEnabled()).toBe(false);
-  });
-});
-
-describe('hot path pattern', () => {
-  beforeEach(() => {
-    providerRef.current = undefined;
-  });
-
-  it('should skip telemetry when disabled', () => {
-    const mockFn = vi.fn();
-
-    // Hot path pattern
-    const p = providerRef.current;
-    if (p) {
-      mockFn();
-    }
-
-    expect(mockFn).not.toHaveBeenCalled();
-  });
-
-  it('should call telemetry when enabled', () => {
-    const mockProvider: TelemetryProvider = {
-      onReceiptIssued: vi.fn(),
-      onReceiptVerified: vi.fn(),
-      onAccessDecision: vi.fn(),
-    };
-
-    setTelemetryProvider(mockProvider);
-
-    // Hot path pattern
-    const p = providerRef.current;
-    if (p) {
-      p.onReceiptIssued({ receiptHash: 'sha256:test' });
-    }
-
-    expect(mockProvider.onReceiptIssued).toHaveBeenCalledWith({
-      receiptHash: 'sha256:test',
-    });
-  });
-
-  it('should guard against throwing providers', () => {
-    const throwingProvider: TelemetryProvider = {
-      onReceiptIssued: () => {
-        throw new Error('Provider error');
-      },
-      onReceiptVerified: vi.fn(),
-      onAccessDecision: vi.fn(),
-    };
-
-    setTelemetryProvider(throwingProvider);
-
-    // Hot path pattern with guard
-    const p = providerRef.current;
-    if (p) {
-      try {
-        p.onReceiptIssued({ receiptHash: 'sha256:test' });
-      } catch {
-        // Telemetry MUST NOT break core flow - swallow silently
-      }
-    }
-
-    // Should not throw, test passes if we get here
-    expect(true).toBe(true);
-  });
-
-  it('should have zero overhead when disabled (structural)', () => {
-    // This test documents the performance contract structurally
-    // When providerRef.current is undefined, no provider methods are called
-    // Time-based assertions are avoided to prevent CI flakes
-
-    const iterations = 1000;
-    let callCount = 0;
-
-    for (let i = 0; i < iterations; i++) {
-      const p = providerRef.current;
-      if (p) {
-        callCount++;
-      }
-    }
-
-    // Structural assertion: no calls when disabled
-    expect(callCount).toBe(0);
-    // The pattern above is the only overhead (single truthiness check)
-  });
-});
-
-describe('concurrent access', () => {
-  beforeEach(() => {
-    providerRef.current = undefined;
-  });
-
-  it('should handle rapid enable/disable', () => {
-    for (let i = 0; i < 100; i++) {
-      setTelemetryProvider(noopProvider);
-      expect(isTelemetryEnabled()).toBe(true);
-      setTelemetryProvider(undefined);
-      expect(isTelemetryEnabled()).toBe(false);
-    }
-  });
-});