@johnnyboy11234/esg-idea-contest 0.2.4 → 0.3.1

package/backend/internal/shared/job/job.go

@@ -0,0 +1,54 @@
+// Package job runs background work on a fixed period with random jitter
+// (Backend.md §9). Every replica runs its own loop; the work itself must be
+// idempotent and safe to run concurrently on several replicas, because no
+// leader is elected.
+package job
+
+import (
+	"context"
+	"log/slog"
+	"math/rand/v2"
+	"time"
+)
+
+// Spec describes one periodic job.
+type Spec struct {
+	Name     string        // log attribute "job"
+	Interval time.Duration // base period between two runs
+	Jitter   time.Duration // each wait adds a random [0, Jitter), so replicas drift apart
+}
+
+// Run calls fn once per Interval plus jitter until ctx is cancelled, then
+// returns. The first call also waits a random [0, Jitter), so replicas started
+// together do not run in step. A failing run is logged and the loop goes on;
+// a run in progress sees ctx cancelled and should return promptly.
+func Run(ctx context.Context, log *slog.Logger, s Spec, fn func(context.Context) error) {
+	run(ctx, log, s, fn, rand.Int64N)
+}
+
+// run is Run with the random source injected for tests.
+func run(ctx context.Context, log *slog.Logger, s Spec, fn func(context.Context) error, randN func(int64) int64) {
+	log = log.With("job", s.Name)
+	t := time.NewTimer(jitter(s.Jitter, randN))
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			log.Debug("job stopped")
+			return
+		case <-t.C:
+		}
+		if err := fn(ctx); err != nil && ctx.Err() == nil {
+			log.Warn("job run failed", "error", err.Error())
+		}
+		t.Reset(s.Interval + jitter(s.Jitter, randN))
+	}
+}
+
+// jitter returns a random duration in [0, upTo), or 0 when upTo <= 0.
+func jitter(upTo time.Duration, randN func(int64) int64) time.Duration {
+	if upTo <= 0 {
+		return 0
+	}
+	return time.Duration(randN(int64(upTo)))
+}

package/backend/internal/shared/job/job_test.go

@@ -0,0 +1,105 @@
+package job
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"log/slog"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func noRand(int64) int64 { return 0 }
+
+func logger(buf *bytes.Buffer) *slog.Logger {
+	return slog.New(slog.NewTextHandler(buf, &slog.HandlerOptions{Level: slog.LevelDebug}))
+}
+
+type syncBuf struct {
+	mu sync.Mutex
+	b  bytes.Buffer
+}
+
+func (s *syncBuf) Write(p []byte) (int, error) { s.mu.Lock(); defer s.mu.Unlock(); return s.b.Write(p) }
+func (s *syncBuf) String() string              { s.mu.Lock(); defer s.mu.Unlock(); return s.b.String() }
+
+func TestRunRepeatsUntilCancelled(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	var calls atomic.Int32
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		run(ctx, slog.New(slog.DiscardHandler), Spec{Name: "t", Interval: time.Millisecond}, func(context.Context) error {
+			if calls.Add(1) == 3 {
+				cancel()
+			}
+			return nil
+		}, noRand)
+	}()
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Run did not return after cancel")
+	}
+	if n := calls.Load(); n != 3 {
+		t.Errorf("calls = %d, want 3 (no run after cancel)", n)
+	}
+}
+
+func TestRunLogsFailureAndContinues(t *testing.T) {
+	buf := &syncBuf{}
+	ctx, cancel := context.WithCancel(context.Background())
+	var calls atomic.Int32
+	run(ctx, slog.New(slog.NewTextHandler(buf, nil)), Spec{Name: "purge", Interval: time.Millisecond}, func(context.Context) error {
+		if calls.Add(1) == 2 {
+			cancel()
+		}
+		return errors.New("boom")
+	}, noRand)
+	out := buf.String()
+	// The first failure is logged; the second, returned after cancel, is not.
+	if strings.Count(out, "job run failed") != 1 || !strings.Contains(out, "job=purge") || !strings.Contains(out, "error=boom") {
+		t.Errorf("log = %q", out)
+	}
+}
+
+func TestRunFirstCallWaitsForJitter(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+	defer cancel()
+	var buf bytes.Buffer
+	called := false
+	run(ctx, logger(&buf), Spec{Name: "t", Interval: time.Millisecond, Jitter: time.Hour}, func(context.Context) error {
+		called = true
+		return nil
+	}, func(n int64) int64 { return n - 1 })
+	if called {
+		t.Error("first run must wait for its jitter")
+	}
+	if !strings.Contains(buf.String(), "job stopped") {
+		t.Errorf("log = %q", buf.String())
+	}
+}
+
+func TestJitter(t *testing.T) {
+	var asked int64
+	got := jitter(time.Minute, func(n int64) int64 { asked = n; return n / 2 })
+	if asked != int64(time.Minute) || got != 30*time.Second {
+		t.Errorf("jitter = %v (asked %d)", got, asked)
+	}
+	for _, d := range []time.Duration{0, -time.Second} {
+		if got := jitter(d, func(int64) int64 { panic("must not be called") }); got != 0 {
+			t.Errorf("jitter(%v) = %v", d, got)
+		}
+	}
+}
+
+func TestRunUsesRealRandom(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	Run(ctx, slog.New(slog.DiscardHandler), Spec{Name: "t", Interval: time.Hour, Jitter: time.Nanosecond}, func(context.Context) error {
+		cancel()
+		return nil
+	})
+}

package/backend/internal/shared/web/multipart.go

@@ -0,0 +1,175 @@
+package web
+
+import (
+	"crypto/sha256"
+	"errors"
+	"io"
+	"mime"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"unicode/utf8"
+)
+
+// maxTextPartBytes caps one text part. Text fields are short (PRD §6.6); a
+// larger one is malformed, not an excuse to buffer.
+const maxTextPartBytes = 64 << 10
+
+// MultipartSpec describes the one multipart shape a route accepts.
+type MultipartSpec struct {
+	// FileField is the single file part; it is required and may appear once.
+	FileField string
+	// TextFields are required text parts, each exactly once. Other parts are
+	// drained and ignored.
+	TextFields []string
+	// TooLarge is the code answered when the body limit trips (FILE_TOO_LARGE
+	// on slide routes).
+	TooLarge ErrorCode
+	// TempDir is where the file is spooled; empty means os.TempDir() (the
+	// pod's /tmp emptyDir).
+	TempDir string
+}
+
+// SpooledFile is the file part written to a temporary file. Its size and
+// SHA-256 were computed while streaming.
+type SpooledFile struct {
+	Filename string // as sent, UTF-8, path components not stripped (PRD §6.8)
+	Size     int64
+	SHA256   [sha256.Size]byte
+	f        *os.File
+}
+
+// ReaderAt gives random access for the validator (ZIP central directory).
+func (s *SpooledFile) ReaderAt() io.ReaderAt { return s.f }
+
+// Open returns a fresh reader positioned at the start, for the upload.
+func (s *SpooledFile) Open() io.Reader { return io.NewSectionReader(s.f, 0, s.Size) }
+
+// Form is a spooled multipart request. The caller must Close it (defer), which
+// removes the temporary file whether the request succeeded or failed.
+type Form struct {
+	Fields map[string]string
+	File   *SpooledFile
+}
+
+// Close removes the temporary file. Safe on a nil Form and when called twice.
+func (m *Form) Close() error {
+	if m == nil || m.File == nil || m.File.f == nil {
+		return nil
+	}
+	f := m.File.f
+	m.File.f = nil
+	err := f.Close()
+	if rerr := os.Remove(f.Name()); rerr != nil && !errors.Is(rerr, os.ErrNotExist) {
+		err = errors.Join(err, rerr)
+	}
+	return err
+}
+
+// ReadMultipart streams the body with r.MultipartReader (never
+// ParseMultipartForm, which buffers in memory and creates temp files we do
+// not control). The file part is copied into a temp file through
+// io.MultiWriter(file, sha256). A non-multipart body, a missing or repeated
+// part, or a file part without a filename is 400 MALFORMED_REQUEST; the body
+// limit is spec.TooLarge. On any error nothing is left on disk.
+func ReadMultipart(r *http.Request, spec MultipartSpec) (*Form, error) {
+	mr, err := r.MultipartReader()
+	if err != nil {
+		return nil, malformed("request is not valid multipart/form-data", err)
+	}
+	form := &Form{Fields: make(map[string]string, len(spec.TextFields))}
+	ok := false
+	defer func() {
+		if !ok {
+			_ = form.Close()
+		}
+	}()
+	wanted := make(map[string]bool, len(spec.TextFields))
+	for _, n := range spec.TextFields {
+		wanted[n] = true
+	}
+	for {
+		part, err := mr.NextPart()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return nil, spec.readErr(err, "unreadable multipart body")
+		}
+		name := part.FormName()
+		switch {
+		case name == spec.FileField:
+			if form.File != nil {
+				return nil, malformed("repeated part: "+name, nil)
+			}
+			form.File, err = spec.spool(part, spec.TempDir)
+			if err != nil {
+				return nil, err
+			}
+		case wanted[name]:
+			if _, dup := form.Fields[name]; dup {
+				return nil, malformed("repeated part: "+name, nil)
+			}
+			b, err := io.ReadAll(io.LimitReader(part, maxTextPartBytes+1))
+			if err != nil {
+				return nil, spec.readErr(err, "unreadable multipart body")
+			}
+			if len(b) > maxTextPartBytes || !utf8.Valid(b) {
+				return nil, malformed("invalid part: "+name, nil)
+			}
+			form.Fields[name] = string(b)
+		default:
+			if _, err := io.Copy(io.Discard, part); err != nil {
+				return nil, spec.readErr(err, "unreadable multipart body")
+			}
+		}
+	}
+	if form.File == nil {
+		return nil, malformed("missing part: "+spec.FileField, nil)
+	}
+	for _, n := range spec.TextFields {
+		if _, have := form.Fields[n]; !have {
+			return nil, malformed("missing part: "+n, nil)
+		}
+	}
+	ok = true
+	return form, nil
+}
+
+func (s MultipartSpec) readErr(err error, detail string) error {
+	if IsBodyTooLarge(err) {
+		return NewError(s.TooLarge, "Request body too large.")
+	}
+	return malformed(detail, err)
+}
+
+func (s MultipartSpec) spool(part *multipart.Part, dir string) (*SpooledFile, error) {
+	// Part.FileName() applies filepath.Base; the filename must be taken as sent.
+	_, params, err := mime.ParseMediaType(part.Header.Get("Content-Disposition"))
+	name, has := params["filename"]
+	if err != nil || !has || !utf8.ValidString(name) {
+		return nil, malformed("part "+s.FileField+" needs a UTF-8 filename", err)
+	}
+	f, err := os.CreateTemp(dir, "upload-*")
+	if err != nil {
+		return nil, err // plain error: mapped to 500 by the pipeline
+	}
+	out := &SpooledFile{Filename: name, f: f}
+	h := sha256.New()
+	n, err := io.Copy(io.MultiWriter(f, h), part)
+	if err != nil {
+		_ = f.Close()
+		_ = os.Remove(f.Name())
+		if IsBodyTooLarge(err) {
+			return nil, NewError(s.TooLarge, "Request body too large.")
+		}
+		var pe *os.PathError
+		if errors.As(err, &pe) {
+			return nil, err // disk failure, not the client's fault
+		}
+		return nil, malformed("unreadable multipart body", err)
+	}
+	out.Size = n
+	h.Sum(out.SHA256[:0])
+	return out, nil
+}

package/backend/internal/shared/web/multipart_test.go

@@ -0,0 +1,169 @@
+package web
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"errors"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+type mpPart struct{ name, filename, body string }
+
+func mpRequest(t *testing.T, parts []mpPart) *http.Request {
+	t.Helper()
+	var buf bytes.Buffer
+	w := multipart.NewWriter(&buf)
+	for _, p := range parts {
+		disp := `form-data; name="` + p.name + `"`
+		if p.filename != "" {
+			disp += `; filename="` + p.filename + `"`
+		}
+		pw, err := w.CreatePart(map[string][]string{"Content-Disposition": {disp}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, _ = pw.Write([]byte(p.body))
+	}
+	_ = w.Close()
+	r := httptest.NewRequest("POST", "/ideas", &buf)
+	r.Header.Set("Content-Type", w.FormDataContentType())
+	return r
+}
+
+func spec(dir string) MultipartSpec {
+	return MultipartSpec{FileField: "slides", TextFields: []string{"name"}, TooLarge: CodeFileTooLarge, TempDir: dir}
+}
+
+func assertEmpty(t *testing.T, dir string) {
+	t.Helper()
+	if es, _ := os.ReadDir(dir); len(es) != 0 {
+		t.Fatalf("temp dir not empty: %v", es)
+	}
+}
+
+func wantCode(t *testing.T, err error, code ErrorCode) {
+	t.Helper()
+	var e *Error
+	if !errors.As(err, &e) || e.Code != code {
+		t.Fatalf("err = %v, want %s", err, code)
+	}
+}
+
+func TestReadMultipartSuccess(t *testing.T) {
+	dir := t.TempDir()
+	r := mpRequest(t, []mpPart{{"name", "", "Idea"}, {"extra", "", "ignored"}, {"slides", `a/b\c.pdf`, "%PDF-1"}})
+	f, err := ReadMultipart(r, spec(dir))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.Fields["name"] != "Idea" || f.File.Size != 6 || f.File.Filename != `a/b\c.pdf` {
+		t.Fatalf("form = %+v file = %+v", f.Fields, f.File)
+	}
+	if f.File.SHA256 != sha256.Sum256([]byte("%PDF-1")) {
+		t.Fatal("sha256 mismatch")
+	}
+	b, _ := io.ReadAll(f.File.Open())
+	head := make([]byte, 5)
+	_, _ = f.File.ReaderAt().ReadAt(head, 0)
+	if string(b) != "%PDF-1" || string(head) != "%PDF-" {
+		t.Fatalf("content %q head %q", b, head)
+	}
+	if es, _ := os.ReadDir(dir); len(es) != 1 {
+		t.Fatalf("want one temp file while open, got %d", len(es))
+	}
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Close(); err != nil {
+		t.Fatal("second Close must be a no-op:", err)
+	}
+	assertEmpty(t, dir)
+}
+
+func TestReadMultipartMalformedRemovesTempFile(t *testing.T) {
+	tests := []struct {
+		name  string
+		parts []mpPart
+	}{
+		{"missing file", []mpPart{{"name", "", "x"}}},
+		{"missing text", []mpPart{{"slides", "a.pdf", "x"}}},
+		{"duplicate file", []mpPart{{"name", "", "x"}, {"slides", "a.pdf", "x"}, {"slides", "b.pdf", "y"}}},
+		{"duplicate text", []mpPart{{"name", "", "x"}, {"name", "", "y"}, {"slides", "a.pdf", "x"}}},
+		{"file without filename", []mpPart{{"name", "", "x"}, {"slides", "", "x"}}},
+		{"non-UTF-8 filename", []mpPart{{"name", "", "x"}, {"slides", "\xff.pdf", "x"}}},
+		{"non-UTF-8 text", []mpPart{{"name", "", "\xff"}, {"slides", "a.pdf", "x"}}},
+		{"oversized text", []mpPart{{"name", "", strings.Repeat("a", maxTextPartBytes+1)}, {"slides", "a.pdf", "x"}}},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			f, err := ReadMultipart(mpRequest(t, tc.parts), spec(dir))
+			if f != nil {
+				t.Fatal("form must be nil on error")
+			}
+			wantCode(t, err, CodeMalformedRequest)
+			assertEmpty(t, dir)
+		})
+	}
+}
+
+func TestReadMultipartNotMultipart(t *testing.T) {
+	r := httptest.NewRequest("POST", "/ideas", strings.NewReader("{}"))
+	r.Header.Set("Content-Type", "application/json")
+	_, err := ReadMultipart(r, spec(t.TempDir()))
+	wantCode(t, err, CodeMalformedRequest)
+}
+
+func TestReadMultipartTruncatedBody(t *testing.T) {
+	dir := t.TempDir()
+	r := mpRequest(t, []mpPart{{"name", "", "x"}, {"slides", "a.pdf", strings.Repeat("a", 1000)}})
+	body, _ := io.ReadAll(r.Body)
+	r.Body = io.NopCloser(bytes.NewReader(body[:len(body)/2]))
+	_, err := ReadMultipart(r, spec(dir))
+	wantCode(t, err, CodeMalformedRequest)
+	assertEmpty(t, dir)
+}
+
+func TestReadMultipartBodyLimit(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		parts []mpPart
+	}{
+		{"inside file part", []mpPart{{"name", "", "x"}, {"slides", "a.pdf", strings.Repeat("a", 4000)}}},
+		{"inside ignored part", []mpPart{{"junk", "", strings.Repeat("a", 4000)}, {"name", "", "x"}, {"slides", "a.pdf", "x"}}},
+		{"inside text part", []mpPart{{"name", "", strings.Repeat("a", 4000)}, {"slides", "a.pdf", "x"}}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			r := mpRequest(t, tc.parts)
+			rec := httptest.NewRecorder()
+			r.Body = http.MaxBytesReader(rec, r.Body, 1024)
+			_, err := ReadMultipart(r, spec(dir))
+			wantCode(t, err, CodeFileTooLarge)
+			assertEmpty(t, dir)
+		})
+	}
+}
+
+func TestReadMultipartTempDirUnwritable(t *testing.T) {
+	missing := filepath.Join(t.TempDir(), "nope")
+	_, err := ReadMultipart(mpRequest(t, []mpPart{{"name", "", "x"}, {"slides", "a.pdf", "x"}}), spec(missing))
+	var e *Error
+	if err == nil || errors.As(err, &e) {
+		t.Fatalf("want plain (500) error, got %v", err)
+	}
+}
+
+func TestFormCloseNil(t *testing.T) {
+	var f *Form
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
+}

