JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 819
  • Score
    100M100P100Q91787F
  • License MIT

Bylaw ALCV runtime enforcement SDK for AI agent actions with policy-gated clearance, A-JWT authorization, and audit evidence

Package Exports

  • bylaw-ts
  • bylaw-ts/adapters/langchain
  • bylaw-ts/adapters/llamaindex
  • bylaw-ts/adapters/vercel-ai

Readme

bylaw-ts

npm License: MIT

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