explorer-monorepo/deployment/ACCESS_EDGE_ENFORCEMENT_RUNBOOK.md

Explorer Access Edge Enforcement Runbook

Operational runbook for enforcing explorer-issued API keys at the RPC edge for Chain 138 service lanes such as:

• alltra-rpc on VMID 2102
• thirdweb-rpc on VMID 2103
• approval-gated core-rpc on VMID 2101

This complements the explorer access console and backend access APIs. The explorer can already issue, rotate, revoke, and validate keys; this runbook covers how to enforce those keys on nginx-facing RPC endpoints.

Preconditions

• Explorer config/API backend is running on VMID 5000 and reachable at 127.0.0.1:8081
• ACCESS_INTERNAL_SECRET is configured on the explorer API service
• Users and subscriptions are already managed through /access
• The target RPC lane is behind nginx or another proxy that can make a subrequest to the explorer API

Canonical validator endpoint

• Internal: http://127.0.0.1:8081/api/v1/access/internal/validate-key
• Public-prefixed equivalent through explorer nginx: https://explorer.d-bis.org/explorer-api/v1/access/internal/validate-key

Validator modes

• GET for nginx auth_request
  • supply X-API-Key or Authorization: Bearer ...
  • supply X-Access-Internal-Secret
  • returns 200 on success or 401 on rejection
  • includes headers such as:
    • X-Validated-Product
    • X-Validated-Tier
    • X-Validated-Scopes
    • X-Quota-Remaining
• POST for richer internal clients
  • JSON body with api_key, method_name, request_count, last_ip
  • returns JSON payload with validated key metadata

Canonical nginx pattern

Use common/nginx-rpc-api-key-gate.conf as the starting template. For lane-specific rendered configs, use ../scripts/render-rpc-access-gate-nginx.sh.

The important behavior is:

1. nginx receives user traffic
2. nginx subrequests /__access_validate_rpc
3. that subrequest calls the explorer validator with:
   • the client API key
   • the shared internal secret
   • request method and source IP
4. only validated requests are proxied to the protected RPC upstream

Render a product-specific config

Instead of editing the template manually, render a concrete config for the target lane:

bash explorer-monorepo/scripts/render-rpc-access-gate-nginx.sh \
  --product thirdweb-rpc \
  --server-name thirdweb-rpc.example.org \
  --internal-secret "$ACCESS_INTERNAL_SECRET" \
  --output /etc/nginx/conf.d/thirdweb-rpc-gated.conf

Example for alltra-rpc:

bash explorer-monorepo/scripts/render-rpc-access-gate-nginx.sh \
  --product alltra-rpc \
  --server-name alltra-rpc.example.org \
  --internal-secret "$ACCESS_INTERNAL_SECRET" \
  --output /etc/nginx/conf.d/alltra-rpc-gated.conf

Example for core-rpc with an explicit upstream override:

bash explorer-monorepo/scripts/render-rpc-access-gate-nginx.sh \
  --product core-rpc \
  --server-name rpc-http-prv.d-bis.org \
  --internal-secret "$ACCESS_INTERNAL_SECRET" \
  --upstream http://192.168.11.211:8545 \
  --output /etc/nginx/conf.d/core-rpc-gated.conf

After rendering, verify syntax before reload:

nginx -t
systemctl reload nginx

Recommended product mapping

Product	Suggested public host	Upstream target
core-rpc	rpc-http-prv.d-bis.org	http://192.168.11.211:8545
alltra-rpc	partner/internal hostname	http://192.168.11.212:8545
thirdweb-rpc	managed SaaS/internal hostname	http://192.168.11.217:8545

For core-rpc, keep manual approval enabled and consider IP allowlists in addition to API keys.

Safe remote install workflow

For an operator-friendly rollout, use the dry-run-first installer:

bash explorer-monorepo/scripts/install-rpc-access-gate-nginx-via-ssh.sh \
  --product thirdweb-rpc \
  --server-name thirdweb-rpc.example.org \
  --ssh-host root@192.168.11.217 \
  --internal-secret "$ACCESS_INTERNAL_SECRET"

That prints the rendered config and planned remote target without mutating anything.

Apply only after review:

bash explorer-monorepo/scripts/install-rpc-access-gate-nginx-via-ssh.sh \
  --product thirdweb-rpc \
  --server-name thirdweb-rpc.example.org \
  --ssh-host root@192.168.11.217 \
  --internal-secret "$ACCESS_INTERNAL_SECRET" \
  --apply

By default the installer copies the config, runs nginx -t, and only then reloads nginx.

Explorer API service env

At minimum, set:

ACCESS_ADMIN_EMAILS=ops@example.org,platform@example.org
ACCESS_INTERNAL_SECRET=replace-with-long-random-secret

Verification

Use the dedicated verifier:

bash explorer-monorepo/scripts/verify-explorer-access-edge-hook.sh \
  --base-url https://explorer.d-bis.org \
  --internal-secret "$ACCESS_INTERNAL_SECRET"

To test a real key:

bash explorer-monorepo/scripts/verify-explorer-access-edge-hook.sh \
  --base-url https://explorer.d-bis.org \
  --internal-secret "$ACCESS_INTERNAL_SECRET" \
  --api-key "sk_live_example"

Rollout order

1. Deploy explorer config/API backend so the validator endpoint is live
2. Confirm ACCESS_INTERNAL_SECRET is loaded in the service env
3. Apply nginx config for one protected lane first, usually thirdweb-rpc
4. Verify validation responses and upstream reachability
5. Expand to alltra-rpc
6. Apply stricter controls for core-rpc only after admin approval flow is tested

Honest limits

• This repo now provides the validator hook, operator docs, and example edge config
• Actual enforcement still depends on where the RPC traffic is terminated
• Billing settlement, Stripe, or x402 monetization is a separate commercial layer