// Package mcpsrv is dolt.sr.ht's Model Context Protocol surface: the read-only
// tools of docs/DESIGN.mcp.md ch. 9 an agent calls to read a hosted Dolt
// database — and the beads tracker inside it — served over streamable HTTP at
// /mcp on the daemon's web listener.
//
// The donor is cov.sr.ht's mcpsrv/, the newest of the four this instance already
// runs, and the family convention is to copy the pattern rather than import it:
// the SDK server built in New, the tools registered through the generic
// mcp.AddTool so every schema is derived from a Go struct, the streamable
// handler mounted on the service's own router, and the Host allowlist that
// replaces the SDK's DNS-rebinding guard.
//
// # A surface, not a second service
//
// Nothing here re-derives what the rest of the service already decides.
// Visibility is core.Allowed over the grant the metadata store resolves, the
// beads fingerprint is beads.Applies, the default branch is
// browse.DefaultBranch. Two surfaces that each grew their own copy is how they
// start answering one question differently, quietly, months later — so the
// browse handlers' dance (web/router.go's loadRepoForBrowse) is reproduced here
// call for call rather than re-thought.
//
// # No engine, no writes
//
// The whole pure-Go build stands on one fact: this service never starts the SQL
// engine, because a bare NBS store has no working set to start it against
// (browse/open.go). This surface changes nothing about that. There is no
// query(sql) tool and there will not be one, there is no mutation of any kind,
// and neither is a rule anybody has to remember: ports.go names no seam that
// could reach either, so a handler here cannot write what it has no way to
// call.
//
// # Identity
//
// This is the only bearer surface the service has, so the credential middleware
// lives here rather than in the daemon (which is the one departure from the
// donor, whose siblings share a resolver in front of three surfaces). A request
// carrying no Authorization header is anonymous, and anonymous is a normal
// caller: it reads what anonymity may read. A bearer token that fails to resolve
// is a refusal and never a downgrade to anonymous, with authn/bearer.go's two
// error classes rendered as 401, 403 and 503 (resolveCaller).
//
// How that caller reaches a tool handler is decided by the SDK's transport and
// is why this one runs stateless; the constant below carries the argument and
// the measurement made against the version go.mod pins.
package mcpsrv

import (
	"context"
	"errors"
	"log/slog"
	"net"
	"net/http"
	"runtime/debug"
	"strings"

	"github.com/modelcontextprotocol/go-sdk/mcp"
	"go.bigb.es/auxilia/culpa"
	"go.bigb.es/auxilia/scribe"

	"sourcecraft.dev/bigbes/sr-ht-ecore/bearer"
	"sourcecraft.dev/bigbes/sr-ht-ecore/instconf"

	"sourcecraft.dev/bigbes/sr-ht-dolt/authn"
	"sourcecraft.dev/bigbes/sr-ht-dolt/beads"
	"sourcecraft.dev/bigbes/sr-ht-dolt/core"
)

const (
	// ServerName is the implementation name reported in the MCP handshake, and
	// the realm of every 401 this surface writes.
	//
	// It is the service's config-section name spelled as a literal rather than
	// read from a config section: a client listing several SourceHut MCP
	// endpoints tells them apart by this string, so it is part of this surface's
	// contract and does not follow a key that may move for reasons of its own.
	ServerName = "dolt.sr.ht"

	// stateless puts the streamable transport in stateless mode, and that is an
	// authentication decision rather than a performance one
	// (docs/DESIGN.mcp.md §5).
	//
	// The SDK connects a session with the context of the HTTP request that
	// created it, and every tool call that session handles then runs under that
	// one context. In stateful mode the creating request is the *initialize*
	// handshake, so the caller resolved for the handshake answers every later
	// tools/call on that session — and the consequence is worse than a stale
	// authority: the session id becomes a bearer credential in its own right,
	// issued by a service that issues none, and the credential presented on the
	// call is not consulted at all. Anyone holding that id — a proxy log, a crash
	// report, a shared client's state file — then reads as the caller who opened
	// the session, and a token revoked mid-session keeps working until the client
	// reconnects.
	//
	// Stateless mode connects a temporary session per POST, so a tool handler's
	// context descends from the request that carried the call, credential
	// middleware included, and identity is per call — which is what a bearer
	// surface means.
	//
	// The measurement behind this is the donor's, and a paragraph is not a
	// measurement: TestIdentityIsPerCallAndNotPerSession re-makes it here,
	// against the SDK version go.mod pins, by swapping the credential
	// mid-session. Flipping this constant to false and running it gives, for one
	// session whose handshake carried no credential and one owner with six
	// databases of which four are public:
	//
	//	stateless: handshake anonymous, call with the OWNER's token -> 6
	//	           handshake anonymous, call with NO credential     -> 4
	//	stateful:  handshake anonymous, call with the OWNER's token -> 4
	//	           i.e. the token on the call is not consulted at all
	//
	// and the mirror image — a handshake that *did* carry a token — is the same
	// fact the other way round: the session answers as its opener to a caller
	// presenting nothing.
	//
	// What it costs is the server->client half of the protocol: no standalone SSE
	// stream, so no server-initiated requests, and a GET is answered 405. Every
	// tool of ch. 9 is a read that answers in one response — none samples,
	// elicits or reports progress — so there is nothing to give up.
	stateless = true

	// privateVary is what every answer of this endpoint actually depends on, and
	// it names one header rather than the donor's two: /mcp is bearer-only
	// (docs/DESIGN.mcp.md §4.1). The unified-login cookie is the web UI's plane
	// and is not read here, so promising a cache that answers vary by it would be
	// a promise about a header this surface never looks at.
	privateVary = "Authorization"

	// refusalCacheControl is the private-cache pair every refusal carries.
	refusalCacheControl = "private, no-store"

	// answerCacheControl is that pair plus the one directive the SDK sets for its
	// own reasons. The transport writes `no-cache, no-transform` on every
	// response it produces: no-transform protects the SSE framing from an
	// intermediary that would recompress or rechunk it, and is kept; no-cache is
	// replaced, because it permits a cache to *store* the body and merely
	// revalidate — which is exactly what no-store forbids and what an answer
	// carrying a PRIVATE database's contents may not allow.
	answerCacheControl = refusalCacheControl + ", no-transform"
)

// bearerChallenge is the RFC 7235 challenge every 401 of this surface carries.
// bearer.Challenge assembles it, so the quoting RFC 9110 §11.6.1 requires of a
// realm is done once for the instance rather than by hand in six services.
var bearerChallenge = bearer.Challenge(ServerName)

// A Server is the MCP surface: the SDK server with the tools registered,
// wrapped in the HTTP chain the daemon mounts at /mcp.
//
// It holds no request state and is safe for concurrent use — the caller's
// identity travels in the request context, never on the server — which is what
// lets one instance serve every session.
type Server struct {
	repos  Repos
	opener BrowseOpener

	// validator verifies a tokens.sr.ht working token. It may be nil, and a nil
	// one is a configuration rather than a degradation: an instance whose
	// config.ini carries no [tokens.sr.ht] origin has no such daemon, so meta
	// PATs and anonymity keep working and a working token is refused rather than
	// guessed at (authn.ResolveBearer documents the contract, including that a
	// *typed* nil is not it).
	validator authn.InstanceValidator

	// mcp is the protocol server the tools are registered on, kept so that a test
	// can connect an in-memory transport to it without going through HTTP
	// (Connect).
	mcp *mcp.Server

	// ready is ready_work's projection cache: one ready set per database, gated
	// on that database's head hash and expiring on beads.ReadyCacheTTL. It is
	// the one piece of state that outlives a call here, and it is built once, per
	// server — a cache created per call is not a cache, and the head-hash gate it
	// exists to enforce would never fire.
	//
	// It holds projections and never an open store, which is what makes holding
	// it across calls compatible with opening a session per call: an open store
	// is a file handle and a memory mapping, and that is precisely what the
	// per-call discipline exists not to hoard (beads.ReadyCache).
	ready *beads.ReadyCache

	// http is the whole handler chain. It is built once, in New, because
	// mcp.NewStreamableHTTPHandler owns transport state and two of them would be
	// two servers.
	http http.Handler
}

// A Server is an http.Handler: the daemon mounts it with r.Handle("/mcp", s) —
// Handle and not Mount, because the streamable handler serves that exact path
// (docs/DESIGN.mcp.md §3).
var _ http.Handler = (*Server)(nil)

// New builds the MCP surface over its seams.
//
// origin is [dolt.sr.ht]origin — the instance's public base URL — and it is
// required: it is the Host allowlist this endpoint is guarded by (allowHosts).
// An origin with no host is a wiring error and is refused here rather than
// warned about and then served unguarded.
//
// validator may be nil (see Server.validator). repos and opener may not: a
// surface that answered every call "internal error" because a seam was never
// wired would be a daemon that starts and does not work, and the daemon that
// wired it is not an operator to be warned, it is a bug.
func New(repos Repos, opener BrowseOpener, validator authn.InstanceValidator, origin string) (*Server, error) {
	if repos == nil {
		return nil, culpa.New("mcpsrv: nil Repos")
	}
	if opener == nil {
		return nil, culpa.New("mcpsrv: nil BrowseOpener")
	}
	// instconf.OriginHost is the instance's one reading of "what host does this
	// origin name": the name without the port, "" for anything that does not
	// parse — never a guessed "localhost", which would make every malformed
	// origin agree with a local client on the one code path where that decides
	// an allowlist.
	host := instconf.OriginHost(origin)
	if host == "" {
		return nil, culpa.Errorf("mcpsrv: origin %q has no host to guard /mcp with", origin)
	}

	s := &Server{repos: repos, opener: opener, validator: validator, ready: beads.NewReadyCache()}
	s.mcp = mcp.NewServer(&mcp.Implementation{Name: ServerName, Version: serverVersion()}, nil)
	s.register()

	// The SDK's DNS-rebinding guard is disabled deliberately, and disabling a
	// security default usually is not defensible, so here is why this one is.
	//
	// The guard refuses any request that arrives on a loopback address carrying a
	// non-loopback Host header. That is precisely this deployment: the daemon
	// binds localhost and Traefik/nginx forwards with the instance's public Host
	// (docs/DESIGN.mcp.md §3, §6). Every genuine request would be a 403 — and
	// only in production, because a local client sends a loopback Host and
	// passes.
	//
	// It is not that the guard has nothing to catch: a browser running on the
	// daemon's own host could reach the loopback port directly with an attacker's
	// Host. The guard simply cannot tell that request from the proxy's — both
	// arrive from loopback with a non-loopback Host — and the SDK offers no
	// allowlist to separate them. So it is disabled and *replaced*, in the same
	// constructor, by a stricter check.
	handler := mcp.NewStreamableHTTPHandler(
		func(*http.Request) *mcp.Server { return s.mcp },
		&mcp.StreamableHTTPOptions{
			DisableLocalhostProtection: true,
			Stateless:                  stateless,
		},
	)

	// The order of the wrappers is the order of the questions, outermost first,
	// and each one is where it is for a reason:
	//
	//	privateCache        every answer AND every refusal is unstorable, so it
	//	                    wraps the lot — including the Host 403, which is
	//	                    written before the SDK is reached at all.
	//	allowHosts          a request naming somebody else's host is refused
	//	                    before its credential is even parsed: there is no
	//	                    reason to spend an HMAC, or a meta lookup, on a
	//	                    request this endpoint will not answer.
	//	resolveCaller       who is calling, once per request, put in the context
	//	                    the SDK will hand every tool handler.
	//	requireReadGrant    what that credential covers, asked after it resolved
	//	                    and before a session is negotiated or a tool named.
	s.http = privateCache(allowHosts(s.resolveCaller(requireReadGrant(handler)), host))
	return s, nil
}

// ServeHTTP serves the streamable MCP transport behind the chain New built.
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { s.http.ServeHTTP(w, r) }

// Connect attaches the protocol server to a transport directly, for a caller
// that speaks MCP without HTTP — the in-process client the tools are tested
// with (docs/DESIGN.mcp.md §12).
//
// It exists so that a test drives the very server the daemon serves: the tools,
// their schemas and their handlers are registered once, in New, and a second
// registration path for tests would be a second surface to keep in agreement.
// The caller comes from ctx exactly as it does over HTTP — the SDK connects the
// session with the context it is given and every handler descends from it (see
// stateless).
func (s *Server) Connect(ctx context.Context, t mcp.Transport) (*mcp.ServerSession, error) {
	return s.mcp.Connect(ctx, t, nil)
}

type contextKey struct{ name string }

// bearerCallerKey holds the resolved *authn.BearerCaller for the grant gate.
//
// The identity itself goes where the rest of the service looks for it
// (authn.WithCaller), so a tool handler reads a caller the same way a web
// handler does. What has no house-wide home is the tokens.sr.ht grant set: it
// exists only on a working token, only this surface asks about it, and putting
// it on the shared AuthContext would subject it to core-go's entirely different
// OAuth gate (authn/bearer.go says why). So it stays here, private to this
// package, read by requireReadGrant alone.
var bearerCallerKey = &contextKey{"mcpsrv.bearerCaller"}

