@fenixforce/kernel 0.1.0

package/dist/security/approval-gates.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Approval Gates — channel-agnostic approval flow with
+ * Telegram inline keyboard support, HTTP pending-approval endpoint,
+ * 5-minute timeout, and pluggable persistence.
+ */
+export type RiskLevel = "low" | "medium" | "high" | "critical";
+export type ApprovalStatus = "pending" | "approved" | "denied" | "timeout" | "error";
+export interface ApprovalRequest {
+    id: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    userId: string;
+    chatId: string;
+    channel: string;
+    reason?: string;
+    riskLevel: RiskLevel;
+    status: ApprovalStatus;
+    createdAt: Date;
+    resolvedAt?: Date;
+    resolvedBy?: string;
+    timeoutMs: number;
+}
+export interface ApprovalResult {
+    approved: boolean;
+    request: ApprovalRequest;
+}
+export interface ApprovalPolicy {
+    /** Tool name pattern. Use "*" for all tools. */
+    toolName: string;
+    /** Minimum risk level that triggers approval. Default: all levels require it. */
+    riskLevel?: RiskLevel;
+    /** If true, this tool requires approval. */
+    requireApproval: boolean;
+    /** Users that are auto-approved (skip the gate). */
+    autoApproveForUsers?: string[];
+}
+export interface ChannelSender {
+    /** Send approval prompt to user via channel UI (e.g. Telegram inline keyboard). */
+    sendApproval(request: ApprovalRequest): Promise<void>;
+    /** Notify user that approval was resolved (optional). */
+    notifyResolved?(request: ApprovalRequest): Promise<void>;
+}
+export interface ApprovalStore {
+    save(request: ApprovalRequest): Promise<void>;
+    get(id: string): Promise<ApprovalRequest | undefined>;
+    update(id: string, updates: Partial<ApprovalRequest>): Promise<void>;
+    listPending(): Promise<ApprovalRequest[]>;
+    listByUser(userId: string): Promise<ApprovalRequest[]>;
+    listAll(): Promise<ApprovalRequest[]>;
+}
+export type ApprovalEventType = "approval_requested" | "approval_approved" | "approval_denied" | "approval_timeout" | "approval_error";
+export interface ApprovalEvent {
+    type: ApprovalEventType;
+    request: ApprovalRequest;
+    timestamp: Date;
+}
+export type ApprovalEventListener = (event: ApprovalEvent) => void;
+export interface HttpApprovalInfo {
+    id: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    userId: string;
+    channel: string;
+    riskLevel: RiskLevel;
+    reason?: string;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface ApprovalGateConfig {
+    /** Default timeout in ms. Default 300_000 (5 minutes). */
+    defaultTimeoutMs?: number;
+    /** Maximum pending approvals per agent/user. Default 5. */
+    maxPendingPerAgent?: number;
+    /** Pluggable persistence store. Defaults to in-memory. */
+    store?: ApprovalStore;
+}
+export interface ApprovalGate {
+    /** Request approval. Blocks until approved, denied, or timed out. */
+    requestApproval(opts: {
+        toolName: string;
+        args: Record<string, unknown>;
+        userId: string;
+        chatId: string;
+        channel: string;
+        reason?: string;
+        riskLevel?: RiskLevel;
+        timeoutMs?: number;
+    }): Promise<ApprovalResult>;
+    /** Resolve a pending approval externally (e.g. from callback query or HTTP). */
+    resolve(approvalId: string, decision: "approved" | "denied", resolvedBy?: string): void;
+    /** Get a single approval request. */
+    getRequest(id: string): ApprovalRequest | undefined;
+    /** All currently pending requests. */
+    listPending(): ApprovalRequest[];
+    /** Pending count for a specific user. */
+    pendingCountForUser(userId: string): number;
+    /** All requests for a user. */
+    listByUser(userId: string): ApprovalRequest[];
+    /** Pending approvals as HTTP-friendly JSON. */
+    listPendingHttp(): HttpApprovalInfo[];
+    /** Add or update a policy. */
+    addPolicy(policy: ApprovalPolicy): void;
+    /** Remove a policy for a tool name. */
+    removePolicy(toolName: string): boolean;
+    /** Check if a tool call needs approval for a given user. */
+    needsApproval(toolName: string, userId: string): boolean;
+    /** Register a channel sender (e.g. Telegram, Slack). */
+    registerChannel(channelName: string, sender: ChannelSender): void;
+    on(listener: ApprovalEventListener): void;
+    off(listener: ApprovalEventListener): void;
+    /** Clean up timers and resolve all pending as denied. */
+    dispose(): void;
+}
+export declare function _resetApprovalIds(): void;
+export declare function createInMemoryApprovalStore(): ApprovalStore;
+export declare function createApprovalGate(config?: ApprovalGateConfig): ApprovalGate;
+/**
+ * Creates a ChannelSender that uses the Telegram adapter's
+ * sendApprovalKeyboard / sendMessage methods.
+ *
+ * The `onResolve` callback lets the Telegram adapter's callback-query
+ * handler call `gate.resolve()` when the user taps Approve/Deny.
+ */
+export interface TelegramSenderConfig {
+    /** Send an inline keyboard approval prompt. */
+    sendApprovalKeyboard: (chatId: string, approvalId: string, toolName: string, args: Record<string, unknown>) => void;
+    /** Send a plain text message. */
+    sendMessage: (chatId: string, text: string) => Promise<void>;
+}
+export declare function createTelegramApprovalSender(config: TelegramSenderConfig): ChannelSender;
+/**
+ * Creates a ChannelSender for voice-based approval: speaks the approval
+ * prompt and listens for a spoken "approve" or "deny" response.
+ */
+export interface VoiceSenderConfig {
+    /** Speak a text prompt to the user. */
+    speak: (chatId: string, text: string) => Promise<void>;
+    /**
+     * Listen for a spoken confirmation. Should resolve to "approve" or "deny"
+     * (or any string — the sender maps to a decision).
+     * A timeout or unrecognised input should resolve to "deny".
+     */
+    listenForConfirmation: (chatId: string, timeoutMs: number) => Promise<string>;
+}
+export declare function createVoiceApprovalSender(config: VoiceSenderConfig, gate: ApprovalGate): ChannelSender;
+/**
+ * Build HTTP handler functions for approval endpoints.
+ * These can be mounted on Hono, Express, or any HTTP framework.
+ */
+export interface HttpApprovalHandlers {
+    /** GET /approvals — list pending approvals. */
+    listPending: () => HttpApprovalInfo[];
+    /** POST /approvals/:id/approve — approve a request. */
+    approve: (id: string, approvedBy?: string) => {
+        ok: boolean;
+        message: string;
+    };
+    /** POST /approvals/:id/deny — deny a request. */
+    deny: (id: string, deniedBy?: string) => {
+        ok: boolean;
+        message: string;
+    };
+    /** GET /approvals/:id — get a single approval. */
+    getApproval: (id: string) => HttpApprovalInfo | null;
+}
+export declare function createHttpApprovalHandlers(gate: ApprovalGate): HttpApprovalHandlers;

package/dist/security/content-wrapper.d.ts

@@ -0,0 +1,38 @@
+import type { ExtensionDefinition } from "../extensions/manager.js";
+export interface ContentWrapperConfig {
+    enabled: boolean;
+    /** XML tag name for wrapping (default: "untrusted") */
+    wrapper: string;
+    /** Tool names whose output is trusted (injected directly) */
+    trustedSources: string[];
+    /** Extract URLs from untrusted content as [LINK: url] references */
+    treatLinksAsHostile: boolean;
+    /** User IDs whose messages are trusted in group contexts */
+    allowlistedUsers?: string[];
+}
+/**
+ * Standing instruction appended to system prompt when content wrapping is active.
+ */
+export declare const UNTRUSTED_CONTENT_INSTRUCTION: string;
+/**
+ * Determine whether a tool's output should be wrapped.
+ */
+export declare function isTrustedSource(toolName: string, config: ContentWrapperConfig): boolean;
+/**
+ * Wrap content in XML delimiters with source attribution.
+ */
+export declare function wrapContent(content: string, source: string, config: ContentWrapperConfig): string;
+/**
+ * Check if a user message in group context should be wrapped.
+ */
+export declare function isAllowlistedUser(userId: string, config: ContentWrapperConfig): boolean;
+/**
+ * Wrap a group message from a non-allowlisted user.
+ */
+export declare function wrapGroupMessage(content: string, userId: string, config: ContentWrapperConfig): string;
+/**
+ * Create the content wrapper as a guard-rails extension.
+ * Runs as a `tool:after` hook — wraps untrusted tool results
+ * before they enter the LLM context.
+ */
+export declare function createContentWrapperExtension(config?: Partial<ContentWrapperConfig>): ExtensionDefinition;

package/dist/security/guard-rails.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionDefinition } from "../extensions/manager.js";
+/** Mark a session as unattended (no human in the loop). */
+export declare function setSessionUnattended(sessionId: string, unattended: boolean): void;
+export declare const guardRailsExtension: ExtensionDefinition;
+/** Reset context tracking state (for tests). */
+export declare function _resetGuardRailState(): void;

