meshguard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MeshGuard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# MeshGuard SDK for TypeScript / JavaScript
+
+> AI agent governance — policy enforcement, audit logging, and trust management.
+
+[![npm](https://img.shields.io/npm/v/meshguard)](https://www.npmjs.com/package/meshguard)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MeshGuard provides governance guardrails for AI agents. This SDK lets your TypeScript/JavaScript agents enforce policies, generate audit trails, and manage trust — with zero runtime dependencies.
+
+## Features
+
+- 🛡️ **Policy enforcement** — check, enforce, or govern any action
+- 📋 **Audit logging** — full trail of every decision
+- 🤖 **Agent management** — create, list, and revoke agents
+- 🔗 **LangChain.js integration** — govern tools and toolkits
+- 📦 **Zero runtime deps** — uses native `fetch` (Node 18+)
+- 🎯 **Full TypeScript** — complete type definitions
+- 🔄 **Dual output** — ESM + CommonJS
+
+## Installation
+
+```bash
+npm install meshguard
+```
+
+## Quick Start
+
+```ts
+import { MeshGuardClient } from "meshguard";
+
+const client = new MeshGuardClient({
+  gatewayUrl: "https://dashboard.meshguard.app",
+  agentToken: "your-agent-token",
+});
+
+// Check if an action is allowed
+const decision = await client.check("read:contacts");
+if (decision.allowed) {
+  console.log("Access granted!");
+}
+```
+
+## Configuration
+
+The client reads configuration from constructor options or environment variables:
+
+| Option       | Env Variable             | Default                  |
+| ------------ | ------------------------ | ------------------------ |
+| `gatewayUrl` | `MESHGUARD_GATEWAY_URL`  | `http://localhost:3100`  |
+| `agentToken` | `MESHGUARD_AGENT_TOKEN`  | —                        |
+| `adminToken` | `MESHGUARD_ADMIN_TOKEN`  | —                        |
+| `timeout`    | —                        | `30000` (ms)             |
+| `traceId`    | —                        | Auto-generated UUID      |
+
+```ts
+// Using environment variables (zero-config)
+const client = new MeshGuardClient();
+
+// Explicit options override env vars
+const client = new MeshGuardClient({
+  gatewayUrl: "https://dashboard.meshguard.app",
+  agentToken: process.env.MY_TOKEN,
+});
+```
+
+## Core Governance
+
+### check() — Non-throwing policy check
+
+Returns a `PolicyDecision` — never throws on deny.
+
+```ts
+const decision = await client.check("read:contacts");
+
+if (decision.allowed) {
+  const contacts = await fetchContacts();
+} else {
+  console.log(`Denied: ${decision.reason}`);
+  console.log(`Policy: ${decision.policy}, Rule: ${decision.rule}`);
+}
+```
+
+### enforce() — Throwing policy check
+
+Throws `PolicyDeniedError` if the action is denied.
+
+```ts
+import { PolicyDeniedError } from "meshguard";
+
+try {
+  await client.enforce("write:email");
+  await sendEmail(to, subject, body);
+} catch (err) {
+  if (err instanceof PolicyDeniedError) {
+    console.error(`Blocked by policy: ${err.policy}`);
+  }
+}
+```
+
+### govern() — Governed function execution
+
+Combines enforcement with execution — the function only runs if allowed.
+
+```ts
+// Sync or async functions work
+const contacts = await client.govern("read:contacts", async () => {
+  return db.contacts.findAll();
+});
+
+// With resource context
+const file = await client.govern(
+  "read:file",
+  () => fs.readFileSync("/etc/config"),
+  "/etc/config",
+);
+```
+
+## Proxy Requests
+
+Route HTTP requests through the MeshGuard governance proxy:
+
+```ts
+// GET through proxy
+const response = await client.get("/api/users", "read:users");
+
+// POST through proxy
+const response = await client.post("/api/users", "write:users", {
+  body: JSON.stringify({ name: "Alice" }),
+  headers: { "Content-Type": "application/json" },
+});
+
+// Generic method
+const response = await client.request("PATCH", "/api/users/1", "write:users", {
+  body: JSON.stringify({ name: "Bob" }),
+});
+```
+
+## Admin Operations
+
+These require an `adminToken`:
+
+### Agent Management
+
+```ts
+const admin = new MeshGuardClient({
+  adminToken: "your-admin-token",
+});
+
+// List all agents
+const agents = await admin.listAgents();
+for (const agent of agents) {
+  console.log(`${agent.name} (${agent.trustTier})`);
+}
+
+// Create a new agent
+const result = await admin.createAgent({
+  name: "data-bot",
+  trustTier: "verified",
+  tags: ["production", "data-team"],
+});
+
+// Revoke an agent
+await admin.revokeAgent("agent-id-123");
+```
+
+### Audit Log
+
+```ts
+// Get recent entries
+const entries = await admin.getAuditLog({ limit: 100 });
+
+// Filter by decision
+const denials = await admin.getAuditLog({
+  limit: 50,
+  decision: "deny",
+});
+```
+
+### Policies
+
+```ts
+const policies = await admin.listPolicies();
+```
+
+## Health Check
+
+```ts
+// Detailed health info
+const status = await client.health();
+
+// Quick boolean check
+if (await client.isHealthy()) {
+  console.log("Gateway is up");
+}
+```
+
+## LangChain.js Integration
+
+Govern LangChain tools with MeshGuard policies:
+
+```ts
+import { MeshGuardClient } from "meshguard";
+import {
+  GovernedTool,
+  GovernedToolkit,
+  governedTool,
+} from "meshguard/langchain";
+```
+
+### Wrap a single tool
+
+```ts
+import { DuckDuckGoSearch } from "@langchain/community/tools/duckduckgo";
+
+const client = new MeshGuardClient();
+const search = new DuckDuckGoSearch();
+
+// Functional wrapper
+const governed = governedTool("read:web_search", client, search);
+const result = await governed.invoke("TypeScript SDK patterns");
+
+// Class wrapper
+const governedSearch = new GovernedTool({
+  tool: search,
+  action: "read:web_search",
+  client,
+  onDeny: (err) => `Search blocked: ${err.reason}`,
+});
+```
+
+### Govern a toolkit
+
+```ts
+const toolkit = new GovernedToolkit({
+  tools: [searchTool, calcTool, emailTool],
+  client,
+  actionMap: {
+    search: "read:web_search",
+    calculator: "execute:math",
+    email: "write:email",
+  },
+  defaultAction: "execute:tool",
+});
+
+const governedTools = toolkit.getTools();
+// Pass governedTools to your LangChain agent
+```
+
+## Error Handling
+
+All errors extend `MeshGuardError`:
+
+```ts
+import {
+  MeshGuardError,
+  PolicyDeniedError,
+  AuthenticationError,
+  RateLimitError,
+} from "meshguard";
+
+try {
+  await client.enforce("dangerous:action");
+} catch (err) {
+  if (err instanceof PolicyDeniedError) {
+    // Action was denied by policy
+    console.log(err.action);  // "dangerous:action"
+    console.log(err.policy);  // "safety-policy"
+    console.log(err.rule);    // "block-dangerous"
+    console.log(err.reason);  // "Action not permitted"
+  } else if (err instanceof AuthenticationError) {
+    // Token is invalid or expired
+  } else if (err instanceof RateLimitError) {
+    // Too many requests
+  } else if (err instanceof MeshGuardError) {
+    // Other gateway error
+  }
+}
+```
+
+## Python SDK
+
+Looking for the Python SDK? See [meshguard-python](https://github.com/dbhurley/meshguard-python).
+
+## Requirements
+
+- **Node.js 18+** (uses native `fetch` and `crypto.randomUUID`)
+- **TypeScript 5.0+** (optional — works with plain JavaScript too)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cjs/client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * MeshGuard Client
+ *
+ * Core client for interacting with the MeshGuard gateway.
+ */
+import type { MeshGuardOptions, PolicyDecision, Agent, CreateAgentOptions, AuditEntry, AuditLogOptions, HealthStatus, Policy } from "./types.js";
+/**
+ * Client for the MeshGuard governance gateway.
+ *
+ * @example
+ * ```ts
+ * const client = new MeshGuardClient({
+ *   gatewayUrl: "https://dashboard.meshguard.app",
+ *   agentToken: "your-agent-token",
+ * });
+ *
+ * // Check if an action is allowed
+ * const decision = await client.check("read:contacts");
+ * if (decision.allowed) {
+ *   // proceed
+ * }
+ *
+ * // Or enforce (throws on deny)
+ * await client.enforce("read:contacts");
+ *
+ * // Or govern a function
+ * const result = await client.govern("read:contacts", async () => {
+ *   return fetchContacts();
+ * });
+ * ```
+ */
+export declare class MeshGuardClient {
+    readonly gatewayUrl: string;
+    readonly agentToken?: string;
+    readonly adminToken?: string;
+    readonly timeout: number;
+    readonly traceId: string;
+    constructor(options?: MeshGuardOptions);
+    private headers;
+    private adminHeaders;
+    private handleResponse;
+    private safeJson;
+    private fetch;
+    /**
+     * Check if an action is allowed by policy.
+     *
+     * Returns a {@link PolicyDecision} — never throws on deny.
+     */
+    check(action: string, resource?: string): Promise<PolicyDecision>;
+    /**
+     * Enforce policy — throws {@link PolicyDeniedError} if the action is denied.
+     */
+    enforce(action: string, resource?: string): Promise<PolicyDecision>;
+    /**
+     * Execute a function only if the action is allowed by policy.
+     *
+     * @example
+     * ```ts
+     * const contacts = await client.govern("read:contacts", async () => {
+     *   return db.contacts.findAll();
+     * });
+     * ```
+     */
+    govern<T>(action: string, fn: () => T | Promise<T>, resource?: string): Promise<T>;
+    /**
+     * Make a governed request through the MeshGuard proxy.
+     */
+    request(method: string, path: string, action: string, init?: RequestInit): Promise<Response>;
+    /** GET through the governance proxy. */
+    get(path: string, action: string, init?: RequestInit): Promise<Response>;
+    /** POST through the governance proxy. */
+    post(path: string, action: string, init?: RequestInit): Promise<Response>;
+    /** PUT through the governance proxy. */
+    put(path: string, action: string, init?: RequestInit): Promise<Response>;
+    /** DELETE through the governance proxy. */
+    delete(path: string, action: string, init?: RequestInit): Promise<Response>;
+    /** Check gateway health. */
+    health(): Promise<HealthStatus>;
+    /** Quick boolean health check. */
+    isHealthy(): Promise<boolean>;
+    /** List all agents (requires admin token). */
+    listAgents(): Promise<Agent[]>;
+    /** Create a new agent (requires admin token). */
+    createAgent(options: CreateAgentOptions): Promise<Record<string, unknown>>;
+    /** Revoke an agent (requires admin token). */
+    revokeAgent(agentId: string): Promise<void>;
+    /** List all policies (requires admin token). */
+    listPolicies(): Promise<Policy[]>;
+    /** Get audit log entries (requires admin token). */
+    getAuditLog(options?: AuditLogOptions): Promise<AuditEntry[]>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,KAAK,EACL,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,MAAM,EACP,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,GAAE,gBAAqB;IAmB1C,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,YAAY;YAUN,cAAc;YAuBd,QAAQ;YAUR,KAAK;IAiBnB;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAgDvE;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAazE;;;;;;;;;OASG;IACG,MAAM,CAAC,CAAC,EACZ,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACxB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC;IASb;;OAEG;IACG,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,QAAQ,CAAC;IAwBpB,wCAAwC;IAClC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI9E,yCAAyC;IACnC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI/E,wCAAwC;IAClC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI9E,2CAA2C;IACrC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAQjF,4BAA4B;IACtB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAKrC,kCAAkC;IAC5B,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAanC,8CAA8C;IACxC,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAepC,iDAAiD;IAC3C,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAgBhF,8CAA8C;IACxC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjD,gDAAgD;IAC1C,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQvC,oDAAoD;IAC9C,WAAW,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CAYxE"}