Warum muss [email protected] im Nuxt-Auth-Projekt fixiert werden?

# Warum ein Nuxt-Projekt auf `[email protected]` festgenagelt werden muss

Kürzlich habe ich die Abhängigkeiten eines Nuxt-Auth-Projekts aktualisiert, was zu einer Reihe von Warnungen und einer Fehlfunktion der Anmeldefunktion führte. Oberflächlich betrachtet schien es ein Konflikt zwischen `@sidebase/nuxt-auth` und `next-auth` zu sein, tatsächlich handelt es sich jedoch um ein altes Problem, bei dem die Exportstrategien von Nuxt, Nitro und NextAuth-Paketen aufeinandertreffen. Dieser Artikel erklärt die Ursachen, warum ein Upgrade nicht möglich ist, ob die aktuelle Version sicher ist und wie ich das Problem letztendlich gelöst habe, basierend auf meinen eigenen Erfahrungen.

## Zuerst beobachtete Phänomene

Nach dem Upgrade der Abhängigkeiten und dem Start des Entwicklungsservers gab Nitro während der Build-Phase kontinuierlich Warnungen wie diese aus:

```text
WARN  "next-auth/providers/google" is imported by "server/api/auth/[...].ts", but could not be resolved – treating it as an external dependency.

WARN  "next-auth/providers/credentials" is imported by "server/api/auth/[...].ts", but could not be resolved – treating it as an external dependency.

WARN  "next-auth/providers/github" is imported by "server/api/auth/[...].ts", but could not be resolved – treating it as an external dependency.

WARN  "next-auth/jwt" is imported by ".../@sidebase/nuxt-auth/.../nuxtAuthHandler.js", but could not be resolved – treating it as an external dependency.

WARN  "next-auth/core" is imported by ".../@sidebase/nuxt-auth/.../nuxtAuthHandler.js", but could not be resolved – treating it as an external dependency.
```

Die Warnungen klangen, als ob "nicht auflösbar, also als externe Abhängigkeit behandeln". Viele würden dies als Rauschen abtun. Danach funktionierte die Anmeldung nicht mehr: Benutzername und Passwort zeigten keine Reaktion, und GitHub-/Google-Callbacks wurden nicht erreicht.

Ich habe zwei "vernünftige" Dinge ausprobiert, mit dem gleichen Ergebnis:

1.  `next-auth` auf 4.22+, 4.24 oder sogar 5 aktualisieren.
2.  `next-auth` nicht im Projekt deklarieren, in der Hoffnung, dass `@sidebase/nuxt-auth` eine eigene Version mitbringt.

Beide Wege führten zu ähnlichen WARN-Meldungen, und die Anmeldung funktionierte weiterhin nicht.

## Erster Irrtum: `nuxt-auth` bringt `next-auth` nicht mit

`@sidebase/nuxt-auth` ist kein vollständiger Authentifizierungskern, sondern eine Nuxt-Adapter-Schicht. Der eigentliche Prozess des Ausstellens von JWTs, der Durchführung von OAuth und der Bereitstellung von Google / GitHub / Credentials in dieser `authjs`-Kette wird von `next-auth` übernommen.

Ein Blick in die `package.json` bestätigt dies:

```json
{
  "peerDependencies": {
    "next-auth": "~4.21.1"
  },
  "peerDependenciesMeta": {
    "next-auth": {
      "optional": true
    }
  }
}
```

Es gibt drei wichtige Punkte:

-   Es ist eine **Peer-Abhängigkeit**, keine gebündelte Abhängigkeit. Der Modul-Quellcode `import "next-auth/core"` sucht zur Laufzeit nach diesem Paket in Ihrem Projekt.
-   Die Version ist `~4.21.1`, was nur 4.21.x erlaubt, nicht `^4`.
-   Es ist auch als **optional** gekennzeichnet. Der Grund dafür ist, dass das Modul auch einen `local`-Provider hat, der nicht mit Auth.js verbunden sein muss. Wenn Sie `authjs` wählen, bedeutet optional nicht "muss nicht installiert werden".

