From f196bd50ba5949964a1faa0ffbbe8132963bb9c9 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sat, 10 Oct 2026 20:20:08 +0000 Subject: [PATCH] feat(https): set HTTPS up in Settings and open its ports from the web app Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01YB1b1hox6iFRdfWcpoKZwK --- CHANGELOG.md | 4 +- docs/https.md | 15 +- fastapi_backend/app/api/v1/routes/admin.py | 27 +- fastapi_backend/app/domain/updates.py | 26 +- fastapi_backend/app/schemas/admin.py | 8 + fastapi_backend/app/schemas/updates.py | 3 +- fastapi_backend/tests/api/test_https.py | 62 +++++ .../__tests__/httpsSettings.test.tsx | 152 ++++++++++ nextjs-frontend/app/openapi-client/index.ts | 6 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 22 ++ .../app/openapi-client/types.gen.ts | 64 ++++- .../components/settings/bodies.tsx | 259 +++++++++++++++++- nextjs-frontend/components/settings/model.ts | 157 +++++++++++ .../components/settings/settings-shell.tsx | 2 + nextjs-frontend/openapi.json | 107 +++++++- packaging/host/lens-upgrade.sh | 10 +- 16 files changed, 906 insertions(+), 18 deletions(-) create mode 100644 nextjs-frontend/__tests__/httpsSettings.test.tsx diff --git a/CHANGELOG.md b/CHANGELOG.md index 176d51f97..940d1bd4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -120,8 +120,8 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version - **HTTPS with automatic certificates.** Lens can serve itself at `https://` your domain with a certificate it gets and renews on its own from Let's Encrypt or ZeroSSL (or any ACME authority), proving the domain over HTTP, TLS-ALPN or DNS, with Cloudflare, Route 53 and the other caddy-dns providers, so wildcards and machines the internet can't - reach work too. Run the install line with `LENS_HTTPS=1` to open ports 443 and 80, then set it up with - `PUT /api/v1/settings/https`; the Settings page comes next. Off by default ([HTTPS](docs/https.md)). + reach work too. Set it up in **Settings › HTTPS**, whose **Open the HTTPS ports** has the machine open 443 and 80 + and restart Lens (or run the install line with `LENS_HTTPS=1`). Off by default ([HTTPS](docs/https.md)). - **Budget meter and Costs page.** The top bar shows what the namespace picked spent against its budget, used and left, highlighted when near or over, and follows the namespace switcher; it opens the details for a day, week or diff --git a/docs/https.md b/docs/https.md index 1914c06dd..ad92d67ed 100644 --- a/docs/https.md +++ b/docs/https.md @@ -6,8 +6,7 @@ Lens can serve itself at `https://lens.example.com` with a certificate it gets a renews it about a month before it runs out and passes visitors on to the web app. Passkeys work there, since browsers allow them on https:// addresses. -Status: **built** in the API and the installer; the **Settings › HTTPS** page in the web app is in progress (until -then, `PUT /api/v1/settings/https` sets it). Off by default. +Status: **built**, set up in **Settings › HTTPS**. Off by default. For a machine the internet can't reach at all, [Remote access](remote-access.md) (a Cloudflare tunnel) is the other way to an https:// address. @@ -15,8 +14,10 @@ other way to an https:// address. ## Turning it on 1. Point the domain's DNS at this machine (an A or AAAA record), unless you use the DNS challenge. -2. Give Lens the HTTPS ports: run the install line again with `LENS_HTTPS=1`. It publishes ports 443 and 80 to the - worker, where Caddy runs, and remembers it in `.env`, so upgrades keep them. +2. Give Lens the HTTPS ports: **Open the HTTPS ports** in Settings › HTTPS has the machine's upgrade agent + ([Updates](updates.md)) run install.sh again for the version running, with `LENS_HTTPS=1`, and Lens restarts. Or + run the install line again with it yourself. Either way it publishes ports 443 and 80 to the worker, where Caddy + runs, and remembers it in `.env`, so upgrades keep them. ```sh curl -fsSL https://raw.githubusercontent.com/adeelahmad/lense/main/install.sh | LENS_HTTPS=1 sh @@ -63,7 +64,7 @@ its fields as JSON. `dns_package` names a plugin outside caddy-dns (`github.com/ ## Settings -All in Settings › HTTPS (the `https` section of `PUT /api/v1/settings/https`): +All in Settings › HTTPS (`PUT /api/v1/settings/https`; `POST /api/v1/settings/https/ports` opens the ports): | Key | Default | | | --- | --- | --- | @@ -106,6 +107,6 @@ docker compose -f docker-compose.prod.yml -f docker-compose.https.yml up -d ## Refine later -- A button in Settings that opens the ports through the upgrade agent, so step 2 needs no terminal. -- The install wizard asking for the domain. +- Closing the ports again from Settings (`LENS_HTTPS=0` on the install line does it now). +- The install wizard asking for the domain (left out on purpose: it asks only what's needed to start). - Caddy in the image, for machines that can't download it. diff --git a/fastapi_backend/app/api/v1/routes/admin.py b/fastapi_backend/app/api/v1/routes/admin.py index 8f4f98ae9..0ec3123f2 100644 --- a/fastapi_backend/app/api/v1/routes/admin.py +++ b/fastapi_backend/app/api/v1/routes/admin.py @@ -41,6 +41,7 @@ telemetry, tika, tunnel, + updates, ) from app.schemas.admin import ( AuditEntry, @@ -54,6 +55,7 @@ FileStoreTestResult, FileStoreTry, Health, + HttpsPorts, HttpsProvider, HttpsStatus, IndexQueued, @@ -217,7 +219,30 @@ def tunnel_status(user: AdminReader, cfg: Cfg, db: Db) -> TunnelStatus: def https_status(user: AdminReader, cfg: Cfg, db: Db) -> HttpsStatus: """How HTTPS (Settings › HTTPS) is doing: whether a process has the HTTPS ports and runs Caddy, the certificates it holds and when they run out, and Caddy's last lines.""" - return HttpsStatus(**https.status(db, cfg)) + return _https_status(db, cfg) + + +def _https_status(db, cfg) -> HttpsStatus: + run = updates.run_state(db) + return HttpsStatus( + **https.status(db, cfg), + agent=updates.agent(), + manual=updates.manual_https(cfg, True), + reconfigure=run if run and run.get("https") is not None else None, + ) + + +@router.post("/settings/https/ports", status_code=202) +def https_ports(user: AdminWriter, cfg: Cfg, db: Db, body: HttpsPorts | None = None) -> HttpsStatus: + """Open (or close) the HTTPS ports: this machine's upgrade agent runs install.sh again for the version running, + with LENS_HTTPS=1 (or 0), and Lens restarts. Without an agent, `manual` is the line to run there instead.""" + body = body or HttpsPorts() + try: + updates.reconfigure(db, cfg, body.open, by=user.email) + except updates.UpdateError as e: + raise HTTPException(409, str(e)) from None + auth.audit(db, user.as_audit(), "https.ports", None, {"open": body.open}) + return _https_status(db, cfg) @router.get("/settings/https/providers") diff --git a/fastapi_backend/app/domain/updates.py b/fastapi_backend/app/domain/updates.py index 777ede171..52318104a 100644 --- a/fastapi_backend/app/domain/updates.py +++ b/fastapi_backend/app/domain/updates.py @@ -247,6 +247,29 @@ def upgrade(db, cfg, ref=None, by=None, backup=True, wait=False): return run_state(db) +def reconfigure(db, cfg, https, by=None, wait=False): + """Have this machine run install.sh again for the version it runs, with the HTTPS ports opened (https=True) or + closed (docs/https.md). Lens restarts; nothing else changes. Returns the run.""" + if not agent(): + raise UpdateError("this machine has no upgrade agent; run the line shown instead") + run = run_state(db) or {} + if run.get("state") in ACTIVE and not run.get("error"): + raise UpdateError("an upgrade is already under way; try again when it's done") + run = {"id": secrets.token_hex(8), "ref": "", "https": bool(https), "by": by, "state": "queued", "asked_at": _ts(), "error": None} + _put(db, upgrade=run) + t = threading.Thread(target=_hand_over, args=(db, run, False), daemon=True, name="reconfigure") + t.start() + if wait: + t.join() + return run_state(db) + + +def manual_https(cfg, https): + """The line that opens (or closes) the HTTPS ports by hand, on the machine Lens runs on.""" + line = manual(cfg) + return f"{line[: -len(' sh')]} LENS_HTTPS={1 if https else 0} sh" + + def _hand_over(db, run, backup): try: if backup: @@ -256,7 +279,8 @@ def _hand_over(db, run, backup): run["backup"] = dst.name inbox = control_dir() / "inbox" part = inbox / f".upgrade.{run['id']}" - part.write_text(f"id={run['id']}\nref={run['ref']}\nby={run.get('by') or ''}\nat={_ts()}\n", encoding="utf-8") + extra = f"https={1 if run['https'] else 0}\n" if run.get("https") is not None else "" + part.write_text(f"id={run['id']}\nref={run['ref']}\n{extra}by={run.get('by') or ''}\nat={_ts()}\n", encoding="utf-8") part.replace(inbox / "upgrade") run.update(state="queued", queued_at=_ts()) except Exception as e: # noqa: BLE001 - the admin reads why diff --git a/fastapi_backend/app/schemas/admin.py b/fastapi_backend/app/schemas/admin.py index 755ad1764..47fa22ef1 100644 --- a/fastapi_backend/app/schemas/admin.py +++ b/fastapi_backend/app/schemas/admin.py @@ -7,6 +7,7 @@ from pydantic import Field from app.schemas.common import Ok, RequestModel, ResponseModel +from app.schemas.updates import UpgradeRun class Started(Ok): @@ -101,6 +102,13 @@ class HttpsStatus(ResponseModel): log: list[str] = Field(default_factory=list, description="Caddy's last lines") origin: str = Field(description="where Caddy sends visitors: the web app, as the server reaches it") process: str | None = Field(None, description="the server process with the HTTPS ports") + agent: str | None = Field(None, description="what can open the ports from here (the upgrade agent: systemd, launchd)") + manual: str = Field(description="the line that opens the ports by hand, on the machine Lens runs on") + reconfigure: UpgradeRun | None = Field(None, description="the last run that opened or closed the ports (as in /admin/updates)") + + +class HttpsPorts(RequestModel): + open: bool = Field(True, description="open the HTTPS ports (true) or close them") class HttpsProviderField(ResponseModel): diff --git a/fastapi_backend/app/schemas/updates.py b/fastapi_backend/app/schemas/updates.py index cc927371e..54c19e7c3 100644 --- a/fastapi_backend/app/schemas/updates.py +++ b/fastapi_backend/app/schemas/updates.py @@ -20,7 +20,8 @@ class Release(ResponseModel): class UpgradeRun(ResponseModel): id: str - ref: str = Field(description="the release tag (or branch) being installed") + ref: str = Field(description="the release tag (or branch) being installed; empty: the one running, set up again") + https: bool | None = Field(None, description="the HTTPS ports opened (true) or closed (false) by this run (docs/https.md)") state: Literal["backing-up", "queued", "running", "done", "failed"] by: str | None = None asked_at: str | None = None diff --git a/fastapi_backend/tests/api/test_https.py b/fastapi_backend/tests/api/test_https.py index 9178149c6..38c1e1c73 100644 --- a/fastapi_backend/tests/api/test_https.py +++ b/fastapi_backend/tests/api/test_https.py @@ -7,6 +7,8 @@ import datetime as dt import json import pathlib +import shutil +import subprocess import sys import textwrap import time @@ -288,3 +290,63 @@ def test_passkeys_and_email_links_use_the_https_address(app, client, db, cfg, mo db.next_id("settings") # the app's settings are read again o = client.post("/api/v1/auth/passkey/options", headers={"x-forwarded-host": "lens.example.com", "x-forwarded-proto": "https"}) assert o.json()["options"]["rpId"] == "localhost" + + +@pytest.fixture +def control(tmp_path, monkeypatch): + """The control folder install.sh shares with the containers, with an upgrade agent watching it.""" + d = tmp_path / "control" + (d / "inbox").mkdir(parents=True) + (d / "agent").write_text("kind=systemd\n") + monkeypatch.setenv("LENS_CONTROL_DIR", str(d)) + return d + + +def test_the_ports_are_opened_by_the_upgrade_agent(client, db, control, monkeypatch): + make_user(db, "root@x.io", "root password 1", admin=True) + a = login(client, "root@x.io", "root password 1") + s = client.get("/api/v1/settings/https/status", headers=a).json() + assert s["agent"] == "systemd" and "LENS_HTTPS=1 sh" in s["manual"] and s["reconfigure"] is None + r = client.post("/api/v1/settings/https/ports", headers=a, json={"open": True}) + assert r.status_code == 202, r.text + for _ in range(100): # handed over after the response + if (control / "inbox" / "upgrade").exists(): + break + time.sleep(0.02) + req = dict(line.split("=", 1) for line in (control / "inbox" / "upgrade").read_text().splitlines()) + assert req["ref"] == "" and req["https"] == "1" # the version running, set up again with the ports + run = client.get("/api/v1/settings/https/status", headers=a).json()["reconfigure"] + assert run["https"] is True and run["state"] == "queued" and run["id"] == req["id"] + assert client.post("/api/v1/settings/https/ports", headers=a, json={"open": False}).status_code == 409 # one at a time + monkeypatch.delenv("LENS_CONTROL_DIR") + r = client.post("/api/v1/settings/https/ports", headers=a, json={"open": True}) + assert r.status_code == 409 and "run the line shown" in r.json()["detail"] + + +AGENT = pathlib.Path(__file__).resolve().parents[3] / "packaging" / "host" / "lens-upgrade.sh" + + +@pytest.mark.skipif(not shutil.which("git"), reason="needs git") +def test_the_agent_sets_up_the_version_running_with_the_ports(tmp_path): + """packaging/host/lens-upgrade.sh, with an install.sh that writes down what it was given.""" + d = tmp_path / "lens" + d.mkdir() + (d / "install.sh").write_text('echo "ref=$LENS_REF https=$LENS_HTTPS" > "$LENS_DIR/ran"\n') + (d / ".env").write_text("LENS_HTTPS=0\n") + git = ["git", "-C", str(d), "-c", "user.name=t", "-c", "user.email=t@x.io"] + subprocess.run([*git, "init", "-q", "-b", "main"], check=True) + subprocess.run([*git, "add", "."], check=True) + subprocess.run([*git, "commit", "-q", "-m", "x"], check=True) + (d / ".lens-control" / "inbox").mkdir(parents=True) + + def run(request): + (d / ".lens-control" / "inbox" / "upgrade").write_text(request) + subprocess.run(["sh", str(AGENT), str(d)], check=True, capture_output=True) + return (d / "ran").read_text().strip(), (d / ".lens-control" / "upgrade-status").read_text() + + ran, st = run("id=a1\nref=\nhttps=1\n") + assert ran == "ref=main https=1" and "state=done" in st + ran, _ = run("id=a2\nref=main\n") # an upgrade keeps what .env says + assert ran == "ref=main https=0" + ran, _ = run("id=a3\nref=\nhttps=yes; rm -rf /\n") # nothing but 0 or 1 + assert ran == "ref=main https=0" diff --git a/nextjs-frontend/__tests__/httpsSettings.test.tsx b/nextjs-frontend/__tests__/httpsSettings.test.tsx new file mode 100644 index 000000000..34a63872d --- /dev/null +++ b/nextjs-frontend/__tests__/httpsSettings.test.tsx @@ -0,0 +1,152 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { fireEvent, render, screen, waitFor } from "@testing-library/react"; +import "@testing-library/jest-dom"; + +import { Admin } from "@/app/openapi-client"; +import { crossErrors, type SettingsView } from "@/components/settings/model"; +import { SettingsSection } from "@/components/settings/section"; +import { TooltipProvider } from "@/components/ui/tooltip"; + +jest.mock("@/app/openapi-client", () => ({ + Admin: { updateSettings: jest.fn(), httpsStatus: jest.fn(), httpsProviders: jest.fn(), httpsPorts: jest.fn() }, + Metadata: {}, +})); +jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) })); +jest.mock("next/navigation", () => ({ useRouter: () => ({ push: jest.fn() }) })); +jest.mock("@/lib/hooks/session", () => ({ useArchive: () => ({ namespaces: [] }) })); +jest.mock("@/components/ui/toast", () => ({ useToast: () => jest.fn() })); + +const ok = (data: unknown) => Promise.resolve({ data, response: { ok: true, status: 200 } }); +const STATUS = { + enabled: true, + running: false, + ports_open: true, + url: "https://lens.example.com", + certificates: [], + error: null, + log: [], + origin: "http://frontend:3000", + process: "worker-1", + agent: null, + manual: + "curl -fsSL https://raw.githubusercontent.com/adeelahmad/lense/main/install.sh | LENS_REF=main LENS_HTTPS=1 sh", + reconfigure: null, +}; +const PROVIDERS = [ + { name: "cloudflare", label: "Cloudflare", fields: [{ name: "api_token", label: "API token", secret: true }] }, +]; +const OFF = { + enabled: false, + domains: [], + email: "", + ca: "both", + ca_url: "", + staging: false, + challenge: "http", + dns_provider: "", + dns_package: "", + dns_credentials: { set: false }, + dns_resolvers: [], + propagation: "", + eab_key_id: "", + eab_hmac_key: { set: false }, + redirect_http: true, + hsts: false, + origin: "", + https_port: 8443, + http_port: 8080, +}; + +function show(values: Record) { + const view = { https: { values } } as unknown as SettingsView; + const qc = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } }); + return render( + + + undefined} /> + + , + ); +} + +describe("Settings › HTTPS", () => { + beforeEach(() => { + (Admin.updateSettings as jest.Mock).mockReset().mockImplementation(() => ok({ ok: true })); + (Admin.httpsStatus as jest.Mock).mockReset(); + (Admin.httpsProviders as jest.Mock).mockReset().mockImplementation(() => ok(PROVIDERS)); + (Admin.httpsPorts as jest.Mock).mockReset(); + }); + + it("shows the address and the certificate once it has one", async () => { + (Admin.httpsStatus as jest.Mock).mockImplementation(() => + ok({ + ...STATUS, + running: true, + certificates: [{ names: ["lens.example.com"], expires: "2027-01-08T00:00:00+00:00", issuer: "Let's Encrypt" }], + }), + ); + show({ ...OFF, enabled: true, domains: ["lens.example.com"] }); + expect(await screen.findByText("Serving over HTTPS.")).toBeInTheDocument(); + expect(screen.getByRole("link", { name: "https://lens.example.com" })).toBeInTheDocument(); + expect(screen.getByText(/Let's Encrypt · until/)).toBeInTheDocument(); + }); + + it("gives the line to run when nothing has the ports and nothing can open them", async () => { + (Admin.httpsStatus as jest.Mock).mockImplementation(() => ok({ ...STATUS, ports_open: false })); + show({ ...OFF, enabled: true, domains: ["lens.example.com"] }); + expect(await screen.findByText("No server process has the HTTPS ports yet.")).toBeInTheDocument(); + expect(screen.getByText(/LENS_HTTPS=1 sh/)).toBeInTheDocument(); + }); + + it("opens the ports through the upgrade agent", async () => { + (Admin.httpsStatus as jest.Mock).mockImplementation(() => ok({ ...STATUS, ports_open: false, agent: "systemd" })); + (Admin.httpsPorts as jest.Mock).mockImplementation(() => + ok({ + ...STATUS, + ports_open: false, + agent: "systemd", + reconfigure: { id: "r1", ref: "", https: true, state: "queued", log: [] }, + }), + ); + show({ ...OFF, enabled: true, domains: ["lens.example.com"] }); + fireEvent.click(await screen.findByRole("button", { name: "Open the HTTPS ports" })); + expect(await screen.findByText("Opening the HTTPS ports.")).toBeInTheDocument(); + expect((Admin.httpsPorts as jest.Mock).mock.calls[0][0]).toMatchObject({ body: { open: true } }); + }); + + it("shows why there's no certificate", async () => { + (Admin.httpsStatus as jest.Mock).mockImplementation(() => + ok({ ...STATUS, running: true, error: "could not get certificate: no valid A records found", log: ["ERROR x"] }), + ); + show({ ...OFF, enabled: true, domains: ["lens.example.com"] }); + expect(await screen.findByText("could not get certificate: no valid A records found")).toBeInTheDocument(); + expect(screen.getByText(/What Caddy said/)).toBeInTheDocument(); + }); + + it("sets up the DNS challenge with Cloudflare", async () => { + (Admin.httpsStatus as jest.Mock).mockImplementation(() => ok({ ...STATUS, enabled: false })); + show(OFF); + expect(await screen.findByText("Off.")).toBeInTheDocument(); + fireEvent.click(screen.getByText("DNS")); + await screen.findByRole("option", { name: "Cloudflare" }); + fireEvent.change(screen.getByLabelText("DNS provider"), { target: { value: "cloudflare" } }); + fireEvent.change(await screen.findByLabelText("API token"), { target: { value: "cf-secret" } }); + fireEvent.click(screen.getByRole("button", { name: "Save" })); + await waitFor(() => expect(Admin.updateSettings).toHaveBeenCalledTimes(1)); + expect((Admin.updateSettings as jest.Mock).mock.calls[0][0]).toMatchObject({ + path: { section: "https" }, + body: { challenge: "dns", dns_provider: "cloudflare", dns_credentials: '{"api_token":"cf-secret"}' }, + }); + }); + + it("checks the domains, the email and the authority's address", () => { + expect(crossErrors({ "https.domains": ["not a domain"] })["https.domains"]).toMatch(/domain/); + expect(crossErrors({ "https.domains": ["*.example.com"], "https.challenge": "http" })["https.domains"]).toMatch( + /DNS/, + ); + expect(crossErrors({ "https.domains": ["*.example.com"], "https.challenge": "dns" })).toEqual({}); + expect(crossErrors({ "https.enabled": true, "https.domains": [] })["https.domains"]).toMatch(/domain/); + expect(crossErrors({ "https.email": "nobody" })["https.email"]).toMatch(/email/); + expect(crossErrors({ "https.ca": "custom", "https.ca_url": "http://x" })["https.ca_url"]).toMatch(/https/); + }); +}); diff --git a/nextjs-frontend/app/openapi-client/index.ts b/nextjs-frontend/app/openapi-client/index.ts index 0e987d26b..533b6fad4 100644 --- a/nextjs-frontend/app/openapi-client/index.ts +++ b/nextjs-frontend/app/openapi-client/index.ts @@ -1333,6 +1333,12 @@ export type { HookItem, HookPushed, HttpsCertificate, + HttpsPorts, + HttpsPortsData, + HttpsPortsError, + HttpsPortsErrors, + HttpsPortsResponse, + HttpsPortsResponses, HttpsProvider, HttpsProviderField, HttpsProvidersData, diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 0b3515647..a0d6ae60b 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -666,6 +666,9 @@ import type { HomeSuggestionsData, HomeSuggestionsErrors, HomeSuggestionsResponses, + HttpsPortsData, + HttpsPortsErrors, + HttpsPortsResponses, HttpsProvidersData, HttpsProvidersResponses, HttpsStatusData, @@ -2678,6 +2681,25 @@ export class Admin { }); } + /** + * Https Ports + * + * Open (or close) the HTTPS ports: this machine's upgrade agent runs install.sh again for the version running, + * with LENS_HTTPS=1 (or 0), and Lens restarts. Without an agent, `manual` is the line to run there instead. + */ + public static httpsPorts( + options?: Options, + ): RequestResult { + return (options?.client ?? client).post({ + url: "/api/v1/settings/https/ports", + ...options, + headers: { + "Content-Type": "application/json", + ...options?.headers, + }, + }); + } + /** * Https Providers * diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 843b729a3..b294112d7 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -6229,6 +6229,18 @@ export type HttpsCertificate = { [key: string]: unknown; }; +/** + * HttpsPorts + */ +export type HttpsPorts = { + /** + * Open + * + * open the HTTPS ports (true) or close them + */ + open?: boolean; +}; + /** * HttpsProvider */ @@ -6323,6 +6335,22 @@ export type HttpsStatus = { * the server process with the HTTPS ports */ process?: string | null; + /** + * Agent + * + * what can open the ports from here (the upgrade agent: systemd, launchd) + */ + agent?: string | null; + /** + * Manual + * + * the line that opens the ports by hand, on the machine Lens runs on + */ + manual: string; + /** + * the last run that opened or closed the ports (as in /admin/updates) + */ + reconfigure?: UpgradeRun | null; [key: string]: unknown; }; @@ -18117,9 +18145,15 @@ export type UpgradeRun = { /** * Ref * - * the release tag (or branch) being installed + * the release tag (or branch) being installed; empty: the one running, set up again */ ref: string; + /** + * Https + * + * the HTTPS ports opened (true) or closed (false) by this run (docs/https.md) + */ + https?: boolean | null; /** * State */ @@ -21248,6 +21282,34 @@ export type HttpsStatusResponses = { export type HttpsStatusResponse = HttpsStatusResponses[keyof HttpsStatusResponses]; +export type HttpsPortsData = { + /** + * Body + */ + body?: HttpsPorts | null; + path?: never; + query?: never; + url: "/api/v1/settings/https/ports"; +}; + +export type HttpsPortsErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type HttpsPortsError = HttpsPortsErrors[keyof HttpsPortsErrors]; + +export type HttpsPortsResponses = { + /** + * Successful Response + */ + 202: HttpsStatus; +}; + +export type HttpsPortsResponse = HttpsPortsResponses[keyof HttpsPortsResponses]; + export type HttpsProvidersData = { body?: never; path?: never; diff --git a/nextjs-frontend/components/settings/bodies.tsx b/nextjs-frontend/components/settings/bodies.tsx index 8a8f47ebc..47431599e 100644 --- a/nextjs-frontend/components/settings/bodies.tsx +++ b/nextjs-frontend/components/settings/bodies.tsx @@ -6,7 +6,7 @@ import Link from "next/link"; import { useEffect, useRef, useState, type ReactNode } from "react"; import { Admin, Fedora, Metadata, Sensors, Shares, Sources, Users } from "@/app/openapi-client"; -import type { MatterbridgeStatus } from "@/app/openapi-client/types.gen"; +import type { HttpsStatus, MatterbridgeStatus } from "@/app/openapi-client/types.gen"; import { MonitoringSwitch } from "@/components/admin/monitoring-switch"; import { BackupsPanel } from "@/components/settings/backups-panel"; import { ComponentsStatus } from "@/components/settings/components-status"; @@ -37,7 +37,7 @@ import { } from "@/components/settings/model"; import { Banner } from "@/components/ui/banner"; import { Button } from "@/components/ui/button"; -import { Select, Switch } from "@/components/ui/field"; +import { Field, Input, Select, Switch } from "@/components/ui/field"; import { Skeleton } from "@/components/ui/states"; import { data, useApiClient } from "@/lib/api/browser"; import { useArchive } from "@/lib/hooks/session"; @@ -325,6 +325,8 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) { return ; case "remote-access": return ; + case "https": + return ; case "components": return ( <> @@ -1360,6 +1362,259 @@ function MailBody({ ctx }: { ctx: BodyCtx }) { ); } +const OTHER_DNS = "__other"; + +/** Settings › HTTPS, when no server process has the HTTPS ports: open them through the upgrade agent (Lens restarts), + * or the line to run on the machine. */ +function HttpsPorts({ + status: s, + open, + busy, + error, +}: { + status: HttpsStatus; + open: () => void; + busy: boolean; + error?: string; +}) { + const run = s.reconfigure; + const going = run && !run.error && ["queued", "running"].includes(run.state); + if (going) + return ( + + Lens is setting itself up again with ports 443 and 80 and restarts; this page follows when it’s back. + {(run.log ?? []).length > 0 && ( +
+            {(run.log ?? []).join("\n")}
+          
+ )} +
+ ); + return ( + + {run?.error && The last try didn’t work: {run.error}} + {error && {error}} + {s.agent ? ( + <> + Lens opens ports 443 and 80 on this machine and restarts, keeping them through upgrades. + + + + + ) : ( + <> + Run this on the machine Lens runs on: it opens ports 443 and 80 and keeps them through upgrades. +
{s.manual}
+ + )} +
+ ); +} + +/** Settings › HTTPS: the domains Lens serves over https://, how it gets their certificates, and how that's going. */ +function HttpsBody({ ctx }: { ctx: BodyCtx }) { + const client = useApiClient(); + const t = ctx.view.https; + const on = ctx.state("https.enabled").value === true; + const challenge = (ctx.state("https.challenge").value as string | undefined) ?? "http"; + const ca = (ctx.state("https.ca").value as string | undefined) ?? "both"; + const provider = ctx.state("https.dns_provider"); + const creds = ctx.state("https.dns_credentials"); + const eab = ctx.state("https.eab_hmac_key"); + const [fields, setFields] = useState>({}); + const [other, setOther] = useState(false); + const status = useQuery({ + queryKey: ["https-status", t?.updated_at ?? null], + queryFn: () => data(Admin.httpsStatus({ client })), + refetchInterval: (q) => + !q.state.data?.enabled ? false : q.state.data.certificates?.length && !q.state.data.error ? 30_000 : 3_000, + }); + const providers = useQuery({ + queryKey: ["https-providers"], + queryFn: () => data(Admin.httpsProviders({ client })), + enabled: challenge === "dns", + staleTime: Infinity, + }); + const qc = useQueryClient(); + const ports = useMutation({ + mutationFn: () => data(Admin.httpsPorts({ client, body: { open: true } })), + onSuccess: (got) => qc.setQueryData(["https-status", t?.updated_at ?? null], got), + }); + const s = status.data; + const secret = (k: string) => Boolean(((t?.values?.[k] ?? {}) as { set?: boolean }).set); + const prov = (provider.value as string | undefined) ?? ""; + const known = providers.data?.find((p) => p.name === prov); + const choice = other || (prov && providers.data && !known) ? OTHER_DNS : prov; + const setField = (name: string, value: string) => { + const next = { ...fields, [name]: value }; + setFields(next); + const filled = Object.fromEntries(Object.entries(next).filter(([, v]) => v.trim() !== "")); + creds.onChange(Object.keys(filled).length ? JSON.stringify(filled) : undefined); + }; + const expiry = (iso: string) => new Date(iso).toLocaleDateString(undefined, { dateStyle: "medium" }); + return ( + <> + {!s || !s.enabled ? ( + + Lens answers over http:// only, or through a proxy or tunnel in front of it. Turn this on to serve it at your + own domain over https://, where passkeys work too. + + ) : !s.ports_open ? ( + ports.mutate()} busy={ports.isPending} error={ports.error?.message} /> + ) : s.error ? ( + + {s.error} + + ) : s.certificates?.length && s.url ? ( + + + {s.url} + + + ) : ( + + Lens starts Caddy and asks the certificate authority within a few seconds. + + )} + {s?.enabled && (s.certificates ?? []).length > 0 && ( +
    + {(s.certificates ?? []).map((c) => ( +
  • + {c.names.join(", ")} · {c.issuer} · until {expiry(c.expires)}, + renewed on its own +
  • + ))} +
+ )} + + + + + {challenge === "dns" && ( + <> + + {({ id }) => ( + setField(f.name, e.target.value)} + /> + )} + + ))} + + ) + )} +

