API Reference

Complete reference for governance-sdk v0.11.2. All functions are TypeScript-native. Zero runtime dependencies. Start with the quickstart if you haven't set up governance yet.

Core

import ... from 'governance-sdk'

Primary API. Create governance instances, register agents, enforce policies.

createGovernancev0.1.0+core

createGovernance(config: GovernanceConfig): Governance

Creates a new governance instance with the provided configuration. The instance is the central object for all policy enforcement, agent registration, and audit logging.

Parameters

name	type	description
`config.rules`	`PolicyRule[]`	Array of policy rules to evaluate on every enforce() call.
`config.storage`	`StorageAdapter`	Storage backend. Defaults to in-memory. Use postgresStorage() for persistence.
`config.signingKey`	`string`	HMAC signing key for tamper-evident audit chains.

Returns

Governance— Governance instance with register(), enforce(), kill(), and on() methods.

Example

import { createGovernance } from "governance-sdk";

const gov = createGovernance({
  rules: [
    { id: "block-shell", condition: { type: "tool_blocked", params: { tools: ["shell_exec"] } }, outcome: "block" },
    { id: "level-gate", condition: { type: "agent_level", params: { minLevel: 3 } }, outcome: "allow" },
  ],
  signingKey: process.env.AUDIT_SECRET,
});

gov.registerv0.1.0+core

gov.register(agent: AgentRegistration): Promise<RegisteredAgent>

Registers an agent with the governance system. Computes a 7-dimension governance score (0–100) and assigns a governance level (L0–L4). Call once per agent at startup.

Parameters

name	type	description
`agent.name`required	`string`	Unique identifier for the agent.
`agent.framework`	`'mastra' \| 'vercel-ai' \| 'langchain' \| 'openai'`	Framework the agent uses.
`agent.tools`	`string[]`	List of tool names the agent can access.
`agent.hasAuth`	`boolean`	Whether the agent has authentication enabled.
`agent.hasGuardrails`	`boolean`	Whether the agent has guardrails configured.

Returns

Promise<RegisteredAgent>— Registered agent with id, score, level, status, and assessment fields.

Example

const agent = await gov.register({
  name: "payment-agent",
  framework: "mastra",
  tools: ["check_balance", "initiate_transfer"],
  hasAuth: true,
  hasGuardrails: true,
  hasAuditLog: true,
  hasObservability: true,
});
// → { id: "...", score: 82, level: 4, status: "active", assessment: {...} }

gov.enforcev0.1.0+coreenforcement

gov.enforce(agentId: string, action: Action): Promise<EnforceResult>

Evaluates all policies against the proposed action before execution. Returns allow or block with the matching rule. Automatically writes to audit trail.

Parameters

name	type	description
`agentId`required	`string`	ID of the agent requesting the action (from gov.register()).
`action.tool`required	`string`	Name of the tool being called.
`action.params`	`Record<string, unknown>`	Tool parameters, logged to audit trail.

Returns

Promise<EnforceResult>— { outcome: 'allow' | 'block', rule?: string, reason?: string, latencyMs: number }

Example

const result = await gov.enforce("agent-123", {
  tool: "send_email",
  params: { to: "[email protected]", subject: "Report" },
});

if (result.outcome === "block") {
  throw new Error(`Blocked by ${result.rule}: ${result.reason}`);
}
// Proceed with execution

createKillSwitchv0.2.0+kill-switch

createKillSwitch(gov: Governance): KillSwitch

Creates a kill switch instance bound to a governance engine. Use ks.kill() to halt a specific agent, ks.killAll() for fleet-wide emergency. Priority 999 overrides all other policies.

Parameters

name	type	description
`gov`required	`Governance`	Governance instance from createGovernance().

Returns

KillSwitch— Kill switch with kill(), killAll(), revive(), reviveAll(), isKilled(), and getKillRecords() methods.

Example

import { createKillSwitch } from "governance-sdk/kill-switch";

const ks = createKillSwitch(gov);

ks.kill("agent-123", "Exceeded rate limit 3x in 1 minute");
// All future enforce() calls → { outcome: "block", rule: "kill-switch" }

ks.isKilled("agent-123"); // true
ks.revive("agent-123");   // Re-enable when safe
ks.getKillRecords();       // Full audit trail

Injection Detection

import ... from 'governance-sdk'

54-pattern regex injection scanner (F1 ≈ 0.48 — defense in depth, not a sole control). Run on all user-sourced strings before agent processing.

detectInjectionv0.2.0+security

detectInjection(input: string): InjectionResult

Synchronously scans a string for prompt injection patterns across 7 categories. Returns detection status, category, matched pattern, and confidence score.

Parameters

name	type	description
`input`required	`string`	User-provided string to scan.

Returns

InjectionResult— { detected: boolean, category?: string, pattern?: string, score: number }

Example

import { detectInjection } from "governance-sdk";

const result = detectInjection(userMessage);

if (result.detected) {
  return {
    blocked: true,
    category: result.category,  // "instruction_override"
    pattern: result.pattern,    // "ignore_previous_instructions"
    confidence: result.score,   // 0.94
  };
}

Audit Integrity

import ... from 'governance-sdk/audit-integrity'

HMAC-SHA256 hash-chained audit trail. Tamper detection with exact broken-link location.

createIntegrityChainv0.3.0+auditsecurity

createIntegrityChain(config: ChainConfig): IntegrityChain

Creates an HMAC-SHA256 hash-chained audit log. Each event includes the hash of the previous, making any modification detectable via chain.verify().

Parameters

name	type	description
`config.signingKey`required	`string`	Secret key for HMAC computation. Keep in environment variables.
`config.storage`	`StorageAdapter`	Where to persist events. Defaults to in-memory.

Returns

IntegrityChain— Chain with append(), verify(), and export() methods.

Example

import { createIntegrityChain } from "governance-sdk/audit-integrity";

const chain = createIntegrityChain({ signingKey: process.env.AUDIT_SECRET });

chain.append({ agentId: "a1", event: "tool_blocked", tool: "shell_exec" });

const { valid, brokenAt } = chain.verify();
// valid: true (or false + brokenAt: 3 if event #3 was modified)

const report = chain.export();
// { events: [...], verified: true, exportedAt: "..." }

EU AI Act Compliance Mapping

import ... from 'governance-sdk/compliance'

Self-assessment cross-reference of your governance configuration against EU AI Act Articles 9, 11, 12, 14, 15, and 50. Not a certified audit; not legal advice.

mapToEuAiActv0.3.0+compliance

mapToEuAiAct(config: ComplianceConfig): ComplianceResult

Maps your governance configuration against 6 EU AI Act articles and returns a self-assessment score with covered/gap breakdown. (Aliased as `assessCompliance` for backward compatibility.)

Parameters

name	type	description
`config.hasPolicies`	`boolean`	Whether policy rules are configured (Article 9, 15).
`config.hasAuditTrail`	`boolean`	Whether HMAC audit chain is enabled (Article 12).
`config.hasRequireApproval`	`boolean`	Whether human oversight gates are active (Article 14).
`config.registeredAgents`	`number`	Number of agents registered via gov.register() (Article 11).

Returns

ComplianceResult— { score: number, covered: string[], gaps: string[], articles: ArticleStatus[] }

Example

import { mapToEuAiAct, getDaysUntilDeadline } from "governance-sdk/compliance";

const result = mapToEuAiAct({
  hasPolicies: true,
  hasAuditTrail: true,
  hasRequireApproval: true,
  registeredAgents: 5,
});

console.log(result.score);        // 100
console.log(result.covered);      // ["9", "11", "12", "14", "15", "50"]
console.log(getDaysUntilDeadline()); // days until Aug 2, 2026

Enterprise (Lua Governance Cloud)

import ... from 'governance-sdk'

Enterprise governance runs on Lua Governance Cloud, the hosted product — not a separate npm package. Connect your SDK instance via serverUrl + apiKey on createGovernance(). Adds multi-tenant isolation, RBAC, distributed kill switch, ML injection detection, durable audit chain, approval queue, anomaly detection, and scheduled compliance reports.

createGovernance (remote mode)v0.5.0+enterprisecloud

createGovernance({ serverUrl, apiKey, fallbackMode }): GovernanceInstance

Connect the SDK to Lua Governance Cloud. enforce() and register() POST to the Cloud API instead of running in-process. fallbackMode controls behaviour when the API is unreachable after retries.

Parameters

name	type	description
`serverUrl`required	`string`	Cloud API base URL (e.g., 'https://api.heygovernance.ai').
`apiKey`required	`string`	Bearer token for your tenant.
`fallbackMode`	`'allow' \| 'block'`	What to do when the API is unreachable. Default 'allow' (fail-open).
`timeout`	`number`	Per-request timeout in ms. Default 30000.
`maxRetries`	`number`	Retry attempts on transient failure. Default 3.

Returns

GovernanceInstance— Same interface as the local SDK — enforce(), register(), audit, eval, recordOutcome — but routed through the Cloud.

Example

import { createGovernance } from "governance-sdk";

const gov = createGovernance({
  serverUrl: "https://api.heygovernance.ai",
  apiKey: process.env.GOVERNANCE_API_KEY!,
  fallbackMode: "allow",
});

const status = await gov.connect();
// { connected: true, mode: "remote", plan: "pro", features: [...] }

// Everything else is identical to local mode — the Cloud just adds shared state.
const decision = await gov.enforce({ agentId: "bot", action: "tool_call", tool: "search" });

Need the full quickstart?

8-step setup guide with adapter examples and policy templates.

Quickstart →Use Cases