Gateway

@bolyra/gateway

Bolyra MCP Auth Gateway -- standalone reverse proxy that verifies agent ZKP credentials before forwarding requests to upstream MCP servers.

Put @bolyra/gateway in front of your MCP server; it verifies agent authority, prevents replay, enforces delegated scopes, and gives you signed audit logs for every tool call.

Quickstart

# Install

npm install @bolyra/gateway

Create a config file (optional)

cat > gateway.yaml << 'EOF' target: http://localhost:3000/mcp port: 4100 devMode: true EOF

Run

npx @bolyra/gateway --config ./gateway.yaml

Or run directly with CLI flags:

npx @bolyra/gateway --target http://localhost:3000/mcp --dev --port 4100

How It Works

                  +----------------------------------+

| @bolyra/gateway | Agent -------->| |--------> Upstream MCP Server (with proof | 1. Parse Authorization header | (unmodified) bundle) | 2. verifyBundle() from @bolyra/mcp| | 3. checkToolPolicy() | | 4. Nonce replay check | | 5. Emit signed receipt | | 6. Proxy request + X-Bolyra-* hdrs| | | | Config: gateway.yaml | | Receipts: ./receipts/ or stdout | +----------------------------------+

Request routing:

1. GET /healthz -- returns gateway status (intercepted, not proxied)
2. JSON-RPC method != tools/call -- forwarded to upstream without auth
3. JSON-RPC method == tools/call -- auth verified, then forwarded if authorized

CLI Reference

npx @bolyra/gateway [options]

Options: --target Upstream MCP server URL (required unless in config) --port Gateway listen port (default: 4100) --config Path to gateway config file (default: ./gateway.yaml) --dev Enable Bolyra Core mode (classical checks: tool policy, nonce replay, signed receipts, credential binding against registered credentials; ZK proof verification off. Without registered credentials, permission claims are self-asserted — see Credential Binding below) --credentials Credentials file (YAML/JSON map: commitment -> { permissionBitmask, expiryTimestamp? }); overrides the config's credentials section --receipt-dir Directory for receipt JSON files (default: ./receipts/) --receipt-stdout Write receipts to stdout (NDJSON) --no-receipts Disable receipt generation --network Bolyra network (default: base-sepolia) --help Show help --version Show version

CLI flags override config file values.

Config File Reference

# gateway.yaml

target: http://localhost:3000/mcp port: 4100 network: base-sepolia

Bolyra Core mode: classical checks only, ZK proof verification skipped

devMode: false

Registered credentials (see "Credential Binding" below).

Core mode (devMode: true): claims are checked against this registry —

unknown commitments, forged masks, and expired credentials are denied.

Production mode: this map becomes the resolveCredential source for

verifyBundle's Poseidon3 scopeCommitment binding (expiryTimestamp

required per entry).

type: registry (on-chain resolution) is not supported by the packaged

gateway yet and fails validation — use the library resolveCredential

option for custom resolution.

credentials: type: static map: "48201394857102938471029384": # credential commitment (decimal) permissionBitmask: 3 # READ_DATA | WRITE_DATA expiryTimestamp: "1893456000" # unix seconds; optional in Core mode

Per-tool policies

tools: write_file: requireBitmask: 2 # WRITE_DATA (0b10) delete_file: requireBitmask: 6 # WRITE_DATA + FINANCIAL_SMALL (0b110) maxChainDepth: 0 # Direct credentials only transfer_funds: requireBitmask: 28 # FINANCIAL_* (0b11100) minScore: 90

Nonce replay protection

nonce: store: memory # "memory" (default) or "redis" maxProofAge: 300 # seconds

Redis config (required when store: redis)

redis:

url: ${REDIS_URL} # required

keyPrefix: "bolyra:nonce:" # optional, default shown

connectTimeout: 5000 # optional, ms

Receipt signing — every allow/deny decision is ES256K-signed (see

"Signed Receipts" below). Without privateKey an ephemeral key is

generated at startup; set it for a stable, pinnable signer address.

receipts: enabled: true issuer: "my-gateway" keyId: "k1" privateKey: "${BOLYRA_RECEIPT_KEY}" # 32-byte hex secp256k1 key, env var substitution output: file # "file", "stdout", or "webhook" dir: ./receipts/

Health check

health: enabled: true path: /healthz

Optional HMAC signing for X-Bolyra-* headers

