Stash

Stash ist eine Next.js-App-Router-Anwendung mit First-Party-E-Mail-/Passwort-Authentifizierung, zustandslosen Auth.js-Sitzungen, Prisma/PostgreSQL-Persistenz, transaktionalen E-Mails über Resend und authentifizierten Lesezeichen-Tools über Model Context Protocol (MCP).

Lokale Einrichtung

1. Installiere Abhängigkeiten mit pnpm install.

2. Kopiere .env.example nach .env und ersetze jeden Platzhalter. Committe niemals .env.

3. Generiere AUTH_SECRET mit pnpm exec auth secret (oder einem anderen kryptografisch sicheren Generator).

4. Setze APP_URL auf die vertrauenswürdige öffentliche Origin, normalerweise http://localhost:3000 lokal. In der Produktion muss HTTPS verwendet werden.

5. Konfiguriere EMAIL_FROM mit einem Absender auf einer in Resend verifizierten Domain.

6. Setze MCP_AUTH_ISSUER auf den exakten vertrauenswürdigen Issuer des OAuth-Autorisierungsservers. Lokale Entwicklung darf Loopback-HTTP verwenden; Produktions-Issuer müssen HTTPS verwenden und dürfen weder Query noch Fragment enthalten.

7. Wende Migrationen mit pnpm prisma migrate dev an. Die eingecheckten Migrationen erstellen die Tabellen für Authentifizierung und Lesezeichen.

8. Starte die Anwendung mit pnpm dev.

Der Server validiert DATABASE_URL, RESEND_API_KEY, AUTH_SECRET, APP_URL, MCP_AUTH_ISSUER und EMAIL_FROM und meldet ungültige Variablennamen, ohne deren Werte auszugeben.

Related MCP server: bookmark-mcp

Authentifizierungsverhalten

• /signup erstellt einen Credentials-Benutzer, sendet eine Best-Effort-Willkommens-E-Mail und meldet den Benutzer an.

• /login erstellt eine siebentägige, verschlüsselte Auth.js-Cookie-Sitzung mit HTTP-only.

• /forgot-password gibt für eine syntaktisch gültige E-Mail-Adresse immer eine Antwort, die gegen Account-Enumeration geschützt ist.

• /reset-password verbraucht ein SHA-256-gehashtes, 60-minütiges Einmal-Token und widerruft ältere Sitzungen, indem die Sitzungsversion des Benutzers erhöht wird.

• / autorisiert anhand des aktuellen Datenbankdatensatzes über das DAL, bevor gerendert wird.

lib/rate-limit.ts ist der Erweiterungspunkt für einen zukünftigen gemeinsamen IP-/E-Mail-Limiter. Die datenbankgestützte 60-Sekunden-Abklingzeit pro Konto ist allein kein vollständiges Produktionssystem zur Missbrauchskontrolle.

Lesezeichen-MCP

Der zustandslose, ausschließlich moderne MCP-Endpunkt ist POST /api/mcp. Sein kanonischer RFC-8707-Ressourcenidentifikator und die Access-Token-Audience sind immer ${APP_URL}/api/mcp. Öffentliche RFC-9728-Discovery ist unter /.well-known/oauth-protected-resource/api/mcp verfügbar; Stash stellt keine Autorisierungs-, Token-, Registrierungs-, Widerrufs- oder JWKS-Endpunkte bereit.

Der Endpunkt stellt genau vier Tools bereit:

• add_bookmark und delete_bookmark erfordern bookmarks:write.

• list_bookmarks und search_bookmarks erfordern bookmarks:read.

Stash-Clients mit gleicher Herkunft können ihr Auth.js-Cookie verwenden und erhalten beide Fähigkeiten. Remote-native, Desktop- und Server-Clients senden bei jeder Anfrage ein Bearer-Zugriffstoken. Cross-Origin-MCP-Aufrufe im Browser werden bewusst nicht unterstützt. Eine 401-Challenge verweist Clients auf das Dokument der geschützten Ressource; eine 403-insufficient_scope-Challenge identifiziert den genauen Scope, der für ein begrenztes OAuth-Schritt-up erforderlich ist.

Stash ist ausschließlich eine durch OAuth 2.1 geschützte Ressource. Der separat betriebene Autorisierungsserver muss Authorization Code mit PKCE S256, Ressourcen-Indikatoren für die exakte kanonische MCP-URI und die Identifizierung des Issuers in der Autorisierungsantwort unterstützen. Er muss validierte RFC-8414- oder OpenID-Discovery-Metadaten, eine jwks_uri und access_token_signing_alg_values_supported veröffentlichen, wobei access_token_signing_alg_values_supported einen erlaubten asymmetrischen Algorithmus (RS256 oder ES256) enthält.

Zugriffstokens müssen kurzlebige JWT-Zugriffstokens mit geschütztem Header typ: at+jwt und einem kid sein. Erforderliche Claims sind exakte iss, aud mit genau einer Ressource, die lokale Stash-Benutzer-ID in sub, exp, iat, mit Leerzeichen getrenntes scope, client_id (oder azp) und ganzzahliges stash_session_version. Der Autorisierungsserver muss diese Version aus der aktuellen Stash-Benutzerzeile erzeugen und die Token-Lebensdauer auf höchstens 60 Minuten begrenzen. Er darf niemals E-Mail-Adressen in sub platzieren und darf nicht erwarten, dass Stash Benutzer aus Tokens bereitstellt.

Für lokale Remote-Client-Tests konfiguriere einen Loopback-Autorisierungsserver, setze MCP_AUTH_ISSUER auf dessen Issuer, registriere den Client vorab (oder verwende ein Client-ID-Metadaten-Dokument), fordere die exakte Ressource ${APP_URL}/api/mcp sowie die geringsten Lesezeichen-Scopes an und sende Stash ausschließlich das daraus resultierende Zugriffstoken. Refresh-Tokens gehen ausschließlich an den Autorisierungsserver.

E-Mail-Entwicklung

Automatisierte Tests mocken Resend und rufen dessen API niemals auf. Um Vorlagen ohne Versand vorab anzusehen, rendern Sie die exportierten React-Komponenten in emails/ mit einem lokalen React-E-Mail-Vorschauwerkzeug oder einem privaten, nur für Entwicklungszwecke bestimmten Harness. Füge keinen öffentlichen /api/send-Endpunkt hinzu. Verwende End-to-End-E-Mail-Tests einen separaten Resend-Testschlüssel und -Absender sowie ein separates Postfach; verwende niemals Produktionsempfänger.

Verifizierung

pnpm prisma format
pnpm prisma validate
pnpm prisma generate
pnpm lint
pnpm test
pnpm build

Datenbankintegrationstests erfordern eine isolierte TEST_DATABASE_URL. Browsertests erfordern eine isolierte Testkonfiguration und laufen mit pnpm test:e2e. Richte keine der Test-Suiten auf eine Entwicklungs- oder Produktionsdatenbank aus und setze niemals eine Datenbank ohne ausdrückliche Genehmigung zurück.