authoravatarclover caruso<git@paperclover.net>2026-10-17 13:05:54-07:00
committeravatarclover caruso<git@paperclover.net>2026-10-21 02:52:29-07:00
logbc5fc51efa42a982c642c7aa79b021613e8e4e4a
tree8fb8321ecd8aeba45b263fa47a6b14f7dc38679d
parenta4c36c6d8f5893c91e75def1bc06dad8917475bc
signature Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU

Host CLIProxyAPI behind Snow and an independent client key

Pin the runtime and management panel, persist provider sign-ins and native settings, and isolate management from the public API. Enforce the infra key at the gateway, deny callback URLs before native request logging, and distinguish plain host aliases from SSO hosts. Assisted-by: gpt-6.1-sol

11 files changed, 696 insertions(+), 14 deletions(-)

service/cliproxy/Dockerfile created+3
...@@ -0,0 +1,3 @@
1FROM docker.io/eceasy/cli-proxy-api@sha256:c08d02fbd94927708721afd059bff9ff36a04d9cedb4d69f2c2671aba8239031 AS proxy
2FROM docker.io/library/nginx@sha256:17ae566734b63632e543c907ba74757e0c1a25d812ab9f10a07a6bed98dd199c
3COPY --from=proxy /CLIProxyAPI/CLIProxyAPI /CLIProxyAPI/CLIProxyAPI
service/cliproxy/nginx.conf created+90
...@@ -0,0 +1,90 @@
1worker_processes 1;
2pid /tmp/nginx.pid;
3error_log /dev/stderr crit;
4events { worker_connections 512; }
5http {
6 access_log off;
7 server_tokens off;
8 absolute_redirect off;
9 map_hash_bucket_size 128;
10 server_names_hash_bucket_size 128;
11 client_body_temp_path /tmp/client;
12 proxy_temp_path /tmp/proxy;
13 fastcgi_temp_path /tmp/fastcgi;
14 uwsgi_temp_path /tmp/uwsgi;
15 scgi_temp_path /tmp/scgi;
16 map $http_upgrade $connection_upgrade { default upgrade; '' close; }
17 map "$request_method:$uri" $client_route {
18 default 0;
19 ~^GET:/v1/models(?:/[^/]+)?$ 1;
20 ~^POST:/v1/(?:chat/completions|completions|messages(?:/count_tokens)?|responses(?:/compact)?|alpha/search)$ 1;
21 "GET:/v1/responses" 1;
22 ~^POST:/backend-api/codex/(?:responses(?:/compact)?|alpha/search)$ 1;
23 "GET:/backend-api/codex/responses" 1;
24 }
25 map "$request_method:$uri" $browser_oauth_callback {
26 default 0;
27 ~^(?:GET|HEAD):/(?:v0/management/oauth-callback|v8/management/oauth/callback|(?:anthropic|codex|antigravity|devin)/callback|callback)/?$ 1;
28 }
29 {{ with nomadVar "NOMAD_VARIABLE" }}
30 map $http_authorization $bearer_key { default 0; "Bearer {{ .api_key.Value }}" 1; }
31 map $http_x_api_key $claude_key { default 0; "{{ .api_key.Value }}" 1; }
32 map $client_key $upstream_authorization { default ""; 1 "Bearer {{ .api_key.Value }}"; }
33 {{ end }}
34 map "$bearer_key:$claude_key" $client_key { default 1; "0:0" 0; }
35 upstream cliproxy_backend {
36 server 127.0.0.1:8317;
37 }
38 server {
39 listen 8080 default_server;
40 server_name _;
41 location = /healthz { proxy_pass http://cliproxy_backend; }
42 location / { return 404; }
43 }
44 server {
45 listen 8080;
46 server_name ADMIN_HOST;
47 client_max_body_size 32m;
48 location = / { return 302 /management.html; }
49 location / {
50 if ($browser_oauth_callback = 1) { return 404; }
51 if ($arg_code != "") { return 404; }
52 proxy_pass http://cliproxy_backend;
53 proxy_http_version 1.1;
54 proxy_set_header Host $host;
55 proxy_buffering off;
56 proxy_read_timeout 3600s;
57 }
58 }
59 server {
60 listen 8080;
61 server_name API_HOST;
62 client_max_body_size 32m;
63 location = /healthz { proxy_pass http://cliproxy_backend; }
64 location = / { return 404; }
65 location / {
66 if ($client_route = 0) { return 404; }
67 if ($client_key = 0) { return 401; }
68 if ($arg_key != "") { return 400; }
69 if ($arg_auth_token != "") { return 400; }
70 proxy_pass http://cliproxy_backend$uri$is_args$args;
71 proxy_http_version 1.1;
72 proxy_set_header Host $host;
73 proxy_set_header Upgrade $http_upgrade;
74 proxy_set_header Connection $connection_upgrade;
75 proxy_set_header Cookie "";
76 proxy_set_header Authorization $upstream_authorization;
77 proxy_set_header X-Api-Key "";
78 proxy_set_header X-Goog-Api-Key "";
79 proxy_set_header X-Management-Key "";
80 proxy_set_header X-Forwarded-For "";
81 proxy_set_header X-Forwarded-Host "";
82 proxy_set_header X-Forwarded-Proto "";
83 proxy_buffering off;
84 proxy_request_buffering off;
85 proxy_cache off;
86 proxy_read_timeout 3600s;
87 proxy_send_timeout 3600s;
88 }
89 }
90}
service/cliproxy/prepare.py created+51
...@@ -0,0 +1,51 @@
1#!/usr/bin/env python3
2import hashlib
3import json
4import os
5from pathlib import Path
6import stat
7import sys
8import tempfile
9import urllib.request
10
11
12PANEL_URL = "https://github.com/router-for-me/Cli-Proxy-API-Management-Center/releases/download/v1.26.5/management.html"
13PANEL_SHA256 = "57558cd023475674634a114824b014d3e5ac161f6f3791e3d86b6adab962a700"
14PANEL_SIZE = 3312180
15
16
17def prepare(data):
18 root = Path(data["hostRoot"]) / "data"
19 static = root / "static"
20 panel = static / "management.html"
21 if root.is_symlink() or static.is_symlink() or panel.is_symlink():
22 raise ValueError("CLIProxyAPI panel paths must not be symbolic links")
23 static.mkdir(parents=True, exist_ok=True)
24 if panel.exists():
25 metadata = panel.stat()
26 if not stat.S_ISREG(metadata.st_mode):
27 raise ValueError("CLIProxyAPI panel must be a regular file")
28 if metadata.st_size == PANEL_SIZE and hashlib.sha256(panel.read_bytes()).hexdigest() == PANEL_SHA256:
29 panel.chmod(0o444)
30 return
31 with urllib.request.urlopen(PANEL_URL, timeout=60) as response:
32 contents = response.read(PANEL_SIZE + 1)
33 if len(contents) != PANEL_SIZE or hashlib.sha256(contents).hexdigest() != PANEL_SHA256:
34 raise ValueError("CLIProxyAPI management panel failed checksum verification")
35 with tempfile.NamedTemporaryFile(dir=static, prefix=".panel-", delete=False) as file:
36 pending = Path(file.name)
37 try:
38 file.write(contents)
39 os.fchmod(file.fileno(), 0o444)
40 os.fchown(file.fileno(), data["uid"], data["uid"])
41 file.flush()
42 os.fsync(file.fileno())
43 pending.replace(panel)
44 finally:
45 pending.unlink(missing_ok=True)
46 os.chown(static, data["uid"], data["uid"])
47 static.chmod(0o755)
48
49
50if __name__ == "__main__":
51 prepare(json.load(sys.stdin))
service/cliproxy/service.pkl created+59
...@@ -0,0 +1,59 @@
1amends "../../config/Service.pkl"
2
3import "../../config/site.pkl" as site
4
5name = "CLIProxyAPI"
6tagline = "Codex and Claude API access"
7access = "infra-admin"
8stageIsolation = "fresh"
9prepare = "prepare.py"
10
11secrets {
12 ["api_key"] {}
13 ["management_key"] {}
14}
15
16container {
17 build = "."
18 entrypoint = "/bin/bash"
19 args { "/snowglobe/start.sh" }
20 readOnlyRoot = true
21 tmpfs { "/tmp:rw,nosuid,nodev,noexec,size=64m" }
22 http {
23 containerPort = 8080
24 subdomain = "cliproxy"
25 authRole = "infra-admin"
26 checkPath = "/healthz"
27 plainHostnames { "cliproxy-api.\(site.domain)" }
28 }
29 volumes {
30 ["/data"] {}
31 ["/data/static"] { readOnly = true }
32 ["/snowglobe/start.sh"] { config = "start.sh" }
33 }
34 env {
35 ["HOME"] = "/data"
36 ["WRITABLE_PATH"] = "/data"
37 ["MANAGEMENT_STATIC_PATH"] = "/data/static"
38 ["TZ"] = "America/Los_Angeles"
39 }
40 secretFiles {
41 ["/run/secrets/cliproxy-seed.json"] = """
42 {{ with nomadVar "nomad/jobs/\(module.id)" }}
43 {
44 "config-version": 8,
45 "server": {"host": "127.0.0.1", "port": 8317, "commercial-mode": true, "max-request-body-bytes": 33554432, "discovery": {"enabled": false}},
46 "access": {"api-keys": [{{ .api_key.Value | toJSON }}]},
47 "management": {"allow-remote": true, "secret-key": {{ .management_key.Value | toJSON }}, "disable-auto-update-panel": true},
48 "oauth": {"auth-dir": "/data/auth"},
49 "plugins": {"enabled": false, "dir": "/data/plugins"},
50 "observability": {"logs": {"debug": false, "logging-to-file": false, "request-log": false}, "usage": {"usage-statistics-enabled": false}, "pprof": {"enable": false}}
51 }
52 {{ end }}
53 """
54 ["/run/secrets/cliproxy-nginx.conf"] = read("nginx.conf").text
55 .replaceAll("NOMAD_VARIABLE", "nomad/jobs/\(module.id)")
56 .replaceAll("ADMIN_HOST", module.container.http.hostname!!)
57 .replaceAll("API_HOST", module.container.http.plainHostnames[0])
58 }
59}
service/cliproxy/start.sh created+29
...@@ -0,0 +1,29 @@
1#!/bin/bash
2set -eu
3umask 077
4
5if [ -L /data/config.yaml ] || { [ -e /data/config.yaml ] && [ ! -f /data/config.yaml ]; }; then
6 echo 'CLIProxyAPI configuration must be a regular file' >&2
7 exit 1
8fi
9if [ ! -e /data/config.yaml ]; then
10 pending=$(mktemp /data/.config.XXXXXX)
11 trap 'rm -f "$pending"' EXIT HUP INT TERM
12 cat /run/secrets/cliproxy-seed.json > "$pending"
13 ln "$pending" /data/config.yaml || test -f /data/config.yaml
14 rm -f "$pending"
15 trap - EXIT HUP INT TERM
16fi
17test -s /data/config.yaml
18chmod 600 /data/config.yaml
19mkdir -p /data/auth /data/plugins
20chmod 700 /data /data/auth /data/plugins
21/CLIProxyAPI/CLIProxyAPI --config /data/config.yaml &
22app=$!
23/usr/sbin/nginx -c /run/secrets/cliproxy-nginx.conf -g 'daemon off;' &
24gateway=$!
25trap 'kill "$app" "$gateway" 2>/dev/null || :; wait "$app" "$gateway" 2>/dev/null || :' EXIT
26trap 'exit 143' TERM
27trap 'exit 130' INT
28wait -n "$app" "$gateway"
29exit 1
service/forward-auth/service.pkl+1-1
...@@ -14,7 +14,7 @@ requirements {...@@ -14,7 +14,7 @@ requirements {
14 name = module.name14 name = module.name
15 redirectUris {15 redirectUris {
16 when (isPreview) { "https://\(module.id).\(site.domain)/snow.oauth2/callback" }16 when (isPreview) { "https://\(module.id).\(site.domain)/snow.oauth2/callback" }
17 when (!isPreview) { for (host in new Listing<String> { "music"; "seedbox"; "ddns"; "redis"; "pg"; "snr"; "rdr"; "logs"; "metrics"; "traces"; "jkt"; "openclaw" }) {17 when (!isPreview) { for (host in new Listing<String> { "music"; "seedbox"; "ddns"; "redis"; "pg"; "snr"; "rdr"; "logs"; "metrics"; "traces"; "jkt"; "openclaw"; "cliproxy" }) {
18 "https://\(host).\(site.domain)/snow.oauth2/callback"18 "https://\(host).\(site.domain)/snow.oauth2/callback"
19 } }19 } }
20 }20 }
tools/cliproxy-test.py created+355
...@@ -0,0 +1,355 @@
1#!/usr/bin/env python3
2import argparse
3import base64
4from contextlib import contextmanager
5import hashlib
6import http.client
7from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
8import importlib.util
9import io
10import json
11import os
12from pathlib import Path
13import re
14import socket
15import subprocess
16import tempfile
17import threading
18import time
19import unittest
20from unittest.mock import patch
21
22import snowglobe
23
24
25SERVICE = Path(__file__).resolve().parents[1] / "service/cliproxy"
26spec = importlib.util.spec_from_file_location("cliproxy_prepare", SERVICE / "prepare.py")
27prepare = importlib.util.module_from_spec(spec)
28spec.loader.exec_module(prepare)
29NGINX = None
30API_KEY = "a1" * 32
31MANAGEMENT_KEY = "b2" * 32
32ADMIN_HOST = "cliproxy-preview-12345678.paperclover.net"
33API_HOST = "cliproxy-preview-12345678-cliproxy-api.paperclover.net"
34
35
36class ServiceTests(unittest.TestCase):
37 @classmethod
38 def setUpClass(cls):
39 result = subprocess.run([os.environ.get("PKL", "pkl"), "eval", "-p", "uid=3150", "-p", "serviceId=cliproxy", "-p", "domain=paperclover.net", str(SERVICE / "service.pkl")], check=True, capture_output=True, text=True)
40 cls.data = json.loads(result.stdout)
41 cls.data.update(uid=3150, sourceId="cliproxy", inputs={})
42 cls.data.pop("requirements")
43 cls.data['containers']['app']['image'] = 'localhost/cliproxy:test'
44
45 def test_native_defaults_keep_credentials_private_and_requests_unlogged(self):
46 app = self.data["containers"]["app"]
47 seed = app["secretFiles"]["/run/secrets/cliproxy-seed.json"]
48 seed = re.sub(r"{{ with nomadVar [^}]+}}|{{ end }}", "", seed)
49 seed = seed.replace("{{ .api_key.Value | toJSON }}", json.dumps(API_KEY))
50 seed = seed.replace("{{ .management_key.Value | toJSON }}", json.dumps(MANAGEMENT_KEY))
51 config = json.loads(seed)
52 self.assertEqual(config["access"]["api-keys"], [API_KEY])
53 self.assertNotEqual(config["access"]["api-keys"][0], config["management"]["secret-key"])
54 self.assertTrue(config["server"]["commercial-mode"])
55 self.assertFalse(config["observability"]["logs"]["request-log"])
56 self.assertFalse(config["observability"]["pprof"]["enable"])
57 self.assertFalse(config["plugins"]["enabled"])
58 self.assertEqual(config["oauth"]["auth-dir"], "/data/auth")
59 self.assertTrue(config["management"]["disable-auto-update-panel"])
60 self.assertEqual(app["http"]["authRole"], "infra-admin")
61 self.assertEqual(app["http"]["plainHostnames"], ['cliproxy-api.paperclover.net'])
62 self.assertEqual(self.data["stageIsolation"], "fresh")
63
64 def test_rendered_job_has_only_nonroot_private_managed_storage(self):
65 rendered = snowglobe.render(self.data, {"cliproxy": self.data})
66 self.assertEqual(rendered.count('user = "3150:3150"'), 1)
67 self.assertEqual(rendered.count('readonly_rootfs = true'), 1)
68 self.assertEqual(rendered.count('perms = "0400"'), 2)
69 self.assertIn('secrets/cliproxy-seed.json:/run/secrets/cliproxy-seed.json:ro', rendered)
70 self.assertIn('secrets/cliproxy-nginx.conf:/run/secrets/cliproxy-nginx.conf:ro', rendered)
71 self.assertIn('server 127.0.0.1:8317;', rendered)
72 self.assertIn('/data/static:/data/static:ro', rendered)
73 self.assertNotIn("NOMAD_SERVICE", rendered)
74 self.assertNotIn("NOMAD_VARIABLE", rendered)
75 self.assertNotIn("/srv/clover", rendered)
76 self.assertNotIn("host_port", rendered)
77 self.assertNotIn('env = true', rendered)
78
79 def test_bootstrap_preserves_native_config_and_provider_credentials(self):
80 with tempfile.TemporaryDirectory() as temporary:
81 root = Path(temporary)
82 data = root / "data"
83 data.mkdir()
84 seed = root / "seed.json"
85 seed.write_text(json.dumps({"access": {"api-keys": [API_KEY]}}))
86 binary = root / "binary"
87 binary.write_text('#!/usr/bin/env python3\nimport pathlib,signal,sys\nassert sys.argv[1] == "--config" and pathlib.Path(sys.argv[2]).stat().st_size\nsignal.pause()\n')
88 binary.chmod(0o700)
89 gateway = root / "gateway"
90 gateway.write_text('#!/bin/sh\nexit 0\n')
91 gateway.chmod(0o700)
92 script = (SERVICE / "start.sh").read_text().replace('/run/secrets/cliproxy-seed.json', str(seed)).replace('/CLIProxyAPI/CLIProxyAPI', str(binary)).replace('/usr/sbin/nginx', str(gateway)).replace('/data', str(data))
93 self.assertEqual(subprocess.run(["bash", "-ec", script], timeout=5).returncode, 1)
94 config = data / "config.yaml"
95 self.assertEqual(json.loads(config.read_text())["access"]["api-keys"], [API_KEY])
96 self.assertEqual(config.stat().st_mode & 0o777, 0o600)
97 self.assertEqual((data / "auth").stat().st_mode & 0o777, 0o700)
98 config.write_text('access:\n api-keys: [edited-key]\nprovider-setting: retained\n')
99 credential = data / "auth/fixture.json"
100 credential.write_text('{"synthetic":true}')
101 seed.write_text('different seed')
102 self.assertEqual(subprocess.run(["bash", "-ec", script], timeout=5).returncode, 1)
103 self.assertIn('provider-setting: retained', config.read_text())
104 self.assertEqual(credential.read_text(), '{"synthetic":true}')
105 config.unlink()
106 config.symlink_to(seed)
107 result = subprocess.run(["bash", "-ec", script], capture_output=True)
108 self.assertNotEqual(result.returncode, 0)
109 self.assertEqual(seed.read_text(), 'different seed')
110
111 def test_panel_pin_rejects_bad_download_without_replacing_existing_file(self):
112 with tempfile.TemporaryDirectory() as temporary:
113 root = Path(temporary)
114 static = root / "data/static"
115 static.mkdir(parents=True)
116 panel = static / "management.html"
117 panel.write_bytes(b"previous panel")
118 with patch.object(prepare.urllib.request, "urlopen", return_value=io.BytesIO(b"bad panel")):
119 with self.assertRaisesRegex(ValueError, "checksum"):
120 prepare.prepare({"hostRoot": str(root), "uid": os.getuid()})
121 self.assertEqual(panel.read_bytes(), b"previous panel")
122 panel.unlink()
123 panel.symlink_to(root / "outside")
124 with self.assertRaisesRegex(ValueError, "symbolic"):
125 prepare.prepare({"hostRoot": str(root), "uid": os.getuid()})
126
127 def test_panel_verified_existing_asset_never_contacts_release_feed(self):
128 with tempfile.TemporaryDirectory() as temporary:
129 root = Path(temporary)
130 static = root / "data/static"
131 static.mkdir(parents=True)
132 panel = static / "management.html"
133 contents = b"pinned synthetic panel"
134 panel.write_bytes(contents)
135 with patch.object(prepare, "PANEL_SIZE", len(contents)), patch.object(prepare, "PANEL_SHA256", hashlib.sha256(contents).hexdigest()), patch.object(prepare.urllib.request, "urlopen", side_effect=AssertionError("unexpected download")):
136 prepare.prepare({"hostRoot": str(root), "uid": os.getuid()})
137 self.assertEqual(panel.read_bytes(), contents)
138
139
140@unittest.skipUnless(NGINX, "pass --nginx to test the real gateway binary")
141class GatewayTests(unittest.TestCase):
142 def setUp(self):
143 self.temporary = tempfile.TemporaryDirectory(prefix="cliproxy-gateway-")
144 self.addCleanup(self.temporary.cleanup)
145 root = Path(self.temporary.name)
146 self.observed = []
147 self.secret_markers = [API_KEY]
148 observed = self.observed
149
150 class Backend(BaseHTTPRequestHandler):
151 protocol_version = "HTTP/1.1"
152
153 def do_GET(self):
154 self.respond()
155
156 def do_POST(self):
157 self.respond()
158
159 def respond(self):
160 observed.append((self.command, self.path, dict(self.headers), self.rfile.read(int(self.headers.get('Content-Length', '0')))))
161 if self.headers.get("Upgrade", "").lower() == "websocket":
162 accept = base64.b64encode(hashlib.sha1((self.headers['Sec-WebSocket-Key'] + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11').encode()).digest()).decode()
163 self.send_response(101)
164 self.send_header("Upgrade", "websocket")
165 self.send_header("Connection", "Upgrade")
166 self.send_header("Sec-WebSocket-Accept", accept)
167 self.end_headers()
168 header = self.rfile.read(2)
169 mask = self.rfile.read(4)
170 body = self.rfile.read(2)
171 if header != b'\x81\x82' or bytes(value ^ mask[index % 4] for index, value in enumerate(body)) != b'hi':
172 raise AssertionError('incorrect client WebSocket frame')
173 self.wfile.write(b'\x81\x02hi')
174 self.wfile.flush()
175 self.close_connection = True
176 return
177 if self.headers.get("X-Synthetic-Stream"):
178 self.send_response(200)
179 self.send_header("Content-Type", "text/event-stream")
180 self.send_header("Connection", "close")
181 self.end_headers()
182 self.wfile.write(b'data: first\n\n')
183 self.wfile.flush()
184 time.sleep(.5)
185 self.wfile.write(b'data: last\n\n')
186 self.close_connection = True
187 return
188 body = json.dumps({"method": self.command, "path": self.path}).encode()
189 self.send_response(200)
190 self.send_header("Content-Length", str(len(body)))
191 self.end_headers()
192 self.wfile.write(body)
193
194 def log_message(self, *args):
195 pass
196
197 backend = ThreadingHTTPServer(("127.0.0.1", 0), Backend)
198 threading.Thread(target=backend.serve_forever, daemon=True).start()
199 self.addCleanup(backend.server_close)
200 self.addCleanup(backend.shutdown)
201 with socket.socket() as reservation:
202 reservation.bind(("127.0.0.1", 0))
203 self.port = reservation.getsockname()[1]
204 config = (SERVICE / "nginx.conf").read_text()
205 config = config.replace('server 127.0.0.1:8317;', 'server 127.0.0.1:' + str(backend.server_port) + ';')
206 config = re.sub(r'{{ with nomadVar .*?}}|{{ end }}', '', config)
207 config = config.replace('{{ .api_key.Value }}', API_KEY)
208 config = config.replace('/tmp/', str(root) + '/').replace('listen 8080', f'listen 127.0.0.1:{self.port}')
209 config = config.replace('ADMIN_HOST', ADMIN_HOST).replace('API_HOST', API_HOST)
210 self.assertNotIn('{{', config)
211 path = root / "nginx.conf"
212 path.write_text(config)
213 log = (root / "stderr").open('w+b')
214 self.addCleanup(log.close)
215 process = subprocess.Popen([NGINX, '-c', str(path), '-g', 'daemon off;'], stdout=log, stderr=log)
216 def stop():
217 process.terminate()
218 process.wait(timeout=5)
219 log.seek(0)
220 contents = log.read()
221 for marker in self.secret_markers:
222 self.assertNotIn(marker.encode(), contents)
223 self.addCleanup(stop)
224 for _ in range(100):
225 if process.poll() is not None:
226 log.seek(0)
227 self.fail('nginx failed: ' + log.read().decode())
228 try:
229 connection = socket.create_connection(('127.0.0.1', self.port), .1)
230 connection.close()
231 break
232 except OSError:
233 time.sleep(.02)
234 else:
235 self.fail('nginx did not listen')
236
237 @contextmanager
238 def request(self, method, path, headers=None, body=None):
239 connection = http.client.HTTPConnection('127.0.0.1', self.port, timeout=3)
240 connection.request(method, path, body=body, headers={'Host': API_HOST, **(headers or {})})
241 response = connection.getresponse()
242 try:
243 yield response
244 finally:
245 response.close()
246 connection.close()
247
248 def test_management_callback_and_path_confusion_never_reach_backend(self):
249 for path in ['/', '/management.html', '/v8/management/config', '/v0/management/auth-files', '/v0/resource/plugins/x', '/codex/callback?code=synthetic', '/anthropic/callback', '/healthz/../v8/management/config', '/v1/models/../../v8/management/config', '/v1/models/%2e%2e/%2e%2e/v8/management/config', '/v1/models/%2f..%2f..%2fv8%2fmanagement%2fconfig', '/v1/responses/../management']:
250 with self.subTest(path=path), self.request('GET', path, {'Authorization': 'Bearer ' + API_KEY}) as response:
251 self.assertIn(response.status, [400, 404])
252 response.read()
253 self.assertEqual(self.observed, [])
254
255 def test_admin_hostname_has_native_panel_and_unknown_hostname_is_denied(self):
256 with self.request('GET', '/', {'Host': ADMIN_HOST}) as response:
257 self.assertEqual(response.status, 302)
258 self.assertEqual(response.getheader('Location'), '/management.html')
259 response.read()
260 with self.request('GET', '/management.html', {'Host': ADMIN_HOST}) as response:
261 self.assertEqual(response.status, 200)
262 response.read()
263 count = len(self.observed)
264 with self.request('GET', '/management.html', {'Host': 'other.example.test'}) as response:
265 self.assertEqual(response.status, 404)
266 response.read()
267 self.assertEqual(len(self.observed), count)
268
269 def test_browser_oauth_callback_credentials_never_reach_upstream_or_logs(self):
270 code = 'synthetic-oauth-code-must-not-be-logged'
271 state = 'synthetic-oauth-state-must-not-be-logged'
272 self.secret_markers.extend([code, state])
273 paths = ['/v0/management/oauth-callback', '/v8/management/oauth/callback', '/anthropic/callback', '/codex/callback', '/antigravity/callback', '/devin/callback', '/callback']
274 for path in paths:
275 for method in ['GET', 'HEAD']:
276 for suffix in ['', '/']:
277 with self.subTest(path=path, method=method, suffix=suffix), self.request(method, path + suffix + '?code=' + code + '&state=' + state, {'Host': ADMIN_HOST}) as response:
278 self.assertEqual(response.status, 404)
279 response.read()
280 with self.request('GET', path + '?state=' + state, {'Host': ADMIN_HOST}) as response:
281 self.assertEqual(response.status, 404)
282 response.read()
283 with self.request('GET', '/future-provider/callback?code=' + code, {'Host': ADMIN_HOST}) as response:
284 self.assertEqual(response.status, 404)
285 response.read()
286 self.assertEqual(self.observed, [])
287 payload = json.dumps({'provider': 'codex', 'redirect_url': 'http://localhost:1455/auth/callback?code=' + code + '&state=' + state}).encode()
288 for path in paths[:2]:
289 with self.request('POST', path, {'Host': ADMIN_HOST, 'Content-Type': 'application/json'}, body=payload) as response:
290 self.assertEqual(response.status, 200)
291 response.read()
292 self.assertEqual(self.observed[-1][3], payload)
293 self.assertNotIn(code, self.observed[-1][1])
294 self.assertNotIn(state, self.observed[-1][1])
295 with self.request('GET', '/v8/management/oauth/status?state=' + state, {'Host': ADMIN_HOST}) as response:
296 self.assertEqual(response.status, 200)
297 response.read()
298
299 def test_api_key_is_required_independently_of_upstream_auth(self):
300 for headers in [{}, {'Authorization': 'Bearer ' + MANAGEMENT_KEY}, {'Authorization': 'Bearer wrong'}, {'X-Api-Key': 'wrong'}]:
301 with self.request('GET', '/v1/models', headers) as response:
302 self.assertEqual(response.status, 401)
303 response.read()
304 self.assertEqual(self.observed, [])
305 for headers in [{'Authorization': 'Bearer ' + API_KEY}, {'X-Api-Key': API_KEY}]:
306 with self.request('GET', '/v1/models', headers) as response:
307 self.assertEqual(response.status, 200)
308 response.read()
309 self.assertEqual(self.observed[-1][2]['Authorization'], 'Bearer ' + API_KEY)
310 self.assertNotIn('X-Api-Key', self.observed[-1][2])
311 for query in ['key=other', 'auth_token=other']:
312 with self.request('GET', '/v1/models?' + query, {'Authorization': 'Bearer ' + API_KEY}) as response:
313 self.assertEqual(response.status, 400)
314 response.read()
315
316 def test_confirmed_codex_claude_methods_preserve_query_and_strip_admin_cookies(self):
317 for method, path in [('GET', '/v1/models'), ('POST', '/v1/chat/completions'), ('POST', '/v1/responses'), ('POST', '/v1/responses/compact'), ('POST', '/v1/messages'), ('POST', '/v1/messages/count_tokens'), ('POST', '/backend-api/codex/responses')]:
318 with self.subTest(path=path), self.request(method, path + '?fixture=yes', {'Authorization': 'Bearer ' + API_KEY, 'Cookie': 'snowglobe_session=synthetic', 'X-Management-Key': MANAGEMENT_KEY}) as response:
319 self.assertEqual(response.status, 200)
320 self.assertEqual(json.loads(response.read())['path'], path + '?fixture=yes')
321 self.assertNotIn('Cookie', self.observed[-1][2])
322 self.assertNotIn('X-Management-Key', self.observed[-1][2])
323 for method, path in [('DELETE', '/v1/models'), ('GET', '/v1/messages'), ('POST', '/v1/models'), ('OPTIONS', '/v1/responses')]:
324 with self.request(method, path, {'Authorization': 'Bearer ' + API_KEY}) as response:
325 self.assertEqual(response.status, 404)
326 response.read()
327
328 def test_stream_is_delivered_before_upstream_finishes(self):
329 started = time.monotonic()
330 with self.request('POST', '/v1/responses', {'Authorization': 'Bearer ' + API_KEY, 'X-Synthetic-Stream': 'yes'}) as response:
331 self.assertEqual(response.status, 200)
332 self.assertEqual(response.readline(), b'data: first\n')
333 self.assertLess(time.monotonic() - started, .4)
334 self.assertIn(b'data: last', response.read())
335
336 def test_websocket_upgrade_reaches_responses_route(self):
337 key = base64.b64encode(b'synthetic-16-key').decode()
338 with socket.create_connection(('127.0.0.1', self.port), timeout=3) as connection:
339 connection.sendall(('GET /v1/responses HTTP/1.1\r\nHost: ' + API_HOST + '\r\nAuthorization: Bearer ' + API_KEY + '\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: ' + key + '\r\n\r\n').encode())
340 headers = b''
341 while not headers.endswith(b'\r\n\r\n'):
342 headers += connection.recv(1)
343 self.assertIn(b' 101 ', headers.split(b'\r\n')[0])
344 self.assertIn(b'upgrade: websocket', headers.lower())
345 connection.sendall(b'\x81\x82\x01\x02\x03\x04ik')
346 self.assertEqual(connection.recv(4), b'\x81\x02hi')
347
348
349if __name__ == '__main__':
350 parser = argparse.ArgumentParser()
351 parser.add_argument('--nginx', type=Path)
352 options, remaining = parser.parse_known_args()
353 NGINX = str(options.nginx.resolve()) if options.nginx else None
354 GatewayTests.__unittest_skip__ = not NGINX
355 unittest.main(argv=[__file__, *remaining])
tools/cliproxy.md created+60
...@@ -0,0 +1,60 @@
1# CLIProxyAPI
2
3`cliproxy.paperclover.net` is the management panel, protected by Snow's
4`infra-admin` role and CLIProxyAPI's independent management key.
5`cliproxy-api.paperclover.net` is the client endpoint: use
6`https://cliproxy-api.paperclover.net/v1` for OpenAI-compatible clients or
7`https://cliproxy-api.paperclover.net` for Claude-compatible clients.
8
9Nomad variable `nomad/jobs/cliproxy` owns `api_key` and `management_key`.
10Keep values in restricted private files or a password manager; do not paste them
11into chat, command arguments, or tracked configuration. The native panel asks
12for its management key once and offers **Remember password**. That stores the
13key in this browser's local storage; use it only in a trusted browser profile.
14API clients accept the separate client key through `Authorization: Bearer …`
15or `X-Api-Key`. The gateway independently enforces this one infra-managed key,
16even if the native panel removes its own API keys. Query-string keys are rejected.
17
18## Connect providers
19
20Open the management panel, sign in through Snow, then unlock the panel with the
21management key. Its OAuth section supports **Codex** and **Claude**. Start the
22chosen provider's login and complete consent in the provider's own browser page.
23For remote OAuth flows that finish on an unreachable `localhost` URL, copy that
24entire callback URL into the panel's callback form. Treat the callback URL as a
25temporary credential. No callback ports or provider callbacks are exposed on
26the client hostname. Browser GET/HEAD callback routes are blocked on the admin
27hostname too: CLIProxyAPI logs URL queries, so callback credentials must be
28submitted through the management POST form. API-key provider credentials can also be configured in
29the native panel; their persistent home is the private service dataset.
30
31`/data/config.yaml` is seeded once from a read-only Nomad template. Native
32configuration edits, hashed management key, OAuth accounts, and refreshed tokens
33remain under `/srv/prod/cliproxy/data`; restarts and normal releases retain them.
34Changing a generated Nomad key does not overwrite an existing native config:
35coordinate key rotation in both Nomad and the native panel. Fresh staging uses
36separate storage and generated keys and must use synthetic providers only.
37
38## Boundary and updates
39
40Only the confirmed Codex/Claude client routes are public: model listing, chat,
41completions, messages/counting, Responses/compact/WebSocket, and Codex search
42and direct aliases. Management, plugins, OAuth callbacks, unknown paths, and
43unapproved methods return 404 on the API hostname. The app listens only on
44container loopback; nginx publishes the sole port. Both processes exit together
45if either fails. The host-side route requires Snow for management; nginx's
46admin-host routing does not replace that authentication boundary.
47
48The service pins CLIProxyAPI v8.0.32 and the management panel v1.26.5. Panel
49downloads are size- and SHA-256-checked during preparation; runtime auto-update
50is disabled. Request-body logging is omitted by `commercial-mode: true` and
51`request-log: false`. Plugins, discovery, usage aggregation, and profiling start
52disabled. The read-only image has only `/data` and a private `/tmp` writable;
53the pinned `/data/static` subdirectory is mounted read-only separately.
54
55Run `python3 tools/cliproxy-test.py --nginx /path/to/nginx` for bootstrap,
56rendering, pinned-asset, and actual HTTP/streaming/WebSocket boundary checks.
57The test uses temporary synthetic credentials and a loopback fixture upstream.
58Stage with the normal deployment command, verify anonymous management is routed
59to Snow, valid/invalid client-key behavior, provider persistence on restart,
60and logs containing no fixture keys or prompts before production promotion.
tools/router.py+9-7
...@@ -291,8 +291,10 @@ def render(token):...@@ -291,8 +291,10 @@ def render(token):
291 if access and not any(tag.startswith("caddy-host=") for tag in tags):291 if access and not any(tag.startswith("caddy-host=") for tag in tags):
292 raise ValueError("route access role has no host")292 raise ValueError("route access role has no host")
293 for tag in tags:293 for tag in tags:
294 if tag.startswith("caddy-host="):294 if tag.startswith(("caddy-host=", "caddy-plain-host=")):
295 host = tag.split("=", 1)[1]295 host = tag.split("=", 1)[1]
296 role = access[0] if access and tag.startswith("caddy-host=") else None
297 user_header = user_headers[0] if user_headers and role else None
296 if not HOST.fullmatch(host):298 if not HOST.fullmatch(host):
297 raise ValueError(f"invalid Caddy host: {host!r}")299 raise ValueError(f"invalid Caddy host: {host!r}")
298 route = routes.setdefault((80, host), {"upstreams": set(), "services": set(), "authRole": None, "userHeader": None, "internal": False, "realIp": False, "secureCookies": False, "jellyfinAuth": False})300 route = routes.setdefault((80, host), {"upstreams": set(), "services": set(), "authRole": None, "userHeader": None, "internal": False, "realIp": False, "secureCookies": False, "jellyfinAuth": False})
...@@ -300,14 +302,14 @@ def render(token):...@@ -300,14 +302,14 @@ def render(token):
300 if not (instance["ServiceName"] == "jellyfin" or re.fullmatch(r"jellyfin-preview-[0-9a-f]{8}", instance["ServiceName"])):302 if not (instance["ServiceName"] == "jellyfin" or re.fullmatch(r"jellyfin-preview-[0-9a-f]{8}", instance["ServiceName"])):
301 raise ValueError("Jellyfin gateway tag belongs to another service")303 raise ValueError("Jellyfin gateway tag belongs to another service")
302 route["jellyfinAuth"] = True304 route["jellyfinAuth"] = True
303 if access and route["authRole"] not in (None, access[0]):305 if role and route["authRole"] not in (None, role):
304 raise ValueError("conflicting route access roles")306 raise ValueError("conflicting route access roles")
305 if user_headers and route["userHeader"] not in (None, user_headers[0]):307 if user_header and route["userHeader"] not in (None, user_header):
306 raise ValueError("conflicting authenticated user headers")308 raise ValueError("conflicting authenticated user headers")
307 if access:309 if role:
308 route["authRole"] = access[0]310 route["authRole"] = role
309 if user_headers:311 if user_header:
310 route["userHeader"] = user_headers[0]312 route["userHeader"] = user_header
311 if "caddy-internal=true" in tags:313 if "caddy-internal=true" in tags:
312 route["internal"] = True314 route["internal"] = True
313 if "caddy-real-ip=true" in tags:315 if "caddy-real-ip=true" in tags:
tools/snowglobe-sso-test.py+31-1
...@@ -1,6 +1,7 @@...@@ -1,6 +1,7 @@
1#!/usr/bin/env python31#!/usr/bin/env python3
2import json2import json
3import os3import os
4import re
4from pathlib import Path5from pathlib import Path
5import subprocess6import subprocess
6import tempfile7import tempfile
...@@ -8,6 +9,7 @@ import unittest...@@ -8,6 +9,7 @@ import unittest
8from unittest.mock import patch9from unittest.mock import patch
910
10import snowglobe11import snowglobe
12import router
1113
1214
13class SsoConnectivity(unittest.TestCase):15class SsoConnectivity(unittest.TestCase):
...@@ -17,7 +19,7 @@ class SsoConnectivity(unittest.TestCase):...@@ -17,7 +19,7 @@ class SsoConnectivity(unittest.TestCase):
17 redirectUris { "https://fixture.example/api/callback" }19 redirectUris { "https://fixture.example/api/callback" }
18}'''20}'''
1921
20 def load(self, requirements=client, extra_hosts=()):22 def load(self, requirements=client, extra_hosts=(), http=""):
21 with tempfile.TemporaryDirectory(prefix="snowglobe-sso-") as temporary:23 with tempfile.TemporaryDirectory(prefix="snowglobe-sso-") as temporary:
22 fixture = Path(temporary) / "fixture.pkl"24 fixture = Path(temporary) / "fixture.pkl"
23 fixture.write_text(f'''amends {json.dumps((snowglobe.REPO / "config/Service.pkl").as_uri())}25 fixture.write_text(f'''amends {json.dumps((snowglobe.REPO / "config/Service.pkl").as_uri())}
...@@ -27,6 +29,7 @@ requirements {{ {requirements} }}...@@ -27,6 +29,7 @@ requirements {{ {requirements} }}
27containers {{29containers {{
28 ["app"] {{30 ["app"] {{
29 image = "localhost/fixture:pinned"31 image = "localhost/fixture:pinned"
32 {http}
30 extraHosts {{ {"; ".join(json.dumps(host) for host in extra_hosts)} }}33 extraHosts {{ {"; ".join(json.dumps(host) for host in extra_hosts)} }}
31 }}34 }}
32 ["worker"] {{ image = "localhost/fixture:pinned" }}35 ["worker"] {{ image = "localhost/fixture:pinned" }}
...@@ -66,6 +69,33 @@ containers {{...@@ -66,6 +69,33 @@ containers {{
66 data = self.load(requirements=self.client + "\n" + other)69 data = self.load(requirements=self.client + "\n" + other)
67 self.assertEqual(self.render(data).count("snowglobe.fixture.example:host-gateway"), 2)70 self.assertEqual(self.render(data).count("snowglobe.fixture.example:host-gateway"), 2)
6871
72 def test_plain_alias_omits_sso_role_and_identity_header(self):
73 data = self.load(requirements="", http='http { containerPort = 8080; subdomain = "fixture"; authRole = "infra-admin"; userHeader = "X-User"; plainHostnames { "api.fixture.example" } }')
74 tags = json.loads(re.search(r'tags = (\[.*\])', self.render(data))[1])
75 def nomad(path, _):
76 if path == '/v1/services':
77 return [{'Namespace': 'default', 'Services': [{'ServiceName': name} for name in ('fixture', 'forward-auth')]}]
78 if path.startswith('/v1/service/'):
79 name = path.rsplit('/', 1)[1]
80 return [{'ServiceName': name, 'JobID': name, 'AllocID': name, 'Address': '127.0.0.1', 'Port': 28000,
81 'Tags': tags if name == 'fixture' else []}]
82 return {'http': {'Status': 'success'}}
83 with tempfile.TemporaryDirectory() as temporary:
84 root = Path(temporary)
85 proof = root / 'proof'; proof.write_text('a' * 64)
86 environment = {'SNOWGLOBE_DOMAIN': 'fixture.example', 'SNOWGLOBE_DASHBOARD_PORT': '28001',
87 'SNOWGLOBE_PROXY_TOKEN_FILE': str(proof), 'SNOWGLOBE_STATE': temporary}
88 with patch.dict(os.environ, environment, clear=True), patch.object(router, 'nomad', nomad), patch.object(router, 'ROUTE_DIR', str(root / 'routes')):
89 rendered = router.render('fixture')
90 protected = rendered.split('fixture.fixture.example {', 1)[1].split('\n}\n', 1)[0]
91 public = rendered.split('api.fixture.example {', 1)[1].split('\n}\n', 1)[0]
92 self.assertIn('/snow.oauth2/auth', protected)
93 self.assertIn('role:infra-admin', protected)
94 self.assertIn('X-User', protected)
95 self.assertNotIn('/snow.oauth2/', public)
96 self.assertNotIn('X-User', public)
97 self.assertIn('reverse_proxy 127.0.0.1:28000', public)
98
69 def test_services_without_sso_preserve_their_explicit_hosts(self):99 def test_services_without_sso_preserve_their_explicit_hosts(self):
70 data = self.load(requirements="", extra_hosts=["other.example:host-gateway"])100 data = self.load(requirements="", extra_hosts=["other.example:host-gateway"])
71 rendered = self.render(data)101 rendered = self.render(data)
tools/snowglobe.py+8-5
...@@ -341,7 +341,8 @@ def render(data, definitions):...@@ -341,7 +341,8 @@ def render(data, definitions):
341 if kind == "http" and endpoint.get("metricsPath"):341 if kind == "http" and endpoint.get("metricsPath"):
342 tags.append("snowglobe-metrics-path=" + endpoint["metricsPath"])342 tags.append("snowglobe-metrics-path=" + endpoint["metricsPath"])
343 if kind == "http" and endpoint.get("hostname"):343 if kind == "http" and endpoint.get("hostname"):
344 tags += ["caddy-host=" + host for host in [endpoint["hostname"], *endpoint["plainHostnames"]]]344 tags.append("caddy-host=" + endpoint["hostname"])
345 tags += ["caddy-plain-host=" + host for host in endpoint["plainHostnames"]]
345 if endpoint.get("authRole"):346 if endpoint.get("authRole"):
346 tags.append("caddy-auth-role=" + endpoint["authRole"])347 tags.append("caddy-auth-role=" + endpoint["authRole"])
347 if endpoint.get("userHeader"):348 if endpoint.get("userHeader"):
...@@ -1053,13 +1054,15 @@ def main():...@@ -1053,13 +1054,15 @@ def main():
1053 for port in task["tcp"]:1054 for port in task["tcp"]:
1054 port["hostPort"] = None1055 port["hostPort"] = None
1055 if hostname:1056 if hostname:
1057 hosts = {original_host: hostname, **{host: stage + "-" + host for host in http[0]["plainHostnames"]}}
1056 for task in data["containers"].values():1058 for task in data["containers"].values():
1057 if task.get("http") and task["http"].get("hostname") == original_host:1059 if task.get("http") and task["http"].get("hostname") == original_host:
1058 task["http"]["hostname"] = hostname1060 task["http"]["hostname"] = hostname
1059 task["http"]["plainHostnames"] = [stage + "-" + host for host in task["http"]["plainHostnames"]]1061 task["http"]["plainHostnames"] = [hosts[host] for host in task["http"]["plainHostnames"]]
1060 task["env"] = {key: value.replace(original_host, hostname) for key, value in task["env"].items()}1062 for source, target in hosts.items():
1061 if task.get("secretFiles"):1063 task["env"] = {key: value.replace(source, target) for key, value in task["env"].items()}
1062 task["secretFiles"] = {key: value.replace(original_host, hostname) for key, value in task["secretFiles"].items()}1064 if task.get("secretFiles"):
1065 task["secretFiles"] = {key: value.replace(source, target) for key, value in task["secretFiles"].items()}
1063 for request in data["inputs"].values():1066 for request in data["inputs"].values():
1064 if request["provider"] == "snowglobe":1067 if request["provider"] == "snowglobe":
1065 request["redirectUris"] = [uri.replace(original_host, hostname) for uri in request["redirectUris"]]1068 request["redirectUris"] = [uri.replace(original_host, hostname) for uri in request["redirectUris"]]