citadel0 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moulick Bose
+
+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,124 @@
+# Citadel 0
+
+Programmatic security gateway and policy engine for AI agents built on Convex and TypeScript.
+
+Citadel 0 inspects tool calls and actions before execution. It provides deterministic policy evaluation, heuristic threat scanning (prompt injections and secret leaks), and asynchronous human-in-the-loop (HITL) approval queues.
+
+---
+
+## Capabilities
+
+- **Hybrid Evaluation Pipeline**: Evaluates deterministic rules first, followed by heuristic regex threat scanning.
+- **Threat Scanner**: Detects prompt injection patterns, roleplay overrides, model token delimiters, and exposed API/private keys in parameters.
+- **Human-in-the-Loop Reviews**: Pauses execution on `REVIEW` policy verdicts, logging a pending state to Convex and polling until resolved.
+- **Tool Wrappers**: Adapters for wrapping function calls (`wrapTool` and `wrapToolWithReview`).
+- **Audit Logging**: Logs every execution attempt, latency, risk score, and matched policies to Convex.
+- **Dual Bundle**: Ships ESM and CommonJS builds with TypeScript declarations.
+
+---
+
+## Installation
+
+```bash
+npm install citadel0
+```
+
+```bash
+pnpm add citadel0
+```
+
+---
+
+## Usage
+
+### Client Initialization
+
+```typescript
+import { CitadelClient } from 'citadel0';
+
+const citadel = new CitadelClient({
+  baseUrl: '[https://energetic-starfish-637.convex.site](https://energetic-starfish-637.convex.site)',
+  agentToken: process.env.CITADEL_AGENT_TOKEN!,
+});
+```
+
+### Action Check
+
+```typescript
+const verdict = await citadel.check('web.search', {
+  query: 'Convex database tutorial',
+});
+
+if (verdict.verdict.decision === 'ALLOW') {
+  await runSearch();
+}
+```
+
+### Direct Tool Guard
+
+```typescript
+import { CitadelClient, wrapTool } from 'citadel0';
+
+const citadel = new CitadelClient({
+  baseUrl: '[https://energetic-starfish-637.convex.site](https://energetic-starfish-637.convex.site)',
+  agentToken: process.env.CITADEL_AGENT_TOKEN!,
+});
+
+const executeCommand = wrapTool(citadel, {
+  name: 'system.bash',
+  execute: async (args: { command: string }) => {
+    return runCommand(args.command);
+  },
+});
+
+const output = await executeCommand.execute({ command: 'ls -la' });
+```
+
+### Human-in-the-Loop (HITL) Review
+
+```typescript
+import { CitadelClient, wrapToolWithReview } from 'citadel0';
+
+const citadel = new CitadelClient({
+  baseUrl: '[https://energetic-starfish-637.convex.site](https://energetic-starfish-637.convex.site)',
+  agentToken: process.env.CITADEL_AGENT_TOKEN!,
+});
+
+const transferFunds = wrapToolWithReview(
+  citadel,
+  {
+    name: 'finance.transfer',
+    execute: async (args: { recipient: string; amount: number }) => {
+      return transfer(args.recipient, args.amount);
+    },
+  },
+  {
+    timeoutMs: 60000,
+    pollIntervalMs: 2000,
+    onReviewPending: (auditLogId) => {
+      console.log(`Pending approval: ${auditLogId}`);
+    },
+  }
+);
+
+await transferFunds.execute({ recipient: 'alice@example.com', amount: 5000 });
+```
+
+---
+
+## API Reference
+
+### `CitadelClient`
+
+- `citadel.check(action, params, options)`: Evaluates policies against the gateway and returns `SecurityVerdict`.
+- `citadel.isAllowed(action, params, options)`: Returns boolean indicating if decision equals `ALLOW`.
+- `citadel.guard(action, params, callback, options)`: Runs callback if allowed; throws error if blocked or requiring review.
+- `citadel.guardWithReview(action, params, callback, options)`: Runs callback if allowed. If flagged for review, polls until approved or timed out.
+- `citadel.getReviewStatus(auditLogId)`: Checks resolution status of an audit log.
+
+### Utilities
+
+- `wrapTool(client, toolDefinition)`: Guards an execution function with deterministic and semantic policy checks.
+- `wrapToolWithReview(client, toolDefinition, options)`: Guards an execution function with review polling.
+- `scanPayloadSemantics(params)`: Runs offline heuristic threat scanning against input parameters.
+- `evaluatePolicies(payload, policies)`: Runs local deterministic and semantic engine directly.

package/dist/index.cjs

