@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/cjs/trace-context.js

@@ -1 +1,424 @@
-"use strict";var TraceFlags;Object.defineProperty(exports,"__esModule",{value:!0}),exports.TraceContext=exports.TraceFlags=exports.TRACE_VERSION=exports.TRACESTATE_HEADER=exports.TRACEPARENT_HEADER=void 0,exports.generateTraceId=generateTraceId,exports.generateSpanId=generateSpanId,exports.validateTraceId=validateTraceId,exports.validateSpanId=validateSpanId,exports.parseTraceparent=parseTraceparent,exports.parseTracestate=parseTracestate,exports.TRACEPARENT_HEADER="traceparent",exports.TRACESTATE_HEADER="tracestate",exports.TRACE_VERSION="00",function(t){t[t.NONE=0]="NONE",t[t.SAMPLED=1]="SAMPLED"}(TraceFlags||(exports.TraceFlags=TraceFlags={}));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=exports.TRACE_VERSION,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(exports.TRACEPARENT_HEADER):t[exports.TRACEPARENT_HEADER];if(!e)return null;const r=parseTraceparent(e);if(!r)return null;const a=t instanceof Headers?t.get(exports.TRACESTATE_HEADER):t[exports.TRACESTATE_HEADER],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(exports.TRACEPARENT_HEADER,e),this.traceState.length>0&&t.set(exports.TRACESTATE_HEADER,this.toTracestate())):(t[exports.TRACEPARENT_HEADER]=e,this.traceState.length>0&&(t[exports.TRACESTATE_HEADER]=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()}}}function generateTraceId(){return generateRandomHex(32)}function generateSpanId(){return generateRandomHex(16)}function validateTraceId(t){return"string"==typeof t&&(32===t.length&&(!!/^[a-f0-9]{32}$/.test(t)&&"00000000000000000000000000000000"!==t))}function validateSpanId(t){return"string"==typeof t&&(16===t.length&&(!!/^[a-f0-9]{16}$/.test(t)&&"0000000000000000"!==t))}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)}}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.")}}exports.TraceContext=TraceContext;
+"use strict";
+/**
+ * @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();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceContext = exports.TraceFlags = exports.TRACE_VERSION = exports.TRACESTATE_HEADER = exports.TRACEPARENT_HEADER = void 0;
+exports.generateTraceId = generateTraceId;
+exports.generateSpanId = generateSpanId;
+exports.validateTraceId = validateTraceId;
+exports.validateSpanId = validateSpanId;
+exports.parseTraceparent = parseTraceparent;
+exports.parseTracestate = parseTracestate;
+/**
+ * W3C Trace Context specification constants
+ */
+exports.TRACEPARENT_HEADER = 'traceparent';
+exports.TRACESTATE_HEADER = 'tracestate';
+/**
+ * Trace context version (currently only 00 is supported)
+ */
+exports.TRACE_VERSION = '00';
+/**
+ * Trace flags
+ */
+var TraceFlags;
+(function (TraceFlags) {
+    /** Not sampled */
+    TraceFlags[TraceFlags["NONE"] = 0] = "NONE";
+    /** Sampled */
+    TraceFlags[TraceFlags["SAMPLED"] = 1] = "SAMPLED";
+})(TraceFlags || (exports.TraceFlags = TraceFlags = {}));
+/**
+ * W3C Trace Context implementation
+ *
+ * Represents a single point in a distributed trace with parent-child relationships.
+ */
+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 = exports.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(exports.TRACEPARENT_HEADER)
+            : headers[exports.TRACEPARENT_HEADER];
+        if (!traceparent)
+            return null;
+        const spec = parseTraceparent(traceparent);
+        if (!spec)
+            return null;
+        // Extract tracestate
+        const tracestateValue = headers instanceof Headers
+            ? headers.get(exports.TRACESTATE_HEADER)
+            : headers[exports.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(exports.TRACEPARENT_HEADER, traceparent);
+            if (this.traceState.length > 0) {
+                headers.set(exports.TRACESTATE_HEADER, this.toTracestate());
+            }
+        }
+        else {
+            headers[exports.TRACEPARENT_HEADER] = traceparent;
+            if (this.traceState.length > 0) {
+                headers[exports.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(),
+        };
+    }
+}
+exports.TraceContext = TraceContext;
+/**
+ * Generate a random trace ID (32 hex characters)
+ *
+ * @returns 32-character hex string
+ */
+function generateTraceId() {
+    return generateRandomHex(32);
+}
+/**
+ * Generate a random span ID (16 hex characters)
+ *
+ * @returns 16-character hex string
+ */
+function generateSpanId() {
+    return generateRandomHex(16);
+}
+/**
+ * Validate trace ID format
+ *
+ * @param traceId - Trace ID to validate
+ * @returns True if valid
+ */
+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
+ */
+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
+ */
+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
+ */
+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.');
+    }
+}