@johnnyboy11234/esg-idea-contest 0.2.0 → 0.2.2

package/backend/api/openapi.yaml

@@ -41,6 +41,35 @@ paths:
         '204': { description: Logged out }
         '403': { $ref: '#/components/responses/Problem' }
         '500': { $ref: '#/components/responses/Problem' }
+  /auth/register:
+    post:
+      operationId: register
+      tags: [auth]
+      summary: Self-service registration (no session is created)
+      description: >
+        Validation order: format, password policy, uniqueness (PRD 6.3). Sets no cookie.
+      security: []
+      parameters:
+        - $ref: '#/components/parameters/CsrfToken'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/RegisterRequest' }
+      responses:
+        '201':
+          description: Account created; log in separately
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RegisterResponse' }
+        '400': { $ref: '#/components/responses/Problem' }
+        '403': { $ref: '#/components/responses/Problem' }
+        '409': { $ref: '#/components/responses/Problem' }
+        '413': { $ref: '#/components/responses/Problem' }
+        '415': { $ref: '#/components/responses/Problem' }
+        '422': { $ref: '#/components/responses/Problem' }
+        '500': { $ref: '#/components/responses/Problem' }
+        '503': { $ref: '#/components/responses/Problem' }
   /deadline:
     get:
       operationId: getDeadline
@@ -125,6 +154,21 @@ components:
       required: [token]
       properties:
         token: { type: string }
+    RegisterRequest:
+      type: object
+      required: [empNo, name, email, password]
+      properties:
+        empNo: { type: string, description: 'Exactly 6 ASCII digits' }
+        name: { type: string, description: 1-50 code points after clean-up }
+        email: { type: string, description: 'Printable ASCII with exactly one @, at most 254 characters; stored lower-cased' }
+        password: { type: string, format: password }
+    RegisterResponse:
+      type: object
+      required: [empNo, name, email]
+      properties:
+        empNo: { type: string }
+        name: { type: string }
+        email: { type: string }
     Problem:
       type: object
       required: [type, title, status, code]

package/backend/cmd/server/main.go

@@ -13,6 +13,9 @@ import (
 
 	_ "github.com/go-sql-driver/mysql"
 
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/account"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/deadline"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/server"
 	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/config"
@@ -42,8 +45,23 @@ func run() error {
 	}
 	defer func() { _ = db.Close() }()
 
-	si := server.API{Deadline: deadline.Handler{Store: deadline.SQLStore{DB: db}}}
+	auditSvc := audit.New(db, log)
+	errs := server.ErrorAdapter{Audit: auditSvc, Log: log}
+	csrf, err := auth.NewCSRF(cfg.CSRFKey, cfg.CSRFKeyPrevious)
+	if err != nil {
+		return err
+	}
+	si := server.API{
+		Auth: auth.Handler{CSRF: csrf, Log: log},
+		Account: account.Handler{
+			Service: &account.Service{DB: db, Audit: auditSvc, Policy: account.StubPolicy{}},
+			Fail:    errs.Write,
+		},
+		Deadline: deadline.Handler{Store: deadline.SQLStore{DB: db}},
+	}
 
 	var ready atomic.Bool
-	return server.Run(ctx, cfg, log, server.NewPublic(log, server.Mount(si)), &ready, server.DBCheck(db))
+	return server.Run(ctx, cfg, log, server.NewPublic(log, server.Mount(si),
+		auth.Middleware(auth.New(db), server.IsPublic, log),
+		csrf.Middleware(errs.Write, server.ActionFor)), &ready, server.DBCheck(db))
 }

package/backend/db/migration/V004__session.sql

@@ -0,0 +1,19 @@
+-- V004 (B1-07): server-side sessions (PRD 6.5). Only SHA-256(session ID) is stored, never the ID itself,
+-- so a database read does not yield usable cookies. The role is NOT stored: it is read from app_user on
+-- every request. Times are database time in UTC (Architecture principle 4).
+--   idle timeout     30 min since last_access_at (refreshed at most once per 60 s, OI-11)
+--   absolute timeout  8 h since created_at
+-- Deleting or disabling a user ends their sessions: ON DELETE CASCADE here, SessionRevoker for disable.
+
+CREATE TABLE session (
+    id_hash        BINARY(32)  NOT NULL,
+    user_id        UUID        NOT NULL,
+    created_at     DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    last_access_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    PRIMARY KEY (id_hash),
+    KEY ix_session_user (user_id),
+    -- Purge scans by age.
+    KEY ix_session_created (created_at),
+    KEY ix_session_last_access (last_access_at),
+    CONSTRAINT fk_session_user FOREIGN KEY (user_id) REFERENCES app_user (id) ON DELETE CASCADE
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_bin;

package/backend/go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/oapi-codegen/runtime v1.8.0
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
 	github.com/testcontainers/testcontainers-go/modules/mariadb v0.45.0
+	golang.org/x/crypto v0.58.0
 	golang.org/x/text v0.43.0
 )
 