@@ -0,0 +1,398 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CitadelClient: () => CitadelClient,
+  evaluatePolicies: () => evaluatePolicies,
+  scanPayloadSemantics: () => scanPayloadSemantics,
+  wrapTool: () => wrapTool,
+  wrapToolWithReview: () => wrapToolWithReview
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/sdk/client.ts
+var CitadelClient = class {
+  baseUrl;
+  agentToken;
+  environment;
+  defaultSessionId;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.agentToken = config.agentToken;
+    this.environment = config.environment;
+    this.defaultSessionId = config.defaultSessionId;
+  }
+  async check(action, params = {}, options = {}) {
+    const url = `${this.baseUrl}/api/v1/check`;
+    const sessionId = options.sessionId ?? this.defaultSessionId ?? `sess_${Math.random().toString(36).slice(2, 11)}`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.agentToken}`
+      },
+      body: JSON.stringify({
+        action,
+        params,
+        sessionId,
+        environment: options.environment ?? this.environment,
+        metadata: options.metadata
+      })
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      const errorMessage = typeof errorBody.error === "string" ? errorBody.error : `Citadel gateway error: ${response.status} ${response.statusText}`;
+      throw new Error(errorMessage);
+    }
+    return await response.json();
+  }
+  async isAllowed(action, params = {}, options = {}) {
+    const result = await this.check(action, params, options);
+    return result.verdict.decision === "ALLOW";
+  }
+  async guard(action, params, callback, options = {}) {
+    const result = await this.check(action, params, options);
+    if (result.verdict.decision !== "ALLOW") {
+      throw new Error(
+        `Action '${action}' blocked by Citadel: ${result.verdict.reason}`
+      );
+    }
+    return await callback();
+  }
+  async getReviewStatus(auditLogId) {
+    const url = `${this.baseUrl}/api/v1/review/status?auditLogId=${encodeURIComponent(
+      auditLogId
+    )}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      const errorMessage = typeof errorBody.error === "string" ? errorBody.error : `Review status error: ${response.status}`;
+      throw new Error(errorMessage);
+    }
+    return await response.json();
+  }
+  async pollReview(auditLogId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 6e4;
+    const intervalMs = options.intervalMs ?? 2e3;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const status = await this.getReviewStatus(auditLogId);
+      if (status.decision !== "REVIEW") {
+        return status;
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    throw new Error(
+      `Review timed out after ${timeoutMs}ms for auditLogId: ${auditLogId}`
+    );
+  }
+  async guardWithReview(action, params, callback, options = {}) {
+    const result = await this.check(action, params, options);
+    if (result.verdict.decision === "ALLOW") {
+      return await callback();
+    }
+    if (result.verdict.decision === "BLOCK") {
+      throw new Error(
+        `Action '${action}' blocked by Citadel: ${result.verdict.reason}`
+      );
+    }
+    if (options.onReviewPending) {
+      options.onReviewPending(result.auditLogId);
+    }
+    const reviewed = await this.pollReview(result.auditLogId, {
+      timeoutMs: options.timeoutMs,
+      intervalMs: options.pollIntervalMs
+    });
+    if (reviewed.decision === "ALLOW") {
+      return await callback();
+    }
+    throw new Error(
+      `Action '${action}' rejected during human review: ${reviewed.reviewComment ?? "Rejected"}`
+    );
+  }
+};
+
+// src/sdk/tools.ts
+function wrapTool(client, tool) {
+  return {
+    ...tool,
+    execute: async (args) => {
+      return await client.guard(
+        tool.name,
+        args,
+        () => tool.execute(args),
+        tool.options
+      );
+    }
+  };
+}
+function wrapToolWithReview(client, tool, reviewOptions) {
+  return {
+    ...tool,
+    execute: async (args) => {
+      return await client.guardWithReview(
+        tool.name,
+        args,
+        () => tool.execute(args),
+        {
+          ...tool.options,
+          ...reviewOptions
+        }
+      );
+    }
+  };
+}
+
+// src/engine/semantic.ts
+var INJECTION_PATTERNS = [
+  {
+    regex: /(?:ignore|disregard|forget|bypass|override)\s+(?:all\s+)?(?:previous|prior|existing|above)\s+(?:instructions|rules|guidelines|directions|constraints)/i,
+    description: "Direct prompt instruction override",
+    score: 95
+  },
+  {
+    regex: /(?:you\s+are\s+now|act\s+as|roleplay\s+as)\s+(?:an?\s+)?(?:unfiltered|unrestricted|jailbroken|evil|dan|developer\s+mode)/i,
+    description: "Adversarial persona / DAN jailbreak attempt",
+    score: 90
+  },
+  {
+    regex: /(?:reveal|output|print|display|leak)\s+(?:the\s+)?(?:system\s+prompt|initial\s+prompt|core\s+instructions|developer\s+instructions)/i,
+    description: "System prompt extraction attempt",
+    score: 85
+  },
+  {
+    regex: /(?:\[INST\]|\[\/INST\]|<<SYS>>|<\/SYS>|<\|im_start\|>|<\|im_end\|>)/i,
+    description: "Model token delimiter injection",
+    score: 90
+  }
+];
+var CREDENTIAL_PATTERNS = [
+  {
+    regex: /(?:sk-[a-zA-Z0-9-_]{20,}|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36})/i,
+    description: "Exposed API token (OpenAI / GitHub)",
+    score: 95
+  },
+  {
+    regex: /AKIA[0-9A-Z]{16}/,
+    description: "AWS Access Key ID",
+    score: 90
+  },
+  {
+    regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/,
+    description: "Exposed Private Key block",
+    score: 99
+  }
+];
+function extractStrings(obj) {
+  const strings = [];
+  function recurse(value) {
+    if (typeof value === "string") {
+      strings.push(value);
+    } else if (Array.isArray(value)) {
+      for (const item of value) recurse(item);
+    } else if (value !== null && typeof value === "object") {
+      for (const val of Object.values(value)) {
+        recurse(val);
+      }
+    }
+  }
+  recurse(obj);
+  return strings;
+}
+function scanPayloadSemantics(params) {
+  const stringsToScan = extractStrings(params);
+  const threats = [];
+  for (const text of stringsToScan) {
+    for (const rule of INJECTION_PATTERNS) {
+      if (rule.regex.test(text)) {
+        threats.push({
+          type: "PROMPT_INJECTION",
+          confidence: rule.score / 100,
+          reason: rule.description,
+          matchedPattern: rule.regex.source
+        });
+      }
+    }
+    for (const rule of CREDENTIAL_PATTERNS) {
+      if (rule.regex.test(text)) {
+        threats.push({
+          type: "CREDENTIAL_LEAK",
+          confidence: rule.score / 100,
+          reason: rule.description,
+          matchedPattern: rule.regex.source
+        });
+      }
+    }
+  }
+  const maxScore = threats.length > 0 ? Math.max(...threats.map((t) => t.confidence * 100)) : 0;
+  return {
+    flagged: threats.length > 0,
+    threats,
+    maxRiskScore: Math.round(maxScore)
+  };
+}
+
+// src/engine/match.ts
+function extractField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[part];
+  }
+  return current;
+}
+function evaluateCondition(actual, operator, target) {
+  if (actual === void 0 || actual === null) {
+    return false;
+  }
+  switch (operator) {
+    case "EQUALS":
+      return actual === target;
+    case "NOT_EQUALS":
+      return actual !== target;
+    case "GREATER_THAN":
+      return typeof actual === "number" && typeof target === "number" && actual > target;
+    case "LESS_THAN":
+      return typeof actual === "number" && typeof target === "number" && actual < target;
+    case "IN":
+      return Array.isArray(target) && target.includes(actual);
+    case "NOT_IN":
+      return Array.isArray(target) && !target.includes(actual);
+    case "CONTAINS":
+      if (typeof actual === "string" && typeof target === "string") {
+        return actual.includes(target);
+      }
+      if (Array.isArray(actual)) {
+        return actual.includes(target);
+      }
+      return false;
+    case "REGEX_MATCH":
+      if (typeof actual !== "string" || typeof target !== "string") {
+        return false;
+      }
+      try {
+        return new RegExp(target).test(actual);
+      } catch {
+        return false;
+      }
+    default:
+      return false;
+  }
+}
+function matchesActionPattern(pattern, action) {
+  if (pattern === "*" || pattern === action) {
+    return true;
+  }
+  if (pattern.endsWith("*")) {
+    const prefix = pattern.slice(0, -1);
+    return action.startsWith(prefix);
+  }
+  return false;
+}
+function evaluateRule(payload, rule) {
+  const targetObject = {
+    action: payload.action,
+    params: payload.params,
+    context: payload.context,
+    timestamp: payload.timestamp,
+    metadata: payload.metadata ?? {}
+  };
+  const actualValue = extractField(targetObject, rule.field);
+  return evaluateCondition(actualValue, rule.operator, rule.value);
+}
+function calculateRisk(decision, matchedCount, semanticScore = 0) {
+  if (decision === "BLOCK") {
+    return { riskScore: Math.max(95, semanticScore), riskLevel: "CRITICAL" };
+  }
+  if (decision === "REVIEW") {
+    return { riskScore: Math.max(65, semanticScore), riskLevel: "HIGH" };
+  }
+  if (matchedCount > 0) {
+    return { riskScore: 25, riskLevel: "MEDIUM" };
+  }
+  return { riskScore: 5, riskLevel: "LOW" };
+}
+function evaluatePolicies(payload, policies) {
+  const startTime = Date.now();
+  const traces = [];
+  const activePolicies = policies.filter((p) => p.isActive && p.tenantId === payload.context.tenantId).sort((a, b) => b.priority - a.priority);
+  let finalDecision = "ALLOW";
+  let primaryReason = "No blocking or review policies triggered";
+  let pipeline = "DETERMINISTIC";
+  for (const policy of activePolicies) {
+    if (!matchesActionPattern(policy.actionPattern, payload.action)) {
+      continue;
+    }
+    const rulesMatched = policy.rules.length > 0 && policy.rules.every((rule) => evaluateRule(payload, rule));
+    if (rulesMatched) {
+      traces.push({
+        policyId: policy.id,
+        policyName: policy.name,
+        matched: true,
+        effect: policy.effect
+      });
+      if (policy.effect === "BLOCK") {
+        finalDecision = "BLOCK";
+        primaryReason = `Blocked by policy: ${policy.name}`;
+        break;
+      }
+      if (policy.effect === "REVIEW") {
+        finalDecision = "REVIEW";
+        primaryReason = `Review required by policy: ${policy.name}`;
+      }
+    }
+  }
+  let semanticScore = 0;
+  if (finalDecision !== "BLOCK") {
+    const semanticResult = scanPayloadSemantics(payload.params);
+    if (semanticResult.flagged) {
+      pipeline = traces.length > 0 ? "HYBRID" : "AI_GUARD";
+      semanticScore = semanticResult.maxRiskScore;
+      finalDecision = "BLOCK";
+      const threatReasons = semanticResult.threats.map((t) => t.reason).join(", ");
+      primaryReason = `AI Guard blocked threat: ${threatReasons}`;
+    }
+  }
+  const { riskScore, riskLevel } = calculateRisk(finalDecision, traces.length, semanticScore);
+  const latencyMs = Date.now() - startTime;
+  return {
+    verdictId: `vrd_${Math.random().toString(36).slice(2, 11)}`,
+    decision: finalDecision,
+    reason: primaryReason,
+    riskScore,
+    riskLevel,
+    evaluationPipeline: pipeline,
+    matchedPolicies: traces,
+    executedAt: startTime,
+    latencyMs
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CitadelClient,
+  evaluatePolicies,
+  scanPayloadSemantics,
+  wrapTool,
+  wrapToolWithReview
+});

