Method handleAttachmentDownload

internal/httpapi/attachments.go:217–293

handleAttachmentDownload streams one attachment's bytes. It is a RAW chi route (not Huma, not bearer): the capability TOKEN authorizes the download, so the URL can be handed to a sandboxed tool without leaking the agent's credential — the same model as the HITL magic-link. The token binds message+in

(w http.ResponseWriter, r *http.Request)

// keyed by agent id), so a valid token can only stream the exact attachment it
// was minted for.
func (s *Server) handleAttachmentDownload(w http.ResponseWriter, r *http.Request) {
	// Per-IP rate limit FIRST. This raw capability-token route sits OUTSIDE the
	// Huma rate-limit middleware, and each accepted hit runs GetAgent +
	// GetMessage + a full MIME re-parse — so throttle before any of that work to
	// bound token-replay and index/message probing. Keyed by client IP (no bearer
	// here); shares the per-IP convention of the registration/feedback limiters.
	if s.deps.DownloadLimit != nil {
		ok, retryAfter, limit, remaining, reset := s.deps.DownloadLimit(clientIP(r))
		w.Header().Set("RateLimit-Limit", strconv.Itoa(limit))
		w.Header().Set("RateLimit-Remaining", strconv.Itoa(remaining))
		w.Header().Set("RateLimit-Reset", strconv.Itoa(reset))
		if !ok {
			secs := int(retryAfter.Round(time.Second).Seconds())
			if secs < 1 {
				secs = 1
			}
			w.Header().Set("Retry-After", strconv.Itoa(secs))
			writeRawError(w, r, http.StatusTooManyRequests, "rate_limited", "rate limit exceeded",
				map[string]any{"retry_after_seconds": secs})
			return
		}
	}

	email := identity.NormalizeEmail(chi.URLParam(r, "email"))
	id := chi.URLParam(r, "id")
	index, err := strconv.Atoi(chi.URLParam(r, "index"))
	if err != nil || index < 0 {
		http.Error(w, "invalid attachment index", http.StatusBadRequest)
		return
	}
	token := r.URL.Query().Get("token")
	if token == "" {
		http.Error(w, "token query parameter required", http.StatusUnauthorized)
		return
	}
	if s.deps.AttachmentStore == nil || s.deps.GetAgent == nil || s.deps.GetMessage == nil {
		http.Error(w, "attachment download unavailable", http.StatusInternalServerError)
		return
	}
	// Capability check: the token must authorize exactly this message+index.
	if !s.deps.AttachmentStore.VerifyDownload(token, id, index) {
		http.Error(w, "invalid or expired download token", http.StatusForbidden)
		return
	}
	// Bind the message to the path agent (GetMessage is keyed by agent id), so a
	// token can't be replayed against a path naming a different agent.
	ag, err := s.deps.GetAgent(r.Context(), email)
	if err != nil || ag == nil {
		http.Error(w, "agent not found", http.StatusNotFound)
		return
	}
	msg, err := s.deps.GetMessage(r.Context(), id, ag.ID)
	if err != nil || msg == nil {
		http.Error(w, "message not found", http.StatusNotFound)
		return
	}
	att, ok := mailparse.AttachmentAt(msg.RawMessage, index)
	if !ok {