package/dist/security/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Security module — SSRF, shell bleed, taint tracking, approval gates,
+ * instruction hierarchy, secret store, tool access control.
+ */
+export { validateUrl, validateUrlWithDns, } from "./ssrf.js";
+export type { SsrfResult, DnsResolver } from "./ssrf.js";
+export { TaintTracker, TaintSet, CLEAN } from "./taint-tracker.js";
+export type { TaintLabel, OutputPolicy } from "./taint-tracker.js";
+export { detectShellBleed, detectShellBleedWithEvents } from "./shell-bleed.js";
+export type { ShellBleedAction, ShellBleedLeak, ShellBleedResult } from "./shell-bleed.js";
+export { createApprovalGate, createInMemoryApprovalStore, createTelegramApprovalSender, createVoiceApprovalSender, createHttpApprovalHandlers, _resetApprovalIds, } from "./approval-gates.js";
+export type { RiskLevel, ApprovalStatus, ApprovalRequest, ApprovalResult, ApprovalPolicy, ChannelSender, ApprovalStore, ApprovalEventType, ApprovalEvent, ApprovalEventListener, HttpApprovalInfo, ApprovalGateConfig, ApprovalGate, TelegramSenderConfig, VoiceSenderConfig, HttpApprovalHandlers, } from "./approval-gates.js";
+export { createInstructionHierarchy, applyWebIsolation, containsWebIsolation, stripWebIsolation, WEB_ISOLATION_PREFIX, WEB_ISOLATION_SUFFIX, } from "./instruction-hierarchy.js";
+export type { InstructionSource, TaggedContent, SensitiveAction, ConfirmationRequest, ConfirmationHandler, ValidationVerdict, ValidationResult, HierarchyEventType, HierarchyEvent, HierarchyEventListener, InstructionHierarchyConfig, InstructionHierarchy, } from "./instruction-hierarchy.js";
+export { createSecretStore } from "./secret-store.js";
+export type { EncryptedCredential, SecretStoreConfig, SecretStore } from "./secret-store.js";
+export { guardRailsExtension, setSessionUnattended, _resetGuardRailState, } from "./guard-rails.js";
+export { PIITokenizer, createPIITokenizerExtension } from "./pii-tokenizer.js";
+export type { PIIPattern, TokenMap, PIIEventEmitter } from "./pii-tokenizer.js";
+export { createToolAccessControl, EDITION_PRO, EDITION_MOBILE, EDITION_VOICES, } from "./tool-access-control.js";
+export type { ToolCategory, ToolDefinition as AccessToolDefinition, EditionName, EditionManifest, AgentRole, AgentConfig, AccessVerdict, AccessCheckResult, AccessEventType, AccessEvent, AccessEventListener, ToolAccessControlConfig, ToolAccessControl, } from "./tool-access-control.js";