package/backend/internal/shared/web/problem.go

@@ -17,6 +17,7 @@ type FieldError struct {
 	Field    string    `json:"field"`
 	Code     ErrorCode `json:"code"`
 	Expected string    `json:"expected,omitempty"`
+	Rule     string    `json:"rule,omitempty"` // PASSWORD_POLICY only: the violated rule id (PRD §6.4)
 }
 
 // Error is the one error type handlers and services return. The central

package/backend/internal/shared/web/request.go

@@ -1,8 +1,10 @@
 package web
 
 import (
+	"context"
 	"net/http"
 	"net/netip"
+	"strings"
 
 	"github.com/go-chi/chi/v5"
 )
@@ -17,8 +19,47 @@ func RoutePattern(r *http.Request) string {
 	return ""
 }
 
-// ClientIP is the TCP peer. Trusted-proxy handling is not decided yet.
+type clientIPKey struct{}
+
+// TrustedProxies resolves the client address from X-Forwarded-For when hops > 0
+// and stores it for ClientIP. hops is the number of proxies in front of the
+// service that append to the header; the client is the hops-th entry from the
+// right (earlier entries are client-supplied and ignored). With hops <= 0, or
+// when the header has fewer than hops valid entries, the TCP peer is used.
+func TrustedProxies(hops int) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		if hops <= 0 {
+			return next
+		}
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if ip, ok := forwardedClient(r.Header.Values("X-Forwarded-For"), hops); ok {
+				r = r.WithContext(context.WithValue(r.Context(), clientIPKey{}, ip))
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+func forwardedClient(values []string, hops int) (netip.Addr, bool) {
+	var parts []string
+	for _, v := range values {
+		parts = append(parts, strings.Split(v, ",")...)
+	}
+	if len(parts) < hops {
+		return netip.Addr{}, false
+	}
+	ip, err := netip.ParseAddr(strings.TrimSpace(parts[len(parts)-hops]))
+	if err != nil {
+		return netip.Addr{}, false
+	}
+	return ip.WithZone("").Unmap(), true
+}
+
+// ClientIP is the address TrustedProxies resolved, else the TCP peer.
 func ClientIP(r *http.Request) netip.Addr {
+	if ip, ok := r.Context().Value(clientIPKey{}).(netip.Addr); ok {
+		return ip
+	}
 	ap, err := netip.ParseAddrPort(r.RemoteAddr)
 	if err != nil {
 		return netip.Addr{}

package/backend/internal/shared/web/web_test.go

@@ -7,6 +7,7 @@ import (
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
+	"net/netip"
 	"os"
 	"sort"
 	"strings"
@@ -181,3 +182,38 @@ func TestFieldErrorsRendered(t *testing.T) {
 		t.Fatalf("%d %s", rec.Code, rec.Body)
 	}
 }
+
+func TestClientIPTrustedProxies(t *testing.T) {
+	for name, tc := range map[string]struct {
+		hops int
+		xff  []string
+		want string
+	}{
+		"hops 0 ignores header":     {0, []string{"198.51.100.1"}, "192.0.2.9"},
+		"one hop takes last entry":  {1, []string{"203.0.113.7, 198.51.100.1"}, "198.51.100.1"},
+		"spoofed prefix is ignored": {1, []string{"10.0.0.1, 198.51.100.1"}, "198.51.100.1"},
+		"two hops":                  {2, []string{"203.0.113.7, 198.51.100.1, 10.1.1.1"}, "198.51.100.1"},
+		"several header lines":      {1, []string{"203.0.113.7", "198.51.100.1"}, "198.51.100.1"},
+		"too few entries":           {2, []string{"198.51.100.1"}, "192.0.2.9"},
+		"no header":                 {1, nil, "192.0.2.9"},
+		"garbage entry":             {1, []string{"198.51.100.1, nope"}, "192.0.2.9"},
+		"ipv4-mapped and zone":      {1, []string{"::ffff:198.51.100.1"}, "198.51.100.1"},
+		"ipv6":                      {1, []string{"2001:db8::1"}, "2001:db8::1"},
+		"empty entry":               {1, []string{"198.51.100.1,"}, "192.0.2.9"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			r := httptest.NewRequest("GET", "/", nil)
+			r.RemoteAddr = "192.0.2.9:4000"
+			for _, v := range tc.xff {
+				r.Header.Add("X-Forwarded-For", v)
+			}
+			var got netip.Addr
+			web.TrustedProxies(tc.hops)(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+				got = web.ClientIP(r)
+			})).ServeHTTP(httptest.NewRecorder(), r)
+			if got.String() != tc.want {
+				t.Fatalf("got %s want %s", got, tc.want)
+			}
+		})
+	}
+}