@@ -73,7 +74,6 @@ require (
 	go.opentelemetry.io/otel/metric v1.44.0 // indirect
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.5 // indirect
-	golang.org/x/crypto v0.58.0 // indirect
 	golang.org/x/mod v0.41.0 // indirect
 	golang.org/x/sync v0.24.0 // indirect
 	golang.org/x/sys v0.49.0 // indirect

package/backend/internal/account/account_test.go

@@ -0,0 +1,191 @@
+package account_test
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/account"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// A Service with no database: every case here must be rejected before any I/O.
+func validate(t *testing.T, cmd account.RegisterCommand) *web.Error {
+	t.Helper()
+	svc := &account.Service{Policy: account.StubPolicy{}}
+	_, err := svc.Register(context.Background(), cmd, account.Request{})
+	var e *web.Error
+	if !errors.As(err, &e) {
+		t.Fatalf("want *web.Error, got %v", err)
+	}
+	return e
+}
+
+func good() account.RegisterCommand {
+	return account.RegisterCommand{EmpNo: "089290", Name: "王小明", Email: "a@b.c", Password: "whatever-goes"}
+}
+
+func codes(e *web.Error) []string {
+	var out []string
+	for _, f := range e.Fields {
+		out = append(out, f.Field+":"+string(f.Code))
+	}
+	return out
+}
+
+func TestRegisterValidation(t *testing.T) {
+	cases := []struct {
+		name   string
+		mut    func(*account.RegisterCommand)
+		top    web.ErrorCode
+		fields string
+	}{
+		{"empty emp no", func(c *account.RegisterCommand) { c.EmpNo = " " }, web.CodeValidationFailed, "empNo:REQUIRED"},
+		{"emp no 5 digits", func(c *account.RegisterCommand) { c.EmpNo = "12345" }, web.CodeValidationFailed, "empNo:INVALID_FORMAT"},
+		{"emp no 7 digits", func(c *account.RegisterCommand) { c.EmpNo = "1234567" }, web.CodeValidationFailed, "empNo:INVALID_FORMAT"},
+		{"emp no letter", func(c *account.RegisterCommand) { c.EmpNo = "12345a" }, web.CodeValidationFailed, "empNo:INVALID_FORMAT"},
+		{"emp no not trimmed", func(c *account.RegisterCommand) { c.EmpNo = " 12345" }, web.CodeValidationFailed, "empNo:INVALID_FORMAT"},
+		{"emp no fullwidth digits", func(c *account.RegisterCommand) { c.EmpNo = "１２３４５６" }, web.CodeValidationFailed, "empNo:INVALID_FORMAT"},
+		{"name empty after clean-up", func(c *account.RegisterCommand) { c.Name = " 　\t" }, web.CodeValidationFailed, "name:REQUIRED"},
+		{"name forbidden char", func(c *account.RegisterCommand) { c.Name = "a/b" }, web.CodeInvalidNameChars, "name:INVALID_NAME_CHARS"},
+		{"name control char", func(c *account.RegisterCommand) { c.Name = "a\x00b" }, web.CodeValidationFailed, "name:INVALID_FORMAT"},
+		{"name 51 code points", func(c *account.RegisterCommand) { c.Name = strings.Repeat("名", 51) }, web.CodeValidationFailed, "name:OUT_OF_RANGE"},
+		{"email with space", func(c *account.RegisterCommand) { c.Email = "a b@x.com" }, web.CodeValidationFailed, "email:INVALID_FORMAT"},
+		{"email without @", func(c *account.RegisterCommand) { c.Email = "ab.com" }, web.CodeValidationFailed, "email:INVALID_FORMAT"},
+		{"email two @", func(c *account.RegisterCommand) { c.Email = "a@b@c" }, web.CodeValidationFailed, "email:INVALID_FORMAT"},
+		{"email empty local", func(c *account.RegisterCommand) { c.Email = "@b" }, web.CodeValidationFailed, "email:INVALID_FORMAT"},
+		{"email empty domain", func(c *account.RegisterCommand) { c.Email = "a@" }, web.CodeValidationFailed, "email:INVALID_FORMAT"},
+		{"email non-ASCII", func(c *account.RegisterCommand) { c.Email = "é@x.com" }, web.CodeValidationFailed, "email:INVALID_FORMAT"},
+		{"email empty", func(c *account.RegisterCommand) { c.Email = "" }, web.CodeValidationFailed, "email:REQUIRED"},
+		{"email 255 chars", func(c *account.RegisterCommand) { c.Email = strings.Repeat("a", 253) + "@b" }, web.CodeValidationFailed, "email:OUT_OF_RANGE"},
+		{"password empty", func(c *account.RegisterCommand) { c.Password = "" }, web.CodeValidationFailed, "password:REQUIRED"},
+		{"password beyond bcrypt", func(c *account.RegisterCommand) { c.Password = strings.Repeat("p", 73) }, web.CodeValidationFailed, "password:OUT_OF_RANGE"},
+		{"all fields in form order", func(c *account.RegisterCommand) {
+			c.EmpNo, c.Name, c.Email, c.Password = "x", "a:b", "nope", ""
+		}, web.CodeValidationFailed, "empNo:INVALID_FORMAT name:INVALID_NAME_CHARS email:INVALID_FORMAT password:REQUIRED"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := good()
+			tc.mut(&cmd)
+			e := validate(t, cmd)
+			if e.Status != 422 || e.Code != tc.top {
+				t.Errorf("status %d code %s, want 422 %s", e.Status, e.Code, tc.top)
+			}
+			if got := strings.Join(codes(e), " "); got != tc.fields {
+				t.Errorf("fields = %q, want %q", got, tc.fields)
+			}
+			// Every failure is an AUTH_REGISTER FAILED attempt for the adapter.
+			if e.AuditAction != "AUTH_REGISTER" || e.AuditOutcome != "FAILED" || e.AuditReason != "validation" {
+				t.Errorf("audit fields = %q %q %q", e.AuditAction, e.AuditOutcome, e.AuditReason)
+			}
+		})
+	}
+}
+
+func TestFailedAuditCarriesEmpNoOnlyWhenWellFormed(t *testing.T) {
+	cmd := good()
+	cmd.Name = ""
+	e := validate(t, cmd)
+	if e.AuditSubmittedEmpNo != "089290" || e.AuditDetail["empNo"] != "089290" {
+		t.Errorf("well-formed: submitted %q detail %v", e.AuditSubmittedEmpNo, e.AuditDetail)
+	}
+	cmd.EmpNo = "12x"
+	e = validate(t, cmd)
+	if e.AuditSubmittedEmpNo != "12x" || e.AuditDetail != nil {
+		t.Errorf("malformed: submitted %q detail %v", e.AuditSubmittedEmpNo, e.AuditDetail)
+	}
+}
+
+type spyPolicy struct{ empNo string }
+
+func (s *spyPolicy) Check(_, empNo string) []web.FieldError {
+	s.empNo = empNo
+	return []web.FieldError{{Field: "password", Code: web.CodePasswordPolicy}}
+}
+
+func TestPolicyRunsWithFormatErrorsAndSeesEmpNoOnlyWhenWellFormed(t *testing.T) {
+	spy := &spyPolicy{}
+	svc := &account.Service{Policy: spy}
+	cmd := good()
+	cmd.Email = "bad"
+
+	_, err := svc.Register(context.Background(), cmd, account.Request{})
+	var e *web.Error
+	if !errors.As(err, &e) {
+		t.Fatal(err)
+	}
+	if got := strings.Join(codes(e), " "); got != "email:INVALID_FORMAT password:PASSWORD_POLICY" {
+		t.Errorf("fields = %q: format and policy errors must come together", got)
+	}
+	if spy.empNo != "089290" {
+		t.Errorf("policy got empNo %q", spy.empNo)
+	}
+
+	cmd.EmpNo = "bad"
+	_, _ = svc.Register(context.Background(), cmd, account.Request{})
+	if spy.empNo != "" {
+		t.Errorf("policy got empNo %q for a malformed ID; CONTAINS_EMP_NO must be skipped", spy.empNo)
+	}
+}
+
+func TestTopCodeIsPasswordPolicyWhenFirst(t *testing.T) {
+	svc := &account.Service{Policy: &spyPolicy{}}
+	_, err := svc.Register(context.Background(), good(), account.Request{})
+	var e *web.Error
+	if !errors.As(err, &e) || e.Code != web.CodePasswordPolicy || e.Status != 422 {
+		t.Fatalf("%v", err)
+	}
+}
+
+func handlerFor(got *error) http.Handler {
+	h := account.Handler{
+		Service: &account.Service{Policy: account.StubPolicy{}},
+		Fail:    func(_ http.ResponseWriter, _ *http.Request, err error) { *got = err },
+	}
+	return http.HandlerFunc(h.Register)
+}
+
+func post(h http.Handler, contentType, body string) {
+	req := httptest.NewRequest("POST", "/api/v1/auth/register", strings.NewReader(body))
+	if contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	h.ServeHTTP(httptest.NewRecorder(), req)
+}
+
+func TestHandlerTransportErrors(t *testing.T) {
+	cases := []struct {
+		name, ct, body string
+		code           web.ErrorCode
+		audited        bool
+	}{
+		{"broken JSON", "application/json", `{`, web.CodeMalformedRequest, true},
+		{"missing field", "application/json", `{"empNo":"089290","name":"n","email":"a@b"}`, web.CodeMalformedRequest, true},
+		{"null field", "application/json", `{"empNo":"089290","name":"n","email":"a@b","password":null}`, web.CodeMalformedRequest, true},
+		{"wrong type", "application/json", `{"empNo":89290,"name":"n","email":"a@b","password":"x"}`, web.CodeMalformedRequest, true},
+		{"duplicate key", "application/json", `{"empNo":"1","empNo":"2","name":"n","email":"a@b","password":"x"}`, web.CodeMalformedRequest, true},
+		{"not JSON", "text/plain", `{}`, web.CodeUnsupportedMedia, false},
+		{"no content type", "", `{}`, web.CodeUnsupportedMedia, false},
+		{"over 16 KiB", "application/json", `{"name":"` + strings.Repeat("x", 17<<10) + `"}`, web.CodeRequestTooLarge, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var got error
+			post(handlerFor(&got), tc.ct, tc.body)
+			var e *web.Error
+			if !errors.As(got, &e) || e.Code != tc.code {
+				t.Fatalf("got %v, want %s", got, tc.code)
+			}
+			if audited := e.AuditReason != ""; audited != tc.audited {
+				t.Errorf("audited = %v, want %v (PRD 6.11: only 400, 409, 422)", audited, tc.audited)
+			}
+			if tc.audited && (e.AuditAction != "AUTH_REGISTER" || e.AuditOutcome != "FAILED" || e.AuditSubmittedEmpNo != "") {
+				t.Errorf("audit fields = %q %q %q", e.AuditAction, e.AuditOutcome, e.AuditSubmittedEmpNo)
+			}
+		})
+	}
+}

package/backend/internal/account/handler.go

@@ -0,0 +1,58 @@
+package account
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/api"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// maxJSONBody is the JSON body limit (error-codes.md §2: 16 KiB → 413).
+const maxJSONBody = 16 << 10
+
+// Handler is the HTTP adapter of the account module. Fail is the central error
+// adapter (server.ErrorAdapter.Write); the module cannot import server.
+type Handler struct {
+	Service *Service
+	Fail    func(w http.ResponseWriter, r *http.Request, err error)
+}
+
+// registerBody holds pointers so DecodeJSON can tell absent/null (400) from
+// empty (422). Unknown keys are ignored.
+type registerBody struct {
+	EmpNo    *string `json:"empNo"`
+	Name     *string `json:"name"`
+	Email    *string `json:"email"`
+	Password *string `json:"password"`
+}
+
+// Register serves POST /auth/register: 201 {empNo, name, email}, no cookie, no Location.
+func (h Handler) Register(w http.ResponseWriter, r *http.Request) {
+	r.Body = http.MaxBytesReader(w, r.Body, maxJSONBody)
+	var b registerBody
+	if err := web.DecodeJSON(r, &b); err != nil {
+		h.Fail(w, r, auditMalformed(err))
+		return
+	}
+	u, err := h.Service.Register(r.Context(), RegisterCommand{
+		EmpNo: *b.EmpNo, Name: *b.Name, Email: *b.Email, Password: *b.Password,
+	}, Request{
+		Method: r.Method, Route: web.RoutePattern(r), UserAgent: r.UserAgent(), IP: web.ClientIP(r),
+	})
+	if err != nil {
+		h.Fail(w, r, err)
+		return
+	}
+	web.WriteJSON(w, http.StatusCreated, api.RegisterResponse{EmpNo: u.EmpNo, Name: u.Name, Email: u.Email})
+}
+
+// auditMalformed marks a 400 as a FAILED registration (PRD §6.11 audits 400,
+// 409 and 422 here). Other transport errors (413, 415) are not audited.
+func auditMalformed(err error) error {
+	var e *web.Error
+	if errors.As(err, &e) && e.Code == web.CodeMalformedRequest {
+		return failed(e, "malformed_request", "", false)
+	}
+	return err
+}