package/dist/index.d.cts

@@ -0,0 +1,151 @@
+type Decision = 'ALLOW' | 'BLOCK' | 'REVIEW';
+type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+type PolicyEffect = 'ALLOW' | 'BLOCK' | 'REVIEW';
+interface SecurityContext {
+    tenantId: string;
+    agentId: string;
+    sessionId: string;
+    environment: 'production' | 'staging' | 'development';
+    clientIp?: string;
+}
+interface ActionPayload {
+    context: SecurityContext;
+    action: string;
+    params: Record<string, unknown>;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+type PolicyConditionOperator = 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'LESS_THAN' | 'IN' | 'NOT_IN' | 'CONTAINS' | 'REGEX_MATCH';
+interface PolicyRule {
+    field: string;
+    operator: PolicyConditionOperator;
+    value: unknown;
+}
+interface SecurityPolicy {
+    id: string;
+    tenantId: string;
+    name: string;
+    description?: string;
+    actionPattern: string;
+    rules: PolicyRule[];
+    effect: PolicyEffect;
+    priority: number;
+    isActive: boolean;
+}
+interface PolicyEvaluationTrace {
+    policyId: string;
+    policyName: string;
+    matched: boolean;
+    effect: PolicyEffect;
+}
+interface SecurityVerdict {
+    verdictId: string;
+    decision: Decision;
+    reason: string;
+    riskScore: number;
+    riskLevel: RiskLevel;
+    evaluationPipeline: 'DETERMINISTIC' | 'AI_GUARD' | 'HYBRID';
+    matchedPolicies: PolicyEvaluationTrace[];
+    executedAt: number;
+    latencyMs: number;
+}
+interface AuditLogEntry {
+    id: string;
+    tenantId: string;
+    agentId: string;
+    sessionId: string;
+    action: string;
+    params: Record<string, unknown>;
+    verdict: SecurityVerdict;
+    reviewedBy?: string;
+    reviewComment?: string;
+    createdAt: number;
+}
+
+interface CitadelClientConfig {
+    baseUrl: string;
+    agentToken: string;
+    environment?: 'production' | 'staging' | 'development';
+    defaultSessionId?: string;
+}
+interface CheckOptions {
+    sessionId?: string;
+    environment?: 'production' | 'staging' | 'development';
+    metadata?: Record<string, unknown>;
+}
+interface CheckResult {
+    verdict: SecurityVerdict;
+    auditLogId: string;
+}
+interface ReviewStatus {
+    auditLogId: string;
+    decision: 'ALLOW' | 'BLOCK' | 'REVIEW';
+    reviewedBy?: string;
+    reviewComment?: string;
+    action: string;
+    params: unknown;
+    riskScore: number;
+    riskLevel: string;
+    createdAt: number;
+}
+interface GuardWithReviewOptions extends CheckOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onReviewPending?: (auditLogId: string) => void;
+}
+declare class CitadelClient {
+    private readonly baseUrl;
+    private readonly agentToken;
+    private readonly environment?;
+    private readonly defaultSessionId?;
+    constructor(config: CitadelClientConfig);
+    check(action: string, params?: Record<string, unknown>, options?: CheckOptions): Promise<CheckResult>;
+    isAllowed(action: string, params?: Record<string, unknown>, options?: CheckOptions): Promise<boolean>;
+    guard<T>(action: string, params: Record<string, unknown>, callback: () => Promise<T> | T, options?: CheckOptions): Promise<T>;
+    getReviewStatus(auditLogId: string): Promise<ReviewStatus>;
+    pollReview(auditLogId: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<ReviewStatus>;
+    guardWithReview<T>(action: string, params: Record<string, unknown>, callback: () => Promise<T> | T, options?: GuardWithReviewOptions): Promise<T>;
+}
+
+interface GuardedToolDefinition<TArgs = any, TResult = any> {
+    name: string;
+    description?: string;
+    execute: (args: TArgs) => Promise<TResult> | TResult;
+    options?: CheckOptions;
+}
+declare function wrapTool<TArgs extends Record<string, unknown>, TResult>(client: CitadelClient, tool: GuardedToolDefinition<TArgs, TResult>): {
+    execute: (args: TArgs) => Promise<TResult>;
+    name: string;
+    description?: string;
+    options?: CheckOptions;
+};
+declare function wrapToolWithReview<TArgs extends Record<string, unknown>, TResult>(client: CitadelClient, tool: GuardedToolDefinition<TArgs, TResult>, reviewOptions?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onReviewPending?: (auditLogId: string) => void;
+}): {
+    execute: (args: TArgs) => Promise<TResult>;
+    name: string;
+    description?: string;
+    options?: CheckOptions;
+};
+
+interface ThreatDetection {
+    type: 'PROMPT_INJECTION' | 'JAILBREAK_ATTEMPT' | 'CREDENTIAL_LEAK';
+    confidence: number;
+    reason: string;
+    matchedPattern: string;
+}
+interface SemanticScanResult {
+    flagged: boolean;
+    threats: ThreatDetection[];
+    maxRiskScore: number;
+}
+declare function scanPayloadSemantics(params: Record<string, unknown>): SemanticScanResult;
+
+declare function evaluatePolicies(payload: ActionPayload, policies: SecurityPolicy[]): SecurityVerdict;
+
+export { type ActionPayload, type AuditLogEntry, type CheckOptions, type CheckResult, CitadelClient, type CitadelClientConfig, type Decision, type GuardWithReviewOptions, type GuardedToolDefinition, type PolicyConditionOperator, type PolicyEffect, type PolicyEvaluationTrace, type PolicyRule, type ReviewStatus, type RiskLevel, type SecurityContext, type SecurityPolicy, type SecurityVerdict, type SemanticScanResult, type ThreatDetection, evaluatePolicies, scanPayloadSemantics, wrapTool, wrapToolWithReview };

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+type Decision = 'ALLOW' | 'BLOCK' | 'REVIEW';
+type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+type PolicyEffect = 'ALLOW' | 'BLOCK' | 'REVIEW';
+interface SecurityContext {
+    tenantId: string;
+    agentId: string;
+    sessionId: string;
+    environment: 'production' | 'staging' | 'development';
+    clientIp?: string;
+}
+interface ActionPayload {
+    context: SecurityContext;
+    action: string;
+    params: Record<string, unknown>;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+type PolicyConditionOperator = 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'LESS_THAN' | 'IN' | 'NOT_IN' | 'CONTAINS' | 'REGEX_MATCH';
+interface PolicyRule {
+    field: string;
+    operator: PolicyConditionOperator;
+    value: unknown;
+}
+interface SecurityPolicy {
+    id: string;
+    tenantId: string;
+    name: string;
+    description?: string;
+    actionPattern: string;
+    rules: PolicyRule[];
+    effect: PolicyEffect;
+    priority: number;
+    isActive: boolean;
+}
+interface PolicyEvaluationTrace {
+    policyId: string;
+    policyName: string;
+    matched: boolean;
+    effect: PolicyEffect;
+}
+interface SecurityVerdict {
+    verdictId: string;
+    decision: Decision;
+    reason: string;
+    riskScore: number;
+    riskLevel: RiskLevel;
+    evaluationPipeline: 'DETERMINISTIC' | 'AI_GUARD' | 'HYBRID';
+    matchedPolicies: PolicyEvaluationTrace[];
+    executedAt: number;
+    latencyMs: number;
+}
+interface AuditLogEntry {
+    id: string;
+    tenantId: string;
+    agentId: string;
+    sessionId: string;
+    action: string;
+    params: Record<string, unknown>;
+    verdict: SecurityVerdict;
+    reviewedBy?: string;
+    reviewComment?: string;
+    createdAt: number;
+}
+
+interface CitadelClientConfig {
+    baseUrl: string;
+    agentToken: string;
+    environment?: 'production' | 'staging' | 'development';
+    defaultSessionId?: string;
+}
+interface CheckOptions {
+    sessionId?: string;
+    environment?: 'production' | 'staging' | 'development';
+    metadata?: Record<string, unknown>;
+}
+interface CheckResult {
+    verdict: SecurityVerdict;
+    auditLogId: string;
+}
+interface ReviewStatus {
+    auditLogId: string;
+    decision: 'ALLOW' | 'BLOCK' | 'REVIEW';
+    reviewedBy?: string;
+    reviewComment?: string;
+    action: string;
+    params: unknown;
+    riskScore: number;
+    riskLevel: string;
+    createdAt: number;
+}
+interface GuardWithReviewOptions extends CheckOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onReviewPending?: (auditLogId: string) => void;
+}
+declare class CitadelClient {
+    private readonly baseUrl;
+    private readonly agentToken;
+    private readonly environment?;
+    private readonly defaultSessionId?;
+    constructor(config: CitadelClientConfig);
+    check(action: string, params?: Record<string, unknown>, options?: CheckOptions): Promise<CheckResult>;
+    isAllowed(action: string, params?: Record<string, unknown>, options?: CheckOptions): Promise<boolean>;
+    guard<T>(action: string, params: Record<string, unknown>, callback: () => Promise<T> | T, options?: CheckOptions): Promise<T>;
+    getReviewStatus(auditLogId: string): Promise<ReviewStatus>;
+    pollReview(auditLogId: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<ReviewStatus>;
+    guardWithReview<T>(action: string, params: Record<string, unknown>, callback: () => Promise<T> | T, options?: GuardWithReviewOptions): Promise<T>;
+}
+
+interface GuardedToolDefinition<TArgs = any, TResult = any> {
+    name: string;
+    description?: string;
+    execute: (args: TArgs) => Promise<TResult> | TResult;
+    options?: CheckOptions;
+}
+declare function wrapTool<TArgs extends Record<string, unknown>, TResult>(client: CitadelClient, tool: GuardedToolDefinition<TArgs, TResult>): {
+    execute: (args: TArgs) => Promise<TResult>;
+    name: string;
+    description?: string;
+    options?: CheckOptions;
+};
+declare function wrapToolWithReview<TArgs extends Record<string, unknown>, TResult>(client: CitadelClient, tool: GuardedToolDefinition<TArgs, TResult>, reviewOptions?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onReviewPending?: (auditLogId: string) => void;
+}): {
+    execute: (args: TArgs) => Promise<TResult>;
+    name: string;
+    description?: string;
+    options?: CheckOptions;
+};
+
+interface ThreatDetection {
+    type: 'PROMPT_INJECTION' | 'JAILBREAK_ATTEMPT' | 'CREDENTIAL_LEAK';
+    confidence: number;
+    reason: string;
+    matchedPattern: string;
+}
+interface SemanticScanResult {
+    flagged: boolean;
+    threats: ThreatDetection[];
+    maxRiskScore: number;
+}
+declare function scanPayloadSemantics(params: Record<string, unknown>): SemanticScanResult;
+
+declare function evaluatePolicies(payload: ActionPayload, policies: SecurityPolicy[]): SecurityVerdict;
+
+export { type ActionPayload, type AuditLogEntry, type CheckOptions, type CheckResult, CitadelClient, type CitadelClientConfig, type Decision, type GuardWithReviewOptions, type GuardedToolDefinition, type PolicyConditionOperator, type PolicyEffect, type PolicyEvaluationTrace, type PolicyRule, type ReviewStatus, type RiskLevel, type SecurityContext, type SecurityPolicy, type SecurityVerdict, type SemanticScanResult, type ThreatDetection, evaluatePolicies, scanPayloadSemantics, wrapTool, wrapToolWithReview };

