@salucallc/tiresias-sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @salucallc/tiresias-sdk
+ * Unified Tiresias AI Safety SDK
+ *
+ * @example
+ * ```typescript
+ * import { Tiresias, OpenAIAdapter } from "@salucallc/tiresias-sdk";
+ *
+ * const tiresias = new Tiresias();
+ * const adapter = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
+ *
+ * const result = await tiresias.call(
+ *   [{ role: "user", content: "What is the capital of France?" }],
+ *   adapter,
+ *   { sessionId: "user-123" }
+ * );
+ *
+ * if (result.blocked) {
+ *   console.log("Request blocked:", result.decision, result.composite.score);
+ * } else {
+ *   console.log(result.llmResponse?.content);
+ * }
+ * ```
+ */
+
+export { Tiresias } from "./tiresias.js";
+export { computeCompositeScore, scoreToPolicy } from "./scoring.js";
+export {
+  computeChainHash,
+  hashRequest,
+  buildAuditEntry,
+  verifyChain,
+  MemoryAuditStore,
+  GENESIS_HASH,
+} from "./audit.js";
+export { SessionManager } from "./session.js";
+export { OpenAIAdapter, AnthropicAdapter } from "./adapters.js";
+export type {
+  WatchSignal,
+  ReportSignal,
+  NetworkSignal,
+  CompositeScore,
+  PolicyDecision,
+  PolicyThresholds,
+  AuditEntry,
+  TiresiasSession,
+  Message,
+  MessageRole,
+  LLMResponse,
+  LLMAdapter,
+  LLMCallOptions,
+  TiresiasConfig,
+  AuditStore,
+  TiresiasCallResult,
+} from "./types.js";
+export { DEFAULT_POLICY_THRESHOLDS } from "./types.js";

package/src/scoring.ts

