authoravatarclover caruso<git@paperclover.net>2026-10-16 15:02:20-07:00
committeravatarclover caruso<git@paperclover.net>2026-10-21 02:52:29-07:00
log82853a3868c3cc2c7d8b0df531e0ebd6723913f6
treec85853caef459fc6aa76d0aa79e12345e717966f
parentfaf5d02abe3fc04b016593b922ac52e3ae8bd9f1
signature Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU

Host Knife with private pairing and NAS transcript archives

Run the supplied Linux bundle at knife.paperclover.net with managed state, provider home, archives, and workspaces. Follow the release feed on restart, configure the native environment hub, and keep pairing credentials out of logs. Add deferred Secure cookie enforcement for services that require it. Document owner pairing, laptop offload, private hub enrollment, token renewal, and runtime update recovery. Native pairing remains compatible with desktop clients. Verified fresh Zenith staging, native auth/replay/Origin/revocation, archive integrity and byte ranges, synthetic client offload/restart/read/restore, browser setup/settings/keyboard/reload, actual Caddy cookie responses, deployment tests, and private client-token command capture. Assisted-by: gpt-6.1-sol

9 files changed, 396 insertions(+), 1 deletions(-)

config/Service.pkl+2
...@@ -26,6 +26,8 @@ class Http {...@@ -26,6 +26,8 @@ class Http {
26 identityHeaders: Mapping<String, String> = new {}26 identityHeaders: Mapping<String, String> = new {}
27 /// Set X-Real-Ip from Caddy's observed client address before proxying.27 /// Set X-Real-Ip from Caddy's observed client address before proxying.
28 forwardRealIp: Boolean = false28 forwardRealIp: Boolean = false
29 /// Require HTTPS when browsers send cookies issued by this route.
30 secureCookies: Boolean = false
29 /// Generated secret whose value becomes the private proxy header name.31 /// Generated secret whose value becomes the private proxy header name.
30 identityProofSecret: String?32 identityProofSecret: String?
31 /// Additional hosts routed to this container without SSO headers.33 /// Additional hosts routed to this container without SSO headers.
service/knife/bundle.json created+5
...@@ -0,0 +1,5 @@
1{
2 "url": "https://file.paperclover.net/shr/the-knife/knife-server-linux-amd64.tar.gz",
3 "sha256": "02d9dda61a4de554c5640e6039d2fe9bc5ebcb71d3967efa1930ffc953614102",
4 "image": "sha256:027c96783e914e8a7b4ab3351e89e2c2f75845e889bf81e19aa5b2e87c8a01a6"
5}
service/knife/prepare.py created+31
...@@ -0,0 +1,31 @@
1#!/usr/bin/env python3
2import hashlib
3import json
4from pathlib import Path
5import shutil
6import subprocess
7import tarfile
8import tempfile
9import urllib.request
10
11
12bundle = json.loads(Path(__file__).with_name("bundle.json").read_text())
13if subprocess.run(["podman", "image", "exists", bundle["image"]]).returncode:
14 with tempfile.TemporaryDirectory(prefix="studio-knife-") as temporary:
15 archive = Path(temporary) / "bundle.tar.gz"
16 digest = hashlib.sha256()
17 with urllib.request.urlopen(bundle["url"], timeout=120) as source, archive.open("wb") as target:
18 while block := source.read(1024 * 1024):
19 digest.update(block)
20 target.write(block)
21 if digest.hexdigest() != bundle["sha256"]:
22 raise ValueError("Knife server bundle failed checksum verification")
23 image = Path(temporary) / "image.tar"
24 with tarfile.open(archive) as source, image.open("wb") as target:
25 member = source.getmember("image.tar")
26 if not member.isfile():
27 raise ValueError("Knife server bundle has no image file")
28 with source.extractfile(member) as contents:
29 shutil.copyfileobj(contents, target)
30 subprocess.run(["podman", "load", "--quiet", "--input", str(image)], check=True)
31 subprocess.run(["podman", "image", "exists", bundle["image"]], check=True)
service/knife/service.pkl created+46
...@@ -0,0 +1,46 @@
1amends "../../config/Service.pkl"
2
3import "pkl:json"
4
5local bundle = (new json.Parser {}).parse(read("bundle.json"))
6
7meta { name = "The Knife"; access = "infra-admin" }
8stageIsolation = "fresh"
9prepare = "prepare.py"
10setup = "setup.py"
11
12container {
13 image = bundle.image
14 cpu = 1000
15 memory = 4096
16 entrypoint = "/usr/bin/tini"
17 args {
18 "--"
19 "/bin/sh"
20 "-ec"
21 "node /opt/knife/scripts/container-runtime.ts; exec knife start --host 0.0.0.0 --port 3773 --no-browser"
22 }
23 http {
24 containerPort = 3773
25 subdomain = "knife"
26 loopback = true
27 secureCookies = true
28 checkPath = "/.well-known/t3/environment"
29 }
30 volumes {
31 ["/data"] {}
32 ["/home/node"] {}
33 ["/archives"] {}
34 ["/workspaces"] {}
35 }
36 env {
37 ["HOME"] = "/home/node"
38 ["KNIFE_UPDATE_URL"] = "https://file.paperclover.net/shr/the-knife/"
39 ["T3CODE_HOME"] = "/data"
40 ["T3CODE_ARCHIVE_DIR"] = "/archives"
41 ["T3CODE_ARCHIVE_OFFLOAD"] = "true"
42 ["T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD"] = "false"
43 // Info-level startup logs include a live owner pairing credential.
44 ["T3CODE_LOG_LEVEL"] = "Warn"
45 }
46}
service/knife/setup.py created+19
...@@ -0,0 +1,19 @@
1#!/usr/bin/env python3
2import json
3import os
4from pathlib import Path
5import subprocess
6import sys
7
8
9data = json.load(sys.stdin)
10allocations = json.loads(subprocess.check_output(
11 ["nomad", "job", "allocs", "-json", data["serviceId"]],
12 env={**os.environ, "NOMAD_TOKEN": Path("/var/lib/studio/nomad.token").read_text().strip()},
13))
14running = [item["ID"] for item in allocations if item["ClientStatus"] == "running" and item["DesiredStatus"] == "run"]
15if len(running) != 1:
16 raise ValueError("Knife setup requires one running allocation")
17subprocess.run([
18 "podman", "exec", "app-" + running[0], "knife", "shared", "hub", "configure", "https://" + data["host"],
19], check=True, capture_output=True)
tools/knife.md created+184
...@@ -0,0 +1,184 @@
1# Knife setup and operation
2
3`https://knife.paperclover.net` runs the private Knife authority, archive
4receiver, and optional environment hub. Native single-use pairing controls
5access; there is no public registration. The service's four directories live
6on the managed NAS dataset `/srv/prod/knife`: `data`, `archives`, `home/node`,
7and `workspaces`. Provider credentials can stay on each laptop.
8
9## Pair the owner
10
11Run these commands in your terminal. SSH access to Zenith is the recovery
12path; no owner credential is written to application or deployment logs.
13
14```sh
15ssh -p 22 root@10.0.0.1
16export NOMAD_TOKEN="$(cat /var/lib/studio/nomad.token)"
17knife_allocation=$(nomad job allocs -json knife | python3 -c 'import json,sys; a=[r["ID"] for r in json.load(sys.stdin) if r["ClientStatus"]=="running" and r["DesiredStatus"]=="run"]; assert len(a)==1; print(a[0])')
18knife_container="app-$knife_allocation"
19podman exec "$knife_container" knife auth pairing create \
20 --ttl 5m --label 'Clover owner' --base-url https://knife.paperclover.net \
21 --scope orchestration:read --scope orchestration:operate \
22 --scope settings:write --scope providers:manage \
23 --scope environment:maintain --scope preview:operate \
24 --scope diagnostics:read --scope terminal:read --scope terminal:operate \
25 --scope source-control:write --scope filesystem:read --scope filesystem:write \
26 --scope relay:read --scope relay:write --scope access:read --scope access:write
27```
28
29Open the printed pairing link privately within five minutes. It is single-use.
30An owner pairing needs the full scope list: supplying `--scope` replaces the
31CLI defaults, and default pairing omits access management. The browser session
32lasts 30 days. Repeat the command for another owner device or browser.
33
34In the desktop app, choose **Self-hosted server**, enter
35`https://knife.paperclover.net`, and paste a fresh pairing code. The same entry
36is under **Settings → Environments**. Choose this path to avoid T3 Connect.
37A browser paired to the NAS controls the NAS environment; laptop transcripts
38remain in their originating environments until those laptops are connected.
39
40The NAS needs no provider login for archive storage or hub routing. Configure
41providers on the NAS only if agents should actually run there. Its writable
42workspace is `/workspaces`; the personal file archive and host credentials are
43not mounted into the container.
44
45## Enable laptop archive offload
46
47UI pairing and archive offload are separate connections. Repeat these steps for
48each laptop, using a separate, revocable token and label.
49
50From the Mac, create a private local token file by capturing SSH output directly.
51The current API requires orchestration read/operate and provider-management
52permissions for offload plus the `shared connect` account-list check. These also
53permit thread/provider operations on the NAS; keep the token private. No provider
54accounts need to be imported.
55
56```sh
57umask 077
58mkdir -p "$HOME/.config/knife"
59ssh -p 22 root@10.0.0.1 'export NOMAD_TOKEN="$(cat /var/lib/studio/nomad.token)"; allocation=$(nomad job allocs -json knife | python3 -c '\''import json,sys; a=[r["ID"] for r in json.load(sys.stdin) if r["ClientStatus"]=="running" and r["DesiredStatus"]=="run"]; assert len(a)==1; print(a[0])'\''); podman exec "app-$allocation" knife auth session issue --ttl 30d --label "Clover Mac archive" --scope orchestration:read --scope orchestration:operate --scope providers:manage --token-only' > "$HOME/.config/knife/nas-token"
60chmod 600 "$HOME/.config/knife/nas-token"
61"$HOME/.t3/bin/t3" shared connect https://knife.paperclover.net \
62 --token-file "$HOME/.config/knife/nas-token"
63```
64
65The packaged Knife desktop installs `~/.t3/bin/t3`. If a custom `T3CODE_HOME`
66is used, use its `bin/t3` and pass the matching `--base-dir` to CLI commands.
67The local Knife backend must already be running for `shared connect`.
68
69Quit Knife, then launch its executable with archive offload enabled:
70
71```sh
72T3CODE_ARCHIVE_OFFLOAD=true '/Applications/The Knife.app/Contents/MacOS/The Knife'
73```
74
75The setting must reach the backend on every launch. For Finder launches,
76`launchctl setenv T3CODE_ARCHIVE_OFFLOAD true` supplies it for this login session;
77repeat after logging in again. Fully quit the existing app before relaunching.
78Windows WSL backends currently do not forward this variable from the desktop;
79enable it inside the WSL backend environment before using offload there.
80
81Check the connection and archive queue:
82
83```sh
84"$HOME/.t3/bin/t3" shared status
85"$HOME/.t3/bin/t3" shared archive status
86```
87
88Archive one disposable conversation first. Within roughly a minute, status
89should report `enabled: true`, an increased `offloaded` count, `pending: 0`,
90and no failures. Open its transcript and unarchive it to check retrieval and
91restoration before relying on the connection for real history.
92
93Offload replaces archived T3 transcript bodies with local metadata after the
94NAS acknowledges the object. Failed uploads retain the local bodies. Reading
95cold history requires the NAS and its valid token; unarchive restores local
96bodies. Existing SQLite files can retain allocated pages, and native Claude or
97Codex history files remain: this feature does not compact all existing laptop
98storage. Keep the NAS state and archive objects together in backups.
99
100The archive token expires after 30 days without automatic renewal. Issue a
101replacement into the private file and run `shared connect` again before it
102expires. `shared archive retry` retries failed uploads. Choose a longer `--ttl`
103explicitly if monthly renewal is unsuitable; retain a separate label per laptop.
104
105## Route laptop environments through the NAS
106
107Archive offload only needs an outbound laptop connection to the NAS. Routing
108interactive access through the hub additionally requires Zenith to reach the
109laptop backend over a private LAN or VPN address. This fork has no reverse
110connection that makes an unreachable laptop accessible through the hub.
111
112The NAS public hub URL is configured automatically during deployment. To enroll
113a laptop, get its environment ID from its private
114`/.well-known/t3/environment` descriptor. Issue a separate, labeled administrative
115session on that laptop with `~/.t3/bin/t3 auth session issue --ttl 30d
116--label "Clover NAS hub" --token-only`, capturing it into a mode-0600 file rather
117than displaying it.
118Transfer that file privately to Zenith. In the SSH session above:
119
120```sh
121podman cp /root/knife-laptop-enrollment-token "$knife_container":/data/laptop-enrollment-token
122podman exec "$knife_container" knife shared hub enroll \
123 https://YOUR-PRIVATE-LAPTOP-ADDRESS ENVIRONMENT-ID \
124 --token-file /data/laptop-enrollment-token
125podman exec "$knife_container" rm /data/laptop-enrollment-token
126rm /root/knife-laptop-enrollment-token
127```
128
129Use a private endpoint already secured by Knife authentication; Tailscale Serve
130is one option. No public laptop port is required. Do not disable certificate
131verification. The hub retains this administrative credential in its private
132state to delegate later connections; removing the transfer files does not revoke
133it. Renew and re-enroll before its 30-day expiry, or revoke the labeled laptop
134session to withdraw hub access. A sleeping or unreachable laptop cannot serve
135an interactive session. Its uploaded archive objects remain on the NAS.
136
137## Revoke access and update the service
138
139The owner session can manage pairing links and clients in **Settings → This machine → Authorized clients**.
140SSH recovery also works without a live browser session:
141
142```sh
143podman exec "$knife_container" knife auth session list
144podman exec "$knife_container" knife auth session revoke SESSION-ID
145podman exec "$knife_container" knife auth pairing list
146podman exec "$knife_container" knife auth pairing revoke PAIRING-ID
147```
148
149Keep pairing links and archive tokens private. Access is possession-based:
150anyone holding a live code or token has its granted scopes. The proxy adds
151`Secure` to browser cookies; the app supplies `HttpOnly` and `SameSite=Lax`.
152The container's published port binds only to loopback.
153
154As requested, each container restart checks the release feed and starts its
155newest compatible server/UI/assets after SHA-256 verification. The running
156process keeps its current code until restarted. This quiet startup path does
157not prefetch in the background. A temporary feed outage starts the installed
158runtime; corrupt downloads or a release requiring a newer base image stop
159startup instead of executing unverified or incompatible code.
160
161For a new base image, review the Linux bundle, update
162`service/knife/bundle.json` with its checksum and image ID, and use the normal
163stage → main → prod workflow. The loader rejects changed bytes at the existing
164bundle URL until its recorded checksum is updated. Application code cached
165under `/data/runtime/knife-container` survives image/infra rollback; restoring
166an older runtime requires an explicit application recovery choice. Code
167rollback does not roll back state or archive objects.
168
169## 2026-10-16 verification
170
171Zenith fresh preview verified anonymous project/archive/pairing denial,
172single-use pairing, hostile cookie Origin rejection, session revocation,
173hash-checked archive upload, identical download, byte ranges, and corrupt-object
174rejection. A disposable local client imported a two-message synthetic Claude
175conversation, offloaded it to the NAS, restarted, read both cold transcript
176items, and restored both bodies on unarchive. Temporary client credentials
177were revoked and local fixture stores removed.
178
179Browser verification covered first run, self-hosted connection entry, settings,
180access management, archive/history controls, keyboard navigation, and reload
181persistence. Real Caddy checks verified Secure on multiple cookies and logout
182responses while leaving default routes unchanged. Warn-level startup emitted
183no pairing credential. All four service mounts used disposable managed preview
184storage with the assigned service UID.
tools/router-cookie-test.py created+102
...@@ -0,0 +1,102 @@
1#!/usr/bin/env python3
2import argparse
3from http.client import HTTPConnection
4from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
5import json
6import os
7from pathlib import Path
8import socket
9import subprocess
10import tempfile
11import threading
12import time
13from unittest.mock import patch
14
15import router
16
17
18class Cookies(BaseHTTPRequestHandler):
19 def do_GET(self):
20 self.send_response(204 if self.path == '/logout' else 200)
21 self.send_header('Set-Cookie', 'session=fixture; HttpOnly; Path=/')
22 self.send_header('Set-Cookie', 'other=fixture; SameSite=Lax')
23 self.end_headers()
24
25 def log_message(self, *_):
26 pass
27
28
29def main():
30 parser = argparse.ArgumentParser()
31 parser.add_argument('--caddy', required=True, type=Path)
32 args = parser.parse_args()
33 with tempfile.TemporaryDirectory(prefix='studio-router-cookies-') as temporary, ThreadingHTTPServer(('127.0.0.1', 0), Cookies) as backend:
34 root = Path(temporary)
35 proof = root / 'proof'
36 proof.write_text('a' * 64)
37 environment = {**os.environ, 'STUDIO_DOMAIN': 'studio.test', 'STUDIO_DASHBOARD_PORT': '3000',
38 'STUDIO_PROXY_TOKEN_FILE': str(proof), 'XDG_DATA_HOME': str(root / 'data'),
39 'XDG_CONFIG_HOME': str(root / 'config')}
40 environment.pop('STUDIO_INTERNAL_PORT', None)
41
42 def nomad(path, _):
43 if path == '/v1/services':
44 return [{'Namespace': 'default', 'Services': [{'ServiceName': 'knife'}, {'ServiceName': 'plain'}]}]
45 if path.startswith('/v1/service/'):
46 service = path.rsplit('/', 1)[1]
47 return [{'ServiceName': service, 'JobID': service, 'AllocID': service, 'Address': '127.0.0.1',
48 'Port': backend.server_port, 'Tags': ['caddy-host=' + service + '.studio.test'] +
49 (['caddy-secure-cookies=true'] if service == 'knife' else [])}]
50 return {'http': {'Status': 'success'}}
51
52 with patch.dict(os.environ, environment, clear=True), patch.object(router, 'nomad', nomad), patch.object(router, 'ROUTE_DIR', str(root / 'routes')):
53 rendered = router.render('fixture')
54 assert rendered.count('header >Set-Cookie') == 1
55 configuration = root / 'routes.caddy'
56 configuration.write_text('{\n admin off\n auto_https off\n skip_install_trust\n}\n' + rendered)
57 adapted = subprocess.run([str(args.caddy), 'adapt', '--config', str(configuration), '--adapter', 'caddyfile'], check=True, capture_output=True, text=True, env=environment)
58 assert '"deferred":true' in adapted.stdout.replace(' ', '')
59 subprocess.run([str(args.caddy), 'validate', '--config', str(configuration), '--adapter', 'caddyfile'], check=True, capture_output=True, env=environment)
60 with socket.socket() as listener:
61 listener.bind(('127.0.0.1', 0))
62 port = listener.getsockname()[1]
63 runtime = root / 'Caddyfile'
64 sites = rendered.split('auth.studio.test {', 1)[0]
65 sites = sites.replace('knife.studio.test {', f'http://127.0.0.1:{port} {{').replace('plain.studio.test {', f'http://localhost:{port} {{').replace(' tls internal\n', '')
66 runtime.write_text('{\n admin off\n auto_https off\n}\n' + sites)
67 threading.Thread(target=backend.serve_forever, daemon=True).start()
68 with (root / 'caddy.log').open('w') as log:
69 caddy = subprocess.Popen([str(args.caddy), 'run', '--config', str(runtime), '--adapter', 'caddyfile'], stdout=log, stderr=log, env=environment)
70 try:
71 deadline = time.monotonic() + 10
72 while True:
73 try:
74 connection = HTTPConnection('127.0.0.1', port, timeout=1)
75 connection.request('GET', '/')
76 response = connection.getresponse()
77 response.read()
78 connection.close()
79 break
80 except OSError:
81 assert caddy.poll() is None and time.monotonic() < deadline, (root / 'caddy.log').read_text()
82 time.sleep(0.05)
83 for host in ('127.0.0.1', 'localhost'):
84 for path in ('/', '/logout'):
85 connection = HTTPConnection('127.0.0.1', port, timeout=2)
86 connection.request('GET', path, headers={'Host': f'{host}:{port}'})
87 response = connection.getresponse()
88 cookies = [value for key, value in response.getheaders() if key.lower() == 'set-cookie']
89 assert response.status == (204 if path == '/logout' else 200)
90 assert cookies == ['session=fixture; HttpOnly; Path=/' + ('; Secure' if host == '127.0.0.1' else ''),
91 'other=fixture; SameSite=Lax' + ('; Secure' if host == '127.0.0.1' else '')], cookies
92 response.read()
93 connection.close()
94 finally:
95 caddy.terminate()
96 caddy.wait(timeout=10)
97 backend.shutdown()
98 print(json.dumps({'generated_config': 'validated', 'multiple_cookies': 'secure', 'logout_cookies': 'secure', 'default_route': 'unchanged'}))
99
100
101if __name__ == '__main__':
102 main()
tools/router.py+5-1
...@@ -151,7 +151,7 @@ def render(token):...@@ -151,7 +151,7 @@ def render(token):
151 host = tag.split("=", 1)[1]151 host = tag.split("=", 1)[1]
152 if not HOST.fullmatch(host):152 if not HOST.fullmatch(host):
153 raise ValueError(f"invalid Caddy host: {host!r}")153 raise ValueError(f"invalid Caddy host: {host!r}")
154 route = routes.setdefault((80, host), {"upstreams": set(), "services": set(), "authRole": None, "userHeader": None, "internal": False, "realIp": False})154 route = routes.setdefault((80, host), {"upstreams": set(), "services": set(), "authRole": None, "userHeader": None, "internal": False, "realIp": False, "secureCookies": False})
155 if access and route["authRole"] not in (None, access[0]):155 if access and route["authRole"] not in (None, access[0]):
156 raise ValueError("conflicting route access roles")156 raise ValueError("conflicting route access roles")
157 if user_headers and route["userHeader"] not in (None, user_headers[0]):157 if user_headers and route["userHeader"] not in (None, user_headers[0]):
...@@ -164,6 +164,8 @@ def render(token):...@@ -164,6 +164,8 @@ def render(token):
164 route["internal"] = True164 route["internal"] = True
165 if "caddy-real-ip=true" in tags:165 if "caddy-real-ip=true" in tags:
166 route["realIp"] = True166 route["realIp"] = True
167 if "caddy-secure-cookies=true" in tags:
168 route["secureCookies"] = True
167 route["upstreams"].add(upstream)169 route["upstreams"].add(upstream)
168 route["services"].add(instance.get("JobID") or instance["ServiceName"])170 route["services"].add(instance.get("JobID") or instance["ServiceName"])
169 elif tag.startswith("caddy-port="):171 elif tag.startswith("caddy-port="):
...@@ -184,6 +186,8 @@ def render(token):...@@ -184,6 +186,8 @@ def render(token):
184 lines.append(f"{host if listener == 80 else f'{host}:{listener}'} {{")186 lines.append(f"{host if listener == 80 else f'{host}:{listener}'} {{")
185 if host.endswith(".test") or route["internal"]:187 if host.endswith(".test") or route["internal"]:
186 lines.append(" tls internal")188 lines.append(" tls internal")
189 if route["secureCookies"]:
190 lines.append(' header >Set-Cookie "(.*)" "$1; Secure"')
187 if route["realIp"]:191 if route["realIp"]:
188 lines.append(" request_header X-Real-Ip {remote_host}")192 lines.append(" request_header X-Real-Ip {remote_host}")
189 if len(route["services"]) != 1:193 if len(route["services"]) != 1:
tools/studio.py+2
...@@ -342,6 +342,8 @@ def render(data, definitions):...@@ -342,6 +342,8 @@ def render(data, definitions):
342 tags.append("caddy-user-header=" + endpoint["userHeader"])342 tags.append("caddy-user-header=" + endpoint["userHeader"])
343 if endpoint["forwardRealIp"]:343 if endpoint["forwardRealIp"]:
344 tags.append("caddy-real-ip=true")344 tags.append("caddy-real-ip=true")
345 if endpoint.get("secureCookies"):
346 tags.append("caddy-secure-cookies=true")
345 if endpoint["tlsInternal"]:347 if endpoint["tlsInternal"]:
346 tags.append("caddy-internal=true")348 tags.append("caddy-internal=true")
347 if tags:349 if tags: