Gateway Config Reference

The gateway is the network-boundary runtime that accepts incoming tool calls, applies policy, and forwards allowed requests upstream. This page keeps the configuration surface a gateway integrator normally wires into an application.

Minimal shape

startGatewayServer({
  port: 8088,
  tenant: "my-app",
  targets: {
    orders: "https://orders.internal.example.com",
  },
  policyYaml,
});

const config: MiddlewareConfig = {
  authn: {
    oidc: {
      issuer: process.env.OIDC_ISSUER!,
      audience: process.env.OIDC_AUDIENCE!,
      jwks_uri: process.env.OIDC_JWKS_URI!,
    },
  },
  quotas: {
    adapter: myQuotaAdapter,
  },
  audit: {
    append: (env) => audit.append(env),
    gatewayName: "edge-gateway",
    gatewayVersion: "1.0.0",
  },
  enforcement: {
    mode: "enforce",
    deny_on: ["tool_not_in_allowlist"],
  },
  security: {
    egress_allowlist: ["*.internal.example.com"],
    side_effects: {
      require_idempotency_key: true,
    },
  },
};

`startGatewayServer(...)` options

Key	Type	Required	Description
`port`	number	Yes	HTTP listen port
`tenant`	string	Yes	Default tenant used by the bootstrapper
`targets`	`Record<string, string>`	Yes	Server name to upstream base URL map
`policyYaml`	string	No	Policy YAML mapped into runtime config before startup
`policyObject`	object	No	Object form of the same override flow
`sec0Dir`	string	No	Optional local Sec0 directory hint

audit and quotas are required at runtime. The gateway throws if either is missing.

Policy YAML overrides

When you pass policyYaml or policyObject, the bootstrapper maps the following policy sections into gateway runtime config:

Policy section	Runtime target
`authn`	`authn`
`entitlements`	`entitlements`
`brokers`	`brokers`
`targets`	`targets`
`enforcement`	`enforcement`
`runtime.enforcement`	`runtime.enforcement`
`security`	`security`
`privacy`	`privacy`
`ap2` or `security.ap2`	`ap2`

If you need anything outside that mapping, provide it directly in MiddlewareConfig.

`MiddlewareConfig`

Key	Type	Required	Description
`authn`	object	No	Bearer-token validation config
`entitlements`	object	No	Tenant and plan entitlements
`quotas`	object	Yes	Quota adapter configuration
`privacy`	object	No	Privacy controls
`enforcement`	object	No	Observe/enforce mode plus deny and escalate reasons
`ap2`	object	No	AP2 mandate handling
`brokers`	object	No	Upstream credential injection rules
`security`	object	No	Version, egress, filesystem, limits, and side-effect rules
`dedupe`	object	No	Idempotency replay or reject behavior
`audit`	object	Yes	Audit writer and gateway identity
`runtime`	object	No	Local or remote runtime evaluation settings

authn

Key	Type	Required	Description
`authn.allowUnauthenticated`	boolean	No	Allow missing bearer token. Default is `false`
`authn.oidc`	object	No	OIDC validation settings

`OIDCConfig`

Key	Type	Required	Description
`issuer`	string	Yes	OIDC issuer
`audience`	string	Yes	OIDC audience
`jwks_uri`	string	Yes	JWKS endpoint
`tenantClaim`	string	No	Tenant claim name. Default is `org`
`userClaim`	string	No	User claim name. Default is `email`
`rolesClaim`	string	No	Roles claim name. Default is `roles`
`subjectClaim`	string	No	Subject claim name. Default is `sub`
`clientIdClaim`	string	No	Service principal claim name

entitlements

`Entitlements`

Key	Type	Required	Description
`default_plan`	string	Yes	Plan name for tenants without explicit overrides
`plans`	`Record<string, PlanConfig>`	Yes	Plan-level limits
`tenants`	`Record<string, TenantEntitlement>`	Yes	Tenant-specific entitlements

`TenantEntitlement`

Key	Type	Required	Description
`plan`	string	Yes	Plan name
`allowlist`	string[]	Yes	Allowed tools
`denylist`	string[]	No	Explicitly denied tools
`per_tool`	object	No	Per-tool limits
`users`	object	No	Per-user overrides
`user_ids`	object	No	Per-subject overrides
`roles`	object	No	Per-role overrides
`agents`	object	No	Per-service-agent overrides
`agent_nodes`	object	No	Per-agent-node overrides

quotas

Key	Type	Required	Description
`quotas.adapter`	`QuotaAdapter`	Yes	Storage adapter for rate and usage limits

`QuotaAdapter`

Method	Signature	Description
`incrDaily`	`(tenant, tool, limit, now?) => Promise<{ count; resetAt }>`	Increment daily usage
`takeToken`	`(tenant, tool, ratePerSec, burst?, now?) => Promise<{ tokens; resetAt }>`	Token-bucket rate limiting

privacy

Key	Type	Required	Description
`privacy.redact_identities`	boolean	No	Redact identity data in gateway spans

enforcement

Key	Type	Required	Description
`enforcement.mode`	`"observe"` or `"enforce"`	No	Enforcement mode
`enforcement.deny_on`	string[]	No	Deny reasons
`enforcement.escalate_on`	string[]	No	Escalation reasons

brokers

brokers is keyed by upstream server name:

Key	Type	Required	Description
`brokers.<server>.type`	`"vendor_key_pool"`, `"oidc_on_behalf"`, or `"static"`	Yes	Broker type
`brokers.<server>.key_refs`	string[]	No	Key references
`brokers.<server>.inject.header`	string	Yes	Header name to inject
`brokers.<server>.inject.format`	`"raw"`, `"bearer"`, or `"template"`	Yes	Injection format

