@entropy0/express 0.1.5

package/README.md

@@ -0,0 +1,101 @@
+# @entropy0/express
+
+Entropy0 Trust Control Plane middleware for Express.js.
+
+Evaluates an incoming request's target domain through the Entropy0 `/v1/decide` endpoint and routes it to the appropriate handler based on the recommended action — before your application logic runs.
+
+## Install
+
+```bash
+npm install @entropy0/express
+```
+
+## Usage
+
+```typescript
+import express from "express";
+import { entropy0Guard } from "@entropy0/express";
+
+const app = express();
+
+app.use(
+  entropy0Guard({
+    apiKey: process.env.ENTROPY0_API_KEY!,
+    policy: "balanced",
+  })
+);
+
+app.get("/proxy", (req, res) => {
+  // Only reached if action is "proceed" or "proceed_with_caution"
+  // req.entropy0 contains the full decision if caution was flagged
+  res.json({ ok: true });
+});
+```
+
+## Custom action handlers
+
+```typescript
+app.use(
+  "/outbound",
+  entropy0Guard({
+    apiKey: process.env.ENTROPY0_API_KEY!,
+    policy: "strict",
+
+    // Extract target from a query param instead of req.hostname
+    getTarget: (req) => {
+      const url = req.query.url as string;
+      return url ? { type: "url", value: url } : null;
+    },
+
+    // Describe the interaction context
+    getInteraction: (req) => ({
+      kind: "fetch",
+      mode: "read_only",
+      sensitivity: req.user?.role === "admin" ? "high" : "medium",
+    }),
+
+    onProceed:  (_req, _res, next, _result) => next(),
+    onCaution:  (req, res, next, result)    => { req.entropy0 = result; next(); },
+    onSandbox:  (_req, res) => res.status(403).json({ blocked: true, reason: "sandbox" }),
+    onEscalate: (_req, res) => res.status(403).json({ blocked: true, reason: "review_required" }),
+    onDeny:     (_req, res) => res.status(403).json({ blocked: true, reason: "deny" }),
+
+    // Fail open on API errors (default) — swap for fail closed if needed
+    onError: (_req, _res, next, err) => {
+      console.error("Entropy0 check failed:", err);
+      next();
+    },
+
+    timeoutMs: 3000,
+  })
+);
+```
+
+## Recommended actions
+
+| Action | Default behavior | Meaning |
+|---|---|---|
+| `proceed` | `next()` | Normal interaction is safe |
+| `proceed_with_caution` | `next()` + attaches `req.entropy0` | Continue with reduced trust assumptions |
+| `sandbox` | 403 | Interact only in an isolated environment |
+| `escalate_to_human` | 403 | Pause automation and request human review |
+| `deny` | 403 | Do not proceed under this policy |
+
+All handlers are overridable. Override `onSandbox` or `onEscalate` to queue for review instead of blocking.
+
+## TypeScript
+
+Full type exports — `DecisionResult`, `TargetDescriptor`, `InteractionDescriptor`, `Entropy0Options`.
+
+`req.entropy0` is automatically typed via Express namespace augmentation.
+
+## Requirements
+
+- Node.js 18+
+- Express 4+
+
+## Links
+
+- [API docs](https://entropy0.ai/docs)
+- [Decision model](https://entropy0.ai/docs/decision-model)
+- [Get an API key](https://entropy0.ai/signup)

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import type { Request, Response, NextFunction } from "express";
+export type RecommendedAction = "proceed" | "proceed_with_caution" | "sandbox" | "escalate_to_human" | "deny";
+export interface DecisionResult {
+    request_id: string;
+    decision: {
+        recommended_action: RecommendedAction;
+        action_confidence: number;
+        reason_codes: string[];
+    };
+    uncertainty: {
+        state: "low" | "medium" | "high";
+        requires_human_review: boolean;
+    };
+    validity: {
+        evaluated_at: string;
+        valid_until: string;
+        ttl_seconds: number;
+    };
+}
+export interface TargetDescriptor {
+    type: "domain" | "url";
+    value: string;
+}
+export interface InteractionDescriptor {
+    kind?: "navigate" | "fetch" | "enrich" | "download_file" | "submit_credentials" | "initiate_payment";
+    mode?: "read_only" | "transactional" | "privileged";
+    sensitivity?: "low" | "medium" | "high" | "critical";
+}
+export interface Entropy0Options {
+    /** Your Entropy0 API key (sk_ent0_xxxx). Required. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://entropy0.ai/api */
+    baseUrl?: string;
+    /** Policy profile to evaluate against. Defaults to "balanced". */
+    policy?: "open" | "balanced" | "strict" | "critical";
+    /** How to extract the target from the incoming request. Defaults to req.hostname. */
+    getTarget?: (req: Request) => TargetDescriptor | null;
+    /** How to describe the interaction context. Defaults to fetch / read_only / medium. */
+    getInteraction?: (req: Request) => InteractionDescriptor;
+    /** Called when action is "proceed". Default: calls next(). */
+    onProceed?: (req: Request, res: Response, next: NextFunction, result: DecisionResult) => void;
+    /** Called when action is "proceed_with_caution". Default: attaches result to req.entropy0, calls next(). */
+    onCaution?: (req: Request, res: Response, next: NextFunction, result: DecisionResult) => void;
+    /** Called when action is "sandbox". Default: 403. */
+    onSandbox?: (req: Request, res: Response, next: NextFunction, result: DecisionResult) => void;
+    /** Called when action is "escalate_to_human". Default: 403. */
+    onEscalate?: (req: Request, res: Response, next: NextFunction, result: DecisionResult) => void;
+    /** Called when action is "deny". Default: 403. */
+    onDeny?: (req: Request, res: Response, result: DecisionResult) => void;
+    /** Called when the Entropy0 API call fails. Default: fail open (calls next()). */
+    onError?: (req: Request, res: Response, next: NextFunction, error: unknown) => void;
+    /** Request timeout in ms. Defaults to 5000. */
+    timeoutMs?: number;
+}
+export declare function entropy0Guard(options: Entropy0Options): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+declare global {
+    namespace Express {
+        interface Request {
+            /** Entropy0 decision result, attached when action is proceed_with_caution. */
+            entropy0?: DecisionResult;
+        }
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entropy0Guard = entropy0Guard;
+// ── Internal API call ─────────────────────────────────────────────────────
+async function callDecide(target, interaction, policy, apiKey, baseUrl, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${baseUrl}/v1/decide`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": apiKey,
+            },
+            body: JSON.stringify({
+                target,
+                interaction: {
+                    kind: interaction.kind ?? "fetch",
+                    mode: interaction.mode ?? "read_only",
+                    sensitivity: interaction.sensitivity ?? "medium",
+                },
+                policy: { profile: policy },
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`Entropy0 API responded ${res.status}: ${body}`);
+        }
+        return res.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ── Middleware factory ─────────────────────────────────────────────────────
+function entropy0Guard(options) {
+    const { apiKey, baseUrl = "https://entropy0.ai/api", policy = "balanced", timeoutMs = 5000, getTarget = (req) => ({ type: "domain", value: req.hostname }), getInteraction = () => ({}), onProceed = (_req, _res, next, _result) => next(), onCaution = (req, res, next, result) => { req.entropy0 = result; next(); }, onSandbox = (_req, res, _next, _result) => res.status(403).json({ blocked: true, action: "sandbox" }), onEscalate = (_req, res, _next, _result) => res.status(403).json({ blocked: true, action: "escalate_to_human" }), onDeny = (_req, res, _result) => res.status(403).json({ blocked: true, action: "deny" }), onError = (_req, _res, next, _err) => next(), // fail open by default
+     } = options;
+    return async function entropy0Middleware(req, res, next) {
+        const target = getTarget(req);
+        if (!target)
+            return next();
+        try {
+            const interaction = getInteraction(req);
+            const result = await callDecide(target, interaction, policy, apiKey, baseUrl, timeoutMs);
+            switch (result.decision.recommended_action) {
+                case "proceed": return onProceed(req, res, next, result);
+                case "proceed_with_caution": return onCaution(req, res, next, result);
+                case "sandbox": return onSandbox(req, res, next, result);
+                case "escalate_to_human": return onEscalate(req, res, next, result);
+                case "deny": return onDeny(req, res, result);
+                default: return next();
+            }
+        }
+        catch (err) {
+            return onError(req, res, next, err);
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@entropy0/express",
+  "version": "0.1.5",
+  "description": "Entropy0 Trust Control Plane middleware for Express.js — gate requests through trust evaluation before your server processes them.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "express", "middleware", "trust", "security",
+    "domain-intelligence", "ai-agents", "trust-control-plane"
+  ],
+  "author": "Entropy0 <dev@entropy0.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/entropy0dev/sdk"
+  },
+  "homepage": "https://entropy0.ai/docs",
+  "bugs": {
+    "url": "https://github.com/entropy0dev/sdk/issues"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "express": "^4.18.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}