@trigguard/express-middleware

@trigguard/express-middleware

Express middleware for TrigGuard. Two explicit modes — do not confuse them.

TRIGGUARD_PROTECTED (FULLY_ENFORCED)

Consequential effects run only after:

authorize → PERMIT + EAT → executeBound (FINAL_PEP) → server-owned adapter → effect

next() is not used for effects. Presented PERMIT / HTTP 200 are never enough.

import express from "express";
import {
  trigguardProtectedEffect,
  disposableProtectedExpressAdapter,
} from "@trigguard/express-middleware";

// Distributed replay store required (Postgres-backed in production).
const replayStore = /* InMemoryReplayStore only for hermetic demos with distributed:true */;

app.post(
  "/protected-effect",
  trigguardProtectedEffect({
    gatewayUrl: process.env.TRIGGUARD_GATEWAY_URL,
    apiKey: process.env.TRIGGUARD_API_KEY,
    organizationId: process.env.TRIGGUARD_ORG_ID,
    surface: "deploy.release",
    replayStore,
    mapBinding: () => ({
      repository: "TrigGuard-AI/trigguard-example-deploy",
      commit: "",
      workflow: "",
      environment: "sandbox",
    }),
    mapContext: (req) => ({
      repository: "TrigGuard-AI/trigguard-example-deploy",
      environment: "sandbox",
      ...req.body?.context,
    }),
    mapPayload: (req) => req.body,
    runProtectedAdapter: disposableProtectedExpressAdapter, // or your SERVER_OWNED adapter
  }),
);

Credential sovereignty

• Rejects request-body provider secrets (api_key, stripeSecretKey, …).
• Refuses when agent-reachable provider env vars are set (OPENAI_API_KEY, STRIPE_SECRET_KEY, …).
• Adapter secrets come only from TRIGGUARD_SERVER_OWNED_* (or TRIGGUARD_EXPRESS_DISPOSABLE_STUB=1 for hermetic canaries).

UNPROTECTED_OR_PARTIAL (PARTIALLY_ENFORCED)

Default trigguardExecute — requires PERMIT + EAT before next(), but route handlers may still hold independently usable credentials.

import { trigguardExecute } from "@trigguard/express-middleware";

app.post(
  "/partial",
  trigguardExecute({
    gatewayUrl,
    apiKey,
    organizationId,
    surface: "deploy.release",
    mode: "UNPROTECTED_OR_PARTIAL", // default
  }),
  handler, // NOT fully protected
);

Do not market generic trigguardExecute + next() as FULLY_ENFORCED.

Set TRIGGUARD_EXPRESS_MODE=TRIGGUARD_PROTECTED|UNPROTECTED_OR_PARTIAL where applicable. trigguardExecute({ mode: "TRIGGUARD_PROTECTED" }) throws — use trigguardProtectedEffect.

Build / test

npm run build -w @trigguard/express-middleware
npm test -w @trigguard/express-middleware

License

Apache-2.0 (see repository root LICENSE).