bylaw-ts

Bylaw ALCV — TypeScript runtime enforcement SDK for AI agent actions.

The SDK intercepts proposed tool/API calls, requests policy clearance from an ALCV Vault server, blocks or escalates unapproved actions, and passes only approved actions forward with a short-lived signed A-JWT (Agentic JSON Web Token, Ed25519/EdDSA) and audit evidence.

Installation

npm install bylaw-ts

Optional Framework Adapters

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

# LlamaIndex.ts
npm install bylaw-ts llamaindex

# Vercel AI SDK
npm install bylaw-ts ai

# OpenTelemetry correlation (optional)
npm install bylaw-ts @opentelemetry/api

Quick Start

// bylaw.json
// {
//   "enforce": [
//     { "tool": "stripe*", "policyId": "financial-high-risk" },
//     { "tool": "*", "policyId": "default" }
//   ]
// }

import { configure, autoInstrument, currentToken } from "bylaw-ts";

const rawTools = {
  async stripeRefund(amount: number, reason: string) {
    const token = currentToken();
    return { refunded: amount, reason, token };
  },
};

configure({ agentId: "payments-agent" });

const tools = autoInstrument(rawTools);

const result = await tools.stripeRefund(45, "Late package");
console.log(result.token);

autoInstrument() reads bylaw.json from the current working directory by default, wraps matching functions automatically, and leaves unmatched entries unchanged.

Configuration

| Option | Env Variable | Default | Description | |---|---|---|---| | vaultUrl | BYLAW_VAULT_URL | http://localhost:8000 | Vault server URL | | vaultApiKey | BYLAW_VAULT_API_KEY | "" | API key for auth | | vaultTimeout | BYLAW_VAULT_TIMEOUT | 30000 | Timeout in ms | | verifyJwt | BYLAW_VERIFY_JWT | true | Auto-verify A-JWTs | | jwtIssuer | BYLAW_JWT_ISSUER | alcv-vault | Expected A-JWT issuer | | jwtAudience | BYLAW_JWT_AUDIENCE | bylaw-sdk | Expected A-JWT audience | | agentId | BYLAW_AGENT_ID | "default-agent" | Agent identifier | | sessionId | BYLAW_SESSION_ID | "" | Session identifier | | otelEnabled | BYLAW_OTEL_ENABLED | true | Emit OpenTelemetry span events and propagate trace context when an active span exists |

OpenTelemetry correlation

If your app already has OpenTelemetry configured, install @opentelemetry/api and leave otelEnabled on. The SDK records clearance outcomes as span events on the active span and sends context.telemetry.otel to Vault so ledger entries can be correlated back to your trace by trace_id, span_id, and request_id.

Events:

• bylaw.clearance.pending_review
• bylaw.clearance.decision

Event attributes include request ID, decision/status fields, policy version/hash, confidence buckets, tool name, agent/session IDs, manual review flag, and latency. The SDK also injects W3C trace propagation headers into Vault HTTP calls when OpenTelemetry propagation is available.

Telemetry is best-effort: if OpenTelemetry is not installed, disabled, or no span is active, clearance behavior is unchanged. The SDK does not include raw tool args, prompt text, model output, or policy reasoning in OTel attributes.

API Reference

BylawClient

const client = new BylawClient(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

autoInstrument

import * as rawTools from "./tools.js";

const tools = autoInstrument(rawTools);
const toolsFromInline = autoInstrument(rawTools, {
  enforce: [{ tool: "stripe*", policyId: "financial-high-risk" }],
});

tool

const specialFn = tool(async function specialRefund(amount: number) {
  return currentToken();
});

const overrideFn = tool(
  async function stripeCharge(amount: number) {
    return currentToken();
  },
  { policyId: "override-policy" },
);

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 "bylaw-ts/adapters/langchain";

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

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

Error Handling

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

Demo

npx tsx demo.ts

License

MIT