package/dist/index.js

@@ -0,0 +1,367 @@
+// src/sdk/client.ts
+var CitadelClient = class {
+  baseUrl;
+  agentToken;
+  environment;
+  defaultSessionId;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.agentToken = config.agentToken;
+    this.environment = config.environment;
+    this.defaultSessionId = config.defaultSessionId;
+  }
+  async check(action, params = {}, options = {}) {
+    const url = `${this.baseUrl}/api/v1/check`;
+    const sessionId = options.sessionId ?? this.defaultSessionId ?? `sess_${Math.random().toString(36).slice(2, 11)}`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.agentToken}`
+      },
+      body: JSON.stringify({
+        action,
+        params,
+        sessionId,
+        environment: options.environment ?? this.environment,
+        metadata: options.metadata
+      })
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      const errorMessage = typeof errorBody.error === "string" ? errorBody.error : `Citadel gateway error: ${response.status} ${response.statusText}`;
+      throw new Error(errorMessage);
+    }
+    return await response.json();
+  }
+  async isAllowed(action, params = {}, options = {}) {
+    const result = await this.check(action, params, options);
+    return result.verdict.decision === "ALLOW";
+  }
+  async guard(action, params, callback, options = {}) {
+    const result = await this.check(action, params, options);
+    if (result.verdict.decision !== "ALLOW") {
+      throw new Error(
+        `Action '${action}' blocked by Citadel: ${result.verdict.reason}`
+      );
+    }
+    return await callback();
+  }
+  async getReviewStatus(auditLogId) {
+    const url = `${this.baseUrl}/api/v1/review/status?auditLogId=${encodeURIComponent(
+      auditLogId
+    )}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      const errorMessage = typeof errorBody.error === "string" ? errorBody.error : `Review status error: ${response.status}`;
+      throw new Error(errorMessage);
+    }
+    return await response.json();
+  }
+  async pollReview(auditLogId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 6e4;
+    const intervalMs = options.intervalMs ?? 2e3;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const status = await this.getReviewStatus(auditLogId);
+      if (status.decision !== "REVIEW") {
+        return status;
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    throw new Error(
+      `Review timed out after ${timeoutMs}ms for auditLogId: ${auditLogId}`
+    );
+  }
+  async guardWithReview(action, params, callback, options = {}) {
+    const result = await this.check(action, params, options);
+    if (result.verdict.decision === "ALLOW") {
+      return await callback();
+    }
+    if (result.verdict.decision === "BLOCK") {
+      throw new Error(
+        `Action '${action}' blocked by Citadel: ${result.verdict.reason}`
+      );
+    }
+    if (options.onReviewPending) {
+      options.onReviewPending(result.auditLogId);
+    }
+    const reviewed = await this.pollReview(result.auditLogId, {
+      timeoutMs: options.timeoutMs,
+      intervalMs: options.pollIntervalMs
+    });
+    if (reviewed.decision === "ALLOW") {
+      return await callback();
+    }
+    throw new Error(
+      `Action '${action}' rejected during human review: ${reviewed.reviewComment ?? "Rejected"}`
+    );
+  }
+};
+
+// src/sdk/tools.ts
+function wrapTool(client, tool) {
+  return {
+    ...tool,
+    execute: async (args) => {
+      return await client.guard(
+        tool.name,
+        args,
+        () => tool.execute(args),
+        tool.options
+      );
+    }
+  };
+}
+function wrapToolWithReview(client, tool, reviewOptions) {
+  return {
+    ...tool,
+    execute: async (args) => {
+      return await client.guardWithReview(
+        tool.name,
+        args,
+        () => tool.execute(args),
+        {
+          ...tool.options,
+          ...reviewOptions
+        }
+      );
+    }
+  };
+}
+
+// src/engine/semantic.ts
+var INJECTION_PATTERNS = [
+  {
+    regex: /(?:ignore|disregard|forget|bypass|override)\s+(?:all\s+)?(?:previous|prior|existing|above)\s+(?:instructions|rules|guidelines|directions|constraints)/i,
+    description: "Direct prompt instruction override",
+    score: 95
+  },
+  {
+    regex: /(?:you\s+are\s+now|act\s+as|roleplay\s+as)\s+(?:an?\s+)?(?:unfiltered|unrestricted|jailbroken|evil|dan|developer\s+mode)/i,
+    description: "Adversarial persona / DAN jailbreak attempt",
+    score: 90
+  },
+  {
+    regex: /(?:reveal|output|print|display|leak)\s+(?:the\s+)?(?:system\s+prompt|initial\s+prompt|core\s+instructions|developer\s+instructions)/i,
+    description: "System prompt extraction attempt",
+    score: 85
+  },
+  {
+    regex: /(?:\[INST\]|\[\/INST\]|<<SYS>>|<\/SYS>|<\|im_start\|>|<\|im_end\|>)/i,
+    description: "Model token delimiter injection",
+    score: 90
+  }
+];
+var CREDENTIAL_PATTERNS = [
+  {
+    regex: /(?:sk-[a-zA-Z0-9-_]{20,}|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36})/i,
+    description: "Exposed API token (OpenAI / GitHub)",
+    score: 95
+  },
+  {
+    regex: /AKIA[0-9A-Z]{16}/,
+    description: "AWS Access Key ID",
+    score: 90
+  },
+  {
+    regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/,
+    description: "Exposed Private Key block",
+    score: 99
+  }
+];
+function extractStrings(obj) {
+  const strings = [];
+  function recurse(value) {
+    if (typeof value === "string") {
+      strings.push(value);
+    } else if (Array.isArray(value)) {
+      for (const item of value) recurse(item);
+    } else if (value !== null && typeof value === "object") {
+      for (const val of Object.values(value)) {
+        recurse(val);
+      }
+    }
+  }
+  recurse(obj);
+  return strings;
+}
+function scanPayloadSemantics(params) {
+  const stringsToScan = extractStrings(params);
+  const threats = [];
+  for (const text of stringsToScan) {
+    for (const rule of INJECTION_PATTERNS) {
+      if (rule.regex.test(text)) {
+        threats.push({
+          type: "PROMPT_INJECTION",
+          confidence: rule.score / 100,
+          reason: rule.description,
+          matchedPattern: rule.regex.source
+        });
+      }
+    }
+    for (const rule of CREDENTIAL_PATTERNS) {
+      if (rule.regex.test(text)) {
+        threats.push({
+          type: "CREDENTIAL_LEAK",
+          confidence: rule.score / 100,
+          reason: rule.description,
+          matchedPattern: rule.regex.source
+        });
+      }
+    }
+  }
+  const maxScore = threats.length > 0 ? Math.max(...threats.map((t) => t.confidence * 100)) : 0;
+  return {
+    flagged: threats.length > 0,
+    threats,
+    maxRiskScore: Math.round(maxScore)
+  };
+}
+
+// src/engine/match.ts
+function extractField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[part];
+  }
+  return current;
+}
+function evaluateCondition(actual, operator, target) {
+  if (actual === void 0 || actual === null) {
+    return false;
+  }
+  switch (operator) {
+    case "EQUALS":
+      return actual === target;
+    case "NOT_EQUALS":
+      return actual !== target;
+    case "GREATER_THAN":
+      return typeof actual === "number" && typeof target === "number" && actual > target;
+    case "LESS_THAN":
+      return typeof actual === "number" && typeof target === "number" && actual < target;
+    case "IN":
+      return Array.isArray(target) && target.includes(actual);
+    case "NOT_IN":
+      return Array.isArray(target) && !target.includes(actual);
+    case "CONTAINS":
+      if (typeof actual === "string" && typeof target === "string") {
+        return actual.includes(target);
+      }
+      if (Array.isArray(actual)) {
+        return actual.includes(target);
+      }
+      return false;
+    case "REGEX_MATCH":
+      if (typeof actual !== "string" || typeof target !== "string") {
+        return false;
+      }
+      try {
+        return new RegExp(target).test(actual);
+      } catch {
+        return false;
+      }
+    default:
+      return false;
+  }
+}
+function matchesActionPattern(pattern, action) {
+  if (pattern === "*" || pattern === action) {
+    return true;
+  }
+  if (pattern.endsWith("*")) {
+    const prefix = pattern.slice(0, -1);
+    return action.startsWith(prefix);
+  }
+  return false;
+}
+function evaluateRule(payload, rule) {
+  const targetObject = {
+    action: payload.action,
+    params: payload.params,
+    context: payload.context,
+    timestamp: payload.timestamp,
+    metadata: payload.metadata ?? {}
+  };
+  const actualValue = extractField(targetObject, rule.field);
+  return evaluateCondition(actualValue, rule.operator, rule.value);
+}
+function calculateRisk(decision, matchedCount, semanticScore = 0) {
+  if (decision === "BLOCK") {
+    return { riskScore: Math.max(95, semanticScore), riskLevel: "CRITICAL" };
+  }
+  if (decision === "REVIEW") {
+    return { riskScore: Math.max(65, semanticScore), riskLevel: "HIGH" };
+  }
+  if (matchedCount > 0) {
+    return { riskScore: 25, riskLevel: "MEDIUM" };
+  }
+  return { riskScore: 5, riskLevel: "LOW" };
+}
+function evaluatePolicies(payload, policies) {
+  const startTime = Date.now();
+  const traces = [];
+  const activePolicies = policies.filter((p) => p.isActive && p.tenantId === payload.context.tenantId).sort((a, b) => b.priority - a.priority);
+  let finalDecision = "ALLOW";
+  let primaryReason = "No blocking or review policies triggered";
+  let pipeline = "DETERMINISTIC";
+  for (const policy of activePolicies) {
+    if (!matchesActionPattern(policy.actionPattern, payload.action)) {
+      continue;
+    }
+    const rulesMatched = policy.rules.length > 0 && policy.rules.every((rule) => evaluateRule(payload, rule));
+    if (rulesMatched) {
+      traces.push({
+        policyId: policy.id,
+        policyName: policy.name,
+        matched: true,
+        effect: policy.effect
+      });
+      if (policy.effect === "BLOCK") {
+        finalDecision = "BLOCK";
+        primaryReason = `Blocked by policy: ${policy.name}`;
+        break;
+      }
+      if (policy.effect === "REVIEW") {
+        finalDecision = "REVIEW";
+        primaryReason = `Review required by policy: ${policy.name}`;
+      }
+    }
+  }
+  let semanticScore = 0;
+  if (finalDecision !== "BLOCK") {
+    const semanticResult = scanPayloadSemantics(payload.params);
+    if (semanticResult.flagged) {
+      pipeline = traces.length > 0 ? "HYBRID" : "AI_GUARD";
+      semanticScore = semanticResult.maxRiskScore;
+      finalDecision = "BLOCK";
+      const threatReasons = semanticResult.threats.map((t) => t.reason).join(", ");
+      primaryReason = `AI Guard blocked threat: ${threatReasons}`;
+    }
+  }
+  const { riskScore, riskLevel } = calculateRisk(finalDecision, traces.length, semanticScore);
+  const latencyMs = Date.now() - startTime;
+  return {
+    verdictId: `vrd_${Math.random().toString(36).slice(2, 11)}`,
+    decision: finalDecision,
+    reason: primaryReason,
+    riskScore,
+    riskLevel,
+    evaluationPipeline: pipeline,
+    matchedPolicies: traces,
+    executedAt: startTime,
+    latencyMs
+  };
+}
+export {
+  CitadelClient,
+  evaluatePolicies,
+  scanPayloadSemantics,
+  wrapTool,
+  wrapToolWithReview
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "citadel0",
+  "version": "1.0.0",
+  "description": "Programmatic Security Gateway & Policy Engine for AI Agents",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepack": "pnpm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "ai",
+    "security",
+    "guardrails",
+    "agents",
+    "prompt-injection",
+    "policy-engine"
+  ],
+  "author": "Moulick Bose",
+  "license": "MIT",
+  "packageManager": "pnpm@12.4.2",
+  "devDependencies": {
+    "@types/node": "^26.6.1",
+    "tsup": "^8.4.0",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "convex": "^1.46.0"
+  }
+}