docs: add approved task-1 oauth design (D1-D13)

[knockknock10]

Adds the approved Task 1 OAuth design document (decisions D1-D13, flow, endpoint contract, file changes, failure analysis, testing plan, docs updates, out-of-scope list).

[Copilot]

Pull request overview

Adds an approved design document for “Task 1 — GitHub OAuth Login (End-to-End)”, covering decisions (D1–D13), flow, endpoint contract, failure analysis, testing plan, and scoped implementation file changes.

Changes:

• Introduces the full Task 1 OAuth final design write-up (status, decisions, and sequence flow).
• Documents endpoint contracts for /auth/github/login, /auth/github/callback, and /users/me.
• Captures prerequisites/security gate, failure modes, and a testing/verification plan.

Suppressed comments (3)

task-1-oauth-design.md:15

• The text says "verified in repo" and then cites paths like internal/auth/service.go and cmd/server/main.go. In this docs repo those paths don't exist; clarify the target repo/directory and avoid hard-coded line ranges that will drift.

Users cannot authenticate. Current state (verified in repo):

- `GET /auth/github/login` redirects to GitHub, but `RedirectURL` points to `/auth/github/callback`, which has **no route** (404).
- OAuth `state` is hardcoded `"aevor-state"` (`internal/auth/service.go:17-20`) — a CSRF hole.
- `internal/auth/jwt.go` and `internal/auth/middleware.go` are empty — no JWT, no auth middleware.

task-1-oauth-design.md:17

• This bullet references cmd/server/main.go:50, but the design doc doesn't scope paths to a specific repo and hard-coded line numbers are brittle. Prefer a scoped path without line numbers.

- User creation is an unauthenticated `POST /users` (`cmd/server/main.go:50`) — anyone can create arbitrary users.
- `GET /users/:id` and `GET /users/github/:id` are unauthenticated — enumeration risk.

task-1-oauth-design.md:33

• This docs repo doesn't contain a go.mod, so "Go toolchain per go.mod (1.26.1)" is ambiguous. Scope it to the API service's go.mod (or drop the explicit version if it isn't guaranteed).

4. Go toolchain per `go.mod` (1.26.1).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.