@private.me/xbind 3.0.2 → 3.0.4

package/dist-standalone/trace-context.js

@@ -1,414 +1 @@
-/**
- * @module trace-context
- * W3C Trace Context implementation for distributed tracing
- *
- * Implements the W3C Trace Context specification for distributed tracing across
- * xBind agent operations, enabling correlation of requests across service boundaries.
- *
- * Standard: https://www.w3.org/TR/trace-context/
- *
- * Headers:
- * - `traceparent`: Required header with version, trace-id, parent-id, and trace-flags
- * - `tracestate`: Optional vendor-specific state
- *
- * Format: `{version}-{trace-id}-{parent-id}-{trace-flags}`
- * Example: `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`
- *
- * Usage:
- * ```typescript
- * import { TraceContext } from '@private.me/xbind';
- *
- * // Create a new trace context
- * const ctx = TraceContext.create();
- *
- * // Attach to request headers
- * const headers = new Headers();
- * ctx.inject(headers);
- *
- * // Extract from incoming headers
- * const incomingCtx = TraceContext.extract(headers);
- *
- * // Create child span
- * const childCtx = incomingCtx.createChild();
- * ```
- */
-/**
- * W3C Trace Context specification constants
- */
-export const TRACEPARENT_HEADER = 'traceparent';
-export const TRACESTATE_HEADER = 'tracestate';
-/**
- * Trace context version (currently only 00 is supported)
- */
-export const TRACE_VERSION = '00';
-/**
- * Trace flags
- */
-export var TraceFlags;
-(function (TraceFlags) {
-    /** Not sampled */
-    TraceFlags[TraceFlags["NONE"] = 0] = "NONE";
-    /** Sampled */
-    TraceFlags[TraceFlags["SAMPLED"] = 1] = "SAMPLED";
-})(TraceFlags || (TraceFlags = {}));
-/**
- * W3C Trace Context implementation
- *
- * Represents a single point in a distributed trace with parent-child relationships.
- */
-export class TraceContext {
-    /** W3C version (always '00' for now) */
-    version;
-    /** Trace ID (32 hex characters, 16 bytes) */
-    traceId;
-    /** Parent span ID (16 hex characters, 8 bytes) */
-    parentId;
-    /** Trace flags (8-bit field) */
-    traceFlags;
-    /** Vendor-specific trace state */
-    traceState;
-    /**
-     * Create a trace context
-     *
-     * @param traceId - 32-character hex trace ID
-     * @param parentId - 16-character hex parent span ID
-     * @param traceFlags - 8-bit trace flags
-     * @param traceState - Optional vendor-specific state
-     */
-    constructor(traceId, parentId, traceFlags = TraceFlags.SAMPLED, traceState = []) {
-        if (!validateTraceId(traceId)) {
-            throw new Error(`Invalid trace ID: ${traceId}. Must be 32 hex characters.`);
-        }
-        if (!validateSpanId(parentId)) {
-            throw new Error(`Invalid parent ID: ${parentId}. Must be 16 hex characters.`);
-        }
-        if (traceFlags < 0 || traceFlags > 255) {
-            throw new Error(`Invalid trace flags: ${traceFlags}. Must be 0-255.`);
-        }
-        this.version = TRACE_VERSION;
-        this.traceId = traceId;
-        this.parentId = parentId;
-        this.traceFlags = traceFlags;
-        this.traceState = traceState;
-    }
-    /**
-     * Create a new root trace context
-     *
-     * Generates a new trace ID and parent ID for a new trace.
-     *
-     * @param sampled - Whether this trace should be sampled
-     * @returns New trace context
-     *
-     * @example
-     * ```typescript
-     * const ctx = TraceContext.create();
-     * console.log(ctx.traceId); // => "4bf92f3577b34da6a3ce929d0e0e4736"
-     * ```
-     */
-    static create(sampled = true) {
-        const traceId = generateTraceId();
-        const parentId = generateSpanId();
-        const flags = sampled ? TraceFlags.SAMPLED : TraceFlags.NONE;
-        return new TraceContext(traceId, parentId, flags);
-    }
-    /**
-     * Extract trace context from headers
-     *
-     * Parses the traceparent and tracestate headers according to W3C spec.
-     *
-     * @param headers - Headers object or plain object
-     * @returns Trace context if found, null otherwise
-     *
-     * @example
-     * ```typescript
-     * const headers = new Headers({
-     *   traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'
-     * });
-     * const ctx = TraceContext.extract(headers);
-     * ```
-     */
-    static extract(headers) {
-        const traceparent = headers instanceof Headers
-            ? headers.get(TRACEPARENT_HEADER)
-            : headers[TRACEPARENT_HEADER];
-        if (!traceparent)
-            return null;
-        const spec = parseTraceparent(traceparent);
-        if (!spec)
-            return null;
-        // Extract tracestate
-        const tracestateValue = headers instanceof Headers
-            ? headers.get(TRACESTATE_HEADER)
-            : headers[TRACESTATE_HEADER];
-        const traceState = tracestateValue ? parseTracestate(tracestateValue) : [];
-        return new TraceContext(spec.traceId, spec.parentId, spec.traceFlags, traceState);
-    }
-    /**
-     * Inject trace context into headers
-     *
-     * Adds traceparent and tracestate headers to the provided headers object.
-     *
-     * @param headers - Headers to modify
-     * @returns Modified headers
-     *
-     * @example
-     * ```typescript
-     * const ctx = TraceContext.create();
-     * const headers = new Headers();
-     * ctx.inject(headers);
-     * ```
-     */
-    inject(headers) {
-        const traceparent = this.toTraceparent();
-        if (headers instanceof Headers) {
-            headers.set(TRACEPARENT_HEADER, traceparent);
-            if (this.traceState.length > 0) {
-                headers.set(TRACESTATE_HEADER, this.toTracestate());
-            }
-        }
-        else {
-            headers[TRACEPARENT_HEADER] = traceparent;
-            if (this.traceState.length > 0) {
-                headers[TRACESTATE_HEADER] = this.toTracestate();
-            }
-        }
-        return headers;
-    }
-    /**
-     * Create a child trace context
-     *
-     * Generates a new parent ID (span ID) while keeping the same trace ID.
-     * This represents a new span in the same trace.
-     *
-     * @param sampled - Override sampling decision (defaults to parent's decision)
-     * @returns New child trace context
-     *
-     * @example
-     * ```typescript
-     * const parent = TraceContext.create();
-     * const child = parent.createChild();
-     * console.log(parent.traceId === child.traceId); // => true
-     * console.log(parent.parentId === child.parentId); // => false
-     * ```
-     */
-    createChild(sampled) {
-        const newParentId = generateSpanId();
-        const flags = sampled !== undefined
-            ? (sampled ? TraceFlags.SAMPLED : TraceFlags.NONE)
-            : this.traceFlags;
-        return new TraceContext(this.traceId, newParentId, flags, this.traceState);
-    }
-    /**
-     * Format as traceparent header value
-     *
-     * @returns traceparent string
-     */
-    toTraceparent() {
-        const flags = this.traceFlags.toString(16).padStart(2, '0');
-        return `${this.version}-${this.traceId}-${this.parentId}-${flags}`;
-    }
-    /**
-     * Format as tracestate header value
-     *
-     * @returns tracestate string
-     */
-    toTracestate() {
-        return this.traceState
-            .map(({ key, value }) => `${key}=${value}`)
-            .join(',');
-    }
-    /**
-     * Check if this trace is sampled
-     *
-     * @returns True if sampled
-     */
-    isSampled() {
-        return (this.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED;
-    }
-    /**
-     * Add or update tracestate entry
-     *
-     * @param key - Vendor key (format: vendor[@system])
-     * @param value - State value
-     * @returns New trace context with updated state
-     *
-     * @example
-     * ```typescript
-     * const ctx = TraceContext.create();
-     * const updated = ctx.withTracestate('private.me', 'did:key:z6Mk...');
-     * ```
-     */
-    withTracestate(key, value) {
-        const newState = this.traceState.filter((e) => e.key !== key);
-        newState.unshift({ key, value });
-        return new TraceContext(this.traceId, this.parentId, this.traceFlags, newState);
-    }
-    /**
-     * Get tracestate value by key
-     *
-     * @param key - Vendor key
-     * @returns State value or undefined
-     */
-    getTracestate(key) {
-        const entry = this.traceState.find((e) => e.key === key);
-        return entry?.value;
-    }
-    /**
-     * Convert to plain object
-     *
-     * @returns Plain object representation
-     */
-    toObject() {
-        return {
-            version: this.version,
-            traceId: this.traceId,
-            parentId: this.parentId,
-            traceFlags: this.traceFlags,
-            traceState: [...this.traceState],
-            sampled: this.isSampled(),
-        };
-    }
-}
-/**
- * Generate a random trace ID (32 hex characters)
- *
- * @returns 32-character hex string
- */
-export function generateTraceId() {
-    return generateRandomHex(32);
-}
-/**
- * Generate a random span ID (16 hex characters)
- *
- * @returns 16-character hex string
- */
-export function generateSpanId() {
-    return generateRandomHex(16);
-}
-/**
- * Validate trace ID format
- *
- * @param traceId - Trace ID to validate
- * @returns True if valid
- */
-export function validateTraceId(traceId) {
-    if (typeof traceId !== 'string')
-        return false;
-    if (traceId.length !== 32)
-        return false;
-    if (!/^[a-f0-9]{32}$/.test(traceId))
-        return false;
-    // Trace ID must not be all zeros
-    if (traceId === '00000000000000000000000000000000')
-        return false;
-    return true;
-}
-/**
- * Validate span ID format
- *
- * @param spanId - Span ID to validate
- * @returns True if valid
- */
-export function validateSpanId(spanId) {
-    if (typeof spanId !== 'string')
-        return false;
-    if (spanId.length !== 16)
-        return false;
-    if (!/^[a-f0-9]{16}$/.test(spanId))
-        return false;
-    // Span ID must not be all zeros
-    if (spanId === '0000000000000000')
-        return false;
-    return true;
-}
-/**
- * Parse traceparent header value
- *
- * @param traceparent - Header value
- * @returns Parsed components or null if invalid
- */
-export function parseTraceparent(traceparent) {
-    if (typeof traceparent !== 'string')
-        return null;
-    const parts = traceparent.split('-');
-    if (parts.length !== 4)
-        return null;
-    const [version, traceId, parentId, flagsStr] = parts;
-    // Version validation
-    if (version !== '00')
-        return null;
-    // Trace ID validation
-    if (!validateTraceId(traceId ?? ''))
-        return null;
-    // Parent ID validation
-    if (!validateSpanId(parentId ?? ''))
-        return null;
-    // Flags validation
-    if (!flagsStr || flagsStr.length !== 2)
-        return null;
-    if (!/^[a-f0-9]{2}$/.test(flagsStr))
-        return null;
-    const traceFlags = parseInt(flagsStr, 16);
-    return {
-        version: version ?? '00',
-        traceId: traceId ?? '',
-        parentId: parentId ?? '',
-        traceFlags,
-    };
-}
-/**
- * Parse tracestate header value
- *
- * @param tracestate - Header value
- * @returns Array of key-value pairs
- */
-export function parseTracestate(tracestate) {
-    if (!tracestate)
-        return [];
-    const entries = [];
-    const parts = tracestate.split(',');
-    for (const part of parts) {
-        const trimmed = part.trim();
-        const eqIndex = trimmed.indexOf('=');
-        if (eqIndex === -1)
-            continue;
-        const key = trimmed.substring(0, eqIndex).trim();
-        const value = trimmed.substring(eqIndex + 1).trim();
-        if (key && value) {
-            entries.push({ key, value });
-        }
-    }
-    return entries;
-}
-/**
- * Generate random hex string
- *
- * Uses Web Crypto API in browser, Node.js crypto in Node.
- *
- * @param length - Number of hex characters to generate
- * @returns Random hex string
- *
- * @internal
- */
-function generateRandomHex(length) {
-    const bytes = Math.ceil(length / 2);
-    // Try Web Crypto API (browser)
-    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-        const buffer = new Uint8Array(bytes);
-        crypto.getRandomValues(buffer);
-        return Array.from(buffer)
-            .map((b) => b.toString(16).padStart(2, '0'))
-            .join('')
-            .substring(0, length);
-    }
-    // Try Node.js crypto
-    try {
-        const nodeCrypto = require('node:crypto');
-        return nodeCrypto.randomBytes(bytes).toString('hex').substring(0, length);
-    }
-    catch {
-        // SECURITY: Never fall back to Math.random() in production (OWASP violation)
-        throw new Error('Cryptographic random generation unavailable. ' +
-            'Install crypto polyfill or use environment with crypto support.');
-    }
-}
+export const TRACEPARENT_HEADER="traceparent";export const TRACESTATE_HEADER="tracestate";export const TRACE_VERSION="00";export var TraceFlags;!function(t){t[t.NONE=0]="NONE",t[t.SAMPLED=1]="SAMPLED"}(TraceFlags||(TraceFlags={}));export class TraceContext{version;traceId;parentId;traceFlags;traceState;constructor(t,e,r=TraceFlags.SAMPLED,a=[]){if(!validateTraceId(t))throw new Error(`Invalid trace ID: ${t}. Must be 32 hex characters.`);if(!validateSpanId(e))throw new Error(`Invalid parent ID: ${e}. Must be 16 hex characters.`);if(r<0||r>255)throw new Error(`Invalid trace flags: ${r}. Must be 0-255.`);this.version="00",this.traceId=t,this.parentId=e,this.traceFlags=r,this.traceState=a}static create(t=!0){const e=generateTraceId(),r=generateSpanId(),a=t?TraceFlags.SAMPLED:TraceFlags.NONE;return new TraceContext(e,r,a)}static extract(t){const e=t instanceof Headers?t.get("traceparent"):t.traceparent;if(!e)return null;const r=parseTraceparent(e);if(!r)return null;const a=t instanceof Headers?t.get("tracestate"):t.tracestate,n=a?parseTracestate(a):[];return new TraceContext(r.traceId,r.parentId,r.traceFlags,n)}inject(t){const e=this.toTraceparent();return t instanceof Headers?(t.set("traceparent",e),this.traceState.length>0&&t.set("tracestate",this.toTracestate())):(t.traceparent=e,this.traceState.length>0&&(t.tracestate=this.toTracestate())),t}createChild(t){const e=generateSpanId(),r=void 0!==t?t?TraceFlags.SAMPLED:TraceFlags.NONE:this.traceFlags;return new TraceContext(this.traceId,e,r,this.traceState)}toTraceparent(){const t=this.traceFlags.toString(16).padStart(2,"0");return`${this.version}-${this.traceId}-${this.parentId}-${t}`}toTracestate(){return this.traceState.map(({key:t,value:e})=>`${t}=${e}`).join(",")}isSampled(){return(this.traceFlags&TraceFlags.SAMPLED)===TraceFlags.SAMPLED}withTracestate(t,e){const r=this.traceState.filter(e=>e.key!==t);return r.unshift({key:t,value:e}),new TraceContext(this.traceId,this.parentId,this.traceFlags,r)}getTracestate(t){const e=this.traceState.find(e=>e.key===t);return e?.value}toObject(){return{version:this.version,traceId:this.traceId,parentId:this.parentId,traceFlags:this.traceFlags,traceState:[...this.traceState],sampled:this.isSampled()}}}export function generateTraceId(){return generateRandomHex(32)}export function generateSpanId(){return generateRandomHex(16)}export function validateTraceId(t){return"string"==typeof t&&(32===t.length&&(!!/^[a-f0-9]{32}$/.test(t)&&"00000000000000000000000000000000"!==t))}export function validateSpanId(t){return"string"==typeof t&&(16===t.length&&(!!/^[a-f0-9]{16}$/.test(t)&&"0000000000000000"!==t))}export function parseTraceparent(t){if("string"!=typeof t)return null;const e=t.split("-");if(4!==e.length)return null;const[r,a,n,s]=e;if("00"!==r)return null;if(!validateTraceId(a??""))return null;if(!validateSpanId(n??""))return null;if(!s||2!==s.length)return null;if(!/^[a-f0-9]{2}$/.test(s))return null;return{version:r??"00",traceId:a??"",parentId:n??"",traceFlags:parseInt(s,16)}}export function parseTracestate(t){if(!t)return[];const e=[],r=t.split(",");for(const t of r){const r=t.trim(),a=r.indexOf("=");if(-1===a)continue;const n=r.substring(0,a).trim(),s=r.substring(a+1).trim();n&&s&&e.push({key:n,value:s})}return e}function generateRandomHex(t){const e=Math.ceil(t/2);if("undefined"!=typeof crypto&&crypto.getRandomValues){const r=new Uint8Array(e);return crypto.getRandomValues(r),Array.from(r).map(t=>t.toString(16).padStart(2,"0")).join("").substring(0,t)}try{return require("node:crypto").randomBytes(e).toString("hex").substring(0,t)}catch{throw new Error("Cryptographic random generation unavailable. Install crypto polyfill or use environment with crypto support.")}}