feat(admin): three-mode auth — BUZZ_ADMIN_AUTH enum + NIP-98 pubkey allowlist

Deletes BUZZ_ADMIN_INSECURE_NO_AUTH. Replaces it with BUZZ_ADMIN_AUTH, a
mode enum with three exact values:

- unset / "token"  — bearer token via BUZZ_ADMIN_TOKEN (unchanged default)
- "disabled"       — no auth; boot WARN retained (replaces INSECURE_NO_AUTH)
- "nip98"          — NIP-98 HTTP Auth via BUZZ_ADMIN_PUBKEYS allowlist

All existing token/disabled invariants carry 1:1 under the new name.
Junk values fail closed at startup with a ConfigError.

NIP-98 mode (admin-moderation scope):
- Parses BUZZ_ADMIN_PUBKEYS as comma-separated 64-hex pubkeys (deduped).
- BUZZ_ADMIN_PUBKEYS required non-empty in nip98 mode; warn-and-ignore in
  token/disabled modes. BUZZ_ADMIN_TOKEN + nip98 = ConfigError.
- authorize_nip98(): single Authorization: Nostr <base64 event> header,
  verify_nip98_event, deployment-scoped replay guard (admin-moderation),
  allowlist membership check. Uniform 401 on all failures; no oracle.
- WWW-Authenticate: Nostr on 401 (Bearer stays in token mode) — the SPA
  uses this header to discover the auth mode.
- Canonical URL: https://<BUZZ_ADMIN_HOST>/api/admin/v1<stripped-path>;
  http:// for loopback hosts (local dev). Axum strips the prefix before
  handlers; ADMIN_API_PREFIX constant re-adds it for NIP-98 verification.

SPA (admin-web):
- probeAuthMode() reads WWW-Authenticate: Bearer/Nostr/absent to return
  "token" | "nip98" | "disabled".
- nip98 mode: signNip98() helper builds kind-27235 events via window.nostr
  (NIP-07); send() attaches Authorization: Nostr per request.
- Nip07Screen: shown when nip98 mode is detected but window.nostr is absent;
  instructs operator to install nos2x or Alby.
- 401 in nip98 mode re-signs once then surfaces the error (no infinite loop).

Docs/config:
- docs/admin/README.md rewritten to three-mode shape; migration note from
  BUZZ_ADMIN_INSECURE_NO_AUTH.
- Both .env.example files updated (root and deploy/compose/).
- CHANGELOG.md Unreleased sections updated with three-mode description.

Tests:
- Config matrix: all mode values, junk, every mutual exclusion,
  missing/invalid BUZZ_ADMIN_PUBKEYS.
- NIP-98 route tests: wrong pubkey → 401, replay → 401, wrong u/method →
  401, duplicate Authorization → 401, valid → 200, valid + wrong host → 403.
- Regression pins: token-mode and disabled-mode behavior unchanged.
- Playwright: nip98 mode without NIP-07 → instruction screen; mocked
  window.nostr happy path signs requests and renders dashboard.

Co-authored-by: Will Pfleger <pfleger.will@gmail.com>
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>

Author: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7

.env.example

@@ -67,16 +67,25 @@ RELAY_URL=ws://localhost:3000
 # Setting it requires one of the two authentication variables below.
 # BUZZ_ADMIN_HOST=admin.localhost:3000
 #
-# Option A — Bearer token (recommended for public-facing / OSS deployments):
+# Authentication mode. Accepted values: token (default), disabled, nip98.
+# Any other value is a startup error.
+# BUZZ_ADMIN_AUTH=token
+#
+# Option A — BUZZ_ADMIN_AUTH=token (default when unset):
 # Exactly 64 hex characters (32 bytes); generate with `openssl rand -hex 32`.
 # `just admin` generates a throwaway one per run and prints it.
 # BUZZ_ADMIN_TOKEN=<64 hex characters>
 #
-# Option B — Network-layer auth (for deployments behind a VPN or firewall):
-# Set only when the admin API is already protected at the network layer.
-# The relay logs a WARN on every startup in this mode.
-# Only the exact value "true" is accepted; any other non-empty value fails.
-# BUZZ_ADMIN_INSECURE_NO_AUTH=true
+# Option B — BUZZ_ADMIN_AUTH=disabled (network-layer auth only):
+# Set only when the admin API is already protected at the network layer
+# (VPN, private ingress). The relay logs a WARN on every startup.
+# BUZZ_ADMIN_TOKEN must NOT also be set.
+#
+# Option C — BUZZ_ADMIN_AUTH=nip98 (Nostr pubkey allowlist):
+# NIP-98 HTTP Auth. Each request must carry an Authorization: Nostr header
+# with a signed kind-27235 event. The signer's pubkey must be in
+# BUZZ_ADMIN_PUBKEYS. The dashboard requires a NIP-07 browser extension.
+# BUZZ_ADMIN_PUBKEYS=<64-char hex pubkey>[,<64-char hex pubkey>...]
 #
 # Directory holding the built dashboard assets (`pnpm -C admin-web build`).
 # BUZZ_ADMIN_WEB_DIR=./admin-web/dist

