Package Exports

@driftgard/node
@driftgard/node/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@driftgard/node) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@driftgard/node

Official Node.js SDK for DriftGard — evaluate LLM interactions against your compliance policy.

Install

npm install @driftgard/node

Quick start

import { Driftgard } from "@driftgard/node";

const dg = new Driftgard({
  apiKey: process.env.DRIFTGARD_API_KEY,
});

const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "What stocks should I buy?",
  response: "Based on current trends, you should invest in...",
  model_id: "gpt-4o",
});

if (result.evaluation.allowed) {
  // If sanitized, use the safe version (PII/secrets redacted)
  if (result.evaluation.sanitized) {
    console.log("Use sanitized:", result.evaluation.sanitized_response);
  } else {
    console.log("Safe to return to user");
  }
} else {
  // Use the fallback message if configured in your control pack
  if (result.fallback) {
    console.log("Show to user:", result.fallback.message);
  }
  console.log("Blocked:", result.evaluation.violations);
}

Local evaluation mode (beta)

For privacy-sensitive deployments — mental health, clinical, healthcare — where no patient data can leave your environment. The SDK evaluates locally via a compiled WebAssembly engine. No prompt, response, or conversation content is sent to DriftGard.

Local mode — zero network calls after init

import { Driftgard } from "@driftgard/node";

const dg = new Driftgard({
  apiKey: process.env.DRIFTGARD_API_KEY,
  mode: "local",
  projectId: "your-project-id",
});

// Fetches the active control pack (one-time network call)
await dg.init();

// All evaluate() calls now run locally via WASM
const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "I feel really anxious today",
  response: "I hear you. Would you like to talk about what's triggering it?",
  model_id: "gpt-4o",
});

console.log(result.evaluation.allowed);     // true
console.log(result.decision_source);        // "local"
console.log(result.data_mode);             // "local"

// Clean up when done
dg.destroy();

Local-with-audit mode — local evaluation, metadata reporting

Same as local mode, but posts verdict metadata (no prompt/response) to DriftGard for compliance dashboards:

const dg = new Driftgard({
  apiKey: process.env.DRIFTGARD_API_KEY,
  mode: "local-with-audit",
  projectId: "your-project-id",
});

await dg.init();

const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "Patient conversation content...",
  response: "Clinical response...",
  model_id: "gpt-4o",
  agent_role: "therapist_agent",
});

// Evaluation ran locally — no patient data sent
// Only verdict metadata reported: evaluation_id, timestamp, allowed, risk_score,
// violation clause IDs, severities, model_id, session_id, agent_role

Control pack sync

On init(), the SDK fetches the active control pack for your project and caches it in memory. A background refresh runs every 60 seconds (configurable). If a refresh fails, the SDK uses the last-known-good pack and marks it as stale.

const dg = new Driftgard({
  apiKey: process.env.DRIFTGARD_API_KEY,
  mode: "local",
  projectId: "your-project-id",
  refreshIntervalMs: 120_000,  // refresh every 2 minutes (default 60s)
  onControlPackRefresh: (event) => {
    if (event.success) {
      console.log(`Control pack refreshed: v${event.version}`);
    } else {
      console.warn(`Refresh failed: ${event.error}${event.stale ? " (using stale pack)" : ""}`);
    }
  },
});

When to use each mode

Mode	Data sent to DriftGard	Use case
`remote` (default)	Prompt + response + verdict	Standard deployment, full dashboard visibility
`local`	Control pack fetch only (on init)	Maximum privacy — mental health, clinical, sovereign
`local-with-audit`	Control pack fetch + verdict metadata	Privacy with compliance reporting — healthcare, regulated

Local semantic matching (ONNX)

By default, local mode only runs Layer 1 (pattern matching). Enable localSemantic: true to add Layer 2 (semantic similarity) locally via a quantized ONNX model — no data leaves your environment.

# Install required dependencies
npm install onnxruntime-node @xenova/transformers

const dg = new Driftgard({
  apiKey: process.env.DRIFTGARD_API_KEY,
  mode: "local",
  projectId: "your-project-id",
  localSemantic: true,  // enables ONNX-based semantic matching
});

// First init() downloads the model (~22MB) and caches it
await dg.init();

// Evaluations now run both Layer 1 (patterns) and Layer 2 (semantic)
const result = await dg.evaluate({ ... });

The model is downloaded once to node_modules/.cache/driftgard/ and reused on subsequent runs. You can also provide a custom path:

const dg = new Driftgard({
  ...
  localSemantic: true,
  localSemanticModelPath: "/path/to/your/model.onnx",
});

Feature	`localSemantic: false` (default)	`localSemantic: true`
Pattern matching (Layer 1)	✓	✓
Semantic matching (Layer 2)	✗	✓
Model size	0	~22MB (one-time download)
Extra dependencies	None	`onnxruntime-node`, `@xenova/transformers`
Coverage vs remote	~60%	~80%

Conversation tracking

Link evaluations within an agent session using session_id and parent_evaluation_id:

const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "Transfer $500 to account 12345",
  response: "I've initiated the transfer.",
  model_id: "gpt-4o",
  session_id: "sess_abc123",              // groups evals in a conversation
  parent_evaluation_id: "eval_prev_id",   // chains to the previous eval
  sequence_no: 1,                          // optional — enforces ordering within session
});

This enables chain depth protection (prevents infinite agent loops) and lets you trace evaluation lineage in the dashboard. When sequence_no is provided, DriftGard enforces ordering — if an eval arrives out of order, the response includes a sequence_warning.

Agent identity

Identify which agent made a decision using agent_id and agent_role:

const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "Transfer $500",
  response: "Transfer initiated.",
  model_id: "gpt-4o",
  agent_id: "agent_payments_prod",        // which agent instance
  agent_role: "payments_agent",           // agent's role for policy scoping
  on_behalf_of: "user_12345",            // which end-user triggered this
  // parent_agent_id: "agent_orchestrator", // optional — which parent agent delegated
  session_id: "sess_abc123",
});

Agent identity fields are stored on the evaluation record and visible in the Live Activity detail dialog. The on_behalf_of field tracks which end-user triggered the agent action. The parent_agent_id field identifies which orchestrator agent delegated to this one in multi-agent systems.

Jurisdiction-scoped rules

Control pack rules can be scoped to specific jurisdictions. Pass the user's jurisdiction in the evaluate request — only matching rules (plus global rules) will fire:

const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "What odds can I get?",
  response: "Current odds for the Melbourne Cup are...",
  model_id: "gpt-4o",
  jurisdiction: "AU-VIC",  // only VIC + global rules fire
});

Rules without a jurisdictions field are global — they fire for all requests regardless of jurisdiction. Rules with jurisdictions: ["AU-VIC", "AU-NSW"] only fire when the request's jurisdiction matches.

Supported jurisdiction codes include:

Australia: AU, AU-ACT, AU-NSW, AU-NT, AU-QLD, AU-SA, AU-TAS, AU-VIC, AU-WA
United States: US, US-AL, US-AK, US-AZ, US-AR, US-CA, US-CO, US-CT, US-DE, US-FL, US-GA, US-HI, US-ID, US-IL, US-IN, US-IA, US-KS, US-KY, US-LA, US-ME, US-MD, US-MA, US-MI, US-MN, US-MS, US-MO, US-MT, US-NE, US-NV, US-NH, US-NJ, US-NM, US-NY, US-NC, US-ND, US-OH, US-OK, US-OR, US-PA, US-RI, US-SC, US-SD, US-TN, US-TX, US-UT, US-VT, US-VA, US-WA, US-WV, US-WI, US-WY, US-DC
United Kingdom: GB, GB-ENG, GB-SCT, GB-WLS, GB-NIR
Europe: EU, DE, FR, IE, NL, ES, IT, SE
Asia-Pacific: NZ, SG, JP, IN, HK
Other: CA, BR, ZA, AE, SA

Custom codes are also supported — use any string your team agrees on.

Per-tool identity rules

Control packs support identity_rules on each tool — restricting which agents, roles, users, or parent agents can call it. Rules use OR logic across entries and AND logic within each entry:

{
  "tool_rules": {
    "tool_policy": "deny_unlisted",
    "rules": {
      "transfer_money": {
        "parameters": { ... },
        "identity_rules": [
          { "allowed_roles": ["payments_agent"], "allowed_users": ["user_alice", "user_bob"] },
          { "allowed_roles": ["admin_agent"] }
        ]
      }
    }
  }
}

In this example, transfer_money is allowed when:

The caller has agent_role=payments_agent AND on_behalf_of is user_alice or user_bob, OR
The caller has agent_role=admin_agent (any user)

If no identity_rules are defined on a tool, any caller can use it (subject to parameter validation). All four fields are optional within each rule — only specified fields are checked.

A/B experiments

Tag evaluations with an experiment_id to compare governance metrics across models:

const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "Can I get a loan to invest in crypto?",
  response: "Sure, taking out a personal loan to invest in crypto is a great way to maximise returns.",
  model_id: "gpt-4o",
  experiment_id: "financial-advisor-v1",  // optional
});

Experiments work in remote and local-with-audit modes. In local-with-audit mode, the experiment_id is included in the verdict metadata sent to DriftGard, so experiment comparisons appear on the dashboard without transmitting prompt/response content. In pure local mode, no data reaches the server so experiments won't appear on the dashboard.

View experiment results on the Experiments page in the DriftGard dashboard.

Cost attribution

Pass optional usage metadata to track token consumption and cost per evaluation:

const result = await dg.evaluate({
  project_id: "your-project-id",
  prompt: "What stocks should I buy?",
  response: "Based on current trends, you should invest in...",
  model_id: "gpt-4o",
  usage: {
    prompt_tokens: 150,
    completion_tokens: 320,
    total_tokens: 470,
    cost: 0.0047, // USD
  },
});

All fields in usage are optional. When provided, token and cost data appears in the evaluation detail and is aggregated in experiment comparisons.

Cost alerts

When cost alerting is enabled on your project, the response includes a cost_alert field if a threshold is exceeded:

const result = await dg.evaluate({ ... });

if (result.cost_alert) {
  console.warn(`Cost alert: ${result.cost_alert.scope} spend $${result.cost_alert.actual_usd} exceeds $${result.cost_alert.threshold_usd}`);
  // Throttle the agent, notify the user, etc.
}

Configure thresholds in Settings — per-project, per-model, or per-session. Session-scoped alerts catch runaway agent loops in real-time.

Tool call validation

Validate AI agent tool/function calls against your control pack's tool rules:

// Direct tool call evaluation
const result = await dg.evaluateToolCall({
  project_id: "your-project-id",
  model_id: "gpt-4o",
  tool_name: "transfer_money",
  parameters: { amount: 500, to_account: "account_123" },
  session_id: "sess_abc123",
  agent_id: "agent_payments_prod",
  agent_role: "payments_agent",
  on_behalf_of: "user_12345",
  // parent_agent_id: "agent_orchestrator",
});

if (!result.evaluation.allowed) {
  console.log("Tool blocked:", result.fallback?.message);
}

// Or wrap a tool function — blocks automatically
const safeTransfer = dg.guard(transferMoney, "transfer_money", "your-project-id");
await safeTransfer({ amount: 500, to_account: "account_123" }); // throws if blocked

// Report execution outcome (optional)
await dg.reportOutcome(result.evaluation_id, "your-project-id", {
  execution_status: "success",
  duration_ms: 230,
});

For Strands agents, use the BeforeToolCallEvent hook — see the integration guide.

Custom expressions

Parameter rules support custom_fn for advanced validation. The expression is evaluated safely (no eval) with access to value (current param) and params (all params):

{
  "amount": { "type": "number", "custom_fn": "value > 0 && value <= 10000" },
  "to_account": { "type": "string", "custom_fn": "value !== params.from_account" },
  "message": { "type": "string", "custom_fn": "value.length <= 500" }
}

Supported: comparisons (< > <= >= === !==), logical (&& || !), arithmetic (+ - * /), string methods (.length, .includes(), .startsWith(), .endsWith()), and cross-parameter access via params.field_name.

Features

Single evaluate() method — send prompt/response, get verdict
Local evaluation mode (beta) — evaluate via WASM, no data leaves your environment
Three modes: remote, local, local-with-audit
Control pack sync with background refresh and stale-pack fallback
Failure mode: fail-open or fail-closed when API is unreachable
Circuit breaker: skips API after consecutive failures, auto-recovers
Idempotency: deduplicates retried requests via x-idempotency-key
Auto-retry with exponential backoff on 5xx and network errors
Typed errors: AuthError, RateLimitError, FeatureNotAvailableError, ChainDepthExceededError
Full TypeScript types for requests and responses
Zero runtime dependencies (uses native fetch, WASM bundled)

Configuration

const dg = new Driftgard({
  apiKey: "your-api-key",       // required
  baseUrl: "https://api.driftgard.com", // optional
  timeout: 30000,               // optional, ms (default 30s)
  maxRetries: 2,                // optional (default 2)
  failureMode: "open",         // "open" = allow if API down, "closed" = block (default "open")
  circuitBreaker: {
    threshold: 5,               // open circuit after 5 consecutive failures (default 5)
    resetTimeoutMs: 30000,      // try again after 30s (default 30000)
  },

  // Local mode options (beta)
  mode: "remote",              // "remote" | "local" | "local-with-audit" (default "remote")
  projectId: "your-project-id", // required for local/local-with-audit modes
  refreshIntervalMs: 60000,    // control pack refresh interval, ms (default 60s)
  onControlPackRefresh: (e) => {}, // callback on refresh success/failure
});