package/dist/security/instruction-hierarchy.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Instruction Hierarchy — tag content with InstructionSource,
+ * enforce web content isolation markers, and require user
+ * confirmation for sensitive actions.
+ *
+ * Privilege levels (highest → lowest):
+ *   system > user > tool > web
+ *
+ * Content from lower-privilege sources cannot override
+ * higher-privilege instructions. Web content is always
+ * isolated and cannot trigger sensitive actions directly.
+ */
+/** Ordered from most to least privileged. */
+export type InstructionSource = "system" | "user" | "tool" | "web";
+export interface TaggedContent {
+    /** The raw content string. */
+    content: string;
+    /** Where this content originated. */
+    source: InstructionSource;
+    /** Whether web-isolation markers have been applied. */
+    isolated: boolean;
+    /** ISO timestamp of when this was tagged. */
+    taggedAt: string;
+    /** Optional label identifying the specific origin (e.g. URL, tool name). */
+    origin?: string;
+}
+export declare const WEB_ISOLATION_PREFIX = "<!-- [WEB_CONTENT_START] -->";
+export declare const WEB_ISOLATION_SUFFIX = "<!-- [WEB_CONTENT_END] -->";
+/**
+ * Wrap content with web-isolation markers so downstream processors
+ * can detect and sandbox web-sourced content.
+ */
+export declare function applyWebIsolation(content: string, origin?: string): string;
+/**
+ * Check if a string contains web-isolated content.
+ */
+export declare function containsWebIsolation(text: string): boolean;
+/**
+ * Strip web-isolation markers from content, returning the inner text.
+ */
+export declare function stripWebIsolation(text: string): string;
+export interface SensitiveAction {
+    /** Action/tool name pattern. Use "*" for all. */
+    action: string;
+    /** Human-readable description of why this is sensitive. */
+    reason: string;
+    /** Minimum source privilege required to execute without confirmation. */
+    minSource: InstructionSource;
+}
+export interface ConfirmationRequest {
+    action: string;
+    args: Record<string, unknown>;
+    triggeredBy: InstructionSource;
+    reason: string;
+    origin?: string;
+}
+export type ConfirmationHandler = (request: ConfirmationRequest) => Promise<boolean>;
+export type ValidationVerdict = "allow" | "confirm" | "deny";
+export interface ValidationResult {
+    verdict: ValidationVerdict;
+    reason: string;
+    action: string;
+    triggeredBy: InstructionSource;
+    requiredSource?: InstructionSource;
+}
+export type HierarchyEventType = "content_tagged" | "action_allowed" | "action_confirmed" | "action_denied" | "web_content_isolated" | "privilege_escalation_blocked";
+export interface HierarchyEvent {
+    type: HierarchyEventType;
+    timestamp: Date;
+    source?: InstructionSource;
+    action?: string;
+    detail: string;
+}
+export type HierarchyEventListener = (event: HierarchyEvent) => void;
+export interface InstructionHierarchyConfig {
+    /** Callback to ask user for confirmation on sensitive actions. */
+    confirmationHandler?: ConfirmationHandler;
+    /** If true, web-sourced content is always denied for sensitive actions
+     *  regardless of confirmation. Default: true. */
+    strictWebIsolation?: boolean;
+}
+export interface InstructionHierarchy {
+    /** Tag content with its source. Web content gets isolation markers. */
+    tagContent(content: string, source: InstructionSource, origin?: string): TaggedContent;
+    /** Register a sensitive action that requires elevated privilege. */
+    addSensitiveAction(action: SensitiveAction): void;
+    /** Remove a sensitive action. */
+    removeSensitiveAction(actionName: string): boolean;
+    /** List all registered sensitive actions. */
+    listSensitiveActions(): SensitiveAction[];
+    /** Check if an action is registered as sensitive. */
+    isSensitive(actionName: string): boolean;
+    /** Validate whether a source can execute an action.
+     *  Returns "allow", "confirm", or "deny". */
+    validate(actionName: string, triggeredBy: InstructionSource): ValidationResult;
+    /** Execute an action through the hierarchy — validates, confirms if
+     *  needed, and returns whether the action was permitted. */
+    executeAction(actionName: string, args: Record<string, unknown>, triggeredBy: InstructionSource, origin?: string): Promise<{
+        permitted: boolean;
+        result: ValidationResult;
+    }>;
+    /** Check if one source has higher or equal privilege to another. */
+    hasPrivilege(source: InstructionSource, requiredSource: InstructionSource): boolean;
+    /** Get the privilege level (0-3) for a source. */
+    getPrivilegeLevel(source: InstructionSource): number;
+    on(listener: HierarchyEventListener): void;
+    off(listener: HierarchyEventListener): void;
+}
+export declare function createInstructionHierarchy(config?: InstructionHierarchyConfig): InstructionHierarchy;

