@auxdynamics/mastguard-agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AuxDynamics Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @auxdynamics/mastguard-agent-sdk
+
+> Runtime AI security SDK for MastGuard — wraps any LLM call with prompt injection detection, scope enforcement, and tamper-evident audit logging.
+
+[![npm version](https://img.shields.io/npm/v/@auxdynamics/mastguard-agent-sdk)](https://www.npmjs.com/package/@auxdynamics/mastguard-agent-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Installation
+
+```bash
+npm install @auxdynamics/mastguard-agent-sdk
+```
+
+## Quickstart
+
+```ts
+import { MastGuardShield } from '@auxdynamics/mastguard-agent-sdk';
+
+const shield = new MastGuardShield({
+  apiKey: process.env.MASTGUARD_API_KEY,
+  policy: 'standard',
+  agentId: 'my-customer-support-bot',
+  organizationId: 'org-abc123',
+});
+
+const response = await shield.protect(
+  openai.chat.completions.create({ model: 'gpt-4o', messages }),
+  { sessionId: req.user.id, toolCalls: pendingToolCalls }
+);
+
+if (!response.allowed) {
+  console.log('Blocked:', response.violations);
+}
+```
+
+## Authentication
+
+Get your API key from **[https://dashboard.mastguard.io](https://dashboard.mastguard.io) → Settings → API Keys**.
+
+Pass it as `apiKey` in `ShieldConfig` or set the `MASTGUARD_API_KEY` environment variable. All requests use the `X-API-Key` header.
+
+## Configuration
+
+| Option           | Type                   | Required | Default                      | Description                                               |
+| ---------------- | ---------------------- | -------- | ---------------------------- | --------------------------------------------------------- |
+| `apiKey`         | `string`               | Yes      | —                            | MastGuard API key from dashboard                          |
+| `policy`         | `string`               | Yes      | —                            | Policy name: `standard`, `hipaa`, or `enterprise`         |
+| `agentId`        | `string`               | Yes      | —                            | Unique identifier for this agent                          |
+| `organizationId` | `string`               | Yes      | —                            | Your MastGuard organization ID                            |
+| `endpoint`       | `string`               | No       | `https://api.mastguard.io`   | Override API base URL (staging / self-hosted)             |
+| `mode`           | `'block' \| 'monitor'` | No       | `'block'`                    | `block` enforces policy; `monitor` logs only              |
+| `timeout`        | `number`               | No       | `3000`                       | Ingest API timeout in milliseconds                        |
+
+## Shield Methods
+
+### `shield.protect(llmCall, options)`
+
+Wraps any LLM call — evaluates the request and response against your configured policy.
+
+```ts
+const result = await shield.protect(
+  openai.chat.completions.create({ model: 'gpt-4o', messages }),
+  {
+    sessionId: 'session-xyz',   // required — ties events to a session
+    toolCalls: [...],           // optional — pending tool calls to inspect
+    userId: 'user-123',         // optional — for per-user audit trails
+    metadata: { env: 'prod' },  // optional — attached to audit records
+  }
+);
+```
+
+**Returns** `ShieldResult<T>`:
+
+| Field        | Type                 | Description                                      |
+| ------------ | -------------------- | ------------------------------------------------ |
+| `data`       | `T \| null`          | The original LLM response (null if blocked)      |
+| `allowed`    | `boolean`            | `true` if the call passed all policy checks      |
+| `violations` | `ViolationRecord[]`  | List of policy violations found (empty if clean) |
+| `auditId`    | `string \| undefined`| Tamper-evident audit record ID                   |
+| `sessionId`  | `string`             | Session ID echoed back for correlation           |
+
+## Detection Layers
+
+| Layer              | Rule ID           | What It Detects                                            | Research Basis   |
+| ------------------ | ----------------- | ---------------------------------------------------------- | ---------------- |
+| Prompt Injection   | `RULE-INJ-001`    | Direct instruction-override attempts in user input         | arXiv:2510.22620 |
+| Indirect Injection | `RULE-INJ-002`    | Instructions embedded in tool outputs or RAG results       | arXiv:2510.22620 |
+| Scope Violation    | `RULE-SCOPE-001`  | Tool calls outside the agent's declared policy             | arXiv:2510.22620 |
+| Data Exfiltration  | `RULE-EXFIL-PII-*`| PII, credentials, API keys in LLM responses                | arXiv:2510.22620 |
+| Multi-Step Attack  | `RULE-CHAIN-001`  | Sequential tool calls matching known attack chains         | arXiv:2603.11214 |
+
+All detections are run by `ThreatDetector` and evaluated against your policy by `PolicyEngine`. Events are logged via `AuditLogger` with SHA-256 chain hashing for tamper evidence.
+
+## Error Handling
+
+```ts
+const result = await shield.protect(llmCall, { sessionId });
+
+if (!result.allowed) {
+  for (const v of result.violations) {
+    console.error(`[${v.severity}] ${v.category}: ${v.description}`);
+    // v.action is 'block' | 'flag' | 'log'
+    // v.evidence contains the raw matched content
+  }
+  // result.data is null when mode === 'block' and violations were found
+}
+```
+
+In `monitor` mode, `allowed` is always `true` — violations are logged to MastGuard but the call is never blocked, letting you evaluate policy impact before enforcing it.
+
+## TypeScript
+
+Full TypeScript support is included — no `@types` package needed. CJS and ESM builds are both shipped.
+
+```ts
+import type {
+  ShieldConfig,
+  ShieldResult,
+  ViolationRecord,
+  ToolCallRecord,
+  ProtectOptions,
+  EvaluationResult,
+  PolicyTier,
+  ShieldMode,
+  Severity,
+  ViolationAction,
+} from '@auxdynamics/mastguard-agent-sdk';
+```
+
+## Related Packages
+
+This package handles **runtime AI security monitoring**.
+
+If you need to integrate with the MastGuard **governance platform** (audit logs, HITL queues, webhooks, compliance dashboards), use the companion SDK:
+
+[@auxdynamics/mastguard-sdk](https://www.npmjs.com/package/@auxdynamics/mastguard-sdk)
+
+## License
+
+MIT © [AuxDynamics Inc.](https://mastguard.io)

package/dist/index.d.mts

@@ -0,0 +1,129 @@
+type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type ViolationAction = 'block' | 'flag' | 'log';
+type EventType = 'prompt_injection' | 'scope_violation' | 'data_exfiltration' | 'multi_step_attack' | 'normal';
+type ShieldMode = 'block' | 'monitor';
+type PolicyTier = 'standard' | 'hipaa' | 'enterprise';
+interface ViolationRecord {
+    category: string;
+    severity: Severity;
+    description: string;
+    action: ViolationAction;
+    evidence: string;
+}
+interface ShieldConfig {
+    apiKey: string;
+    organizationId: string;
+    agentId: string;
+    policy?: string;
+    mode?: ShieldMode;
+    apiBaseUrl?: string;
+    timeoutMs?: number;
+}
+interface ToolCall {
+    name: string;
+    parameters?: Record<string, unknown>;
+}
+interface TurnRecord {
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: ToolCall[];
+}
+interface ProtectOptions {
+    sessionId: string;
+    toolCalls?: ToolCall[];
+    toolOutputs?: string[];
+    sessionHistory?: TurnRecord[];
+    tokenCount?: number;
+}
+interface ShieldResult<T> {
+    data: T | null;
+    allowed: boolean;
+    violations: ViolationRecord[];
+    auditId?: string;
+}
+interface DetectOptions {
+    prompt: string;
+    response?: string;
+    toolCalls?: ToolCall[];
+    toolOutputs?: string[];
+    sessionHistory?: TurnRecord[];
+    allowedTools?: string[];
+    tokenCount?: number;
+}
+interface EvaluationResult {
+    violations: ViolationRecord[];
+    allow: boolean;
+    worstSeverity: Severity | null;
+}
+
+declare class MastGuardShield {
+    private readonly config;
+    private readonly sessionTracker;
+    private readonly policyEngine;
+    private readonly auditLogger;
+    constructor(config: ShieldConfig);
+    protect<T>(llmCall: Promise<T>, options: ProtectOptions): Promise<ShieldResult<T>>;
+    clearSession(sessionId: string): void;
+    invalidatePolicyCache(): void;
+}
+
+declare class ThreatDetector {
+    static detect(options: DetectOptions): EvaluationResult;
+    private static detectPromptInjection;
+    private static detectScopeViolation;
+    private static detectDataExfiltration;
+    private static detectIndirectInjection;
+    private static detectMultiStepAttack;
+}
+
+interface IngestPayload {
+    session_id: string;
+    agent_id: string;
+    org_id: string;
+    policy_id: string | null;
+    event_type: string;
+    prompt: string;
+    response: string | null;
+    tool_calls: Array<{
+        name: string;
+        parameters?: Record<string, unknown> | undefined;
+    }>;
+    tool_outputs: string[];
+    session_history: Array<{
+        role: string;
+        content: string;
+    }>;
+    token_count: number;
+    duration_ms: number;
+}
+declare class AuditLogger {
+    private readonly config;
+    constructor(config: ShieldConfig);
+    static computeChainHash(prevHash: string | null, contentJson: string, salt: string): string;
+    static verifyChain(entries: Array<{
+        content: string;
+        hash: string;
+    }>, salt: string): boolean;
+    ingest(payload: IngestPayload): Promise<string | null>;
+}
+
+declare class PolicyEngine {
+    private readonly config;
+    private policyCache;
+    constructor(config: ShieldConfig);
+    evaluate(options: DetectOptions, policyName: string): Promise<EvaluationResult>;
+    private fetchPolicy;
+    invalidateCache(): void;
+}
+
+declare class SessionTracker {
+    private sessions;
+    addTurn(sessionId: string, turn: TurnRecord): void;
+    getHistory(sessionId: string): TurnRecord[];
+    getToolCallSequence(sessionId: string): string[];
+    clearSession(sessionId: string): void;
+    getSessionCount(): number;
+    pruneOldSessions(maxAgeMs?: number): void;
+}
+
+export { AuditLogger, type DetectOptions, type EvaluationResult, type EventType, MastGuardShield, PolicyEngine, type PolicyTier, type ProtectOptions, SessionTracker, type Severity, type ShieldConfig, type ShieldMode, type ShieldResult, ThreatDetector, type ToolCall, type TurnRecord, type ViolationAction, type ViolationRecord };

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type ViolationAction = 'block' | 'flag' | 'log';
+type EventType = 'prompt_injection' | 'scope_violation' | 'data_exfiltration' | 'multi_step_attack' | 'normal';
+type ShieldMode = 'block' | 'monitor';
+type PolicyTier = 'standard' | 'hipaa' | 'enterprise';
+interface ViolationRecord {
+    category: string;
+    severity: Severity;
+    description: string;
+    action: ViolationAction;
+    evidence: string;
+}
+interface ShieldConfig {
+    apiKey: string;
+    organizationId: string;
+    agentId: string;
+    policy?: string;
+    mode?: ShieldMode;
+    apiBaseUrl?: string;
+    timeoutMs?: number;
+}
+interface ToolCall {
+    name: string;
+    parameters?: Record<string, unknown>;
+}
+interface TurnRecord {
+    role: 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: ToolCall[];
+}
+interface ProtectOptions {
+    sessionId: string;
+    toolCalls?: ToolCall[];
+    toolOutputs?: string[];
+    sessionHistory?: TurnRecord[];
+    tokenCount?: number;
+}
+interface ShieldResult<T> {
+    data: T | null;
+    allowed: boolean;
+    violations: ViolationRecord[];
+    auditId?: string;
+}
+interface DetectOptions {
+    prompt: string;
+    response?: string;
+    toolCalls?: ToolCall[];
+    toolOutputs?: string[];
+    sessionHistory?: TurnRecord[];
+    allowedTools?: string[];
+    tokenCount?: number;
+}
+interface EvaluationResult {
+    violations: ViolationRecord[];
+    allow: boolean;
+    worstSeverity: Severity | null;
+}
+
+declare class MastGuardShield {
+    private readonly config;
+    private readonly sessionTracker;
+    private readonly policyEngine;
+    private readonly auditLogger;
+    constructor(config: ShieldConfig);
+    protect<T>(llmCall: Promise<T>, options: ProtectOptions): Promise<ShieldResult<T>>;
+    clearSession(sessionId: string): void;
+    invalidatePolicyCache(): void;
+}
+
+declare class ThreatDetector {
+    static detect(options: DetectOptions): EvaluationResult;
+    private static detectPromptInjection;
+    private static detectScopeViolation;
+    private static detectDataExfiltration;
+    private static detectIndirectInjection;
+    private static detectMultiStepAttack;
+}
+
+interface IngestPayload {
+    session_id: string;
+    agent_id: string;
+    org_id: string;
+    policy_id: string | null;
+    event_type: string;
+    prompt: string;
+    response: string | null;
+    tool_calls: Array<{
+        name: string;
+        parameters?: Record<string, unknown> | undefined;
+    }>;
+    tool_outputs: string[];
+    session_history: Array<{
+        role: string;
+        content: string;
+    }>;
+    token_count: number;
+    duration_ms: number;
+}
+declare class AuditLogger {
+    private readonly config;
+    constructor(config: ShieldConfig);
+    static computeChainHash(prevHash: string | null, contentJson: string, salt: string): string;
+    static verifyChain(entries: Array<{
+        content: string;
+        hash: string;
+    }>, salt: string): boolean;
+    ingest(payload: IngestPayload): Promise<string | null>;
+}
+
+declare class PolicyEngine {
+    private readonly config;
+    private policyCache;
+    constructor(config: ShieldConfig);
+    evaluate(options: DetectOptions, policyName: string): Promise<EvaluationResult>;
+    private fetchPolicy;
+    invalidateCache(): void;
+}
+
+declare class SessionTracker {
+    private sessions;
+    addTurn(sessionId: string, turn: TurnRecord): void;
+    getHistory(sessionId: string): TurnRecord[];
+    getToolCallSequence(sessionId: string): string[];
+    clearSession(sessionId: string): void;
+    getSessionCount(): number;
+    pruneOldSessions(maxAgeMs?: number): void;
+}
+
+export { AuditLogger, type DetectOptions, type EvaluationResult, type EventType, MastGuardShield, PolicyEngine, type PolicyTier, type ProtectOptions, SessionTracker, type Severity, type ShieldConfig, type ShieldMode, type ShieldResult, ThreatDetector, type ToolCall, type TurnRecord, type ViolationAction, type ViolationRecord };