Authensor TypeScript SDK guide

The Authensor TypeScript SDK (@authensor/sdk) is the primary way to integrate safety guardrails into TypeScript and JavaScript AI agents. This guide covers the full API surface.

Creating a guard

The createGuard function is the main entry point:

import { createGuard } from '@authensor/sdk';

// From a YAML file
const guard = createGuard({ policyPath: './policy.yaml' });

// From an inline policy object
const guard = createGuard({
  policy: {
    version: '1',
    rules: [
      { tool: '*', action: 'allow' }
    ]
  }
});

// Connected to the control plane
const guard = createGuard({
  controlPlane: 'https://your-server.com',
  apiKey: process.env.AUTHENSOR_API_KEY,
});

Evaluating tool calls

Call the guard with a tool name and arguments:

const decision = guard(toolName, args);

The return type is PolicyDecision:

interface PolicyDecision {
  action: 'allow' | 'block' | 'escalate';
  reason?: string;
  rule?: PolicyRule;
  threats?: ContentThreat[];
  receipt: Receipt;
}

Enabling Aegis

Pass aegis options to enable content scanning:

const guard = createGuard({
  policy,
  aegis: {
    enabled: true,
    threshold: 0.7,
    detectors: ['prompt_injection', 'pii', 'credentials'],
  }
});

Aegis runs before policy evaluation. If it detects a threat above the threshold, the action is blocked regardless of the policy.

Enabling Sentinel

const guard = createGuard({
  policy,
  sentinel: {
    enabled: true,
    windowSize: 60_000,  // 1 minute sliding window
    alertThreshold: 5,   // Alert after 5 anomalies
    onAlert: (alert) => {
      notify('sentinel-alert', alert);
    },
  }
});

Session context

Attach session-level context that policies can match against:

const guard = createGuard({
  policy,
  context: {
    userId: 'user_123',
    role: 'engineer',
    environment: 'production',
  }
});

# Policy can match on context
- tool: "deployment.trigger"
  action: block
  when:
    context.environment:
      equals: "production"
    context.role:
      not:
        equals: "devops"

Receipt access

Access the full receipt chain:

const receipts = guard.getReceipts();
const valid = guard.verifyChain();

// Export for external storage
const exported = guard.exportReceipts();

Error handling

The guard function itself never throws. It always returns a PolicyDecision. If something goes wrong internally (corrupted policy, missing configuration), the guard fails closed and returns a block decision:

const decision = guard('tool.name', args);
// If internal error: decision.action === 'block'
// decision.reason === 'Internal error: fail-closed'

This ensures that a misconfiguration cannot accidentally permit actions.

TypeScript types

All types are generated from JSON Schema. Import them directly:

import type { PolicyDecision, Receipt, PolicyRule, ContentThreat } from '@authensor/sdk';