docs(git): jeden ausgehenden Aufruf einzeln mit seinem Recht belegen

Die Faelle A und B beantworteten die Frage auf Ebene der Scopes, nicht
auf Ebene der Aufrufe. Wer nachpruefen wollte, ob ein Recht wirklich
noetig ist, musste die drei Clients selbst lesen.

Jetzt steht in der README je System eine vollstaendige Tabelle: Aufruf,
Zweck, benoetigtes Recht. Die Zuordnung bei GitHub folgt der offiziellen
Berechtigungsuebersicht - dass /tags und /stats/commit_activity unter
Metadata fallen und nicht unter Contents, ist nicht zu erraten. Fuer
GitLab ist mit Quellenangabe belegt, dass es unterhalb von 'api' keinen
Schreibzugriff auf Issues gibt.

Ausserdem war offen, woher die Kommentare an den Issues stammen: Nebula
schreibt keine. Der Schreibzugriff besteht aus genau zwei Aufrufen. Ein
Test klopft dafuer die Clients ab - kaeme ein dritter dazu, wuerde die
Empfehlung 'nimm ein lesendes Token' still falsch, ohne dass jemand
einen Fehler saehe.

Der Hinweis am Eingabefeld nannte Actions nicht, obwohl der CI-Zustand
bei GitHub genau daran haengt.

Refs #10

src/lib/git/meta.ts

@@ -12,8 +12,9 @@ export const PROVIDER_META: Record<
     label: "GitHub",
     defaultBaseUrl: "https://github.com",
     tokenHelp:
-      "Fine-grained Token: Metadata, Contents und Pull requests lesen, Issues lesen. " +
-      "Nur wenn Aufgaben als Issue angelegt werden sollen, Issues zusaetzlich schreiben.",
+      "Fine-grained Token, alle nur lesend: Metadata, Contents, Issues, Pull requests " +
+      "und Actions. Nur wenn Aufgaben als Issue angelegt werden sollen, Issues " +
+      "zusaetzlich schreiben.",
     docsUrl: "https://github.com/settings/tokens",
   },
   GITLAB: {

src/lib/git/schreibzugriffe.test.ts

@@ -0,0 +1,60 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Waechter ueber eine Zusage in der Dokumentation.
+ *
+ * README und FEATURES sagen zu, dass Nebula an genau zwei Stellen nach
+ * draussen schreibt: ein Issue anlegen und seinen Zustand umsetzen. Auf
+ * dieser Zusage steht die Empfehlung, ein rein lesendes Token zu vergeben,
+ * solange die Issue-Anbindung nicht gebraucht wird.
+ *
+ * Kaeme ein dritter Schreibaufruf dazu, wuerde die Empfehlung still falsch:
+ * niemand bekaeme einen Fehler, nur ein 403 an einer Stelle, die laut
+ * Dokumentation gar nicht schreibt. Deshalb wird hier der Quelltext selbst
+ * abgeklopft – sendJson ist der einzige Weg aus lib/git heraus, der eine
+ * andere Methode als GET benutzt (siehe http.ts).
+ */
+const CLIENTS = ["gitea.ts", "github.ts", "gitlab.ts"] as const;
+
+/** Die Zeile ueber dem Methoden-Argument nennt den Endpunkt. */
+function schreibaufrufe(quelltext: string): string[] {
+  const zeilen = quelltext.split("\n");
+  const gefunden: string[] = [];
+  zeilen.forEach((zeile, i) => {
+    if (!/\bsendJson[<(]/.test(zeile)) return;
+    // sendJson(url, METHODE, …) – Endpunkt und Methode stehen darunter.
+    const block = zeilen.slice(i, i + 4).join(" ");
+    const methode = block.match(/"(POST|PATCH|PUT)"/)?.[1];
+    const pfad = block.match(/\/issues[^`"']*/)?.[0] ?? "?";
+    gefunden.push(`${methode ?? "?"} ${pfad}`);
+  });
+  return gefunden;
+}
+
+describe("Schreibzugriffe nach draussen", () => {
+  it("beschraenken sich auf Issues anlegen und Zustand setzen", () => {
+    for (const datei of CLIENTS) {
+      const quelltext = readFileSync(join(__dirname, datei), "utf8");
+      const aufrufe = schreibaufrufe(quelltext);
+
+      expect(aufrufe.length, `${datei}: Anzahl Schreibaufrufe`).toBe(2);
+      for (const aufruf of aufrufe) {
+        expect(aufruf, `${datei}: ${aufruf}`).toMatch(/^(POST|PATCH|PUT) \/issues/);
+      }
+      // Genau einer legt an, genau einer setzt um.
+      expect(aufrufe.filter((a) => a.startsWith("POST")).length, datei).toBe(1);
+      expect(aufrufe.filter((a) => /^(PATCH|PUT)/.test(a)).length, datei).toBe(1);
+    }
+  });
+
+  it("laufen ueber sendJson, nicht an http.ts vorbei", () => {
+    // Ein direkter fetch in einem Client haette weder SSRF-Schutz noch
+    // Zeitbegrenzung – und wuerde am Waechter oben vorbeilaufen.
+    for (const datei of CLIENTS) {
+      const quelltext = readFileSync(join(__dirname, datei), "utf8");
+      expect(quelltext, datei).not.toMatch(/\bfetch\s*\(/);
+    }
+  });
+});