@johnnyboy11234/esg-idea-contest 0.3.0 → 0.3.2

package/backend/internal/idea/download.go

@@ -0,0 +1,193 @@
+package idea
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/idea/internal/store"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/db"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// Download is an opened slide file. Body yields exactly Idea.Slides.Size bytes
+// unless storage fails mid-stream; the caller must Close it.
+type Download struct {
+	Idea Idea
+	Body io.ReadCloser
+}
+
+// Download runs GET /ideas/{id}/slides (Sequence.md §6): the visibility query
+// and the SLIDES_DOWNLOAD row share one transaction, and the object is opened
+// only after that transaction has committed, so no byte is served without a
+// durable audit row (fail-closed, PRD 6.11). A missing and a hidden Idea both
+// return NOT_FOUND. An unknown commit outcome serves nothing (503), because
+// the audit row may not exist. Downloads are never state-limited.
+//
+// If storage fails after the commit, the audit row stays for a download that
+// answered 503: accepted, the intent was real (Sequence.md §6).
+func (s *Service) Download(ctx context.Context, id uuid.UUID, caller security.Principal, req Request) (Download, error) {
+	var got Idea
+	out, err := db.InTx(ctx, s.DB, func(ctx context.Context, tx *sql.Tx) error {
+		var err error
+		if got, err = store.GetVisible(ctx, tx, id, caller.UserID, caller.IsAdmin()); err != nil {
+			return err
+		}
+		return s.Audit.Record(ctx, tx, audit.Event{
+			Action: audit.SlidesDownload, Outcome: audit.Success,
+			TargetType: audit.TargetIdea, TargetID: id,
+			Method: req.Method, Route: req.Route, Status: http.StatusOK,
+			IP: req.IP, UserAgent: req.UserAgent,
+		})
+	})
+	switch {
+	case out == db.Unknown:
+		e := web.NewError(web.CodeServiceUnavailable, "The download could not be recorded; please retry.")
+		e.Cause = err
+		return Download{}, e
+	case errors.Is(err, store.ErrNotFound):
+		return Download{}, web.NewError(web.CodeNotFound, "")
+	case err != nil:
+		return Download{}, err
+	}
+
+	// Storage outages are *web.Error STORAGE_UNAVAILABLE (503); a missing
+	// object is a consistency fault and answers 500.
+	body, size, err := s.Objects.Get(ctx, got.Slides.ObjectKey)
+	if err != nil {
+		return Download{}, fmt.Errorf("open slides of idea %s: %w", id, err)
+	}
+	// Content-Length is the stored slides_size; an object of another length
+	// would make every client see a truncated or overlong body.
+	if size != got.Slides.Size {
+		_ = body.Close()
+		return Download{}, fmt.Errorf("slides of idea %s: object is %d bytes, row says %d", id, size, got.Slides.Size)
+	}
+	return Download{Idea: got, Body: body}, nil
+}
+
+// DownloadSlides serves GET /ideas/{id}/slides: 200 with the file named by the
+// current expected filename (PRD 6.6, 6.8). HEAD never reaches this handler
+// (explicit 405 route, D47/D59).
+func (h Handler) DownloadSlides(w http.ResponseWriter, r *http.Request, id api.IdeaId) {
+	p, ok := security.PrincipalFrom(r.Context())
+	if !ok {
+		h.Fail(w, r, web.NewError(web.CodeUnauthenticated, "authentication required"))
+		return
+	}
+	d, err := h.Service.Download(r.Context(), uuid.UUID(id), p,
+		Request{Method: r.Method, Route: web.RoutePattern(r), UserAgent: r.UserAgent(), IP: web.ClientIP(r)})
+	if err != nil {
+		var e *web.Error
+		switch {
+		case errors.As(err, &e) && e.Code == web.CodeNotFound:
+			e.AuditAction = string(audit.SlidesDownload)
+			e.AuditReason = auditReasonHidden
+			e.AuditTargetType = string(audit.TargetIdea)
+			e.AuditTargetID = uuid.UUID(id)
+		case e == nil:
+			h.log().ErrorContext(r.Context(), "slides download failed", "ideaId", uuid.UUID(id).String(), "error", err)
+		}
+		h.Fail(w, r, err)
+		return
+	}
+	defer func() { _ = d.Body.Close() }()
+
+	i := d.Idea
+	base, err := h.ExpectedFilename(i.Category, i.Org, i.LeaderName, i.LeaderEmpNo, i.Name)
+	if err != nil {
+		h.Fail(w, r, err)
+		return
+	}
+	hd := w.Header()
+	hd.Set("Content-Type", contentTypes[i.Slides.Ext])
+	hd.Set("Content-Length", strconv.FormatInt(i.Slides.Size, 10))
+	hd.Set("Content-Disposition", ContentDisposition(base+"."+i.Slides.Ext))
+	hd.Set("Cache-Control", "no-store")
+	hd.Set("X-Content-Type-Options", "nosniff")
+	w.WriteHeader(http.StatusOK)
+
+	src := &readErrRecorder{r: d.Body}
+	n, err := io.CopyN(w, src, i.Slides.Size)
+	if err == nil {
+		return
+	}
+	if src.err != nil || errors.Is(err, io.EOF) {
+		// Headers are out, so no error body can follow. Abort the connection
+		// (HTTP/1.1 close, HTTP/2 RST_STREAM): with Content-Length set the
+		// client sees an incomplete body instead of a silently short file.
+		h.log().ErrorContext(r.Context(), "slides download aborted: storage failed mid-stream",
+			"ideaId", i.ID.String(), "sent", n, "size", i.Slides.Size, "error", err)
+		panic(http.ErrAbortHandler)
+	}
+	// The client went away; nothing left to tell it.
+	h.log().InfoContext(r.Context(), "slides download interrupted by client",
+		"ideaId", i.ID.String(), "sent", n, "size", i.Slides.Size, "error", err)
+}
+
+func (h Handler) log() *slog.Logger {
+	if h.Log == nil {
+		return slog.New(slog.DiscardHandler)
+	}
+	return h.Log
+}
+
+// readErrRecorder remembers the source's first non-EOF error, so a failed copy
+// can be blamed on storage (abort) or on the client (just stop).
+type readErrRecorder struct {
+	r   io.Reader
+	err error
+}
+
+func (x *readErrRecorder) Read(p []byte) (int, error) {
+	n, err := x.r.Read(p)
+	if err != nil && !errors.Is(err, io.EOF) && x.err == nil {
+		x.err = err
+	}
+	return n, err
+}
+
+// ContentDisposition is the RFC 6266 attachment header for name: an ASCII
+// fallback filename (non-ASCII, quotes, backslashes and controls become "_")
+// and the exact UTF-8 name as filename* (RFC 8187 percent-encoding).
+func ContentDisposition(name string) string {
+	var fallback, ext strings.Builder
+	for _, r := range name {
+		if r < 0x20 || r > 0x7e || r == '"' || r == '\\' {
+			fallback.WriteByte('_')
+		} else {
+			fallback.WriteRune(r)
+		}
+	}
+	const hex = "0123456789ABCDEF"
+	for _, b := range []byte(name) {
+		if isAttrChar(b) {
+			ext.WriteByte(b)
+		} else {
+			ext.WriteByte('%')
+			ext.WriteByte(hex[b>>4])
+			ext.WriteByte(hex[b&0x0f])
+		}
+	}
+	return `attachment; filename="` + fallback.String() + `"; filename*=UTF-8''` + ext.String()
+}
+
+// isAttrChar is RFC 8187 attr-char: ALPHA / DIGIT / "!#$&+-.^_`|~".
+func isAttrChar(b byte) bool {
+	switch {
+	case b >= 'a' && b <= 'z', b >= 'A' && b <= 'Z', b >= '0' && b <= '9':
+		return true
+	}
+	return strings.IndexByte("!#$&+-.^_`|~", b) >= 0
+}