func withBearerCaller(ctx context.Context, bc *authn.BearerCaller) context.Context {
	return context.WithValue(ctx, bearerCallerKey, bc)
}

func bearerCallerFrom(ctx context.Context) *authn.BearerCaller {
	bc, _ := ctx.Value(bearerCallerKey).(*authn.BearerCaller)
	return bc
}

// callerOf is how a tool handler learns who is asking: the core.Caller the
// access matrix is written against, nil for an anonymous caller.
//
// It reads the context and nothing else. There is no field on Server holding a
// caller and there must not be: one Server answers every session, and identity
// that lived on it would be the last caller's rather than this call's.
func callerOf(ctx context.Context) *core.Caller {
	return authn.AsCoreCaller(authn.CallerFromContext(ctx))
}

// resolveCaller is this surface's credential middleware: the bearer plane of
// docs/DESIGN.mcp.md §4.1, and the only one it accepts.
//
// It lives here rather than in the daemon because /mcp is the only bearer
// surface this service has — the web UI resolves a cookie, the remotesapi
// resolves Basic and a dolt JWT, and each does it in its own place. A middleware
// mounted globally would be a fourth plane in front of three surfaces that do
// not want it.
//
// No Authorization header is anonymous, and anonymous is a normal caller: it
// falls through with nothing in the context, which CallerFromContext already
// reads as "not signed in". A header naming another scheme is likewise no
// bearer token (authn.ParseBearer), not a refusal — Basic belongs to dolt's
// remote flow and is not this plane's to reject.
//
// A presented token that does not resolve is a refusal and never a downgrade to
// anonymous, which is the rule the whole design rests on: an agent whose token
// expired must be told so, not quietly served the public half of the instance
// and left to conclude its databases were deleted. The classes are
// authn/bearer.go's, unchanged:
//
//	ErrMissingGrant   403 — the credential is good, the caller is known, and
//	                  what is missing is a permission. A 401 here would send
//	                  them round a loop that cannot end: a token does not grow
//	                  a grant by being presented twice.
//	ErrInvalidToken   401 + the challenge — forged, expired, revoked, or a
//	                  working token on an instance that configures no
//	                  tokens.sr.ht to verify it against.
//	anything else     503 — the credential could not be *checked*. "I could not
//	                  decide" is not "your token is bad", and answering 401 to a
//	                  restart of meta.sr.ht would tell every agent on the
//	                  instance to re-mint credentials that were never broken.
//
// The messages are written here, from what the caller already knows, and never
// from the error's own text: authn's errors name usernames, hosts and token
// ids. The cause is logged instead, on the arm where an operator needs it.
func (s *Server) resolveCaller(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		presented := authn.ParseBearer(r)
		if presented == "" {
			next.ServeHTTP(w, r)
			return
		}

		bc, err := authn.ResolveBearer(r.Context(), s.validator, presented)
		if err != nil {
			switch {
			case errors.Is(err, authn.ErrMissingGrant):
				// Asked before ErrInvalidToken: ResolveBearer joins the two, so
				// that a caller who only knows the permanent/transient split
				// still answers 401, while one that can say 403 asks for this
				// sentinel first. This surface can.
				http.Error(w, "this credential does not grant read access to "+ServerName+" databases",
					http.StatusForbidden)
			case errors.Is(err, authn.ErrInvalidToken):
				w.Header().Set("WWW-Authenticate", bearerChallenge)
				http.Error(w, "the bearer token presented was refused", http.StatusUnauthorized)
			default:
				slog.Error("a bearer credential could not be checked", scribe.Err(err))
				http.Error(w, "the credential could not be verified, try again",
					http.StatusServiceUnavailable)
			}
			return
		}

		ctx := authn.WithCaller(r.Context(), bc.AuthContext)
		ctx = withBearerCaller(ctx, bc)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

// requireReadGrant is the grant gate of docs/DESIGN.mcp.md §4.2: a tokens.sr.ht
// working token must carry core.GrantRead to reach any of this surface.
//
// It is one check at the boundary rather than one per tool because every tool
// registered here is a read, so the surface has exactly one action, and checking
// it per tool would be one chance per tool to forget the next one. A write tool
// added here must NOT rely on this: it would be admitted by a read grant, which
// is not what a read grant says. Give it its own check against a
// core.GrantWrite that does not exist yet, in its handler, where the action it
// performs is finally known.
//
// A meta PAT and an anonymous caller pass, and neither is a hole.
// BearerCaller.Authorize already encodes that: a PAT carries no tokens.sr.ht
// grants at all — the vocabularies do not overlap — and its scoping was applied
// at resolve time by the same gate the clone path applies; anonymity carries no
// credential to scope. What either may then see is core.Allowed's answer and
// not this gate's.
func requireReadGrant(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if bc := bearerCallerFrom(r.Context()); bc != nil {
			if err := bc.Authorize(core.GrantRead); err != nil {
				// 403 and not 401, for resolveCaller's reason: the credential is
				// good and the caller is known.
				//
				// No cache headers here: this runs inside privateCache, which
				// marks everything this endpoint writes.
				http.Error(w, "this token does not carry the "+core.GrantRead+" grant",
					http.StatusForbidden)
				return
			}
		}
		next.ServeHTTP(w, r)
	})
}