CHANGELOG.md

@@ -3,16 +3,27 @@
 ## Unreleased
 
 - **Breaking:** the relay admin moderation API (`/api/admin/v1`) now requires
-  explicit authentication when `BUZZ_ADMIN_HOST` is set. Choose one mode:
-  - **Token mode:** set `BUZZ_ADMIN_TOKEN` to exactly 64 hex characters
-    (`openssl rand -hex 32`). Every API request requires `Authorization: Bearer`.
-    The dashboard prompts for the token on first load.
-  - **Network-layer mode:** set `BUZZ_ADMIN_INSECURE_NO_AUTH=true` (exact value
-    only). Use only when the admin API is already protected by a VPN or private
-    ingress. The relay logs a `WARN` on every startup. The dashboard skips the
-    token prompt and renders directly.
-  - Both set at the same time, or neither, is a startup error.
-  `Host`/`Origin` matching is retained in both modes as defense-in-depth.
+  explicit authentication configuration when `BUZZ_ADMIN_HOST` is set. Choose
+  one mode via `BUZZ_ADMIN_AUTH` (unset defaults to `token`):
+  - **`BUZZ_ADMIN_AUTH=token` (default):** set `BUZZ_ADMIN_TOKEN` to exactly
+    64 hex characters (`openssl rand -hex 32`). Every request requires
+    `Authorization: Bearer`. The dashboard prompts for the token on first load.
+  - **`BUZZ_ADMIN_AUTH=disabled`:** admin API is unauthenticated. Use only when
+    the admin API is already protected by a VPN or private ingress. The relay
+    logs a `WARN` on every startup. The dashboard skips the token prompt.
+  - **`BUZZ_ADMIN_AUTH=nip98`:** NIP-98 HTTP Auth. Every request must carry an
+    `Authorization: Nostr <base64 event>` header containing a signed kind-27235
+    event. The signer's pubkey must be listed in `BUZZ_ADMIN_PUBKEYS`
+    (comma-separated 64-char hex pubkeys). The dashboard requires a NIP-07
+    browser extension (nos2x or Alby); without one it shows an installation
+    screen. Individual operator access is revocable without rotating a shared
+    secret.
+  - Any unrecognised value for `BUZZ_ADMIN_AUTH` is a startup error
+    (typo-proofing). `BUZZ_ADMIN_TOKEN` set alongside `disabled` or `nip98` is
+    also a startup error.
+  - `Host`/`Origin` matching is retained in all modes as defense-in-depth.
+  - **Migration from the previous `BUZZ_ADMIN_INSECURE_NO_AUTH=true`:** replace
+    with `BUZZ_ADMIN_AUTH=disabled`. The behavior is identical.
 
 
 ## v0.5.4

admin-web/src/App.tsx

@@ -7,8 +7,9 @@ import {
   useState,
 } from "react";
 import {
+  type AuthMode,
   ApiFailure,
-  probeAuthRequired,
+  probeAuthMode,
   request,
   requestObjectUrl,
 } from "./api";
