@johnnyboy11234/esg-idea-contest 0.2.0 → 0.2.2

package/backend/internal/account/service.go

@@ -0,0 +1,153 @@
+// Package account owns app_user: registration today; profile, password change
+// and admin sync land with their own PRs. Backend.md §2.
+package account
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/netip"
+	"strings"
+
+	"github.com/google/uuid"
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/account/internal/store"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/db"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/text"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// bcryptCost is the only cost the table accepts (PRD §6.4, OI-13).
+const bcryptCost = 10
+
+// Recorder writes the success audit row in the registration transaction.
+// *audit.Service implements it.
+type Recorder interface {
+	Record(ctx context.Context, tx *sql.Tx, e audit.Event) error
+}
+
+// Service implements the account use cases.
+type Service struct {
+	DB     *sql.DB
+	Audit  Recorder
+	Policy PasswordPolicy
+}
+
+// RegisterCommand is the raw, unvalidated input.
+type RegisterCommand struct {
+	EmpNo, Name, Email, Password string
+}
+
+// Request is the transport facts the audit row needs.
+type Request struct {
+	Method, Route, UserAgent string
+	IP                       netip.Addr
+}
+
+// Registered is the stored account (never the hash).
+type Registered struct {
+	ID                 uuid.UUID
+	EmpNo, Name, Email string
+}
+
+// Register creates a USER. Order (PRD §6.3): format → password policy →
+// uniqueness. Every failure is a *web.Error carrying the AUTH_REGISTER FAILED
+// audit fields, so the central adapter writes the track-B row; a success
+// writes its SUCCESS row in the same transaction as the INSERT (fail-closed).
+func (s *Service) Register(ctx context.Context, cmd RegisterCommand, req Request) (Registered, error) {
+	empNoOK := checkEmpNo(cmd.EmpNo) == text.None
+
+	var fields []web.FieldError
+	add := func(field string, p text.Problem) {
+		if p != text.None {
+			fields = append(fields, web.FieldError{Field: field, Code: web.ErrorCode(p)})
+		}
+	}
+	add(fieldEmpNo, checkEmpNo(cmd.EmpNo))
+	name, p := text.CheckName(cmd.Name, maxNameLen)
+	add(fieldName, p)
+	email, p := checkEmail(cmd.Email)
+	add(fieldEmail, p)
+
+	policyEmpNo := ""
+	if empNoOK {
+		policyEmpNo = cmd.EmpNo
+	}
+	fields = append(fields, s.Policy.Check(cmd.Password, policyEmpNo)...)
+
+	if len(fields) > 0 {
+		e := web.NewError(topCode(fields), "the request has invalid fields")
+		e.Fields = fields
+		return Registered{}, failed(e, "validation", cmd.EmpNo, empNoOK)
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte(cmd.Password), bcryptCost)
+	if err != nil {
+		return Registered{}, fmt.Errorf("hash password: %w", err)
+	}
+
+	u := Registered{ID: uuid.New(), EmpNo: cmd.EmpNo, Name: name, Email: email}
+	after, _ := json.Marshal(map[string]string{"empNo": u.EmpNo, "name": u.Name}) // no email (PRD §6.11)
+
+	_, err = db.InTx(ctx, s.DB, func(ctx context.Context, tx *sql.Tx) error {
+		if err := store.InsertUser(ctx, tx, store.NewUser{
+			ID: u.ID, EmpNo: u.EmpNo, Name: u.Name, Email: u.Email, PasswordHash: string(hash),
+		}); err != nil {
+			return err
+		}
+		return s.Audit.Record(ctx, tx, audit.Event{
+			Action: audit.AuthRegister, Outcome: audit.Success,
+			TargetType: audit.TargetUser, TargetID: u.ID,
+			Method: req.Method, Route: req.Route, Status: http.StatusCreated,
+			IP: req.IP, UserAgent: req.UserAgent,
+			After: after,
+		})
+	})
+	if err != nil {
+		if e := duplicate(err); e != nil {
+			return Registered{}, failed(e, e.AuditReason, cmd.EmpNo, true)
+		}
+		return Registered{}, err
+	}
+	return u, nil
+}
+
+// duplicate maps a unique-key violation to 409. emp_no is checked first by the
+// server (it is the first unique key), so a row clashing on both says EMP_NO_TAKEN.
+func duplicate(err error) *web.Error {
+	key, ok := db.DuplicateKey(err)
+	if !ok {
+		return nil
+	}
+	var e *web.Error
+	switch {
+	case strings.Contains(key, "emp_no"):
+		e = web.NewError(web.CodeEmpNoTaken, "employee ID is already registered")
+		e.AuditReason = "emp_no_taken"
+	case strings.Contains(key, "email"):
+		e = web.NewError(web.CodeEmailTaken, "email is already registered")
+		e.AuditReason = "email_taken"
+	default:
+		return nil
+	}
+	e.Cause = err
+	return e
+}
+
+// failed marks e as an AUTH_REGISTER FAILED attempt (PRD §6.11): the typed
+// employee ID goes into the dedicated column (sanitized by audit), and into
+// after_json only when well-formed.
+func failed(e *web.Error, reason, empNo string, wellFormed bool) *web.Error {
+	e.AuditReason = reason
+	e.AuditAction = string(audit.AuthRegister)
+	e.AuditOutcome = string(audit.Failed)
+	e.AuditSubmittedEmpNo = empNo
+	if wellFormed {
+		e.AuditDetail = map[string]string{"empNo": empNo}
+	}
+	return e
+}