@@ -0,0 +1,71 @@
+/**
+ * PATENT-CRITICAL: Composite Risk Scoring (SALUCA-005 / cross_layer_orchestration)
+ *
+ * Composite formula:
+ *   score = (0.5 × injection_threat) + (0.4 × pii_risk) + (0.1 × network_threat)
+ *
+ * This cross-module weighting is the novel IP element of the orchestration patent.
+ * The injection signal dominates (0.5) because it represents active adversarial attack;
+ * PII leakage is structural risk (0.4); network telemetry is ambient context (0.1).
+ */
+
+import type {
+  WatchSignal,
+  ReportSignal,
+  NetworkSignal,
+  CompositeScore,
+  PolicyDecision,
+  PolicyThresholds,
+} from "./types.js";
+import { DEFAULT_POLICY_THRESHOLDS } from "./types.js";
+
+// Composite weight constants — PATENT-CRITICAL
+const W_INJECTION = 0.5;
+const W_PII = 0.4;
+const W_NETWORK = 0.1;
+
+/**
+ * Compute composite risk score from three independent safety signals.
+ * PATENT-CRITICAL: formula and weights are novel claims in SALUCA-005.
+ */
+export function computeCompositeScore(
+  watch: WatchSignal,
+  report: ReportSignal,
+  network: NetworkSignal,
+  thresholds: PolicyThresholds = DEFAULT_POLICY_THRESHOLDS,
+): CompositeScore {
+  const score = clamp(
+    W_INJECTION * watch.injectionThreat +
+    W_PII * report.piiRisk +
+    W_NETWORK * network.networkThreat,
+  );
+
+  const policy = scoreToPolicy(score, thresholds);
+
+  return {
+    score,
+    injectionThreat: watch.injectionThreat,
+    piiRisk: report.piiRisk,
+    networkThreat: network.networkThreat,
+    policy,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Map composite score to policy decision using configured thresholds.
+ * Default thresholds are patent-critical nominal values.
+ */
+export function scoreToPolicy(
+  score: number,
+  thresholds: PolicyThresholds = DEFAULT_POLICY_THRESHOLDS,
+): PolicyDecision {
+  if (score >= thresholds.quarantineAt) return "QUARANTINE";
+  if (score >= thresholds.blockAt) return "BLOCK";
+  if (score >= thresholds.warnAt) return "WARN";
+  return "ALLOW";
+}
+
+function clamp(v: number, lo = 0, hi = 1): number {
+  return Math.min(Math.max(v, lo), hi);
+}

package/src/session.ts

@@ -0,0 +1,49 @@
+/**
+ * Tiresias Session Manager
+ * Tracks per-session state: request count, last score, audit chain head.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { TiresiasSession, CompositeScore } from "./types.js";
+import { GENESIS_HASH } from "./audit.js";
+
+export class SessionManager {
+  private sessions: Map<string, TiresiasSession> = new Map();
+
+  create(sessionId?: string): TiresiasSession {
+    const id = sessionId ?? randomUUID();
+    const session: TiresiasSession = {
+      sessionId: id,
+      createdAt: Date.now(),
+      requestCount: 0,
+      lastScore: null,
+      auditChainHead: GENESIS_HASH,
+    };
+    this.sessions.set(id, session);
+    return session;
+  }
+
+  get(sessionId: string): TiresiasSession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  getOrCreate(sessionId: string): TiresiasSession {
+    return this.sessions.get(sessionId) ?? this.create(sessionId);
+  }
+
+  update(sessionId: string, score: CompositeScore, newChainHash: string): void {
+    const session = this.getOrCreate(sessionId);
+    session.requestCount += 1;
+    session.lastScore = score;
+    session.auditChainHead = newChainHash;
+    this.sessions.set(sessionId, session);
+  }
+
+  list(): TiresiasSession[] {
+    return Array.from(this.sessions.values());
+  }
+
+  delete(sessionId: string): boolean {
+    return this.sessions.delete(sessionId);
+  }
+}

package/src/tiresias.ts

@@ -0,0 +1,215 @@
+/**
+ * Tiresias SDK — Main Orchestrator
+ *
+ * tiresias.call(messages, adapter, options) is the high-level entry point.
+ * It runs the three safety signals, computes composite score, applies policy,
+ * writes a hash-chained audit entry, and either passes through to the LLM
+ * or blocks the request.
+ */
+
+import type {
+  Message,
+  LLMAdapter,
+  LLMCallOptions,
+  TiresiasCallResult,
+  TiresiasConfig,
+  WatchSignal,
+  ReportSignal,
+  NetworkSignal,
+} from "./types.js";
+import { DEFAULT_POLICY_THRESHOLDS } from "./types.js";
+import { computeCompositeScore } from "./scoring.js";
+import { buildAuditEntry, MemoryAuditStore } from "./audit.js";
+import { SessionManager } from "./session.js";
+
+// Lazily import sub-modules to allow tree-shaking
+import {
+  generateKey,
+  injectGuard,
+  stripEcho,
+  verify,
+} from "@salucallc/tiresias-watch";
+
+import { scan } from "@salucallc/tiresias-report";
+
+export class Tiresias {
+  private config: TiresiasConfig;
+  private sessions: SessionManager;
+  private auditStore: MemoryAuditStore;
+
+  constructor(config: TiresiasConfig = {}) {
+    this.config = config;
+    this.sessions = new SessionManager();
+    this.auditStore = (config.auditStore as MemoryAuditStore) ?? new MemoryAuditStore();
+  }
+
+  /**
+   * Main entry point.
+   * 1. Run watch (injection detection)
+   * 2. Run report (PII scan)
+   * 3. Get network signal (passthrough or provider)
+   * 4. Compute composite score
+   * 5. Apply policy
+   * 6. Write hash-chained audit entry
+   * 7. If ALLOW/WARN: call LLM adapter and return response
+   *    If BLOCK/QUARANTINE: return without calling LLM
+   */
+  async call(
+    messages: Message[],
+    adapter: LLMAdapter,
+    options: LLMCallOptions & { sessionId?: string } = {},
+  ): Promise<TiresiasCallResult> {
+    const { sessionId: sid, ...llmOptions } = options;
+    const session = this.sessions.getOrCreate(sid ?? "default");
+
+    // Serialize request for hashing and scanning
+    const requestContent = messages.map((m) => `${m.role}: ${m.content}`).join("\n");
+
+    // ── Signal 1: Injection Detection (tiresias-watch) ────────────────────────
+    const key = generateKey();
+    const guardedMessages = messages.map((m) => ({
+      ...m,
+      content: injectGuard(m.content, key),
+    }));
+    // We scan the original content for injection markers from prior round-trips.
+    // For a fresh request, injection threat comes from structural analysis.
+    const watchSignal = await this.runWatchSignal(messages, key);
+
+    // ── Signal 2: PII Detection (tiresias-report) ─────────────────────────────
+    const reportSignal = await this.runReportSignal(requestContent);
+
+    // ── Signal 3: Network Threat (tiresias-network or stub) ───────────────────
+    const networkSignal = await this.runNetworkSignal();
+
+    // ── Composite Score (PATENT-CRITICAL) ─────────────────────────────────────
+    const thresholds = this.config.policy ?? DEFAULT_POLICY_THRESHOLDS;
+    const composite = computeCompositeScore(watchSignal, reportSignal, networkSignal, thresholds);
+
+    // ── Audit Entry (PATENT-CRITICAL hash chain) ──────────────────────────────
+    const prevHash = await this.auditStore.getHead(session.sessionId);
+    const auditEntry = buildAuditEntry(
+      session.sessionId,
+      requestContent,
+      composite,
+      prevHash,
+    );
+    await this.auditStore.append(auditEntry);
+    this.sessions.update(session.sessionId, composite, auditEntry.chainHash);
+
+    const blocked = composite.policy === "BLOCK" || composite.policy === "QUARANTINE";
+
+    // ── Policy Callbacks ──────────────────────────────────────────────────────
+    if (composite.policy === "WARN" && this.config.onWarn) {
+      await this.config.onWarn(auditEntry);
+    }
+    if (blocked && this.config.onBlock) {
+      await this.config.onBlock(auditEntry);
+    }
+
+    // ── LLM Call ──────────────────────────────────────────────────────────────
+    let llmResponse;
+    if (!blocked) {
+      // Use guarded messages so we can detect echo manipulation in future turns
+      llmResponse = await adapter.call(guardedMessages, llmOptions);
+
+      // Strip guard tokens from response before returning to caller
+      if (llmResponse.content) {
+        llmResponse = {
+          ...llmResponse,
+          content: stripEcho(llmResponse.content),
+        };
+      }
+    }
+
+    return {
+      decision: composite.policy,
+      composite,
+      auditEntry,
+      llmResponse,
+      blocked,
+    };
+  }
+
+  /** Audit log access */
+  get audit(): MemoryAuditStore {
+    return this.auditStore;
+  }
+
+  /** Session access */
+  get session(): SessionManager {
+    return this.sessions;
+  }
+
+  // ── Private signal runners ────────────────────────────────────────────────
+
+  private async runWatchSignal(messages: Message[], key: string): Promise<WatchSignal> {
+    // For a fresh outbound request, injection threat is determined by
+    // checking if any inbound message contains injection markers aimed at
+    // hijacking the guard echo. We use verifyResponse on each user message.
+    let maxThreat = 0;
+    let echoFound = false;
+    let failureMode: string | undefined;
+
+    for (const m of messages) {
+      if (m.role !== "user") continue;
+      const result = verify(m.content, key);
+      if (!result.verified) {
+        if (result.failure_mode) {
+          failureMode = result.failure_mode;
+          maxThreat = Math.max(maxThreat, result.threat);
+          echoFound = true;
+        }
+      }
+    }
+
+    // Check for common injection patterns in user messages
+    const injectionPatterns = [
+      /ignore\s+(all\s+)?previous\s+instructions?/i,
+      /you\s+are\s+now\s+(?:a\s+)?(?:an?\s+)?(?:different|new|another|alternative)/i,
+      /disregard\s+(?:your\s+)?(?:previous\s+|prior\s+)?(?:instructions?|rules?|guidelines?)/i,
+      /\[SYSTEM\]/i,
+      /<\|system\|>/i,
+      /###\s*SYSTEM/i,
+    ];
+
+    for (const m of messages) {
+      if (m.role !== "user") continue;
+      let patternHits = 0;
+      for (const p of injectionPatterns) {
+        if (p.test(m.content)) patternHits++;
+      }
+      if (patternHits > 0) {
+        maxThreat = Math.max(maxThreat, Math.min(0.3 + patternHits * 0.2, 1.0));
+      }
+    }
+
+    return { injectionThreat: maxThreat, echoFound, failureMode };
+  }
+
+  private async runReportSignal(content: string): Promise<ReportSignal> {
+    try {
+      const result = await scan(content);
+      const highConf = result.entities.filter((e) => e.confidence > 0.85).length;
+      return {
+        piiRisk: result.risk,
+        entityCount: result.entity_count,
+        highConfidenceCount: highConf,
+      };
+    } catch {
+      // Fail safe: treat scan failure as zero risk (don't block on scan error)
+      return { piiRisk: 0, entityCount: 0, highConfidenceCount: 0 };
+    }
+  }
+
+  private async runNetworkSignal(): Promise<NetworkSignal> {
+    if (this.config.networkThreatProvider) {
+      try {
+        const threat = await this.config.networkThreatProvider();
+        return { networkThreat: Math.min(Math.max(threat, 0), 1) };
+      } catch {
+        return { networkThreat: 0 };
+      }
+    }
+    return { networkThreat: 0 };
+  }
+}

package/src/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Tiresias SDK — Shared Types
+ * Composite scoring, policy engine, session, and audit types.
+ */
+
+// ── Signals from sub-modules ──────────────────────────────────────────────────
+
+export interface WatchSignal {
+  injectionThreat: number;   // [0,1] — from tiresias-watch
+  echoFound: boolean;
+  failureMode?: string;
+}
+
+export interface ReportSignal {
+  piiRisk: number;           // [0,1] — from tiresias-report
+  entityCount: number;
+  highConfidenceCount: number;
+}
+
+export interface NetworkSignal {
+  networkThreat: number;     // [0,1] — from tiresias-network (future)
+}
+
+// ── Composite Scoring ─────────────────────────────────────────────────────────
+
+/**
+ * PATENT-CRITICAL: Composite risk score formula (SALUCA-005 / cross_layer_orchestration)
+ * score = (0.5 × injection_threat) + (0.4 × pii_risk) + (0.1 × network_threat)
+ */
+export interface CompositeScore {
+  score: number;             // [0,1]
+  injectionThreat: number;
+  piiRisk: number;
+  networkThreat: number;
+  policy: PolicyDecision;
+  timestamp: number;         // Unix ms
+}
+
+// ── Policy Engine ─────────────────────────────────────────────────────────────
+
+export type PolicyDecision = "ALLOW" | "WARN" | "BLOCK" | "QUARANTINE";
+
+/**
+ * Policy thresholds (configurable, defaults are patent-critical values)
+ * ALLOW    < 0.30
+ * WARN     < 0.60
+ * BLOCK    < 0.85
+ * QUARANTINE >= 0.85
+ */
+export interface PolicyThresholds {
+  warnAt: number;       // default 0.30
+  blockAt: number;      // default 0.60
+  quarantineAt: number; // default 0.85
+}
+
+export const DEFAULT_POLICY_THRESHOLDS: PolicyThresholds = {
+  warnAt: 0.30,
+  blockAt: 0.60,
+  quarantineAt: 0.85,
+};
+
+// ── Audit Log ─────────────────────────────────────────────────────────────────
+
+/**
+ * PATENT-CRITICAL: Hash-chained audit log entry (SALUCA-005)
+ * chain_hash = SHA3-256(prev_chain_hash || session_id || timestamp || score_json)
+ */
+export interface AuditEntry {
+  entryId: string;          // UUID v4
+  sessionId: string;
+  timestamp: number;        // Unix ms
+  requestHash: string;      // SHA-256 of raw request content
+  composite: CompositeScore;
+  chainHash: string;        // SHA3-256 chain link — PATENT-CRITICAL
+  prevChainHash: string;    // "genesis" for first entry
+  metadata?: Record<string, unknown>;
+}
+
+// ── Session ───────────────────────────────────────────────────────────────────
+
+export interface TiresiasSession {
+  sessionId: string;
+  createdAt: number;
+  requestCount: number;
+  lastScore: CompositeScore | null;
+  auditChainHead: string;   // most recent chain hash
+}
+
+// ── LLM Adapters ─────────────────────────────────────────────────────────────
+
+export type MessageRole = "system" | "user" | "assistant";
+
+export interface Message {
+  role: MessageRole;
+  content: string;
+}
+
+export interface LLMResponse {
+  content: string;
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+  raw?: unknown;
+}
+
+export interface LLMAdapter {
+  call(messages: Message[], options?: LLMCallOptions): Promise<LLMResponse>;
+}
+
+export interface LLMCallOptions {
+  model?: string;
+  maxTokens?: number;
+  temperature?: number;
+  systemPrompt?: string;
+}
+
+// ── Tiresias SDK Config ───────────────────────────────────────────────────────
+
+export interface TiresiasConfig {
+  policy?: PolicyThresholds;
+  auditStore?: AuditStore;
+  networkThreatProvider?: () => Promise<number>;
+  onBlock?: (entry: AuditEntry) => void | Promise<void>;
+  onWarn?: (entry: AuditEntry) => void | Promise<void>;
+}
+
+// ── Audit Store Interface ─────────────────────────────────────────────────────
+
+export interface AuditStore {
+  append(entry: AuditEntry): Promise<void>;
+  getHead(sessionId: string): Promise<string>;  // returns latest chain hash
+  query(sessionId: string, limit?: number): Promise<AuditEntry[]>;
+}
+
+// ── Result from tiresias.call() ───────────────────────────────────────────────
+
+export interface TiresiasCallResult {
+  decision: PolicyDecision;
+  composite: CompositeScore;
+  auditEntry: AuditEntry;
+  llmResponse?: LLMResponse;  // undefined if BLOCK or QUARANTINE
+  blocked: boolean;
+}