> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sec0.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Config Reference

> Developer-facing configuration for sec0-sdk/gateway and startGatewayServer.

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

```typescript theme={null}
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                      |