+ Lens fetches a Caddy built with this provider’s plugin the first time. The credentials are kept encrypted + and given to Caddy only in a file only Lens can read. +

+ + )} +
+ More options +
+ + {ca === "custom" && } + {(ca === "both" || ca === "letsencrypt") && } + {ca !== "letsencrypt" && ( +
+ + eab.onChange(x)} + /> +
+ )} + {challenge === "dns" && ( +
+ + +
+ )} + + + +
+ + +
+
+
+ {on && s && (s.log ?? []).length > 0 && ( +
+ + What Caddy said{s.process ? ` (in ${s.process})` : ""} + +
+            {(s.log ?? []).join("\n")}
+          
+
+ )} + + ); +} + /** Settings › Remote access: the Cloudflare tunnel Lens runs, and how it's doing right now. */ function TunnelBody({ ctx }: { ctx: BodyCtx }) { const client = useApiClient(); diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index 078071e60..dbfa79651 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -76,6 +76,7 @@ export type SectionId = | "components" | "access" | "remote-access" + | "https" | "sign-in" | "encryption" | "notifications" @@ -228,6 +229,13 @@ export const SECTIONS: SectionSpec[] = [ description: "Off unless you turn it on. Reach Lens from anywhere at an https:// address through a Cloudflare Tunnel that Lens runs itself: nothing to open on your router.", }, + { + id: "https", + label: "HTTPS", + backend: ["https"], + description: + "Off unless you turn it on. Serve Lens at your own domain over https://, with certificates from Let’s Encrypt or ZeroSSL that Lens gets and renews itself.", + }, { id: "mail", label: "Email", @@ -995,6 +1003,131 @@ export const FIELDS: FieldSpec[] = [ placeholder: "as installed", hint: "Where cloudflared reaches the web app from the server. Leave empty unless you moved it.", }, + // HTTPS (Caddy run by Lens, certificates over ACME) + { section: "https", key: "enabled", label: "Serve Lens over HTTPS", kind: "switch" }, + { + section: "https", + key: "domains", + label: "Domains", + kind: "lines", + mono: true, + placeholder: "lens.example.com", + hint: "One per line. Each one’s DNS points at this machine; *.example.com needs the DNS challenge.", + }, + { + section: "https", + key: "email", + label: "Email for the certificate authority", + kind: "text", + placeholder: "you@example.com", + hint: "Optional. It warns you before a certificate expires; ZeroSSL needs it.", + }, + { + section: "https", + key: "challenge", + label: "How Lens proves the domain is yours", + kind: "cards", + options: [ + { value: "http", label: "HTTP", hint: "Ports 80 or 443 reach this machine from the internet" }, + { value: "tls-alpn", label: "TLS-ALPN", hint: "Only port 443 reaches this machine" }, + { + value: "dns", + label: "DNS", + hint: "Lens adds a TXT record with your DNS provider’s API. Nothing has to reach this machine; wildcards work", + }, + ], + }, + { + section: "https", + key: "ca", + label: "Certificate authority", + kind: "select", + options: [ + { value: "both", label: "Let’s Encrypt, then ZeroSSL" }, + { value: "letsencrypt", label: "Let’s Encrypt" }, + { value: "zerossl", label: "ZeroSSL" }, + { value: "custom", label: "Another ACME authority" }, + ], + }, + { + section: "https", + key: "ca_url", + label: "ACME directory", + kind: "text", + mono: true, + placeholder: "https://ca.example.com/acme/directory", + }, + { + section: "https", + key: "staging", + label: "Use Let’s Encrypt’s staging service", + kind: "switch", + hint: "For trying things out: no rate limits, but browsers don’t trust its certificates.", + }, + { + section: "https", + key: "eab_key_id", + label: "EAB key ID", + kind: "text", + mono: true, + hint: "External account binding, from your account at the authority. ZeroSSL works without it.", + }, + { section: "https", key: "eab_hmac_key", label: "EAB HMAC key", kind: "secret" }, + { + section: "https", + key: "dns_provider", + label: "DNS provider", + kind: "text", + mono: true, + placeholder: "cloudflare", + }, + { + section: "https", + key: "dns_package", + label: "DNS plugin", + kind: "text", + mono: true, + placeholder: "github.com/caddy-dns/", + hint: "Only for a plugin outside caddy-dns.", + }, + { section: "https", key: "dns_credentials", label: "DNS provider’s fields", kind: "secret" }, + { + section: "https", + key: "dns_resolvers", + label: "DNS resolvers", + kind: "lines", + mono: true, + placeholder: "1.1.1.1", + hint: "Optional: where Lens checks that the TXT record is there.", + }, + { + section: "https", + key: "propagation", + label: "Wait for the DNS record", + kind: "text", + mono: true, + placeholder: "2m", + hint: "Optional: how long to wait for the record to spread, like 2m.", + }, + { section: "https", key: "redirect_http", label: "Send http:// to https://", kind: "switch" }, + { + section: "https", + key: "hsts", + label: "Tell browsers to use https:// only (HSTS)", + kind: "switch", + hint: "For a year. Turn it on once HTTPS works: if you turn HTTPS off later, browsers can’t reach the http:// address.", + }, + { + section: "https", + key: "origin", + label: "Web app address for HTTPS", + kind: "text", + mono: true, + placeholder: "as installed", + hint: "Where Caddy reaches the web app from the server. Leave empty unless you moved it.", + }, + { section: "https", key: "https_port", label: "HTTPS port in the container", kind: "int", min: 1, max: 65535 }, + { section: "https", key: "http_port", label: "HTTP port in the container", kind: "int", min: 1, max: 65535 }, // Chat rooms (Matterbridge) { section: "bridge", key: "enabled", label: "Answer in chat rooms", kind: "switch" }, { @@ -3174,6 +3307,30 @@ export function crossErrors(values: Record): Record !TUNNEL_HOST_RX.test(d.replace(/^\*\./, ""))); + if (badDomain) e["https.domains"] = `“${badDomain}” isn’t a domain name like lens.example.com`; + else if (values["https.enabled"] === true && hDomains && hDomains.length === 0) + e["https.domains"] = "Enter the domain Lens is reached at, like lens.example.com"; + else if (values["https.challenge"] !== "dns" && hDomains?.some((d) => d.startsWith("*."))) + e["https.domains"] = "A wildcard name needs the DNS challenge"; + const hEmail = values["https.email"] as string | undefined; + if (hEmail && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(hEmail)) e["https.email"] = "Enter an email address"; + const caUrl = values["https.ca_url"] as string | undefined; + if (values["https.ca"] === "custom" && !/^https:\/\/[^/\s]+/.test(caUrl ?? "")) + e["https.ca_url"] = "Use the authority’s https:// ACME directory"; + const prov = values["https.dns_provider"] as string | undefined; + if ( + values["https.challenge"] === "dns" && + "https.dns_provider" in values && + !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(prov ?? "") + ) + e["https.dns_provider"] = "Choose the DNS provider that holds the domain"; + const prop = values["https.propagation"] as string | undefined; + if (prop && !/^\d+(ms|s|m|h)$/.test(prop)) e["https.propagation"] = "A duration, like 2m"; + const hOrigin = values["https.origin"] as string | undefined; + if (hOrigin && !/^http:\/\/[^/\s]+/.test(hOrigin)) + e["https.origin"] = "Use an http:// address, such as http://frontend:3000"; const otlp = values["telemetry.endpoint"] as string | null | undefined; if (otlp && !URL_RX.test(otlp)) e["telemetry.endpoint"] = "Use an http(s) address, such as http://localhost:4318"; else if (otlp && /\/v1\/(traces|metrics)\/?$/.test(otlp)) diff --git a/nextjs-frontend/components/settings/settings-shell.tsx b/nextjs-frontend/components/settings/settings-shell.tsx index 903c3fe6c..96c96262b 100644 --- a/nextjs-frontend/components/settings/settings-shell.tsx +++ b/nextjs-frontend/components/settings/settings-shell.tsx @@ -40,6 +40,7 @@ import { Hash, PackageCheck, RadioTower, + Lock, Network, ScrollText, } from "lucide-react"; @@ -82,6 +83,7 @@ const ICON: Record = { components: PackageCheck, access: ShieldCheck, "remote-access": Cloud, + https: Lock, "sign-in": LockKeyhole, encryption: FileLock, notifications: Bell, diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 66fae3bc5..84f7eb40d 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -2583,6 +2583,55 @@ } } }, + "/api/v1/settings/https/ports": { + "post": { + "tags": [ + "admin" + ], + "summary": "Https Ports", + "description": "Open (or close) the HTTPS ports: this machine's upgrade agent runs install.sh again for the version running,\nwith LENS_HTTPS=1 (or 0), and Lens restarts. Without an agent, `manual` is the line to run there instead.", + "operationId": "https_ports", + "requestBody": { + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/HttpsPorts" + }, + { + "type": "null" + } + ], + "title": "Body" + } + } + } + }, + "responses": { + "202": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HttpsStatus" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, "/api/v1/settings/https/providers": { "get": { "tags": [ @@ -37324,6 +37373,19 @@ ], "title": "HttpsCertificate" }, + "HttpsPorts": { + "properties": { + "open": { + "type": "boolean", + "title": "Open", + "description": "open the HTTPS ports (true) or close them", + "default": true + } + }, + "additionalProperties": false, + "type": "object", + "title": "HttpsPorts" + }, "HttpsProvider": { "properties": { "name": { @@ -37447,6 +37509,34 @@ ], "title": "Process", "description": "the server process with the HTTPS ports" + }, + "agent": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Agent", + "description": "what can open the ports from here (the upgrade agent: systemd, launchd)" + }, + "manual": { + "type": "string", + "title": "Manual", + "description": "the line that opens the ports by hand, on the machine Lens runs on" + }, + "reconfigure": { + "anyOf": [ + { + "$ref": "#/components/schemas/UpgradeRun" + }, + { + "type": "null" + } + ], + "description": "the last run that opened or closed the ports (as in /admin/updates)" } }, "additionalProperties": true, @@ -37455,7 +37545,8 @@ "enabled", "running", "ports_open", - "origin" + "origin", + "manual" ], "title": "HttpsStatus" }, @@ -57811,7 +57902,19 @@ "ref": { "type": "string", "title": "Ref", - "description": "the release tag (or branch) being installed" + "description": "the release tag (or branch) being installed; empty: the one running, set up again" + }, + "https": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Https", + "description": "the HTTPS ports opened (true) or closed (false) by this run (docs/https.md)" }, "state": { "type": "string", diff --git a/packaging/host/lens-upgrade.sh b/packaging/host/lens-upgrade.sh index 3b54e59f0..f7b5f239a 100755 --- a/packaging/host/lens-upgrade.sh +++ b/packaging/host/lens-upgrade.sh @@ -7,7 +7,8 @@ # how it went into .lens-control/upgrade-status and upgrade.log, which the web app shows. # # It takes a release tag (vX.Y.Z), or the branch this install already follows; nothing else, whoever wrote the -# request. Run by hand: sh packaging/host/lens-upgrade.sh +# request. An empty ref sets up the version running again, as Settings › HTTPS does with https=1 or 0 to open or close +# the HTTPS ports (docs/https.md). Run by hand: sh packaging/host/lens-upgrade.sh # # A request with action=services turns the monitoring containers on or off instead (docs/prometheus.md): it adds or # removes `monitoring` in COMPOSE_PROFILES in .env and starts or stops Prometheus, node-exporter and Grafana, and says @@ -87,6 +88,7 @@ id="$(val id "$REQ")" ref="$(val ref "$REQ")" action="$(val action "$REQ")" monitoring="$(val monitoring "$REQ")" +https="$(val https "$REQ")" rm -f "$REQ" now() { date -u +%Y-%m-%dT%H:%M:%SZ; } env_of() { [ -f "$DIR/.env" ] && sed -n "s/^$1=//p" "$DIR/.env" | head -1; } @@ -108,6 +110,11 @@ started="$(now)" : >"$CTL/upgrade.log" branch="$(git -C "$DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || true)" +if [ -z "$ref" ]; then # the version running: this install's branch, or the release tag it's on + ref="$branch" + [ "$ref" = HEAD ] && ref="$(git -C "$DIR" describe --tags --exact-match 2>/dev/null || true)" +fi +case "$https" in 0 | 1 | "") ;; *) https="" ;; esac if ! printf '%s' "$ref" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' && [ "$ref" != "$branch" ]; then echo "Not upgrading to '$ref': only a release tag (vX.Y.Z) or this install's branch ($branch)." >>"$CTL/upgrade.log" status failed "finished_at=$(now)" "code=2" "error=only a release tag (vX.Y.Z) or this install's branch can be installed" @@ -121,6 +128,7 @@ set +e cd "$DIR" && LENS_DIR="$DIR" LENS_REF="$ref" LENS_NO_OPEN=1 LENS_YES=1 LENS_WIZARD=0 LENS_AGENT_RUN=1 \ LENS_REPO="$(env_of LENS_REPO)" LENS_TARGET="$(env_of LENS_TARGET)" LENS_BACKEND="$(env_of LENS_BACKEND)" \ + LENS_HTTPS="${https:-$(env_of LENS_HTTPS)}" \ GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=safe.directory GIT_CONFIG_VALUE_0="$DIR" \ sh "$DIR/install.sh" ) >>"$CTL/upgrade.log" 2>&1