@@ -91,9 +92,9 @@ function StateView<T>({
   return resource.data ? children(resource.data) : null;
 }
 
-function Reports() {
+function Reports({ authMode }: { authMode: AuthMode }) {
   const resource = useResource(
-    () => request<Report[]>("/reports?status=open&limit=100"),
+    () => request<Report[]>("/reports?status=open&limit=100", authMode),
     "reports",
   );
   return (
@@ -141,9 +142,9 @@ function Reports() {
   );
 }
 
-function ReportDetail({ id }: { id: string }) {
+function ReportDetail({ id, authMode }: { id: string; authMode: AuthMode }) {
   const resource = useResource(
-    () => request<ReportDetailData>(`/reports/${id}`),
+    () => request<ReportDetailData>(`/reports/${id}`, authMode),
     id,
   );
   return (
@@ -216,9 +217,9 @@ function ReportDetail({ id }: { id: string }) {
   );
 }
 
-function FeedbackList() {
+function FeedbackList({ authMode }: { authMode: AuthMode }) {
   const resource = useResource(
-    () => request<FeedbackSummary[]>("/feedback"),
+    () => request<FeedbackSummary[]>("/feedback", authMode),
     "feedback",
   );
   const [query, setQuery] = useState("");
@@ -425,9 +426,15 @@ function FeedbackResults({
   return children(results);
 }
 
-function FeedbackDetailView({ id }: { id: string }) {
+function FeedbackDetailView({
+  id,
+  authMode,
+}: {
+  id: string;
+  authMode: AuthMode;
+}) {
   const resource = useResource(
-    () => request<FeedbackDetail>(`/feedback/${id}`),
+    () => request<FeedbackDetail>(`/feedback/${id}`, authMode),
     id,
   );
   return (
@@ -468,6 +475,7 @@ function FeedbackDetailView({ id }: { id: string }) {
                         <Attachment
                           key={`${attachment.hash}-${attachment.path}`}
                           attachment={attachment}
+                          authMode={authMode}
                         />
                       ))}
                     </dd>
@@ -601,7 +609,13 @@ function stripAttachmentMarkdown(
     .trim();
 }
 
-function Attachment({ attachment }: { attachment: FeedbackAttachment }) {
+function Attachment({
+  attachment,
+  authMode,
+}: {
+  attachment: FeedbackAttachment;
+  authMode: AuthMode;
+}) {
   const [objectUrl, setObjectUrl] = useState<string>();
   const [failed, setFailed] = useState(false);
   const path = attachment.path;
@@ -622,7 +636,7 @@ function Attachment({ attachment }: { attachment: FeedbackAttachment }) {
     let active = true;
     setObjectUrl(undefined);
     setFailed(false);
-    requestObjectUrl(path)
+    requestObjectUrl(path, authMode)
       .then((created) => {
         if (!active) {
           URL.revokeObjectURL(created);
@@ -638,7 +652,7 @@ function Attachment({ attachment }: { attachment: FeedbackAttachment }) {
       active = false;
       if (url) URL.revokeObjectURL(url);
     };
-  }, [path]);
+  }, [path, authMode]);
 
   const detail = failed ? "Could not load attachment" : metadata;
 
@@ -885,6 +899,38 @@ function TokenPrompt({ rejected }: { rejected: boolean }) {
   );
 }
 
+/// Shown in nip98 mode when no NIP-07 extension is available. Instructs the
+/// operator to install nos2x or Alby before continuing.
+function Nip07Screen() {
+  return (
+    <div className="app">
+      <div className="state token-prompt">
+        <h2>Nostr extension required</h2>
+        <p>
+          This relay uses NIP-98 HTTP Auth. Install a NIP-07 browser extension
+          such as{" "}
+          <a
+            href="https://github.com/fiatjaf/nos2x"
+            target="_blank"
+            rel="noreferrer"
+          >
+            nos2x
+          </a>{" "}
+          or{" "}
+          <a href="https://getalby.com" target="_blank" rel="noreferrer">
+            Alby
+          </a>
+          , then reload this page. Your Nostr key will be used to sign each
+          request.
+        </p>
+        <button type="button" onClick={() => location.reload()}>
+          Reload
+        </button>
+      </div>
+    </div>
+  );
+}
+
 export function App() {
   const { path } = usePath();
   const token = useToken();
@@ -894,21 +940,20 @@ export function App() {
     if (token !== null) setEverHadToken(true);
   }, [token]);
 
-  // When no token is stored, probe the relay to find out whether it requires
-  // one. In insecure_no_auth mode the probe returns 200 and the dashboard
-  // renders without a credential; in token mode it returns 401 and the prompt
-  // is shown. `null` means the probe is still in flight.
-  const [authRequired, setAuthRequired] = useState<boolean | null>(
-    token !== null ? false : null,
+  // Probe the relay once to discover the auth mode. `null` means the probe is
+  // still in flight. Once resolved, the mode is stable for the session.
+  const [authMode, setAuthMode] = useState<AuthMode | null>(
+    // If we already have a token we know we're in token mode; skip the probe.
+    token !== null ? "token" : null,
   );
   useEffect(() => {
     if (token !== null) {
-      setAuthRequired(false);
+      setAuthMode("token");
       return;
     }
     let active = true;
-    probeAuthRequired().then((required) => {
-      if (active) setAuthRequired(required);
+    probeAuthMode().then((mode) => {
+      if (active) setAuthMode(mode);
     });
     return () => {
       active = false;
@@ -919,18 +964,24 @@ export function App() {
   const feedback = path.match(/^\/feedback\/([^/]+)$/);
 
   // Probe still in flight — render nothing to avoid a visible flash.
-  if (authRequired === null) return null;
+  if (authMode === null) return null;
+
+  // Token mode: show the token prompt until a valid token is stored.
+  if (authMode === "token" && !token)
+    return <TokenPrompt rejected={everHadToken} />;
 
-  if (authRequired && !token) return <TokenPrompt rejected={everHadToken} />;
+  // NIP-98 mode: require a NIP-07 extension.
+  if (authMode === "nip98" && !(window as Window & { nostr?: unknown }).nostr)
+    return <Nip07Screen />;
 
   const content = report ? (
-    <ReportDetail id={report[1]} />
+    <ReportDetail id={report[1]} authMode={authMode} />
   ) : feedback ? (
-    <FeedbackDetailView id={feedback[1]} />
+    <FeedbackDetailView id={feedback[1]} authMode={authMode} />
   ) : path === "/feedback" ? (
-    <FeedbackList />
+    <FeedbackList authMode={authMode} />
   ) : (
-    <Reports />
+    <Reports authMode={authMode} />
   );
   return (
     <div className="app">