package/dist/security/pii-tokenizer.d.ts

@@ -0,0 +1,30 @@
+import type { ExtensionDefinition } from "../extensions/manager.js";
+export interface PIIPattern {
+    type: string;
+    regex: RegExp;
+    tokenPrefix: string;
+}
+export interface TokenMap {
+    tokenToValue: Map<string, string>;
+    valueToToken: Map<string, string>;
+    counters: Map<string, number>;
+}
+export type PIIEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+export declare class PIITokenizer {
+    private sessionMaps;
+    private patterns;
+    private emitEvent;
+    constructor(customPatterns?: PIIPattern[], emitEvent?: PIIEventEmitter);
+    /** Tokenize PII in text, returning sanitized text. */
+    tokenize(sessionId: string, text: string, toolName?: string): string;
+    /** Untokenize — restore real values from tokens. */
+    untokenize(sessionId: string, text: string): string;
+    /** Clear session token map (on session end). */
+    clearSession(sessionId: string): void;
+    /** Get token count for a session. */
+    getTokenCount(sessionId: string): number;
+    private getOrCreateMap;
+}
+export declare function createPIITokenizerExtension(tokenizer: PIITokenizer, opts?: {
+    privacyLevel?: string;
+}): ExtensionDefinition;

package/dist/security/reputation.d.ts

