proxy-manager: nginx proxy manager in officer

reads hosts and certificates against a live NPM 2.15.1. one grantable permission, with /_config owner-only — reading which hosts are healthy is worth sharing, an NPM admin login is not, and NPM has no read-only role. the quirk that shapes the whole plugin: NPM answers an unauthenticated read with 404, not 401, because its router only registers a resource once a token is present. so 'not signed in' and 'no such endpoint' are the same response, and a naive client tells you a feature is missing when your password is wrong. the client mints a fresh token and retries once, then reports a persistent 404 as likelyAuth. certificates sort by expiry rather than name, which is the only ordering that answers a question. no create/edit/delete and no cert issuance: NPM's own UI does those and a wrong proxy host takes a domain off the internet. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-25 08:38:15 +00:00
commit 5914e96cf3
12 changed files with 1155 additions and 0 deletions
@@ -0,0 +1,100 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { RefreshCw, ShieldAlert, ShieldCheck } from "lucide-react";
+import { useClient } from "hooks/useClient";
+
+/**
+ * Certificates, ordered by how soon they expire.
+ *
+ * That ordering is the whole design. A certificate list sorted by name is a reference; sorted by expiry
+ * it answers the only question anybody has, which is whether something is about to break. The server
+ * computes `daysUntilExpiry` so the browser is not parsing dates and getting the timezone wrong.
+ */
+
+type Certificate = {
+  id: number;
+  provider: string;
+  nice_name: string;
+  domain_names: string[];
+  expires_on: string | null;
+  daysUntilExpiry: number | null;
+};
+
+/** Let's Encrypt renews at 30 days, so inside 14 something has actually gone wrong. */
+const WARN_DAYS = 30;
+const URGENT_DAYS = 14;
+
+export const CertificatesPanel = () => {
+  const client = useClient();
+  const clientRef = useRef(client);
+  clientRef.current = client;
+
+  const [certificates, setCertificates] = useState<Certificate[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    try {
+      setCertificates(await clientRef.current.get<Certificate[]>("/proxy-manager/certificates"));
+      setError(null);
+    } catch (caught) {
+      const body = (caught as { body?: { error?: string } })?.body;
+      setError(body?.error ?? "Could not load certificates.");
+      setCertificates(null);
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  if (error) return <Centred>{error}</Centred>;
+  if (!certificates) return <Centred>Loading certificates…</Centred>;
+  if (certificates.length === 0) return <Centred>No certificates.</Centred>;
+
+  const expiring = certificates.filter((c) => c.daysUntilExpiry !== null && c.daysUntilExpiry < WARN_DAYS).length;
+
+  return (
+    <div className="flex size-full flex-col">
+      <header className="flex items-center justify-between border-b px-3 py-2">
+        <span className="text-sm font-medium">
+          {certificates.length} certificate{certificates.length === 1 ? "" : "s"}
+          {expiring > 0 ? <span className="ml-2 text-xs text-amber-500">{expiring} expiring</span> : null}
+        </span>
+        <button type="button" onClick={() => void load()} className="text-muted-foreground hover:text-foreground">
+          <RefreshCw className="size-4" />
+        </button>
+      </header>
+
+      <ul className="flex-1 overflow-auto">
+        {certificates.map((certificate) => {
+          const days = certificate.daysUntilExpiry;
+          const urgent = days !== null && days < URGENT_DAYS;
+          const warn = days !== null && days < WARN_DAYS;
+          return (
+            <li key={certificate.id} className="flex items-center gap-2 border-b px-3 py-2">
+              {warn ? (
+                <ShieldAlert className={`size-4 shrink-0 ${urgent ? "text-destructive" : "text-amber-500"}`} />
+              ) : (
+                <ShieldCheck className="size-4 shrink-0 text-emerald-500" />
+              )}
+              <span className="min-w-0 flex-1">
+                <span className="block truncate text-sm">{certificate.nice_name}</span>
+                <span className="block truncate text-xs text-muted-foreground">
+                  {certificate.domain_names.join(", ")}
+                </span>
+              </span>
+              <span className={`shrink-0 text-xs ${urgent ? "text-destructive" : warn ? "text-amber-500" : "text-muted-foreground"}`}>
+                {days === null ? certificate.provider : days < 0 ? `expired ${-days}d ago` : `${days}d`}
+              </span>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+};
+
+const Centred = ({ children }: { children: React.ReactNode }) => (
+  <div className="flex size-full items-center justify-center p-6 text-center text-sm text-muted-foreground">
+    {children}
+  </div>
+);
@@ -0,0 +1,194 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { AlertTriangle, Globe, Lock, LockOpen, Power, RefreshCw, ShieldCheck, Users } from "lucide-react";
+import { useClient } from "hooks/useClient";
+import { useSearchParams } from "react-router";
+
+/**
+ * The proxy hosts, which is the thing anybody opens this plugin to see.
+ *
+ * Selection lives in the URL (`?host=<id>`), not in a channel — `docs/navigation-audit.md` is the
+ * authority and this is the case it names: the detail panel reads the same parameter rather than being
+ * handed the id through a bus.
+ */
+
+type ProxyHost = {
+  id: number;
+  domain_names: string[];
+  forward_scheme: string;
+  forward_host: string;
+  forward_port: number;
+  enabled: number;
+  ssl_forced: number;
+  certificate_id: number;
+  access_list_id: number;
+  meta?: { nginx_online?: boolean; nginx_err?: string | null };
+};
+
+type Failure = { error: string; likelyAuth?: boolean; unreachable?: boolean; unconfigured?: boolean };
+
+export const HostsPanel = () => {
+  const client = useClient();
+  // useClient() rebuilds its verbs every render, so it must not sit in a dependency list.
+  const clientRef = useRef(client);
+  clientRef.current = client;
+
+  const [hosts, setHosts] = useState<ProxyHost[] | null>(null);
+  const [failure, setFailure] = useState<Failure | null>(null);
+  const [busy, setBusy] = useState<number | null>(null);
+  const [params, setParams] = useSearchParams();
+  const selected = params.get("host");
+
+  const load = useCallback(async () => {
+    try {
+      setHosts(await clientRef.current.get<ProxyHost[]>("/proxy-manager/hosts"));
+      setFailure(null);
+    } catch (error) {
+      const body = (error as { body?: Failure })?.body;
+      setFailure(body ?? { error: error instanceof Error ? error.message : "Could not load hosts." });
+      setHosts(null);
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const toggle = async (host: ProxyHost) => {
+    setBusy(host.id);
+    try {
+      await clientRef.current.post(`/proxy-manager/hosts/${host.id}/${host.enabled ? "disable" : "enable"}`, {});
+      await load();
+    } catch {
+      setFailure({ error: `Could not ${host.enabled ? "disable" : "enable"} that host.` });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  if (failure) return <Failed failure={failure} onRetry={() => void load()} />;
+  if (!hosts) return <Centred>Loading hosts…</Centred>;
+  if (hosts.length === 0) return <Centred>Nginx Proxy Manager has no proxy hosts.</Centred>;
+
+  return (
+    <div className="flex size-full flex-col">
+      <header className="flex items-center justify-between border-b px-3 py-2">
+        <span className="text-sm font-medium">
+          {hosts.length} host{hosts.length === 1 ? "" : "s"}
+        </span>
+        <button type="button" onClick={() => void load()} className="text-muted-foreground hover:text-foreground">
+          <RefreshCw className="size-4" />
+        </button>
+      </header>
+
+      <ul className="flex-1 overflow-auto">
+        {hosts.map((host) => {
+          const offline = host.meta?.nginx_online === false;
+          return (
+            <li key={host.id}>
+              <button
+                type="button"
+                onClick={() => setParams((p) => { p.set("host", String(host.id)); return p; }, { replace: true })}
+                className={`flex w-full items-center gap-2 border-b px-3 py-2 text-left hover:bg-muted/50 ${
+                  selected === String(host.id) ? "bg-muted" : ""
+                } ${host.enabled ? "" : "opacity-50"}`}
+              >
+                <Globe className="size-4 shrink-0 text-muted-foreground" />
+
+                <span className="min-w-0 flex-1">
+                  <span className="block truncate text-sm">{host.domain_names.join(", ")}</span>
+                  <span className="block truncate text-xs text-muted-foreground">
+                    → {host.forward_scheme}://{host.forward_host}:{host.forward_port}
+                  </span>
+                </span>
+
+                {/* Certificate state, not certificate identity — "is it https" is the question here. */}
+                {host.certificate_id ? (
+                  <Lock className={`size-3.5 shrink-0 ${host.ssl_forced ? "text-emerald-500" : "text-muted-foreground"}`} />
+                ) : (
+                  <LockOpen className="size-3.5 shrink-0 text-amber-500" />
+                )}
+                {host.access_list_id ? <Users className="size-3.5 shrink-0 text-sky-500" /> : null}
+                {offline ? <AlertTriangle className="size-3.5 shrink-0 text-destructive" /> : null}
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+
+      {selected ? (
+        <footer className="border-t p-2">
+          <ToggleButton
+            hosts={hosts}
+            selected={selected}
+            busy={busy}
+            onToggle={(host) => void toggle(host)}
+          />
+        </footer>
+      ) : null}
+    </div>
+  );
+};
+
+const ToggleButton = ({
+  hosts,
+  selected,
+  busy,
+  onToggle,
+}: {
+  hosts: ProxyHost[];
+  selected: string;
+  busy: number | null;
+  onToggle: (host: ProxyHost) => void;
+}) => {
+  const host = hosts.find((h) => String(h.id) === selected);
+  if (!host) return null;
+  return (
+    <button
+      type="button"
+      disabled={busy === host.id}
+      onClick={() => onToggle(host)}
+      className="flex w-full items-center justify-center gap-2 rounded-md border px-3 py-1.5 text-sm hover:bg-muted disabled:opacity-50"
+    >
+      <Power className="size-4" />
+      {busy === host.id ? "Working…" : host.enabled ? "Take out of service" : "Put back in service"}
+    </button>
+  );
+};
+
+/**
+ * NPM answers 404 when unauthenticated, so a naive client shows "not found" for a wrong password. The
+ * server marks that case `likelyAuth`; this turns it into a sentence that points somewhere useful.
+ */
+const Failed = ({ failure, onRetry }: { failure: Failure; onRetry: () => void }) => (
+  <div className="flex size-full flex-col items-center justify-center gap-3 p-6 text-center">
+    <ShieldCheck className="size-8 text-muted-foreground" />
+    {failure.unconfigured ? (
+      <>
+        <p className="text-sm text-muted-foreground">No Nginx Proxy Manager connection is set.</p>
+        <p className="max-w-xs text-xs text-muted-foreground">The owner sets it in this plugin's settings.</p>
+      </>
+    ) : failure.likelyAuth ? (
+      <>
+        <p className="text-sm text-muted-foreground">Nginx Proxy Manager refused the credential.</p>
+        <p className="max-w-xs text-xs text-muted-foreground">
+          Its API answers 404 when unauthenticated, so this is almost always a wrong identity or secret rather than a
+          missing endpoint.
+        </p>
+      </>
+    ) : failure.unreachable ? (
+      <>
+        <p className="text-sm text-muted-foreground">Nginx Proxy Manager is not answering.</p>
+        <p className="max-w-xs text-xs text-muted-foreground">{failure.error}</p>
+      </>
+    ) : (
+      <p className="max-w-xs text-sm text-muted-foreground">{failure.error}</p>
+    )}
+    <button type="button" onClick={onRetry} className="flex items-center gap-1 text-xs hover:text-foreground">
+      <RefreshCw className="size-3" /> try again
+    </button>
+  </div>
+);
+
+const Centred = ({ children }: { children: React.ReactNode }) => (
+  <div className="flex size-full items-center justify-center p-6 text-sm text-muted-foreground">{children}</div>
+);
@@ -0,0 +1,13 @@
+import type { LayoutNode } from 'officerdev';
+
+// Hosts wide, certificates beside it. Certificates is a glance rather than a workspace — you look at it
+// when something is red — so it gets the narrower half.
+export const defaultLayout: LayoutNode = {
+  type: 'group',
+  id: 'proxy-manager-root',
+  direction: 'horizontal',
+  children: [
+    { node: { type: 'panel', id: 'proxy-manager-hosts', appType: 'proxy-manager-hosts' }, size: 62 },
+    { node: { type: 'panel', id: 'proxy-manager-certificates', appType: 'proxy-manager-certificates' }, size: 38 },
+  ],
+};
@@ -0,0 +1,19 @@
+import { Route, ShieldCheck } from 'lucide-react';
+import type { AppRegistryMeta } from 'officerdev';
+import { HostsPanel } from './HostsPanel';
+import { CertificatesPanel } from './CertificatesPanel';
+
+// Two panels. Hosts is what the plugin is for; certificates is the thing that quietly breaks and is
+// worth seeing beside it rather than a click away.
+//
+// `availableOnPanel: false` — these belong to this plugin's screen, not to the generic panel picker.
+export const appRegistryMetas: AppRegistryMeta[] = [
+  { key: 'proxy-manager-hosts', name: 'Hosts', icon: Route, component: HostsPanel, availableOnPanel: false },
+  {
+    key: 'proxy-manager-certificates',
+    name: 'Certificates',
+    icon: ShieldCheck,
+    component: CertificatesPanel,
+    availableOnPanel: false,
+  },
+];