@aumos/agentshield 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * TypeScript interfaces for the AgentShield defense layer.
+ *
+ * Mirrors the Pydantic models defined in:
+ *   agentshield.schemas.threats
+ *   agentshield.schemas.scan
+ *   agentshield.schemas.defense
+ *
+ * All interfaces use readonly fields to match Python's frozen Pydantic models.
+ */
+/**
+ * Severity level of a detected threat.
+ * Maps to ThreatLevel enum in Python.
+ */
+export type ThreatLevel = "critical" | "high" | "medium" | "low" | "info";
+/**
+ * The layer of the defense pipeline that produced a finding.
+ * Maps to DefenseLayer enum in Python.
+ */
+export type DefenseLayer = "input_validation" | "output_validation" | "tool_call_validation" | "pii_detection" | "prompt_injection" | "malicious_payload";
+/** A single threat or anomaly detected by one defense rule. */
+export interface ThreatFinding {
+    /** Unique identifier for this finding. */
+    readonly finding_id: string;
+    /** Defense layer that produced this finding. */
+    readonly layer: DefenseLayer;
+    /** Threat severity. */
+    readonly level: ThreatLevel;
+    /** Short rule identifier (e.g. "PI-001", "PII-EMAIL"). */
+    readonly rule_id: string;
+    /** Human-readable description of the finding. */
+    readonly description: string;
+    /** Character offset in the scanned content where the issue begins (-1 if not applicable). */
+    readonly offset: number;
+    /** Redacted excerpt of the offending content (never the raw payload). */
+    readonly excerpt: string;
+    /** Arbitrary metadata from the rule implementation. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/** Result of scanning a single piece of content through the defense pipeline. */
+export interface ScanResult {
+    /** Unique identifier for this scan operation. */
+    readonly scan_id: string;
+    /** ISO-8601 UTC timestamp of when the scan completed. */
+    readonly scanned_at: string;
+    /** Agent that triggered the scan. */
+    readonly agent_id: string;
+    /** Whether any finding at level "high" or "critical" was detected. */
+    readonly blocked: boolean;
+    /** All findings produced by the scan, ordered by severity descending. */
+    readonly findings: readonly ThreatFinding[];
+    /** Highest threat level across all findings ("info" when no threats found). */
+    readonly max_level: ThreatLevel;
+    /** Total scan duration in milliseconds. */
+    readonly duration_ms: number;
+}
+/** Aggregated threat statistics for a single agent over a time window. */
+export interface ThreatDetectionResult {
+    /** Agent being reported on. */
+    readonly agent_id: string;
+    /** ISO-8601 UTC start of the reporting window. */
+    readonly window_start: string;
+    /** ISO-8601 UTC end of the reporting window. */
+    readonly window_end: string;
+    /** Total number of scans in this window. */
+    readonly total_scans: number;
+    /** Number of scans that triggered a block action. */
+    readonly blocked_count: number;
+    /** Breakdown of finding counts by threat level. */
+    readonly findings_by_level: Readonly<Record<ThreatLevel, number>>;
+    /** Breakdown of finding counts by defense layer. */
+    readonly findings_by_layer: Readonly<Record<DefenseLayer, number>>;
+    /** Most frequently triggered rule_ids in this window. */
+    readonly top_rules: readonly string[];
+}
+/** Request to validate a proposed tool call before execution. */
+export interface ToolCallValidationRequest {
+    /** Agent submitting the tool call. */
+    readonly agent_id: string;
+    /** Name of the tool being called. */
+    readonly tool_name: string;
+    /** Arguments that will be passed to the tool. */
+    readonly tool_arguments: Readonly<Record<string, unknown>>;
+    /** Optional session context for policy decisions. */
+    readonly session_id?: string;
+}
+/** Outcome of a tool-call validation check. */
+export interface ToolCallValidationResult {
+    /** Whether the tool call is permitted to proceed. */
+    readonly allowed: boolean;
+    /** Reason the call was blocked, or null if allowed. */
+    readonly block_reason: string | null;
+    /** Findings raised during validation. */
+    readonly findings: readonly ThreatFinding[];
+    /** Validation duration in milliseconds. */
+    readonly duration_ms: number;
+}
+/** Standard error payload returned by the AgentShield API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * TypeScript interfaces for the AgentShield defense layer.
+ *
+ * Mirrors the Pydantic models defined in:
+ *   agentshield.schemas.threats
+ *   agentshield.schemas.scan
+ *   agentshield.schemas.defense
+ *
+ * All interfaces use readonly fields to match Python's frozen Pydantic models.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@aumos/agentshield",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS AgentShield defense layer — threat detection, input/output scanning, and tool-call validation",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agentshield",
+    "threat-detection",
+    "prompt-injection",
+    "defense",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/invincible-jha/agentshield"
+  }
+}

package/src/client.ts

@@ -0,0 +1,240 @@
+/**
+ * HTTP client for the AgentShield defense API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentShieldClient } from "@aumos/agentshield";
+ *
+ * const client = createAgentShieldClient({ baseUrl: "http://localhost:8091" });
+ *
+ * const result = await client.scanInput({
+ *   agent_id: "my-agent",
+ *   content: userMessage,
+ *   session_id: "session-abc",
+ * });
+ *
+ * if (result.ok && result.data.blocked) {
+ *   console.warn("Input blocked:", result.data.findings);
+ * }
+ * ```
+ */
+
+import type {
+  ApiError,
+  ApiResult,
+  ScanResult,
+  ThreatDetectionResult,
+  ToolCallValidationRequest,
+  ToolCallValidationResult,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentShieldClient. */
+export interface AgentShieldClientConfig {
+  /** Base URL of the AgentShield server (e.g. "http://localhost:8091"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 10000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Scan request types
+// ---------------------------------------------------------------------------
+
+/** Request body for input or output scanning. */
+export interface ContentScanRequest {
+  /** Agent that produced or received the content. */
+  readonly agent_id: string;
+  /** Raw content string to scan. */
+  readonly content: string;
+  /** Optional session context. */
+  readonly session_id?: string;
+  /** Arbitrary metadata forwarded to rule implementations. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the AgentShield defense server. */
+export interface AgentShieldClient {
+  /**
+   * Scan content arriving as agent input (e.g. user messages, tool results).
+   *
+   * @param request - Content and context to scan.
+   * @returns ScanResult with findings and a blocked flag.
+   */
+  scanInput(request: ContentScanRequest): Promise<ApiResult<ScanResult>>;
+
+  /**
+   * Scan content produced as agent output (e.g. LLM responses, tool invocations).
+   *
+   * @param request - Content and context to scan.
+   * @returns ScanResult with findings and a blocked flag.
+   */
+  scanOutput(request: ContentScanRequest): Promise<ApiResult<ScanResult>>;
+
+  /**
+   * Retrieve aggregated threat detection statistics for an agent.
+   *
+   * @param options - Agent and optional time-window filters.
+   * @returns ThreatDetectionResult summarising threat activity.
+   */
+  getThreatReport(options: {
+    agentId: string;
+    windowStart?: string;
+    windowEnd?: string;
+  }): Promise<ApiResult<ThreatDetectionResult>>;
+
+  /**
+   * Validate a proposed tool call before it is executed.
+   *
+   * @param request - Tool name, arguments, and calling-agent context.
+   * @returns ToolCallValidationResult indicating whether execution is permitted.
+   */
+  validateToolCall(
+    request: ToolCallValidationRequest,
+  ): Promise<ApiResult<ToolCallValidationResult>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the AgentShield server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentShieldClient instance.
+ */
+export function createAgentShieldClient(
+  config: AgentShieldClientConfig,
+): AgentShieldClient {
+  const { baseUrl, timeoutMs = 10_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async scanInput(
+      request: ContentScanRequest,
+    ): Promise<ApiResult<ScanResult>> {
+      return fetchJson<ScanResult>(
+        `${baseUrl}/scan/input`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async scanOutput(
+      request: ContentScanRequest,
+    ): Promise<ApiResult<ScanResult>> {
+      return fetchJson<ScanResult>(
+        `${baseUrl}/scan/output`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getThreatReport(options: {
+      agentId: string;
+      windowStart?: string;
+      windowEnd?: string;
+    }): Promise<ApiResult<ThreatDetectionResult>> {
+      const params = new URLSearchParams({ agent_id: options.agentId });
+      if (options.windowStart !== undefined) {
+        params.set("window_start", options.windowStart);
+      }
+      if (options.windowEnd !== undefined) {
+        params.set("window_end", options.windowEnd);
+      }
+      return fetchJson<ThreatDetectionResult>(
+        `${baseUrl}/threats/report?${params.toString()}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async validateToolCall(
+      request: ToolCallValidationRequest,
+    ): Promise<ApiResult<ToolCallValidationResult>> {
+      return fetchJson<ToolCallValidationResult>(
+        `${baseUrl}/validate/tool-call`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @aumos/agentshield
+ *
+ * TypeScript client for the AumOS AgentShield defense layer.
+ * Provides HTTP client, synchronous input scanner, and threat-detection type definitions.
+ */
+
+// Client and configuration
+export type { AgentShieldClient, AgentShieldClientConfig, ContentScanRequest } from "./client.js";
+export { createAgentShieldClient } from "./client.js";
+
+// Core types
+export type {
+  ThreatLevel,
+  DefenseLayer,
+  ThreatFinding,
+  ScanResult,
+  ThreatDetectionResult,
+  ToolCallValidationRequest,
+  ToolCallValidationResult,
+  ApiError,
+  ApiResult,
+} from "./types.js";
+
+// Input scanner
+export type { InputScanner, ScanOptions } from "./scanner.js";
+export { createInputScanner } from "./scanner.js";