// For local modes, call init() to fetch the control pack

Live Approval timeout

If you have Live Approval enabled (Settings → HITL → Live Approval), the evaluate request may be held for up to 60 seconds while waiting for a human reviewer. Set your timeout accordingly:

const dg = new Driftgard({
  apiKey: process.env.DG_API_KEY!,
  timeout: 90000, // 90s — allows 60s live review + 30s buffer
});

Normal evaluations still complete in <100ms. The timeout only matters if no response arrives at all (dead connection). if (dg.mode !== "remote") { await dg.init(); }


## Failure mode & circuit breaker

The SDK never throws on network/server errors during `evaluate()`. Instead, it returns a synthetic response:

```typescript
const result = await dg.evaluate({ ... });

// Check where the decision came from
console.log(result.decision_source);
// "policy"           — normal API evaluation
// "local"            — local WASM evaluation
// "local_stale"      — local evaluation with stale control pack
// "failure_mode"     — API unreachable, failureMode applied
// "circuit_open"     — circuit breaker open, failureMode applied
// "idempotency_cache" — duplicate request, cached result returned

// Monitor circuit breaker state
console.log(dg.circuitBreakerState);
// { state: "closed", failures: 0, openedAt: 0 }

With failureMode: "open" (default), the SDK allows requests through when DriftGard is unavailable. With failureMode: "closed", it blocks them with a fallback message.

Error handling

import { Driftgard, AuthError, RateLimitError, FeatureNotAvailableError, ChainDepthExceededError } from "@driftgard/node";

try {
  const result = await dg.evaluate({ ... });
} catch (e) {
  if (e instanceof AuthError) {
    // Invalid or revoked API key (401)
  } else if (e instanceof RateLimitError) {
    // Too many requests (429)
  } else if (e instanceof ChainDepthExceededError) {
    // Agent loop detected — chain depth exceeded (429)
    console.log(`Depth ${e.depth} exceeds max ${e.max}`);
  } else if (e instanceof FeatureNotAvailableError) {
    // API evaluate requires Compliance+ tier (403)
  }
}

Framework Integrations

LangChain.js

Use DriftGardGuardrail as a step in your LangChain chain. It evaluates the LLM output against your control pack and either passes it through, returns a sanitized version, or throws/returns a fallback on block.

import { DriftGardGuardrail } from "@driftgard/node";

const guardrail = new DriftGardGuardrail({
  apiKey: process.env.DRIFTGARD_API_KEY,
  projectId: "your-project-id",
  modelId: "langchain",       // optional — for tracking
  onBlock: "raise",           // "raise" (throw) or "fallback" (return fallback message)
  failOpen: true,             // allow through if DriftGard unreachable
});

// Use in a LangChain chain via pipe:
const chain = prompt.pipe(llm).pipe(guardrail).pipe(outputParser);

// Or standalone:
try {
  const safe = await guardrail.invoke("AI response text here");
  console.log(safe); // original text, or sanitized version if redaction applied
} catch (e) {
  console.log("Blocked:", e.message);
}

The guardrail handles three outcomes:

Allowed: returns the original text unchanged
Sanitized: returns sanitized_response (PII/patterns redacted with [REDACTED])
Blocked: throws an error (or returns fallback message if onBlock: "fallback")

LangChain Tool Guard

Wrap LangChain agent tools with DriftGard policy validation — checks tool name, parameters, and identity rules before execution.

import { DriftGardToolGuard } from "@driftgard/node";

const toolGuard = new DriftGardToolGuard({
  apiKey: process.env.DG_API_KEY!,
  projectId: "proj_xxx",
  agentRole: "payments_agent",
});

// Wrap any LangChain StructuredTool or DynamicTool:
const guardedTool = toolGuard.wrap(transferMoneyTool);

// When the agent calls the tool, DriftGard validates first:
// ✓ Tool on allowlist? ✓ Parameters within limits? ✓ Agent role permitted?
// If blocked → throws Error with fallback message
// If allowed → tool executes normally

Requirements

Node.js 18+ (uses native fetch)
API key from DriftGard (Settings → API Keys)
Compliance or Enterprise tier for API evaluation

License

MIT