@@ -0,0 +1,53 @@
+import type { Severity } from "./security-engine.js";
+import type { StorageAdapter } from "../storage/interface.js";
+export type ReputationStatus = "trusted" | "normal" | "suspicious" | "blocklisted";
+export interface ReputationRecord {
+    userId: string;
+    sessionCount: number;
+    securityEvents: SecurityEventEntry[];
+    trustScore: number;
+    status: ReputationStatus;
+    lastUpdated: Date;
+}
+export interface SecurityEventEntry {
+    severity: Severity;
+    module: string;
+    timestamp: Date;
+}
+export interface ReputationConfig {
+    /** Initial trust score for new users (default: 0.5) */
+    initialScore?: number;
+    /** TTL in days for inactive records (default: 90) */
+    ttlDays?: number;
+    /** Owner user IDs that bypass escalation */
+    ownerIds?: string[];
+}
+export declare class ReputationEngine {
+    private records;
+    private config;
+    private storage;
+    constructor(config?: ReputationConfig, storage?: StorageAdapter);
+    /**
+     * Record a security event and update the user's trust score.
+     */
+    recordEvent(userId: string, severity: Severity, module: string): Promise<ReputationRecord>;
+    /**
+     * Get the effective severity after reputation-based escalation.
+     * - Suspicious users: escalate by one level
+     * - Blocklisted users: always CRITICAL
+     * - Trusted users: de-escalate MEDIUM → LOW
+     * - Owners: ALLOW unless CRITICAL
+     */
+    adjustSeverity(userId: string, baseSeverity: Severity): Severity;
+    /** Get a user's current reputation record. */
+    getRecord(userId: string): Promise<ReputationRecord | null>;
+    /** Manually blocklist a user. */
+    blocklist(userId: string): Promise<void>;
+    /** Reset a user's reputation to initial state. */
+    reset(userId: string): Promise<void>;
+    /** Purge expired records (older than TTL). */
+    purgeExpired(): Promise<number>;
+    private getOrCreate;
+    private computeStatus;
+    private persist;
+}