Der offizielle Quick Start ist sehr deutlich: Zusätzlich zu npm müssen Sie es selbst noch einmal installieren, und die Version wird explizit genannt:

```bash
pnpm i [email protected]
```

Die Dokumentation warnt gleichzeitig: Aufgrund von Breaking Changes in NextAuth ist **nuxt-auth nur mit Versionen unter 4.23.0 kompatibel** und empfiehlt, `4.21.1` festzunageln.

Daher schlägt "die vom Modul mitgelieferte Version verwenden" in pnpm-Projekten fast zwangsläufig fehl. pnpm ist streng isoliert: Wenn Sie `next-auth` nicht in Ihre eigenen `dependencies` schreiben, ist es nicht im `node_modules`-Verzeichnis des Stammverzeichnisses vorhanden. Wenn Nitro versucht, `next-auth/providers/google` aufzulösen, findet es das Paket nicht und muss es als extern kennzeichnen; wenn Node es zur Laufzeit `import`iert, ist das Paket nicht vorhanden, und die Anmeldekette wird direkt unterbrochen.

npm verschiebt Peer-Abhängigkeiten manchmal in das Stammverzeichnis, sodass es so aussieht, als ob "es auch ohne Deklaration läuft". Bei pnpm / yarn wird die wahre Natur sichtbar. Dies ist kein Fehler des Paketmanagers, sondern das erwartete Verhalten von Peer + optional + strenger Isolation.

## Was bedeuten diese WARN-Meldungen wirklich?

Dies ist kein ESLint, sondern **Nitro / Vite / Rollup, die beim Erstellen des Server-Bundles fehlschlagen**.

Zwei Importketten suchen gleichzeitig nach Unterpfaden von `next-auth`:

-   Ihre Catch-all-Route: `next-auth/providers/google`, `github`, `credentials`
-   Das interne `NuxtAuthHandler` des Moduls: `next-auth/core`, `next-auth/jwt`

Wenn die Auflösung erfolgreich ist, werden diese Module in das Nitro-Artefakt gebündelt. Wenn die Auflösung fehlschlägt, sagt der Bundler "als externe Abhängigkeit behandeln" – was bedeutet: Ignoriere es während des Builds, und lass Node es zur Laufzeit in `node_modules` suchen.

Dies führt zu einer sehr verwirrenden Erfahrung: Der Build ist "erfolgreich", nur mit gelben Warnungen; erst wenn der Worker startet oder sich anmeldet, wird es zu `Cannot find package 'next-auth'` oder `Package subpath './core' is not defined by "exports"`.

WARN ist ein Symptom. Die Grundursache ist: **Der Unterpfad existiert entweder in der aktuell installierten Version von `next-auth` nicht, oder er ist durch `exports` verborgen.**

## Warum ausgerechnet 4.21.1?

Der Handler von `@sidebase/nuxt-auth` referenziert direkt die damals noch öffentlichen internen Einstiegspunkte von NextAuth: `next-auth/core` und `next-auth/jwt`. `4.21.1` behandelt diese Unterpfade immer noch als importierbare Module.

Ab **4.23.0** hat NextAuth die `exports` in der `package.json` verschärft und interne Pfade wie `./core` aus den öffentlichen Exporten entfernt, um sich auf das spätere Auth.js / v5 vorzubereiten. Wenn Nitro dann versucht, sie auf die alte Weise aufzulösen, wird es zu:

```text
Package subpath './core' is not defined by "exports"
```

Ein eigenes Issue von sidebase hat dies bestätigt: [NextAuth >= v4.23.0 Breaking change](https://github.com/sidebase/nuxt-auth/issues/514). Die Maintainer gaben später zu: Sie müssen das Modul gemäß der neuen Architektur überarbeiten, und danach wird es nicht mehr mit Versionen unter 4.23 kompatibel sein; aber diese Überarbeitung für 1.x wurde noch nicht als stabile Lösung veröffentlicht. Daher bleibt die Peer-Abhängigkeit in 1.x auf `~4.21.1` festgenagelt.

`next-auth@5` ist noch radikaler: Paketstruktur, Provider-Pfade und Handler-API wurden geändert. `@sidebase/[email protected]` kann nicht daran anknüpfen.

Ein weiteres leicht zu übersehendes Detail: Die Provider von 4.21.1 sind CommonJS. Nuxt-Projekte sind normalerweise ESM (`"type": "module"`), daher muss das offizielle Beispiel als `.default()` geschrieben werden:

```ts
import { NuxtAuthHandler } from "#auth"
import GithubProvider from "next-auth/providers/github"
import CredentialsProvider from "next-auth/providers/credentials"

export default NuxtAuthHandler({
  secret: process.env.NUXT_AUTH_SECRET,
  providers: [
    // @ts-expect-error ESM lädt CJS-Provider über .default
    GithubProvider.default({
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    }),
    // @ts-expect-error
    CredentialsProvider.default({
      name: "Credentials",
      credentials: {
        email: { label: "Email", type: "text" },
        password: { label: "Password", type: "password" },
      },
      async authorize(credentials) {
        // Hier Ihre eigene Validierung durchführen, Benutzer oder null zurückgeben
        return null
      },
    }),
  ],
  session: { strategy: "jwt" },
  pages: {
    signIn: "/login",
  },
})
```

Dies ist keine Projekt-Eigenart, sondern die Interoperabilität von CJS-Providern in einem ESM-Server. Sobald die Version ESM-priorisiert ist, ist `.default` oft `undefined`, der Provider kann überhaupt nicht registriert werden, und die Anmeldung schlägt auf andere Weise stillschweigend fehl.

Die entsprechende Nuxt-Konfiguration muss lediglich angeben, dass Auth.js verwendet werden soll:

```ts
export default defineNuxtConfig({
  modules: ["@sidebase/nuxt-auth"],
  auth: {
    originEnvKey: "NUXT_AUTH_BASE_URL",
    provider: {
      type: "authjs",
      trustHost: false,
      addDefaultCallbackUrl: true,
    },
  },
})
```

`trustHost: false` sollte beibehalten werden. In der Produktion sollte `NUXT_AUTH_BASE_URL` als vollständige Adresse konfiguriert werden, z. B. `https://example.com/api/auth`, nicht nur der Domänenstamm.

## Warum beide falschen Operationen fehlschlagen

**`next-auth` nicht deklarieren.**
pnpm wird optionale Peer-Abhängigkeiten nicht in die Root-Abhängigkeiten Ihrer Anwendung hochstufen. Ihre `server/api/auth/[...].ts` und das interne `nuxtAuthHandler.js` des Moduls schlagen gleichzeitig bei der Auflösung fehl. Dies ist die gleiche Art von Problem wie bei sidebase [#748](https://github.com/sidebase/nuxt-auth/issues/748) und [#877](https://github.com/sidebase/nuxt-auth/issues/877).

**Auf 4.22+ / 4.24 / 5 wechseln.**
Das Paket kann installiert werden, aber `exports` exportiert `./core` nicht mehr. Nitro schlägt ebenfalls bei der Auflösung fehl, und zur Laufzeit wird es zu `ERR_PACKAGE_PATH_NOT_EXPORTED`. Die Anmeldung ist ebenfalls nicht verfügbar. Der Scanner mag vorübergehend Ruhe geben, aber die Anwendung ist kaputt.

Schreiben Sie in `package.json` nicht `^4.21.1`. `^` würde 4.22, 4.23, 4.24 zulassen. Richtig ist Tilde oder die genaue Version:

```json
{
  "dependencies": {
    "@sidebase/nuxt-auth": "1.3.1",
    "next-auth": "~4.21.1"
  }
}
```

Überprüfen Sie nach der Installation mit dem Paketmanager die tatsächliche Version, um zu vermeiden, dass im Lockfile heimlich eine weitere Kopie auftaucht:

```bash
pnpm ls next-auth
```

Es sollte `[email protected]` angezeigt werden. Dann `nuxt prepare` erneut ausführen / den Dev-Server neu starten, die Warnung "treating it as an external dependency" sollte verschwinden, und die Anmelderoute kann tatsächlich in Nitro gebündelt werden.

## Gibt es eine neue Version, die zusammen aktualisiert werden kann?

Zum Zeitpunkt des Verfassens dieses Artikels (September 2026) ist die Situation wie folgt:

| Ding                         | Status                            |
| ---------------------------- | ------------------------------- |
| `@sidebase/nuxt-auth` stabile Version | `1.3.1` (30.06.2026), bereits die neueste |
| Peer                         | Immer noch `next-auth@~4.21.1`      |
| sidebase 2.0                 | Roadmap vorhanden, nicht auf npm            |
| Offizielles `@auth/nuxt`            | Auth.js-Dokumentation immer noch als Open PR gekennzeichnet      |

1.3.x behebt Probleme mit der Aktualisierung, Cookies und der Nuxt 4-Kompatibilität des Moduls selbst, **lockert aber nicht** die Versionseinschränkung von `next-auth`. Ein Upgrade von nuxt-auth von 1.1 auf 1.3 löst die WARN-Meldungen in diesem Artikel nicht.

sidebase hatte ursprünglich geplant, in 2.0 auf Auth.js v5 umzusteigen, entsprechende Diskussionen finden sich in [Roadmap #1028](https://github.com/sidebase/nuxt-auth/issues/1028) und [Migration #673](https://github.com/sidebase/nuxt-auth/issues/673). Sie haben mindestens zwei Migrations-PRs durchgeführt, die jedoch aufgrund der Instabilität von `@auth/core` / `oauth4webapi` gestoppt wurden. Die Maintainer haben öffentlich erklärt: Sie waren besorgt über die damalige Stabilität von Auth.js und wollten keine stabile Version mit fehlerhaften Abhängigkeiten veröffentlichen.

Später wurde Auth.js in Better Auth integriert. Jemand schlug vor, dass sidebase direkt dorthin migrieren sollte, was die Maintainer ablehnten: Auth.js kann JWT-Sessions ohne Datenbank verwenden, Better Auth benötigt standardmäßig Datenbank-Sessions, es ist nicht nur eine Umbenennung des Pakets. Die aktuelle Better Auth-Kapselung in der Nuxt-Community befindet sich ebenfalls noch in einem frühen Stadium.

Daher gibt es heute kein synchrones Upgrade, das "nur die Versionsnummer ändert und den Geschäfts-Anmeldecode unberührt lässt". Um von 4.21.1 wegzukommen, müsste im Wesentlichen der Authentifizierungskern gewechselt werden: Warten auf sidebase 2.0 oder selbst auf `nuxt-auth-utils` / Better Auth migrieren und Handler, `signIn`, Session-Lesen und Cookies neu schreiben. Das ist eine Projektmigration, kein Abhängigkeits-Upgrade.

## Ist es sicher, auf 4.21.1 festgenagelt zu bleiben?

Dies war die wichtigste Frage für mich, bevor ich mich entschied, "erstmal nichts zu ändern". Die Antwort muss differenziert betrachtet werden und darf nicht von den roten Warnungen von `npm audit` beeinflusst werden.

Der Scanner wird fast immer melden:

-   `next-auth < 4.24.5`: [CVE-2023-48309](https://github.com/advisories/GHSA-v64w-49xw-qq89), Fälschung leerer Benutzer
-   `next-auth < 4.24.15`: [CVE-2026-73419](https://github.com/advisories/GHSA-x445-f3h2-j279), OAuth-Provider-Verwechslung

Beide Patches sind in 4.24.x, aber 4.24.x würde die aktuelle nuxt-auth-Anmeldung zum Absturz bringen. Die Frage lautet also: **Betreffen diese Lücken den Nuxt-Pfad?**

**CVE-2023-48309 ist für NuxtAuth grundsätzlich nicht anwendbar.**
Sie betrifft nur die Standard-`withAuth`-Middleware von Next.js – eine Schreibweise, die nur prüft, ob "eine Session vorhanden ist". Ein Angreifer kann mit einem unvollständigen JWT den Anschein erwecken, angemeldet zu sein, hat aber keine E-Mail und keine Berechtigungen. Die sidebase-Dokumentation widmet diesem Abschnitt einen eigenen Teil: Sie verwenden nicht die Next-Middleware, sondern ihre eigenen Nuxt-/h3-Session-Tools. Die Maintainer haben in [#1001](https://github.com/sidebase/nuxt-auth/issues/1001) dieses Problem als nicht modulanfällig markiert.

Im Lockfile erscheint oft auch `next@13`. Das ist eine Peer-Abhängigkeit von `[email protected]`, nicht Ihr Webserver. Eine Nuxt-Anwendung führt keine Next Server Actions aus, und die vom Scanner gemeldeten Next SSRF sind normalerweise nicht die HTTP-Angriffsfläche dieser Site.

**CVE-2026-73419 betrifft die Version, aber die vollständigen Ausnutzungsbedingungen sind sehr streng.**
4.21.1 fällt tatsächlich in den betroffenen Bereich. Die offizielle Beschreibung erfordert gleichzeitig: mehrere OAuth-Anbieter, das Binden eines zweiten Anbieters an den aktuellen Benutzer **im angemeldeten Zustand** und dass mindestens einer der Anbieter-Callbacks ohne PKCE auskommt. Wenn Sie OAuth nur auf der Anmeldeseite initiieren, keinen "zweites Konto nach der Anmeldung binden"-Einstiegspunkt haben und auch nicht das NextAuth Adapter-Set `linkAccount` verwenden, ist das tatsächliche Risiko geringer, als der Scanner angibt. Dies ist ein theoretisches Risiko, das durch das Alter der Bibliothek entsteht, nicht ein "muss sofort deaktiviert werden".

Meine Schlussfolgerung ist:

-   **Es kann weiterhin** `@sidebase/[email protected]` + `[email protected]` **verwendet werden**.
-   Audit-Warnungen werden als bekannt, bewertet und vorerst nicht behoben behandelt.
-   `next-auth` nicht aktualisieren, um die roten Warnungen zu beseitigen.

Was wirklich beachtet werden muss, ist die Verwendung, nicht die Versionsnummer selbst:

-   `NUXT_AUTH_SECRET` sollte ein ausreichend langer Zufallsstring sein; die Anwendung sollte fehlschlagen, wenn beim Start kein Schlüssel vorhanden ist.
-   `trustHost` auf `false` belassen, Weiterleitungs-Header nicht blind vertrauen.
-   `NUXT_AUTH_BASE_URL` als absolute Adresse mit `/api/auth` schreiben.
-   Frontend-Middleware ist nur für die Weiterleitung zur Anmeldeseite zuständig; die API-Autorisierung muss serverseitig erneut die Session überprüfen und nicht nur prüfen, ob "das Objekt vorhanden ist", sondern mindestens das Benutzeridentitätsfeld bestätigen; Management-APIs müssen auch Rollen überprüfen.
-   Produktion über HTTPS, damit Session-Cookies gemäß den Sicherheitsprefixen von Auth.js funktionieren können.

Es muss auch eine strukturelle Einschränkung akzeptiert werden: `next-auth` v4 befindet sich bereits im Wartungsmodus. Sollte in Zukunft eine neue Lücke auftreten, die **die JWT-Validierung oder den OAuth-Callback-Kern** betrifft, und sidebase immer noch auf 4.21.1 festgenagelt ist, dann kann dies nicht durch `pnpm update` behoben werden, sondern erfordert einen Stack-Wechsel. Dies auf der Liste der technischen Schulden zu vermerken, ist ehrlicher, als so zu tun, als ob der Scanner grün wäre.

## Meine letztendlich gewählte Lösung

Die Lösung ist eigentlich sehr kurz, so kurz, dass sie dem Instinkt des "Abhängigkeiten aktualisieren" widerspricht.

1.  In den eigenen `dependencies` der Anwendung explizit `next-auth@~4.21.1` hinzufügen, um es mit der Peer-Abhängigkeit von `@sidebase/nuxt-auth` abzugleichen.
2.  Bei Verwendung von pnpm als Paketmanager nicht davon ausgehen, dass Peer-Abhängigkeiten automatisch hochgestuft werden.
3.  Catch-all-Route importiert Provider auf offizielle Weise, CJS-Interoperabilität über `.default()`.
4.  `next-auth` nicht auf `^4` oder `5` ändern, nicht löschen.
5.  Die beiden next-auth CVEs in `npm audit` als "Nuxt-Pfad bewertet, kann nicht mit Patch-Version aktualisiert werden" vermerken.
6.  Warten, bis sidebase 2.0 verfügbar ist oder selbst eine Authentifizierungsmigration vorbereiten, dann ein separates Projekt starten und es nicht mit den täglichen Abhängigkeits-Upgrades verbinden.

Die Verifizierung ist ebenfalls direkt: Nach dem Neustart des Dev-Servers sollte Nitro `next-auth/core`, `next-auth/jwt`, `next-auth/providers/*` nicht mehr als extern behandeln; Benutzername/Passwort und OAuth-Callbacks sollten vollständig durchlaufen werden; `pnpm ls next-auth` sollte nur 4.21.1 anzeigen.

## Was, wenn ich später unbedingt von 4.21.1 weg muss?

Es gibt keinen dritten Weg, der "nur die Version aktualisiert". Die Optionen, die ich mir offen halte, sind:

1.  **Daran festhalten.** Das Modul wird weiterhin gewartet, Nuxt 4 ist verwendbar. Der Preis ist, für immer bei NextAuth v4 zu bleiben.
2.  **Auf sidebase 2.0 warten.** Die Offiziellen haben gesagt, dass sie auf Auth.js v5 migrieren wollen, aber es gibt keinen stabilen Zeitplan und keine npm `dist-tag`, die für die Produktion verwendet werden könnte.
3.  **Stack wechseln und neu schreiben.** Die offizielle Nuxt-Anleitung weist auf `nuxt-auth-utils` hin (verschlüsselte Cookie-Session, OAuth muss selbst implementiert werden); oder Better Auth. Beide erfordern das Neuschreiben des Anmeldeeingangs, der Session-Form und der Callback-URL, und bestehende Anmeldezustände gehen verloren.

Bis dahin werde ich dieses Versionspaar als eingefrorene Schicht der Anmeldeinfrastruktur betrachten: Ich kann meine eigenen Seiten und Autorisierungslogiken reparieren, aber nicht versuchen, `next-auth` zu "organisieren".

## Fazit

Die Sache ist deswegen so eigenartig, weil sie der Intuition des Abhängigkeitsmanagements widerspricht: Der Scanner sagt alt, die Dokumentation sagt festnageln, der Build warnt nur, schlägt aber nicht fehl, und der Fehler tritt bei der Anmeldung auf. Wenn man die drei Dinge trennt, wird es klarer –

-   **Auflösungsfehler** kommen von der pnpm-Isolation, plus der Tatsache, dass NextAuth ab 4.23 `./core` nicht mehr exportiert.
-   **Kein Upgrade möglich**, weil `@sidebase/[email protected]` noch auf diesen internen Einstiegspunkten basiert und 2.0 noch nicht ausgeliefert wurde.
-   **Weiterhin verwendbar**, weil die am häufigsten gescannte CVE die Standard-Middleware von Next.js betrifft, nicht die eigenen Session-Tools von NuxtAuth; die neue OAuth-Verwechslung hängt davon ab, ob Sie einen Pfad für "zweites Konto nach der Anmeldung binden" haben.

Deshalb habe ich die Lösung in einem Satz zusammengefasst, den ich selbst ausführen kann: Bei der `authjs`-Provider-Implementierung in Nuxt `[email protected]` als erstklassige Abhängigkeit festnageln, die Audit-Warnungen als bekannte Schuld betrachten und das eigentliche Upgrade auf die nächste Authentifizierungsmigration verschieben.