// privateCache marks every answer this endpoint writes as one no cache may keep,
// and states what it depends on.
//
// Setting the headers before the handler runs is not enough: the SDK's
// streamable transport sets Cache-Control itself, with Set, from inside the
// handler — so a value written on the way in is overwritten on the way out, and
// the response leaves with `no-cache, no-transform` and no Vary. They are
// therefore written at the last moment they still can be, when the status line
// is committed and every Set the handler was going to make has been made.
//
// It wraps rather than replaces what the SDK asked for: answerCacheControl keeps
// its no-transform and drops only the directive that contradicts no-store.
func privateCache(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		next.ServeHTTP(&cacheWriter{ResponseWriter: w}, r)
	})
}

// cacheWriter is the http.ResponseWriter privateCache hands down: it sets the
// two headers when the response is committed, whether that is an explicit
// WriteHeader or the implicit one of the first Write.
//
// Unwrap is what keeps the streamable transport working through it:
// http.NewResponseController follows it to reach the real writer's Flush, and an
// SSE stream that could not be flushed would be a response no client sees until
// the handler returns.
type cacheWriter struct {
	http.ResponseWriter
	committed bool
}

func (w *cacheWriter) WriteHeader(status int) {
	w.commit()
	w.ResponseWriter.WriteHeader(status)
}

func (w *cacheWriter) Write(b []byte) (int, error) {
	w.commit()
	return w.ResponseWriter.Write(b)
}

func (w *cacheWriter) commit() {
	if w.committed {
		return
	}
	w.committed = true
	w.Header().Set("Cache-Control", answerCacheControl)
	w.Header().Set("Vary", privateVary)
}

func (w *cacheWriter) Unwrap() http.ResponseWriter { return w.ResponseWriter }

// allowHosts is this endpoint's DNS-rebinding protection in the form the
// deployment needs: Host must be the instance's own hostname, or a loopback name
// for local development (an MCP client on the same machine as a dev daemon).
//
// It is a wrapper rather than a check inside ServeHTTP so that the refusal
// happens before the SDK sees a byte of the body.
func allowHosts(next http.Handler, want string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if !hostAllowed(r.Host, want) {
			http.Error(w, "unexpected Host header", http.StatusForbidden)
			return
		}
		next.ServeHTTP(w, r)
	})
}

// hostAllowed compares a request's Host against the expected hostname, ignoring
// any port and IPv6 brackets.
func hostAllowed(reqHost, want string) bool {
	h := reqHost
	if stripped, _, err := net.SplitHostPort(h); err == nil {
		h = stripped
	}
	h = strings.TrimSuffix(strings.TrimPrefix(h, "["), "]")
	switch {
	case strings.EqualFold(h, want):
		return true
	case h == "localhost", h == "127.0.0.1", h == "::1":
		return true
	default:
		return false
	}
}

// serverVersion is the implementation version reported in the MCP handshake.
//
// It is read from the build info rather than declared as a constant, because a
// constant would be a number somebody has to remember to bump and would
// therefore be wrong: the daemon has no version string of its own, and the one
// thing that does change per build is the module version the toolchain stamps
// in.
//
// A binary built with no module information — a `go test` binary is the usual
// one — reports "(devel)", the spelling the Go toolchain itself uses for an
// unstamped build. It is a display string in a handshake and nothing branches
// on it.
func serverVersion() string {
	info, ok := debug.ReadBuildInfo()
	if !ok || info.Main.Version == "" {
		return "(devel)"
	}
	return info.Main.Version
}