package/dist/security/secret-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Encrypted Credentials — AES-256-GCM encryption for API keys
+ * and credentials. Keys are encrypted with a workspace master key
+ * derived from an environment variable.
+ *
+ * Methods: store, retrieve, delete, list.
+ * Backed by an in-memory encrypted_credentials table.
+ */
+export interface EncryptedCredential {
+    /** User ID. */
+    userId: string;
+    /** Provider name (e.g. "openai", "anthropic"). */
+    provider: string;
+    /** Base64-encoded encrypted data. */
+    encryptedData: string;
+    /** Base64-encoded initialization vector. */
+    iv: string;
+    /** Base64-encoded auth tag. */
+    authTag: string;
+    /** When this credential was stored. */
+    createdAt: Date;
+    /** When this credential was last updated. */
+    updatedAt: Date;
+}
+export interface SecretStoreConfig {
+    /** Master key for encryption (32 bytes as hex string or Uint8Array). */
+    masterKey: string | Uint8Array;
+}
+export interface SecretStore {
+    /** Store an encrypted credential. Overwrites if exists. */
+    store(userId: string, provider: string, key: string): Promise<void>;
+    /** Retrieve and decrypt a credential. Returns null if not found. */
+    retrieve(userId: string, provider: string): Promise<string | null>;
+    /** Delete a credential. */
+    delete(userId: string, provider: string): boolean;
+    /** List all providers with stored credentials for a user. */
+    list(userId: string): string[];
+    /** Check if a credential exists. */
+    has(userId: string, provider: string): boolean;
+}
+export declare function createSecretStore(config: SecretStoreConfig): SecretStore;

package/dist/security/security-engine.d.ts

@@ -0,0 +1,53 @@
+import type { EventBus } from "../events/bus.js";
+export type Severity = "SAFE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+export type ActionDisposition = "allow" | "log" | "warn" | "block";
+export interface DetectionFinding {
+    module: string;
+    severity: Severity;
+    description: string;
+    evidence?: string;
+}
+export interface ValidationResult {
+    severity: Severity;
+    action: ActionDisposition;
+    findings: DetectionFinding[];
+    durationMs: number;
+}
+export interface SecurityEngineConfig {
+    /** Per-severity action overrides (workspace-level) */
+    actionMap?: Partial<Record<Severity, ActionDisposition>>;
+    /** Workspace root for policy file loading */
+    workspaceRoot?: string;
+    /** Custom deny patterns from workspace policy */
+    customDenyPatterns?: string[];
+    /** Trusted sources that skip content policy scanning */
+    trustedSources?: string[];
+}
+export interface ValidationInput {
+    /** What is being validated: tool call, tool result, user message */
+    kind: "tool-call" | "tool-result" | "user-message";
+    /** Tool name, if applicable */
+    toolName?: string;
+    /** Content to validate */
+    content: string;
+    /** Tool parameters, if applicable */
+    params?: Record<string, unknown>;
+    /** User/session ID for reputation lookup */
+    userId?: string;
+}
+export declare class SecurityEngine {
+    private actionMap;
+    private config;
+    private eventBus;
+    constructor(config?: SecurityEngineConfig, eventBus?: EventBus);
+    /**
+     * Validate input through all 6 detection modules in parallel.
+     * Returns aggregated severity with findings.
+     */
+    validate(input: ValidationInput): Promise<ValidationResult>;
+    /**
+     * Aggregate = max(individual severities), with escalation:
+     * 2+ HIGH findings → CRITICAL.
+     */
+    private aggregateSeverity;
+}

