Network Gateway

sec0-sdk/gateway centralizes authentication, authorization, entitlements, quotas, vendor token brokering, idempotency/dedupe, and audit at network boundaries. Use it when tool execution crosses process or network boundaries so custody and policy enforcement continue across hops.

When to Use the Gateway

Your agents call tool servers over HTTP/HTTPS
You need centralized OIDC auth at the network edge
You want per-tenant/per-user rate limits and daily quotas
You need vendor API key injection without exposing keys to agents
You want idempotency/dedupe for side-effecting tool calls
You need egress and filesystem allowlists at the boundary

Starting the Gateway

import { startGatewayServer, InMemoryAdapter } from "sec0-sdk/gateway";
import { Sec0Appender } from "sec0-sdk/audit";
import { LocalDevSigner } from "sec0-sdk/signer";

const signer = LocalDevSigner.fromKeyRef("file://./.sec0/keys/ed25519.key");
const appender = new Sec0Appender({ config: { dir: ".sec0" }, signer });

startGatewayServer({
  port: 8088,
  tenant: "my-app",

  // Map server names to upstream base URLs
  targets: {
    "vision-mcp": "https://vision.example.com",
    "database-mcp": "https://db.example.com",
    "stripe-mcp": "https://stripe-adapter.example.com",
  },

  // Required: audit sink
  audit: {
    append: (env) => appender.append(env),
    gatewayName: "sec0.gateway",
    gatewayVersion: "1.0.0",
  },

  // Required: quota adapter
  quotas: { adapter: new InMemoryAdapter() },

  // Start in observe mode, then switch to enforce
  enforcement: { mode: "observe" },
});

Gateway Endpoints

Endpoint	Description
`POST /mcp/:server/:toolAtVersion`	Invoke a tool on an upstream server
`POST /a2a/invoke`	Agent-to-agent convenience envelope

Required Headers

Header	Purpose
`x-idempotency-key`	Required when dedupe or side-effect idempotency policies are enabled
`x-node-id`	Agent state: node identifier
`x-agent-ref`	Agent state: run reference
`x-agent-state`	Agent state: full encoded payload

Authentication

OIDC JWT Validation

startGatewayServer({
  // ...
  authn: {
    allowUnauthenticated: false,
    oidc: {
      issuer: "https://auth.example.com",
      audience: "sec0.gateway",
      jwks_uri: "https://auth.example.com/.well-known/jwks.json",
      tenantClaim: "org",
      userClaim: "email",
      rolesClaim: "roles",
      subjectClaim: "sub",
      clientIdClaim: "azp",
    },
  },
});

For machine-to-machine agents, use OIDC client-credentials tokens (the gateway can authorize these via agents entitlements using the token azp/client_id claim).

Entitlements

Control which tenants, users, roles, and service agents can access which tools:

startGatewayServer({
  // ...
  entitlements: {
    default_plan: "free",
    plans: {
      free: { calls_per_day: 1000 },
      pro: { calls_per_day: 100000 },
    },
    tenants: {
      "acme-corp": {
        plan: "pro",
        allowlist: [],
        denylist: ["mcp://payments/refund@2.0"],
        per_tool: {
          "mcp://fetch/fetch.get@1.0": { rate_per_sec: 10, calls_per_day: 50000 },
        },
        users: {
          "admin@acme.com": { allowlist: ["*"] },
          "readonly@acme.com": { allowlist: ["mcp://fetch/*@1.*"] },
        },
        user_ids: {
          "auth0|usr_123": { allowlist: ["mcp://ehr/patient.read@r4"] },
        },
        roles: {
          "security-analyst": { allowlist: ["mcp://posture/*@1.*"] },
          "contractor": { denylist: ["mcp://payments/*@2.*"] },
        },
        agents: {
          "sec0-orchestrator-prod": { allowlist: ["mcp://payments/charge@2.*"] },
        },
        agent_nodes: {
          "workflow-planner": { allowlist: ["mcp://planner/*@1.*"] },
        },
      },
    },
  },
});

Quotas

Rate limiting and daily limits via pluggable adapters:

import { InMemoryAdapter } from "sec0-sdk/gateway";

startGatewayServer({
  // ...
  quotas: {
    adapter: new InMemoryAdapter(),
    // Or use a Redis adapter for production:
    // adapter: new RedisAdapter({ url: process.env.REDIS_URL }),
  },
});

QuotaAdapter Interface

interface QuotaAdapter {
  incrDaily(tenant: string, tool: string, limit: number, now?: Date):
    Promise<{ count: number; resetAt: Date }>;
  takeToken(tenant: string, tool: string, ratePerSec: number, burst?: number, now?: Date):
    Promise<{ tokens: number; resetAt: Date }>;
}

Vendor Token Brokering

Inject upstream API keys without exposing them to agents:

