@nekzus/liop 1.0.0-alpha.1

package/dist/index-DoW2gzBZ.d.ts

@@ -0,0 +1,566 @@
+import { z } from 'zod';
+import { M as MeshNodeConfig, a as MeshNode } from './node-B0b2vUFS.js';
+import { J as JwtValidator, S as ServerInfo, a as CallToolResult, P as Prompt, G as GetPromptRequest, d as GetPromptResult, C as CallToolRequest, T as Tool, R as Resource } from './types-lJIxBlWF.js';
+
+/**
+ * LIOP OAuth 2.1 Hybrid Auth — Configuration Types
+ *
+ * Defines the auth configuration interface consumed by LiopServerOptions.
+ * Designed for zero-friction developer experience: most values auto-resolve.
+ *
+ * Standards: NIST SP 800-207, OWASP API-A07, MCP Spec 2025-11-25
+ */
+/**
+ * Role of this node in the LIOP auth hierarchy.
+ * - "nexus": Runs the embedded Authorization Server (oidc-provider) + Resource Server.
+ * - "node": Resource Server only; validates JWTs issued by the Nexus.
+ * - "none": Auth disabled (dev mode, stdio/local transport).
+ */
+type AuthRole = "nexus" | "node" | "none";
+/**
+ * OAuth client registration for M2M (Client Credentials) flows.
+ * Used exclusively by the Nexus role.
+ */
+interface OAuthClientConfig {
+    /** Unique identifier for the OAuth client. */
+    client_id: string;
+    /** Client secret for authentication (client_secret_post). */
+    client_secret: string;
+    /** OAuth grant types allowed for this client (e.g., ["client_credentials"]). */
+    grant_types: string[];
+    /** Space-delimited scopes this client can request. */
+    scope: string;
+}
+/**
+ * LIOP Auth Configuration.
+ *
+ * Minimal surface for developers:
+ *   - Nexus node:  { role: "nexus" }
+ *   - Data node:   { role: "node" }
+ *   - Dev/stdio:   omit or { role: "none" }
+ *
+ * All other fields auto-resolve from env, DHT, or secure defaults.
+ */
+interface LiopAuthConfig {
+    /** Role of this node in the auth hierarchy. */
+    role: AuthRole;
+    /**
+     * OIDC Issuer URL. Auto-derived:
+     *   - Nexus: inferred from listen address (e.g., "http://localhost:3000")
+     *   - Node: resolved from Nexus /health endpoint
+     */
+    issuer?: string;
+    /**
+     * JWT audience claim.
+     * Default: "urn:liop:mesh:api"
+     */
+    audience?: string;
+    /**
+     * URL of the Nexus authorization server (node role only).
+     * Fallback: env.LIOP_NEXUS_URL → DHT auto-discovery.
+     */
+    nexusUrl?: string;
+    /**
+     * Required scopes for accessing this node's tools.
+     * Default: auto-derived from registered tools.
+     */
+    requiredScopes?: string[];
+    /**
+     * Pre-registered OAuth clients (nexus role only).
+     * Fallback: auto-detected from env.LIOP_OAUTH_CLIENT_ID + env.LIOP_OAUTH_CLIENT_SECRET.
+     */
+    clients?: OAuthClientConfig[];
+    /**
+     * Path to local token revocation JSON list (Resource Token Revocation List).
+     * Saved as an array of SHA-256 hashes of revoked access tokens.
+     */
+    revocationPath?: string;
+    /**
+     * Pre-shared local test token for isolated testing in non-production environments.
+     * A token matching this will bypass remote JWKS check only on this specific node.
+     */
+    localTestToken?: string;
+}
+/**
+ * Secure defaults for the OAuth subsystem.
+ * Sources: NIST SP 800-207 §3.1, NIST SP 800-63B, OWASP API-A07
+ */
+declare const AUTH_DEFAULTS: {
+    /** JWT audience claim for the LIOP mesh API. */
+    readonly audience: "urn:liop:mesh:api";
+    /** M2M token time-to-live in seconds (1 hour). */
+    readonly tokenTtlSeconds: 3600;
+    /** JWKS cache TTL in milliseconds (10 min — jose default). */
+    readonly jwksCacheTtlMs: 600000;
+    /** Minimum interval between JWKS refetches (30s — jose default). */
+    readonly jwksCooldownMs: 30000;
+    /** Clock tolerance for JWT expiration checks (mesh clock skew). */
+    readonly clockToleranceSec: 5;
+    /** JWT signing algorithm (aligned with libp2p Ed25519 PeerID curve). */
+    readonly signingAlgorithm: "EdDSA";
+};
+
+type AuditStatus = "SUCCESS" | "BLOCKED_EGRESS" | "ERROR" | "POLICY_VIOLATION";
+interface AuditEntry {
+    id: string;
+    timestamp: string;
+    traceId: string;
+    agentDid: string;
+    peerId: string;
+    toolName: string;
+    datasetHash: string;
+    fuelConsumed: number;
+    outputHash: string;
+    zkReceiptSig: string;
+    status: AuditStatus;
+    prevEntryHash: string;
+    entryHash: string;
+}
+interface AuditRecordParams {
+    timestamp?: string;
+    traceId?: string;
+    agentDid: string;
+    peerId: string;
+    toolName: string;
+    datasetHash?: string;
+    fuelConsumed: number;
+    outputHash?: string;
+    zkReceiptSig?: string;
+    status: AuditStatus;
+}
+declare const GENESIS_HASH: string;
+declare function computeEntryHash(entryWithoutHash: Omit<AuditEntry, "entryHash">): string;
+declare class AuditLogger {
+    private entries;
+    private lastEntryHash;
+    private filePath?;
+    constructor(filePath?: string);
+    recordExecution(params: AuditRecordParams): AuditEntry;
+    getEntries(): readonly AuditEntry[];
+    getEntryCount(): number;
+    verifyIntegrity(): {
+        valid: boolean;
+        totalEntries: number;
+        brokenIndex?: number;
+        reason?: string;
+    };
+    exportJsonl(): string;
+    private loadFromFile;
+}
+declare const globalAuditLogger: AuditLogger;
+
+/** Single named entity detected by the NER scanner. */
+interface NerEntity {
+    type: "person" | "place" | "organization";
+    text: string;
+}
+/** Result of an NER scan operation. */
+interface NerScanResult {
+    detected: boolean;
+    entities: NerEntity[];
+}
+/**
+ * Scans text content for named entities that may represent PII.
+ * Uses `compromise/three` for person, place, and organization detection.
+ *
+ * Designed for egress filtering — optimized for recall over precision
+ * to ensure sensitive data does not leak through aliased output keys.
+ */
+declare class NerScanner {
+    private static nlp;
+    /**
+     * Lazy loads the compromise library only when needed.
+     */
+    private getNlp;
+    /**
+     * Scans a single string value for named entities.
+     * Returns detected entities if the text contains recognizable PII.
+     */
+    scan(text: string): Promise<NerScanResult>;
+    /**
+     * Recursively scans all string values within an object/array.
+     * Stops at the first detection for performance (fail-fast).
+     */
+    scanDeep(input: unknown, seen?: WeakSet<object>): Promise<NerScanResult>;
+}
+
+/**
+ * LIOP Egress Shield Output Sanitizer (NIST SP 800-226 and OWASP DLP 2025 compliant)
+ * Recursively sanitizes execution outputs by rounding floating-point numbers
+ * and clamping negative values to zero floor where appropriate.
+ *
+ * Implements absolute immutability, returning a fresh copy of the data.
+ */
+interface OutputSanitizerConfig {
+    /** Maximum decimal places for floating-point values (default: 4) */
+    maxDecimalPlaces?: number;
+    /** Clamp negative values to zero floor (default: true) */
+    clampNonNegative?: boolean;
+}
+/**
+ * Recursively walks a JSON-like tree, rounding floats and clamping negative values.
+ *
+ * @param output - The raw or DP-modified output object/value to sanitize
+ * @param config - Sanitization parameters (rounding depth, negative clamping)
+ * @returns A sanitized deep copy of the output
+ */
+declare function sanitizeOutput(output: unknown, config?: OutputSanitizerConfig): unknown;
+
+type PiiRuleDefinition = {
+    name: string;
+    pattern: string | RegExp;
+    validator?: (match: string) => boolean;
+};
+type PiiRule = string | RegExp | PiiRuleDefinition;
+declare const PII_PATTERNS: {
+    EMAIL: PiiRuleDefinition;
+    CREDIT_CARD: PiiRuleDefinition;
+    IP_ADDRESS: PiiRuleDefinition;
+    PHONE: PiiRuleDefinition;
+    SSN: PiiRuleDefinition;
+    IBAN: PiiRuleDefinition;
+    PASSPORT_MRZ: PiiRuleDefinition;
+};
+/**
+ * Regional and Cultural Security Presets for Out-Of-The-Box compliance.
+ * Developers can override, merge, or omit these based on local laws.
+ */
+declare const PII_PRESETS: {
+    GLOBAL_STRICT: PiiRuleDefinition[];
+    US_COMPLIANT: PiiRuleDefinition[];
+    EU_GDPR: PiiRuleDefinition[];
+};
+declare class PiiScanner {
+    private patterns;
+    private forbiddenKeysSet;
+    private nerScanner;
+    /**
+     * Safelist of keys that contain forbidden substrings but are NOT PII.
+     * Prevents false positives from fuzzy matching (e.g., "grid" contains "id").
+     */
+    private static readonly KEY_SAFELIST;
+    /**
+     * Short forbidden tokens (< 4 chars) that require boundary-aware matching.
+     * Uses regex boundary detection to avoid false positives.
+     */
+    private shortTokenBoundaryPatterns;
+    /**
+     * Long forbidden tokens (>= 4 chars) that use substring containment.
+     */
+    private longForbiddenTokens;
+    constructor(patterns?: PiiRule[], forbiddenKeys?: string[], nerScanner?: NerScanner | null);
+    /**
+     * Scans any input (string, object, array) for PII violations.
+     * Returns the pattern/rule name that triggered the violation, or null if safe.
+     *
+     * Detection pipeline (fail-fast):
+     *   1. Exact key match (O(1) Set lookup)
+     *   2. Fuzzy key match (boundary detection for short tokens, substring for long)
+     *   3. Regex/algorithmic pattern match on string values
+     *   4. NER content scan on string values (if enabled)
+     */
+    scan(input: unknown, seen?: WeakSet<object>): Promise<string | null>;
+    /**
+     * Checks a key against fuzzy matching rules.
+     * Short tokens use boundary-aware regex; long tokens use substring containment.
+     */
+    private checkKeyFuzzy;
+    private checkString;
+}
+
+type ToolHandler<T extends z.ZodRawShape = z.ZodRawShape> = (args: z.infer<z.ZodObject<T>>, extra: {
+    signal?: AbortSignal;
+}) => Promise<CallToolResult>;
+interface LiopServerOptions {
+    capabilities?: Record<string, unknown>;
+    workerPool?: {
+        enabled?: boolean;
+        minThreads?: number;
+        maxThreads?: number;
+        idleTimeout?: number;
+        /** Max heap memory per worker in MB (default: 64). Prevents heap bomb DoS. */
+        maxHeapMb?: number;
+        /** Maximum number of tasks allowed in the queue. Default is "auto". */
+        maxQueue?: number | "auto";
+    };
+    security?: {
+        piiPatterns?: PiiRule[];
+        forbiddenKeys?: string[];
+        sensitiveKeys?: string[];
+        /** Enable NLP-based Named Entity Recognition scanning on output values. */
+        enableNerScanning?: boolean;
+        /** Rate limiting configuration for tool calls (OWASP A01). */
+        rateLimit?: {
+            /** Maximum calls per window per tool (default: 15). */
+            maxPerWindow?: number;
+            /** Maximum calls per window across ALL tools combined (default: 40). */
+            globalMaxPerWindow?: number;
+            /** Sliding window duration in milliseconds (default: 60000 = 1 min). */
+            windowMs?: number;
+        };
+    };
+    taxonomy?: {
+        domain?: string;
+        clearanceTier?: number;
+        executionTypes?: string[];
+    };
+    /**
+     * OAuth 2.1 Hybrid Auth configuration.
+     *
+     * Minimal usage:
+     *   - Nexus (Authorization Server): `{ role: "nexus" }`
+     *   - Data Node (Resource Server): `{ role: "node" }`
+     *   - Disabled (dev/stdio): omit or `{ role: "none" }`
+     *
+     * All other values (issuer, JWKS, audience) auto-resolve from
+     * env vars, DHT discovery, or secure defaults.
+     */
+    auth?: LiopAuthConfig;
+    /**
+     * Canonical slug for deterministic token resolution.
+     * Agents/clients resolve `LIOP_TOKEN_<tokenSlug>` from environment.
+     * Must match SCREAMING_SNAKE_CASE: /^[A-Z][A-Z0-9_]*$/ (e.g., "BANK", "VAULT", "HFT_ORACLE").
+     */
+    tokenSlug?: string;
+    /**
+     * SOC 2 Type II / HIPAA immutable audit logger instance.
+     */
+    auditLogger?: AuditLogger;
+    /**
+     * Path to a shared JSON file for persistent Query Budget tracking across multiple server instances.
+     */
+    budgetStorePath?: string;
+}
+interface AggregationPolicy {
+    /** Maximum number of object-type array elements allowed (default: 10) */
+    maxOutputRows?: number;
+    /** Allow arrays containing only primitive values (default: true) */
+    allowPrimitiveArrays?: boolean;
+    /** Block min/max extraction when dataset size < this value (default: 50) */
+    minMaxBlockThreshold?: number;
+}
+interface LogicExecutionPolicy {
+    /**
+     * Validate the business payload returned by sandbox logic (post-execution).
+     * This runs before final egress checks and blocks non-conforming outputs.
+     */
+    outputSchema?: z.ZodType<unknown>;
+    /**
+     * Enforce aggregation-first heuristics (preflight + post-check).
+     */
+    enforceAggregationFirst?: boolean | AggregationPolicy;
+    /**
+     * Optional additional deny patterns checked against extracted logic source.
+     */
+    preflightDenyPatterns?: RegExp[];
+    /**
+     * Differential Privacy epsilon per query (default: 1.0).
+     * Lower = stronger privacy + more noise. Standard: Apple iOS uses 1.0.
+     */
+    dpEpsilon?: number;
+    /**
+     * DP sensitivity: max change when one record added/removed (default: 1.0).
+     * For SUM queries on a field with range [0, X], set sensitivity = X.
+     */
+    dpSensitivity?: number;
+    /**
+     * Dataset size threshold below which Differential Privacy is active (default: 50).
+     */
+    dpSmallDatasetThreshold?: number;
+    /**
+     * Max queries per numeric field per PQC session (default: 5).
+     * Prevents multi-query differencing attacks.
+     */
+    queryBudgetPerField?: number;
+    /**
+     * Domain-specific sensitive keys that fall under the "sensitive" query budget tier.
+     */
+    sensitiveKeys?: string[];
+    /**
+     * Path to a shared JSON file for persistent Query Budget tracking across multiple server instances.
+     */
+    budgetStorePath?: string;
+}
+declare class LiopServer {
+    private serverInfo;
+    private config?;
+    private logicCache;
+    private connectionStats;
+    private readonly CACHE_TTL_MS;
+    private readonly THROTTLE_THRESHOLD;
+    private readonly THROTTLE_COOLDOWN_MS;
+    private toolCallWindows;
+    private readonly toolCallMaxPerWindow;
+    private readonly toolCallWindowMs;
+    private globalCallWindow;
+    private readonly globalCallMaxPerWindow;
+    private fieldQueryBudget;
+    private readonly taintAnalyzer;
+    private tools;
+    private resources;
+    private prompts;
+    private activeSchema;
+    private sandboxRecords;
+    private piiScanner;
+    private workerPool;
+    private meshNode;
+    private rpcServer;
+    private boundPort;
+    jwtValidator?: JwtValidator;
+    oauthProvider?: any;
+    private sessions;
+    private revokedTokenHashes;
+    private lastRevocationLoadTime;
+    private pqcKeyPair;
+    readonly auditLogger: AuditLogger;
+    getDatasetHash(): string;
+    private static readonly LIOP_COMPACT_REGEX;
+    private extractLogic;
+    private parseUnknownJson;
+    private runPreflightPolicy;
+    private validateOutputPolicy;
+    /**
+     * Proxied tools stringify a full MCP CallToolResult (`{ content: [...] }`).
+     * Aggregation-first heuristics must scan the inner business JSON, not the MCP envelope
+     * (otherwise `content` looks like a tabular array of objects and everything blocks).
+     */
+    private unwrapForAggregationPolicyScan;
+    private violatesAggregationFirstPolicy;
+    constructor(serverInfo: ServerInfo, config?: LiopServerOptions | undefined);
+    /**
+     * Builds the centralized LIOP envelope specification document.
+     * Served as a single Resource (liop://protocol/envelope-spec) instead
+     * of being duplicated across every tool description.
+     */
+    private buildEnvelopeSpec;
+    /**
+     * Extracts a compact, human-readable field summary from a JSON Schema.
+     *
+     * Walks the schema structure to find actual data property names and types,
+     * rather than returning top-level schema metadata keys (type, items, etc.).
+     *
+     * Example output for a banking schema:
+     *   "Array of {id(string), accountHolder(string), balance(number), transactions(array of {date(string), amount(number)})}"
+     */
+    private extractSchemaFieldSummary;
+    /**
+     * Convenience alias for connectToMesh(), matching official documentation.
+     */
+    connect(options?: {
+        port?: number;
+        meshConfig?: MeshNodeConfig;
+    }): Promise<void>;
+    /**
+     * Register a new Tool
+     */
+    tool<T extends z.ZodRawShape>(name: string, description: string, shape: T, handler: ToolHandler<T>, policy?: LogicExecutionPolicy): void;
+    /**
+     * Register a dynamic prompt
+     */
+    prompt(name: string, description: string | undefined, args: Prompt["arguments"], handler: (request: GetPromptRequest) => GetPromptResult | Promise<GetPromptResult>): void;
+    /**
+     * Enables LIOP Zero-Shot Autonomy by registering the Blind Analyst standard prompt.
+     */
+    enableZeroShotAutonomy(): void;
+    /**
+     * Register a dynamic resource
+     */
+    resource(name: string, uri: string, description?: string, mimeType?: string, content?: string | (() => Promise<string>)): void;
+    /**
+     * Builds execution guidelines served as a resource to guide LLM code generation.
+     */
+    private buildExecutionGuidelines;
+    /**
+     * Broadcasts the Data Dictionary to the LLM prior to code injection.
+     */
+    dataDictionary(schema: Record<string, unknown>, name?: string, uri?: string, description?: string): void;
+    /**
+     * Manually invalidates the AST Logic Cache (e.g. for Zero-Day patches).
+     */
+    clearAstCache(): void;
+    /**
+     * Sliding window rate limiter for tool call frequency.
+     * Prevents micro-query exfiltration attacks where an attacker
+     * makes hundreds of individually-legitimate calls to reconstruct
+     * the full dataset field by field. (OWASP A01)
+     */
+    private checkToolCallRateLimit;
+    /**
+     * Global cross-tool rate limiter.
+     * Prevents attackers from distributing micro-queries across multiple tools
+     * to evade per-tool rate limits. (OWASP A01)
+     */
+    private checkGlobalRateLimit;
+    /**
+     * Emulates calling a tool (used locally or via LIOPMcpBridge)
+     */
+    callTool(request: CallToolRequest, clientId?: string): Promise<CallToolResult>;
+    /**
+     * Retrieves registered tools
+     */
+    listTools(): Tool[];
+    /**
+     * Retrieves registered prompts
+     */
+    listPrompts(): Prompt[];
+    /**
+     * Gets a specific prompt by name
+     */
+    getPrompt(request: GetPromptRequest): Promise<GetPromptResult>;
+    /**
+     * Retrieves registered resources
+     */
+    listResources(): Resource[];
+    /**
+     * Reads a specific resource by URI
+     */
+    readResource(uri: string): Promise<{
+        contents: Array<{
+            uri: string;
+            mimeType?: string;
+            text: string;
+        }>;
+    }>;
+    getServerInfo(): ServerInfo;
+    getMeshNode(): MeshNode | null;
+    /**
+     * Injects data into the secure sandbox context for Logic-on-Origin tools.
+     */
+    setSandboxData(records: Record<string, unknown>[]): void;
+    getBoundPort(): number | null;
+    /**
+     * Connects to the libp2p Kademlia DHT and announces capabilities.
+     * Boots the gRPC server for secure Logic-on-Origin.
+     */
+    connectToMesh(options?: {
+        port?: number;
+        meshConfig?: MeshNodeConfig;
+    }): Promise<void>;
+    /**
+     * Internal worker execution with Egress Filtering logic.
+     */
+    private executeInWorkerPool;
+    /**
+     * Safely destroys the worker pool, gRPC server, and Mesh node.
+     * Recommended to be called during graceful shutdowns or test teardowns.
+     */
+    close(): Promise<void>;
+    private loadRevocationList;
+    revokeToken(token: string): void;
+    revokeTokenHash(hash: string): void;
+    /**
+     * Resets the query budget for a specific client identity.
+     * If toolName is provided, only that tool's budget is cleared.
+     * Otherwise, all tool budgets for the client are reset.
+     *
+     * Operates on both in-memory and persistent (disk) budget stores.
+     * Uses file-level locking for safe concurrent access.
+     */
+    resetFieldBudget(clientId: string, toolName?: string): void;
+    private getPersistentBudget;
+    private savePersistentBudget;
+    private executeWithBudgetLock;
+    private applyInMemoryBudget;
+}
+
+export { AUTH_DEFAULTS as A, GENESIS_HASH as G, LiopServer as L, NerScanner as N, type OAuthClientConfig as O, PII_PATTERNS as P, type ToolHandler as T, type LiopServerOptions as a, type AggregationPolicy as b, type AuditEntry as c, AuditLogger as d, type AuditRecordParams as e, type AuditStatus as f, type AuthRole as g, type LiopAuthConfig as h, type LogicExecutionPolicy as i, type OutputSanitizerConfig as j, PII_PRESETS as k, type PiiRule as l, PiiScanner as m, computeEntryHash as n, globalAuditLogger as o, sanitizeOutput as s };