package/dist/security/shell-bleed.d.ts

@@ -0,0 +1,15 @@
+import type { AgentEvent } from "../events/types.js";
+export type ShellBleedAction = "warn" | "block";
+export interface ShellBleedLeak {
+    variable: string;
+    line: number;
+    pattern: string;
+}
+export interface ShellBleedResult {
+    safe: boolean;
+    action: ShellBleedAction;
+    leaks: ShellBleedLeak[];
+    blocked: boolean;
+}
+export declare function detectShellBleed(script: string, action?: ShellBleedAction): ShellBleedResult;
+export declare function detectShellBleedWithEvents(script: string, action?: ShellBleedAction, sessionId?: string): Generator<AgentEvent, ShellBleedResult>;

package/dist/security/ssrf.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SSRF protection — validates URLs against private IP ranges, cloud metadata
+ * endpoints, and DNS-rebinding attacks.
+ */
+export interface SsrfResult {
+    safe: boolean;
+    reason?: string;
+    resolvedIP?: string;
+}
+export declare function validateUrl(url: string): SsrfResult;
+export type DnsResolver = (hostname: string) => Promise<string[]>;
+export declare function validateUrlWithDns(url: string, resolver?: DnsResolver): Promise<SsrfResult>;

package/dist/security/taint-tracker.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Taint Tracker — dynamic information flow tracking during a single
+ * agent turn. Prevents tainted data from reaching restricted outputs.
+ *
+ * Five taint labels: externalNetwork, userInput, pii, secret, untrustedAgent.
+ * When values combine, the result inherits the union of all label sets.
+ */
+export type TaintLabel = "externalNetwork" | "userInput" | "pii" | "secret" | "untrustedAgent";
+export declare const ALL_TAINT_LABELS: readonly TaintLabel[];
+/** Immutable set of taint labels attached to a tracked value. */
+export declare class TaintSet {
+    private readonly labels;
+    constructor(labels?: Iterable<TaintLabel>);
+    /** Check if this set contains a specific label. */
+    has(label: TaintLabel): boolean;
+    /** Check if any of the given labels are present. */
+    hasAny(labels: TaintLabel[]): boolean;
+    /** Return the union of this set with another. */
+    union(other: TaintSet): TaintSet;
+    /** Number of taint labels. */
+    get size(): number;
+    /** True if no taint labels are set. */
+    get clean(): boolean;
+    /** Return labels as a sorted array (for serialization/logging). */
+    toArray(): TaintLabel[];
+}
+/** Convenience: create an empty (clean) taint set. */
+export declare const CLEAN: TaintSet;
+export interface OutputPolicy {
+    /** Human-readable name for this output channel. */
+    name: string;
+    /** Taint labels that are BLOCKED from reaching this output. */
+    blocked: TaintLabel[];
+}
+export declare class TaintTracker {
+    private values;
+    private policies;
+    /** Register a tracked value with initial taint labels. */
+    track(id: string, labels: TaintLabel[]): void;
+    /** Get the taint set for a tracked value. Returns CLEAN if unknown. */
+    getTaint(id: string): TaintSet;
+    /**
+     * Combine multiple tracked values. The result inherits the union
+     * of all taint label sets. Registers the result under the given id.
+     */
+    combine(resultId: string, sourceIds: string[]): TaintSet;
+    /** Propagate taint from one value to another (add, don't replace). */
+    propagate(fromId: string, toId: string): void;
+    /** Register an output policy (defines which labels are blocked). */
+    registerOutput(outputId: string, policy: OutputPolicy): void;
+    /**
+     * Check if a tracked value is allowed to reach a registered output.
+     * Returns { allowed, violations } where violations lists the blocked labels found.
+     */
+    checkOutput(valueId: string, outputId: string): {
+        allowed: boolean;
+        violations: TaintLabel[];
+    };
+    /** Number of tracked values. */
+    get size(): number;
+    /** Reset all tracked values (start of new agent turn). */
+    clear(): void;
+}