@longarc/mdash 3.1.2 → 3.1.3

package/src/context/fragment.ts

@@ -0,0 +1,454 @@
+/**
+ * Caret — Context Fragment Implementation
+ * @module @longarcstudios/caret/fragment
+ * 
+ * The atomic unit of structured context.
+ * Immutable, sealed, attributable.
+ */
+
+import type {
+  ContextFragment,
+  FragmentId,
+  Timestamp,
+  SemanticUnit,
+  SemanticType,
+  TokenCount,
+  Constraint,
+  ProvenanceChain,
+  Attribution,
+  SourceURI,
+  TrustLevel,
+} from './types.js';
+import { sha256Object } from './crypto/hash.js';
+import { sealFragment, verifyFragmentSeal } from './crypto/hmac.js';
+import { 
+  createProvenanceRecord, 
+  createProvenanceChain,
+  extendProvenanceChain,
+} from './provenance.js';
+
+// ============================================================================
+// UUID GENERATION
+// ============================================================================
+
+/**
+ * Generate a UUID v4.
+ * Uses crypto.randomUUID if available, falls back to crypto.getRandomValues.
+ * SECURITY: Never falls back to Math.random — fails instead.
+ */
+function generateUUID(): FragmentId {
+  // Preferred: native randomUUID
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID() as FragmentId;
+  }
+  
+  // Fallback: manual UUID from getRandomValues (still cryptographically secure)
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    
+    // Set version (4) and variant (RFC4122)
+    bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+    bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+    
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` as FragmentId;
+  }
+  
+  // SECURITY: Do not fall back to Math.random — fail secure
+  throw new Error('Cryptographically secure random number generator not available');
+}
+
+// ============================================================================
+// TOKEN COUNTING
+// ============================================================================
+
+/** Default tokenizer: approximate cl100k_base behavior */
+function defaultTokenCount(text: string): TokenCount {
+  // Rough approximation: ~4 chars per token for English
+  // More accurate would require actual tokenizer
+  const charCount = text.length;
+  const estimate = Math.ceil(charCount / 4);
+  return estimate as TokenCount;
+}
+
+/** Tokenizer function type */
+type Tokenizer = (content: unknown) => TokenCount;
+
+/** Current tokenizer (can be replaced) */
+let currentTokenizer: Tokenizer = (content: unknown): TokenCount => {
+  const text = typeof content === 'string' 
+    ? content 
+    : JSON.stringify(content);
+  return defaultTokenCount(text);
+};
+
+/**
+ * Set a custom tokenizer function.
+ */
+export function setTokenizer(tokenizer: Tokenizer): void {
+  currentTokenizer = tokenizer;
+}
+
+/**
+ * Count tokens in content using current tokenizer.
+ */
+export function countTokens(content: unknown): TokenCount {
+  return currentTokenizer(content);
+}
+
+// ============================================================================
+// SEMANTIC UNIT
+// ============================================================================
+
+/**
+ * Create a SemanticUnit from content.
+ */
+export function createSemanticUnit<T>(
+  data: T,
+  options: {
+    type?: SemanticType;
+    compression_ratio?: number;
+  } = {}
+): SemanticUnit<T> {
+  const type = options.type ?? inferSemanticType(data);
+  const token_count = countTokens(data);
+  
+  return {
+    type,
+    data,
+    token_count,
+    compression_ratio: options.compression_ratio,
+  };
+}
+
+/**
+ * Infer semantic type from data.
+ */
+function inferSemanticType(data: unknown): SemanticType {
+  if (typeof data === 'string') {
+    return 'text';
+  }
+  
+  if (typeof data === 'object' && data !== null) {
+    // Check for special object patterns
+    if ('$ref' in data || 'uri' in data || 'url' in data) {
+      return 'reference';
+    }
+    return 'structured';
+  }
+  
+  return 'text';
+}
+
+// ============================================================================
+// FRAGMENT CREATION
+// ============================================================================
+
+/** Options for creating a fragment */
+export interface CreateFragmentOptions<T = unknown> {
+  /** The content to store */
+  content: T;
+  
+  /** Source URI for provenance */
+  source: SourceURI | string;
+  
+  /** Attribution type */
+  attribution: Attribution;
+  
+  /** Trust level (0-100, optional) */
+  trust_level?: number;
+  
+  /** Constraints to apply */
+  constraints?: Constraint[];
+  
+  /** Parent fragment for provenance chain */
+  parent?: ContextFragment;
+  
+  /** Optional signature */
+  signature?: string;
+  
+  /** Semantic type override */
+  semantic_type?: SemanticType;
+  
+  /** Secret key for sealing */
+  seal_key: string;
+}
+
+/**
+ * Create a new ContextFragment.
+ * This is the primary factory function for fragments.
+ */
+export async function createFragment<T = unknown>(
+  options: CreateFragmentOptions<T>
+): Promise<ContextFragment<T>> {
+  const id = generateUUID();
+  const sealed_at = new Date().toISOString() as Timestamp;
+  
+  // Create semantic unit
+  const content = createSemanticUnit(options.content, {
+    type: options.semantic_type,
+  });
+  
+  // Create provenance
+  const record = await createProvenanceRecord({
+    source: options.source,
+    attribution: options.attribution,
+    trust_level: options.trust_level,
+    parent_hash: options.parent?.hash ?? null,
+    signature: options.signature,
+  });
+  
+  let provenance: ProvenanceChain;
+  if (options.parent) {
+    provenance = await extendProvenanceChain(options.parent.provenance, record);
+  } else {
+    provenance = await createProvenanceChain(record);
+  }
+  
+  // Compute content hash
+  const hash = await sha256Object({
+    content,
+    provenance,
+    sealed_at,
+  });
+  
+  // Create seal
+  const fragmentData = {
+    id,
+    hash,
+    content,
+    provenance,
+    sealed_at,
+    constraints: options.constraints ?? [],
+  };
+  
+  const seal = await sealFragment(fragmentData, options.seal_key);
+  
+  return {
+    id,
+    hash,
+    content,
+    provenance,
+    sealed_at,
+    seal,
+    constraints: options.constraints ?? [],
+    version: 'v3.1',
+  };
+}
+
+// ============================================================================
+// FRAGMENT VERIFICATION
+// ============================================================================
+
+/**
+ * Verify a fragment's integrity.
+ * Checks both the content hash and the HMAC seal.
+ */
+export async function verifyFragment(
+  fragment: ContextFragment,
+  seal_key: string
+): Promise<{
+  valid: boolean;
+  errors: string[];
+}> {
+  const errors: string[] = [];
+  
+  // Verify content hash
+  const expectedHash = await sha256Object({
+    content: fragment.content,
+    provenance: fragment.provenance,
+    sealed_at: fragment.sealed_at,
+  });
+  
+  if (expectedHash !== fragment.hash) {
+    errors.push('Content hash mismatch');
+  }
+  
+  // Verify HMAC seal
+  const sealValid = await verifyFragmentSeal(
+    {
+      id: fragment.id,
+      hash: fragment.hash,
+      content: fragment.content,
+      provenance: fragment.provenance,
+      sealed_at: fragment.sealed_at,
+      constraints: fragment.constraints,
+      seal: fragment.seal,
+    },
+    seal_key
+  );
+  
+  if (!sealValid) {
+    errors.push('HMAC seal verification failed');
+  }
+  
+  // Verify version (accept both v3.1 and legacy 1.0)
+  if (fragment.version !== 'v3.1' && fragment.version !== '1.0') {
+    errors.push(`Unknown fragment version: ${fragment.version}`);
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+// ============================================================================
+// FRAGMENT OPERATIONS
+// ============================================================================
+
+/**
+ * Derive a new fragment from an existing one.
+ * Creates a new fragment with the parent's provenance extended.
+ */
+export async function deriveFragment<T, U = T>(
+  parent: ContextFragment<T>,
+  options: {
+    content: U;
+    source: SourceURI | string;
+    attribution?: Attribution;
+    trust_level?: number;
+    constraints?: Constraint[];
+    seal_key: string;
+  }
+): Promise<ContextFragment<U>> {
+  return createFragment({
+    content: options.content,
+    source: options.source,
+    attribution: options.attribution ?? 'derived',
+    trust_level: options.trust_level,
+    constraints: [...(options.constraints ?? parent.constraints)],
+    parent,
+    seal_key: options.seal_key,
+  });
+}
+
+/**
+ * Clone a fragment with new constraints.
+ * Creates a new fragment with the same content but different constraints.
+ */
+export async function withConstraints<T>(
+  fragment: ContextFragment<T>,
+  constraints: Constraint[],
+  seal_key: string
+): Promise<ContextFragment<T>> {
+  return deriveFragment(fragment, {
+    content: fragment.content.data,
+    source: fragment.provenance.head.source,
+    attribution: 'derived',
+    constraints,
+    seal_key,
+  });
+}
+
+/**
+ * Get the age of a fragment in milliseconds.
+ */
+export function getFragmentAge(fragment: ContextFragment): number {
+  const sealed = new Date(fragment.sealed_at).getTime();
+  return Date.now() - sealed;
+}
+
+/**
+ * Check if a fragment is expired based on time constraints.
+ */
+export function isFragmentExpired(fragment: ContextFragment): boolean {
+  for (const constraint of fragment.constraints) {
+    if (constraint.kind === 'time') {
+      // Check max_age
+      if (constraint.max_age_ms !== undefined) {
+        const age = getFragmentAge(fragment);
+        if (age > constraint.max_age_ms) {
+          return true;
+        }
+      }
+      
+      // Check not_after
+      if (constraint.not_after !== undefined) {
+        const deadline = new Date(constraint.not_after).getTime();
+        if (Date.now() > deadline) {
+          return true;
+        }
+      }
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Get the trust level of a fragment (minimum in chain).
+ */
+export function getFragmentTrust(fragment: ContextFragment): TrustLevel {
+  let min = fragment.provenance.head.trust_level;
+  let current = fragment.provenance.tail;
+  
+  while (current !== null) {
+    if (current.head.trust_level < min) {
+      min = current.head.trust_level;
+    }
+    current = current.tail;
+  }
+  
+  return min;
+}
+
+// ============================================================================
+// SERIALIZATION
+// ============================================================================
+
+/**
+ * Serialize a fragment to JSON.
+ */
+export function serializeFragment(fragment: ContextFragment): string {
+  return JSON.stringify(fragment);
+}
+
+/**
+ * Sanitize an object to prevent prototype pollution.
+ * Removes __proto__, constructor, and prototype properties recursively.
+ */
+function sanitizeObject(obj: unknown): unknown {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  
+  if (Array.isArray(obj)) {
+    return obj.map(sanitizeObject);
+  }
+  
+  const sanitized: Record<string, unknown> = Object.create(null);
+  for (const key of Object.keys(obj)) {
+    // Block dangerous properties
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      continue;
+    }
+    sanitized[key] = sanitizeObject((obj as Record<string, unknown>)[key]);
+  }
+  
+  return sanitized;
+}
+
+/**
+ * Deserialize a fragment from JSON.
+ * Note: Does NOT verify integrity — call verifyFragment separately.
+ */
+export function deserializeFragment<T = unknown>(json: string): ContextFragment<T> {
+  const raw = JSON.parse(json);
+  
+  // Sanitize to prevent prototype pollution
+  const parsed = sanitizeObject(raw) as Record<string, unknown>;
+  
+  // Type validation
+  if (!parsed.id || !parsed.hash || !parsed.content || !parsed.provenance) {
+    throw new Error('Invalid fragment structure');
+  }
+  
+  if (parsed.version !== 'v3.1' && parsed.version !== '1.0') {
+    // SECURITY: Do not leak version value in error message
+    throw new Error('Unsupported fragment version');
+  }
+  
+  return parsed as unknown as ContextFragment<T>;
+}