package/backend/internal/idea/download_integration_test.go

@@ -0,0 +1,311 @@
+//go:build integration
+
+package idea_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/idea"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/dbtest"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// created posts a valid create as p and returns the new Idea's ID and the key
+// of its stored object.
+func (e *createEnv) created(t *testing.T, p security.Principal, name string) (uuid.UUID, string) {
+	t.Helper()
+	return e.createdWith(t, p, validForm(name))
+}
+
+func (e *createEnv) createdWith(t *testing.T, p security.Principal, f form) (uuid.UUID, string) {
+	t.Helper()
+	rec := e.post(t, p, f)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("create: %d %s", rec.Code, rec.Body)
+	}
+	var b struct{ ID uuid.UUID }
+	if err := json.Unmarshal(rec.Body.Bytes(), &b); err != nil {
+		t.Fatal(err)
+	}
+	return b.ID, e.objects.last
+}
+
+func (e *createEnv) downloadRouter() http.Handler {
+	r := chi.NewRouter()
+	r.Get("/ideas/{id}/slides", func(w http.ResponseWriter, req *http.Request) {
+		id, err := uuid.Parse(chi.URLParam(req, "id"))
+		if err != nil {
+			panic(err)
+		}
+		e.h.DownloadSlides(w, req, api.IdeaId(id))
+	})
+	return r
+}
+
+func (e *createEnv) download(t *testing.T, p security.Principal, id uuid.UUID) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, "/ideas/"+id.String()+"/slides", nil)
+	req = req.WithContext(security.WithPrincipal(context.Background(), p))
+	rec := httptest.NewRecorder()
+	e.downloadRouter().ServeHTTP(rec, req)
+	return rec
+}
+
+func (e *createEnv) gets() int {
+	e.objects.mu.Lock()
+	defer e.objects.mu.Unlock()
+	return e.objects.gets
+}
+
+func TestDownloadSlides(t *testing.T) {
+	e := newCreateEnv(t)
+	leader := addUser(t, e.db, "100001", "USER")
+	other := addUser(t, e.db, "100002", "USER")
+	admin := addUser(t, e.db, "900001", "ADMIN")
+	id, key := e.created(t, leader, "Idea A")
+	successRows := func() int {
+		return e.count(t, `SELECT COUNT(*) FROM audit_log WHERE action = 'SLIDES_DOWNLOAD' AND outcome = 'SUCCESS'`)
+	}
+
+	// The audit row is committed (visible to another connection) before the
+	// object is even opened, so before the first byte.
+	rowsAtOpen := -1
+	e.objects.onGet = func() { rowsAtOpen = successRows() }
+
+	rec := e.download(t, leader, id)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("leader: %d %s", rec.Code, rec.Body)
+	}
+	if rowsAtOpen != 1 {
+		t.Errorf("SLIDES_DOWNLOAD rows when the object was opened = %d, want 1", rowsAtOpen)
+	}
+	if !bytes.Equal(rec.Body.Bytes(), e.objects.puts[key]) {
+		t.Error("body differs from the stored object")
+	}
+	want := map[string]string{
+		"Content-Type":           "application/pdf",
+		"Content-Length":         strconv.Itoa(len(e.objects.puts[key])),
+		"Content-Disposition":    idea.ContentDisposition("I_BSID_User 100001_100001_Idea A.pdf"),
+		"Cache-Control":          "no-store",
+		"X-Content-Type-Options": "nosniff",
+	}
+	for k, v := range want {
+		if got := rec.Header().Get(k); got != v {
+			t.Errorf("%s = %q, want %q", k, got, v)
+		}
+	}
+	if rec.Header().Get("Accept-Ranges") != "" {
+		t.Error("Range must not be advertised")
+	}
+	if n := e.count(t, `SELECT COUNT(*) FROM audit_log WHERE action = 'SLIDES_DOWNLOAD' AND outcome = 'SUCCESS'
+	        AND actor_role = 'USER' AND actor_emp_no = '100001' AND target_type = 'IDEA' AND target_id = ?
+	        AND method = 'GET' AND route = '/ideas/{id}/slides' AND status = 200`, id.String()); n != 1 {
+		t.Errorf("leader SUCCESS row with full fields = %d, want 1", n)
+	}
+
+	// Admin: 200 and a second SUCCESS row.
+	if rec := e.download(t, admin, id); rec.Code != http.StatusOK {
+		t.Fatalf("admin: %d %s", rec.Code, rec.Body)
+	}
+	if n := e.count(t, `SELECT COUNT(*) FROM audit_log WHERE action = 'SLIDES_DOWNLOAD' AND outcome = 'SUCCESS' AND actor_role = 'ADMIN'`); n != 1 {
+		t.Errorf("admin SUCCESS rows = %d, want 1", n)
+	}
+
+	// Hidden and missing: identical 404 (bar the request ID), both DENIED, and
+	// storage is never touched.
+	before := e.gets()
+	hidden, missing := e.download(t, other, id), e.download(t, other, uuid.New())
+	if hidden.Code != 404 || missing.Code != 404 {
+		t.Fatalf("codes %d %d", hidden.Code, missing.Code)
+	}
+	strip := func(rr *httptest.ResponseRecorder) map[string]any {
+		var m map[string]any
+		_ = json.Unmarshal(rr.Body.Bytes(), &m)
+		delete(m, "requestId")
+		return m
+	}
+	hb, mb := strip(hidden), strip(missing)
+	if len(hb) != len(mb) || hb["code"] != "NOT_FOUND" || hb["code"] != mb["code"] || hb["detail"] != mb["detail"] {
+		t.Errorf("bodies differ: %v vs %v", hb, mb)
+	}
+	for k := range hidden.Header() {
+		if hidden.Header().Get(k) != missing.Header().Get(k) {
+			t.Errorf("header %s differs", k)
+		}
+	}
+	if e.gets() != before {
+		t.Error("a 404 must not open the object")
+	}
+	if n := e.count(t, `SELECT COUNT(*) FROM audit_log WHERE action = 'SLIDES_DOWNLOAD' AND outcome = 'DENIED'
+	        AND status = 404 AND error_code = 'NOT_FOUND'`); n != 2 {
+		t.Errorf("DENIED rows = %d, want 2", n)
+	}
+	if successRows() != 2 {
+		t.Errorf("SUCCESS rows = %d, want 2", successRows())
+	}
+
+	// Not state-limited, and the name is the *current* expected filename.
+	e.setDeadline(t, "NOW(6) - INTERVAL 1 DAY")
+	if _, err := e.db.Exec(`UPDATE idea SET name = 'Renamed' WHERE id = ?`, id.String()); err != nil {
+		t.Fatal(err)
+	}
+	rec = e.download(t, leader, id)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("after deadline: %d %s", rec.Code, rec.Body)
+	}
+	if got, want := rec.Header().Get("Content-Disposition"), idea.ContentDisposition("I_BSID_User 100001_100001_Renamed.pdf"); got != want {
+		t.Errorf("Content-Disposition = %q, want %q", got, want)
+	}
+}
+
+// A non-ASCII Idea name is served exactly through filename*.
+func TestDownloadSlidesUnicodeFilename(t *testing.T) {
+	e := newCreateEnv(t)
+	leader := addUser(t, e.db, "100001", "USER")
+	id, _ := e.created(t, leader, "減碳 Idea")
+	rec := e.download(t, leader, id)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("%d %s", rec.Code, rec.Body)
+	}
+	want := `attachment; filename="I_BSID_User 100001_100001___ Idea.pdf"; ` +
+		`filename*=UTF-8''I_BSID_User%20100001_100001_%E6%B8%9B%E7%A2%B3%20Idea.pdf`
+	if got := rec.Header().Get("Content-Disposition"); got != want {
+		t.Errorf("Content-Disposition = %q, want %q", got, want)
+	}
+}
+
+// Failures before the first byte answer a problem; the audit row stays
+// (Sequence.md §6: the intent to download was real).
+func TestDownloadSlidesFailsBeforeFirstByte(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		breakIt func(e *createEnv, id uuid.UUID, key string)
+		status  int
+		code    string
+	}{
+		{"MinIO down", func(e *createEnv, _ uuid.UUID, _ string) {
+			e.objects.getErr = web.NewError(web.CodeStorageUnavailable, "object storage is unavailable")
+		}, 503, "STORAGE_UNAVAILABLE"},
+		{"object missing", func(e *createEnv, _ uuid.UUID, key string) {
+			delete(e.objects.puts, key)
+		}, 500, "INTERNAL_ERROR"},
+		{"object length differs from the row", func(e *createEnv, id uuid.UUID, _ string) {
+			if _, err := e.db.Exec(`UPDATE idea SET slides_size = slides_size + 1 WHERE id = ?`, id.String()); err != nil {
+				panic(err)
+			}
+		}, 500, "INTERNAL_ERROR"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			e := newCreateEnv(t)
+			leader := addUser(t, e.db, "100001", "USER")
+			id, key := e.created(t, leader, "Idea A")
+			tc.breakIt(e, id, key)
+			rec := e.download(t, leader, id)
+			if rec.Code != tc.status || decodeProblem(t, rec).Code != tc.code {
+				t.Fatalf("%d %s, want %d %s", rec.Code, rec.Body, tc.status, tc.code)
+			}
+			if ct := rec.Header().Get("Content-Type"); ct != web.ProblemContentType {
+				t.Errorf("Content-Type = %q", ct)
+			}
+			if n := e.count(t, `SELECT COUNT(*) FROM audit_log WHERE action = 'SLIDES_DOWNLOAD' AND outcome = 'SUCCESS'`); n != 1 {
+				t.Errorf("SUCCESS rows = %d, want 1", n)
+			}
+		})
+	}
+}
+
+// A storage failure mid-stream aborts the connection, so the client never
+// takes a short body for the whole file. Past net/http's write buffer the 200
+// and its Content-Length are already out and the body ends early; before it,
+// the client gets no response at all.
+func TestDownloadSlidesAbortsMidStream(t *testing.T) {
+	const size = 64 << 10
+	for _, tc := range []struct {
+		name      string
+		failAfter int64
+		headers   bool // the 200 reached the client
+	}{
+		{"after the headers were sent", 32 << 10, true},
+		{"within the write buffer", 10, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			e := newCreateEnv(t)
+			leader := addUser(t, e.db, "100001", "USER")
+			f := validForm("Idea A")
+			f.file = pdf(size)
+			id, key := e.createdWith(t, leader, f)
+			total := int64(len(e.objects.puts[key]))
+			e.objects.failAfter = tc.failAfter
+			e.objects.streamErr = errors.New("minio: connection reset")
+
+			inner := e.downloadRouter()
+			srv := httptest.NewServer(web.Recover(slog.New(slog.DiscardHandler))(
+				http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					inner.ServeHTTP(w, r.WithContext(security.WithPrincipal(r.Context(), leader)))
+				})))
+			t.Cleanup(srv.Close)
+
+			resp, err := http.Get(srv.URL + "/ideas/" + id.String() + "/slides")
+			if !tc.headers {
+				if err == nil {
+					_ = resp.Body.Close()
+					t.Fatalf("got a response (%d); want the connection aborted", resp.StatusCode)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer func() { _ = resp.Body.Close() }()
+			if resp.StatusCode != 200 || resp.ContentLength != total {
+				t.Fatalf("status %d, length %d, want 200 %d", resp.StatusCode, resp.ContentLength, total)
+			}
+			b, err := io.ReadAll(resp.Body)
+			if !errors.Is(err, io.ErrUnexpectedEOF) {
+				t.Errorf("read error = %v, want unexpected EOF", err)
+			}
+			if int64(len(b)) >= total {
+				t.Errorf("read %d of %d bytes; want a short body", len(b), total)
+			}
+		})
+	}
+}
+
+// An unknown commit outcome serves nothing: the audit row may not exist.
+func TestDownloadSlidesUnknownOutcome(t *testing.T) {
+	dsn := dbtest.Start(t)
+	d := dbtest.Open(t, dsn)
+	faulty, faults := dbtest.OpenFaulty(t, dsn)
+	e := newCreateEnvOn(t, d, faulty)
+	leader := addUser(t, d, "100001", "USER")
+	id, _ := e.created(t, leader, "Idea A")
+
+	for _, fault := range []dbtest.CommitFault{dbtest.LostAckCommitted, dbtest.LostAckNotCommitted} {
+		before := e.gets()
+		faults.FailNextCommit(fault)
+		rec := e.download(t, leader, id)
+		if rec.Code != 503 || decodeProblem(t, rec).Code != "SERVICE_UNAVAILABLE" {
+			t.Fatalf("fault %v: %d %s", fault, rec.Code, rec.Body)
+		}
+		if e.gets() != before {
+			t.Errorf("fault %v: the object must not be opened", fault)
+		}
+	}
+	if faults.Fired() != 2 {
+		t.Errorf("faults fired = %d, want 2", faults.Fired())
+	}
+}