security

Key	Type	Required	Description
`security.allow_versions`	`Record<string, string[]>`	No	Allowed versions per server
`security.egress_allowlist`	string[]	No	Allowed host patterns
`security.fs_allowlist`	string[]	No	Allowed path patterns
`security.limits`	object	No	Payload or duration limits
`security.side_effects`	object	No	Side-effect rules

`security.limits`

Key	Type	Required	Description
`security.limits.max_payload_kb`	number	No	Max payload size
`security.limits.max_duration_ms`	number	No	Max duration

`security.side_effects`

Key	Type	Required	Description
`security.side_effects.require_idempotency_key`	boolean	No	Require idempotency for side effects
`security.side_effects.approve_high_risk`	boolean	No	Enable escalation creation
`security.side_effects.human_escalation`	object	No	Snake-case approval strategy config
`security.side_effects.humanEscalation`	object	No	Camel-case approval strategy config

`security.side_effects.human_escalation / humanEscalation`

Key	Type	Required	Description
`approval_strategy`	`auto_allow`, `single_approver`, or `human_quorum`	No	Approval strategy
`timeout_action`	`auto_approve` or `auto_reject`	No	Action when escalation expires
`min_approvals`	number	No	Approval quorum
`min_rejections`	number	No	Rejection quorum
`required_roles`	string[]	No	Roles that must appear on approval votes
`veto_roles`	string[]	No	Roles that can force rejection
`approval_set_id`	string	No	Explicit reviewer set override

dedupe

Key	Type	Required	Description
`dedupe.enabled`	boolean	No	Enable dedupe
`dedupe.duplicatePolicy`	`"replay"` or `"reject"`	No	Behavior for duplicates
`dedupe.ttlSec`	number	No	Cache window in seconds
`dedupe.namespace`	string	No	Key prefix
`dedupe.redisUrl`	string	No	Redis URL

audit

Key	Type	Required	Description
`audit.append`	function	Yes	`(env) => Promise<void>` writer
`audit.gatewayName`	string	Yes	Gateway name
`audit.gatewayVersion`	string	Yes	Gateway version
`audit.clientName`	string	No	Optional client name

This page keeps audit at the integration level. The full envelope shape is intentionally left out of the main reference.

ap2

Key	Type	Required	Description
`ap2.enabled`	boolean	No	Enable AP2 checks
`ap2.requireForSideEffects`	boolean	No	Require AP2 for side effects
`ap2.headers.intent`	string	No	Header name for intent mandate
`ap2.headers.cart`	string	No	Header name for cart mandate
`ap2.headers.bundle`	string	No	Header name for bundle
`ap2.trust.didMethods`	string[]	No	Allowed DID methods
`ap2.trust.issuersAllowlist`	string[]	No	Allowed issuers
`ap2.trust.clockSkewSec`	number	No	Clock skew seconds
`ap2.tools.allow`	string[]	No	Allowed tools
`ap2.mode`	`""`, `"observe"`, `"partial"`, or `"full"`	No	AP2 enforcement mode
`ap2.policyWebhookUrl`	string	No	Policy webhook URL

runtime

`runtime.enforcement`

Key	Type	Required	Description
`runtime.enforcement.mode`	`"local"` or `"remote"`	No	Runtime adapter mode
`runtime.enforcement.protocolVersion`	string	No	Runtime protocol version
`runtime.enforcement.failureMode`	`"local"`, `"allow"`, or `"deny"`	No	Fallback behavior when remote runtime fails
`runtime.enforcement.remote.endpoint`	string	No	Remote evaluate endpoint
`runtime.enforcement.remote.timeoutMs`	number	No	Remote timeout
`runtime.enforcement.remote.maxRetries`	number	No	Retry count
`runtime.enforcement.remote.retryBackoffMs`	number	No	Retry backoff base
`runtime.enforcement.remote.headers`	object	No	Extra request headers
`runtime.enforcement.remote.apiKey`	string	No	Remote runtime API key

Getting Started

In-Device Security

Network Boundary Security

Policy & Compliance

Operations

Advanced

Reference

Gateway Config Reference

Minimal shape

`startGatewayServer(...)` options

Policy YAML overrides

`MiddlewareConfig`

authn

`OIDCConfig`

entitlements

`Entitlements`

`TenantEntitlement`

quotas

`QuotaAdapter`

privacy

enforcement

brokers

security

`security.limits`

`security.side_effects`

`security.side_effects.human_escalation / humanEscalation`

dedupe

audit

ap2

runtime

`runtime.enforcement`

​Minimal shape

​startGatewayServer(...) options

​Policy YAML overrides

​MiddlewareConfig

​authn

​OIDCConfig

​entitlements

​Entitlements

​TenantEntitlement

​quotas

​QuotaAdapter

​privacy

​enforcement

​brokers

​security

​security.limits

​security.side_effects

​security.side_effects.human_escalation / humanEscalation

​dedupe

​audit

​ap2

​runtime

​runtime.enforcement

Minimal shape

`startGatewayServer(...)` options

Policy YAML overrides

`MiddlewareConfig`

authn

`OIDCConfig`

entitlements

`Entitlements`

`TenantEntitlement`

quotas

`QuotaAdapter`

privacy

enforcement

brokers

security

`security.limits`

`security.side_effects`

`security.side_effects.human_escalation / humanEscalation`

dedupe

audit

ap2

runtime

`runtime.enforcement`