feat(mcp): OAuth so claude.ai and ChatGPT can connect as connectors

MindSift becomes the OAuth authorization server for its own MCP
endpoint: discovery (RFC 9728/8414), dynamic client registration,
authorization code with PKCE (S256), rotating refresh tokens with reuse
detection. The consent page lives in the app at /oauth/authorize. A
grant is an api_keys entry (kind 'oauth'), so scopes, origin badges,
renaming and revoking work as for keys; tokens are valid for /mcp only.
Unused connections expire after OAUTH_IDLE_DAYS (default 90). Requires
BASE_URL; off in demo mode. Release 0.51.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/api/apikey_access.go

@@ -17,6 +17,8 @@ import (
 type apiKeyAuth struct {
 	ID     string
 	Scopes []string
+	// OAuth: an access token of an OAuth connection (oauth.go), valid for the MCP endpoint only
+	OAuth bool
 }
 
 // apiActor: an API key acting on entries; via is storage.OriginAPI or storage.OriginMCP. Recorded as

internal/api/done_cleanup.go

@@ -14,14 +14,16 @@ import (
 
 // startDoneCleanupTicker runs the retention delays (storage/retention.go): completed tasks into the
 // task trash, the trashes and ticked-off list items emptied; once shortly after the start and then
-// every hour.
+// every hour. Expired and unused OAuth connections go in the same pass (oauth.go).
 func (s *Server) startDoneCleanupTicker() {
 	time.Sleep(2 * time.Minute)
 	s.runDoneCleanup(time.Now())
+	s.runOAuthCleanup(time.Now())
 	ticker := time.NewTicker(time.Hour)
 	defer ticker.Stop()
 	for now := range ticker.C {
 		s.runDoneCleanup(now)
+		s.runOAuthCleanup(now)
 	}
 }
 

internal/api/handlers_auth.go

@@ -48,6 +48,13 @@ func (s *Server) handleAuthStatus(w http.ResponseWriter, r *http.Request) {
 		"demoMode":            s.cfg.DemoMode,
 		"sharingMode":         s.store.SharingMode(),
 		"passwordReset":       s.passwordResetAvailable(),
+		// Address to enter as connector in claude.ai / ChatGPT (OAuth); empty while OAuth is off
+		"mcpConnectorUrl": func() string {
+			if s.oauthEnabled() {
+				return s.oauthResource()
+			}
+			return ""
+		}(),
 		// How voice input works: "server" (own Whisper), "browser" or "off"; set by STT_* only
 		// browserAllowed: whether people may pick the browser's recognition instead of the Whisper server
 		"voice": map[string]interface{}{"mode": s.voiceMode(), "maxSeconds": s.cfg.Speech.MaxSeconds, "browserAllowed": !s.cfg.Speech.NoBrowser},

internal/api/handlers_integrations.go

@@ -93,7 +93,7 @@ func (s *Server) handleWebhookIngest(w http.ResponseWriter, r *http.Request) {
 
 	// Same checks as every other request (revoked/outdated sessions, inactive accounts)
 	user, key := s.authenticateToken(token)
-	if user == nil {
+	if user == nil || (key != nil && key.OAuth) {
 		writeError(w, http.StatusUnauthorized, "Ungültiger Webhook-Token oder API-Key")
 		return
 	}

internal/api/oauth.go

@@ -0,0 +1,369 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/sandrodach/mindsift/internal/auth"
+	"github.com/sandrodach/mindsift/internal/storage"
+)
+
+// OAuth for the MCP endpoint (Doku/plans/oauth-fuer-mcp.md), so that claude.ai, ChatGPT and other
+// clients that cannot send an API key header can connect. MindSift is the authorization server for
+// its own MCP endpoint: discovery (RFC 9728, RFC 8414), dynamic client registration (RFC 7591),
+// authorization code with PKCE (S256 only, public clients) and rotating refresh tokens. The consent
+// page is part of the app (/oauth/authorize), because the login lives in the browser's storage, not
+// in a cookie the server could read. A grant is an api_keys entry (storage/oauth.go).
+//
+// Only with BASE_URL: it is the issuer and the resource, and building them from the Host header
+// would let anyone choose them. Off in the demo.
+
+const (
+	limitOAuthRegisterPerIP = 20
+	oauthMaxRedirectURIs    = 10
+)
+
+// Rights offered on the consent page; the narrow "create only" ones stay with ordinary keys.
+var oauthOfferedScopes = []string{storage.ScopeTasksRead, storage.ScopeTasksWrite, storage.ScopeListsRead, storage.ScopeListsWrite, storage.ScopeTriage}
+
+// Preselected when the client asks for nothing in particular (claude.ai usually does not)
+var oauthDefaultScopes = []string{storage.ScopeTasksRead, storage.ScopeTasksWrite, storage.ScopeListsRead, storage.ScopeListsWrite}
+
+func (s *Server) oauthEnabled() bool { return s.cfg.BaseURLSet && !s.cfg.DemoMode }
+
+func (s *Server) oauthIssuer() string { return strings.TrimRight(s.cfg.BaseURL, "/") }
+
+func (s *Server) oauthResource() string { return s.oauthIssuer() + mcpPath }
+
+func (s *Server) oauthResourceMetadataURL() string {
+	return s.oauthIssuer() + "/.well-known/oauth-protected-resource"
+}
+
+// oauthOnly answers 404 while OAuth is off, as if the endpoint did not exist.
+func (s *Server) oauthOnly(next http.HandlerFunc) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if !s.oauthEnabled() {
+			http.NotFound(w, r)
+			return
+		}
+		next(w, r)
+	}
+}
+
+// writeOAuthError: error body of the OAuth endpoints (RFC 6749 5.2)
+func writeOAuthError(w http.ResponseWriter, status int, code, description string) {
+	writeJSON(w, status, map[string]string{"error": code, "error_description": description})
+}
+
+func (s *Server) handleOAuthProtectedResource(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"resource":                 s.oauthResource(),
+		"authorization_servers":    []string{s.oauthIssuer()},
+		"scopes_supported":         oauthOfferedScopes,
+		"bearer_methods_supported": []string{"header"},
+		"resource_name":            "MindSift",
+	})
+}
+
+func (s *Server) handleOAuthServerMetadata(w http.ResponseWriter, r *http.Request) {
+	issuer := s.oauthIssuer()
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"issuer":                                         issuer,
+		"authorization_endpoint":                         issuer + "/oauth/authorize",
+		"token_endpoint":                                 issuer + "/oauth/token",
+		"registration_endpoint":                          issuer + "/oauth/register",
+		"revocation_endpoint":                            issuer + "/oauth/revoke",
+		"response_types_supported":                       []string{"code"},
+		"grant_types_supported":                          []string{"authorization_code", "refresh_token"},
+		"code_challenge_methods_supported":               []string{"S256"},
+		"token_endpoint_auth_methods_supported":          []string{"none"},
+		"revocation_endpoint_auth_methods_supported":     []string{"none"},
+		"scopes_supported":                               oauthOfferedScopes,
+		"authorization_response_iss_parameter_supported": true,
+	})
+}
+
+// validRedirectURI: https anywhere, plain http only back to this computer (desktop clients); no
+// fragment (RFC 6749 3.1.2).
+func validRedirectURI(raw string) bool {
+	u, err := url.Parse(raw)
+	if err != nil || u.Host == "" || u.Fragment != "" || u.User != nil {
+		return false
+	}
+	switch u.Scheme {
+	case "https":
+		return true
+	case "http":
+		h := u.Hostname()
+		return h == "localhost" || h == "127.0.0.1" || h == "::1"
+	}
+	return false
+}
+
+// handleOAuthRegister: POST /oauth/register (RFC 7591). Every client is public and authenticates
+// with PKCE only, so a requested client secret method is answered with "none".
+func (s *Server) handleOAuthRegister(w http.ResponseWriter, r *http.Request) {
+	if wait := s.loginGuard.throttle("oauth-register", clientIPFrom(r), limitOAuthRegisterPerIP); wait > 0 {
+		writeThrottled(w, wait)
+		return
+	}
+	var req struct {
+		ClientName   string   `json:"client_name"`
+		RedirectURIs []string `json:"redirect_uris"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeOAuthError(w, http.StatusBadRequest, "invalid_client_metadata", "Ungültiges JSON")
+		return
+	}
+	if len(req.RedirectURIs) == 0 || len(req.RedirectURIs) > oauthMaxRedirectURIs {
+		writeOAuthError(w, http.StatusBadRequest, "invalid_redirect_uri", "redirect_uris fehlt oder enthält zu viele Einträge")
+		return
+	}
+	for _, u := range req.RedirectURIs {
+		if !validRedirectURI(u) {
+			writeOAuthError(w, http.StatusBadRequest, "invalid_redirect_uri", "Nur https oder http://localhost erlaubt: "+u)
+			return
+		}
+	}
+	client, err := s.store.CreateOAuthClient(req.ClientName, req.RedirectURIs, time.Now())
+	if err != nil {
+		writeOAuthError(w, http.StatusInternalServerError, "server_error", err.Error())
+		return
+	}
+	writeJSON(w, http.StatusCreated, map[string]interface{}{
+		"client_id":                  client.ID,
+		"client_id_issued_at":        time.Now().Unix(),
+		"client_name":                client.Name,
+		"redirect_uris":              client.RedirectURIs,
+		"grant_types":                []string{"authorization_code", "refresh_token"},
+		"response_types":             []string{"code"},
+		"token_endpoint_auth_method": "none",
+	})
+}
+
+// oauthAuthorizeParams: the query of /oauth/authorize, handed on by the consent page
+type oauthAuthorizeParams struct {
+	ResponseType        string `json:"responseType"`
+	ClientID            string `json:"clientId"`
+	RedirectURI         string `json:"redirectUri"`
+	CodeChallenge       string `json:"codeChallenge"`
+	CodeChallengeMethod string `json:"codeChallengeMethod"`
+	State               string `json:"state"`
+	Scope               string `json:"scope"`
+	Resource            string `json:"resource"`
+}
+
+func oauthParamsFromQuery(q url.Values) oauthAuthorizeParams {
+	return oauthAuthorizeParams{
+		ResponseType:        q.Get("response_type"),
+		ClientID:            q.Get("client_id"),
+		RedirectURI:         q.Get("redirect_uri"),
+		CodeChallenge:       q.Get("code_challenge"),
+		CodeChallengeMethod: q.Get("code_challenge_method"),
+		State:               q.Get("state"),
+		Scope:               q.Get("scope"),
+		Resource:            q.Get("resource"),
+	}
+}
+
+var errOAuthNoRedirect = errors.New("Die Anwendung oder ihre Rücksprungadresse ist MindSift nicht bekannt. Bitte starte die Verbindung in der Anwendung neu.")
+
+// checkAuthorize validates an authorization request. Without a known client and redirect URI there is
+// nowhere safe to send the person back (err); every other problem goes back to the client as
+// errRedirect (RFC 6749 4.1.2.1).
+func (s *Server) checkAuthorize(p oauthAuthorizeParams) (client *storage.OAuthClient, errRedirect string, err error) {
+	client, err = s.store.GetOAuthClient(p.ClientID)
+	if err != nil {
+		return nil, "", errOAuthNoRedirect
+	}
+	known := false
+	for _, u := range client.RedirectURIs {
+		known = known || u == p.RedirectURI
+	}
+	if !known {
+		return nil, "", errOAuthNoRedirect
+	}
+	switch {
+	case p.ResponseType != "code":
+		return client, s.oauthRedirect(p, url.Values{"error": {"unsupported_response_type"}}), nil
+	case p.CodeChallenge == "" || p.CodeChallengeMethod != "S256":
+		return client, s.oauthRedirect(p, url.Values{"error": {"invalid_request"}, "error_description": {"PKCE (S256) ist erforderlich"}}), nil
+	case p.Resource != "" && strings.TrimRight(p.Resource, "/") != s.oauthResource() && strings.TrimRight(p.Resource, "/") != s.oauthIssuer():
+		return client, s.oauthRedirect(p, url.Values{"error": {"invalid_target"}}), nil
+	}
+	return client, "", nil
+}
+
+// oauthRedirect: the client's redirect URI with the answer, its state and the issuer (RFC 9207)
+func (s *Server) oauthRedirect(p oauthAuthorizeParams, values url.Values) string {
+	u, _ := url.Parse(p.RedirectURI)
+	q := u.Query()
+	for k, v := range values {
+		q[k] = v
+	}
+	if p.State != "" {
+		q.Set("state", p.State)
+	}
+	q.Set("iss", s.oauthIssuer())
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+// oauthScopes keeps the offered rights out of a list, in display order.
+func oauthScopes(requested []string) []string {
+	want := map[string]bool{}
+	for _, sc := range requested {
+		want[strings.TrimSpace(sc)] = true
+	}
+	out := []string{}
+	for _, sc := range oauthOfferedScopes {
+		if want[sc] {
+			out = append(out, sc)
+		}
+	}
+	return out
+}
+
+func redirectHost(raw string) string {
+	if u, err := url.Parse(raw); err == nil {
+		return u.Host
+	}
+	return raw
+}
+
+// handleOAuthAuthorizeInfo: GET /api/v1/oauth/authorize?<query of /oauth/authorize> – what the consent
+// page shows. Only for a login (API keys are not allowed here, see keyRoutes).
+func (s *Server) handleOAuthAuthorizeInfo(w http.ResponseWriter, r *http.Request) {
+	p := oauthParamsFromQuery(r.URL.Query())
+	client, errRedirect, err := s.checkAuthorize(p)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	if errRedirect != "" {
+		writeJSON(w, http.StatusOK, map[string]string{"redirect": errRedirect})
+		return
+	}
+	scopes := oauthScopes(strings.Fields(p.Scope))
+	if len(scopes) == 0 {
+		scopes = oauthDefaultScopes
+	}
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"clientName":    client.Name,
+		"redirectHost":  redirectHost(p.RedirectURI),
+		"scopes":        scopes,
+		"offeredScopes": oauthOfferedScopes,
+	})
+}
+
+// handleOAuthAuthorize: POST /api/v1/oauth/authorize – the person allows (with the chosen rights) or
+// refuses; the answer is the URL the consent page sends the browser to.
+func (s *Server) handleOAuthAuthorize(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		oauthAuthorizeParams
+		Approve bool     `json:"approve"`
+		Scopes  []string `json:"scopes"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "Ungültige Anfrage")
+		return
+	}
+	p := req.oauthAuthorizeParams
+	client, errRedirect, err := s.checkAuthorize(p)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	if errRedirect != "" {
+		writeJSON(w, http.StatusOK, map[string]string{"redirect": errRedirect})
+		return
+	}
+	if !req.Approve {
+		writeJSON(w, http.StatusOK, map[string]string{"redirect": s.oauthRedirect(p, url.Values{"error": {"access_denied"}})})
+		return
+	}
+	scopes := oauthScopes(req.Scopes)
+	if len(scopes) == 0 {
+		writeError(w, http.StatusBadRequest, "Wähle mindestens ein Recht aus.")
+		return
+	}
+	code, err := s.store.GrantOAuth(auth.GetUserID(r.Context()), client, scopes, p.RedirectURI, p.CodeChallenge, time.Now())
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"redirect": s.oauthRedirect(p, url.Values{"code": {code}})})
+}
+
+// oauthClientID: public clients send client_id in the form; some use HTTP Basic with an empty secret.
+func oauthClientID(r *http.Request) string {
+	if id := r.PostForm.Get("client_id"); id != "" {
+		return id
+	}
+	id, _, _ := r.BasicAuth()
+	return id
+}
+
+// handleOAuthToken: POST /oauth/token (form-encoded) – authorization_code and refresh_token.
+func (s *Server) handleOAuthToken(w http.ResponseWriter, r *http.Request) {
+	if err := r.ParseForm(); err != nil {
+		writeOAuthError(w, http.StatusBadRequest, "invalid_request", "Ungültige Anfrage")
+		return
+	}
+	clientID := oauthClientID(r)
+	var tokens *storage.OAuthTokens
+	var err error
+	switch r.PostForm.Get("grant_type") {
+	case "authorization_code":
+		tokens, err = s.store.ExchangeOAuthCode(r.PostForm.Get("code"), clientID, r.PostForm.Get("redirect_uri"),
+			r.PostForm.Get("code_verifier"), time.Now())
+	case "refresh_token":
+		tokens, err = s.store.RefreshOAuth(r.PostForm.Get("refresh_token"), clientID, time.Now())
+	default:
+		writeOAuthError(w, http.StatusBadRequest, "unsupported_grant_type", "Nur authorization_code und refresh_token")
+		return
+	}
+	if errors.Is(err, storage.ErrOAuthInvalidGrant) {
+		writeOAuthError(w, http.StatusBadRequest, "invalid_grant", "Code oder Token ungültig, abgelaufen oder widerrufen")
+		return
+	}
+	if err != nil {
+		writeOAuthError(w, http.StatusInternalServerError, "server_error", err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"access_token":  tokens.AccessToken,
+		"token_type":    "Bearer",
+		"expires_in":    tokens.ExpiresIn,
+		"refresh_token": tokens.RefreshToken,
+		"scope":         strings.Join(tokens.Scopes, " "),
+	})
+}
+
+// handleOAuthRevoke: POST /oauth/revoke (RFC 7009); answers 200 even for unknown tokens.
+func (s *Server) handleOAuthRevoke(w http.ResponseWriter, r *http.Request) {
+	if err := r.ParseForm(); err != nil {
+		writeOAuthError(w, http.StatusBadRequest, "invalid_request", "Ungültige Anfrage")
+		return
+	}
+	s.store.RevokeOAuthToken(r.PostForm.Get("token"), oauthClientID(r))
+	w.WriteHeader(http.StatusOK)
+}
+
+// runOAuthCleanup: expired codes and tokens, abandoned registrations and – after OAUTH_IDLE_DAYS –
+// connections nobody used.
+func (s *Server) runOAuthCleanup(now time.Time) {
+	n, err := s.store.PurgeOAuth(now, s.cfg.OAuthIdleDays)
+	if err != nil {
+		slog.Error("Aufräumen der OAuth-Zugänge fehlgeschlagen", "error", err)
+		return
+	}
+	if n > 0 {
+		slog.Info("Unbenutzte OAuth-Zugänge entfernt", "anzahl", n, "tage", s.cfg.OAuthIdleDays)
+	}
+}

internal/api/oauth_test.go

@@ -0,0 +1,222 @@
+package api
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/sandrodach/mindsift/internal/auth"
+	"github.com/sandrodach/mindsift/internal/domain"
+)
+
+const oauthTestRedirect = "https://claude.ai/api/mcp/auth_callback"
+
+// oauthDo sends one request and returns status, headers and the decoded JSON body.
+func oauthDo(t *testing.T, router http.Handler, method, path, bearer, contentType, body string) (int, http.Header, map[string]interface{}) {
+	t.Helper()
+	req := httptest.NewRequest(method, path, strings.NewReader(body))
+	if contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	if bearer != "" {
+		req.Header.Set("Authorization", "Bearer "+bearer)
+	}
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	var out map[string]interface{}
+	_ = json.Unmarshal(rec.Body.Bytes(), &out)
+	return rec.Code, rec.Header(), out
+}
+
+func pkceChallenge(verifier string) string {
+	sum := sha256.Sum256([]byte(verifier))
+	return base64.RawURLEncoding.EncodeToString(sum[:])
+}
+
+// The whole connection as claude.ai makes it: discovery, registration, consent, code, MCP, refresh.
+func TestOAuthFlowForMCP(t *testing.T) {
+	srv, store, session := setupTestServer(t)
+	router := srv.Router()
+	claims, _ := auth.ValidateToken(testJWTSecret, session)
+	const jsonType = "application/json"
+	const formType = "application/x-www-form-urlencoded"
+
+	// Without BASE_URL there is no OAuth at all
+	if code, _, _ := oauthDo(t, router, http.MethodGet, "/.well-known/oauth-protected-resource", "", "", ""); code != http.StatusNotFound {
+		t.Fatalf("OAuth must be off without BASE_URL, got %d", code)
+	}
+	if _, h, _ := oauthDo(t, router, http.MethodPost, mcpPath, "", jsonType, `{}`); h.Get("WWW-Authenticate") != "" {
+		t.Fatalf("no OAuth hint without BASE_URL, got %q", h.Get("WWW-Authenticate"))
+	}
+
+	srv.cfg.BaseURL = "https://ms.example/"
+	srv.cfg.BaseURLSet = true
+	router = srv.Router()
+
+	code, h, _ := oauthDo(t, router, http.MethodPost, mcpPath, "", jsonType, `{}`)
+	if code != http.StatusUnauthorized || !strings.Contains(h.Get("WWW-Authenticate"), `resource_metadata="https://ms.example/.well-known/oauth-protected-resource"`) {
+		t.Fatalf("MCP without token should point to the metadata: %d %q", code, h.Get("WWW-Authenticate"))
+	}
+	_, _, meta := oauthDo(t, router, http.MethodGet, "/.well-known/oauth-protected-resource/api/v1/mcp", "", "", "")
+	if meta["resource"] != "https://ms.example/api/v1/mcp" {
+		t.Fatalf("resource metadata: %v", meta)
+	}
+	_, _, meta = oauthDo(t, router, http.MethodGet, "/.well-known/oauth-authorization-server", "", "", "")
+	if meta["issuer"] != "https://ms.example" || meta["token_endpoint"] != "https://ms.example/oauth/token" {
+		t.Fatalf("server metadata: %v", meta)
+	}
+
+	// Registration: only https or loopback
+	if code, _, _ := oauthDo(t, router, http.MethodPost, "/oauth/register", "", jsonType, `{"client_name":"X","redirect_uris":["http://evil.example/cb"]}`); code != http.StatusBadRequest {
+		t.Fatalf("plain http redirect must be refused, got %d", code)
+	}
+	code, _, reg := oauthDo(t, router, http.MethodPost, "/oauth/register", "", jsonType, `{"client_name":"Claude","redirect_uris":["`+oauthTestRedirect+`"],"token_endpoint_auth_method":"client_secret_post"}`)
+	if code != http.StatusCreated || reg["token_endpoint_auth_method"] != "none" {
+		t.Fatalf("register: %d %v", code, reg)
+	}
+	clientID := reg["client_id"].(string)
+
+	verifier := strings.Repeat("v", 50)
+	params := func(redirect, challenge string) url.Values {
+		return url.Values{"response_type": {"code"}, "client_id": {clientID}, "redirect_uri": {redirect},
+			"code_challenge": {challenge}, "code_challenge_method": {"S256"}, "state": {"st8"}, "resource": {"https://ms.example/api/v1/mcp"}}
+	}
+
+	// Consent page info: unknown redirect is an error shown on the page, never a redirect
+	if code, _, _ := oauthDo(t, router, http.MethodGet, "/api/v1/oauth/authorize?"+params("https://evil.example/cb", pkceChallenge(verifier)).Encode(), session, "", ""); code != http.StatusBadRequest {
+		t.Fatalf("unknown redirect_uri must be refused, got %d", code)
+	}
+	_, _, info := oauthDo(t, router, http.MethodGet, "/api/v1/oauth/authorize?"+params(oauthTestRedirect, "").Encode(), session, "", "")
+	if r, _ := info["redirect"].(string); !strings.Contains(r, "error=invalid_request") {
+		t.Fatalf("missing PKCE must go back as invalid_request: %v", info)
+	}
+	_, _, info = oauthDo(t, router, http.MethodGet, "/api/v1/oauth/authorize?"+params(oauthTestRedirect, pkceChallenge(verifier)).Encode(), session, "", "")
+	if info["clientName"] != "Claude" || info["redirectHost"] != "claude.ai" || len(info["scopes"].([]interface{})) != 4 {
+		t.Fatalf("consent info: %v", info)
+	}
+	// API keys cannot agree on anyone's behalf
+	key, _ := store.CreateAPIKey(claims.UserID, "Skript", []string{"tasks:read"})
+	if code, _, _ := oauthDo(t, router, http.MethodGet, "/api/v1/oauth/authorize?"+params(oauthTestRedirect, pkceChallenge(verifier)).Encode(), key.RawKey, "", ""); code != http.StatusForbidden {
+		t.Fatalf("API key must not reach the consent endpoint, got %d", code)
+	}
+
+	consent := func(approve bool, scopes string) string {
+		t.Helper()
+		body := `{"responseType":"code","clientId":"` + clientID + `","redirectUri":"` + oauthTestRedirect + `","codeChallenge":"` +
+			pkceChallenge(verifier) + `","codeChallengeMethod":"S256","state":"st8","approve":` + map[bool]string{true: "true", false: "false"}[approve] +
+			`,"scopes":` + scopes + `}`
+		code, _, out := oauthDo(t, router, http.MethodPost, "/api/v1/oauth/authorize", session, jsonType, body)
+		if code != http.StatusOK {
+			t.Fatalf("consent: %d %v", code, out)
+		}
+		return out["redirect"].(string)
+	}
+	if r := consent(false, `[]`); !strings.Contains(r, "error=access_denied") || !strings.Contains(r, "state=st8") {
+		t.Fatalf("refusing should report access_denied with state: %s", r)
+	}
+	codeOf := func(redirect string) string {
+		u, _ := url.Parse(redirect)
+		if u.Query().Get("state") != "st8" || u.Query().Get("iss") != "https://ms.example" {
+			t.Fatalf("redirect lacks state or iss: %s", redirect)
+		}
+		return u.Query().Get("code")
+	}
+	token := func(form url.Values) (int, map[string]interface{}) {
+		code, _, out := oauthDo(t, router, http.MethodPost, "/oauth/token", "", formType, form.Encode())
+		return code, out
+	}
+	exchange := func(code, redirect, verifier string) url.Values {
+		return url.Values{"grant_type": {"authorization_code"}, "code": {code}, "client_id": {clientID}, "redirect_uri": {redirect}, "code_verifier": {verifier}}
+	}
+
+	// A wrong verifier uses the code up
+	c1 := codeOf(consent(true, `["tasks:read"]`))
+	if code, out := token(exchange(c1, oauthTestRedirect, strings.Repeat("w", 50))); code != http.StatusBadRequest || out["error"] != "invalid_grant" {
+		t.Fatalf("wrong verifier: %d %v", code, out)
+	}
+	if code, _ := token(exchange(c1, oauthTestRedirect, verifier)); code != http.StatusBadRequest {
+		t.Fatalf("a code works only once, got %d", code)
+	}
+	c2 := codeOf(consent(true, `["tasks:read"]`))
+	if code, _ := token(exchange(c2, "https://claude.ai/other", verifier)); code != http.StatusBadRequest {
+		t.Fatalf("redirect_uri must match the code's, got %d", code)
+	}
+	c3 := codeOf(consent(true, `["tasks:read"]`))
+	code, tok := token(exchange(c3, oauthTestRedirect, verifier))
+	if code != http.StatusOK || tok["scope"] != "tasks:read" || tok["token_type"] != "Bearer" {
+		t.Fatalf("token: %d %v", code, tok)
+	}
+	access, refresh := tok["access_token"].(string), tok["refresh_token"].(string)
+
+	// The access token works at MCP with exactly the agreed rights, and nowhere else
+	_, res := rpc(t, router, access, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`)
+	names := strings.Join(toolNames(res), ",")
+	if !strings.Contains(names, "list_tasks") || strings.Contains(names, "complete_task") || strings.Contains(names, "get_list") {
+		t.Fatalf("tools for tasks:read: %s", names)
+	}
+	if code, _, _ := oauthDo(t, router, http.MethodGet, "/api/v1/tasks", access, "", ""); code != http.StatusForbidden {
+		t.Fatalf("OAuth token must not reach REST, got %d", code)
+	}
+	if code, _, _ := oauthDo(t, router, http.MethodPost, "/api/v1/webhooks/ingest", access, jsonType, `{"content":"x"}`); code != http.StatusUnauthorized {
+		t.Fatalf("OAuth token must not deliver webhooks, got %d", code)
+	}
+
+	// Agent changes carry the connection's name, which is listed among the keys; agreeing again
+	// does not add a second entry
+	_, res = rpc(t, router, access, `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_tasks","arguments":{}}}`)
+	if _, isErr := callResult(t, res); isErr {
+		t.Fatalf("list_tasks via OAuth: %v", res)
+	}
+	codeOf(consent(true, `["tasks:read","lists:read"]`))
+	keys, _ := store.GetAPIKeys(claims.UserID)
+	var grant *domain.APIKey
+	for i := range keys {
+		if keys[i].Kind == "oauth" {
+			if grant != nil {
+				t.Fatalf("consenting again must reuse the entry: %v", keys)
+			}
+			grant = &keys[i]
+		}
+	}
+	if grant == nil || grant.Name != "Claude (OAuth)" || grant.Scopes != "tasks:read,lists:read" || grant.LastUsedAt == "" {
+		t.Fatalf("OAuth entry: %+v", grant)
+	}
+
+	// Refresh rotates; the old refresh token used again ends the whole connection
+	code, tok2 := token(url.Values{"grant_type": {"refresh_token"}, "refresh_token": {refresh}, "client_id": {clientID}})
+	if code != http.StatusOK || tok2["scope"] != "tasks:read lists:read" {
+		t.Fatalf("refresh: %d %v", code, tok2)
+	}
+	access2 := tok2["access_token"].(string)
+	if code, _ := rpc(t, router, access2, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`); code != http.StatusOK {
+		t.Fatalf("refreshed access token: %d", code)
+	}
+	if code, _ := token(url.Values{"grant_type": {"refresh_token"}, "refresh_token": {refresh}, "client_id": {clientID}}); code != http.StatusBadRequest {
+		t.Fatalf("reused refresh token must fail, got %d", code)
+	}
+	if code, _ := rpc(t, router, access2, `{"jsonrpc":"2.0","id":4,"method":"tools/list"}`); code != http.StatusUnauthorized {
+		t.Fatalf("reuse must end every token of the connection, got %d", code)
+	}
+
+	// Removing the entry in the settings ends a fresh connection right away
+	c4 := codeOf(consent(true, `["tasks:read"]`))
+	_, tok3 := token(exchange(c4, oauthTestRedirect, verifier))
+	access3 := tok3["access_token"].(string)
+	if code, _, _ := oauthDo(t, router, http.MethodDelete, "/api/v1/keys/"+grant.ID, session, "", ""); code != http.StatusOK {
+		t.Fatalf("delete entry: %d", code)
+	}
+	if code, _ := rpc(t, router, access3, `{"jsonrpc":"2.0","id":5,"method":"tools/list"}`); code != http.StatusUnauthorized {
+		t.Fatalf("revoked connection must stop working, got %d", code)
+	}
+
+	// The demo has no OAuth
+	srv.cfg.DemoMode = true
+	if code, _, _ := oauthDo(t, srv.Router(), http.MethodPost, "/oauth/register", "", jsonType, `{"redirect_uris":["`+oauthTestRedirect+`"]}`); code != http.StatusNotFound {
+		t.Fatalf("OAuth must be off in the demo, got %d", code)
+	}
+}

internal/api/server.go

@@ -150,6 +150,14 @@ func (s *Server) Router() http.Handler {
 	r.Get("/api/v1/ws/lists/{listId}", s.handleWebSocket)
 	r.Get("/api/v1/events", s.handleSSE)
 
+	// OAuth for the MCP endpoint (oauth.go); the consent page /oauth/authorize is part of the app
+	r.Get("/.well-known/oauth-protected-resource", s.oauthOnly(s.handleOAuthProtectedResource))
+	r.Get("/.well-known/oauth-protected-resource/*", s.oauthOnly(s.handleOAuthProtectedResource))
+	r.Get("/.well-known/oauth-authorization-server", s.oauthOnly(s.handleOAuthServerMetadata))
+	r.Post("/oauth/register", s.oauthOnly(s.handleOAuthRegister))
+	r.Post("/oauth/token", s.oauthOnly(s.handleOAuthToken))
+	r.Post("/oauth/revoke", s.oauthOnly(s.handleOAuthRevoke))
+
 	// Authenticated API Routes
 	r.Group(func(r chi.Router) {
 		r.Use(s.authMiddleware)
@@ -304,6 +312,8 @@ func (s *Server) Router() http.Handler {
 		r.Post(mcpPath, s.handleMCP)
 		r.Get(mcpPath, handleMCPNoStream)
 		r.Delete(mcpPath, handleMCPNoStream)
+		r.Get("/api/v1/oauth/authorize", s.oauthOnly(s.handleOAuthAuthorizeInfo))
+		r.Post("/api/v1/oauth/authorize", s.oauthOnly(s.handleOAuthAuthorize))
 
 		// API Keys Management
 		r.Get("/api/v1/keys", s.handleGetAPIKeys)
@@ -489,6 +499,16 @@ func (s *Server) authenticateToken(token string) (user *domain.User, key *apiKey
 		}
 		return u, &apiKeyAuth{ID: keyID, Scopes: scopes}
 	}
+	if strings.HasPrefix(token, storage.OAuthAccessPrefix) {
+		if !s.oauthEnabled() {
+			return nil, nil
+		}
+		u, scopes, keyID, err := s.store.ValidateOAuthAccessToken(token, time.Now())
+		if err != nil || u == nil || !u.IsActive {
+			return nil, nil
+		}
+		return u, &apiKeyAuth{ID: keyID, Scopes: scopes, OAuth: true}
+	}
 	claims, err := auth.ValidateToken(s.cfg.JWTSecret, token)
 	if err != nil || claims == nil {
 		return nil, nil
@@ -517,9 +537,18 @@ func (s *Server) authMiddleware(next http.Handler) http.Handler {
 		}
 		user, key := s.authenticateToken(token)
 		if user == nil {
+			// Tells MCP clients where to start the OAuth flow (RFC 9728)
+			if r.URL.Path == mcpPath && s.oauthEnabled() {
+				w.Header().Set("WWW-Authenticate", `Bearer resource_metadata="`+s.oauthResourceMetadataURL()+`"`)
+			}
 			writeError(w, http.StatusUnauthorized, "Nicht autorisiert – bitte anmelden")
 			return
 		}
+		// OAuth tokens were issued for the MCP endpoint only
+		if key != nil && key.OAuth && r.URL.Path != mcpPath {
+			writeError(w, http.StatusForbidden, "OAuth-Zugänge gelten nur für den MCP-Endpunkt")
+			return
+		}
 		ctx := auth.WithUserID(r.Context(), user.ID)
 		if key == nil {
 			if claims, err := auth.ValidateToken(s.cfg.JWTSecret, token); err == nil {