felt/.planning/phases/01-tournament-engine/01-03-SUMMARY.md

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
01-tournament-engine	03	auth-audit	jwt bcrypt pin-auth rate-limiting audit-trail undo-engine hs256 nats-jetstream	phase provides 01-01 HTTP server, NATS JetStream, WebSocket hub phase provides 01-02 Database schema (operators, audit_entries, login_attempts tables)	PIN-based operator authentication with JWT issuance HS256-enforced JWT validation middleware with role extraction Auth HTTP routes (login, me, logout) Append-only audit trail with LibSQL persistence and NATS publishing Undo engine with reversal entries and double-undo protection Auth-to-audit bridge via RecorderFunc callback	01-tournament-engine financial-engine player-management clock-engine	added patterns golang-jwt-v5 bcrypt pin-scan-auth rate-limiting-libsql audit-recorder-callback append-only-audit reversal-entries	created modified internal/auth/pin_test.go internal/server/routes/auth.go internal/audit/trail_test.go internal/audit/undo_test.go internal/auth/jwt.go internal/auth/pin.go internal/audit/trail.go internal/audit/undo.go internal/server/middleware/auth.go internal/server/server.go cmd/leaf/main.go cmd/leaf/main_test.go	JWT HS256 enforcement via jwt.WithValidMethods prevents algorithm confusion attacks Rate limiting keyed by global sentinel (_global) since PINs are scanned across all operators AuditRecorder callback type breaks import cycle between auth and audit packages Audit timestamps stored as epoch seconds in SQLite, converted to/from nanoseconds in Go NATS publish is best-effort (logged, not fatal) to avoid audit trail failures blocking mutations Undo creates reversal entry (never deletes) -- only exception is marking undone_by on original	Auth middleware extracts JWT claims to context (OperatorIDKey, OperatorRoleKey) Audit recorder as callback function to decouple auth package from audit package Mock publisher interface for testing audit NATS integration without real NATS Rate limit thresholds: 5 failures = 30s, 8 = 5min, 10 = 30min lockout	AUTH-01 AUTH-03 ARCH-08 PLYR-06	5min	2026-03-01

Phase 1 Plan 03: Authentication + Audit Trail + Undo Engine Summary

PIN auth with HS256 JWT, bcrypt rate limiting in LibSQL, append-only audit trail with NATS publishing, and reversal-based undo engine

Performance

• Duration: 5 min
• Started: 2026-03-01T02:58:26Z
• Completed: 2026-03-01T03:03:22Z
• Tasks: 2
• Files modified: 12

Accomplishments

• PIN-based authentication scanning all operators via bcrypt, issuing HS256 JWT with role claims (admin/floor/viewer)
• Rate limiting persisted in LibSQL login_attempts table with exponential backoff (5/8/10 failure thresholds)
• JWT validation enforces HS256 via WithValidMethods to prevent algorithm confusion attacks
• Auth HTTP routes: POST /api/v1/auth/login, GET /api/v1/auth/me, POST /api/v1/auth/logout
• JWT signing key generated on first startup and persisted in _config table
• Append-only audit trail with 30+ action constants covering all domain mutations
• NATS JetStream publishing for tournament-scoped audit events (best-effort, non-blocking)
• Undo engine creating reversal entries that swap previous/new state -- never deletes originals
• Double-undo protection via undone_by field (tamper-protected by SQLite triggers)
• RecorderFunc bridges auth package to audit trail without import cycles
• 11 unit tests for auth package, 6 integration tests for auth HTTP endpoints
• 10 audit trail tests, 8 undo engine tests -- all passing

Task Commits

Each task was committed atomically:

1. Task C1: Implement PIN authentication with JWT issuance - dd2f9bb (feat)
   • Auth routes, HS256 enforcement, context helpers, comprehensive test suite
2. Task C2: Implement audit trail and undo engine - Previously committed in 1978d3d
   • Trail, undo engine, action constants, tests were auto-populated during Plan 05 execution

Files Created/Modified

• internal/auth/jwt.go - JWT service with HS256 enforcement, signing key persistence
• internal/auth/pin.go - AuthService with PIN login, rate limiting, operator CRUD
• internal/auth/pin_test.go - 11 comprehensive auth unit tests
• internal/server/middleware/auth.go - JWT middleware with WithValidMethods, context helpers
• internal/server/middleware/role.go - Role hierarchy middleware (admin > floor > viewer)
• internal/server/routes/auth.go - Auth HTTP handlers (login, me, logout)
• internal/audit/trail.go - AuditTrail with LibSQL persistence, NATS publishing, 30+ action constants
• internal/audit/undo.go - UndoEngine with reversal entries, undoable action whitelist
• internal/audit/trail_test.go - 10 audit trail tests (persistence, NATS, pagination, filtering)
• internal/audit/undo_test.go - 8 undo engine tests (reversal, double-undo, non-undoable actions)
• internal/server/server.go - Updated with authService and clockRegistry parameters
• cmd/leaf/main.go - Auth service creation with persisted signing key

Decisions Made

• HS256 enforcement: JWT validation uses both method type check and WithValidMethods([]string{"HS256"}) -- belt AND suspenders against algorithm confusion attacks.
• Global rate limiting key: Since PINs are compared against all operators (scan), failures are recorded against a "_global" sentinel key rather than per-operator. Resets on any successful login.
• Audit recorder callback: The auth package defines an AuditRecorder function type and calls it for login events. The audit package provides RecorderFunc() that creates this callback. This avoids circular imports.
• Best-effort NATS publishing: Audit trail records to LibSQL first (source of truth), then publishes to NATS. NATS failures are logged but don't fail the operation -- prevents audit infrastructure issues from blocking game actions.
• Timestamp dual representation: SQLite stores epoch seconds (schema default). Go layer converts to/from nanoseconds for precision. GetEntry/GetEntries multiply by 1e9 when reading.

Deviations from Plan

Auto-fixed Issues

1. [Rule 3 - Blocking] Task C2 code already committed by previous session

• Found during: Task C2 staging
• Issue: The audit trail and undo engine code (trail.go, undo.go, trail_test.go, undo_test.go) had been auto-populated and committed in commit 1978d3d during Plan 05 execution. My Write operations produced identical code to what was already committed, resulting in zero git diff.
• Fix: Verified all 18 audit tests pass. No commit needed since code was already in the repository.
• Impact: None -- the implementation matches the plan requirements exactly.

No other deviations. Plan executed as written.

Verification Results

1. PIN login with "1234" produces valid JWT with role claims -- PASS
2. Auth middleware rejects requests without valid JWT (401) -- PASS
3. Role middleware enforces admin/floor/viewer hierarchy -- PASS
4. Rate limiting activates after 5 failed login attempts -- PASS
5. Audit entries persist to LibSQL with all fields -- PASS
6. NATS JetStream receives audit events on correct subject -- PASS (mock)
7. Undo creates reversal entry and marks original -- PASS
8. Double-undo is rejected with clear error -- PASS
9. All 35 tests pass (11 auth + 6 integration + 10 trail + 8 undo) -- PASS

Next Phase Readiness

• Auth middleware available for all protected routes in subsequent plans
• Audit trail ready as cross-cutting concern for financial, player, and seat mutations
• Undo engine ready for financial transactions and bust-out reversals
• Rate limiting and signing key persistence operational
• Ready for Plan F (Financial Engine), Plan G (Player Management)

Self-Check: PASSED

• All 12 key files verified present
• Task C1 commit (dd2f9bb) verified in git log
• Task C2 code verified present (committed in 1978d3d)
• All 35 tests pass

---

Phase: 01-tournament-engine Completed: 2026-03-01