authoravatarclover caruso<git@paperclover.net>2026-10-28 01:04:28-07:00
committeravatarclover caruso<git@paperclover.net>2026-11-12 16:08:55-08:00
log2eaf043d3ab4571bfc809b8777bd24ecc8326c5d
tree2705b8689b66bf8fdae90370df1cf6c994943066
parent12e0e05ea6505d47807eb7f08e12f9458b0c786a
signature Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU

Remove the retired Knife Nomad service

Preserve its archive recovery record and storage. Assisted-by: gpt-6.1-terra

6 files changed, 8 insertions(+), 301 deletions(-)

service/knife/bundle.json deleted-5
......@@ -1,5 +0,0 @@
1{
2 "url": "https://file.paperclover.net/shr/the-knife/knife-server-linux-amd64.tar.gz",
3 "sha256": "3c67925b1f11492157ad2d7832455c9e07b01ca58f63a3d730ce5a68c6ef8f21",
4 "image": "sha256:9c2da38825a4b35ca13c6f6596f7fd67cebd75dc3394932c8a6f66022136294c"
5}
service/knife/machine-info deleted-1
......@@ -1 +0,0 @@
1PRETTY_HOSTNAME="snow globe"
service/knife/prepare.py deleted-59
......@@ -1,59 +0,0 @@
1#!/usr/bin/env python3
2import hashlib
3import json
4import os
5from pathlib import Path
6import shutil
7import subprocess
8import sys
9import tarfile
10import tempfile
11import urllib.request
12import uuid
13
14
15bundle = json.loads(Path(__file__).with_name("bundle.json").read_text())
16if subprocess.run(["podman", "image", "exists", bundle["image"]]).returncode:
17 with tempfile.TemporaryDirectory(prefix="snowglobe-knife-") as temporary:
18 archive = Path(temporary) / "bundle.tar.gz"
19 digest = hashlib.sha256()
20 with urllib.request.urlopen(bundle["url"], timeout=120) as source, archive.open("wb") as target:
21 while block := source.read(1024 * 1024):
22 digest.update(block)
23 target.write(block)
24 if digest.hexdigest() != bundle["sha256"]:
25 raise ValueError("Knife server bundle failed checksum verification")
26 image = Path(temporary) / "image.tar"
27 with tarfile.open(archive) as source, image.open("wb") as target:
28 member = source.getmember("image.tar")
29 if not member.isfile():
30 raise ValueError("Knife server bundle has no image file")
31 with source.extractfile(member) as contents:
32 shutil.copyfileobj(contents, target)
33 subprocess.run(["podman", "load", "--quiet", "--input", str(image)], check=True)
34 subprocess.run(["podman", "image", "exists", bundle["image"]], check=True)
35
36root = Path(json.load(sys.stdin)["hostRoot"])
37archives = root / "archives"
38mount = subprocess.run(
39 ["findmnt", "-rn", "-o", "TARGET,FSTYPE", "--target", str(archives)],
40 check=True, capture_output=True, text=True,
41).stdout.strip()
42if root.resolve() != root or archives.resolve() != archives or mount != f"{root} zfs":
43 raise ValueError("Knife archives must be on the mounted service ZFS dataset")
44marker = archives / ".knife-archive-store-id"
45try:
46 with marker.open("x") as file:
47 file.write(str(uuid.uuid4()) + "\n")
48 os.fchmod(file.fileno(), 0o444)
49 file.flush()
50 os.fsync(file.fileno())
51 directory = os.open(archives, os.O_RDONLY | os.O_DIRECTORY)
52 try:
53 os.fsync(directory)
54 finally:
55 os.close(directory)
56except FileExistsError:
57 pass
58if marker.is_symlink() or not marker.is_file() or not marker.read_text().strip():
59 raise ValueError("Knife archive store identity must be a nonempty regular file")
service/knife/service.pkl deleted-70
......@@ -1,70 +0,0 @@
1amends "../../config/Service.pkl"
2
3import "pkl:json"
4import "../../config/OpenID.pkl" as sso
5
6local bundle = (new json.Parser {}).parse(read("bundle.json"))
7
8name = "The Knife"
9enabled = false
10access = "infra-admin"
11requirements {
12 new sso.Client {
13 clientId = module.id
14 name = module.name
15 redirectUris { "https://\(module.container.http.hostname)/api/auth/oidc/callback" }
16 }
17}
18stageIsolation = "fresh"
19prepare = "prepare.py"
20
21container {
22 image = bundle.image
23 cpu = 1000
24 memory = 4096
25 entrypoint = "/usr/bin/tini"
26 args {
27 "--"
28 "/bin/sh"
29 "-ec"
30 "T3CODE_ARCHIVE_STORE_ID=$(cat /archives/.knife-archive-store-id); export T3CODE_ARCHIVE_STORE_ID; node /opt/knife/scripts/container-runtime.ts; exec knife start --host 0.0.0.0 --port 3773 --no-browser"
31 }
32 http {
33 containerPort = 3773
34 subdomain = "knife"
35 loopback = true
36 secureCookies = true
37 checkPath = "/.well-known/t3/environment"
38 }
39 volumes {
40 ["/etc/machine-info"] { config = "machine-info" }
41 ["/data"] {}
42 ["/home/node"] {}
43 ["/archives"] {}
44 ["/workspaces"] {}
45 }
46 env {
47 ["HOME"] = "/home/node"
48 ["KNIFE_UPDATE_URL"] = "https://file.paperclover.net/shr/the-knife/"
49 ["T3CODE_HOME"] = "/data"
50 ["T3CODE_SSO_CONFIG"] = "/run/secrets/knife-oidc.json"
51 ["T3CODE_ARCHIVE_DIR"] = "/archives"
52 ["T3CODE_ARCHIVE_OFFLOAD"] = "true"
53 ["T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD"] = "false"
54 // Info-level startup logs include a live owner pairing credential.
55 ["T3CODE_LOG_LEVEL"] = "Warn"
56 }
57 secretFiles {
58 ["/run/secrets/knife-oidc.json"] = """
59 {{ with nomadVar "nomad/jobs/\(module.id)/inputs/oidc" }}
60 {
61 "publicUrl": "https://\(module.container.http.hostname)",
62 "issuer": {{ .issuerUrl.Value | toJSON }},
63 "clientId": {{ .clientId.Value | toJSON }},
64 "clientSecret": {{ .clientSecret.Value | toJSON }},
65 "ownerSub": "8c909fab-98b0-4472-9171-9606ccebe9d5"
66 }
67 {{ end }}
68 """
69 }
70}
tools/knife-test.py deleted-71
......@@ -1,71 +0,0 @@
1#!/usr/bin/env python3
2import io
3import json
4from pathlib import Path
5import runpy
6import subprocess
7import tempfile
8import unittest
9from unittest.mock import patch
10import uuid
11
12
13class ArchiveIdentity(unittest.TestCase):
14 def setUp(self):
15 temporary = tempfile.TemporaryDirectory(prefix="knife-archive-test-")
16 self.addCleanup(temporary.cleanup)
17 self.root = Path(temporary.name).resolve()
18 self.archives = self.root / "archives"
19 self.archives.mkdir()
20 self.marker = self.archives / ".knife-archive-store-id"
21
22 def prepare(self, mount=None):
23 def command(args, **kwargs):
24 if args[:3] == ["podman", "image", "exists"]:
25 return subprocess.CompletedProcess(args, 0)
26 self.assertEqual(args[0], "findmnt")
27 self.assertEqual(args[-1], str(self.archives))
28 return subprocess.CompletedProcess(args, 0, stdout=mount or f"{self.root} zfs\n")
29 with patch("subprocess.run", side_effect=command), patch("sys.stdin", io.StringIO(json.dumps({"hostRoot": str(self.root)}))):
30 runpy.run_path(str(Path(__file__).resolve().parents[1] / "service/knife/prepare.py"))
31
32 def test_create_on_confirmed_zfs_and_preserve_existing_identity(self):
33 self.prepare()
34 uuid.UUID(self.marker.read_text().strip())
35 self.assertEqual(self.marker.stat().st_mode & 0o777, 0o444)
36 self.marker.unlink()
37 self.marker.write_text("existing-nas-identity\n")
38 self.prepare()
39 self.assertEqual(self.marker.read_bytes(), b"existing-nas-identity\n")
40
41 def test_wrong_or_fallback_mount_cannot_create_marker(self):
42 for mount in ["/ ext4", f"{self.root} ext4", f"{self.archives} zfs"]:
43 with self.subTest(mount=mount), self.assertRaises(ValueError):
44 self.prepare(mount)
45 self.assertFalse(self.marker.exists())
46
47 def test_symlinked_archive_directory_cannot_create_marker(self):
48 self.archives.rmdir()
49 target = self.root / "elsewhere"
50 target.mkdir()
51 self.archives.symlink_to(target, target_is_directory=True)
52 with self.assertRaises(ValueError):
53 self.prepare()
54 self.assertFalse((target / self.marker.name).exists())
55
56 def test_invalid_existing_marker_is_preserved_and_rejected(self):
57 self.marker.write_text("")
58 with self.assertRaises(ValueError):
59 self.prepare()
60 self.assertEqual(self.marker.read_bytes(), b"")
61 self.marker.unlink()
62 target = self.root / "outside-marker"
63 target.write_text("outside\n")
64 self.marker.symlink_to(target)
65 with self.assertRaises(ValueError):
66 self.prepare()
67 self.assertEqual(target.read_text(), "outside\n")
68
69
70if __name__ == "__main__":
71 unittest.main()
tools/knife.md+8-95
......@@ -1,95 +1,8 @@
1# Knife sign-in and archive storage
2
3The production service was taken offline on 2026-10-19. Its declaration has
4`enabled = false`, so later deployments do not restart it. The complete
5`globe/prod/knife` dataset remains mounted at `/srv/prod/knife`, including runtime
6state, archive objects, environment identity, and workspaces. The stopped dataset
7has snapshot `knife-retired-20261019T213553Z`, held with
8`knife-archive-retention`. Private verification evidence is in
9`/var/lib/snowglobe/retirements/knife/`.
10
11Keep `data` and `archives` together; archive objects alone are not a complete
12restoration. Preserve the service UID and `archives/.knife-archive-store-id`.
13Retirement does not delete or migrate any conversations. The disposable preview
14was removed on 2026-10-19.
15Later deployment backups omit retired jobs; retain the held snapshot and private
16retirement evidence separately from routine release-backup retention.
17
18## Restoring service access
19
20Re-enabling the service requires a deliberate production deployment. After that,
21open https://knife.paperclover.net and sign in through Snow Globe. The server
22accepts only the configured issuer and Clover's immutable owner subject. The NAS
23environment is **snow globe**. Provider accounts can stay on each laptop; the NAS
24needs none for archive storage or outbound environment routing.
25
26On each machine, install the current Knife desktop release, choose its
27self-hosted server connection, enter `https://knife.paperclover.net`, and complete
28browser sign-in. The desktop returns through its proof-bound application callback;
29only the server's HTTPS callback is registered with Snow Globe. Laptop connections
30run outbound through Knife, with archive offload enabled automatically. No laptop
31port forwarding, SSH pairing, bearer-token file, or manual hub enrollment is needed
32for the SSO connection.
33
34Archive a disposable conversation first, reopen its cold transcript, then unarchive
35it. Confirm that its source connection and archive queue report success before
36relying on offload for existing history. A sleeping laptop cannot run interactive
37agents; uploaded archives remain on the NAS. Successful offload reclaims local
38SQLite pages after publication. Native provider history files remain on the laptop.
39
40## Access and recovery
41
42SSO access credentials last fifteen minutes, with rotating device credentials in
43operating-system protected storage. Browser sign-in is required again after thirty
44days. The server revalidates the issuer grant during renewal at least hourly;
45issuer revocation can therefore take an hour plus fifteen minutes to fully apply.
46Local device revocation disables renewal and closes active connections immediately.
47
48Existing manual pairing credentials survive the upgrade. Manage them separately
49from SSO devices under access settings; do not share pairing links or bearer tokens.
50The listener binds only to loopback behind HTTPS, with WebSocket proxying. Hosted
51SSO cookies are Secure, HttpOnly, SameSite=Lax and protected against cross-origin
52writes.
53
54For local recovery, derive the current container from Nomad rather than retaining
55an allocation ID:
56
57```sh
58ssh -p 22 root@10.0.0.1
59export NOMAD_TOKEN="$(cat /var/lib/snowglobe/nomad.token)"
60knife_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])')
61knife_container="app-$knife_allocation"
62podman exec "$knife_container" knife auth devices revoke-all
63```
64
65This revokes SSO devices and sessions without contacting the issuer. It preserves
66the configured owner, identity-provider account, archives, and manual pairing
67credentials. Inspect/revoke those separately with `knife auth session list`,
68`knife auth session revoke SESSION-ID`, `knife auth pairing list`, and
69`knife auth pairing revoke PAIRING-ID` in the same container.
70
71## Persistent configuration
72
73The existing managed ZFS dataset `/srv/prod/knife` holds `data`, `archives`,
74`home/node`, and `workspaces`. Keep state and archives together in backups. Preserve
75its assigned service UID and environment identity across image upgrades.
76
77Nomad owns the confidential client secret at `nomad/jobs/knife/inputs/oidc`.
78The allocation renders the private SSO JSON and mounts it read-only at
79`/run/secrets/knife-oidc.json`, readable by the assigned service UID. Tracked
80configuration contains the public issuer, callback, and immutable owner subject,
81with references to the private Nomad values. Preview allocations use their own
82registered clients and disposable state.
83
84Preparation creates `archives/.knife-archive-store-id` exclusively on the confirmed
85service ZFS mount, preserving any existing marker. Startup supplies its value as
86`T3CODE_ARCHIVE_STORE_ID`. Missing or mismatched identity blocks archive publication
87and local payload eviction; never replace the marker to silence that failure.
88
89Each restart follows the release feed and applies the newest compatible,
90checksum-verified runtime. The quiet startup path does not prefetch in the
91background. Feed outages retain the installed runtime; incompatible base-image
92requirements or corrupt downloads fail startup. For a new image, review the bundle
93and update `service/knife/bundle.json`, then use the normal stage → main → prod
94workflow. Runtime downloads under `data/runtime/knife-container` survive an infra
95image rollback; rolling back code does not restore state or archive objects.
1# Retired Knife archive
2
3The retired Nomad service's `globe/prod/knife` dataset remains mounted at
4`/srv/prod/knife`. Keep `data` and `archives` together, including the archive
5store identity and assigned service UID. Snapshot `knife-retired-20261019T213553Z`
6has the `knife-archive-retention` hold; private retirement evidence is in
7`/var/lib/snowglobe/retirements/knife/`. Later deployment backups omit retired
8jobs, so retain the held snapshot and evidence separately.