diff --git a/docs/architecture.md b/docs/architecture.md index d4e4e7e..638a631 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -23,20 +23,20 @@ Rules: | Layer | Package | Purpose | Status | |-------|---------|---------|--------| | **CLI** | `cmd` | Cobra root command | πŸ›  WIP | -| | `cmd/serve.go` | `mygo serve` β€” wire deps, start HTTP | πŸ›  WIP | +| | `cmd/serve.go` | `mygo serve` β€” wire deps, start HTTP | βœ… | | | `cmd/config.go` | `mygo config` β€” config subcommand | πŸ›  WIP | | | `cmd/status.go` | `mygo status` β€” health check | πŸ›  WIP | -| **Config** | `internal/config` | Viper load (YAML + env + flags) | πŸ›  WIP | +| **Config** | `internal/config` | Viper load (YAML + env + flags), typed Duration config via built-in decode hook | βœ… | | **App** | `internal/app` | Runtime dependency container and build metadata | πŸ›  WIP | -| **HTTP** | `internal/server` | Gin router init, route registration, graceful shutdown | πŸ›  WIP | +| **HTTP** | `internal/server` | Gin router init, route registration (public/protected split), graceful shutdown | βœ… | | | `internal/handler` | HTTP handlers (auth, file, admin, webdav...) | πŸ›  WIP | -| | `internal/middleware` | Gin middleware (logger, cors, auth) | πŸ›  WIP | -| **Business** | `internal/service` | Business logic (auth, file, admin) | πŸ›  WIP | -| | `internal/model` | Domain types (User, File, errors) | πŸ›  WIP | -| **Data** | `internal/repository` | Repository interfaces + GORM implementations | πŸ›  WIP | +| | `internal/middleware` | Gin middleware (logger, jwt, cors, auth) | πŸ›  WIP | +| **Business** | `internal/service` | Business logic: `AuthService` (register, login, refresh, logout, passkey CRUD) | βœ… | +| | `internal/model` | Domain types (User, File, Credential, Session), error codes | βœ… | +| **Data** | `internal/repository` | Repository interfaces + GORM implementations (User, Session, File, Credential) | βœ… | | | `internal/storage` | Storage backend interface + local disk impl | πŸ›  WIP | -| **Util** | `internal/auth` | JWT sign/verify, context helpers | πŸ›  WIP | -| | `internal/api` | Error body helpers | πŸ›  WIP | +| **Util** | `internal/auth` | JWT sign/verify (HS256), token type discrimination (access/refresh), password hashing (bcrypt), app passkey tokens | βœ… | +| | `internal/api` | Unified JSON error response helpers | βœ… | ## API Routes (v0) @@ -76,7 +76,8 @@ Applied to protected groups: auth (JWT validation, inject user into gin.Context) ## Server Responsibilities -- `cmd/serve.go` loads config, creates `app.WebApp`, builds the router, and starts the HTTP server. +- `cmd/serve.go` loads config, calls `app.Bootstrap` to initialize DB + services, builds the router, and starts the HTTP server. - `app.WebApp` carries runtime dependencies and build metadata needed to assemble handlers. -- `internal/server` owns Gin router setup (`router.go`), route registration split into `routes_public.go` and `routes_protected.go`, and HTTP server lifecycle. +- `internal/server` owns Gin router setup (`router.go`), route registration split into `routes_public.go` (public auth) and `routes_protected.go` (JWT-protected account). +- Each route group creates its own handler instance: `routes_public.go` creates `AuthHandler`, `routes_protected.go` creates `AccountHandler` β€” no shared handler state between public and protected routes. - `RunWithGracefulShutdown` stops accepting new requests on termination and gives in-flight requests time to finish. diff --git a/docs/decisions.md b/docs/decisions.md index 679fafa..97574e2 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -48,3 +48,20 @@ - Version is build metadata from `internal/app/version.go`, not a config-file field. - `app.WebApp` is the place to add future services, repositories, storage, and app metadata incrementally. - Request ID middleware is not part of the current foundation; add it only with a logging/tracing/error-correlation design. + +## 2026-04-29: Auth Refinements + +**Context**: Auth layer had three structural weaknesses β€” handler duplication, indistinguishable token types, and fragile config duration parsing. + +**Decisions**: + +| Decision | Guidance | +|----------|----------| +| One handler per route group | `AuthHandler` owns `/auth/*` (public); `AccountHandler` owns `/account/*` (protected). A route group maps 1:1 to a handler type. | +| JWT `type` claim | `Claims.Type` distinguishes access from refresh tokens. Middleware and service enforce the correct type at their respective boundaries. `ParseToken` does no type check β€” it verifies cryptographic validity only. | +| `time.Duration` in config structs | Config fields representing durations use `time.Duration` directly. Viper's built-in `StringToTimeDurationHookFunc` handles stringβ†’Duration conversion at unmarshal time. No accessor methods, no runtime parsing. Invalid values fail at startup via `Load()`. | + +**Consequences**: +- Handlers are independently extensible (caching, rate limiting scoped per handler). +- Refresh tokens cannot authenticate API requests; access tokens cannot be used to issue new token pairs. +- New duration config fields require zero boilerplate β€” declare as `time.Duration` in the struct. diff --git a/docs/development.md b/docs/development.md index 2e6cc43..a3004cf 100644 --- a/docs/development.md +++ b/docs/development.md @@ -26,12 +26,35 @@ go vet ./... go fmt ./... ``` +## Dependencies + +```bash +go mod tidy # after adding/removing imports +``` + ## Config -Server config is in `config.yaml` (symlink to `config.example.yaml` in development environment). +Server config is loaded via viper from `config.yaml` (defaults in `internal/config/load.go`). -``` +```yaml server: host: 0.0.0.0 port: 10086 + +database: + driver: sqlite3 + sqlite: + path: data/mygo.db + +storage: + driver: local + local: + path: data/files + +jwt: + secret: changeme-in-production + access_ttl: 15m + refresh_ttl: 168h ``` + +Environment variables use `MYGO_` prefix with underscore separators: `MYGO_SERVER_PORT=8080`, `MYGO_JWT_SECRET=...` diff --git a/docs/roadmap.md b/docs/roadmap.md index 4da8342..2c35b87 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -4,7 +4,7 @@ | Feature | Status | Notes | |---------|--------|-------| -| CLI config management | βœ… | | +| CLI config management | βœ… | Viper YAML + env + flags, typed Duration config | | JWT authentication | βœ… | access + refresh tokens, refresh token in DB, app passkey support | | Web API foundation | βœ… | WebApp composition, Gin router, graceful shutdown, `GET /api/v1/version` | | File upload/download/manage APIs | πŸ›  WIP | REST API via Gin | @@ -15,7 +15,7 @@ Package-level implementation order (each task includes unit tests): -1. `internal/config` β€” Viper loader, config struct +1. `internal/config` β€” Viper loader, config struct βœ… 2. `internal/app` β€” runtime dependency container βœ… 3. `internal/model` β€” domain types, error codes βœ… 4. `internal/api` β€” error response helpers βœ… @@ -24,7 +24,7 @@ Package-level implementation order (each task includes unit tests): 7. `internal/repository` β€” interfaces + GORM/SQLite impl βœ… 8. `internal/service` β€” auth, file, admin services βœ… (auth done) 9. `internal/middleware` β€” logger, cors, auth βœ… (auth done) -10. `internal/handler` β€” auth, file, admin handlers βœ… (auth done) +10. `internal/handler` β€” auth, account, file, admin handlers πŸ›  (auth + account done) 11. `internal/server` β€” Gin router, route registration, graceful shutdown βœ… 12. `cmd/serve.go`, `cmd/config.go`, `cmd/status.go` βœ… (serve done) 13. Integration tests