package/backend/internal/storage/expectedfilename.go

@@ -0,0 +1,43 @@
+package storage
+
+import (
+	"golang.org/x/text/unicode/norm"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// MaxFilenameBytes is the longest expected filename in UTF-8 bytes (PRD §6.2).
+const MaxFilenameBytes = 255
+
+// longestExt is the extension used for the length rule: the file type is
+// unknown at create/edit time, so ".pptx" (the longer one) is assumed.
+const longestExt = ".pptx"
+
+// ExpectedFilenameBase builds {I|O}_{org}_{leaderName}_{leaderEmpNo}_{ideaName}
+// without extension by plain concatenation (PRD §6.8). All inputs are the
+// already cleaned values; they are NFC-normalized again so the result never
+// depends on how the caller stored them. category is COOL_IDEA or
+// OUTSTANDING_IMPACT; any other value is a programming error and is reported
+// as INTERNAL_ERROR rather than guessed.
+func ExpectedFilenameBase(category, org, leaderName, leaderEmpNo, ideaName string) (string, error) {
+	var prefix string
+	switch category {
+	case "COOL_IDEA":
+		prefix = "I"
+	case "OUTSTANDING_IMPACT":
+		prefix = "O"
+	default:
+		return "", web.NewError(web.CodeInternalError, "")
+	}
+	base := prefix + "_" + org + "_" + leaderName + "_" + leaderEmpNo + "_" + ideaName
+	return norm.NFC.String(base), nil
+}
+
+// CheckFilenameLength enforces PRD §6.2: base plus ".pptx" must not exceed
+// 255 UTF-8 bytes, else 422 FILENAME_TOO_LONG.
+func CheckFilenameLength(base string) error {
+	if len(base)+len(longestExt) > MaxFilenameBytes {
+		return web.NewError(web.CodeFilenameTooLong, "Expected filename exceeds 255 UTF-8 bytes.")
+	}
+	return nil
+}

package/backend/internal/storage/expectedfilename_test.go

@@ -0,0 +1,16 @@
+package storage
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+func TestExpectedFilenameBaseRejectsUnknownCategory(t *testing.T) {
+	_, err := ExpectedFilenameBase("OTHER", "AAID", "a", "000001", "b")
+	var we *web.Error
+	if !errors.As(err, &we) || we.Code != web.CodeInternalError {
+		t.Fatalf("err = %v, want INTERNAL_ERROR", err)
+	}
+}