package/backend/internal/idea/download_test.go

@@ -0,0 +1,25 @@
+package idea_test
+
+import (
+	"mime"
+	"testing"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/idea"
+)
+
+func TestContentDisposition(t *testing.T) {
+	for _, tc := range []struct{ name, want string }{
+		{"I_BSID_Amy_100001_Plan.pdf", `attachment; filename="I_BSID_Amy_100001_Plan.pdf"; filename*=UTF-8''I_BSID_Amy_100001_Plan.pdf`},
+		{"O_AAID_王小明_100002_減碳.pptx", `attachment; filename="O_AAID_____100002___.pptx"; filename*=UTF-8''O_AAID_%E7%8E%8B%E5%B0%8F%E6%98%8E_100002_%E6%B8%9B%E7%A2%B3.pptx`},
+		{`a "b"\c;d%e.pdf`, `attachment; filename="a _b__c;d%e.pdf"; filename*=UTF-8''a%20%22b%22%5Cc%3Bd%25e.pdf`},
+	} {
+		got := idea.ContentDisposition(tc.name)
+		if got != tc.want {
+			t.Errorf("%q:\n got %s\nwant %s", tc.name, got, tc.want)
+		}
+		// Go's own RFC 2231/8187 parser recovers the exact name from filename*.
+		if _, params, err := mime.ParseMediaType(got); err != nil || params["filename"] != tc.name {
+			t.Errorf("%q: parsed %q, %v", tc.name, params["filename"], err)
+		}
+	}
+}

