kai/web-terminal
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(deploy): device client-CA + issuance/revocation + frp/nginx mTLS templates (V2/V7)

Browse Source 
Committable VPS artifacts for the native reverse-tunnel (no live-ops, no secrets):
- gen-device-ca.sh: EC P-256 self-signed device CA (CA:TRUE pathlen:0, keyCertSign+cRLSign),
  openssl ca db + empty CRL, idempotent, --kind frp-client scaffolds the control-channel CA.
- issue-device-cert.sh: P-256 leaf, EKU=clientAuth only, 825d, emits .p12 (-legacy) + .pem/.key/.fullchain,
  copy_extensions=none prevents CSR-injected serverAuth/CA:TRUE; CN traversal guard.
- revoke-device.sh: openssl ca revoke -> regenerate crl.pem (revocation enforced via -crl_check).
- frp/{frps.toml.example,frpc.example.toml}: control-channel mTLS+token, disableCustomTLSFirstByte=true.
- nginx/frp-mtls.conf: :8470 TLS-term, ssl_verify_client on + device-CA + ssl_crl, WS-upgrade proxy to :7080.
- nginx/stream-sni-additions.md: the two additive SNI map lines (merge-only, coexistence-safe).
Verified: gen->issue->openssl verify->revoke->CRL chain green in a tmp dir (OpenSSL 3.0.18).
This commit is contained in:
Yaojia Wang
2026-07-07 09:42:12 +02:00
parent 6b8269c1c1
commit 5337281e85
8 changed files with 573 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
deploy/nginx/frp-mtls.conf Normal file
View File

@@ -0,0 +1,44 @@
# frp-mtls.conf — nginx :8470 TLS-termination + device-CA mTLS + WS-upgrade proxy to frps vhost.
#
# Native mTLS tunnel · V4. Install target: /etc/nginx/conf.d/frp-mtls.conf
# This is a conf.d snippet (safe to ADD — it only introduces a NEW loopback :8470 server + one map;
# it does NOT touch the existing stream :443 map, which is edited separately per stream-sni-additions.md).
#
# Data-path security gate: `ssl_verify_client on` against the DEVICE CA (with CRL) is the ONE gate for
# the tunnelled base app. `on`, NEVER `optional` (PLAN P-D / R2). The public :8470 SERVER cert is the
# LE wildcard (V3); the CLIENT trust anchor is the private device CA (V2) — two different chains.
#
# nginx 1.24: there is NO standalone `http2` directive here and NO `http2 off;` — HTTP/2 is off by
# default on this listen and `http2 off;` is INVALID on 1.24 (would fail `nginx -t`, PLAN R7).
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 127.0.0.1:8470 ssl;
server_name ~^.+\.terminal\.yaojia\.wang$;
ssl_certificate /etc/relay/frp-tls/fullchain.pem; # LE wildcard *.terminal.yaojia.wang (V3)
ssl_certificate_key /etc/relay/frp-tls/privkey.pem;
# --- the data-path security gate ---
ssl_verify_client on; # ON, never `optional`
ssl_client_certificate /etc/relay/device-ca/device-ca.cert.pem;
ssl_verify_depth 1;
ssl_crl /etc/relay/device-ca/crl.pem; # revocation from day one (V2)
location / {
proxy_pass http://127.0.0.1:7080; # frps vhost — routes by Host → subdomain
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Origin https://$host; # needed for Android/curl; harmless for iOS
proxy_set_header X-Client-Cert-CN $ssl_client_s_dn;
proxy_buffering off;
proxy_read_timeout 3600s; # prevents idle-WS proxy kill (default 60s, R6)
proxy_send_timeout 3600s;
}
}

45
deploy/nginx/stream-sni-additions.md Normal file
View File

@@ -0,0 +1,45 @@
# Stream SNI additions (Native mTLS tunnel · V5)
Two SNI routes must be **merged into the existing** `stream { map $ssl_preread_server_name … }`
block on the VPS (`/etc/nginx/stream-relay.conf`). They add the frp control channel and the
`*.terminal` data path to the single shared `:443` `ssl_preread` listener.
> **This is a MERGE, not a file to ship.** Do **not** drop a full stream conf here — that would
> clobber the live one. Only the two `map` body lines below are new.
## The two additive lines
Add these **inside the existing `map` body** (exact match wins over wildcard, so order is not
load-bearing, but keep the exact `frp.terminal` line above the `*.terminal` wildcard for clarity):
```nginx
frp.terminal.yaojia.wang 127.0.0.1:7000; # frps control channel (TLS passthrough)
*.terminal.yaojia.wang 127.0.0.1:8470; # nginx :8470 TLS-term + device-CA mTLS (frp-mtls.conf)
```
## Coexistence warning (do NOT retype the existing lines)
The existing `map` body already contains — and MUST be preserved **verbatim**:
```nginx
# ... existing hostnames directive ...
*.term.yaojia.wang 127.0.0.1:8443; # E2E browser relay — DO NOT RETYPE / REORDER
default 127.0.0.1:10443; # xray Reality — DO NOT RETYPE / REORDER
```
- `*.term.yaojia.wang` (browser relay) and `*.terminal.yaojia.wang` (this tunnel) are **different
parent labels** — `term` vs `terminal`. `ssl_preread` matches the full SNI, so they never collide.
- Re-type nothing you did not author. Capture the current body first
(`nginx -T | sed -n '/map \$ssl_preread_server_name/,/}/p'`), then append only the two lines above.
## Deploy gate
```bash
cp /etc/nginx/stream-relay.conf{,.bak.$(date +%s)} # snapshot first
# ...edit: append the two lines into the map body...
nginx -t && systemctl reload nginx # NEVER reload on a failed -t
```
After reload, run the 4-zone SNI oracle (`openssl s_client -servername …` for
`frp.terminal` / `<name>.terminal` / `<name>.term` / default) to confirm all four routes still
resolve to the right backend (PLAN V5 / M1 #7).