hmac:

secret: "hex-encoded-shared-secret"

Environment variables are substituted in string values using ${VAR_NAME} syntax.

Library API

For embedding the gateway middleware in your own server:

import {

createGatewayMiddleware, createGatewayProxy, loadConfig, injectBolyraHeaders, computeHmac, verifyHmac, createReceiptWriter, createHealthHandler, } from '@bolyra/gateway'; import type { GatewayConfig, GatewayMiddlewareOptions, GatewayRequest, } from '@bolyra/gateway';

// Option 1: Full proxy server const config = loadConfig({ target: 'http://localhost:3000/mcp', dev: true }); const server = createGatewayProxy({ config }); server.listen(4100);

// Option 2: Just the middleware (for custom servers) const middleware = createGatewayMiddleware({ config }); // Use in your request handler: // const authorized = await middleware(req, res, toolName);

Exports

Redis Nonce Store (v0.2.0+)

For multi-instance deployments, use Redis for shared nonce replay protection:

# gateway.yaml

nonce: store: redis maxProofAge: 300 redis: url: ${REDIS_URL} keyPrefix: "bolyra:nonce:" # optional

Library usage:

import { createGatewayMiddleware, RedisNonceStore } from '@bolyra/gateway';

const store = new RedisNonceStore({ url: 'redis://localhost:6379' }); const middleware = createGatewayMiddleware({ config, nonceStore: store });

// Graceful shutdown process.on('SIGTERM', () => store.close());

Fail-closed behavior: If Redis is unreachable, the gateway returns HTTP 500, never passes requests through. Monitor Redis availability as a critical dependency.

X-Bolyra-* Headers

When a request passes verification, the gateway injects these headers into the proxied request:

The upstream server can use these headers for logging/auditing without importing Bolyra.

Signed Receipts (v0.3.0+)

Every tools/call decision — allow and deny, dev mode and production — produces an ES256K-signed receipt (SignedReceipt from @bolyra/receipts: secp256k1 + keccak256, Ethereum-compatible recovery). This includes rejections with no usable proof bundle at all: a missing or malformed Authorization header still leaves a signed anonymous deny receipt, so the audit trail has no unsigned gaps.

Each receipt carries the verdict (decision.allowed), a human-readable reasonCode (which tool, which permissions were required vs. held), the agent DID when known, score, permission bitmask, delegation chain depth, hashes of the presented proof material, and the decision timestamp. Any edit to a receipt breaks its signature.

Signing key resolution:

1. receiptSigner option (library embedders)
2. receipts.privateKey from the config (recommended for production)
3. Otherwise an ephemeral key is generated at startup. Receipts remain independently verifiable — the signer address is recoverable from every signature — but the address rotates on restart. The CLI prints the signer address in the startup banner and, in file output mode, persists it to {receipt-dir}/signer.json so auditors can pin the trust anchor.

Independent verification needs only the receipt (plus, optionally, the pinned signer address) — no gateway, no database:

import { verifyReceipt } from '@bolyra/receipts';

const receipt = JSON.parse(fs.readFileSync('receipts/2026-07-10/....json', 'utf8')); verifyReceipt(receipt); // true — signature + payload hash check verifyReceipt(receipt, pinnedSigner); // true — also pins the signer address

Hash-Chained Receipts (v0.5.0+)

Signatures make each receipt tamper-evident; hash-chaining makes the receipt stream tamper-evident. Every receipt the gateway signs carries chain: { seq, prevReceiptHash } inside the signed payload (seq is 0-based per gateway process; the first receipt links to the 32-zero-byte genesis sentinel) plus a top-level receiptHash that the next receipt links to. Deleting, reordering, or inserting receipts in a collected log breaks chain verification even though every remaining signature stays individually valid:

# stdout mode: collect NDJSON to a file, verify signatures + chain

bolyra receipt verify-chain receipts.ndjson --signer 0xPinnedSigner

Notes for auditors:

• One chain per gateway process. A restart starts a new chain at seq 0 — rotate the collected log per process run (or verify each run's segment separately); a mid-file restart is reported as chain-restart.
• File mode writes one JSON file per receipt; the chain fields still order and link them (concatenate in seq order to verify).
• Tail truncation is not detectable from the log alone. Chain verification proves nothing was deleted, reordered, or edited *within* the log, but a log cut after any receipt is still internally consistent. Pin the head ha