startGatewayServer({
  // ...
  brokers: {
    "stripe-mcp": {
      type: "vendor_key_pool",
      key_refs: [
        "file:///etc/sec0/stripe-key-1.txt",
        "file:///etc/sec0/stripe-key-2.txt",
      ],
      inject: {
        header: "Authorization",
        format: "bearer",
      },
    },
  },
});

Broker Types

Type	Description
`vendor_key_pool`	Round-robin from a pool of API keys
`oidc_on_behalf`	Exchange tokens via OIDC on-behalf-of flow
`static`	Inject a single static key

Boundary Guardrails

Restrict what upstream servers can access:

startGatewayServer({
  // ...
  security: {
    egress_allowlist: ["*.example.com", "api.stripe.com"],
    fs_allowlist: ["/tmp/sec0-*"],
    limits: {
      max_payload_kb: 1024,
      max_duration_ms: 30000,
    },
    side_effects: {
      require_idempotency_key: true,
      approve_high_risk: true,
    },
    allow_versions: {
      "vision-mcp": ["1.0.0", "1.1.0"],
      "database-mcp": ["2.*"],
    },
  },
});

Idempotency & Dedupe

Prevent duplicate side-effect calls:

startGatewayServer({
  // ...
  dedupe: {
    enabled: true,
    duplicatePolicy: "replay",  // "replay" | "reject"
    ttlSec: 3600,               // Cache window
    namespace: "sec0-gw",       // Key prefix
    redisUrl: process.env.REDIS_URL,  // Optional Redis backend
  },
});

AP2 Mandate Enforcement

Verify multi-hop intent and cart mandates:

startGatewayServer({
  // ...
  ap2: {
    enabled: true,
    requireForSideEffects: true,
    headers: {
      intent: "x-ap2-intent-mandate",
      cart: "x-ap2-cart-mandate",
      bundle: "x-ap2-bundle",
    },
    trust: {
      didMethods: ["did:web"],
      issuersAllowlist: ["did:web:example.com"],
      clockSkewSec: 60,
    },
    mode: "full",  // "" | "observe" | "partial" | "full"
  },
});

Agent State Analytics

Opt-in to derived telemetry written into agent state:

startGatewayServer({
  // ...
  agentState: {
    enableGatewayAnalytics: true,
    includeAp2: true,
    includeRisk: true,
  },
});

Remote Runtime Decisioning

Use the gateway’s runtime adapter when final allow or deny decisions should be delegated to a remote service:

startGatewayServer({
  // ...
  runtime: {
    enforcement: {
      mode: "remote",
      protocolVersion: "2026-02-01",
      failureMode: "local",
      remote: {
        endpoint: process.env.SEC0_RUNTIME_URL!,
        apiKey: process.env.SEC0_RUNTIME_API_KEY,
        timeoutMs: 3000,
      },
    },
  },
});

Using the Pipeline Directly

If you already have an HTTP server, use the lower-level pipeline:

import { gatewayPipeline } from "sec0-sdk/gateway";

// In your route handler:
await gatewayPipeline(config, serverName, toolAtVersion, ctx, span, next);

Policy-Driven Configuration

Map a Sec0 policy YAML into gateway config:

startGatewayServer({
  port: 8088,
  tenant: "my-app",
  targets: { /* ... */ },
  policyYaml: fs.readFileSync("./policy.yaml", "utf8"),
  // ... audit and quotas still required
});

For the full gateway configuration reference, see Gateway Config Reference.

Getting Started

In-Device Security

Network Boundary Security

Policy & Compliance

Operations

Advanced

Reference

Network Gateway

When to Use the Gateway

Starting the Gateway

Gateway Endpoints

Required Headers

Authentication

OIDC JWT Validation

Entitlements

Quotas

QuotaAdapter Interface

Vendor Token Brokering

Broker Types

Boundary Guardrails

Idempotency & Dedupe

AP2 Mandate Enforcement

Agent State Analytics

Remote Runtime Decisioning

Using the Pipeline Directly

Policy-Driven Configuration

​When to Use the Gateway

​Starting the Gateway

​Gateway Endpoints

​Required Headers

​Authentication

​OIDC JWT Validation

​Entitlements

​Quotas

​QuotaAdapter Interface

​Vendor Token Brokering

​Broker Types

​Boundary Guardrails

​Idempotency & Dedupe

​AP2 Mandate Enforcement

​Agent State Analytics

​Remote Runtime Decisioning

​Using the Pipeline Directly

​Policy-Driven Configuration

When to Use the Gateway

Starting the Gateway

Gateway Endpoints

Required Headers

Authentication

OIDC JWT Validation

Entitlements

Quotas

QuotaAdapter Interface

Vendor Token Brokering

Broker Types

Boundary Guardrails

Idempotency & Dedupe

AP2 Mandate Enforcement

Agent State Analytics

Remote Runtime Decisioning

Using the Pipeline Directly

Policy-Driven Configuration