| author | |
| committer | |
| log | 2eaf043d3ab4571bfc809b8777bd24ecc8326c5d |
| tree | 2705b8689b66bf8fdae90370df1cf6c994943066 |
| parent | 12e0e05ea6505d47807eb7f08e12f9458b0c786a |
| signature | Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU |
Preserve its archive recovery record and storage.
Assisted-by: gpt-6.1-terra6 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 @@ |
| 1 | PRETTY_HOSTNAME="snow globe" |
service/knife/prepare.py deleted-59| ... | ... | @@ -1,59 +0,0 @@ |
| 1 | #!/usr/bin/env python3 | |
| 2 | import hashlib | |
| 3 | import json | |
| 4 | import os | |
| 5 | from pathlib import Path | |
| 6 | import shutil | |
| 7 | import subprocess | |
| 8 | import sys | |
| 9 | import tarfile | |
| 10 | import tempfile | |
| 11 | import urllib.request | |
| 12 | import uuid | |
| 13 | ||
| 14 | ||
| 15 | bundle = json.loads(Path(__file__).with_name("bundle.json").read_text()) | |
| 16 | if 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 | ||
| 36 | root = Path(json.load(sys.stdin)["hostRoot"]) | |
| 37 | archives = root / "archives" | |
| 38 | mount = subprocess.run( | |
| 39 | ["findmnt", "-rn", "-o", "TARGET,FSTYPE", "--target", str(archives)], | |
| 40 | check=True, capture_output=True, text=True, | |
| 41 | ).stdout.strip() | |
| 42 | if 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") | |
| 44 | marker = archives / ".knife-archive-store-id" | |
| 45 | try: | |
| 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) | |
| 56 | except FileExistsError: | |
| 57 | pass | |
| 58 | if 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 @@ |
| 1 | amends "../../config/Service.pkl" | |
| 2 | ||
| 3 | import "pkl:json" | |
| 4 | import "../../config/OpenID.pkl" as sso | |
| 5 | ||
| 6 | local bundle = (new json.Parser {}).parse(read("bundle.json")) | |
| 7 | ||
| 8 | name = "The Knife" | |
| 9 | enabled = false | |
| 10 | access = "infra-admin" | |
| 11 | requirements { | |
| 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 | } | |
| 18 | stageIsolation = "fresh" | |
| 19 | prepare = "prepare.py" | |
| 20 | ||
| 21 | container { | |
| 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 | |
| 2 | import io | |
| 3 | import json | |
| 4 | from pathlib import Path | |
| 5 | import runpy | |
| 6 | import subprocess | |
| 7 | import tempfile | |
| 8 | import unittest | |
| 9 | from unittest.mock import patch | |
| 10 | import uuid | |
| 11 | ||
| 12 | ||
| 13 | class 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 | ||
| 70 | if __name__ == "__main__": | |
| 71 | unittest.main() |
tools/knife.md+8-95| ... | ... | @@ -1,95 +1,8 @@ |
| 1 | # Knife sign-in and archive storage | |
| 2 | ||
| 3 | The 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 | |
| 6 | state, archive objects, environment identity, and workspaces. The stopped dataset | |
| 7 | has snapshot `knife-retired-20261019T213553Z`, held with | |
| 8 | `knife-archive-retention`. Private verification evidence is in | |
| 9 | `/var/lib/snowglobe/retirements/knife/`. | |
| 10 | ||
| 11 | Keep `data` and `archives` together; archive objects alone are not a complete | |
| 12 | restoration. Preserve the service UID and `archives/.knife-archive-store-id`. | |
| 13 | Retirement does not delete or migrate any conversations. The disposable preview | |
| 14 | was removed on 2026-10-19. | |
| 15 | Later deployment backups omit retired jobs; retain the held snapshot and private | |
| 16 | retirement evidence separately from routine release-backup retention. | |
| 17 | ||
| 18 | ## Restoring service access | |
| 19 | ||
| 20 | Re-enabling the service requires a deliberate production deployment. After that, | |
| 21 | open https://knife.paperclover.net and sign in through Snow Globe. The server | |
| 22 | accepts only the configured issuer and Clover's immutable owner subject. The NAS | |
| 23 | environment is **snow globe**. Provider accounts can stay on each laptop; the NAS | |
| 24 | needs none for archive storage or outbound environment routing. | |
| 25 | ||
| 26 | On each machine, install the current Knife desktop release, choose its | |
| 27 | self-hosted server connection, enter `https://knife.paperclover.net`, and complete | |
| 28 | browser sign-in. The desktop returns through its proof-bound application callback; | |
| 29 | only the server's HTTPS callback is registered with Snow Globe. Laptop connections | |
| 30 | run outbound through Knife, with archive offload enabled automatically. No laptop | |
| 31 | port forwarding, SSH pairing, bearer-token file, or manual hub enrollment is needed | |
| 32 | for the SSO connection. | |
| 33 | ||
| 34 | Archive a disposable conversation first, reopen its cold transcript, then unarchive | |
| 35 | it. Confirm that its source connection and archive queue report success before | |
| 36 | relying on offload for existing history. A sleeping laptop cannot run interactive | |
| 37 | agents; uploaded archives remain on the NAS. Successful offload reclaims local | |
| 38 | SQLite pages after publication. Native provider history files remain on the laptop. | |
| 39 | ||
| 40 | ## Access and recovery | |
| 41 | ||
| 42 | SSO access credentials last fifteen minutes, with rotating device credentials in | |
| 43 | operating-system protected storage. Browser sign-in is required again after thirty | |
| 44 | days. The server revalidates the issuer grant during renewal at least hourly; | |
| 45 | issuer revocation can therefore take an hour plus fifteen minutes to fully apply. | |
| 46 | Local device revocation disables renewal and closes active connections immediately. | |
| 47 | ||
| 48 | Existing manual pairing credentials survive the upgrade. Manage them separately | |
| 49 | from SSO devices under access settings; do not share pairing links or bearer tokens. | |
| 50 | The listener binds only to loopback behind HTTPS, with WebSocket proxying. Hosted | |
| 51 | SSO cookies are Secure, HttpOnly, SameSite=Lax and protected against cross-origin | |
| 52 | writes. | |
| 53 | ||
| 54 | For local recovery, derive the current container from Nomad rather than retaining | |
| 55 | an allocation ID: | |
| 56 | ||
| 57 | ```sh | |
| 58 | ssh -p 22 root@10.0.0.1 | |
| 59 | export NOMAD_TOKEN="$(cat /var/lib/snowglobe/nomad.token)" | |
| 60 | knife_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])') | |
| 61 | knife_container="app-$knife_allocation" | |
| 62 | podman exec "$knife_container" knife auth devices revoke-all | |
| 63 | ``` | |
| 64 | ||
| 65 | This revokes SSO devices and sessions without contacting the issuer. It preserves | |
| 66 | the configured owner, identity-provider account, archives, and manual pairing | |
| 67 | credentials. 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 | ||
| 73 | The existing managed ZFS dataset `/srv/prod/knife` holds `data`, `archives`, | |
| 74 | `home/node`, and `workspaces`. Keep state and archives together in backups. Preserve | |
| 75 | its assigned service UID and environment identity across image upgrades. | |
| 76 | ||
| 77 | Nomad owns the confidential client secret at `nomad/jobs/knife/inputs/oidc`. | |
| 78 | The 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 | |
| 80 | configuration contains the public issuer, callback, and immutable owner subject, | |
| 81 | with references to the private Nomad values. Preview allocations use their own | |
| 82 | registered clients and disposable state. | |
| 83 | ||
| 84 | Preparation creates `archives/.knife-archive-store-id` exclusively on the confirmed | |
| 85 | service ZFS mount, preserving any existing marker. Startup supplies its value as | |
| 86 | `T3CODE_ARCHIVE_STORE_ID`. Missing or mismatched identity blocks archive publication | |
| 87 | and local payload eviction; never replace the marker to silence that failure. | |
| 88 | ||
| 89 | Each restart follows the release feed and applies the newest compatible, | |
| 90 | checksum-verified runtime. The quiet startup path does not prefetch in the | |
| 91 | background. Feed outages retain the installed runtime; incompatible base-image | |
| 92 | requirements or corrupt downloads fail startup. For a new image, review the bundle | |
| 93 | and update `service/knife/bundle.json`, then use the normal stage → main → prod | |
| 94 | workflow. Runtime downloads under `data/runtime/knife-container` survive an infra | |
| 95 | image rollback; rolling back code does not restore state or archive objects. | |
| 1 | # Retired Knife archive | |
| 2 | ||
| 3 | The retired Nomad service's `globe/prod/knife` dataset remains mounted at | |
| 4 | `/srv/prod/knife`. Keep `data` and `archives` together, including the archive | |
| 5 | store identity and assigned service UID. Snapshot `knife-retired-20261019T213553Z` | |
| 6 | has the `knife-archive-retention` hold; private retirement evidence is in | |
| 7 | `/var/lib/snowglobe/retirements/knife/`. Later deployment backups omit retired | |
| 8 | jobs, so retain the held snapshot and evidence separately. |