package/backend/internal/account/validate.go

@@ -0,0 +1,100 @@
+package account
+
+import (
+	"strings"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/text"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// Field limits (PRD §6.3).
+const (
+	empNoLen     = 6
+	maxNameLen   = 50
+	maxEmailLen  = 254
+	maxPassBytes = 72 // bcrypt silently ignores (x/crypto: rejects) anything longer
+)
+
+// Field names as they appear in errors[]; the order is the form order.
+const (
+	fieldEmpNo    = "empNo"
+	fieldName     = "name"
+	fieldEmail    = "email"
+	fieldPassword = "password"
+)
+
+// checkEmpNo: exactly six ASCII digits, nothing is trimmed (PRD §6.3).
+// Empty is REQUIRED, anything else wrong is INVALID_FORMAT.
+func checkEmpNo(s string) text.Problem {
+	if text.Trim(s) == "" {
+		return text.Required
+	}
+	if len(s) != empNoLen {
+		return text.InvalidFormat
+	}
+	for i := range len(s) {
+		if s[i] < '0' || s[i] > '9' {
+			return text.InvalidFormat
+		}
+	}
+	return text.None
+}
+
+// checkEmail trims, then requires printable ASCII with no whitespace, exactly
+// one '@' with non-empty sides and at most 254 characters; the result is
+// lower-cased (PRD §6.3, OI-14). Report order: REQUIRED, INVALID_FORMAT,
+// OUT_OF_RANGE.
+func checkEmail(s string) (string, text.Problem) {
+	e := text.Trim(s)
+	if e == "" {
+		return "", text.Required
+	}
+	for _, r := range e {
+		if r < 0x21 || r > 0x7E { // also rejects whitespace and control characters
+			return e, text.InvalidFormat
+		}
+	}
+	local, domain, ok := strings.Cut(e, "@")
+	if !ok || local == "" || domain == "" || strings.Contains(domain, "@") {
+		return e, text.InvalidFormat
+	}
+	if len(e) > maxEmailLen { // ASCII only, so bytes = code points
+		return e, text.OutOfRange
+	}
+	return strings.ToLower(e), text.None
+}
+
+// PasswordPolicy checks a candidate password and lists every violation, in
+// PRD §6.4 table order. empNo is the submitted employee ID when it is
+// well-formed and "" otherwise (the CONTAINS_EMP_NO rule is then skipped).
+type PasswordPolicy interface {
+	Check(password, empNo string) []web.FieldError
+}
+
+// StubPolicy is the placeholder until B1b-01 delivers the §6.4 rules. It only
+// refuses what the account cannot store: an empty password and one bcrypt
+// cannot hash (longer than 72 bytes). Everything else is accepted.
+type StubPolicy struct{}
+
+// Check implements PasswordPolicy.
+func (StubPolicy) Check(password, _ string) []web.FieldError {
+	switch {
+	case password == "":
+		return []web.FieldError{{Field: fieldPassword, Code: web.CodeRequired}}
+	case len(password) > maxPassBytes:
+		return []web.FieldError{{Field: fieldPassword, Code: web.CodeOutOfRange}}
+	}
+	return nil
+}
+
+// topCode is the response code of a 422: the first field error's code when it
+// is a specific registered code, else VALIDATION_FAILED (error-codes.md §2).
+func topCode(fields []web.FieldError) web.ErrorCode {
+	if len(fields) > 0 {
+		switch c := fields[0].Code; c {
+		case web.CodeInvalidNameChars, web.CodePasswordPolicy:
+			return c
+		}
+	}
+	return web.CodeValidationFailed
+}

package/backend/internal/api/api.gen.go

@@ -160,6 +160,26 @@ type Problem struct {
 	Type string `json:"type"`
 }
 
+// RegisterRequest defines model for RegisterRequest.
+type RegisterRequest struct {
+	// Email Printable ASCII with exactly one @, at most 254 characters; stored lower-cased
+	Email string `json:"email"`
+
+	// EmpNo Exactly 6 ASCII digits
+	EmpNo string `json:"empNo"`
+
+	// Name 1-50 code points after clean-up
+	Name     string `json:"name"`
+	Password string `json:"password"`
+}
+
+// RegisterResponse defines model for RegisterResponse.
+type RegisterResponse struct {
+	Email string `json:"email"`
+	EmpNo string `json:"empNo"`
+	Name  string `json:"name"`
+}
+
 // CsrfToken defines model for CsrfToken.
 type CsrfToken = string
 
@@ -172,12 +192,21 @@ type LogoutParams struct {
 	XCSRFToken *CsrfToken `json:"X-CSRF-Token,omitempty"`
 }
 
+// RegisterParams defines parameters for Register.
+type RegisterParams struct {
+	// XCSRFToken Session-bound token from GET /auth/csrf. Mandatory on every write, but enforced by the CSRF middleware (403 CSRF_INVALID), so the generated wrapper must not reject its absence first (400).
+	XCSRFToken *CsrfToken `json:"X-CSRF-Token,omitempty"`
+}
+
 // ListIdeasParams defines parameters for ListIdeas.
 type ListIdeasParams struct {
 	Page *int `form:"page,omitempty" json:"page,omitempty"`
 	Size *int `form:"size,omitempty" json:"size,omitempty"`
 }
 
+// RegisterJSONRequestBody defines body for Register for application/json ContentType.
+type RegisterJSONRequestBody = RegisterRequest
+
 // ServerInterface represents all server handlers.
 type ServerInterface interface {
 	// GetCsrfToken Session-bound CSRF token (anonymous before login)
@@ -186,6 +215,9 @@ type ServerInterface interface {
 	// Logout End the session
 	// (POST /auth/logout)
 	Logout(w http.ResponseWriter, r *http.Request, params LogoutParams)
+	// Register Self-service registration (no session is created)
+	// (POST /auth/register)
+	Register(w http.ResponseWriter, r *http.Request, params RegisterParams)
 	// GetDeadline Submission deadline, state and database server time
 	// (GET /deadline)
 	GetDeadline(w http.ResponseWriter, r *http.Request)
@@ -213,6 +245,12 @@ func (_ Unimplemented) Logout(w http.ResponseWriter, r *http.Request, params Log
 	w.WriteHeader(http.StatusNotImplemented)
 }
 
+// Register Self-service registration (no session is created)
+// (POST /auth/register)
+func (_ Unimplemented) Register(w http.ResponseWriter, r *http.Request, params RegisterParams) {
+	w.WriteHeader(http.StatusNotImplemented)
+}
+
 // GetDeadline Submission deadline, state and database server time
 // (GET /deadline)
 func (_ Unimplemented) GetDeadline(w http.ResponseWriter, r *http.Request) {
@@ -295,6 +333,47 @@ func (siw *ServerInterfaceWrapper) Logout(w http.ResponseWriter, r *http.Request
 	handler.ServeHTTP(w, r)
 }
 
+// Register operation middleware
+func (siw *ServerInterfaceWrapper) Register(w http.ResponseWriter, r *http.Request) {
+
+	var err error
+	_ = err
+
+	// Parameter object where we will unmarshal all parameters from the context
+	var params RegisterParams
+
+	headers := r.Header
+
+	// ------------- Optional header parameter "X-CSRF-Token" -------------
+	if valueList, found := headers[http.CanonicalHeaderKey("X-CSRF-Token")]; found {
+		var XCSRFToken CsrfToken
+		n := len(valueList)
+		if n != 1 {
+			siw.ErrorHandlerFunc(w, r, &TooManyValuesForParamError{ParamName: "X-CSRF-Token", Count: n})
+			return
+		}
+
+		err = runtime.BindStyledParameterWithOptions("simple", "X-CSRF-Token", valueList[0], &XCSRFToken, runtime.BindStyledParameterOptions{ParamLocation: runtime.ParamLocationHeader, Explode: false, Required: false, Type: "string", Format: ""})
+		if err != nil {
+			siw.ErrorHandlerFunc(w, r, &InvalidParamFormatError{ParamName: "X-CSRF-Token", Err: err})
+			return
+		}
+
+		params.XCSRFToken = &XCSRFToken
+
+	}
+
+	handler := http.Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		siw.Handler.Register(w, r, params)
+	}))
+
+	for _, middleware := range siw.HandlerMiddlewares {
+		handler = middleware(handler)
+	}
+
+	handler.ServeHTTP(w, r)
+}
+
 // GetDeadline operation middleware
 func (siw *ServerInterfaceWrapper) GetDeadline(w http.ResponseWriter, r *http.Request) {
 
@@ -500,6 +579,9 @@ func HandlerWithOptions(si ServerInterface, options ChiServerOptions) http.Handl
 	r.Group(func(r chi.Router) {
 		r.Post(options.BaseURL+"/auth/logout", wrapper.Logout)
 	})
+	r.Group(func(r chi.Router) {
+		r.Post(options.BaseURL+"/auth/register", wrapper.Register)
+	})
 	r.Group(func(r chi.Router) {
 		r.Get(options.BaseURL+"/deadline", wrapper.GetDeadline)
 	})

package/backend/internal/audit/integration_test.go

@@ -84,7 +84,7 @@ func TestAudit(t *testing.T) {
 
 	t.Run("track A is written in the caller's transaction and carries every field", func(t *testing.T) {
 		reset(t, d)
-		ctx := ctxWithReq(&security.Principal{UserID: 7, EmpNo: "E0001", Role: security.RoleUser})
+		ctx := ctxWithReq(&security.Principal{UserID: uuid.New(), EmpNo: "E0001", Role: security.RoleUser})
 		target := uuid.New()
 		out, err := db.InTx(ctx, d, func(ctx context.Context, tx *sql.Tx) error {
 			return svc.Record(ctx, tx, audit.Event{

package/backend/internal/auth/csrf.go

@@ -0,0 +1,212 @@
+package auth
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"strings"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// CSRF names and sizes (PRD §6.5, Backend.md §6, D40).
+const (
+	// CSRFCookie is the double-submit cookie. The __Host- prefix forces Secure,
+	// Path=/ and no Domain; HttpOnly keeps it away from script, which reads the
+	// token from the GET /auth/csrf body instead.
+	CSRFCookie = "__Host-csrf"
+	// CSRFHeader carries the token on every write.
+	CSRFHeader = "X-CSRF-Token"
+
+	// MinCSRFKeyBytes is the shortest accepted HMAC key (the SHA-256 output size).
+	MinCSRFKeyBytes = 32
+
+	nonceBytes = 16
+)
+
+var anonymousBinding = []byte{0x00, 'a', 'n', 'o', 'n'}
+
+// CSRF signs and verifies session-bound double-submit tokens:
+//
+//	base64url(nonce) "." base64url(HMAC-SHA256(key, binding ‖ nonce))
+//
+// The binding is 0x01 ‖ SHA-256(session ID) with a session, a fixed anonymous
+// value without one. A token minted anonymously, or for another session,
+// therefore fails against a victim's session (D40).
+//
+// The first key signs; every key verifies. Rotation: make the new key current
+// and the old one previous, and drop the previous key after 8 h (Backend.md §6).
+// Tokens carry no expiry, so the operator's removal of the old key is the bound.
+type CSRF struct {
+	keys [][]byte
+}
+
+// NewCSRF returns a signer. current signs; previous (optional) only verifies.
+func NewCSRF(current string, previous ...string) (*CSRF, error) {
+	c := &CSRF{}
+	for i, k := range append([]string{current}, previous...) {
+		if i > 0 && k == "" {
+			continue // an unset previous key means "no rotation in progress"
+		}
+		if len(k) < MinCSRFKeyBytes {
+			return nil, fmt.Errorf("csrf key %d: need at least %d bytes", i, MinCSRFKeyBytes)
+		}
+		c.keys = append(c.keys, []byte(k))
+	}
+	return c, nil
+}
+
+// bindingFor returns the binding for a request: the session's when the session
+// middleware resolved one, else the anonymous value. ok is false only when a
+// validated session carries an ID that cannot be bound (cannot happen unless
+// the validator and Binding disagree).
+func bindingFor(r *http.Request) (b []byte, ok bool) {
+	if _, has := security.PrincipalFrom(r.Context()); !has {
+		return anonymousBinding, true
+	}
+	c, err := r.Cookie(SessionCookie)
+	if err != nil {
+		return nil, false
+	}
+	h, ok := Binding(c.Value)
+	if !ok {
+		return nil, false
+	}
+	return append([]byte{0x01}, h...), true
+}
+
+func mac(key, binding, nonce []byte) []byte {
+	m := hmac.New(sha256.New, key)
+	m.Write(binding)
+	m.Write(nonce)
+	return m.Sum(nil)
+}
+
+// Issue returns a fresh token for binding.
+func (c *CSRF) Issue(binding []byte) (string, error) {
+	nonce := make([]byte, nonceBytes)
+	if _, err := rand.Read(nonce); err != nil {
+		return "", err
+	}
+	return b64(nonce) + "." + b64(mac(c.keys[0], binding, nonce)), nil
+}
+
+// Verify reports whether token was issued by one of the keys for binding.
+func (c *CSRF) Verify(token string, binding []byte) bool {
+	n, s, found := strings.Cut(token, ".")
+	if !found {
+		return false
+	}
+	nonce, err1 := base64.RawURLEncoding.DecodeString(n)
+	sig, err2 := base64.RawURLEncoding.DecodeString(s)
+	if err1 != nil || err2 != nil || len(nonce) != nonceBytes {
+		return false
+	}
+	ok := false
+	for _, k := range c.keys { // no early exit: time does not tell which key matched
+		if hmac.Equal(sig, mac(k, binding, nonce)) {
+			ok = true
+		}
+	}
+	return ok
+}
+
+func b64(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }
+
+// safeMethod is the set that is never CSRF-checked (RFC 9110 §9.2.1).
+func safeMethod(m string) bool {
+	return m == http.MethodGet || m == http.MethodHead || m == http.MethodOptions
+}
+
+// ActionFor names the audit action of the write r attempts, or "" when it is
+// unknown (unrouted path). A rejected attempt is audited only with an action.
+type ActionFor func(r *http.Request) string
+
+// Middleware enforces the CSRF check on every non-safe method. It runs after
+// the session middleware (so 401 wins) and before routing (so 403 beats 404),
+// reads only the header and the cookie and never the body. Accepted only if
+// cookie and header are both present and equal, the signature verifies, and
+// the binding matches the request's session (or anonymous without one).
+//
+// fail is the central error adapter; it audits the denial when the *web.Error
+// carries an AuditReason and an action.
+func (c *CSRF) Middleware(fail func(http.ResponseWriter, *http.Request, error), action ActionFor) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if safeMethod(r.Method) {
+				next.ServeHTTP(w, r)
+				return
+			}
+			if reason := c.check(r); reason != "" {
+				e := web.NewError(web.CodeCSRFInvalid, "CSRF token missing or invalid.")
+				if action != nil {
+					if a := action(r); a != "" {
+						e.AuditAction, e.AuditReason = a, reason
+					}
+				}
+				fail(w, r, e)
+				return
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+// check returns "" when r passes, else the audit reason (never sent to the client).
+func (c *CSRF) check(r *http.Request) string {
+	hdr := r.Header.Get(CSRFHeader)
+	ck, err := r.Cookie(CSRFCookie)
+	switch {
+	case hdr == "" || err != nil || ck.Value == "":
+		return "csrf_missing"
+	case subtle.ConstantTimeCompare([]byte(hdr), []byte(ck.Value)) != 1:
+		return "csrf_mismatch"
+	}
+	b, ok := bindingFor(r)
+	if !ok || !c.Verify(hdr, b) {
+		return "csrf_invalid_binding"
+	}
+	return ""
+}
+
+// Handler serves GET /auth/csrf: a token for the caller's current binding in
+// the body and in the cookie. It is public; with a session the token is bound
+// to it. Login and logout change the binding, so the client refetches then.
+type Handler struct {
+	CSRF *CSRF
+	Log  *slog.Logger
+}
+
+// GetCsrfToken serves GET /auth/csrf.
+func (h Handler) GetCsrfToken(w http.ResponseWriter, r *http.Request) {
+	b, ok := bindingFor(r)
+	if !ok {
+		h.fail(w, r, errors.New("session without bindable ID"))
+		return
+	}
+	tok, err := h.CSRF.Issue(b)
+	if err != nil {
+		h.fail(w, r, err)
+		return
+	}
+	http.SetCookie(w, &http.Cookie{
+		Name: CSRFCookie, Value: tok, Path: "/",
+		Secure: true, HttpOnly: true, SameSite: http.SameSiteLaxMode,
+	})
+	w.Header().Set("Cache-Control", "no-store")
+	web.WriteJSON(w, http.StatusOK, api.CsrfTokenResponse{Token: tok})
+}
+
+func (h Handler) fail(w http.ResponseWriter, r *http.Request, err error) {
+	h.Log.ErrorContext(r.Context(), "csrf token issue failed",
+		"requestId", web.RequestIDFrom(r.Context()), "error", err)
+	web.WriteProblem(w, r, web.NewError(web.CodeInternalError, ""))
+}