package/backend/internal/idea/handler.go

@@ -0,0 +1,151 @@
+package idea
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/idea/internal/store"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/db"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// auditReasonHidden is the one reason stored for a missing and a hidden Idea
+// alike: the log must not tell them apart either (PRD 6.6).
+const auditReasonHidden = "NOT_FOUND"
+
+// View returns the Idea for GET /ideas/{id}. An Admin's successful view writes
+// IDEA_VIEW in the same transaction as the read (fail-closed, PRD 6.11).
+func (s *Service) View(ctx context.Context, id uuid.UUID, caller security.Principal) (Idea, error) {
+	if !caller.IsAdmin() {
+		return s.Get(ctx, id, caller)
+	}
+	var got Idea
+	_, err := db.InTx(ctx, s.DB, func(ctx context.Context, tx *sql.Tx) error {
+		var err error
+		if got, err = store.GetVisible(ctx, tx, id, caller.UserID, true); err != nil {
+			return err
+		}
+		return s.Audit.Record(ctx, tx, audit.Event{
+			Action: audit.IdeaView, Outcome: audit.Success,
+			TargetType: audit.TargetIdea, TargetID: id,
+		})
+	})
+	if errors.Is(err, store.ErrNotFound) {
+		return Idea{}, web.NewError(web.CodeNotFound, "")
+	}
+	return got, err
+}
+
+// Handler serves the Idea endpoints.
+type Handler struct {
+	Service *Service
+	// ExpectedFilename builds the expected slide filename without extension
+	// (storage.ExpectedFilenameBase; injected because idea must not import
+	// storage, D29).
+	ExpectedFilename func(category, org, leaderName, leaderEmpNo, ideaName string) (string, error)
+	Fail             func(w http.ResponseWriter, r *http.Request, err error)
+	// Log receives download failures the response cannot carry (nil = discard).
+	Log *slog.Logger
+}
+
+type person struct {
+	EmpNo string `json:"empNo"`
+	Name  string `json:"name"`
+}
+
+type member struct {
+	EmpNo    string `json:"empNo"`
+	Name     string `json:"name"`
+	JoinedAt string `json:"joinedAt"`
+}
+
+type pending struct {
+	EmpNo       string `json:"empNo"`
+	Name        string `json:"name"`
+	RequestedAt string `json:"requestedAt"`
+}
+
+type slides struct {
+	Ext              string `json:"ext"`
+	Size             int64  `json:"size"`
+	SHA256           string `json:"sha256"`
+	UpdatedAt        string `json:"updatedAt"`
+	DownloadFilename string `json:"downloadFilename"`
+}
+
+// detail is IdeaDetail (docs/API/response-bodies.md). It is local so that
+// timestamps use web.FormatTime (fixed milliseconds) instead of time.Time.
+type detail struct {
+	ID                   uuid.UUID  `json:"id"`
+	Category             string     `json:"category"`
+	Org                  string     `json:"org"`
+	Direction            string     `json:"direction"`
+	Name                 string     `json:"name"`
+	Summary              string     `json:"summary"`
+	Leader               person     `json:"leader"`
+	Members              []member   `json:"members"`
+	PendingRequests      *[]pending `json:"pendingRequests"`
+	Slides               slides     `json:"slides"`
+	ExpectedFilenameBase string     `json:"expectedFilenameBase"`
+	CreatedAt            string     `json:"createdAt"`
+	UpdatedAt            string     `json:"updatedAt"`
+	Version              int64      `json:"version"`
+}
+
+// GetIdea serves GET /ideas/{id}.
+func (h Handler) GetIdea(w http.ResponseWriter, r *http.Request, id api.IdeaId) {
+	p, ok := security.PrincipalFrom(r.Context())
+	if !ok {
+		h.Fail(w, r, web.NewError(web.CodeUnauthenticated, "authentication required"))
+		return
+	}
+	got, err := h.Service.View(r.Context(), uuid.UUID(id), p)
+	if err != nil {
+		var e *web.Error
+		if errors.As(err, &e) && e.Code == web.CodeNotFound {
+			e.AuditAction = string(audit.IdeaView)
+			e.AuditReason = auditReasonHidden
+			e.AuditTargetType = string(audit.TargetIdea)
+			e.AuditTargetID = uuid.UUID(id)
+		}
+		h.Fail(w, r, err)
+		return
+	}
+	body, err := h.toDetail(got, p)
+	if err != nil {
+		h.Fail(w, r, err)
+		return
+	}
+	web.WriteJSON(w, http.StatusOK, body)
+}
+
+func (h Handler) toDetail(i Idea, caller security.Principal) (detail, error) {
+	base, err := h.ExpectedFilename(i.Category, i.Org, i.LeaderName, i.LeaderEmpNo, i.Name)
+	if err != nil {
+		return detail{}, err
+	}
+	d := detail{
+		ID: i.ID, Category: i.Category, Org: i.Org, Direction: i.Direction, Name: i.Name, Summary: i.Summary,
+		Leader: person{EmpNo: i.LeaderEmpNo, Name: i.LeaderName},
+		// TODO(B5-01): approved Members and pending requests come from idea_member.
+		Members: []member{},
+		Slides: slides{Ext: i.Slides.Ext, Size: i.Slides.Size, SHA256: i.Slides.SHA256,
+			UpdatedAt: web.FormatTime(i.SlidesUpdatedAt), DownloadFilename: base + "." + i.Slides.Ext},
+		ExpectedFilenameBase: base,
+		CreatedAt:            web.FormatTime(i.CreatedAt),
+		UpdatedAt:            web.FormatTime(i.UpdatedAt),
+		Version:              int64(i.Version),
+	}
+	if caller.IsAdmin() || caller.UserID == i.LeaderID {
+		d.PendingRequests = &[]pending{}
+	}
+	return d, nil
+}