151 lines
6.1 KiB
Markdown
151 lines
6.1 KiB
Markdown
# Configurable Mock API with Admin Interface - Project Plan
|
|
|
|
## Architecture Decisions (from @architect)
|
|
|
|
### Technology Stack
|
|
- **Framework**: FastAPI (over Flask) for automatic API documentation, async support, type safety.
|
|
- **Server**: Waitress as production WSGI server.
|
|
- **Database**: SQLite with SQLAlchemy ORM, aiosqlite for async.
|
|
- **Template Engine**: Jinja2 with sandboxed environment.
|
|
- **Admin UI**: Custom Jinja2 templates with Bootstrap 5 CDN, session-based authentication.
|
|
|
|
### Database Schema
|
|
- **endpoints** table: id, route (VARCHAR), method (VARCHAR), response_body (TEXT), response_code (INTEGER), content_type (VARCHAR), is_active (BOOLEAN), variables (JSON), headers (JSON), delay_ms (INTEGER), created_at, updated_at.
|
|
- Unique constraint on (route, method).
|
|
|
|
### Application Architecture
|
|
- Repository-Service-Controller pattern with Observer pattern for dynamic route updates.
|
|
- Modules: database, models, repositories, services, controllers, observers, schemas, middleware, utils.
|
|
|
|
### Dynamic Route Registration
|
|
- RouteManager service registers/unregisters endpoints at runtime via FastAPI's `add_api_route`.
|
|
- Observer pattern triggers route refresh on CRUD operations.
|
|
|
|
### Template Variable Rendering
|
|
- Variable sources: path params, query params, request headers, request body, system variables, endpoint defaults.
|
|
- Jinja2 with StrictUndefined to prevent silent failures.
|
|
|
|
### Admin Interface
|
|
- Simple credential store (admin username/password hash from env vars).
|
|
- Session-based authentication with middleware protecting `/admin/*` routes.
|
|
- Pages: Login, Dashboard, Endpoint List, Endpoint Editor, Request Logs (optional).
|
|
|
|
## Project Structure
|
|
```
|
|
mock_api_app/ # Align with user request
|
|
├── app.py
|
|
├── config.py
|
|
├── database.py
|
|
├── dependencies.py
|
|
├── middleware/
|
|
├── models/
|
|
├── repositories/
|
|
├── services/
|
|
├── controllers/
|
|
├── observers/
|
|
├── schemas/
|
|
├── static/
|
|
├── templates/
|
|
├── utils/
|
|
├── requirements.txt
|
|
├── README.md
|
|
└── .env.example
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
### Phase 1: Foundation
|
|
- [x] Create project directory and structure
|
|
- [x] Set up SQLAlchemy model `Endpoint`
|
|
- [x] Configure FastAPI app with Jinja2 templates
|
|
- [x] Write `requirements.txt`
|
|
|
|
### Phase 2: Core Services
|
|
- [x] Implement `EndpointRepository`
|
|
- [x] Implement `RouteManager` service
|
|
- [x] Implement `TemplateService` with variable resolution
|
|
|
|
### Phase 3: Admin Interface
|
|
- [x] Authentication middleware
|
|
- [x] Admin controller routes
|
|
- [x] HTML templates (Bootstrap 5 CDN)
|
|
|
|
### Phase 4: Integration
|
|
- [x] Connect route observer
|
|
- [x] Add request logging (optional)
|
|
- [x] Health check endpoints
|
|
|
|
### Phase 5: Production Ready
|
|
- [x] Waitress configuration
|
|
- [x] Environment variable configuration
|
|
- [x] Comprehensive README
|
|
|
|
### Phase 6: OAuth2 Provider Implementation
|
|
#### 6.1 Database & Models
|
|
- [x] Extend Endpoint model with `requires_oauth` and `oauth_scopes` columns
|
|
- [x] Create OAuth models: OAuthClient, OAuthToken, OAuthUser
|
|
- [x] Implement database migrations with foreign key support
|
|
|
|
#### 6.2 Repositories & Schemas
|
|
- [x] Create OAuth repository classes (OAuthClientRepository, OAuthTokenRepository, OAuthUserRepository)
|
|
- [x] Create Pydantic schemas for OAuth entities with validation
|
|
|
|
#### 6.3 Services
|
|
- [x] TokenService: JWT generation/validation with database revocation checking
|
|
- [x] OAuthService: Grant flow strategies (authorization_code, client_credentials, refresh_token)
|
|
- [x] ClientService: Client validation with bcrypt secret verification
|
|
- [x] ScopeService: Scope validation and checking
|
|
- [x] Update RouteManager to check OAuth2 token validation
|
|
|
|
#### 6.4 Controllers (Current Phase)
|
|
- [ ] OAuth2 endpoint controllers (/oauth/authorize, /oauth/token, /oauth/userinfo)
|
|
- [ ] Admin OAuth2 management controllers (clients, tokens, users)
|
|
- [ ] HTML templates for OAuth2 admin pages
|
|
|
|
#### 6.5 Configuration & Integration
|
|
- [ ] Update config.py with OAuth2 settings
|
|
- [ ] Update app.py to include OAuth2 routers
|
|
- [ ] Integrate OAuth2 protection into existing admin authentication
|
|
|
|
#### 6.6 Testing
|
|
- [ ] Unit tests for OAuth2 services and repositories
|
|
- [ ] Integration tests for OAuth2 flows
|
|
- [ ] End-to-end tests with protected endpoints
|
|
|
|
## Dependencies
|
|
See `requirements.txt` in architect spec.
|
|
|
|
## Security Considerations
|
|
- Template sandboxing
|
|
- SQL injection prevention via ORM
|
|
- Admin authentication with bcrypt
|
|
- Route validation to prevent path traversal
|
|
- OAuth2 security: client secret hashing, token revocation, scope validation, PKCE support (future)
|
|
|
|
## Status Log
|
|
- 2025-03-13: Architectural specification completed by @architect.
|
|
- 2025-03-13: Project plan created.
|
|
- 2026-03-14: Project cleanup and optimization completed. All phases implemented. Integration tests passing. Project ready for demonstration/testing.
|
|
- 2026-03-14 (evening): OAuth2 provider implementation started. Phases 6.1-6.3 completed (Database, Models, Repositories, Schemas, Services). Phase 6.4 (Controllers) in progress.
|
|
- 2026-03-14 (later): OAuth2 controllers completed (authorize, token, userinfo, introspection, revocation, OpenID discovery). Admin OAuth2 management routes and templates implemented. Configuration updated. Integration with main app completed.
|
|
- 2026-03-14 (final): Integration tests for OAuth2 flows completed and passing. OAuth2 provider fully functional.
|
|
|
|
## Current Status (2026-03-14)
|
|
- ✅ Phase 1: Foundation completed
|
|
- ✅ Phase 2: Core Services completed
|
|
- ✅ Security fixes applied (critical issues resolved)
|
|
- ✅ Phase 3: Admin Interface completed
|
|
- ✅ Phase 4: Integration completed
|
|
- ✅ Phase 5: Production Ready completed
|
|
- ✅ Phase 6.1: OAuth2 Database & Models completed
|
|
- ✅ Phase 6.2: OAuth2 Repositories & Schemas completed
|
|
- ✅ Phase 6.3: OAuth2 Services completed
|
|
- ✅ Phase 6.4: OAuth2 Controllers completed
|
|
- ✅ Phase 6.5: Configuration & Integration completed
|
|
- ✅ Phase 6.6: Testing completed
|
|
|
|
## Next Steps (Updated 2026-03-16)
|
|
1. ✅ Documentation updated with OAuth2 usage examples and Bruno API collection.
|
|
2. Deploy to production environment (if needed).
|
|
3. Consider adding PKCE support for public clients.
|
|
4. Add more advanced OAuth2 features (e.g., token introspection, JWKS endpoint).
|