ledgix-ts

Ledgix ALCV — TypeScript SDK for SOX 404 compliance enforcement on AI agent tool calls.

The SDK acts as a shim that intercepts AI agent tool calls, sends clearance requests to an ALCV Vault server, and only allows execution if the Vault approves and returns a signed A-JWT (Agentic JSON Web Token, Ed25519/EdDSA).

Installation

npm install ledgix-ts

Optional Framework Adapters

# LangChain.js
npm install ledgix-ts @langchain/core

# LlamaIndex.ts
npm install ledgix-ts llamaindex

# Vercel AI SDK
npm install ledgix-ts ai

Quick Start

import { LedgixClient, vaultEnforce } from "ledgix-ts";
import type { ClearanceResponse } from "ledgix-ts";

// Create a client (reads LEDGIX_* env vars automatically)
const client = new LedgixClient({
  vaultUrl: "https://vault.example.com",
  vaultApiKey: "your-api-key",
});

// Wrap a function with Vault enforcement
const guardedRefund = vaultEnforce(client, { toolName: "stripe_refund" })(
  async (amount: number, reason: string, _clearance?: ClearanceResponse) => {
    // _clearance is automatically injected with the A-JWT
    return { refunded: amount, token: _clearance!.token };
  },
);

// Call it — clearance is checked automatically
const result = await guardedRefund(45, "Late package");

Configuration

| Option | Env Variable | Default | Description | |---|---|---|---| | vaultUrl | LEDGIX_VAULT_URL | http://localhost:8000 | Vault server URL | | vaultApiKey | LEDGIX_VAULT_API_KEY | "" | API key for auth | | vaultTimeout | LEDGIX_VAULT_TIMEOUT | 30000 | Timeout in ms | | verifyJwt | LEDGIX_VERIFY_JWT | true | Auto-verify A-JWTs | | jwtIssuer | LEDGIX_JWT_ISSUER | alcv-vault | Expected A-JWT issuer | | jwtAudience | LEDGIX_JWT_AUDIENCE | ledgix-sdk | Expected A-JWT audience | | agentId | LEDGIX_AGENT_ID | "default-agent" | Agent identifier | | sessionId | LEDGIX_SESSION_ID | "" | Session identifier |

API Reference

LedgixClient

const client = new LedgixClient(config?);

await client.requestClearance(request);   // → ClearanceResponse
await client.registerPolicy(policy);      // → PolicyRegistrationResponse
await client.fetchJwks();                 // → JWKS object
await client.verifyToken(token);          // → decoded payload
await client.close();                     // cleanup

vaultEnforce (Higher-Order Function)

const guarded = vaultEnforce(client, {
  toolName: "my_tool",
  policyId: "policy-001",
  context: { key: "value" },
})(myAsyncFunction);

withVaultContext (Callback Pattern)

await withVaultContext(
  client,
  "stripe_refund",
  { amount: 45 },
  { policyId: "refund-policy" },
  async (clearance) => {
    // Use clearance.token
  },
);

Framework Adapters

// LangChain.js
import { wrapLangChainTool } from "ledgix-ts/adapters/langchain";

// LlamaIndex.ts
import { wrapTool } from "ledgix-ts/adapters/llamaindex";

// Vercel AI SDK
import { wrapVercelTool } from "ledgix-ts/adapters/vercel-ai";

Error Handling

import {
  ClearanceDeniedError,
  VaultConnectionError,
  TokenVerificationError,
  PolicyRegistrationError,
} from "ledgix-ts";

Demo

npx tsx demo.ts

License

MIT