mc/mc-proxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Switch gRPC admin API to Unix socket only, add client package

Browse Source 
- Remove TCP listener support from gRPC server; Unix socket is now the
  only transport for the admin API (access controlled via filesystem
  permissions)
- Add standard gRPC health check service (grpc.health.v1.Health)
- Implement MCPROXY_* environment variable overrides for config
- Create client/mcproxy package with full API coverage and tests
- Update ARCHITECTURE.md and dev config (srv/mc-proxy.toml)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Kyle Isom
2026-03-19 07:48:11 -07:00
parent b25e1b0e79
commit f24fa2a2b0
9 changed files with 810 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
ARCHITECTURE.md
View File

@@ -177,8 +177,8 @@ gRPC admin API.
## gRPC Admin API
The admin API is optional (disabled if `[grpc]` is omitted from the config).
When enabled, it requires TLS and supports optional mTLS for client
authentication. TLS 1.3 is enforced. The API provides runtime management
It listens on a Unix domain socket for security — access is controlled via
filesystem permissions (0600, owner-only). The API provides runtime management
of routes and firewall rules without restarting the proxy.
### RPCs
@@ -192,6 +192,7 @@ of routes and firewall rules without restarting the proxy.
| `AddFirewallRule` | Add a firewall rule (write-through to DB) |
| `RemoveFirewallRule` | Remove a firewall rule (write-through to DB) |
| `GetStatus` | Return version, uptime, listener status, connection counts |
| `grpc.health.v1.Health` | Standard gRPC health check (Check, Watch) |
### Input Validation
@@ -205,13 +206,11 @@ The admin API validates all inputs before persisting:
### Security
The gRPC admin API has no MCIAS integration — mc-proxy is pre-auth
infrastructure. Access control relies on:
infrastructure. Access control relies on Unix socket filesystem permissions:
1. **Network binding**: bind to `127.0.0.1` (default) to restrict to local access.
2. **mTLS**: configure `client_ca` to require client certificates.
If the admin API is exposed on a non-loopback interface without mTLS,
any network client can modify routing and firewall rules.
- Socket is created with mode `0600` (read/write for owner only)
- Only processes running as the same user can connect
- No network exposure — the API is not accessible over TCP
---
@@ -252,15 +251,9 @@ addr = ":9443"
backend = "127.0.0.1:28443"
# gRPC admin API. Optional — omit or leave addr empty to disable.
# If enabled, tls_cert and tls_key are required (TLS 1.3 only).
# client_ca enables mTLS and is strongly recommended for non-loopback addresses.
# ca_cert is used by the `status` CLI command to verify the server certificate.
# Listens on a Unix socket; access controlled via filesystem permissions.
[grpc]
addr = "127.0.0.1:9090"
tls_cert = "/srv/mc-proxy/certs/cert.pem"
tls_key = "/srv/mc-proxy/certs/key.pem"
client_ca = "/srv/mc-proxy/certs/ca.pem"
ca_cert = "/srv/mc-proxy/certs/ca.pem"
addr = "/var/run/mc-proxy.sock"
# Firewall. Global blocklist, evaluated before routing. Default allow.
[firewall]
@@ -347,14 +340,14 @@ CREATE TABLE firewall_rules (
/srv/mc-proxy/
├── mc-proxy.toml Configuration
├── mc-proxy.db SQLite database
├── certs/ TLS certificates (for gRPC admin API)
├── mc-proxy.sock Unix socket for gRPC admin API
├── GeoLite2-Country.mmdb GeoIP database (if using country blocks)
└── backups/ Database snapshots
```
mc-proxy does not terminate TLS on the proxy listeners, so no proxy
certificates are needed. The `certs/` directory is for the gRPC admin
API's TLS and optional mTLS keypair.
mc-proxy does not terminate TLS on any listener. The proxy listeners pass
through raw TLS streams, and the gRPC admin API uses a Unix socket
(filesystem permissions for access control).
---
@@ -447,5 +440,4 @@ Items are listed roughly in priority order:
| **User-agent blocking** | Block connections based on user-agent string (requires L7 mode). |
| **Connection rate limiting** | Per-source-IP rate limits to mitigate connection floods. |
| **Per-listener connection limits** | Cap maximum concurrent connections per listener. |
| **Health check endpoint** | Lightweight TCP or HTTP health check for load balancers and monitoring. |
| **Metrics** | Prometheus-compatible metrics: connections per listener, firewall blocks by rule, backend dial latency, active connections. |