package/backend/internal/account/integration_test.go

@@ -0,0 +1,268 @@
+//go:build integration
+
+package account_test
+
+import (
+	"database/sql"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/account"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/server"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/dbtest"
+	"github.com/brian-huanggg/AwardRegistration/backend/test/apispec"
+)
+
+type env struct {
+	db *sql.DB
+	h  http.Handler
+}
+
+func newEnv(t *testing.T) env {
+	t.Helper()
+	db := dbtest.New(t)
+	auditSvc := audit.New(db, nil)
+	errs := server.ErrorAdapter{Audit: auditSvc}
+	api := server.API{Account: account.Handler{
+		Service: &account.Service{DB: db, Audit: auditSvc, Policy: account.StubPolicy{}},
+		Fail:    errs.Write,
+	}}
+	h := apispec.Load(t).Validate(t, server.NewPublic(slog.New(slog.DiscardHandler), server.Mount(api)))
+	return env{db: db, h: h}
+}
+
+func (e env) register(body string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest("POST", "/api/v1/auth/register", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("User-Agent", "it/1")
+	req.RemoteAddr = "192.0.2.9:4000"
+	rec := httptest.NewRecorder()
+	e.h.ServeHTTP(rec, req)
+	return rec
+}
+
+func reg(empNo, name, email, pw string) string {
+	b, _ := json.Marshal(map[string]string{"empNo": empNo, "name": name, "email": email, "password": pw})
+	return string(b)
+}
+
+type auditRow struct {
+	Action, Outcome, ActorRole, ErrorCode string
+	Status                                sql.NullInt64
+	Route, Method, Submitted, After       sql.NullString
+	TargetType                            sql.NullString
+}
+
+func (e env) auditRows(t *testing.T) []auditRow {
+	t.Helper()
+	rows, err := e.db.Query(`SELECT action, outcome, actor_role, COALESCE(error_code,''), status, route, method,
+		submitted_emp_no, CAST(after_json AS CHAR), target_type FROM audit_log ORDER BY id`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rows.Close()
+	var out []auditRow
+	for rows.Next() {
+		var r auditRow
+		if err := rows.Scan(&r.Action, &r.Outcome, &r.ActorRole, &r.ErrorCode, &r.Status, &r.Route, &r.Method,
+			&r.Submitted, &r.After, &r.TargetType); err != nil {
+			t.Fatal(err)
+		}
+		out = append(out, r)
+	}
+	return out
+}
+
+func (e env) users(t *testing.T) int {
+	t.Helper()
+	var n int
+	if err := e.db.QueryRow(`SELECT COUNT(*) FROM app_user`).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	return n
+}
+
+func problemCode(t *testing.T, rec *httptest.ResponseRecorder) string {
+	t.Helper()
+	var p struct {
+		Code   string
+		Errors []struct{ Field, Code string }
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &p); err != nil {
+		t.Fatal(err)
+	}
+	return p.Code
+}
+
+func TestRegisterSuccess(t *testing.T) {
+	e := newEnv(t)
+	rec := e.register(reg("089290", "  王　小明 ", "  Wang.Xiao@Example.COM ", "Correct-Horse-1"))
+
+	if rec.Code != 201 {
+		t.Fatalf("status %d: %s", rec.Code, rec.Body)
+	}
+	var body map[string]string
+	_ = json.Unmarshal(rec.Body.Bytes(), &body)
+	if len(body) != 3 || body["empNo"] != "089290" || body["name"] != "王 小明" || body["email"] != "wang.xiao@example.com" {
+		t.Errorf("body = %v: want the cleaned values, no password, no id", body)
+	}
+	if rec.Header().Get("Set-Cookie") != "" || rec.Header().Get("Location") != "" {
+		t.Errorf("headers = %v: registration sets no cookie and no Location", rec.Header())
+	}
+
+	var name, email, hash, role string
+	if err := e.db.QueryRow(`SELECT name, email, password_hash, role FROM app_user WHERE emp_no='089290'`).
+		Scan(&name, &email, &hash, &role); err != nil {
+		t.Fatal(err)
+	}
+	if name != "王 小明" || email != "wang.xiao@example.com" || role != "USER" {
+		t.Errorf("stored %q %q %q", name, email, role)
+	}
+	if cost, err := bcrypt.Cost([]byte(hash)); err != nil || cost != 10 {
+		t.Errorf("hash cost %d err %v", cost, err)
+	}
+	if bcrypt.CompareHashAndPassword([]byte(hash), []byte("Correct-Horse-1")) != nil {
+		t.Error("hash does not match the password")
+	}
+
+	rows := e.auditRows(t)
+	if len(rows) != 1 {
+		t.Fatalf("audit rows = %+v", rows)
+	}
+	r := rows[0]
+	if r.Action != "AUTH_REGISTER" || r.Outcome != "SUCCESS" || r.ActorRole != "ANONYMOUS" || r.Status.Int64 != 201 ||
+		r.Route.String != "/api/v1/auth/register" || r.TargetType.String != "USER" {
+		t.Errorf("row = %+v", r)
+	}
+	if strings.Contains(r.After.String, "@") || strings.Contains(r.After.String, "Correct") ||
+		!strings.Contains(r.After.String, "089290") || !strings.Contains(r.After.String, "王 小明") {
+		t.Errorf("after_json = %s: want empNo and name, never email or password", r.After.String)
+	}
+}
+
+func TestRegisterConflicts(t *testing.T) {
+	e := newEnv(t)
+	if rec := e.register(reg("089290", "A", "a@x.com", "pw")); rec.Code != 201 {
+		t.Fatal(rec.Body)
+	}
+
+	cases := []struct {
+		name, body, code, reason string
+	}{
+		{"same employee ID", reg("089290", "B", "b@x.com", "pw"), "EMP_NO_TAKEN", "emp_no_taken"},
+		{"same email, any case", reg("089291", "B", " A@X.COM ", "pw"), "EMAIL_TAKEN", "email_taken"},
+		{"both taken reports the employee ID", reg("089290", "B", "a@x.com", "pw"), "EMP_NO_TAKEN", "emp_no_taken"},
+	}
+	for _, tc := range cases {
+		rec := e.register(tc.body)
+		if rec.Code != 409 || problemCode(t, rec) != tc.code {
+			t.Errorf("%s: %d %s", tc.name, rec.Code, rec.Body)
+		}
+	}
+	if n := e.users(t); n != 1 {
+		t.Errorf("users = %d", n)
+	}
+
+	rows := e.auditRows(t)
+	if len(rows) != 4 {
+		t.Fatalf("audit rows = %+v", rows)
+	}
+	for i, tc := range cases {
+		r := rows[i+1]
+		if r.Action != "AUTH_REGISTER" || r.Outcome != "FAILED" || r.ErrorCode != tc.code || r.Status.Int64 != 409 ||
+			!strings.Contains(r.After.String, `"reason":"`+tc.reason+`"`) {
+			t.Errorf("%s: row = %+v", tc.name, r)
+		}
+	}
+	if rows[1].Submitted.String != "089290" {
+		t.Errorf("submitted = %q", rows[1].Submitted.String)
+	}
+}
+
+func TestRegisterValidationBeatsConflictAndIsAudited(t *testing.T) {
+	e := newEnv(t)
+	e.register(reg("089290", "A", "a@x.com", "pw"))
+
+	// The employee ID is taken, but the email is malformed: 422, never 409.
+	rec := e.register(reg("089290", "B", "a b@x.com", "pw"))
+	if rec.Code != 422 || problemCode(t, rec) != "VALIDATION_FAILED" {
+		t.Fatalf("%d %s", rec.Code, rec.Body)
+	}
+	rec = e.register(reg("12 4", "B/C", "ok@x.com", "pw"))
+	if rec.Code != 422 {
+		t.Fatalf("%d %s", rec.Code, rec.Body)
+	}
+
+	rows := e.auditRows(t)
+	if len(rows) != 3 {
+		t.Fatalf("rows = %+v", rows)
+	}
+	if r := rows[1]; r.Outcome != "FAILED" || r.Status.Int64 != 422 || r.Submitted.String != "089290" ||
+		!strings.Contains(r.After.String, `"empNo":"089290"`) || !strings.Contains(r.After.String, `"reason":"validation"`) {
+		t.Errorf("422 row = %+v", r)
+	}
+	// A malformed employee ID is kept in the submitted column only, not in after_json.
+	if r := rows[2]; r.Submitted.String != "12 4" || strings.Contains(r.After.String, "empNo") {
+		t.Errorf("malformed-ID row = %+v", r)
+	}
+	if e.users(t) != 1 {
+		t.Error("a rejected registration created a user")
+	}
+}
+
+func TestRegisterMalformedIsAuditedButUnsupportedMediaIsNot(t *testing.T) {
+	e := newEnv(t)
+
+	rec := e.register(`{"empNo":"089290"`)
+	if rec.Code != 400 || problemCode(t, rec) != "MALFORMED_REQUEST" {
+		t.Fatalf("%d %s", rec.Code, rec.Body)
+	}
+	req := httptest.NewRequest("POST", "/api/v1/auth/register", strings.NewReader("x"))
+	req.Header.Set("Content-Type", "text/plain")
+	rec = httptest.NewRecorder()
+	e.h.ServeHTTP(rec, req)
+	if rec.Code != 415 {
+		t.Fatalf("%d %s", rec.Code, rec.Body)
+	}
+
+	rows := e.auditRows(t)
+	if len(rows) != 1 || rows[0].Outcome != "FAILED" || rows[0].Status.Int64 != 400 || rows[0].ActorRole != "ANONYMOUS" {
+		t.Fatalf("rows = %+v: only the 400 is audited", rows)
+	}
+}
+
+func TestRegisterRaceHasOneWinner(t *testing.T) {
+	e := newEnv(t)
+	const n = 6
+	codes := make([]int, n)
+	var wg sync.WaitGroup
+	for i := range n {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			codes[i] = e.register(reg("089290", "A", "race"+string(rune('a'+i))+"@x.com", "pw")).Code
+		}()
+	}
+	wg.Wait()
+
+	created, conflicts := 0, 0
+	for _, c := range codes {
+		switch c {
+		case 201:
+			created++
+		case 409:
+			conflicts++
+		}
+	}
+	if created != 1 || conflicts != n-1 || e.users(t) != 1 {
+		t.Fatalf("codes = %v, users = %d", codes, e.users(t))
+	}
+}

package/backend/internal/account/internal/store/store.go

@@ -0,0 +1,35 @@
+// Package store holds the SQL of the account module. Only the account module
+// may import it (Go's internal rule); no other module touches app_user.
+package store
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/google/uuid"
+)
+
+// NewUser is a row to insert. Every value is already validated and cleaned;
+// the table's CHECKs are the second line of defence (V003).
+type NewUser struct {
+	ID           uuid.UUID
+	EmpNo        string
+	Name         string
+	Email        string // lower-cased
+	PasswordHash string // bcrypt, cost 10
+}
+
+// InsertUser inserts a USER in the caller's transaction. A unique-key
+// violation (emp_no or email) is returned as the driver error; the service
+// maps it with db.DuplicateKey.
+func InsertUser(ctx context.Context, tx *sql.Tx, u NewUser) error {
+	_, err := tx.ExecContext(ctx,
+		`INSERT INTO app_user (id, emp_no, name, email, password_hash, role)
+		 VALUES (?, ?, ?, ?, ?, 'USER')`,
+		u.ID.String(), u.EmpNo, u.Name, u.Email, u.PasswordHash)
+	if err != nil {
+		return fmt.Errorf("insert app_user: %w", err)
+	}
+	return nil
+}