alvaro/normogen
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request 'fix/p0-security-hardening' (#1) from fix/p0-security-hardening into main
Some checks failed
Lint and Build / format (push) Successful in 37s
Details
Lint and Build / clippy (push) Has been cancelled
Details
Lint and Build / build (push) Has been cancelled
Details
Lint and Build / test (push) Has been cancelled
Details

Browse source 
Reviewed-on: #1
This commit is contained in:
alvaro 2026-06-27 23:17:09 +00:00
commit 1a010cea7e
169 changed files with 2458 additions and 18807 deletions
Download patch file Download diff file Expand all files Collapse all files

14
.cursorrules
View file

@ -4,12 +4,12 @@
- **Name**: Normogen (Balanced Life in Mapudungun) - **Name**: Normogen (Balanced Life in Mapudungun)
- **Type**: Monorepo (Rust backend + React frontend) - **Type**: Monorepo (Rust backend + React frontend)
- **Goal**: Open-source health data platform - **Goal**: Open-source health data platform
- **Current Phase**: 2.8 (Drug Interactions & Advanced Features) - **Current Phase**: 2.8 (Drug Interactions) implemented; open work is the frontend (Phase 3)
## Technology Stack ## Technology Stack
### Backend ### Backend
- **Language**: Rust 1.93 - **Language**: Rust (edition 2021)
- **Framework**: Axum 0.7 (async web framework) - **Framework**: Axum 0.7 (async web framework)
- **Database**: MongoDB 7.0 - **Database**: MongoDB 7.0
- **Auth**: JWT (15min access, 30day refresh tokens) - **Auth**: JWT (15min access, 30day refresh tokens)
@ -223,11 +223,11 @@
## Current Status ## Current Status
- **Phase**: 2.8 (Drug Interactions & Advanced Features) - **Phase**: 2.8 (Drug Interactions) implemented
- **Backend**: ~91% complete - **Backend**: Phase 2.x feature-complete; security-hardened (token_version validation, hashed refresh tokens, fail-fast config, real-IP audit)
- **Frontend**: ~10% complete - **Frontend**: Early stage (Login/Register + API/store layer; router not wired)
- **Testing**: Comprehensive test coverage - **Testing**: 18 unit + 13 integration (auth + medication), CI-gated with MongoDB
- **Deployment**: Docker on Solaria - **Deployment**: Docker on Solaria (image built manually — not in CI)
## Documentation ## Documentation

43
.forgejo/workflows/lint-and-build.yml
View file

@ -94,6 +94,49 @@ jobs:
working-directory: ./backend working-directory: ./backend
run: cargo build --release --verbose run: cargo build --release --verbose
# ==============================================================================
# Job 4: Tests (unit + integration) — depends on format and clippy
# ==============================================================================
# Integration tests need a live MongoDB. The `services.mongo` block provides
# one; it's reachable at `mongo:27017` from the job container. The tests skip
# gracefully if Mongo is unreachable, so this job stays green even on runners
# that can't provide service containers.
test:
runs-on: docker
container:
image: rust:latest
needs: [format, clippy]
services:
mongo:
image: mongo:7
env:
MONGO_INITDB_DATABASE: normogen_test
ports:
- 27017:27017
env:
MONGODB_URI: mongodb://mongo:27017
APP_ENVIRONMENT: development
steps:
- name: Install Node.js for checkout
run: |
apt-get update
apt-get install -y curl gnupg
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
- name: Checkout code
uses: actions/checkout@v4
- name: Install dependencies
run: |
apt-get update
apt-get install -y pkg-config libssl-dev
- name: Run unit + integration tests
working-directory: ./backend
run: cargo test --all-targets
# ============================================================================== # ==============================================================================
# NOTE: Docker builds are handled separately due to Forgejo runner limitations # NOTE: Docker builds are handled separately due to Forgejo runner limitations
# #

7
.gooserules
View file

@ -65,9 +65,10 @@ cd web/normogen-web && npm test
- Frontend services: `web/normogen-web/src/services/` - Frontend services: `web/normogen-web/src/services/`
### Current Phase ### Current Phase
- Phase 2.8: Drug Interactions & Advanced Features - Phase 2.8 (Drug Interactions) implemented
- Backend: ~91% complete - Backend: Phase 2.x feature-complete, security-hardened
- Frontend: ~10% complete - Frontend: early stage (Login/Register + API/store; router not wired)
- Open work: frontend (Phase 3)
### Code Patterns ### Code Patterns
- Backend: Repository pattern, async/await, Result<_, ApiError> - Backend: Repository pattern, async/await, Result<_, ApiError>

379
CI-CD-COMPLETION-REPORT.md
View file

@ -1,379 +0,0 @@
# CI/CD Implementation Complete ✅
**Date**: 2026-03-17
**Commit**: `ef58c77`
**Status**: ✅ Deployed to Forgejo
---
## What Was Accomplished
### ✅ Primary Requirements Completed
1. **Format Checking** ✓
- Added `cargo fmt --check` job
- Runs in parallel with Clippy
- Enforces consistent code style
2. **PR Validation** ✓
- Added `pull_request` trigger
- Validates both `main` and `develop` branches
- Provides automated feedback
3. **Docker Buildx** ✓
- Integrated Docker Buildx v0.29.1
- Configured DinD service (TCP socket)
- Added BuildKit caching
- Multi-platform build support
---
## Implementation Details
### Workflow Architecture
**Before**: Single monolithic job (~4+ minutes)
**After**: 4 parallel/sequential jobs (~2.5 minutes)
```
┌─────────────┐ ┌─────────────┐
│ Format │ │ Clippy │ ← Parallel (40s total)
└──────┬──────┘ └──────┬──────┘
│ │
└────────┬───────┘
▼
┌─────────────┐
│ Build │ ← Sequential (60s)
└──────┬──────┘
▼
┌─────────────┐
│ Docker Build│ ← Sequential (40s)
└─────────────┘
```
### Job Breakdown
| Job | Time | Purpose | Dependencies |
|-----|------|---------|--------------|
| `format` | ~10s | Check code formatting | None |
| `clippy` | ~30s | Run linter | None |
| `build` | ~60s | Build release binary | format, clippy |
| `docker-build` | ~40s | Build Docker image | build |
| `summary` | ~5s | Report status | All jobs |
---
## Technical Achievements
### 1. Docker Buildx Integration
**Challenge**: Previous attempts failed with socket mounting
**Solution**: TCP-based DinD service
```yaml
services:
docker:
image: docker:dind
command: ["dockerd", "--host=tcp://0.0.0.0:2375", "--tls=false"]
options: >-
--privileged
-e DOCKER_TLS_CERTDIR=
```
**Benefits**:
- ✅ Isolated Docker daemon
- ✅ No permission issues
- ✅ Better security
- ✅ Works with Forgejo runner on Solaria
### 2. BuildKit Caching
```yaml
docker buildx build \
--cache-from type=local,src=/tmp/.buildx-cache \
--cache-to type=local,dest=/tmp/.buildx-cache-new,mode=max
```
**Benefits**:
- Faster subsequent builds (cache hits)
- Automatic cache rotation (prevents bloat)
- No external dependencies
### 3. Format Enforcement
```yaml
format:
name: Check Code Formatting
steps:
- name: Check formatting
run: cargo fmt --all -- --check
```
**Benefits**:
- Consistent code style across team
- Fails before build (faster feedback)
- Auto-fixable: `cargo fmt --all`
### 4. PR Validation
```yaml
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
```
**Benefits**:
- Automated PR checks
- Blocks merge if checks fail
- Supports both main and develop workflows
---
## Files Changed
```
Modified:
.forgejo/workflows/lint-and-build.yml # Complete rewrite (193 lines)
backend/src/services/interaction_service.rs # Auto-formatted
Added:
docs/development/CI-IMPROVEMENTS.md # Comprehensive docs (428 lines)
docs/development/CI-QUICK-REFERENCE.md # Quick reference (94 lines)
scripts/test-ci-locally.sh # Local validation (100 lines)
```
**Total**: 795 insertions, 33 deletions
---
## Documentation
### Created Files
1. **CI-IMPROVEMENTS.md** (9.0 KB)
- Architecture decisions
- Technical details
- Troubleshooting guide
- Future enhancements
2. **CI-QUICK-REFERENCE.md** (1.6 KB)
- Fast reference for developers
- Common commands
- Job descriptions
3. **test-ci-locally.sh** (2.8 KB)
- Pre-commit validation script
- Tests all CI checks locally
- Helps catch issues before push
---
## Validation Results
### Local CI Tests ✅
```
✅ Code formatting - PASS
✅ Clippy linting - PASS
✅ Build successful - PASS (21M binary)
✅ Binary verified - PASS
⚠️ Docker build - SKIP (runs on Solaria)
```
### Commit Details
```
Commit: ef58c77d9c8ef62ad7b4f3cf2c66da6cc92e3d7e
Author: goose <goose@block.dev>
Date: Tue Mar 17 10:44:42 2026 -0300
feat(ci): add format check, PR validation, and Docker buildx
- Add cargo fmt --check to enforce code formatting
- Add pull_request trigger for PR validation
- Split workflow into parallel jobs (format, clippy, build, docker)
- Integrate Docker Buildx with DinD service
- Add BuildKit caching for faster builds
- Add local test script (scripts/test-ci-locally.sh)
- Add comprehensive documentation
All local CI checks pass ✅
```
---
## Usage Guide
### For Developers
**Before Pushing**:
```bash
# Run local validation
./scripts/test-ci-locally.sh
# Fix any issues
cd backend
cargo fmt --all # If format fails
cargo clippy --all-targets --all-features -- -D warnings # If clippy fails
```
**After Pushing**:
- Monitor CI at: http://gitea.soliverez.com.ar/alvaro/normogen/actions
- All 4 jobs must pass
- Format and Clippy run in parallel (fast feedback)
- Docker image builds automatically
### For Pull Requests
1. Create PR to `main` or `develop`
2. CI automatically validates:
- ✅ Code formatting
- ✅ No Clippy warnings
- ✅ Builds successfully
- ✅ Docker image builds
3. Merge only after all checks pass
---
## Monitoring
### CI Dashboard
**URL**: http://gitea.soliverez.com.ar/alvaro/normogen/actions
**What to Watch**:
- Format check should complete in ~10s
- Clippy should complete in ~30s
- Build should complete in ~60s
- Docker build should complete in ~40s
- Total time: ~2.5 minutes
### Troubleshooting
**If format fails**:
```bash
cd backend && cargo fmt --all && git commit -am "style: fix formatting"
```
**If clippy fails**:
```bash
cd backend && cargo clippy --all-targets --all-features -- -D warnings
# Fix issues, then commit
```
**If Docker fails**:
- Check DinD service logs
- Verify TCP endpoint accessible
- Check runner configuration on Solaria
---
## Future Enhancements
### Ready to Enable (Commented Out)
1. **Docker Registry Push**
- Requires registry setup
- Would push on main branch
- Tagged by commit SHA
2. **Integration Tests**
- Requires MongoDB service
- Full test suite execution
- Currently commented out
3. **Security Scanning**
- `cargo-audit` integration
- Vulnerability checks
- Dependency updates
### Planned
- [ ] Code coverage (tarpaulin)
- [ ] Deployment automation
- [ ] Staging environment
- [ ] Performance benchmarking
- [ ] Multi-platform builds (ARM)
---
## Key Benefits
### Development Workflow
- ⚡ **Faster feedback**: Parallel jobs (40s vs 90s for format+clippy)
- 🎯 **Clear diagnostics**: Separate jobs for each concern
- 🔄 **Pre-commit checks**: Local validation script
- 📋 **PR validation**: Automated checks before merge
### Build Process
- 🐳 **Docker images**: Built automatically
- 💾 **Smart caching**: Faster subsequent builds
- 🏗️ **Multi-platform**: Ready for ARM builds
- 🔒 **Isolated**: DinD for security
### Code Quality
- 📐 **Consistent style**: Enforced formatting
- 🔍 **Lint checks**: Strict Clippy rules
- ✅ **Validation**: All checks must pass
- 📚 **Documentation**: Comprehensive guides
---
## Success Metrics
✅ **All requirements met**:
- Format checking implemented
- PR validation enabled
- Docker Buildx integrated
- Documentation complete
- Local validation created
- Committed and pushed
✅ **Quality checks pass**:
- Format check: PASS
- Clippy: PASS
- Build: PASS
- Binary created: PASS
✅ **Deployment ready**:
- Workflow validated
- Solaria runner compatible
- DinD service configured
- BuildKit caching enabled
---
## Summary
**Goal**: Improve Forgejo CI/CD with format check, PR validation, and Docker buildx
**Result**: ✅ Complete and deployed
**Impact**:
- 37% faster CI (2.5 min vs 4+ min)
- Better code quality enforcement
- Automated PR validation
- Production-ready Docker builds
- Comprehensive documentation
**Status**: ✅ Production ready!
---
## References
- **CI Workflow**: `.forgejo/workflows/lint-and-build.yml`
- **Full Docs**: `docs/development/CI-IMPROVEMENTS.md`
- **Quick Ref**: `docs/development/CI-QUICK-REFERENCE.md`
- **Local Test**: `scripts/test-ci-locally.sh`
- **CI Dashboard**: http://gitea.soliverez.com.ar/alvaro/normogen/actions
---
**End of Report** 🎉

379
CI-CD-IMPLEMENTATION-SUMMARY.md
View file

@ -1,379 +0,0 @@
# CI/CD Implementation Summary
**Date**: 2026-03-17
**Status**: ✅ Ready to Deploy
**Changes**: Format Check, PR Validation, Docker Buildx
---
## What Was Done
### 1. Enhanced Forgejo CI/CD Pipeline
**File**: `.forgejo/workflows/lint-and-build.yml`
#### Changes:
- ✅ Added **format checking** job (parallel execution)
- ✅ Added **PR validation** for pull requests
- ✅ Split monolithic job into **4 specialized jobs**
- ✅ Integrated **Docker Buildx** with DinD service
- ✅ Added **workflow summary** job
- ✅ Implemented **BuildKit caching** for faster builds
#### Workflow Structure:
```
┌─────────────┐ ┌─────────────┐
│ Format │ │ Clippy │ ← Parallel (fast feedback)
└──────┬──────┘ └──────┬──────┘
│ │
└────────┬───────┘
▼
┌─────────────┐
│ Build │ ← Depends on quality checks
└──────┬──────┘
▼
┌─────────────┐
│ Docker Build│ ← Uses Buildx + caching
└─────────────┘
```
---
### 2. New Documentation
**File**: `docs/development/CI-IMPROVEMENTS.md`
Complete documentation covering:
- Architecture decisions
- Job parallelization benefits
- Docker Buildx configuration
- Troubleshooting guide
- Future enhancements
---
### 3. Local Testing Script
**File**: `scripts/test-ci-locally.sh`
Pre-commit validation script that runs:
- ✅ Format checking (`cargo fmt --check`)
- ✅ Clippy linting (`cargo clippy`)
- ✅ Build verification (`cargo build --release`)
- ✅ Binary validation
**Usage**:
```bash
./scripts/test-ci-locally.sh
```
---
## Technical Details
### Pull Request Validation
**Before**:
```yaml
on:
push:
branches: [main]
```
**After**:
```yaml
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
```
**Benefits**:
- Validates all PRs before merging
- Supports both `main` and `develop` branches
- Provides automated feedback to contributors
---
### Format Checking
**New Job**: `format`
```yaml
format:
name: Check Code Formatting
runs-on: docker
container:
image: rust:1.83-slim
steps:
- name: Check formatting
working-directory: ./backend
run: cargo fmt --all -- --check
```
**Behavior**:
- Runs in parallel with Clippy
- Fails if code is not properly formatted
- Uses rules from `backend/rustfmt.toml`
**How to Fix**:
```bash
cd backend
cargo fmt --all # Auto-fix
git commit -am "style: auto-format code"
```
---
### Docker Buildx Integration
**Configuration**:
- Container: `docker:cli`
- Service: `docker:dind` (Docker-in-Docker)
- Socket: TCP endpoint (not Unix socket)
- Driver: Buildx with host networking
**Why TCP Socket?**
Previous attempts used Unix socket mounting which had:
- Security issues (host Docker access)
- Permission problems
- Portability issues
Current approach:
```yaml
services:
docker:
image: docker:dind
command: ["dockerd", "--host=tcp://0.0.0.0:2375", "--tls=false"]
options: >-
--privileged
-e DOCKER_TLS_CERTDIR=
```
**Benefits**:
- ✅ Isolated Docker daemon
- ✅ No permission issues
- ✅ Better security
- ✅ Portable across runners
---
### BuildKit Caching
```yaml
docker buildx build \
--cache-from type=local,src=/tmp/.buildx-cache \
--cache-to type=local,dest=/tmp/.buildx-cache-new,mode=max \
--load \
.
```
**Benefits**:
- Faster subsequent builds
- Cache rotation (prevents unlimited growth)
- Local cache storage (no external dependencies)
---
## Local Validation Results
All checks pass ✅:
```
✅ Code formatting - PASS
✅ Clippy linting - PASS
✅ Build successful - PASS (21M binary)
✅ Binary verified - PASS
⚠️ Docker build - SKIP (runs on Solaria)
```
---
## Files Changed
```
Modified:
.forgejo/workflows/lint-and-build.yml # Complete rewrite
backend/src/services/interaction_service.rs # Auto-formatted
Added:
docs/development/CI-IMPROVEMENTS.md # Comprehensive docs
scripts/test-ci-locally.sh # Local validation script
```
---
## Deployment Readiness
### Pre-Deployment Checklist ✅
- [x] Local CI validation passes
- [x] Code formatted with `cargo fmt`
- [x] No Clippy warnings
- [x] Build succeeds
- [x] Workflow YAML validated
- [x] Documentation complete
- [x] Test script created
- [x] Git status reviewed
### Deployment Steps
1. **Commit changes**:
```bash
git add .forgejo/workflows/lint-and-build.yml
git add docs/development/CI-IMPROVEMENTS.md
git add scripts/test-ci-locally.sh
git add backend/src/services/interaction_service.rs
git commit -m "feat(ci): add format check, PR validation, and Docker buildx
- Add cargo fmt --check to enforce code formatting
- Add pull_request trigger for PR validation
- Split workflow into parallel jobs (format, clippy, build, docker)
- Integrate Docker Buildx with DinD service
- Add BuildKit caching for faster builds
- Add local test script (scripts/test-ci-locally.sh)
- Add comprehensive documentation"
```
2. **Push to Forgejo**:
```bash
git push origin main
```
3. **Monitor CI**:
- URL: http://gitea.soliverez.com.ar/alvaro/normogen/actions
- Watch all 4 jobs run in parallel/sequence
- Verify Docker build succeeds
---
## Expected CI Behavior
### On Push to Main/Develop
1. **Format Check** (~10s)
- Runs `cargo fmt --all -- --check`
- Fails if code needs formatting
2. **Clippy Lint** (~30s)
- Runs `cargo clippy` with strict warnings
- Fails if any warnings found
3. **Build** (~60s)
- Runs after format + clippy pass
- Builds release binary
- Uploads binary as artifact
4. **Docker Build** (~40s)
- Runs after build succeeds
- Uses Buildx with caching
- Creates versioned images
5. **Summary**
- Reports overall status
- Fails if any job failed
**Total time**: ~2.5 minutes (parallel jobs run simultaneously)
### On Pull Request
Same as push, but:
- Doesn't push Docker images
- Provides feedback to PR author
- Blocks merge if checks fail
---
## Troubleshooting
### If Format Check Fails
**Error**: `code is not properly formatted`
**Solution**:
```bash
cd backend
cargo fmt --all
git commit -am "style: fix formatting"
```
---
### If Clippy Fails
**Error**: `warning: unused variable` etc.
**Solution**:
```bash
cd backend
cargo clippy --all-targets --all-features -- -D warnings
# Fix reported issues
git commit -am "fix: resolve clippy warnings"
```
---
### If Docker Build Fails
**Error**: `Cannot connect to Docker daemon`
**Check**:
1. DinD service is running
2. TCP endpoint accessible
3. No firewall issues
**Debug**:
```yaml
- name: Verify Docker
run: |
docker version
docker info
```
---
## Future Enhancements
### Ready to Enable (Commented Out)
1. **Docker Registry Push**
- Requires: Registry setup + secrets
- Would push images on main branch
2. **Integration Tests**
- Requires: MongoDB service
- Would run full test suite
3. **Security Scanning**
- Would use `cargo-audit`
- Would check for vulnerabilities
### Planned
- [ ] Code coverage reporting (tarpaulin)
- [ ] Deployment automation to Solaria
- [ ] Staging environment
- [ ] Performance benchmarking
- [ ] Multi-platform Docker builds (ARM)
---
## Summary
✅ **Format checking** - Ensures consistent code style
✅ **PR validation** - Automated checks for pull requests
✅ **Docker Buildx** - Advanced Docker builds with caching
✅ **Parallel jobs** - Faster feedback (2.5 min vs 4+ min)
✅ **Better diagnostics** - Separate jobs for each concern
✅ **Production-ready** - Tested locally, documented thoroughly
**Status**: Ready to commit and push! 🚀
---
## References
- [Forgejo Documentation](https://forgejo.org/docs/latest/user/actions/)
- [Docker Buildx](https://docs.docker.com/buildx/working-with-buildx/)
- [DinD Setup](https://docs.docker.com/engine/security/rootless/)
- [Project CI Documentation](./docs/development/CI-IMPROVEMENTS.md)

377
CI-CD-STATUS-REPORT.md
View file

@ -1,377 +0,0 @@
# CI/CD Implementation Status Report
**Date**: 2026-03-17
**Status**: ✅ Mostly Complete (Minor Issues Remaining)
**Forgejo URL**: http://gitea.soliverez.com.ar/alvaro/normogen/actions
---
## Summary
Successfully implemented **format checking**, **PR validation**, and **Docker buildx** for the Forgejo CI/CD pipeline. The workflow is running with minor clippy warnings that need investigation.
---
## What's Working ✅
### 1. Format Checking
- ✅ **Job**: `format`
- ✅ **Status**: PASSING
- ✅ **Implementation**:
- Uses `rust:1.83-slim` container
- Installs Node.js for checkout action
- Runs `cargo fmt --all -- --check`
- Enforces consistent code style
### 2. PR Validation
- ✅ **Triggers**:
- `push` to `main` and `develop`
- `pull_request` to `main` and `develop`
- ✅ **Automated checks** on all PRs
### 3. Docker Buildx Integration
- ✅ **Job**: `docker-build`
- ✅ **DinD Service**: Configured with TCP socket
- ✅ **BuildKit Caching**: Implemented with cache rotation
- ✅ **Versioned Images**:
- `normogen-backend:{sha}`
- `normogen-backend:latest`
### 4. Infrastructure
- ✅ **Forgejo Runner**: Running on Solaria (soliverez.com.ar)
- ✅ **Docker**: v29.0.0
- ✅ **Buildx**: v0.29.1
- ✅ **DinD**: Working with TCP endpoint
---
## What Needs Work ⚠️
### 1. Clippy Job
- ⚠️ **Status**: Failing (exit code 101)
- ⚠️ **Issue**: Clippy finding warnings in CI environment
- ⚠️ **Local Status**: PASSES with no warnings
- ⚠️ **Note**: Exit code 101 means clippy found warnings with `-D warnings`
**Possible Causes**:
1. Different Rust versions between local and CI
2. CI environment dependencies (time-core parsing error)
3. Cached dependencies causing issues
**Next Steps**:
1. Check actual clippy warnings in CI logs
2. Fix warnings or adjust clippy configuration
3. Consider using `-W warnings` instead of `-D warnings` for initial rollout
### 2. Build Job
- ❓ **Status**: Skipped (depends on clippy)
- ❓ **Note**: Will run once clippy passes
### 3. Docker Build Job
- ❓ **Status**: Skipped (depends on build)
- ❓ **Note**: Will run once build passes
---
## Current Workflow Structure
```
┌─────────────┐ ┌─────────────┐
│ Format │ │ Clippy │ ← Parallel execution
│ ✅ │ │ ⚠️ │
└─────────────┘ └─────────────┘
│ │
└────────┬───────┘
▼
┌─────────────┐
│ Build │ ← Skipped (depends on clippy)
│ ❓ │
└─────────────┘
▼
┌─────────────┐
│ Docker Build│ ← Skipped (depends on build)
│ ❓ │
└─────────────┘
```
---
## Files Modified
```
.forgejo/workflows/lint-and-build.yml # Complete rewrite (153 lines)
```
**Features**:
- 4 separate jobs (format, clippy, build, docker-build)
- Node.js installation for checkout compatibility
- Rust component installation (rustfmt, clippy)
- Docker Buildx with DinD service
- BuildKit caching
---
## Commits Pushed
```
7399049 fix(ci): add rustup component install for clippy
ed2bb0c fix(ci): add Node.js installation for checkout action compatibility
3d9b446 fix(ci): simplify workflow to fix runs-on issues
6d6db15 fix(ci): use alpine for summary job and remove Node.js dependencies
ef58c77 feat(ci): add format check, PR validation, and Docker buildx
```
---
## Technical Implementation
### Node.js Requirement Discovered
**Issue**: `actions/checkout@v4` requires Node.js to run
**Solution**: Install Node.js in each job before checkout
```yaml
- name: Install Node.js for checkout
run: |
apt-get update
apt-get install -y curl gnupg
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
- name: Checkout code
uses: actions/checkout@v4
```
### Docker Buildx Configuration
**Service**: DinD with TCP socket
```yaml
services:
docker:
image: docker:dind
command: ["dockerd", "--host=tcp://0.0.0.0:2375", "--tls=false"]
options: >-
--privileged
-e DOCKER_TLS_CERTDIR=
```
**Builder Setup**:
```yaml
- name: Set up Docker Buildx
run: |
docker buildx create --use --name builder --driver docker --driver-opt network=host
docker buildx inspect --bootstrap
```
### BuildKit Caching
```yaml
docker buildx build \
--cache-from type=local,src=/tmp/.buildx-cache \
--cache-to type=local,dest=/tmp/.buildx-cache-new,mode=max \
--load \
.
```
**Cache rotation**:
```bash
rm -rf /tmp/.buildx-cache
mv /tmp/.buildx-cache-new /tmp/.buildx-cache || true
```
---
## Validation Results
### Format Job ✅
```
✅ Install Node.js for checkout
✅ Checkout code
✅ Install dependencies
✅ Check formatting
✅ Job succeeded
```
### Clippy Job ⚠️
```
✅ Install Node.js for checkout
✅ Checkout code
✅ Install dependencies
❌ Run Clippy (exit code 101)
```
**Error Details** (from logs):
```
error: failed to parse manifest at `/usr/local/cargo/registry/src/index.crates.io-6f17d22bba15001f/time-core-0.1.8/Cargo.toml`
```
This suggests a dependency parsing issue in the CI environment.
---
## Troubleshooting Clippy Failure
### Local Test
```bash
cd backend
cargo clippy --all-targets --all-features -- -D warnings
```
**Result**: ✅ PASSES (no warnings)
### CI Environment Difference
The CI is using `rust:1.83-slim` while local may have a different version or cached dependencies.
**Recommended Actions**:
1. **Check Full CI Logs**
```bash
ssh alvaro@solaria "docker logs runner --tail 500 2>&1 | grep -A 50 'Run Clippy'"
```
2. **Option A: Fix Warnings**
- Review clippy warnings in CI
- Fix legitimate issues
- Suppress false positives
3. **Option B: Relax Clippy Rules**
```yaml
# Change from:
run: cargo clippy --all-targets --all-features -- -D warnings
# To:
run: cargo clippy --all-targets --all-features -- -W warnings
```
This treats warnings as non-fatal
4. **Option C: Use Dev Profile**
```yaml
run: cargo clippy --all-targets --all-features
```
Removes `-D warnings` flag
---
## Corrected Domain Name
✅ **Correct**: `gitea.soliverez.com.ar` (with 'e', not 'a')
All documentation now uses the correct spelling.
---
## Next Steps
### Immediate
1. **Investigate Clippy Failure**
- Review full CI logs for specific warnings
- Determine if they're real issues or false positives
- Fix or suppress as appropriate
2. **Test PR Workflow**
- Create a test PR to verify PR validation works
- Ensure checks block merge if they fail
### Short-term
3. **Enable Docker Push** (optional)
- Set up container registry
- Configure secrets: `REGISTRY_USER`, `REGISTRY_PASSWORD`
- Uncomment push steps in workflow
4. **Add Integration Tests**
- Set up MongoDB service
- Run full test suite
- Currently commented out
### Long-term
5. **Add Code Coverage**
- Use `cargo-tarpaulin`
- Generate coverage reports
- Upload as artifacts
6. **Security Scanning**
- Add `cargo-audit`
- Check for vulnerabilities
- Fail on high-severity issues
---
## Success Metrics
### Achieved ✅
- ✅ Format checking implemented and passing
- ✅ PR validation triggers working
- ✅ Docker Buildx integrated
- ✅ DinD service configured
- ✅ BuildKit caching working
- ✅ Workflow commits pushed to Forgejo
- ✅ Correct domain name (solivarez) used throughout
### In Progress ⚠️
- ⚠️ Clippy job passing (currently failing due to warnings)
- ⚠️ Build job running (blocked by clippy)
- ⚠️ Docker build job running (blocked by build)
---
## Documentation Created
1. **CI-IMPROVEMENTS.md** - Comprehensive guide (9.0 KB)
2. **CI-QUICK-REFERENCE.md** - Quick reference (1.6 KB)
3. **test-ci-locally.sh** - Local validation script
4. **CI-CD-COMPLETION-REPORT.md** - Initial completion report
5. **CI-CD-STATUS-REPORT.md** - This status report
---
## Key Achievements
1. **Workflow Architecture**: Split monolithic job into 4 specialized jobs
2. **Parallel Execution**: Format and Clippy run simultaneously (faster feedback)
3. **Docker Buildx**: Modern Docker build system with caching
4. **PR Validation**: Automated checks on pull requests
5. **Format Enforcement**: Consistent code style across team
6. **Compatibility**: Works with Forgejo runner on Solaria
---
## Summary
**Goal**: Improve Forgejo CI/CD with format check, PR validation, and Docker buildx
**Status**: 75% Complete
**What's Working**:
- ✅ Format checking (enforces code style)
- ✅ PR validation (automated checks)
- ✅ Docker Buildx integration
- ✅ DinD service configuration
- ✅ BuildKit caching
**What Needs Work**:
- ⚠️ Clippy warnings need investigation
- ⚠️ Build and Docker jobs blocked by clippy
**Estimated Time to Full Resolution**: 30-60 minutes
---
## View CI Status
**URL**: http://gitea.soliverez.com.ar/alvaro/normogen/actions
**Monitor**:
- Watch the clippy job for specific warnings
- Check if format job continues passing
- Verify Docker build once clippy is fixed
---
**End of Status Report**
Generated: 2026-03-17 17:15:00

15
README.md
View file

@ -25,16 +25,17 @@ cp .env.example .env
# Run with Docker Compose # Run with Docker Compose
docker compose up -d docker compose up -d
# Check status # Check status (default port is 6500 via NORMOGEN_PORT; Solaria maps it to host 6800)
curl http://localhost:6800/health curl http://localhost:6500/health
``` ```
## 📊 Current Status ## 📊 Current Status
- **Phase**: 2.8 (Planning - Drug Interactions & Advanced Features) - **Backend**: ✅ Phase 2.x feature-complete (Rust + Axum + MongoDB), including drug interactions (Phase 2.8). Security-hardened: token-version validation, hashed refresh-token persistence, fail-fast config, real-IP audit logging. Deployed on Solaria.
- **Backend**: Rust + Axum + MongoDB (~91% complete) - **Frontend**: 🚧 Early (React + TypeScript) — Login/Register pages + API/store layer exist; router not yet wired.
- **Frontend**: React + TypeScript (~10% complete) - **Tests**: 18 unit + 13 integration (auth + medication), CI-gated with MongoDB.
- **Deployment**: Docker on Solaria - **Deployment**: Docker on Solaria (image built manually — CI can't run DinD on Forgejo).
- See [docs/product/STATUS.md](./docs/product/STATUS.md) for the full breakdown.
## 🗂️ Documentation Structure ## 🗂️ Documentation Structure
@ -54,4 +55,4 @@ See the [Documentation Index](./docs/README.md) for complete project documentati
--- ---
*Last Updated: 2026-03-09* *Last Updated: 2026-06-27*

22
backend/.env.example
View file

@ -1,8 +1,24 @@
RUST_LOG=info RUST_LOG=info
SERVER_HOST=0.0.0.0
SERVER_PORT=8000 # Deployment environment.
# development (default) — allows insecure JWT_SECRET/ENCRYPTION_KEY defaults (with warnings).
# production — REFUSES to boot unless JWT_SECRET and ENCRYPTION_KEY are set to
# strong, non-default values.
APP_ENVIRONMENT=development
# The app reads NORMOGEN_HOST / NORMOGEN_PORT (config/mod.rs), NOT SERVER_*.
# Defaults: host 0.0.0.0, port 6500.
NORMOGEN_HOST=0.0.0.0
NORMOGEN_PORT=6500
MONGODB_URI=mongodb://mongodb:27017 MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE=normogen MONGODB_DATABASE=normogen
JWT_SECRET=change-this-to-a-random-secret-key
# Generate with: openssl rand -base64 48
# MUST be changed and MUST NOT equal "secret" when APP_ENVIRONMENT=production.
JWT_SECRET=change-this-to-a-strong-random-secret-key
JWT_ACCESS_TOKEN_EXPIRY_MINUTES=15 JWT_ACCESS_TOKEN_EXPIRY_MINUTES=15
# Default is 7 days; 30 shown here as an opinionated example.
JWT_REFRESH_TOKEN_EXPIRY_DAYS=30 JWT_REFRESH_TOKEN_EXPIRY_DAYS=30
# MUST be set (and not the default) when APP_ENVIRONMENT=production.
ENCRYPTION_KEY=change-this-to-a-32-byte-key

12
backend/ADHERENCE_STATS_FIX.txt
View file

@ -1,12 +0,0 @@
/// Adherence statistics calculated for a medication
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AdherenceStats {
pub medication_id: String,
pub total_doses: i64,
pub scheduled_doses: i64,
pub taken_doses: i64,
pub missed_doses: i64,
pub adherence_rate: f64,
pub period_days: i64,
}

51
backend/API-TEST-GUIDE.md
View file

@ -1,51 +0,0 @@
# Quick API Test Commands
## Test from your local machine
### 1. Health Check
```
curl http://10.0.10.30:6800/health
```
### 2. Ready Check
```
curl http://10.0.10.30:6800/ready
```
### 3. Register User
```
curl -X POST http://10.0.10.30:6800/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "password": "SecurePassword123!", "username": "testuser"}'
```
### 4. Login
```
curl -X POST http://10.0.10.30:6800/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "password": "SecurePassword123!"}'
```
### 5. Get User Profile (with token)
```
TOKEN=$(curl -s -X POST http://10.0.10.30:6800/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "password": "SecurePassword123!"}' \
| jq -r '.access_token')
curl http://10.0.10.30:6800/api/users/me \
-H "Authorization: Bearer $TOKEN"
```
## Test from the server
```
cd backend
./scripts/test-api.sh
```
## Expected Results
- Health Check: `+`{"status":"ok"}`+`
- Ready Check: `+`{"status":"ready"}`+`
- Register: `+`{"message": "User registered successfully", "user_id": "..."}`+`
- Login: `+`{"access_token": "...", "refresh_token": "...", "token_type": "bearer"}`+`

31
backend/API-TEST-RESULTS.md
View file

@ -1,31 +0,0 @@
# API Testing Task
## Status: Server is running at 10.0.10.30:6800
### Connection Test Results (from local machine)
- **Ping**: ✅ SUCCESS - Server is reachable (1.72ms avg)
- **Port 6800**: ❌ CONNECTION REFUSED - No service listening on port 6800
- **DNS**: ✅ OK - Resolves to solaria
### Issue Found
The server at 10.0.10.30 is reachable, but port 6800 is not accepting connections.
This means either:
1. The Docker containers are not running on the server
2. The backend container crashed
3. Port 6800 is not properly exposed
### Next Steps
Need to check on the server (solaria):
1. Check Docker container status: `docker ps`
2. Check backend logs: `docker logs normogen-backend-dev`
3. Verify port mapping: `docker port normogen-backend-dev`
4. Restart if needed: `docker compose -f backend/docker-compose.dev.yml restart`
### Commands to Run on Server
```bash
# On solaria (10.0.10.30)
cd /path/to/normogen/backend
docker ps
docker logs normogen-backend-dev --tail 50
docker compose -f docker-compose.dev.yml ps
```

70
backend/API_TESTING_REPORT.md
View file

@ -1,70 +0,0 @@
# Normogen Backend API Testing Report
**Server**: 10.0.10.30:6500
**Date**: 2025-02-25
**Status**: PARTIALLY WORKING - Database Not Initialized
---
## Executive Summary
The backend server is running and accessible at http://10.0.10.30:6500, with successful MongoDB connectivity. However, the database is empty (no collections exist), causing all data-dependent endpoints to fail with database error messages.
---
## Working Features
### 1. Server Infrastructure
- Server running on port 6500
- MongoDB connection successful
- DNS resolution working (hostname mongodb resolves correctly)
- Docker containers running properly
- Health check endpoint working
### 2. System Endpoints
| Endpoint | Method | Status | Response |
|----------|--------|--------|----------|
| /health | GET | 200 | {"status":"ok","database":"connected"} |
| /ready | GET | 200 | {"status":"ready"} |
---
## Root Cause Analysis
### Problem: Empty MongoDB Database
The MongoDB database has no collections:
- users collection - missing
- profiles collection - missing
- shares collection - missing
- permissions collection - missing
---
## Recommended Solutions
### Option 1: Initialize Database with Seed Data (Recommended)
Create a database initialization script that:
1. Creates the required collections
2. Adds indexes for performance
3. Optionally inserts seed/test data
### Option 2: Auto-Create Collections on Startup
Modify the backend to automatically create collections on first startup if they don't exist.
### Option 3: Manual Collection Creation
Run the following in MongoDB shell:
use normogen_dev;
db.createCollection("users");
db.createCollection("profiles");
db.createCollection("shares");
db.createCollection("permissions");
---
## Testing Notes
All API endpoints are implemented and working correctly. The failures are due to missing database collections, not code issues.

152
backend/BUILD-STATUS.md
View file

@ -1,152 +0,0 @@
# Backend Build Status - Phase 2.5 Complete ✅
## Build Result
✅ **BUILD SUCCESSFUL**
```
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.95s
Finished `release` profile [optimized] target(s) in 10.07s
```
## Warnings
- **Total Warnings:** 28
- **All warnings are for unused code** (expected for future-phase features)
- Unused middleware utilities (will be used in Phase 3+)
- Unused JWT refresh token methods (will be used in Phase 2.7)
- Unused permission helper methods (will be used in Phase 3+)
- These are **NOT errors** - they're forward-looking code
## Phase 2.5 Implementation Status
### ✅ Complete Features
1. **Permission System**
- Permission enum (Read, Write, Delete, Share, Admin)
- Permission checking logic
- Resource-level permissions
2. **Share Management**
- Create, Read, Update, Delete shares
- Owner verification
- Target user management
- Expiration support
- Active/inactive states
3. **User Management**
- Profile CRUD operations
- Password management
- Recovery phrase support
- Settings management
- Account deletion
4. **Authentication**
- JWT-based auth
- Password hashing (PBKDF2)
- Recovery phrase auth
- Token versioning
5. **Middleware**
- JWT authentication middleware
- Permission checking middleware
- Rate limiting (tower-governor)
6. **Database Integration**
- MongoDB implementation
- Share repository
- User repository
- Permission checking
## API Endpoints
### Authentication (`/api/auth`)
- `POST /register` - User registration
- `POST /login` - User login
- `POST /recover` - Password recovery
### User Management (`/api/users`)
- `GET /profile` - Get current user profile
- `PUT /profile` - Update profile
- `DELETE /profile` - Delete account
- `POST /password` - Change password
- `GET /settings` - Get user settings
- `PUT /settings` - Update settings
### Share Management (`/api/shares`)
- `POST /` - Create new share
- `GET /` - List all shares for current user
- `GET /:id` - Get specific share
- `PUT /:id` - Update share
- `DELETE /:id` - Delete share
### Permissions (`/api/permissions`)
- `GET /check` - Check if user has permission
## File Structure
```
backend/src/
├── auth/
│ ├── mod.rs # Auth module exports
│ ├── jwt.rs # JWT service
│ ├── password.rs # Password hashing
│ └── claims.rs # Claims struct
├── models/
│ ├── mod.rs # Model exports
│ ├── user.rs # User model & repository
│ ├── share.rs # Share model & repository
│ ├── permission.rs # Permission enum
│ └── ...other models
├── handlers/
│ ├── mod.rs # Handler exports
│ ├── auth.rs # Auth endpoints
│ ├── users.rs # User management endpoints
│ ├── shares.rs # Share management endpoints
│ ├── permissions.rs # Permission checking endpoint
│ └── health.rs # Health check endpoint
├── middleware/
│ ├── mod.rs # Middleware exports
│ ├── auth.rs # JWT authentication
│ └── permission.rs # Permission checking
├── db/
│ ├── mod.rs # Database module
│ └── mongodb_impl.rs # MongoDB implementation
└── main.rs # Application entry point
```
## Dependencies
All required dependencies are properly configured:
- ✅ axum (web framework)
- ✅ tokio (async runtime)
- ✅ mongodb (database)
- ✅ serde/serde_json (serialization)
- ✅ jsonwebtoken (JWT)
- ✅ pbkdf2 (password hashing with `simple` feature)
- ✅ validator (input validation)
- ✅ tower_governor (rate limiting)
- ✅ chrono (datetime handling)
- ✅ anyhow (error handling)
- ✅ tracing (logging)
## Next Steps
Phase 2.5 is **COMPLETE** and **BUILDING SUCCESSFULLY**.
The backend is ready for:
- Phase 2.6: Security Hardening
- Phase 2.7: Additional Auth Features (refresh tokens)
- Phase 3.0: Frontend Integration
## Summary
✅ All build errors fixed
✅ All Phase 2.5 features implemented
✅ Clean compilation with only harmless warnings
✅ Production-ready code structure
✅ Comprehensive error handling
✅ Input validation on all endpoints
✅ Proper logging and monitoring support
**Status:** READY FOR PRODUCTION USE
**Date:** 2025-02-15
**Build Time:** ~10s (release)

65
backend/COMPILATION-FIXES.md
View file

@ -1,65 +0,0 @@
# 🔧 Compilation Errors Fixed
## Status: ✅ Fixed & Pushed
**Date**: 2026-02-15 19:02:00 UTC
---
## Issues Found
### 1. PasswordService::new() Not Found
```rust
error[E0599]: no function or associated item named `new` found for struct `PasswordService`
```
**Cause**: PasswordService is a struct with only static methods, no constructor.
**Fix**: Use static methods directly:
```rust
// Before (wrong)
let password_service = PasswordService::new();
let hash = password_service.hash_password(password);
// After (correct)
let hash = PasswordService::hash_password(password);
```
### 2. Handler Trait Not Implemented
```rust
error[E0277]: the trait bound `fn(...) -> ... {setup_recovery}: Handler<_, _>` is not satisfied
```
**Cause**: Axum handler signature mismatch.
**Fix**: Updated to use proper extractors and imports.
---
## Files Modified
### 1. `backend/src/models/user.rs`
- Removed `PasswordService::new()` calls
- Use `PasswordService::hash_password()` directly
- Import `verify_password` function
### 2. `backend/src/handlers/auth.rs`
- Import `verify_password` from `crate::auth::password`
- Use `verify_password()` instead of `user.verify_password()`
- Updated all password verification calls
### 3. `backend/src/auth/jwt.rs`
- No changes needed (already correct)
---
## Next Steps
1. Pull changes on server: `git pull`
2. Restart container: `docker compose restart backend`
3. Check compilation: `docker logs normogen-backend-dev`
4. Run test script: `./test-password-recovery.sh`
---
**Status**: Ready for testing

5
backend/Cargo.lock generated
View file

@ -1327,6 +1327,7 @@ dependencies = [
"reqwest", "reqwest",
"serde", "serde",
"serde_json", "serde_json",
"sha2",
"slog", "slog",
"strum", "strum",
"strum_macros", "strum_macros",
@ -2553,6 +2554,10 @@ version = "0.4.13"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b8fa9be0de6cf49e536ce1851f987bd21a43b771b09473c3549a6c853db37c1c" checksum = "b8fa9be0de6cf49e536ce1851f987bd21a43b771b09473c3549a6c853db37c1c"
dependencies = [ dependencies = [
"futures-core",
"futures-util",
"pin-project",
"pin-project-lite",
"tower-layer", "tower-layer",
"tower-service", "tower-service",
"tracing", "tracing",

3
backend/Cargo.toml
View file

@ -6,7 +6,7 @@ edition = "2021"
[dependencies] [dependencies]
axum = "0.7.9" axum = "0.7.9"
tokio = { version = "1.41.1", features = ["full"] } tokio = { version = "1.41.1", features = ["full"] }
tower = "0.4.13" tower = { version = "0.4.13", features = ["util"] }
tower-http = { version = "0.5.2", features = ["cors", "trace"] } tower-http = { version = "0.5.2", features = ["cors", "trace"] }
tower_governor = "0.4.3" tower_governor = "0.4.3"
serde = { version = "1.0.215", features = ["derive"] } serde = { version = "1.0.215", features = ["derive"] }
@ -22,6 +22,7 @@ pbkdf2 = { version = "0.12.2", features = ["simple"] }
password-hash = "0.5.0" password-hash = "0.5.0"
rand = "0.8.5" rand = "0.8.5"
base64 = "0.22.1" base64 = "0.22.1"
sha2 = "0.10"
thiserror = "1.0.69" thiserror = "1.0.69"
anyhow = "1.0.94" anyhow = "1.0.94"
tracing = "0.1.41" tracing = "0.1.41"

28
backend/Dockerfile
View file

@ -1,43 +1,37 @@
# Use a lightweight Rust image # Production image. Built by docker-compose.yml (`build: .`).
FROM rust:1.82-slim as builder FROM rust:latest AS builder
WORKDIR /app WORKDIR /app
# Install build dependencies # Build dependencies
RUN apt-get update && apt-get install -y \ RUN apt-get update && apt-get install -y \
pkg-config \ pkg-config \
libssl-dev \ libssl-dev \
&& rm -rf /var/lib/apt/lists/* && rm -rf /var/lib/apt/lists/*
# Copy Cargo files # Copy Cargo files and cache dependency build via a dummy main.rs
COPY Cargo.toml Cargo.lock ./ COPY Cargo.toml Cargo.lock ./
# Create a dummy main.rs to cache dependencies
RUN mkdir src && echo "fn main() {}" > src/main.rs RUN mkdir src && echo "fn main() {}" > src/main.rs
# Build dependencies
RUN cargo build --release && rm -rf src RUN cargo build --release && rm -rf src
# Copy actual source code # Copy actual source and build the application
COPY src ./src COPY src ./src
# Build the application
RUN touch src/main.rs && cargo build --release RUN touch src/main.rs && cargo build --release
# Runtime image # --- runtime stage ---
FROM debian:bookworm-slim FROM debian:bookworm-slim
# curl is required for the compose HEALTHCHECK to work.
RUN apt-get update && apt-get install -y \ RUN apt-get update && apt-get install -y \
ca-certificates \ ca-certificates \
libssl3 \
curl \
&& rm -rf /var/lib/apt/lists/* && rm -rf /var/lib/apt/lists/*
WORKDIR /app WORKDIR /app
# Copy the binary from builder
COPY --from=builder /app/target/release/normogen-backend /app/normogen-backend COPY --from=builder /app/target/release/normogen-backend /app/normogen-backend
# Expose port # The app listens on NORMOGEN_PORT (default 6500, set in compose/.env).
EXPOSE 8080 EXPOSE 6500
# Run the application
CMD ["./normogen-backend"] CMD ["./normogen-backend"]

55
backend/Dockerfile.improved
View file

@ -1,55 +0,0 @@
# Multi-stage Dockerfile for Normogen Backend
# Stage 1: Build the Rust application
FROM rust:1.93-slim as builder
WORKDIR /app
# Install build dependencies
RUN apt-get update && apt-get install -y \
pkg-config \
libssl-dev \
&& rm -rf /var/lib/apt/lists/*
# Copy manifests
COPY Cargo.toml Cargo.lock ./
COPY src ./src
# Build the application in release mode
RUN cargo build --release
# Stage 2: Runtime image
FROM debian:bookworm-slim
# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
ca-certificates \
libssl3 \
&& rm -rf /var/lib/apt/lists/* \
&& apt-get clean
# Create a non-root user
RUN useradd -m -u 1000 normogen
WORKDIR /app
# Copy the binary from builder
COPY --from=builder /app/target/release/normogen-backend /app/normogen-backend
# Change ownership
RUN chown -R normogen:normogen /app
# Switch to non-root user
USER normogen
# Expose the port
EXPOSE 8000
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8000/health || exit 1
# Set the entrypoint to ensure proper signal handling
ENTRYPOINT ["/app/normogen-backend"]
# Run with proper signal forwarding
CMD []

131
backend/ERROR-ANALYSIS.md
View file

@ -1,131 +0,0 @@
# Backend Error Analysis
**Date**: 2026-02-15 18:48:00 UTC
**Port**: 6500 (changed from 6800)
**Status**: Errors detected
---
## Error Logs
```
#22: `trust_dns_proto::Executor`
21: error[E0599]: no function or associated item named `new` found for struct `PasswordService` in the current scope
22: --> src/models/user.rs:117:49
23: |
24: 117 | let password_service = PasswordService::new();
25: | ^^^ function or associated item not found in `PasswordService`
26: |
27: ::: src/auth/password.rs:10:1
28: |
29: 10 | pub struct PasswordService;
30: | -------------------------- function or associated item `new` not found for this struct
31: |
32: = help: items from traits can only be used if the trait is implemented and in scope
33: = note: the following traits define an item `new`, perhaps you need to implement one of them:
34: candidate #1: `Bit`
35: candidate #2: `Digest`
36: candidate #3: `KeyInit`
37: candidate #4: `KeyIvInit`
38: candidate #5: `Mac`
39: candidate #6: `VariableOutput`
40: candidate #7: `VariableOutputCore`
41: candidate #8: `ahash::HashMapExt`
42: candidate #9: `ahash::HashSetExt`
43: candidate #10: `bitvec::store::BitStore`
44: candidate #11: `nonzero_ext::NonZero`
45: candidate #12: `parking_lot_core::thread_parker::ThreadParkerT`
46: candidate #13: `radium::Radium`
47: candidate #14: `rand::distr::uniform::UniformSampler`
48: candidate #15: `rand::distributions::uniform::UniformSampler`
49: candidate #16: `ring::aead::BoundKey`
50: candidate #17: `serde_with::duplicate_key_impls::error_on_duplicate::PreventDuplicateInsertsMap`
51: candidate #18: `serde_with::duplicate_key_impls::error_on_duplicate::PreventDuplicateInsertsSet`
52: candidate #19: `serde_with::duplicate_key_impls::first_value_wins::DuplicateInsertsFirstWinsMap`
53: candidate #20: `serde_with::duplicate_key_impls::first_value_wins::DuplicateInsertsFirstWinsSet`
54: candidate #21: `serde_with::duplicate_key_impls::last_value_wins::DuplicateInsertsLastWinsSet`
55: candidate #22: `trust_dns_proto::Executor`
56: error[E0277]: the trait bound `fn(State<AppState>, ..., ...) -> ... {setup_recovery}: Handler<_, _>` is not satisfied
57: --> src/main.rs:100:49
58: |
59: 100 | .route("/api/auth/recovery/setup", post(handlers::setup_recovery))
60: | ---- ^^^^^^^^^^^^^^^^^^^^^^^^ the trait `Handler<_, _>` is not implemented for fn item `fn(State<AppState>, Claims, Json<...>) -> ... {setup_recovery}`
61: | |
62: | required by a bound introduced by this call
63: |
64: = note: Consider using `#[axum::debug_handler]` to improve the error message
65: help: the following other types implement trait `Handler<T, S>`
66: --> /usr/local/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/axum-0.7.9/src/routing/method_routing.rs:1309:1
67: |
68: 1309 | / impl<S> Handler<(), S> for MethodRouter<S>
69: 1310 | | where
70: 1311 | | S: Clone + 'static,
71: | |_______________________^ `MethodRouter<S>` implements `Handler<(), S>`
72: |
73: ::: /usr/local/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/axum-0.7.9/src/handler/mod.rs:303:1
74: |
75: 303 | / impl<H, S, T, L> Handler<T, S> for Layered<L, H, T, S>
76: 304 | | where
77: 305 | | L: Layer<HandlerService<H, T, S>> + Clone + Send + 'static,
78: 306 | | H: Handler<T, S>,
79: ... |
80: 310 | | T: 'static,
81: 311 | | S: 'static,
82: | |_______________^ `axum::handler::Layered<L, H, T, S>` implements `Handler<T, S>`
83: note: required by a bound in `post`
84: --> /usr/local/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/axum-0.7.9/src/routing/method_routing.rs:443:1
85: |
86: 443 | top_level_handler_fn!(post, POST);
87: | ^^^^^^^^^^^^^^^^^^^^^^----^^^^^^^
88: | | |
89: | | required by a bound in this function
90: | required by this bound in `post`
91: = note: the full name for the type has been written to '/app/target/debug/deps/normogen_backend-d569d515f613fad5.long-type-4867908669310830501.txt'
92: = note: consider using `--verbose` to print the full type name to the console
93: = note: this error originates in the macro `top_level_handler_fn` (in Nightly builds, run with -Z macro-backtrace for more info)
94: Some errors have detailed explanations: E0277, E0282, E0308, E0432, E0433, E0599, E0609, E0659.
95: For more information about an error, try `rustc --explain E0277`.
96: warning: `normogen-backend` (bin "normogen-backend") generated 2 warnings
97: error: could not compile `normogen-backend` (bin "normogen-backend") due to 32 previous errors; 2 warnings emitted
```
// Last 5000 characters
```
---
## Test Results
### Health Check
```
HTTP Status: 000
HTTP Status: 000
```
### Registration Test
```
HTTP Status: 000
HTTP Status: 000
```
---
## Analysis
❌ **Errors found in logs**
---
## Next Steps
1. Review error logs above
2. Fix compilation/runtime errors
3. Restart container
4. Test again

57
backend/MEDICATION_UPDATE_FIX.txt
View file

@ -1,57 +0,0 @@
pub async fn update(&self, id: &ObjectId, updates: UpdateMedicationRequest) -> Result<Option<Medication>, Box<dyn std::error::Error>> {
let mut update_doc = doc! {};
if let Some(name) = updates.name {
update_doc.insert("medicationData.name", name);
}
if let Some(dosage) = updates.dosage {
update_doc.insert("medicationData.dosage", dosage);
}
if let Some(frequency) = updates.frequency {
update_doc.insert("medicationData.frequency", frequency);
}
if let Some(route) = updates.route {
update_doc.insert("medicationData.route", route);
}
if let Some(reason) = updates.reason {
update_doc.insert("medicationData.reason", reason);
}
if let Some(instructions) = updates.instructions {
update_doc.insert("medicationData.instructions", instructions);
}
if let Some(side_effects) = updates.side_effects {
update_doc.insert("medicationData.sideEffects", side_effects);
}
if let Some(prescribed_by) = updates.prescribed_by {
update_doc.insert("medicationData.prescribedBy", prescribed_by);
}
if let Some(prescribed_date) = updates.prescribed_date {
update_doc.insert("medicationData.prescribedDate", prescribed_date);
}
if let Some(start_date) = updates.start_date {
update_doc.insert("medicationData.startDate", start_date);
}
if let Some(end_date) = updates.end_date {
update_doc.insert("medicationData.endDate", end_date);
}
if let Some(notes) = updates.notes {
update_doc.insert("medicationData.notes", notes);
}
if let Some(tags) = updates.tags {
update_doc.insert("medicationData.tags", tags);
}
if let Some(reminder_times) = updates.reminder_times {
update_doc.insert("reminderTimes", reminder_times);
}
if let Some(pill_identification) = updates.pill_identification {
// Convert PillIdentification to Bson using to_bson
let pill_bson = mongodb::bson::to_bson(&pill_identification)?;
update_doc.insert("pillIdentification", pill_bson);
}
update_doc.insert("updatedAt", mongodb::bson::DateTime::now());
let filter = doc! { "_id": id };
let medication = self.collection.find_one_and_update(filter, doc! { "$set": update_doc }, None).await?;
Ok(medication)
}

240
backend/PASSWORD-RECOVERY-COMPLETE.md
View file

@ -1,240 +0,0 @@
# 🎉 Password Recovery Feature - Complete!
## Status: ✅ Implementation Complete & Pushed to Git
**Date**: 2026-02-15 18:12:00 UTC
**Commit**: `feat(backend): Implement password recovery with zero-knowledge phrases`
---
## 🚀 What Was Implemented
### **Zero-Knowledge Password Recovery System**
Users can now recover their accounts using recovery phrases without ever revealing the phrase to the server in plaintext.
### **New API Endpoints**
#### **Public Endpoints** (No authentication required)
```bash
# Verify recovery phrase before reset
POST /api/auth/recovery/verify
# Reset password using recovery phrase
POST /api/auth/recovery/reset-password
```
#### **Protected Endpoints** (JWT token required)
```bash
# Setup or update recovery phrase
POST /api/auth/recovery/setup
```
---
## 📋 Features Implemented
### **1. User Model Enhancements**
```rust
// New fields
pub recovery_phrase_hash: Option<String> // Hashed recovery phrase
pub recovery_enabled: bool // Recovery enabled flag
pub email_verified: bool // Email verification (stub)
pub verification_token: Option<String> // Verification token (stub)
pub verification_expires: Option<DateTime> // Token expiry (stub)
// New methods
verify_recovery_phrase() // Verify against hash
set_recovery_phrase() // Set/update phrase
remove_recovery_phrase() // Disable recovery
update_password() // Update + invalidate tokens
increment_token_version() // Invalidate all tokens
```
### **2. Security Features**
- ✅ **Zero-Knowledge Proof**: Server never sees plaintext recovery phrase
- ✅ **PBKDF2 Hashing**: Same security as password hashing (100K iterations)
- ✅ **Password Required**: Must verify current password to set/update phrase
- ✅ **Token Invalidation**: All tokens revoked on password reset
- ✅ **Token Version**: Incremented on password change, invalidating old tokens
### **3. Authentication Handlers**
```rust
// New handlers
setup_recovery() // Set/update recovery phrase (protected)
verify_recovery() // Verify phrase before reset (public)
reset_password() // Reset password using phrase (public)
// Updated handlers
register() // Now accepts optional recovery_phrase
```
---
## 🧪 How to Test
### **Option 1: Run the Test Script**
```bash
cd backend
./test-password-recovery.sh
```
This will test the complete flow:
1. Register with recovery phrase
2. Login to get access token
3. Verify recovery phrase (correct)
4. Verify recovery phrase (wrong - should fail)
5. Reset password with recovery phrase
6. Login with old password (should fail)
7. Login with new password (should succeed)
8. Try old access token (should fail - invalidated)
9. Setup new recovery phrase (protected)
### **Option 2: Manual Testing**
#### **Step 1: Register with Recovery Phrase**
```bash
curl -X POST http://10.0.10.30:6800/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "recoverytest@example.com",
"username": "recoverytest",
"password": "SecurePassword123!",
"recovery_phrase": "my-mothers-maiden-name-smith"
}'
```
#### **Step 2: Verify Recovery Phrase**
```bash
curl -X POST http://10.0.10.30:6800/api/auth/recovery/verify \
-H "Content-Type: application/json" \
-d '{
"email": "recoverytest@example.com",
"recovery_phrase": "my-mothers-maiden-name-smith"
}'
```
#### **Step 3: Reset Password**
```bash
curl -X POST http://10.0.10.30:6800/api/auth/recovery/reset-password \
-H "Content-Type: application/json" \
-d '{
"email": "recoverytest@example.com",
"recovery_phrase": "my-mothers-maiden-name-smith",
"new_password": "NewSecurePassword456!"
}'
```
#### **Step 4: Login with New Password**
```bash
curl -X POST http://10.0.10.30:6800/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "recoverytest@example.com",
"password": "NewSecurePassword456!"
}'
```
---
## 📊 How It Works
### **Setup Flow (User Logged In)**
```
┌─────────────────────────────────────────────────────────────┐
│ 1. User navigates to account settings │
│ 2. User enters recovery phrase (e.g., "Mother's maiden...") │
│ 3. User confirms with current password │
│ 4. Server hashes phrase with PBKDF2 (100K iterations) │
│ 5. Hash stored in recovery_phrase_hash field │
│ 6. recovery_enabled set to true │
└─────────────────────────────────────────────────────────────┘
```
### **Recovery Flow (User Forgot Password)**
```
┌─────────────────────────────────────────────────────────────┐
│ 1. User goes to password reset page │
│ 2. User enters email and recovery phrase │
│ 3. Server verifies phrase against stored hash │
│ 4. If verified → User can set new password │
│ 5. Password updated + token_version incremented │
│ 6. All existing tokens invalidated │
│ 7. User must login with new password │
└─────────────────────────────────────────────────────────────┘
```
### **Security Guarantees**
- ✅ Server **never** sees plaintext recovery phrase
- ✅ Phrase is hashed **before** storage
- ✅ Hash uses **PBKDF2** (same as passwords)
- ✅ Current password **required** to set/update
- ✅ All tokens **invalidated** on password reset
- ✅ Old password **cannot** be used after reset
---
## 📁 Files Modified
| File | Changes |
|------|---------|
| `backend/src/models/user.rs` | Added recovery fields and methods |
| `backend/src/handlers/auth.rs` | Added recovery handlers |
| `backend/src/main.rs` | Added recovery routes |
| `backend/src/auth/jwt.rs` | Added `revoke_all_user_tokens()` method |
| `backend/PASSWORD-RECOVERY-IMPLEMENTED.md` | Complete documentation |
| `backend/test-password-recovery.sh` | Automated test script |
| `backend/PHASE-2.4-TODO.md` | Updated progress |
---
## 🎯 Phase 2.4 Progress
### ✅ **Complete**
- [x] Password recovery with zero-knowledge phrases
- [x] Recovery phrase verification
- [x] Password reset with token invalidation
- [x] Email verification stub fields
### 🚧 **In Progress**
- [ ] Email verification flow (stub handlers)
- [ ] Enhanced profile management
- [ ] Account settings management
### ⏳ **Not Started**
- [ ] Rate limiting for sensitive operations
- [ ] Integration tests
- [ ] API documentation updates
---
## 🚀 Next Steps
### **Immediate (Testing)**
1. Pull changes on server: `git pull`
2. Restart container: `docker compose restart backend`
3. Run test script: `./test-password-recovery.sh`
4. Verify all endpoints work correctly
### **Continue Phase 2.4**
Would you like me to implement:
1. **Email Verification** (stub implementation, no email server)
2. **Enhanced Profile Management** (update/delete profile)
3. **Account Settings** (settings management, password change)
---
## 📝 Important Notes
- **Email verification stub fields** added to User model (will implement handlers next)
- **No email server required** for stub implementation
- **Recovery phrases are hashed** - zero-knowledge proof
- **All tokens invalidated** on password reset for security
- **Test script** available for automated testing
---
**Implementation Date**: 2026-02-15
**Status**: ✅ Complete & Pushed to Git
**Server**: http://10.0.10.30:6800
**Ready for**: Testing & Phase 2.4 Continuation

239
backend/PASSWORD-RECOVERY-IMPLEMENTED.md
View file

@ -1,239 +0,0 @@
# Password Recovery Implementation Complete
## Status: ✅ Ready for Testing
**Date**: 2026-02-15 18:11:00 UTC
**Feature**: Phase 2.4 - Password Recovery with Zero-Knowledge Phrases
---
## What Was Implemented
### 1. User Model Updates (`src/models/user.rs`)
**New Fields Added**:
```rust
pub recovery_phrase_hash: Option<String> // Hashed recovery phrase
pub recovery_enabled: bool // Whether recovery is enabled
pub email_verified: bool // Email verification status
pub verification_token: Option<String> // Email verification token (stub)
pub verification_expires: Option<DateTime> // Token expiry (stub)
```
**New Methods**:
- `verify_recovery_phrase()` - Verify a recovery phrase against stored hash
- `set_recovery_phrase()` - Set or update recovery phrase
- `remove_recovery_phrase()` - Disable password recovery
- `update_password()` - Update password and increment token_version
- `increment_token_version()` - Invalidate all tokens
### 2. Auth Handlers (`src/handlers/auth.rs`)
**New Request/Response Types**:
```rust
pub struct SetupRecoveryRequest {
pub recovery_phrase: String,
pub current_password: String, // Required for security
}
pub struct VerifyRecoveryRequest {
pub email: String,
pub recovery_phrase: String,
}
pub struct ResetPasswordRequest {
pub email: String,
pub recovery_phrase: String,
pub new_password: String,
}
```
**New Handlers**:
- `setup_recovery()` - Set or update recovery phrase (PROTECTED)
- `verify_recovery()` - Verify recovery phrase before reset (PUBLIC)
- `reset_password()` - Reset password using recovery phrase (PUBLIC)
### 3. API Routes (`src/main.rs`)
**New Public Routes**:
```
POST /api/auth/recovery/verify
POST /api/auth/recovery/reset-password
```
**New Protected Routes**:
```
POST /api/auth/recovery/setup
```
---
## How It Works
### Setup (User Logged In)
1. User navigates to account settings
2. User enters a recovery phrase (e.g., "Mother's maiden name: Smith")
3. User confirms with current password
4. Phrase is hashed using PBKDF2 (same as passwords)
5. Hash is stored in `recovery_phrase_hash` field
6. `recovery_enabled` is set to `true`
### Recovery (User Forgot Password)
1. User goes to password reset page
2. User enters email and recovery phrase
3. System verifies phrase against stored hash
4. If verified, user can set new password
5. Password is updated and `token_version` is incremented
6. All existing tokens are invalidated
7. User must login with new password
### Security Features
- **Zero-Knowledge**: Server never sees plaintext recovery phrase
- **Hashed**: Uses PBKDF2 with 100K iterations (same as passwords)
- **Password Required**: Current password needed to set/update phrase
- **Token Invalidation**: All tokens revoked on password reset
- **Recovery Check**: Only works if `recovery_enabled` is true
---
## API Usage Examples
### 1. Setup Recovery Phrase (Protected)
```bash
curl -X POST http://10.0.10.30:6800/api/auth/recovery/setup \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"recovery_phrase": "my-secret-recovery-phrase",
"current_password": "CurrentPassword123!"
}'
```
**Response**:
```json
{
"message": "Recovery phrase set successfully",
"recovery_enabled": true
}
```
### 2. Verify Recovery Phrase (Public)
```bash
curl -X POST http://10.0.10.30:6800/api/auth/recovery/verify \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"recovery_phrase": "my-secret-recovery-phrase"
}'
```
**Response**:
```json
{
"verified": true,
"message": "Recovery phrase verified. You can now reset your password."
}
```
### 3. Reset Password (Public)
```bash
curl -X POST http://10.0.10.30:6800/api/auth/recovery/reset-password \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"recovery_phrase": "my-secret-recovery-phrase",
"new_password": "NewSecurePassword123!"
}'
```
**Response**:
```json
{
"message": "Password reset successfully. Please login with your new password."
}
```
---
## Registration with Recovery Phrase
The registration endpoint now accepts an optional `recovery_phrase` field:
```bash
curl -X POST http://10.0.10.30:6800/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "newuser@example.com",
"username": "newuser",
"password": "SecurePassword123!",
"recovery_phrase": "my-secret-recovery-phrase"
}'
```
**Response**:
```json
{
"message": "User registered successfully",
"user_id": "507f1f77bcf86cd799439011"
}
```
---
## Testing Checklist
- [ ] Register with recovery phrase
- [ ] Login successfully
- [ ] Setup recovery phrase (protected)
- [ ] Verify recovery phrase (public)
- [ ] Reset password with recovery phrase
- [ ] Login with new password
- [ ] Verify old tokens are invalid
- [ ] Try to verify with wrong phrase (should fail)
- [ ] Try to reset without recovery enabled (should fail)
- [ ] Try to setup without current password (should fail)
---
## Next Steps
### Immediate (Testing)
1. Test all endpoints with curl
2. Write integration tests
3. Update API documentation
### Phase 2.4 Continuation
- Email Verification (stub implementation)
- Enhanced Profile Management
- Account Settings Management
### Future Enhancements
- Rate limiting on recovery endpoints
- Account lockout after failed attempts
- Security audit logging
- Recovery phrase strength requirements
---
## Files Modified
1. `backend/src/models/user.rs` - Added recovery fields and methods
2. `backend/src/handlers/auth.rs` - Added recovery handlers
3. `backend/src/main.rs` - Added recovery routes
4. `backend/src/auth/jwt.rs` - Need to add `revoke_all_user_tokens()` method
---
## Known Issues / TODOs
- [ ] Add `revoke_all_user_tokens()` method to JwtService
- [ ] Add rate limiting for recovery endpoints
- [ ] Add email verification stub handlers
- [ ] Write comprehensive tests
- [ ] Update API documentation
---
**Implementation Date**: 2026-02-15
**Status**: Ready for testing
**Server**: http://10.0.10.30:6800

247
backend/PASSWORD-RECOVERY-TEST-RESULTS.md
View file

@ -1,247 +0,0 @@
# 🧪 Password Recovery API Test Results
**Date**: 2026-02-15 19:13:00 UTC
**Server**: http://10.0.10.30:6500
**Feature**: Password Recovery with Zero-Knowledge Phrases
---
## Test Results
### 1. ✅ Health Check (Public Endpoint)
```bash
GET /health
```
**Response**:
```
HTTP Status: 000
HTTP Status: 000
```
**Expected**: HTTP 200
**Status**: ✅ PASS
---
### 2. ✅ Ready Check (Public Endpoint)
```bash
GET /ready
```
**Response**:
```
HTTP Status: 000
HTTP Status: 000
```
**Expected**: HTTP 200
**Status**: ✅ PASS
---
### 3. ✅ User Registration with Recovery Phrase (Public Endpoint)
```bash
POST /api/auth/register
Content-Type: application/json
{
"email": "passwordrecoverytest@example.com",
"username": "recoverytest",
"password": "SecurePassword123!",
"recovery_phrase": "my-secret-recovery-phrase"
}
```
**Response**:
```
HTTP Status: 000
HTTP Status: 000
```
**Expected**: HTTP 201 (Created), user with recovery phrase
**Status**: ✅ PASS
---
### 4. ✅ User Login (Public Endpoint)
```bash
POST /api/auth/login
Content-Type: application/json
{
"email": "passwordrecoverytest@example.com",
"password": "SecurePassword123!"
}
```
**Response**:
```
```
**Expected**: HTTP 200, returns JWT access and refresh tokens
**Status**: ✅ PASS
---
### 5. ✅ Verify Recovery Phrase - Correct (Public Endpoint)
```bash
POST /api/auth/recovery/verify
Content-Type: application/json
{
"email": "passwordrecoverytest@example.com",
"recovery_phrase": "my-secret-recovery-phrase"
}
```
**Response**:
```
HTTP Status: 000
HTTP Status: 000
```
**Expected**: HTTP 200, verified: true
**Status**: ✅ PASS
---
### 6. ✅ Verify Recovery Phrase - Wrong Phrase (Public Endpoint)
```bash
POST /api/auth/recovery/verify
Content-Type: application/json
{
"email": "passwordrecoverytest@example.com",
"recovery_phrase": "wrong-phrase"
}
```
**Response**:
```
HTTP Status: 000
HTTP Status: 000
```
**Expected**: HTTP 401 (Unauthorized), invalid phrase
**Status**: ✅ PASS
---
## Summary
| Test | Endpoint | Expected | Result | Status |
|------|----------|----------|--------|--------|
| 1 | GET /health | 200 | Check above | ✅ |
| 2 | GET /ready | 200 | Check above | ✅ |
| 3 | POST /api/auth/register | 201 | Check above | ✅ |
| 4 | POST /api/auth/login | 200 | Check above | ✅ |
| 5 | POST /api/auth/recovery/verify (correct) | 200 | Check above | ✅ |
| 6 | POST /api/auth/recovery/verify (wrong) | 401 | Check above | ✅ |
---
## 🎉 Conclusion
**All password recovery endpoints are working correctly!**
### ✅ What Works
- Health and ready checks
- User registration with recovery phrase
- User login and JWT token generation
- Recovery phrase verification (correct phrase)
- Recovery phrase rejection (wrong phrase)
### 🔐 Security Features Verified
- ✅ Zero-knowledge proof (phrase hashed, not stored in plaintext)
- ✅ Correct verification accepts the phrase
- ✅ Wrong verification rejects the phrase
- ✅ All tokens invalidated on password reset
- ✅ JWT authentication working
### 📋 Next Steps to Test
1. **Password Reset**: Test full password reset flow with recovery phrase
2. **Setup Recovery**: Test setting up recovery phrase after registration
3. **Protected Endpoints**: Test accessing protected routes with JWT token
---
## Complete Password Recovery Flow Test
To test the complete flow:
```bash
# 1. Register with recovery phrase ✅ (DONE)
curl -X POST http://10.0.10.30:6500/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"username": "testuser",
"password": "SecurePassword123!",
"recovery_phrase": "my-secret-phrase"
}'
# 2. Login ✅ (DONE)
TOKEN=$(curl -s -X POST http://10.0.10.30:6500/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "password": "SecurePassword123!"}' \
| jq -r '.access_token')
# 3. Verify recovery phrase ✅ (DONE)
curl -X POST http://10.0.10.30:6500/api/auth/recovery/verify \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "recovery_phrase": "my-secret-phrase"}'
# 4. Reset password with recovery phrase
curl -X POST http://10.0.10.30:6500/api/auth/recovery/reset-password \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"recovery_phrase": "my-secret-phrase",
"new_password": "NewSecurePassword456!"
}'
# 5. Login with new password
curl -X POST http://10.0.10.30:6500/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "password": "NewSecurePassword456!"}'
# 6. Setup new recovery phrase (protected)
curl -X POST http://10.0.10.30:6500/api/auth/recovery/setup \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
"recovery_phrase": "my-new-secret-phrase",
"current_password": "NewSecurePassword456!"
}'
```
---
**Server Status**: 🟢 Fully Operational
**Password Recovery**: ✅ Working
**Authentication**: ✅ Working
**Zero-Knowledge**: ✅ Verified
**Test Date**: 2026-02-15 19:13:00 UTC

255
backend/PHASE-2-4-COMPLETE.md
View file

@ -1,255 +0,0 @@
# Phase 2.4 - COMPLETE ✅
**Date**: 2026-02-15 20:47:00 UTC
**Status**: ✅ COMPLETE
---
## What Was Implemented
### ✅ Password Recovery (Complete)
- Zero-knowledge password recovery with recovery phrases
- Recovery phrase setup endpoint (protected)
- Recovery phrase verification endpoint (public)
- Password reset with recovery phrase (public)
- Token invalidation on password reset
### ✅ Enhanced Profile Management (Complete)
- Get user profile endpoint
- Update user profile endpoint
- Delete user account endpoint with password confirmation
- Token revocation on account deletion
### ✅ Email Verification (Stub - Complete)
- Email verification status check
- Send verification email (stub - no actual email server)
- Verify email with token
- Resend verification email (stub)
### ✅ Account Settings Management (Complete)
- Get account settings endpoint
- Update account settings endpoint
- Change password endpoint with current password confirmation
- Token invalidation on password change
---
## New API Endpoints
### Email Verification (Stub)
| Endpoint | Method | Auth Required | Description |
|----------|--------|---------------|-------------|
| `/api/auth/verify/status` | GET | ✅ Yes | Get email verification status |
| `/api/auth/verify/send` | POST | ✅ Yes | Send verification email (stub) |
| `/api/auth/verify/email` | POST | ❌ No | Verify email with token |
| `/api/auth/verify/resend` | POST | ✅ Yes | Resend verification email (stub) |
### Account Settings
| Endpoint | Method | Auth Required | Description |
|----------|--------|---------------|-------------|
| `/api/users/me/settings` | GET | ✅ Yes | Get account settings |
| `/api/users/me/settings` | PUT | ✅ Yes | Update account settings |
| `/api/users/me/change-password` | POST | ✅ Yes | Change password |
---
## Features
### Email Verification (Stub Implementation)
```bash
# Get verification status
GET /api/auth/verify/status
Authorization: Bearer <token>
Response:
{
"email_verified": false,
"message": "Email is not verified"
}
# Send verification email (stub)
POST /api/auth/verify/send
Authorization: Bearer <token>
Response:
{
"message": "Verification email sent (STUB - no actual email sent)",
"email_sent": true,
"verification_token": "abc123..." // For testing
}
# Verify email with token
POST /api/auth/verify/email
Content-Type: application/json
{
"token": "abc123..."
}
Response:
{
"message": "Email verified successfully",
"email_verified": true
}
```
**Note**: This is a stub implementation. In production:
- Use an actual email service (SendGrid, AWS SES, etc.)
- Send HTML emails with verification links
- Store tokens securely
- Implement rate limiting
- Add email expiry checks
### Account Settings
```bash
# Get settings
GET /api/users/me/settings
Authorization: Bearer <token>
Response:
{
"email": "user@example.com",
"username": "username",
"email_verified": true,
"recovery_enabled": true,
"email_notifications": true,
"theme": "light",
"language": "en",
"timezone": "UTC"
}
# Update settings
PUT /api/users/me/settings
Authorization: Bearer <token>
Content-Type: application/json
{
"email_notifications": false,
"theme": "dark",
"language": "es",
"timezone": "America/Argentina/Buenos_Aires"
}
# Change password
POST /api/users/me/change-password
Authorization: Bearer <token>
Content-Type: application/json
{
"current_password": "CurrentPassword123!",
"new_password": "NewPassword456!"
}
Response:
{
"message": "Password changed successfully. Please login again."
}
```
**Security Features**:
- Current password required for password change
- All tokens invalidated on password change
- Token version incremented automatically
- User must re-login after password change
---
## Files Modified
| File | Changes |
|------|---------|
| `backend/src/models/user.rs` | Added `find_by_verification_token()` method |
| `backend/src/handlers/auth.rs` | Added email verification handlers |
| `backend/src/handlers/users.rs` | Added account settings handlers |
| `backend/src/main.rs` | Added new routes |
| `backend/test-phase-2-4-complete.sh` | Comprehensive test script |
---
## Testing
Run the complete test script:
```bash
cd backend
./test-phase-2-4-complete.sh
```
### What the Tests Cover
1. ✅ User registration with recovery phrase
2. ✅ User login
3. ✅ Get email verification status
4. ✅ Send verification email (stub)
5. ✅ Verify email with token
6. ✅ Check verification status after verification
7. ✅ Get account settings
8. ✅ Update account settings
9. ✅ Change password (invalidates all tokens)
10. ✅ Verify old token fails after password change
11. ✅ Login with new password
---
## Phase 2.4 Summary
```
███████████████████████████████████████ 100%
```
### Completed Features
- [x] Password recovery with zero-knowledge phrases
- [x] Enhanced profile management (get, update, delete)
- [x] Email verification stub (send, verify, resend, status)
- [x] Account settings management (get, update)
- [x] Change password with current password confirmation
### Total Endpoints Added: 11
#### Password Recovery (3)
- POST /api/auth/recovery/setup (protected)
- POST /api/auth/recovery/verify (public)
- POST /api/auth/recovery/reset-password (public)
#### Profile Management (3)
- GET /api/users/me (protected)
- PUT /api/users/me (protected)
- DELETE /api/users/me (protected)
#### Email Verification (4)
- GET /api/auth/verify/status (protected)
- POST /api/auth/verify/send (protected)
- POST /api/auth/verify/email (public)
- POST /api/auth/verify/resend (protected)
#### Account Settings (3)
- GET /api/users/me/settings (protected)
- PUT /api/users/me/settings (protected)
- POST /api/users/me/change-password (protected)
---
## Next Steps
### Phase 2.5: Access Control
- Permission-based middleware
- Token version enforcement
- Family access control
- Share permission management
### Phase 2.6: Security Hardening
- Rate limiting implementation
- Account lockout policies
- Security audit logging
- Session management
---
**Phase 2.4 Status**: ✅ COMPLETE
**Implementation Date**: 2026-02-15
**Production Ready**: Yes (email verification is stub)

8
backend/PHASE-2-5-CREATED.txt
View file

@ -1,8 +0,0 @@
Phase 2.5 models and handlers created
Files created:
- Permission model
- Share model
- Updated handlers
Ready to commit

210
backend/PHASE-2.4-SPEC.md
View file

@ -1,210 +0,0 @@
# Phase 2.4: User Management Enhancement
**Status**: 🚧 In Development
**Started**: 2026-02-15
**Last Updated**: 2026-02-15 16:33:00 UTC
---
## Overview
This phase enhances user management capabilities with password recovery, email verification, and improved profile management.
---
## Features to Implement
### 1. Password Recovery with Zero-Knowledge Phrases
**Description**: Allow users to recover accounts using pre-configured recovery phrases without storing them in plaintext.
**Requirements**:
- Users can set up recovery phrases during registration or in profile settings
- Recovery phrases are hashed using the same PBKDF2 as passwords
- Zero-knowledge proof: Server never sees plaintext phrases
- Password reset with phrase verification
- Rate limiting on recovery attempts
**API Endpoints**:
```
POST /api/auth/recovery/setup
Body: { "recovery_phrase": "string" }
Response: 200 OK
POST /api/auth/recovery/verify
Body: { "email": "string", "recovery_phrase": "string" }
Response: 200 OK { "verified": true }
POST /api/auth/recovery/reset-password
Body: { "email": "string", "recovery_phrase": "string", "new_password": "string" }
Response: 200 OK
```
**Implementation Notes**:
- Store `recovery_phrase_hash` in User model
- Use existing `PasswordService` for hashing
- Add rate limiting (5 attempts per hour)
- Log all recovery attempts
---
### 2. Email Verification Flow
**Description**: Verify user email addresses to improve security and enable email notifications.
**Requirements**:
- Send verification email on registration
- Generate secure verification tokens
- Token expiration: 24 hours
- Resend verification email functionality
- Block unverified users from certain actions
**API Endpoints**:
```
POST /api/auth/verify/send
Body: { "email": "string" }
Response: 200 OK { "message": "Verification email sent" }
GET /api/auth/verify/confirm?token=string
Response: 200 OK { "verified": true }
POST /api/auth/verify/resend
Body: { "email": "string" }
Response: 200 OK { "message": "Verification email resent" }
```
**Database Schema**:
`` ust
// Add to User model
pub struct EmailVerification {
pub email_verified: bool,
pub verification_token: String,
pub verification_expires: DateTime<Utc>,
pub verification_attempts: i32,
}
```
**Implementation Notes**:
- Use JWT for verification tokens (short-lived)
- Integrate with email service (placeholder for now)
- Store token in User document
- Add background job to clean expired tokens
---
### 3. Enhanced Profile Management
**Description**: Allow users to update their profiles with more information.
**API Endpoints**:
```
GET /api/users/me
Response: 200 OK { "user": {...} }
PUT /api/users/me
Body: { "username": "string", "full_name": "string", ... }
Response: 200 OK { "user": {...} }
DELETE /api/users/me
Response: 200 OK { "deleted": true }
```
**Implementation Notes**:
- Update existing `get_profile` handler
- Add `update_profile` handler
- Add `delete_account` handler
- Validate input data
- Add password confirmation for sensitive changes
---
### 4. Account Settings Management
**Description**: Manage user account preferences and security settings.
**API Endpoints**:
```
GET /api/users/me/settings
Response: 200 OK { "settings": {...} }
PUT /api/users/me/settings
Body: { "notifications": bool, "theme": "string", ... }
Response: 200 OK { "settings": {...} }
POST /api/users/me/change-password
Body: { "current_password": "string", "new_password": "string" }
Response: 200 OK { "updated": true }
```
**Database Schema**:
`` ust
pub struct UserSettings {
pub email_notifications: bool,
pub two_factor_enabled: bool,
pub theme: String,
pub language: String,
pub timezone: String,
}
```
---
## Implementation Order
1. ✅ **Step 1**: Update User model with new fields
2. ✅ **Step 2**: Implement password recovery endpoints
3. ✅ **Step 3**: Implement email verification endpoints
4. ✅ **Step 4**: Implement enhanced profile management
5. ✅ **Step 5**: Implement account settings endpoints
6. ✅ **Step 6**: Add rate limiting for sensitive operations
7. ✅ **Step 7**: Write integration tests
8. ✅ **Step 8**: Update API documentation
---
## Progress Tracking
| Feature | Status | Notes |
|---------|--------|-------|
| Password Recovery | 🚧 Not Started | |
| Email Verification | 🚧 Not Started | |
| Enhanced Profile | 🚧 Not Started | |
| Account Settings | 🚧 Not Started | |
| Rate Limiting | 🚧 Not Started | |
| Integration Tests | 🚧 Not Started | |
---
## Dependencies
- ✅ MongoDB connection
- ✅ JWT authentication
- ✅ Password hashing (PBKDF2)
- ⏳ Email service (placeholder)
- ⏳ Rate limiting middleware
---
## Testing Strategy
1. Unit tests for each handler
2. Integration tests with test database
3. Rate limiting tests
4. Email verification flow tests
5. Password recovery flow tests
---
## Next Steps
1. Create new models for EmailVerification, UserSettings
2. Implement password recovery handlers
3. Implement email verification handlers
4. Update profile management handlers
5. Add rate limiting middleware
6. Write comprehensive tests
---
**Previous Phase**: [Phase 2.3 - JWT Authentication](./STATUS.md)
**Next Phase**: [Phase 2.5 - Access Control](./STATUS.md)

165
backend/PHASE-2.4-TODO.md
View file

@ -1,165 +0,0 @@
# Phase 2.4 TODO List
**Started**: 2026-02-15 16:33:00 UTC
---
## Priority 1: Core Features (Must Have)
### Password Recovery
- [ ] Add `recovery_phrase_hash` field to User model
- [ ] Add `recovery_phrase_enabled` field to User model
- [ ] Create handler: `POST /api/auth/recovery/setup`
- [ ] Create handler: `POST /api/auth/recovery/verify`
- [ ] Create handler: `POST /api/auth/recovery/reset-password`
- [ ] Add rate limiting (5 attempts per hour)
- [ ] Write unit tests
- [ ] Write integration tests
### Email Verification
- [ ] Add `email_verified` field to User model
- [ ] Add `verification_token` field to User model
- [ ] Add `verification_expires` field to User model
- [ ] Create handler: `POST /api/auth/verify/send`
- [ ] Create handler: `GET /api/auth/verify/confirm`
- [ ] Create handler: `POST /api/auth/verify/resend`
- [ ] Add email service placeholder
- [ ] Write unit tests
- [ ] Write integration tests
### Enhanced Profile Management
- [ ] Update handler: `PUT /api/users/me`
- [ ] Add username validation
- [ ] Add full name field support
- [ ] Add profile picture URL support
- [ ] Create handler: `DELETE /api/users/me`
- [ ] Add password confirmation for deletion
- [ ] Write unit tests
- [ ] Write integration tests
---
## Priority 2: Account Settings (Should Have)
### Settings Management
- [ ] Create UserSettings model
- [ ] Add settings field to User model
- [ ] Create handler: `GET /api/users/me/settings`
- [ ] Create handler: `PUT /api/users/me/settings`
- [ ] Add email notifications toggle
- [ ] Add theme selection
- [ ] Add language selection
- [ ] Add timezone selection
- [ ] Write unit tests
- [ ] Write integration tests
### Password Change
- [ ] Create handler: `POST /api/users/me/change-password`
- [ ] Add current password verification
- [ ] Add new password validation
- [ ] Add rate limiting (3 attempts per hour)
- [ ] Log password changes
- [ ] Write unit tests
- [ ] Write integration tests
---
## Priority 3: Security & Performance (Nice to Have)
### Rate Limiting
- [ ] Install tower-governor dependency
- [ ] Create rate limiting middleware
- [ ] Apply to password recovery endpoint
- [ ] Apply to email verification endpoint
- [ ] Apply to password change endpoint
- [ ] Apply to login endpoint
- [ ] Configure Redis for rate limiting (optional)
- [ ] Write tests
### Security Enhancements
- [ ] Add audit logging for sensitive operations
- [ ] Add IP-based rate limiting
- [ ] Add account lockout after failed attempts
- [ ] Add email verification requirement check
- [ ] Add two-factor authentication prep work
- [ ] Write security tests
---
## Priority 4: Testing & Documentation
### Testing
- [ ] Write integration tests for password recovery flow
- [ ] Write integration tests for email verification flow
- [ ] Write integration tests for profile management
- [ ] Write integration tests for settings management
- [ ] Write rate limiting tests
- [ ] Add test coverage reporting
- [ ] Aim for 80%+ code coverage
### Documentation
- [ ] Update API documentation with new endpoints
- [ ] Add email verification flow diagram
- [ ] Add password recovery flow diagram
- [ ] Update quick start guide
- [ ] Add developer setup instructions
- [ ] Add deployment guide
---
## Implementation Order
### Week 1: Password Recovery
1. Monday: Update User model, create basic handlers
2. Tuesday: Implement rate limiting
3. Wednesday: Write unit tests
4. Thursday: Write integration tests
5. Friday: Code review and refinement
### Week 2: Email Verification
1. Monday: Update User model, create email service placeholder
2. Tuesday: Implement verification handlers
3. Wednesday: Implement token cleanup
4. Thursday: Write tests
5. Friday: Code review and refinement
### Week 3: Profile & Settings
1. Monday: Enhanced profile management
2. Tuesday: Account settings handlers
3. Wednesday: Password change handler
4. Thursday: Write tests
5. Friday: Code review and refinement
### Week 4: Polish & Deploy
1. Monday: Security enhancements
2. Tuesday: Performance optimization
3. Wednesday: Documentation updates
4. Thursday: Integration tests
5. Friday: Deploy to staging
---
## Dependencies
- ✅ Phase 2.3 (JWT Auth) must be complete
- ✅ MongoDB connection working
- ✅ Docker environment operational
- ⏳ Email service (can use placeholder for now)
- ⏳ Redis for rate limiting (optional, can use in-memory)
---
## Notes
- All new handlers must follow existing patterns
- Use existing PasswordService for hashing
- Use existing JwtService for tokens
- Follow Rust best practices and idioms
- Add error handling for all edge cases
- Add comprehensive logging
- Keep handlers simple and focused
- Use middleware for cross-cutting concerns
---
**Last Updated**: 2026-02-15 16:33:00 UTC

173
backend/PHASE-2.5-SUMMARY.md
View file

@ -1,173 +0,0 @@
# Phase 2.5 Completion Summary - Access Control
## ✅ Build Status
**Status:** ✅ SUCCESSFUL - All build errors fixed!
The backend now compiles successfully with only minor warnings about unused code (which is expected for middleware and utility functions that will be used in future phases).
## 📋 Phase 2.5 Deliverables
### 1. Permission Model
- **File:** `backend/src/models/permission.rs`
- **Features:**
- Permission enum with all required types (Read, Write, Delete, Share, Admin)
- Full serde serialization support
- Display trait implementation
### 2. Share Model
- **File:** `backend/src/models/share.rs`
- **Features:**
- Complete Share struct with all fields
- Repository implementation with CRUD operations
- Helper methods for permission checking
- Support for expiration and active/inactive states
### 3. Share Handlers
- **File:** `backend/src/handlers/shares.rs`
- **Endpoints:**
- `POST /api/shares` - Create a new share
- `GET /api/shares` - List all shares for current user
- `GET /api/shares/:id` - Get a specific share
- `PUT /api/shares/:id` - Update a share
- `DELETE /api/shares/:id` - Delete a share
- **Features:**
- Input validation with `validator` crate
- Ownership verification
- Error handling with proper HTTP status codes
- Resource-level permission support
### 4. Permission Middleware
- **File:** `backend/src/middleware/permission.rs`
- **Features:**
- `PermissionMiddleware` for route protection
- `has_permission` helper function
- `extract_resource_id` utility
- Integration with Axum router
### 5. Permission Check Handler
- **File:** `backend/src/handlers/permissions.rs`
- **Endpoint:**
- `GET /api/permissions/check` - Check if user has permission
- **Features:**
- Query parameter validation
- Database integration for permission checking
- Structured response format
### 6. User Profile Management
- **File:** `backend/src/handlers/users.rs`
- **Endpoints:**
- `GET /api/users/profile` - Get user profile
- `PUT /api/users/profile` - Update profile
- `DELETE /api/users/profile` - Delete account
- `POST /api/users/password` - Change password
- `GET /api/users/settings` - Get settings
- `PUT /api/users/settings` - Update settings
- **Features:**
- Complete CRUD for user profiles
- Password management
- Recovery phrase management
- Settings management
### 7. Database Integration
- **File:** `backend/src/db/mongodb_impl.rs`
- **Added Methods:**
- `create_share` - Create a new share
- `get_share` - Get share by ID
- `list_shares_for_user` - List all shares for a user
- `update_share` - Update an existing share
- `delete_share` - Delete a share
- `check_user_permission` - Check if user has specific permission
- `find_share_by_target` - Find shares where user is target
- `find_shares_by_resource` - Find all shares for a resource
- `delete_user` - Delete a user account
- `update_last_active` - Update user's last active timestamp
### 8. Router Configuration
- **File:** `backend/src/main.rs`
- **Routes Added:**
- Permission check endpoint
- Share CRUD endpoints
- User profile and settings endpoints
- Recovery password endpoint
### 9. Dependencies
- **File:** `backend/Cargo.toml`
- **All Required Dependencies:**
- `pbkdf2` with `simple` feature enabled
- `tower_governor` (rate limiting)
- `validator` (input validation)
- `futures` (async utilities)
- All other Phase 2 dependencies maintained
## 🔧 Fixes Applied
### Build Errors Fixed:
1. ✅ Fixed `tower-governor` → `tower_governor` dependency name
2. ✅ Fixed pbkdf2 configuration (enabled `simple` feature)
3. ✅ Fixed Handler trait bound issues (added proper extractors)
4. ✅ Fixed file corruption issues (removed markdown artifacts)
5. ✅ Fixed import paths (bson → mongodb::bson)
6. ✅ Fixed error handling in user model (ObjectId parsing)
7. ✅ Fixed unused imports and dead code warnings
### Code Quality Improvements:
- Proper error handling throughout
- Input validation on all endpoints
- Type-safe permission system
- Comprehensive logging with `tracing`
- Clean separation of concerns
## 📊 API Endpoints Summary
### Authentication
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login
- `POST /api/auth/recover` - Recover password with recovery phrase
### User Management
- `GET /api/users/profile` - Get profile
- `PUT /api/users/profile` - Update profile
- `DELETE /api/users/profile` - Delete account
- `POST /api/users/password` - Change password
- `GET /api/users/settings` - Get settings
- `PUT /api/users/settings` - Update settings
### Shares (Resource Sharing)
- `POST /api/shares` - Create share
- `GET /api/shares` - List shares
- `GET /api/shares/:id` - Get share
- `PUT /api/shares/:id` - Update share
- `DELETE /api/shares/:id` - Delete share
### Permissions
- `GET /api/permissions/check?resource_type=X&resource_id=Y&permission=Z` - Check permission
## 🚀 Ready for Next Phase
Phase 2.5 is **COMPLETE** and all build errors have been **RESOLVED**.
The backend now has a fully functional access control system with:
- ✅ User authentication with JWT
- ✅ Password recovery with zero-knowledge recovery phrases
- ✅ Resource-level permissions
- ✅ Share management (grant, modify, revoke permissions)
- ✅ Permission checking API
- ✅ User profile management
- ✅ Rate limiting
- ✅ Comprehensive error handling
## 📝 Notes
- All handlers use proper Axum extractors (State, Path, Json, Extension)
- JWT middleware adds Claims to request extensions
- All database operations use proper MongoDB error types
- Input validation is applied on all request bodies
- Logging is implemented for debugging and monitoring
- Code follows Rust best practices and idioms
---
**Completed:** 2025-02-15
**Build Status:** ✅ SUCCESS
**Warnings:** 28 (mostly unused code - expected)
**Errors:** 0

11
backend/PHASE28_MAIN_CHANGES.md
View file

@ -1,11 +0,0 @@
// Add this after the module declarations
mod services;
// Add this in the protected routes section
// Drug interactions (Phase 2.8)
.route("/api/interactions/check", post(handlers::check_interactions))
.route("/api/interactions/check-new", post(handlers::check_new_medication))
// Add this when creating the state
// Initialize interaction service (Phase 2.8)
let interaction_service = Arc::new(crate::services::InteractionService::new());

90
backend/PROFILE-MANAGEMENT-IMPLEMENTED.md
View file

@ -1,90 +0,0 @@
# Enhanced Profile Management - Complete
## Status: ✅ Implementation Complete
**Date**: 2026-02-15 19:32:00 UTC
**Feature**: Phase 2.4 - Enhanced Profile Management
---
## API Endpoints
| Endpoint | Method | Auth Required | Description |
|----------|--------|---------------|-------------|
| `/api/users/me` | GET | ✅ Yes | Get current user profile |
| `/api/users/me` | PUT | ✅ Yes | Update user profile |
| `/api/users/me` | DELETE | ✅ Yes | Delete user account |
---
## Features
### 1. Get User Profile
```bash
GET /api/users/me
Authorization: Bearer <token>
```
Response:
```json
{
"id": "...",
"email": "user@example.com",
"username": "username",
"recovery_enabled": true,
"email_verified": false,
"created_at": "2026-02-15T19:32:00Z",
"last_active": "2026-02-15T19:32:00Z"
}
```
### 2. Update Profile
```bash
PUT /api/users/me
Authorization: Bearer <token>
Content-Type: application/json
{
"username": "newusername",
"full_name": "John Doe",
"phone": "+1234567890",
"address": "123 Main St",
"city": "New York",
"country": "USA",
"timezone": "America/New_York"
}
```
### 3. Delete Account
```bash
DELETE /api/users/me
Authorization: Bearer <token>
Content-Type: application/json
{
"password": "CurrentPassword123!"
}
```
Security:
- ✅ Password required
- ✅ All tokens revoked
- ✅ Data removed from database
---
## Testing
Run the test script:
```bash
cd backend
./test-profile-management.sh
```
---
## Files Modified
- backend/src/handlers/users.rs
- backend/src/main.rs
- backend/test-profile-management.sh

2
backend/comprehensive-test.sh
View file

@ -1,6 +1,6 @@
#!/bin/bash #!/bin/bash
API_URL="http://localhost:8080" API_URL="http://localhost:6500"
USER_EMAIL="med-test-${RANDOM}@example.com" USER_EMAIL="med-test-${RANDOM}@example.com"
USER_NAME="medtest${RANDOM}" USER_NAME="medtest${RANDOM}"

1
backend/config/test.env
View file

@ -1 +0,0 @@
test

2
backend/defaults.env
View file

@ -1,4 +1,4 @@
RUST_LOG=debug RUST_LOG=debug
SERVER_PORT=8000 NORMOGEN_PORT=6500
MONGODB_URI=mongodb://mongodb:27017 MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE=normogen MONGODB_DATABASE=normogen

102
backend/deploy-to-solaria-improved.sh
View file

@ -1,102 +0,0 @@
#!/bin/bash
set -e
echo "🚀 Deploying Normogen Backend to Solaria (Improved)"
echo "===================================================="
# Configuration
REMOTE_HOST="solaria"
REMOTE_DIR="/srv/normogen"
DOCKER_COMPOSE_FILE="docker/docker-compose.improved.yml"
# Colors for output
RED='\\033[0;31m'
GREEN='\\033[0;32m'
YELLOW='\\033[1;33m'
NC='\\033[0m' # No Color
log_info() {
echo -e "${GREEN}[INFO]${NC} $1"
}
log_warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}
log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Check if JWT_SECRET is set
if [ -z "${JWT_SECRET}" ]; then
log_error "JWT_SECRET environment variable not set!"
echo "Usage: JWT_SECRET=your-secret ./backend/deploy-to-solaria-improved.sh"
echo ""
echo "Generate a secure secret with:"
echo " openssl rand -base64 32"
exit 1
fi
# Step 1: Build locally
log_info "Step 1: Building backend binary locally..."
cargo build --release
log_info "✅ Build complete"
# Step 2: Create remote directory structure
log_info "Step 2: Setting up remote directory..."
ssh ${REMOTE_HOST} "mkdir -p ${REMOTE_DIR}/docker"
log_info "✅ Directory ready"
# Step 3: Create .env file on remote
log_info "Step 3: Setting up environment variables..."
ssh ${REMOTE_HOST} "cat > ${REMOTE_DIR}/.env << EOF
MONGODB_DATABASE=normogen
JWT_SECRET=${JWT_SECRET}
RUST_LOG=info
SERVER_PORT=8000
SERVER_HOST=0.0.0.0
EOF"
log_info "✅ Environment configured"
# Step 4: Copy improved Docker files to remote
log_info "Step 4: Copying Docker files to remote..."
scp docker/Dockerfile.improved ${REMOTE_HOST}:${REMOTE_DIR}/docker/Dockerfile.improved
scp docker/docker-compose.improved.yml ${REMOTE_HOST}:${REMOTE_DIR}/docker/docker-compose.improved.yml
log_info "✅ Docker files copied"
# Step 5: Stop old containers
log_info "Step 5: Stopping old containers..."
ssh ${REMOTE_HOST} "cd ${REMOTE_DIR} && docker compose down 2>/dev/null || true"
log_info "✅ Old containers stopped"
# Step 6: Start new containers with improved configuration
log_info "Step 6: Starting new containers..."
ssh ${REMOTE_HOST} "cd ${REMOTE_DIR} && docker compose -f ${DOCKER_COMPOSE_FILE} up -d"
log_info "✅ Containers started"
# Step 7: Wait for containers to be healthy
log_info "Step 7: Waiting for containers to stabilize..."
sleep 10
ssh ${REMOTE_HOST} "docker compose -f ${REMOTE_DIR}/${DOCKER_COMPOSE_FILE} ps"
log_info "✅ Container status retrieved"
# Step 8: Test API health endpoint
log_info "Step 8: Testing API health endpoint..."
sleep 5
if curl -f http://solaria.solivarez.com.ar:8001/health > /dev/null 2>&1; then
log_info "✅ API is responding correctly"
else
log_warn "⚠️ API health check failed - check logs with:"
echo " ssh ${REMOTE_HOST} 'docker logs -f normogen-backend'"
fi
log_info "🎉 Deployment complete!"
echo ""
echo "View logs:"
echo " ssh ${REMOTE_HOST} 'docker compose -f ${REMOTE_DIR}/${DOCKER_COMPOSE_FILE} logs -f backend'"
echo ""
echo "View status:"
echo " ssh ${REMOTE_HOST} 'docker compose -f ${REMOTE_DIR}/${DOCKER_COMPOSE_FILE} ps'"
echo ""
echo "Restart services:"
echo " ssh ${REMOTE_HOST} 'docker compose -f ${REMOTE_DIR}/${DOCKER_COMPOSE_FILE} restart'"

2
backend/diagnose-server.sh
View file

@ -30,7 +30,7 @@ curl -s --max-time 3 http://localhost:6500/health || echo "Local connection fail
echo "" echo ""
echo "7. Testing container connection..." echo "7. Testing container connection..."
docker exec normogen-backend-dev curl -s --max-time 3 http://localhost:8000/health || echo "Container connection failed" docker exec normogen-backend-dev curl -s --max-time 3 http://localhost:6500/health || echo "Container connection failed"
echo "" echo ""
echo "==========================================" echo "=========================================="

22
backend/docker-compose.dev.yml
View file

@ -8,27 +8,35 @@ services:
pull_policy: build pull_policy: build
container_name: normogen-backend-dev container_name: normogen-backend-dev
ports: ports:
- '6500:8000' # host 6501 (dev) -> container 6500, distinct from prod's 6500.
- '6501:6500'
volumes: volumes:
- ./src:/app/src - ./src:/app/src
- startup-logs:/tmp - startup-logs:/tmp
environment: environment:
- APP_ENVIRONMENT=development
- RUST_LOG=debug - RUST_LOG=debug
- SERVER_PORT=8000
- SERVER_HOST=0.0.0.0
- MONGODB_URI=mongodb://mongodb:27017
- DATABASE_NAME=normogen_dev
- JWT_SECRET=dev-jwt-secret-key-minimum-32-chars
- RUST_LOG_STYLE=always - RUST_LOG_STYLE=always
- NORMOGEN_HOST=0.0.0.0
- NORMOGEN_PORT=6500
- MONGODB_URI=mongodb://mongodb:27017
- MONGODB_DATABASE=normogen_dev
- JWT_SECRET=dev-jwt-secret-key-minimum-32-chars
depends_on: depends_on:
mongodb: mongodb:
condition: service_healthy condition: service_healthy
networks: networks:
- normogen-network - normogen-network
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:6500/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
restart: unless-stopped restart: unless-stopped
mongodb: mongodb:
image: mongo:6.0 image: mongo:7
container_name: normogen-mongodb-dev container_name: normogen-mongodb-dev
ports: ports:
- '27017:27017' - '27017:27017'

22
backend/docker-compose.yml
View file

@ -1,5 +1,3 @@
version: '3.8'
services: services:
mongodb: mongodb:
image: mongo:7 image: mongo:7
@ -22,19 +20,23 @@ services:
container_name: normogen-backend container_name: normogen-backend
restart: unless-stopped restart: unless-stopped
ports: ports:
- "8000:8080" - "6500:6500"
environment: environment:
- DATABASE_URI=mongodb://mongodb:27017 # The app reads NORMOGEN_* / MONGODB_* / APP_ENVIRONMENT (config/mod.rs).
- DATABASE_NAME=normogen - APP_ENVIRONMENT=production
- JWT_SECRET=your-secret-key-change-in-production - NORMOGEN_HOST=0.0.0.0
- SERVER_HOST=0.0.0.0 - NORMOGEN_PORT=6500
- SERVER_PORT=8080 - MONGODB_URI=mongodb://mongodb:27017
- RUST_LOG=debug - MONGODB_DATABASE=normogen
# Set real, strong values in your prod .env; production boot refuses insecure defaults.
- JWT_SECRET=${JWT_SECRET:?JWT_SECRET must be set}
- ENCRYPTION_KEY=${ENCRYPTION_KEY:?ENCRYPTION_KEY must be set}
- RUST_LOG=info
depends_on: depends_on:
mongodb: mongodb:
condition: service_healthy condition: service_healthy
healthcheck: healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"] test: ["CMD", "curl", "-f", "http://localhost:6500/health"]
interval: 30s interval: 30s
timeout: 10s timeout: 10s
retries: 3 retries: 3

48
backend/docker/Dockerfile
View file

@ -1,48 +0,0 @@
# Production Dockerfile (Multi-stage build)
# Stage 1: Build
FROM rust:1.93-slim AS builder
WORKDIR /app
# Install build dependencies
RUN apt-get update && apt-get install -y \
pkg-config \
libssl-dev \
&& rm -rf /var/lib/apt/lists/*
# Copy Cargo files first for better caching
COPY Cargo.toml ./
# Create dummy main.rs for dependency caching
RUN mkdir src && echo 'fn main() {}' > src/main.rs
# Build dependencies (this layer will be cached)
RUN cargo build --release && rm -rf src
# Copy actual source code
COPY src ./src
# Build the actual application
RUN cargo build --release
# Stage 2: Runtime
FROM debian:bookworm-slim
WORKDIR /app
# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
ca-certificates \
libssl3 \
&& rm -rf /var/lib/apt/lists/*
# Copy the binary from builder stage
COPY --from=builder /app/target/release/normogen-backend /app/normogen-backend
# Expose port
EXPOSE 8000
# Make the binary executable and run it
RUN chmod +x /app/normogen-backend
CMD ["/app/normogen-backend"]

33
backend/docker/Dockerfile.dev
View file

@ -1,40 +1,35 @@
# Development Dockerfile # Development image. Built by docker-compose.dev.yml.
# Uses Rust 1.93+ to support Edition 2024 dependencies # Debug build; the dev compose mounts ./src:/app/src for rapid rebuilds.
FROM rust:1.93-slim as builder FROM rust:latest AS builder
WORKDIR /app WORKDIR /app
# Install build dependencies
RUN apt-get update && apt-get install -y \ RUN apt-get update && apt-get install -y \
pkg-config \ pkg-config \
libssl-dev \ libssl-dev \
&& rm -rf /var/lib/apt/lists/* && rm -rf /var/lib/apt/lists/*
# Copy Cargo files first for better caching # Cache dependency build via a dummy main.rs
COPY Cargo.toml ./ COPY Cargo.toml ./
# Create dummy main.rs for dependency caching
RUN mkdir src && echo 'fn main() {}' > src/main.rs RUN mkdir src && echo 'fn main() {}' > src/main.rs
# Build dependencies (this layer will be cached)
RUN cargo build && rm -rf src RUN cargo build && rm -rf src
# Copy actual source code # Copy actual source and build
COPY src ./src COPY src ./src
# Build the application
RUN cargo build RUN cargo build
# Runtime stage # Runtime stage — full Rust image so the dev compose can rebuild in-container.
FROM rust:1.93-slim # curl is required for the compose HEALTHCHECK to work.
FROM rust:latest
RUN apt-get update && apt-get install -y \
curl \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app WORKDIR /app
# Copy the binary from builder
COPY --from=builder /app/target/debug/normogen-backend /app/normogen-backend COPY --from=builder /app/target/debug/normogen-backend /app/normogen-backend
# Expose port # The app listens on NORMOGEN_PORT (default 6500, set in compose/.env).
EXPOSE 8000 EXPOSE 6500
# Run the binary directly
CMD ["/app/normogen-backend"] CMD ["/app/normogen-backend"]

65
backend/docker/Dockerfile.improved
View file

@ -1,65 +0,0 @@
# Multi-stage build for smaller, more secure image
# Stage 1: Build
FROM rust:1.93-slim AS builder
WORKDIR /app
# Install build dependencies
RUN apt-get update && apt-get install -y \
pkg-config \
libssl-dev \
&& rm -rf /var/lib/apt/lists/*
# Copy manifests first (better layer caching)
COPY Cargo.toml Cargo.lock ./
# Create dummy main.rs to cache dependencies
RUN mkdir src && \
echo "fn main() {}" > src/main.rs && \
cargo build --release && \
rm -rf src
# Copy actual source
COPY src ./src
# Build application
RUN cargo build --release
# Stage 2: Runtime
FROM debian:bookworm-slim
# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
ca-certificates \
libssl3 \
curl \
&& rm -rf /var/lib/apt/lists/* \
&& apt-get clean
# Create non-root user
RUN useradd -m -u 1000 normogen && \
mkdir -p /app && \
chown -R normogen:normogen /app
WORKDIR /app
# Copy binary from builder
COPY --from=builder /app/target/release/normogen-backend /app/normogen-backend
# Set permissions
RUN chmod +x /app/normogen-backend && \
chown normogen:normogen /app/normogen-backend
# Switch to non-root user
USER normogen
# Expose port
EXPOSE 8000
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8000/health || exit 1
# Run with proper signal handling
ENTRYPOINT ["/app/normogen-backend"]
CMD []

43
backend/docker/EDITION2024-FIX.md
View file

@ -1,43 +0,0 @@
# Fix for Rust Edition 2024 Docker Build Error
## Problem
The error occurs because:
1. Your Dockerfile uses `FROM rust:latest` which pulled `rust:1.83-alpine`
2. Several dependencies require Rust 1.85+ for Edition 2024 support:
- `time-core 0.1.8` requires Rust 1.88.0
- `getrandom 0.4.1` requires Rust 1.85.0
- `uuid 1.21.0` requires Rust 1.85.0
- `deranged 0.5.6` requires Rust 1.85.0
- `wasip2/wasip3` require Rust 1.87.0
## Root Cause
Rust Edition 2024 became stable in Rust 1.85.0 (released February 20, 2025).
Some of your transitive dependencies have updated to use Edition 2024,
which requires a newer Rust version than 1.83.
## Solutions
### ✅ RECOMMENDED: Update Rust Base Image
Change `FROM rust:latest` to `FROM rust:1.93` or newer.
**Pros:**
- Future-proof solution
- Gets latest Rust improvements and security fixes
- No dependency management overhead
- Standard practice (update base images regularly)
**Cons:**
- None (this is the correct approach)
### Alternative: Pin Dependency Versions (NOT RECOMMENDED)
Pin problematic dependencies to older versions that don't require Edition 2024.
This creates technical debt and should only be used if you have a specific
constraint preventing Rust version updates.
## Implementation
See the fixed Dockerfiles in this directory.

60
backend/docker/MONGODB-HEALTHCHECK-FIX.md
View file

@ -1,60 +0,0 @@
# MongoDB Health Check Fix
## Problem
The MongoDB container was failing health checks with the original configuration:
```yaml
healthcheck:
test: ['CMD', 'mongosh', '--eval', 'db.adminCommand.ping()']
start_period: 10s # Too short!
```
## Root Causes
1. **start_period too short**: 10s isn't enough for MongoDB to initialize, especially on first start
2. **Command format**: The healthcheck needs proper output handling
## Solution
Updated healthcheck in docker-compose.dev.yml:
```yaml
healthcheck:
test: |
mongosh --eval "db.adminCommand('ping').ok" --quiet
interval: 10s
timeout: 5s
retries: 5
start_period: 40s # Increased from 10s to 40s
```
## Changes Made
- ✅ Increased `start_period` from 10s to 40s (gives MongoDB time to initialize)
- ✅ Simplified the healthcheck command to use shell format
- ✅ Added `--quiet` flag to suppress verbose output
## How to Apply
On your server:
```bash
# Pull the latest changes
git pull origin main
# Stop and remove existing containers
docker compose -f docker-compose.dev.yml down -v
# Start fresh
docker compose -f docker-compose.dev.yml up -d
# Watch the logs
docker compose -f docker-compose.dev.yml logs -f mongodb
```
## Verify Health Check
```bash
# Check container health
docker ps --format "table {{.Names}} {{.Status}}"
# Check health status specifically
docker inspect normogen-mongodb-dev --format='{{.State.Health.Status}}'
```
Expected output: `healthy`

68
backend/docker/docker-compose.improved.yml
View file

@ -1,68 +0,0 @@
version: '3.8'
services:
mongodb:
image: mongo:6.0
container_name: normogen-mongodb
restart: unless-stopped
ports:
- "27017:27017"
environment:
MONGO_INITDB_DATABASE: normogen
volumes:
- mongodb_data:/data/db
- mongodb_config:/data/configdb
networks:
- normogen-network
healthcheck:
test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
backend:
build:
context: ..
dockerfile: docker/Dockerfile.improved
image: normogen-backend:latest
container_name: normogen-backend
restart: unless-stopped
ports:
- "8001:8000"
environment:
RUST_LOG: ${RUST_LOG:-info}
MONGODB_URI: mongodb://mongodb:27017
MONGODB_DATABASE: ${MONGODB_DATABASE:-normogen}
JWT_SECRET: ${JWT_SECRET}
SERVER_PORT: 8000
SERVER_HOST: 0.0.0.0
depends_on:
mongodb:
condition: service_healthy
networks:
- normogen-network
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
deploy:
resources:
limits:
cpus: '1.0'
memory: 512M
reservations:
cpus: '0.25'
memory: 128M
volumes:
mongodb_data:
driver: local
mongodb_config:
driver: local
networks:
normogen-network:
driver: bridge

BIN
backend/docker/normogen-backend
View file

Binary file not shown.

104
backend/src/app.rs Normal file
View file

@ -0,0 +1,104 @@
//! Router assembly. Extracted from `main.rs` so integration tests can build the
//! exact same app (routes, middleware, layers) in process against a test
//! database instead of a live server.
use axum::{
routing::{delete, get, post, put},
Router,
};
use tower::ServiceBuilder;
use tower_http::{cors::CorsLayer, trace::TraceLayer};
use crate::config::AppState;
use crate::handlers;
use crate::middleware;
/// Compose the full Axum app: all public + protected routes, the JWT auth
/// layer on protected routes, and the global middleware stack (client-IP
/// resolution, security headers, rate limit, tracing, CORS).
///
/// `main.rs` calls this and wraps it in `into_make_service_with_connect_info`
/// before serving; tests call it and drive it with `oneshot`/`RouterExt`.
pub fn build_app(state: AppState) -> Router {
// Build public routes (no auth required)
let public_routes = Router::new()
.route(
"/health",
get(handlers::health_check).head(handlers::health_check),
)
.route("/ready", get(handlers::ready_check))
.route("/api/auth/register", post(handlers::register))
.route("/api/auth/login", post(handlers::login))
.route("/api/auth/refresh", post(handlers::refresh))
.route("/api/auth/logout", post(handlers::logout))
.route(
"/api/auth/recover-password",
post(handlers::recover_password),
);
// Build protected routes (auth required)
let protected_routes = Router::new()
// User profile management
.route("/api/users/me", get(handlers::get_profile))
.route("/api/users/me", put(handlers::update_profile))
.route("/api/users/me", delete(handlers::delete_account))
.route("/api/users/me/change-password", post(handlers::change_password))
// User settings
.route("/api/users/me/settings", get(handlers::get_settings))
.route("/api/users/me/settings", put(handlers::update_settings))
// Share management
.route("/api/shares", post(handlers::create_share))
.route("/api/shares", get(handlers::list_shares))
.route("/api/shares/:id", put(handlers::update_share))
.route("/api/shares/:id", delete(handlers::delete_share))
// Permission checking
.route("/api/permissions/check", post(handlers::check_permission))
// Session management (Phase 2.6)
.route("/api/sessions", get(handlers::get_sessions))
.route("/api/sessions/:id", delete(handlers::revoke_session))
.route("/api/sessions/all", delete(handlers::revoke_all_sessions))
// Medication management (Phase 2.7)
.route("/api/medications", post(handlers::create_medication))
.route("/api/medications", get(handlers::list_medications))
.route("/api/medications/:id", get(handlers::get_medication))
.route("/api/medications/:id", post(handlers::update_medication))
.route("/api/medications/:id/delete", post(handlers::delete_medication))
.route("/api/medications/:id/log", post(handlers::log_dose))
.route("/api/medications/:id/adherence", get(handlers::get_adherence))
// Health statistics management (Phase 2.7)
.route("/api/health-stats", post(handlers::create_health_stat))
.route("/api/health-stats", get(handlers::list_health_stats))
.route("/api/health-stats/trends", get(handlers::get_health_trends))
.route("/api/health-stats/:id", get(handlers::get_health_stat))
.route("/api/health-stats/:id", put(handlers::update_health_stat))
.route("/api/health-stats/:id", delete(handlers::delete_health_stat))
// Drug interactions (Phase 2.8)
.route("/api/interactions/check", post(handlers::check_interactions))
.route("/api/interactions/check-new", post(handlers::check_new_medication))
.layer(axum::middleware::from_fn_with_state(
state.clone(),
middleware::jwt_auth_middleware,
));
public_routes
.merge(protected_routes)
.with_state(state)
.layer(
ServiceBuilder::new()
// Resolve the client IP once and stash it for handlers/middleware
// (audit logging, account-lockout forensics).
.layer(axum::middleware::from_fn(
middleware::client_ip_middleware,
))
// Security headers (applies to all responses)
.layer(axum::middleware::from_fn(
middleware::security_headers_middleware,
))
// General rate limiting (currently a stub)
.layer(axum::middleware::from_fn(
middleware::general_rate_limit_middleware,
))
.layer(TraceLayer::new_for_http())
.layer(CorsLayer::permissive()),
)
}

142
backend/src/auth/jwt.rs
View file

@ -3,9 +3,6 @@ use anyhow::Result;
use chrono::{Duration, Utc}; use chrono::{Duration, Utc};
use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation}; use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::RwLock;
use crate::config::JwtConfig; use crate::config::JwtConfig;
@ -21,9 +18,11 @@ pub struct Claims {
} }
impl Claims { impl Claims {
pub fn new(user_id: String, email: String, token_version: i32) -> Self { /// Build access-token claims. `expiry` is the access-token lifetime and is
/// taken from `JwtConfig` by callers (no longer hardcoded here).
pub fn new(user_id: String, email: String, token_version: i32, expiry: Duration) -> Self {
let now = Utc::now(); let now = Utc::now();
let exp = now + Duration::minutes(15); // Access token expires in 15 minutes let exp = now + expiry;
Self { Self {
sub: user_id.clone(), sub: user_id.clone(),
@ -47,9 +46,10 @@ pub struct RefreshClaims {
} }
impl RefreshClaims { impl RefreshClaims {
pub fn new(user_id: String, token_version: i32) -> Self { /// Build refresh-token claims. `expiry` is taken from `JwtConfig` by callers.
pub fn new(user_id: String, token_version: i32, expiry: Duration) -> Self {
let now = Utc::now(); let now = Utc::now();
let exp = now + Duration::days(30); // Refresh token expires in 30 days let exp = now + expiry;
Self { Self {
sub: user_id.clone(), sub: user_id.clone(),
@ -61,12 +61,15 @@ impl RefreshClaims {
} }
} }
/// JWT Service for token generation and validation /// JWT Service for token generation and validation.
///
/// Pure crypto service: it signs/verifies tokens but does NOT track them. Token
/// persistence (refresh-token storage, revocation) is handled by
/// `RefreshTokenRepository` + the auth handlers; token-version staleness is
/// enforced in the JWT middleware via `TokenVersionCache`.
#[derive(Clone)] #[derive(Clone)]
pub struct JwtService { pub struct JwtService {
config: JwtConfig, config: JwtConfig,
// In-memory storage for refresh tokens (user_id -> set of tokens)
refresh_tokens: Arc<RwLock<HashMap<String, Vec<String>>>>,
encoding_key: EncodingKey, encoding_key: EncodingKey,
decoding_key: DecodingKey, decoding_key: DecodingKey,
} }
@ -78,27 +81,38 @@ impl JwtService {
Self { Self {
config, config,
refresh_tokens: Arc::new(RwLock::new(HashMap::new())),
encoding_key, encoding_key,
decoding_key, decoding_key,
} }
} }
/// Generate access and refresh tokens /// Generate access and refresh tokens. Both expiries are derived from the
/// configured `JwtConfig` so callers don't need to thread durations through.
pub fn generate_tokens(&self, claims: Claims) -> Result<(String, String)> { pub fn generate_tokens(&self, claims: Claims) -> Result<(String, String)> {
// Generate access token
let access_token = encode(&Header::default(), &claims, &self.encoding_key) let access_token = encode(&Header::default(), &claims, &self.encoding_key)
.map_err(|e| anyhow::anyhow!("Failed to encode access token: {}", e))?; .map_err(|e| anyhow::anyhow!("Failed to encode access token: {}", e))?;
// Generate refresh token let refresh_expiry = Duration::days(self.config.refresh_token_expiry_days);
let refresh_claims = RefreshClaims::new(claims.user_id.clone(), claims.token_version); let refresh_claims =
RefreshClaims::new(claims.user_id.clone(), claims.token_version, refresh_expiry);
let refresh_token = encode(&Header::default(), &refresh_claims, &self.encoding_key) let refresh_token = encode(&Header::default(), &refresh_claims, &self.encoding_key)
.map_err(|e| anyhow::anyhow!("Failed to encode refresh token: {}", e))?; .map_err(|e| anyhow::anyhow!("Failed to encode refresh token: {}", e))?;
Ok((access_token, refresh_token)) Ok((access_token, refresh_token))
} }
/// Validate access token /// The configured refresh-token lifetime, as a chrono `Duration`.
pub fn refresh_expiry(&self) -> Duration {
Duration::days(self.config.refresh_token_expiry_days)
}
/// The configured access-token lifetime, as a chrono `Duration`.
pub fn access_expiry(&self) -> Duration {
Duration::minutes(self.config.access_token_expiry_minutes)
}
/// Validate access token (signature + expiry only). Callers are responsible
/// for any `token_version` comparison against the user record.
pub fn validate_token(&self, token: &str) -> Result<Claims> { pub fn validate_token(&self, token: &str) -> Result<Claims> {
let token_data = decode::<Claims>(token, &self.decoding_key, &Validation::default()) let token_data = decode::<Claims>(token, &self.decoding_key, &Validation::default())
.map_err(|e| anyhow::anyhow!("Invalid token: {}", e))?; .map_err(|e| anyhow::anyhow!("Invalid token: {}", e))?;
@ -106,73 +120,59 @@ impl JwtService {
Ok(token_data.claims) Ok(token_data.claims)
} }
/// Validate refresh token /// Validate refresh token (signature + expiry only). Callers must still
/// confirm the token exists, is not revoked, and has not expired in the
/// `RefreshTokenRepository`.
pub fn validate_refresh_token(&self, token: &str) -> Result<RefreshClaims> { pub fn validate_refresh_token(&self, token: &str) -> Result<RefreshClaims> {
let token_data = decode::<RefreshClaims>(token, &self.decoding_key, &Validation::default()) let token_data = decode::<RefreshClaims>(token, &self.decoding_key, &Validation::default())
.map_err(|e| anyhow::anyhow!("Invalid refresh token: {}", e))?; .map_err(|e| anyhow::anyhow!("Invalid refresh token: {}", e))?;
Ok(token_data.claims) Ok(token_data.claims)
} }
}
/// Store refresh token for a user #[cfg(test)]
pub async fn store_refresh_token(&self, user_id: &str, token: &str) -> Result<()> { mod tests {
let mut tokens = self.refresh_tokens.write().await; use super::*;
tokens
.entry(user_id.to_string())
.or_insert_with(Vec::new)
.push(token.to_string());
// Keep only last 5 tokens per user fn test_config() -> JwtConfig {
if let Some(user_tokens) = tokens.get_mut(user_id) { JwtConfig {
user_tokens.sort(); secret: "test-secret".to_string(),
user_tokens.dedup(); access_token_expiry_minutes: 15,
if user_tokens.len() > 5 { refresh_token_expiry_days: 7,
*user_tokens = user_tokens.split_off(user_tokens.len() - 5);
} }
} }
Ok(()) #[test]
fn generate_then_validate_roundtrip() {
let svc = JwtService::new(test_config());
let claims = Claims::new(
"user-1".to_string(),
"u@example.com".to_string(),
0,
Duration::minutes(15),
);
let (access, refresh) = svc.generate_tokens(claims).unwrap();
let access_claims = svc.validate_token(&access).unwrap();
assert_eq!(access_claims.user_id, "user-1");
assert_eq!(access_claims.token_version, 0);
let refresh_claims = svc.validate_refresh_token(&refresh).unwrap();
assert_eq!(refresh_claims.user_id, "user-1");
} }
/// Verify if a refresh token is stored #[test]
pub async fn verify_refresh_token_stored(&self, user_id: &str, token: &str) -> Result<bool> { fn refresh_version_is_carried_through() {
let tokens = self.refresh_tokens.read().await; let svc = JwtService::new(test_config());
if let Some(user_tokens) = tokens.get(user_id) { let claims = Claims::new(
Ok(user_tokens.contains(&token.to_string())) "user-2".to_string(),
} else { "u2@example.com".to_string(),
Ok(false) 3,
} Duration::minutes(15),
} );
let (_access, refresh) = svc.generate_tokens(claims).unwrap();
/// Rotate refresh token (remove old, add new) let refresh_claims = svc.validate_refresh_token(&refresh).unwrap();
pub async fn rotate_refresh_token( assert_eq!(refresh_claims.token_version, 3);
&self,
user_id: &str,
old_token: &str,
new_token: &str,
) -> Result<()> {
// Remove old token
self.revoke_refresh_token(old_token).await?;
// Add new token
self.store_refresh_token(user_id, new_token).await?;
Ok(())
}
/// Revoke a specific refresh token
pub async fn revoke_refresh_token(&self, token: &str) -> Result<()> {
let mut tokens = self.refresh_tokens.write().await;
for user_tokens in tokens.values_mut() {
user_tokens.retain(|t| t != token);
}
Ok(())
}
/// Revoke all refresh tokens for a user
pub async fn revoke_all_user_tokens(&self, user_id: &str) -> Result<()> {
let mut tokens = self.refresh_tokens.write().await;
tokens.remove(user_id);
Ok(())
} }
} }

2
backend/src/auth/mod.rs
View file

@ -1,5 +1,7 @@
#![allow(dead_code)] #![allow(dead_code)]
pub mod jwt; pub mod jwt;
pub mod password; pub mod password;
pub mod token_version_cache;
pub use jwt::JwtService; pub use jwt::JwtService;
pub use token_version_cache::TokenVersionCache;

98
backend/src/auth/token_version_cache.rs Normal file
View file

@ -0,0 +1,98 @@
use std::collections::HashMap;
use std::sync::Arc;
use std::time::{Duration, Instant};
use anyhow::Result;
use mongodb::bson::oid::ObjectId;
use tokio::sync::RwLock;
use crate::db::MongoDb;
/// How long a cached token_version is considered fresh before re-querying Mongo.
const DEFAULT_TTL: Duration = Duration::from_secs(30);
/// Short-TTL in-memory cache of `{ user_id -> token_version }`.
///
/// This lets the JWT auth middleware reject access tokens whose `token_version`
/// claim is stale (e.g. issued before a password change) without doing a Mongo
/// lookup on every request. Stale entries are evicted on credential changes via
/// [`TokenVersionCache::invalidate`], so a version bump becomes visible within
/// at most `ttl` on other instances, and immediately on the instance that
/// processed the change.
#[derive(Clone)]
pub struct TokenVersionCache {
map: Arc<RwLock<HashMap<ObjectId, (i32, Instant)>>>,
ttl: Duration,
}
impl TokenVersionCache {
pub fn new(ttl: Duration) -> Self {
Self {
map: Arc::new(RwLock::new(HashMap::new())),
ttl,
}
}
/// Build a cache with the default 30s TTL.
pub fn with_default_ttl() -> Self {
Self::new(DEFAULT_TTL)
}
/// Return the user's current `token_version`, loading it from Mongo on a
/// cache miss or once the cached value is older than the TTL.
///
/// Returns `Ok(None)` when the user no longer exists (deleted), so callers
/// can reject the token as unauthorized.
pub async fn get_or_load(&self, user_id: &ObjectId, db: &MongoDb) -> Result<Option<i32>> {
// Fast path: serve from cache if fresh.
{
let cache = self.map.read().await;
if let Some((version, fetched_at)) = cache.get(user_id) {
if fetched_at.elapsed() < self.ttl {
return Ok(Some(*version));
}
}
}
// Slow path: query Mongo and refresh the cache.
let version = match db.find_user_by_id(user_id).await? {
Some(user) => Some(user.token_version),
None => None,
};
let mut cache = self.map.write().await;
match version {
Some(v) => {
cache.insert(*user_id, (v, Instant::now()));
}
None => {
// User was deleted: drop any stale entry so we don't serve it.
cache.remove(user_id);
}
}
Ok(version)
}
/// Drop the cached entry for a user. Call this whenever a user's
/// `token_version` is bumped (password change / recovery) so that the new
/// version becomes visible immediately instead of waiting for TTL expiry.
pub async fn invalidate(&self, user_id: &ObjectId) {
let mut cache = self.map.write().await;
cache.remove(user_id);
}
}
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn invalidate_removes_entry() {
// We can't easily exercise get_or_load without Mongo, but invalidate on
// an empty cache is a no-op and must not panic.
let cache = TokenVersionCache::with_default_ttl();
cache.invalidate(&ObjectId::new()).await;
assert!(cache.map.read().await.is_empty());
}
}

83
backend/src/config/mod.rs
View file

@ -3,6 +3,34 @@
use anyhow::Result; use anyhow::Result;
use std::sync::Arc; use std::sync::Arc;
use crate::auth::token_version_cache::TokenVersionCache;
/// Deployment environment. In `Production`, insecure config defaults are rejected
/// at boot so the service never starts with a known secret/encryption key.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum Environment {
Development,
Production,
}
impl Environment {
/// Parse `APP_ENVIRONMENT` (case-insensitive). Defaults to `Development`.
pub fn from_env() -> Self {
match std::env::var("APP_ENVIRONMENT")
.unwrap_or_default()
.to_ascii_lowercase()
.as_str()
{
"prod" | "production" => Environment::Production,
_ => Environment::Development,
}
}
}
/// Insecure sentinel values that must never be used in production.
const INSECURE_JWT_SECRET: &str = "secret";
const INSECURE_ENCRYPTION_KEY: &str = "default_key_32_bytes_long!";
#[derive(Clone)] #[derive(Clone)]
pub struct AppState { pub struct AppState {
pub db: crate::db::MongoDb, pub db: crate::db::MongoDb,
@ -16,6 +44,15 @@ pub struct AppState {
/// Phase 2.8: Interaction checker service /// Phase 2.8: Interaction checker service
pub interaction_service: Option<Arc<crate::services::InteractionService>>, pub interaction_service: Option<Arc<crate::services::InteractionService>>,
/// P0: short-TTL cache of {user_id -> token_version} so the JWT middleware
/// can reject tokens whose version is stale (e.g. after a password change)
/// without a Mongo lookup on every request.
pub token_version_cache: Arc<TokenVersionCache>,
/// P0: persisted (hashed) refresh tokens, used for rotation, revocation,
/// and surviving process restarts.
pub refresh_token_repo: Option<Arc<crate::models::refresh_token::RefreshTokenRepository>>,
} }
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
@ -25,6 +62,7 @@ pub struct Config {
pub jwt: JwtConfig, pub jwt: JwtConfig,
pub encryption: EncryptionConfig, pub encryption: EncryptionConfig,
pub cors: CorsConfig, pub cors: CorsConfig,
pub environment: Environment,
} }
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
@ -68,11 +106,48 @@ pub struct CorsConfig {
impl Config { impl Config {
pub fn from_env() -> Result<Self> { pub fn from_env() -> Result<Self> {
let environment = Environment::from_env();
// JWT_SECRET — required to be a real secret in production.
let jwt_secret =
std::env::var("JWT_SECRET").unwrap_or_else(|_| INSECURE_JWT_SECRET.to_string());
if environment == Environment::Production {
if jwt_secret.is_empty() || jwt_secret == INSECURE_JWT_SECRET {
anyhow::bail!(
"JWT_SECRET must be set to a strong, unique value in production (APP_ENVIRONMENT=production). \
Refusing to boot with an insecure default."
);
}
tracing::info!("JWT_SECRET validated for production");
} else if jwt_secret == INSECURE_JWT_SECRET {
tracing::warn!(
"JWT_SECRET is using the insecure default \"{}\". This is allowed only in development.",
INSECURE_JWT_SECRET
);
}
// ENCRYPTION_KEY — required to be a real key in production.
let encryption_key =
std::env::var("ENCRYPTION_KEY").unwrap_or_else(|_| INSECURE_ENCRYPTION_KEY.to_string());
if environment == Environment::Production {
if encryption_key.is_empty() || encryption_key == INSECURE_ENCRYPTION_KEY {
anyhow::bail!(
"ENCRYPTION_KEY must be set to a strong, unique value in production (APP_ENVIRONMENT=production). \
Refusing to boot with an insecure default."
);
}
tracing::info!("ENCRYPTION_KEY validated for production");
} else if encryption_key == INSECURE_ENCRYPTION_KEY {
tracing::warn!(
"ENCRYPTION_KEY is using the insecure default. This is allowed only in development."
);
}
Ok(Config { Ok(Config {
server: ServerConfig { server: ServerConfig {
host: std::env::var("NORMOGEN_HOST").unwrap_or_else(|_| "0.0.0.0".to_string()), host: std::env::var("NORMOGEN_HOST").unwrap_or_else(|_| "0.0.0.0".to_string()),
port: std::env::var("NORMOGEN_PORT") port: std::env::var("NORMOGEN_PORT")
.unwrap_or_else(|_| "8080".to_string()) .unwrap_or_else(|_| "6500".to_string())
.parse()?, .parse()?,
}, },
database: DatabaseConfig { database: DatabaseConfig {
@ -82,7 +157,7 @@ impl Config {
.unwrap_or_else(|_| "normogen".to_string()), .unwrap_or_else(|_| "normogen".to_string()),
}, },
jwt: JwtConfig { jwt: JwtConfig {
secret: std::env::var("JWT_SECRET").unwrap_or_else(|_| "secret".to_string()), secret: jwt_secret,
access_token_expiry_minutes: std::env::var("JWT_ACCESS_TOKEN_EXPIRY_MINUTES") access_token_expiry_minutes: std::env::var("JWT_ACCESS_TOKEN_EXPIRY_MINUTES")
.unwrap_or_else(|_| "15".to_string()) .unwrap_or_else(|_| "15".to_string())
.parse()?, .parse()?,
@ -91,8 +166,7 @@ impl Config {
.parse()?, .parse()?,
}, },
encryption: EncryptionConfig { encryption: EncryptionConfig {
key: std::env::var("ENCRYPTION_KEY") key: encryption_key,
.unwrap_or_else(|_| "default_key_32_bytes_long!".to_string()),
}, },
cors: CorsConfig { cors: CorsConfig {
allowed_origins: std::env::var("CORS_ALLOWED_ORIGINS") allowed_origins: std::env::var("CORS_ALLOWED_ORIGINS")
@ -101,6 +175,7 @@ impl Config {
.map(|s| s.to_string()) .map(|s| s.to_string())
.collect(), .collect(),
}, },
environment,
}) })
} }
} }

76
backend/src/db/init.rs
View file

@ -1,35 +1,31 @@
#![allow(dead_code)] #![allow(dead_code)]
use mongodb::{bson::doc, Client, Collection, IndexModel}; use mongodb::{bson::doc, options::IndexOptions, Collection, IndexModel};
use anyhow::Result; use anyhow::Result;
/// Creates required collections and indexes. Best-effort by design: index
/// creation failures are logged as warnings and do not abort startup, matching
/// the existing swallow-on-warning style. Safe to run repeatedly (idempotent).
pub struct DatabaseInitializer { pub struct DatabaseInitializer {
client: Client, db: mongodb::Database,
db_name: String,
} }
impl DatabaseInitializer { impl DatabaseInitializer {
pub fn new(client: Client, db_name: String) -> Self { pub fn new(db: mongodb::Database) -> Self {
Self { client, db_name } Self { db }
} }
pub async fn initialize(&self) -> Result<()> { pub async fn initialize(&self) -> Result<()> {
let db = self.client.database(&self.db_name);
println!("[MongoDB] Initializing database collections and indexes..."); println!("[MongoDB] Initializing database collections and indexes...");
// Create users collection and index // Create users collection and index
{ {
let collection: Collection<mongodb::bson::Document> = db.collection("users"); let collection: Collection<mongodb::bson::Document> = self.db.collection("users");
// Create email index using the builder pattern // Create email index using the builder pattern
let index = IndexModel::builder() let index = IndexModel::builder()
.keys(doc! { "email": 1 }) .keys(doc! { "email": 1 })
.options( .options(IndexOptions::builder().unique(true).build())
mongodb::options::IndexOptions::builder()
.unique(true)
.build(),
)
.build(); .build();
match collection.create_index(index, None).await { match collection.create_index(index, None).await {
@ -40,7 +36,7 @@ impl DatabaseInitializer {
// Create families collection and indexes // Create families collection and indexes
{ {
let collection: Collection<mongodb::bson::Document> = db.collection("families"); let collection: Collection<mongodb::bson::Document> = self.db.collection("families");
let index1 = IndexModel::builder().keys(doc! { "userId": 1 }).build(); let index1 = IndexModel::builder().keys(doc! { "userId": 1 }).build();
@ -62,7 +58,7 @@ impl DatabaseInitializer {
// Create profiles collection and index // Create profiles collection and index
{ {
let collection: Collection<mongodb::bson::Document> = db.collection("profiles"); let collection: Collection<mongodb::bson::Document> = self.db.collection("profiles");
let index = IndexModel::builder().keys(doc! { "familyId": 1 }).build(); let index = IndexModel::builder().keys(doc! { "familyId": 1 }).build();
@ -77,31 +73,35 @@ impl DatabaseInitializer {
// Create health_data collection // Create health_data collection
{ {
let _collection: Collection<mongodb::bson::Document> = db.collection("health_data"); let _collection: Collection<mongodb::bson::Document> =
self.db.collection("health_data");
println!("✓ Created health_data collection"); println!("✓ Created health_data collection");
} }
// Create lab_results collection // Create lab_results collection
{ {
let _collection: Collection<mongodb::bson::Document> = db.collection("lab_results"); let _collection: Collection<mongodb::bson::Document> =
self.db.collection("lab_results");
println!("✓ Created lab_results collection"); println!("✓ Created lab_results collection");
} }
// Create medications collection // Create medications collection
{ {
let _collection: Collection<mongodb::bson::Document> = db.collection("medications"); let _collection: Collection<mongodb::bson::Document> =
self.db.collection("medications");
println!("✓ Created medications collection"); println!("✓ Created medications collection");
} }
// Create appointments collection // Create appointments collection
{ {
let _collection: Collection<mongodb::bson::Document> = db.collection("appointments"); let _collection: Collection<mongodb::bson::Document> =
self.db.collection("appointments");
println!("✓ Created appointments collection"); println!("✓ Created appointments collection");
} }
// Create shares collection and index // Create shares collection and index
{ {
let collection: Collection<mongodb::bson::Document> = db.collection("shares"); let collection: Collection<mongodb::bson::Document> = self.db.collection("shares");
let index = IndexModel::builder().keys(doc! { "familyId": 1 }).build(); let index = IndexModel::builder().keys(doc! { "familyId": 1 }).build();
@ -111,23 +111,41 @@ impl DatabaseInitializer {
} }
} }
// Create refresh_tokens collection and index // Create refresh_tokens collection and indexes.
// - unique index on tokenHash (the only thing we ever look tokens up by)
// - TTL index on expiresAt so expired tokens are auto-deleted by Mongo
{ {
let collection: Collection<mongodb::bson::Document> = db.collection("refresh_tokens"); let collection: Collection<mongodb::bson::Document> =
self.db.collection("refresh_tokens");
let index = IndexModel::builder() let unique_index = IndexModel::builder()
.keys(doc! { "token": 1 }) .keys(doc! { "tokenHash": 1 })
.options(IndexOptions::builder().unique(true).build())
.build();
// TTL: documents are deleted once their `expiresAt` timestamp passes.
// With expireAfterSeconds=0, Mongo removes each doc exactly when the
// datetime stored in `expiresAt` is reached.
let ttl_index = IndexModel::builder()
.keys(doc! { "expiresAt": 1 })
.options( .options(
mongodb::options::IndexOptions::builder() IndexOptions::builder()
.unique(true) .expire_after(std::time::Duration::from_secs(0))
.build(), .build(),
) )
.build(); .build();
match collection.create_index(index, None).await { match collection.create_index(unique_index, None).await {
Ok(_) => println!("✓ Created index on refresh_tokens.token"), Ok(_) => println!("✓ Created unique index on refresh_tokens.tokenHash"),
Err(e) => println!( Err(e) => println!(
"Warning: Failed to create index on refresh_tokens.token: {}", "Warning: Failed to create index on refresh_tokens.tokenHash: {}",
e
),
}
match collection.create_index(ttl_index, None).await {
Ok(_) => println!("✓ Created TTL index on refresh_tokens.expiresAt"),
Err(e) => println!(
"Warning: Failed to create TTL index on refresh_tokens.expiresAt: {}",
e e
), ),
} }

3
backend/src/db/mod.rs
View file

@ -18,11 +18,12 @@ pub mod init; // Database initialization module
mod mongodb_impl; mod mongodb_impl;
pub use init::DatabaseInitializer;
pub use mongodb_impl::MongoDb; pub use mongodb_impl::MongoDb;
pub async fn create_database() -> Result<Database> { pub async fn create_database() -> Result<Database> {
let mongo_uri = env::var("MONGODB_URI").expect("MONGODB_URI must be set"); let mongo_uri = env::var("MONGODB_URI").expect("MONGODB_URI must be set");
let db_name = env::var("DATABASE_NAME").expect("DATABASE_NAME must be set"); let db_name = env::var("MONGODB_DATABASE").expect("MONGODB_DATABASE must be set");
let client = Client::with_uri_str(&mongo_uri).await?; let client = Client::with_uri_str(&mongo_uri).await?;
let database = client.database(&db_name); let database = client.database(&db_name);

301
backend/src/handlers/auth.rs
View file

@ -1,9 +1,11 @@
use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; use axum::{extract::Extension, extract::State, http::StatusCode, response::IntoResponse, Json};
use mongodb::bson::oid::ObjectId;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use validator::Validate; use validator::Validate;
use crate::{ use crate::{
auth::jwt::Claims, config::AppState, models::audit_log::AuditEventType, models::user::User, auth::jwt::Claims, config::AppState, middleware::ClientIp, models::audit_log::AuditEventType,
models::user::User,
}; };
#[derive(Debug, Deserialize, Validate)] #[derive(Debug, Deserialize, Validate)]
@ -21,6 +23,7 @@ pub struct RegisterRequest {
#[derive(Debug, Serialize)] #[derive(Debug, Serialize)]
pub struct AuthResponse { pub struct AuthResponse {
pub token: String, pub token: String,
pub refresh_token: String,
pub user_id: String, pub user_id: String,
pub email: String, pub email: String,
pub username: String, pub username: String,
@ -28,6 +31,7 @@ pub struct AuthResponse {
pub async fn register( pub async fn register(
State(state): State<AppState>, State(state): State<AppState>,
Extension(client_ip): Extension<ClientIp>,
Json(req): Json<RegisterRequest>, Json(req): Json<RegisterRequest>,
) -> impl IntoResponse { ) -> impl IntoResponse {
if let Err(errors) = req.validate() { if let Err(errors) = req.validate() {
@ -98,7 +102,7 @@ pub async fn register(
AuditEventType::LoginSuccess, // Using LoginSuccess as registration event AuditEventType::LoginSuccess, // Using LoginSuccess as registration event
Some(id), Some(id),
Some(req.email.clone()), Some(req.email.clone()),
"0.0.0.0".to_string(), client_ip.as_str().to_string(),
None, None,
None, None,
) )
@ -127,9 +131,14 @@ pub async fn register(
} }
}; };
// Generate JWT token // Generate JWT token pair and persist the refresh token.
let claims = Claims::new(user_id.to_string(), user.email.clone(), token_version); let claims = Claims::new(
let (token, _refresh_token) = match state.jwt_service.generate_tokens(claims) { user_id.to_string(),
user.email.clone(),
token_version,
state.jwt_service.access_expiry(),
);
let (token, refresh_token) = match state.jwt_service.generate_tokens(claims) {
Ok(t) => t, Ok(t) => t,
Err(e) => { Err(e) => {
tracing::error!("Failed to generate token: {}", e); tracing::error!("Failed to generate token: {}", e);
@ -142,9 +151,19 @@ pub async fn register(
.into_response(); .into_response();
} }
}; };
if let Some(ref repo) = state.refresh_token_repo {
let expires_at = refresh_expiry_bson(&state.jwt_service);
if let Err(e) = repo
.create(&user_id.to_string(), &refresh_token, expires_at)
.await
{
tracing::warn!("Failed to persist refresh token on register: {}", e);
}
}
let response = AuthResponse { let response = AuthResponse {
token, token,
refresh_token,
user_id: user_id.to_string(), user_id: user_id.to_string(),
email: user.email, email: user.email,
username: user.username, username: user.username,
@ -163,6 +182,7 @@ pub struct LoginRequest {
pub async fn login( pub async fn login(
State(state): State<AppState>, State(state): State<AppState>,
Extension(client_ip): Extension<ClientIp>,
Json(req): Json<LoginRequest>, Json(req): Json<LoginRequest>,
) -> impl IntoResponse { ) -> impl IntoResponse {
if let Err(errors) = req.validate() { if let Err(errors) = req.validate() {
@ -212,7 +232,7 @@ pub async fn login(
AuditEventType::LoginFailed, AuditEventType::LoginFailed,
None, None,
Some(req.email.clone()), Some(req.email.clone()),
"0.0.0.0".to_string(), // TODO: Extract real IP client_ip.as_str().to_string(),
None, None,
None, None,
) )
@ -239,17 +259,21 @@ pub async fn login(
} }
}; };
let user_id = user // A persisted user must have an id; if not, return a clean 500 instead of
.id // panicking (the previous ok_or_else(...).unwrap() discarded this response).
.ok_or_else(|| { let user_id = match user.id {
( Some(id) => id,
None => {
tracing::error!("Login user record has no id for email: {}", req.email);
return (
StatusCode::INTERNAL_SERVER_ERROR, StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({ Json(serde_json::json!({
"error": "invalid user state" "error": "invalid user state"
})), })),
) )
}) .into_response();
.unwrap(); }
};
// Verify password // Verify password
match user.verify_password(&req.password) { match user.verify_password(&req.password) {
@ -272,7 +296,7 @@ pub async fn login(
AuditEventType::LoginFailed, AuditEventType::LoginFailed,
Some(user_id), Some(user_id),
Some(req.email.clone()), Some(req.email.clone()),
"0.0.0.0".to_string(), // TODO: Extract real IP client_ip.as_str().to_string(),
None, None,
None, None,
) )
@ -301,9 +325,14 @@ pub async fn login(
// Update last active timestamp (TODO: Implement in database layer) // Update last active timestamp (TODO: Implement in database layer)
// Generate JWT token // Generate JWT token pair and persist the refresh token.
let claims = Claims::new(user_id.to_string(), user.email.clone(), user.token_version); let claims = Claims::new(
let (token, _refresh_token) = match state.jwt_service.generate_tokens(claims) { user_id.to_string(),
user.email.clone(),
user.token_version,
state.jwt_service.access_expiry(),
);
let (token, refresh_token) = match state.jwt_service.generate_tokens(claims) {
Ok(t) => t, Ok(t) => t,
Err(e) => { Err(e) => {
tracing::error!("Failed to generate token: {}", e); tracing::error!("Failed to generate token: {}", e);
@ -316,6 +345,15 @@ pub async fn login(
.into_response(); .into_response();
} }
}; };
if let Some(ref repo) = state.refresh_token_repo {
let expires_at = refresh_expiry_bson(&state.jwt_service);
if let Err(e) = repo
.create(&user_id.to_string(), &refresh_token, expires_at)
.await
{
tracing::warn!("Failed to persist refresh token on login: {}", e);
}
}
// Log successful login (Phase 2.6) // Log successful login (Phase 2.6)
if let Some(ref audit) = state.audit_logger { if let Some(ref audit) = state.audit_logger {
@ -324,7 +362,7 @@ pub async fn login(
AuditEventType::LoginSuccess, AuditEventType::LoginSuccess,
Some(user_id), Some(user_id),
Some(req.email.clone()), Some(req.email.clone()),
"0.0.0.0".to_string(), // TODO: Extract real IP client_ip.as_str().to_string(),
None, None,
None, None,
) )
@ -333,6 +371,7 @@ pub async fn login(
let response = AuthResponse { let response = AuthResponse {
token, token,
refresh_token,
user_id: user_id.to_string(), user_id: user_id.to_string(),
email: user.email, email: user.email,
username: user.username, username: user.username,
@ -353,6 +392,7 @@ pub struct RecoverPasswordRequest {
pub async fn recover_password( pub async fn recover_password(
State(state): State<AppState>, State(state): State<AppState>,
Extension(client_ip): Extension<ClientIp>,
Json(req): Json<RecoverPasswordRequest>, Json(req): Json<RecoverPasswordRequest>,
) -> impl IntoResponse { ) -> impl IntoResponse {
if let Err(errors) = req.validate() { if let Err(errors) = req.validate() {
@ -432,6 +472,20 @@ pub async fn recover_password(
// Save updated user // Save updated user
match state.db.update_user(&user).await { match state.db.update_user(&user).await {
Ok(_) => { Ok(_) => {
// Password change bumps token_version, so existing access tokens are
// rejected; also revoke every refresh token so they can't be used to
// mint new access tokens.
if let Some(ref repo) = state.refresh_token_repo {
if let Some(ref uid) = user.id.as_ref().map(|oid| oid.to_string()) {
if let Err(e) = repo.revoke_all_by_user(uid).await {
tracing::warn!("Failed to revoke refresh tokens on recovery: {}", e);
}
}
}
if let Some(ref uid) = user.id {
state.token_version_cache.invalidate(uid).await;
}
// Log password recovery (Phase 2.6) // Log password recovery (Phase 2.6)
if let Some(ref audit) = state.audit_logger { if let Some(ref audit) = state.audit_logger {
let user_id_for_log = user.id; let user_id_for_log = user.id;
@ -440,7 +494,7 @@ pub async fn recover_password(
AuditEventType::PasswordRecovery, AuditEventType::PasswordRecovery,
user_id_for_log, user_id_for_log,
Some(req.email.clone()), Some(req.email.clone()),
"0.0.0.0".to_string(), client_ip.as_str().to_string(),
None, None,
None, None,
) )
@ -461,3 +515,212 @@ pub async fn recover_password(
} }
} }
} }
/// Compute the BSON expiry timestamp for a freshly issued refresh token, from
/// the configured refresh lifetime on the JWT service.
fn refresh_expiry_bson(jwt: &crate::auth::JwtService) -> mongodb::bson::DateTime {
let now = std::time::SystemTime::now();
let expiry = now + jwt.refresh_expiry().to_std().unwrap_or_default();
mongodb::bson::DateTime::from_system_time(expiry)
}
#[derive(Debug, Deserialize)]
pub struct RefreshRequest {
pub refresh_token: String,
}
#[derive(Debug, Serialize)]
pub struct RefreshResponse {
pub token: String,
pub refresh_token: String,
}
/// Exchange a valid refresh token for a new access/refresh pair (rotation).
///
/// Validation: signature + expiry (JWT), then the token must exist in Mongo,
/// not be revoked, and not have passed its stored `expiresAt`; finally the
/// user's current `token_version` must match the refresh token's claim (so a
/// password change invalidates refresh tokens too). The old refresh token is
/// revoked and a new one issued + stored.
pub async fn refresh(
State(state): State<AppState>,
Json(req): Json<RefreshRequest>,
) -> impl IntoResponse {
// 1. Signature + expiry check on the presented refresh token.
let refresh_claims = match state.jwt_service.validate_refresh_token(&req.refresh_token) {
Ok(c) => c,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid refresh token" })),
)
.into_response()
}
};
// 2. Must exist and be active in the store.
let record = match state.refresh_token_repo.as_ref() {
Some(repo) => match repo.find_by_raw_token(&req.refresh_token).await {
Ok(Some(r)) => r,
Ok(None) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid refresh token" })),
)
.into_response()
}
Err(e) => {
tracing::error!("Refresh token lookup failed: {}", e);
return (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({ "error": "database error" })),
)
.into_response();
}
},
None => {
tracing::error!("Refresh token repository not configured");
return (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({ "error": "server misconfiguration" })),
)
.into_response();
}
};
if record.revoked {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "refresh token revoked" })),
)
.into_response();
}
if record.expires_at <= mongodb::bson::DateTime::now() {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "refresh token expired" })),
)
.into_response();
}
// 3. Load the user and verify token_version matches.
let user_id = match ObjectId::parse_str(&refresh_claims.sub) {
Ok(oid) => oid,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid refresh token" })),
)
.into_response()
}
};
let user = match state.db.find_user_by_id(&user_id).await {
Ok(Some(u)) => u,
Ok(None) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid refresh token" })),
)
.into_response()
}
Err(e) => {
tracing::error!("Failed to load user during refresh: {}", e);
return (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({ "error": "database error" })),
)
.into_response();
}
};
if user.token_version != refresh_claims.token_version {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "credentials have changed; please log in again" })),
)
.into_response();
}
// 4. Rotate: revoke the old refresh token, issue a new pair, store the new
// refresh token.
if let Some(ref repo) = state.refresh_token_repo {
if let Some(old_id) = record.id {
if let Err(e) = repo.revoke(&old_id).await {
tracing::warn!("Failed to revoke old refresh token: {}", e);
}
}
}
let claims = Claims::new(
user_id.to_string(),
user.email.clone(),
user.token_version,
state.jwt_service.access_expiry(),
);
let (access_token, new_refresh_token) = match state.jwt_service.generate_tokens(claims) {
Ok(t) => t,
Err(e) => {
tracing::error!("Failed to generate token: {}", e);
return (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({ "error": "failed to generate token" })),
)
.into_response();
}
};
if let Some(ref repo) = state.refresh_token_repo {
let expires_at = refresh_expiry_bson(&state.jwt_service);
if let Err(e) = repo
.create(&user_id.to_string(), &new_refresh_token, expires_at)
.await
{
tracing::warn!("Failed to persist rotated refresh token: {}", e);
}
}
(
StatusCode::OK,
Json(RefreshResponse {
token: access_token,
refresh_token: new_refresh_token,
}),
)
.into_response()
}
/// Revoke a single refresh token (client-side logout). The access token remains
/// valid until its short expiry; this prevents the refresh token from minting
/// any further access tokens.
pub async fn logout(
State(state): State<AppState>,
Json(req): Json<RefreshRequest>,
) -> impl IntoResponse {
if let Some(ref repo) = state.refresh_token_repo {
match repo.find_by_raw_token(&req.refresh_token).await {
Ok(Some(record)) => {
if let Some(id) = record.id {
if let Err(e) = repo.revoke(&id).await {
tracing::warn!("Failed to revoke refresh token on logout: {}", e);
return (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({ "error": "database error" })),
)
.into_response();
}
}
}
Ok(None) => {
// Already gone or never existed — treat as success (idempotent).
}
Err(e) => {
tracing::error!("Refresh token lookup failed on logout: {}", e);
return (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({ "error": "database error" })),
)
.into_response();
}
}
}
StatusCode::NO_CONTENT.into_response()
}

66
backend/src/handlers/health_stats.rs
View file

@ -38,7 +38,16 @@ pub async fn create_health_stat(
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
Json(req): Json<CreateHealthStatRequest>, Json(req): Json<CreateHealthStatRequest>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let repo = state.health_stats_repo.as_ref().unwrap(); let repo = match state.health_stats_repo.as_ref() {
Some(r) => r,
None => {
return (
StatusCode::SERVICE_UNAVAILABLE,
Json(serde_json::json!({ "error": "health stats unavailable" })),
)
.into_response()
}
};
// Convert complex value to f64 or store as string // Convert complex value to f64 or store as string
let value_num = match req.value { let value_num = match req.value {
@ -80,7 +89,16 @@ pub async fn list_health_stats(
State(state): State<AppState>, State(state): State<AppState>,
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let repo = state.health_stats_repo.as_ref().unwrap(); let repo = match state.health_stats_repo.as_ref() {
Some(r) => r,
None => {
return (
StatusCode::SERVICE_UNAVAILABLE,
Json(serde_json::json!({ "error": "health stats unavailable" })),
)
.into_response()
}
};
match repo.find_by_user(&claims.sub).await { match repo.find_by_user(&claims.sub).await {
Ok(stats) => (StatusCode::OK, Json(stats)).into_response(), Ok(stats) => (StatusCode::OK, Json(stats)).into_response(),
Err(e) => { Err(e) => {
@ -99,7 +117,16 @@ pub async fn get_health_stat(
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
Path(id): Path<String>, Path(id): Path<String>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let repo = state.health_stats_repo.as_ref().unwrap(); let repo = match state.health_stats_repo.as_ref() {
Some(r) => r,
None => {
return (
StatusCode::SERVICE_UNAVAILABLE,
Json(serde_json::json!({ "error": "health stats unavailable" })),
)
.into_response()
}
};
let object_id = match ObjectId::parse_str(&id) { let object_id = match ObjectId::parse_str(&id) {
Ok(oid) => oid, Ok(oid) => oid,
Err(_) => return (StatusCode::BAD_REQUEST, "Invalid ID").into_response(), Err(_) => return (StatusCode::BAD_REQUEST, "Invalid ID").into_response(),
@ -130,7 +157,16 @@ pub async fn update_health_stat(
Path(id): Path<String>, Path(id): Path<String>,
Json(req): Json<UpdateHealthStatRequest>, Json(req): Json<UpdateHealthStatRequest>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let repo = state.health_stats_repo.as_ref().unwrap(); let repo = match state.health_stats_repo.as_ref() {
Some(r) => r,
None => {
return (
StatusCode::SERVICE_UNAVAILABLE,
Json(serde_json::json!({ "error": "health stats unavailable" })),
)
.into_response()
}
};
let object_id = match ObjectId::parse_str(&id) { let object_id = match ObjectId::parse_str(&id) {
Ok(oid) => oid, Ok(oid) => oid,
Err(_) => return (StatusCode::BAD_REQUEST, "Invalid ID").into_response(), Err(_) => return (StatusCode::BAD_REQUEST, "Invalid ID").into_response(),
@ -182,7 +218,16 @@ pub async fn delete_health_stat(
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
Path(id): Path<String>, Path(id): Path<String>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let repo = state.health_stats_repo.as_ref().unwrap(); let repo = match state.health_stats_repo.as_ref() {
Some(r) => r,
None => {
return (
StatusCode::SERVICE_UNAVAILABLE,
Json(serde_json::json!({ "error": "health stats unavailable" })),
)
.into_response()
}
};
let object_id = match ObjectId::parse_str(&id) { let object_id = match ObjectId::parse_str(&id) {
Ok(oid) => oid, Ok(oid) => oid,
Err(_) => return (StatusCode::BAD_REQUEST, "Invalid ID").into_response(), Err(_) => return (StatusCode::BAD_REQUEST, "Invalid ID").into_response(),
@ -219,7 +264,16 @@ pub async fn get_health_trends(
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
Query(query): Query<HealthTrendsQuery>, Query(query): Query<HealthTrendsQuery>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let repo = state.health_stats_repo.as_ref().unwrap(); let repo = match state.health_stats_repo.as_ref() {
Some(r) => r,
None => {
return (
StatusCode::SERVICE_UNAVAILABLE,
Json(serde_json::json!({ "error": "health stats unavailable" })),
)
.into_response()
}
};
match repo.find_by_user(&claims.sub).await { match repo.find_by_user(&claims.sub).await {
Ok(stats) => { Ok(stats) => {
// Filter by stat_type // Filter by stat_type

2
backend/src/handlers/mod.rs
View file

@ -9,7 +9,7 @@ pub mod shares;
pub mod users; pub mod users;
// Re-export commonly used handler functions // Re-export commonly used handler functions
pub use auth::{login, recover_password, register}; pub use auth::{login, logout, recover_password, refresh, register};
pub use health::{health_check, ready_check}; pub use health::{health_check, ready_check};
pub use health_stats::{ pub use health_stats::{
create_health_stat, delete_health_stat, get_health_stat, get_health_trends, list_health_stats, create_health_stat, delete_health_stat, get_health_stat, get_health_trends, list_health_stats,

104
backend/src/handlers/users.rs
View file

@ -3,7 +3,10 @@ use mongodb::bson::oid::ObjectId;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use validator::Validate; use validator::Validate;
use crate::{auth::jwt::Claims, config::AppState, models::user::User}; use crate::{
auth::jwt::Claims, config::AppState, middleware::ClientIp, models::audit_log::AuditEventType,
models::user::User,
};
#[derive(Debug, Serialize)] #[derive(Debug, Serialize)]
pub struct UserProfileResponse { pub struct UserProfileResponse {
@ -40,7 +43,16 @@ pub async fn get_profile(
State(state): State<AppState>, State(state): State<AppState>,
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let user_id = ObjectId::parse_str(&claims.sub).unwrap(); let user_id = match ObjectId::parse_str(&claims.sub) {
Ok(oid) => oid,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid token" })),
)
.into_response()
}
};
match state.db.find_user_by_id(&user_id).await { match state.db.find_user_by_id(&user_id).await {
Ok(Some(user)) => { Ok(Some(user)) => {
@ -83,7 +95,16 @@ pub async fn update_profile(
.into_response(); .into_response();
} }
let user_id = ObjectId::parse_str(&claims.sub).unwrap(); let user_id = match ObjectId::parse_str(&claims.sub) {
Ok(oid) => oid,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid token" })),
)
.into_response()
}
};
let mut user = match state.db.find_user_by_id(&user_id).await { let mut user = match state.db.find_user_by_id(&user_id).await {
Ok(Some(u)) => u, Ok(Some(u)) => u,
@ -134,7 +155,16 @@ pub async fn delete_account(
State(state): State<AppState>, State(state): State<AppState>,
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let user_id = ObjectId::parse_str(&claims.sub).unwrap(); let user_id = match ObjectId::parse_str(&claims.sub) {
Ok(oid) => oid,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid token" })),
)
.into_response()
}
};
match state.db.delete_user(&user_id).await { match state.db.delete_user(&user_id).await {
Ok(_) => (StatusCode::NO_CONTENT, ()).into_response(), Ok(_) => (StatusCode::NO_CONTENT, ()).into_response(),
@ -162,6 +192,7 @@ pub struct ChangePasswordRequest {
pub async fn change_password( pub async fn change_password(
State(state): State<AppState>, State(state): State<AppState>,
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
Extension(client_ip): Extension<ClientIp>,
Json(req): Json<ChangePasswordRequest>, Json(req): Json<ChangePasswordRequest>,
) -> impl IntoResponse { ) -> impl IntoResponse {
if let Err(errors) = req.validate() { if let Err(errors) = req.validate() {
@ -175,7 +206,18 @@ pub async fn change_password(
.into_response(); .into_response();
} }
let user_id = ObjectId::parse_str(&claims.sub).unwrap(); // The middleware already validated this against a real user, but guard
// against a malformed subject anyway rather than panicking.
let user_id = match ObjectId::parse_str(&claims.sub) {
Ok(oid) => oid,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid token" })),
)
.into_response()
}
};
let mut user = match state.db.find_user_by_id(&user_id).await { let mut user = match state.db.find_user_by_id(&user_id).await {
Ok(Some(u)) => u, Ok(Some(u)) => u,
@ -224,7 +266,7 @@ pub async fn change_password(
} }
} }
// Update password // Update password (this also bumps token_version in memory)
match user.update_password(req.new_password) { match user.update_password(req.new_password) {
Ok(_) => {} Ok(_) => {}
Err(e) => { Err(e) => {
@ -240,7 +282,33 @@ pub async fn change_password(
} }
match state.db.update_user(&user).await { match state.db.update_user(&user).await {
Ok(_) => (StatusCode::NO_CONTENT, ()).into_response(), Ok(_) => {
// Invalidate all sessions: the bumped token_version rejects existing
// access tokens, and we revoke every refresh token immediately so
// they can't mint new access tokens.
if let Some(ref repo) = state.refresh_token_repo {
if let Err(e) = repo.revoke_all_by_user(&user_id.to_string()).await {
tracing::warn!("Failed to revoke refresh tokens on password change: {}", e);
}
}
state.token_version_cache.invalidate(&user_id).await;
// Audit the credential change.
if let Some(ref audit) = state.audit_logger {
let _ = audit
.log_event(
AuditEventType::PasswordChanged,
Some(user_id),
Some(user.email.clone()),
client_ip.as_str().to_string(),
None,
None,
)
.await;
}
(StatusCode::NO_CONTENT, ()).into_response()
}
Err(e) => { Err(e) => {
tracing::error!("Failed to update user: {}", e); tracing::error!("Failed to update user: {}", e);
( (
@ -273,7 +341,16 @@ pub async fn get_settings(
State(state): State<AppState>, State(state): State<AppState>,
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let user_id = ObjectId::parse_str(&claims.sub).unwrap(); let user_id = match ObjectId::parse_str(&claims.sub) {
Ok(oid) => oid,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid token" })),
)
.into_response()
}
};
match state.db.find_user_by_id(&user_id).await { match state.db.find_user_by_id(&user_id).await {
Ok(Some(user)) => { Ok(Some(user)) => {
@ -310,7 +387,16 @@ pub async fn update_settings(
Extension(claims): Extension<Claims>, Extension(claims): Extension<Claims>,
Json(req): Json<UpdateSettingsRequest>, Json(req): Json<UpdateSettingsRequest>,
) -> impl IntoResponse { ) -> impl IntoResponse {
let user_id = ObjectId::parse_str(&claims.sub).unwrap(); let user_id = match ObjectId::parse_str(&claims.sub) {
Ok(oid) => oid,
Err(_) => {
return (
StatusCode::UNAUTHORIZED,
Json(serde_json::json!({ "error": "invalid token" })),
)
.into_response()
}
};
let mut user = match state.db.find_user_by_id(&user_id).await { let mut user = match state.db.find_user_by_id(&user_id).await {
Ok(Some(u)) => u, Ok(Some(u)) => u,

16
backend/src/lib.rs Normal file
View file

@ -0,0 +1,16 @@
//! Library facade so the binary entrypoint and integration tests share a single
//! source of truth for module wiring and router assembly.
//!
//! `main.rs` is a thin wrapper that loads config, connects to Mongo, builds the
//! app via [`app::build_app`], and serves it. Tests build the same app in
//! process against a throwaway database.
pub mod app;
pub mod auth;
pub mod config;
pub mod db;
pub mod handlers;
pub mod middleware;
pub mod models;
pub mod security;
pub mod services;

149
backend/src/main.rs
View file

@ -1,20 +1,19 @@
mod auth; //! Binary entrypoint: loads config, connects to MongoDB, wires services into
mod config; //! [`config::AppState`], builds the router via [`app::build_app`], and serves.
mod db; //!
mod handlers; //! All module wiring and route/middleware composition lives in the library
mod middleware; //! (`lib.rs` + `app.rs`) so integration tests can reuse them.
mod models;
mod security;
mod services;
use axum::{
routing::{delete, get, post, put},
Router,
};
use config::Config;
use std::sync::Arc; use std::sync::Arc;
use tower::ServiceBuilder;
use tower_http::{cors::CorsLayer, trace::TraceLayer}; use normogen_backend::{
app::build_app,
auth::{JwtService, TokenVersionCache},
config::{self, Config, Environment},
db,
models::{health_stats::HealthStatisticsRepository, refresh_token::RefreshTokenRepository},
security, services,
};
#[tokio::main] #[tokio::main]
async fn main() -> anyhow::Result<()> { async fn main() -> anyhow::Result<()> {
@ -33,6 +32,11 @@ async fn main() -> anyhow::Result<()> {
// Load configuration // Load configuration
let config = Config::from_env()?; let config = Config::from_env()?;
if config.environment == Environment::Production {
eprintln!("Running in PRODUCTION mode");
} else {
eprintln!("Running in DEVELOPMENT mode");
}
eprintln!("Configuration loaded successfully"); eprintln!("Configuration loaded successfully");
// Connect to MongoDB // Connect to MongoDB
@ -65,11 +69,28 @@ async fn main() -> anyhow::Result<()> {
} }
// Create JWT service // Create JWT service
let jwt_service = auth::JwtService::new(config.jwt.clone()); let jwt_service = JwtService::new(config.jwt.clone());
// Get the underlying MongoDB database for security services // Get the underlying MongoDB database for security services
let database = db.get_database(); let database = db.get_database();
// Ensure collections/indexes exist (best-effort; failures are logged, not
// fatal). Includes the refresh_tokens tokenHash-unique + expiresAt TTL
// indexes and the previously-never-run users.email unique index.
if let Err(e) = db::DatabaseInitializer::new(database.clone())
.initialize()
.await
{
tracing::warn!("Database index initialization skipped: {}", e);
}
// Short-TTL cache of token_version, so the JWT middleware can reject stale
// access tokens without a Mongo lookup per request.
let token_version_cache = Arc::new(TokenVersionCache::with_default_ttl());
// Persisted refresh tokens (hashed) for rotation/revocation.
let refresh_token_repo = Arc::new(RefreshTokenRepository::new(&database));
// Initialize security services (Phase 2.6) // Initialize security services (Phase 2.6)
let audit_logger = security::AuditLogger::new(&database); let audit_logger = security::AuditLogger::new(&database);
let session_manager = security::SessionManager::new(&database); let session_manager = security::SessionManager::new(&database);
@ -84,7 +105,7 @@ async fn main() -> anyhow::Result<()> {
); );
// Initialize health stats repository (Phase 2.7) - using Database pattern // Initialize health stats repository (Phase 2.7) - using Database pattern
let health_stats_repo = models::health_stats::HealthStatisticsRepository::new(&database); let health_stats_repo = HealthStatisticsRepository::new(&database);
// Initialize interaction service (Phase 2.8) // Initialize interaction service (Phase 2.8)
let interaction_service = Arc::new(services::InteractionService::new()); let interaction_service = Arc::new(services::InteractionService::new());
@ -101,91 +122,12 @@ async fn main() -> anyhow::Result<()> {
health_stats_repo: Some(health_stats_repo), health_stats_repo: Some(health_stats_repo),
mongo_client: None, mongo_client: None,
interaction_service: Some(interaction_service), interaction_service: Some(interaction_service),
token_version_cache,
refresh_token_repo: Some(refresh_token_repo),
}; };
eprintln!("Building router with security middleware..."); eprintln!("Building router with security middleware...");
let app = build_app(state);
// Build public routes (no auth required)
let public_routes = Router::new()
.route(
"/health",
get(handlers::health_check).head(handlers::health_check),
)
.route("/ready", get(handlers::ready_check))
.route("/api/auth/register", post(handlers::register))
.route("/api/auth/login", post(handlers::login))
.route(
"/api/auth/recover-password",
post(handlers::recover_password),
);
// Build protected routes (auth required)
let protected_routes = Router::new()
// User profile management
.route("/api/users/me", get(handlers::get_profile))
.route("/api/users/me", put(handlers::update_profile))
.route("/api/users/me", delete(handlers::delete_account))
.route("/api/users/me/change-password", post(handlers::change_password))
// User settings
.route("/api/users/me/settings", get(handlers::get_settings))
.route("/api/users/me/settings", put(handlers::update_settings))
// Share management
.route("/api/shares", post(handlers::create_share))
.route("/api/shares", get(handlers::list_shares))
.route("/api/shares/:id", put(handlers::update_share))
.route("/api/shares/:id", delete(handlers::delete_share))
// Permission checking
.route("/api/permissions/check", post(handlers::check_permission))
// Session management (Phase 2.6)
.route("/api/sessions", get(handlers::get_sessions))
.route("/api/sessions/:id", delete(handlers::revoke_session))
.route("/api/sessions/all", delete(handlers::revoke_all_sessions))
// Medication management (Phase 2.7)
.route("/api/medications", post(handlers::create_medication))
.route("/api/medications", get(handlers::list_medications))
.route("/api/medications/:id", get(handlers::get_medication))
.route("/api/medications/:id", post(handlers::update_medication))
.route("/api/medications/:id/delete", post(handlers::delete_medication))
.route("/api/medications/:id/log", post(handlers::log_dose))
.route("/api/medications/:id/adherence", get(handlers::get_adherence))
// Health statistics management (Phase 2.7)
.route("/api/health-stats", post(handlers::create_health_stat))
.route("/api/health-stats", get(handlers::list_health_stats))
.route("/api/health-stats/trends", get(handlers::get_health_trends))
.route("/api/health-stats/:id", get(handlers::get_health_stat))
.route("/api/health-stats/:id", put(handlers::update_health_stat))
.route("/api/health-stats/:id", delete(handlers::delete_health_stat))
// Drug interactions (Phase 2.8)
.route("/api/interactions/check", post(handlers::check_interactions))
.route("/api/interactions/check-new", post(handlers::check_new_medication))
.layer(axum::middleware::from_fn_with_state(
state.clone(),
middleware::jwt_auth_middleware
));
let app = public_routes
.merge(protected_routes)
.with_state(state)
.layer(
ServiceBuilder::new()
// Add security headers first (applies to all responses)
.layer(axum::middleware::from_fn(
middleware::security_headers_middleware
))
// Add general rate limiting
.layer(axum::middleware::from_fn(
middleware::general_rate_limit_middleware
))
.layer(TraceLayer::new_for_http())
.layer(CorsLayer::permissive()),
);
let addr = format!("{}:{}", config.server.host, config.server.port); let addr = format!("{}:{}", config.server.host, config.server.port);
eprintln!("Binding to {}...", addr); eprintln!("Binding to {}...", addr);
@ -193,7 +135,14 @@ async fn main() -> anyhow::Result<()> {
eprintln!("Server listening on {}", &addr); eprintln!("Server listening on {}", &addr);
tracing::info!("Server listening on {}", &addr); tracing::info!("Server listening on {}", &addr);
axum::serve(listener, app).await?; // into_make_service_with_connect_info makes ConnectInfo<SocketAddr> available
// to the client_ip_middleware so we can fall back to the peer address when no
// proxy header (X-Forwarded-For / X-Real-IP) is present.
axum::serve(
listener,
app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
)
.await?;
Ok(()) Ok(())
} }

17
backend/src/middleware/auth.rs
View file

@ -8,6 +8,7 @@ use axum::{
middleware::Next, middleware::Next,
response::Response, response::Response,
}; };
use mongodb::bson::oid::ObjectId;
pub async fn jwt_auth_middleware( pub async fn jwt_auth_middleware(
State(state): State<AppState>, State(state): State<AppState>,
@ -29,12 +30,26 @@ pub async fn jwt_auth_middleware(
let token = &auth_header[7..]; // Remove "Bearer " prefix let token = &auth_header[7..]; // Remove "Bearer " prefix
// Verify token // Verify signature and expiry.
let claims = state let claims = state
.jwt_service .jwt_service
.validate_token(token) .validate_token(token)
.map_err(|_| StatusCode::UNAUTHORIZED)?; .map_err(|_| StatusCode::UNAUTHORIZED)?;
// Reject tokens whose version is stale (e.g. issued before a password
// change). The user's current version is cached briefly so we don't hit
// Mongo on every request; a missing user (deleted) also means 401.
let user_oid = ObjectId::parse_str(&claims.sub).map_err(|_| StatusCode::UNAUTHORIZED)?;
let current_version = state
.token_version_cache
.get_or_load(&user_oid, &state.db)
.await
.map_err(|_| StatusCode::UNAUTHORIZED)?;
match current_version {
Some(v) if v == claims.token_version => {}
_ => return Err(StatusCode::UNAUTHORIZED),
}
// Add claims to request extensions for handlers to use // Add claims to request extensions for handlers to use
req.extensions_mut().insert(claims); req.extensions_mut().insert(claims);

137
backend/src/middleware/client_ip.rs Normal file
View file

@ -0,0 +1,137 @@
//! Resolves the originating client IP for each request and exposes it to
//! handlers via the [`ClientIp`] request extension.
//!
//! Resolution order (most-trusted first):
//! 1. `X-Forwarded-For` — first hop (the original client). Normogen is deployed
//! behind a reverse proxy on Solaria, so this is the primary source.
//! 2. `X-Real-IP` — common single-IP proxy header.
//! 3. The peer address from Axum's `ConnectInfo<SocketAddr>` (direct connection).
//! 4. `"0.0.0.0"` only if none of the above are present.
#![allow(dead_code)]
use axum::{
extract::ConnectInfo, extract::Request, http::HeaderMap, middleware::Next, response::Response,
};
use std::net::SocketAddr;
/// Header carrying the originating client chain (proxy-populated).
const X_FORWARDED_FOR: &str = "x-forwarded-for";
/// Header some proxies set to the single originating IP.
const X_REAL_IP: &str = "x-real-ip";
/// Fallback when no IP can be determined.
const UNKNOWN_IP: &str = "0.0.0.0";
/// Extractor carrying the resolved client IP, inserted by [`client_ip_middleware`].
#[derive(Debug, Clone)]
pub struct ClientIp(pub String);
impl ClientIp {
pub fn as_str(&self) -> &str {
&self.0
}
}
impl std::ops::Deref for ClientIp {
type Target = str;
fn deref(&self) -> &str {
&self.0
}
}
/// Resolve the client IP from request headers, falling back to the peer socket.
///
/// Pure and unit-testable: pass the headers and an optional `ConnectInfo`.
pub fn extract_client_ip(headers: &HeaderMap, conn: Option<&ConnectInfo<SocketAddr>>) -> String {
// X-Forwarded-For: "client, proxy1, proxy2" — the leftmost entry is the
// original client. Only validate it looks like an IP; take the first token.
if let Some(xff) = headers.get(X_FORWARDED_FOR).and_then(|h| h.to_str().ok()) {
if let Some(first) = xff.split(',').map(str::trim).find(|s| !s.is_empty()) {
return first.to_string();
}
}
// X-Real-IP: single IP.
if let Some(ip) = headers.get(X_REAL_IP).and_then(|h| h.to_str().ok()) {
let ip = ip.trim();
if !ip.is_empty() {
return ip.to_string();
}
}
// Direct peer address, when ConnectInfo is wired (see main.rs).
if let Some(info) = conn {
return info.0.ip().to_string();
}
UNKNOWN_IP.to_string()
}
/// Middleware that computes the client IP once and stashes it in request
/// extensions so handlers can pull it out with `Extension(ClientIp(..))`.
pub async fn client_ip_middleware(mut req: Request, next: Next) -> Response {
let conn = req.extensions().get::<ConnectInfo<SocketAddr>>();
let ip = extract_client_ip(req.headers(), conn);
req.extensions_mut().insert(ClientIp(ip));
next.run(req).await
}
#[cfg(test)]
mod tests {
use super::*;
use axum::extract::ConnectInfo;
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
fn headers() -> HeaderMap {
HeaderMap::new()
}
fn conn() -> ConnectInfo<SocketAddr> {
ConnectInfo(SocketAddr::new(
IpAddr::V4(Ipv4Addr::new(203, 0, 113, 7)),
12345,
))
}
#[test]
fn prefers_x_forwarded_for_first_hop() {
let mut h = headers();
h.insert(
X_FORWARDED_FOR,
"198.51.100.2, 10.0.0.1, 10.0.0.2".parse().unwrap(),
);
assert_eq!(extract_client_ip(&h, Some(&conn())), "198.51.100.2");
}
#[test]
fn falls_back_to_x_real_ip_when_no_xff() {
let mut h = headers();
h.insert(X_REAL_IP, "198.51.100.9".parse().unwrap());
assert_eq!(extract_client_ip(&h, Some(&conn())), "198.51.100.9");
}
#[test]
fn xff_takes_precedence_over_x_real_ip() {
let mut h = headers();
h.insert(X_FORWARDED_FOR, "198.51.100.2".parse().unwrap());
h.insert(X_REAL_IP, "10.0.0.99".parse().unwrap());
assert_eq!(extract_client_ip(&h, Some(&conn())), "198.51.100.2");
}
#[test]
fn uses_socket_when_no_proxy_headers() {
assert_eq!(extract_client_ip(&headers(), Some(&conn())), "203.0.113.7");
}
#[test]
fn unknown_when_nothing_available() {
assert_eq!(extract_client_ip(&headers(), None), UNKNOWN_IP);
}
#[test]
fn ignores_blank_xff_entries() {
let mut h = headers();
// Leading whitespace/empty entry should be skipped, not returned blank.
h.insert(X_FORWARDED_FOR, " , 10.0.0.5".parse().unwrap());
assert_eq!(extract_client_ip(&h, None), "10.0.0.5");
}
}

4
backend/src/middleware/mod.rs
View file

@ -1,7 +1,11 @@
pub mod auth; pub mod auth;
pub mod client_ip;
pub mod rate_limit; pub mod rate_limit;
pub use auth::jwt_auth_middleware; pub use auth::jwt_auth_middleware;
pub use client_ip::{client_ip_middleware, ClientIp};
// `extract_client_ip` is `pub` in the client_ip module and used by its own
// tests; handlers consume the resolved IP via the `ClientIp` extractor instead.
pub use rate_limit::general_rate_limit_middleware; pub use rate_limit::general_rate_limit_middleware;
// Simple security headers middleware // Simple security headers middleware

134
backend/src/models/refresh_token.rs
View file

@ -1,18 +1,24 @@
#![allow(dead_code)] #![allow(dead_code)]
#![allow(unused_imports)] use anyhow::Result;
use mongodb::bson::{oid::ObjectId, DateTime}; use base64::Engine;
use mongodb::{
bson::{doc, oid::ObjectId, DateTime},
Collection,
};
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
/// A persisted, rotated refresh token. Only the SHA-256 hash of the raw JWT
/// refresh token is ever stored — the plaintext lives only inside the signed
/// JWT handed to the client.
#[derive(Debug, Clone, Serialize, Deserialize)] #[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RefreshToken { pub struct RefreshToken {
#[serde(rename = "_id", skip_serializing_if = "Option::is_none")] #[serde(rename = "_id", skip_serializing_if = "Option::is_none")]
pub id: Option<ObjectId>, pub id: Option<ObjectId>,
#[serde(rename = "tokenId")]
pub token_id: String,
#[serde(rename = "userId")]
pub user_id: String,
#[serde(rename = "tokenHash")] #[serde(rename = "tokenHash")]
pub token_hash: String, pub token_hash: String,
#[serde(rename = "userId")]
pub user_id: String,
#[serde(rename = "expiresAt")] #[serde(rename = "expiresAt")]
pub expires_at: DateTime, pub expires_at: DateTime,
#[serde(rename = "createdAt")] #[serde(rename = "createdAt")]
@ -22,3 +28,119 @@ pub struct RefreshToken {
#[serde(rename = "revokedAt")] #[serde(rename = "revokedAt")]
pub revoked_at: Option<DateTime>, pub revoked_at: Option<DateTime>,
} }
/// SHA-256 the raw refresh token and base64-encode the digest. Two equal
/// tokens produce equal hashes, so lookups work; the plaintext is never stored.
pub fn hash_token(token: &str) -> String {
let digest = Sha256::digest(token.as_bytes());
base64::engine::general_purpose::STANDARD.encode(digest)
}
#[derive(Clone)]
pub struct RefreshTokenRepository {
collection: Collection<RefreshToken>,
}
impl RefreshTokenRepository {
pub fn new(db: &mongodb::Database) -> Self {
Self {
collection: db.collection("refresh_tokens"),
}
}
/// Persist a refresh token record from its raw JWT form. Hashes the token
/// before storage.
pub async fn create(
&self,
user_id: &str,
raw_token: &str,
expires_at: DateTime,
) -> Result<ObjectId> {
let now = DateTime::now();
let record = RefreshToken {
id: None,
token_hash: hash_token(raw_token),
user_id: user_id.to_string(),
expires_at,
created_at: now,
revoked: false,
revoked_at: None,
};
let id = self
.collection
.insert_one(record, None)
.await?
.inserted_id
.as_object_id()
.ok_or_else(|| anyhow::anyhow!("Failed to get inserted refresh token id"))?;
Ok(id)
}
/// Look up a token record by its raw JWT form. Returns `None` if not found.
/// Callers must still check `revoked` and `expires_at`.
pub async fn find_by_raw_token(&self, raw_token: &str) -> Result<Option<RefreshToken>> {
let hash = hash_token(raw_token);
let record = self
.collection
.find_one(doc! { "tokenHash": hash }, None)
.await?;
Ok(record)
}
/// Mark a single token record (by id) as revoked.
pub async fn revoke(&self, id: &ObjectId) -> Result<()> {
self.collection
.update_one(
doc! { "_id": id },
doc! {
"$set": {
"revoked": true,
"revokedAt": DateTime::now()
}
},
None,
)
.await?;
Ok(())
}
/// Revoke every active refresh token for a user. Called on credential
/// changes (password change / recovery) and explicit "logout everywhere".
pub async fn revoke_all_by_user(&self, user_id: &str) -> Result<()> {
self.collection
.update_many(
doc! { "userId": user_id, "revoked": false },
doc! {
"$set": {
"revoked": true,
"revokedAt": DateTime::now()
}
},
None,
)
.await?;
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn hash_token_is_deterministic() {
assert_eq!(hash_token("abc"), hash_token("abc"));
}
#[test]
fn hash_token_differs_for_different_input() {
assert_ne!(hash_token("abc"), hash_token("abd"));
}
#[test]
fn hash_token_is_base64_sha256_length() {
// SHA-256 = 32 bytes -> 44 base64 chars (standard alphabet, padded).
assert_eq!(hash_token("anything").len(), 44);
}
}

2
backend/test-phase28.sh
View file

@ -3,7 +3,7 @@
# Phase 2.8 Test Suite # Phase 2.8 Test Suite
# Tests Pill Identification, Drug Interactions, and Reminder System # Tests Pill Identification, Drug Interactions, and Reminder System
API_URL="http://localhost:8080/api" API_URL="http://localhost:6500/api"
TEST_USER="test_phase28@example.com" TEST_USER="test_phase28@example.com"
TEST_PASSWORD="TestPassword123!" TEST_PASSWORD="TestPassword123!"

416
backend/tests/auth_tests.rs
View file

@ -1,163 +1,309 @@
use reqwest::Client; //! Auth-flow integration tests.
//!
//! These build the full app in process (via `common::app_for_test`) against an
//! isolated MongoDB test database, so they exercise the real router, middleware,
//! and handlers. They require a live MongoDB; if one isn't reachable the helper
//! returns `None` and every test skips gracefully (see `skip_if_none`).
//!
//! Contracts verified here reflect the *actual* API (post P0):
//! POST /api/auth/register {email, username, password} -> 201 {token, refresh_token, ...}
//! POST /api/auth/login {email, password} -> 200 {token, refresh_token, ...}
//! POST /api/auth/refresh {refresh_token} -> 200 {token, refresh_token}
//! POST /api/auth/logout {refresh_token} -> 204
mod common;
use serde_json::{json, Value}; use serde_json::{json, Value};
const BASE_URL: &str = "http://127.0.0.1:8000"; /// When Mongo is unavailable the helper returns `None`; each test bails out
/// early (counts as a pass) so `cargo test` stays green without Mongo. CI
#[tokio::test] /// provides Mongo and runs them for real.
async fn test_health_check() { macro_rules! require_app {
let client = Client::new(); ($app:expr) => {
let response = client match $app {
.get(format!("{}/health", BASE_URL)) Some(x) => x,
.send() None => {
.await eprintln!("[integration] skipped (MongoDB unavailable)");
.expect("Failed to send request"); return;
}
assert_eq!(response.status(), 200); }
};
} }
#[tokio::test] #[tokio::test]
async fn test_ready_check() { async fn health_and_ready() {
let client = Client::new(); let (app, db_name) = require_app!(common::app_for_test().await);
let response = client
.get(format!("{}/ready", BASE_URL))
.send()
.await
.expect("Failed to send request");
assert_eq!(response.status(), 200); let (status, _) = common::send_json(&app, "GET", "/ready", None, None).await;
assert_eq!(status, 200);
let (status, body) = common::send_json(&app, "GET", "/health", None, None).await;
assert_eq!(status, 200);
assert_eq!(body["status"], "ok");
common::drop_test_db(&db_name).await;
} }
#[tokio::test] #[tokio::test]
async fn test_register_user() { async fn register_returns_token_and_refresh_token() {
let client = Client::new(); let (app, db_name) = require_app!(common::app_for_test().await);
let email = format!("test_{}@example.com", uuid::Uuid::new_v4()); let email = unique_email();
let payload = json!({ // Correct contract: { email, username, password } (NOT password_hash).
"email": email, let (status, body) = common::send_json(
"password_hash": "hashed_password_placeholder", &app,
"encrypted_recovery_phrase": "encrypted_phrase_placeholder", "POST",
"recovery_phrase_iv": "iv_placeholder", "/api/auth/register",
"recovery_phrase_auth_tag": "auth_tag_placeholder" Some(json!({ "email": email, "username": "tester", "password": "supersecret" })),
}); None,
)
.await;
assert_eq!(status, 201, "register should return 201, body: {body}");
assert!(body["token"].is_string(), "missing access token: {body}");
assert!(
body["refresh_token"].is_string(),
"missing refresh token: {body}"
);
assert_eq!(body["email"], email);
let response = client common::drop_test_db(&db_name).await;
.post(format!("{}/api/auth/register", BASE_URL))
.json(&payload)
.send()
.await
.expect("Failed to send request");
assert_eq!(response.status(), 200);
let json: Value = response.json().await.expect("Failed to parse JSON");
assert_eq!(json["email"], email);
assert!(json["user_id"].is_string());
} }
#[tokio::test] #[tokio::test]
async fn test_login() { async fn login_with_correct_password() {
let client = Client::new(); let (app, db_name) = require_app!(common::app_for_test().await);
let email = format!("test_{}@example.com", uuid::Uuid::new_v4()); let email = unique_email();
// First register a user register(&app, &email, "supersecret").await;
let register_payload = json!({
"email": email,
"password_hash": "hashed_password_placeholder",
"encrypted_recovery_phrase": "encrypted_phrase_placeholder",
"recovery_phrase_iv": "iv_placeholder",
"recovery_phrase_auth_tag": "auth_tag_placeholder"
});
let _reg_response = client // Correct contract: { email, password }.
.post(format!("{}/api/auth/register", BASE_URL)) let (status, body) = common::send_json(
.json(&register_payload) &app,
.send() "POST",
.await "/api/auth/login",
.expect("Failed to send request"); Some(json!({ "email": email, "password": "supersecret" })),
None,
)
.await;
assert_eq!(status, 200, "login should succeed, body: {body}");
assert!(body["token"].is_string());
assert!(body["refresh_token"].is_string());
// Now login common::drop_test_db(&db_name).await;
let login_payload = json!({
"email": email,
"password_hash": "hashed_password_placeholder"
});
let response = client
.post(format!("{}/api/auth/login", BASE_URL))
.json(&login_payload)
.send()
.await
.expect("Failed to send request");
assert_eq!(response.status(), 200);
let json: Value = response.json().await.expect("Failed to parse JSON");
assert!(json["access_token"].is_string());
assert!(json["refresh_token"].is_string());
assert_eq!(json["email"], email);
} }
#[tokio::test] #[tokio::test]
async fn test_get_profile_without_auth() { async fn login_with_wrong_password_is_rejected() {
let client = Client::new(); let (app, db_name) = require_app!(common::app_for_test().await);
let email = unique_email();
register(&app, &email, "supersecret").await;
let response = client let (status, body) = common::send_json(
.get(format!("{}/api/users/me", BASE_URL)) &app,
.send() "POST",
.await "/api/auth/login",
.expect("Failed to send request"); Some(json!({ "email": email, "password": "wrong-password" })),
None,
)
.await;
assert_eq!(status, 401, "wrong password should 401, body: {body}");
// Should return 401 Unauthorized without auth token common::drop_test_db(&db_name).await;
assert_eq!(response.status(), 401);
} }
#[tokio::test] #[tokio::test]
async fn test_get_profile_with_auth() { async fn protected_route_rejects_missing_token() {
let client = Client::new(); let (app, db_name) = require_app!(common::app_for_test().await);
let email = format!("test_{}@example.com", uuid::Uuid::new_v4());
// Register and login let (status, _) = common::send_json(&app, "GET", "/api/users/me", None, None).await;
let register_payload = json!({ assert_eq!(status, 401);
"email": email,
"password_hash": "hashed_password_placeholder",
"encrypted_recovery_phrase": "encrypted_phrase_placeholder",
"recovery_phrase_iv": "iv_placeholder",
"recovery_phrase_auth_tag": "auth_tag_placeholder"
});
client common::drop_test_db(&db_name).await;
.post(format!("{}/api/auth/register", BASE_URL)) }
.json(&register_payload)
.send() #[tokio::test]
.await async fn protected_route_accepts_valid_token() {
.expect("Failed to send request"); let (app, db_name) = require_app!(common::app_for_test().await);
let email = unique_email();
let login_payload = json!({
"email": email, let token = register(&app, &email, "supersecret").await;
"password_hash": "hashed_password_placeholder"
}); let (status, body) = common::send_json(&app, "GET", "/api/users/me", None, Some(&token)).await;
assert_eq!(status, 200, "profile fetch should succeed, body: {body}");
let login_response = client assert_eq!(body["email"], email);
.post(format!("{}/api/auth/login", BASE_URL))
.json(&login_payload) common::drop_test_db(&db_name).await;
.send() }
.await
.expect("Failed to send request"); #[tokio::test]
async fn refresh_rotates_and_revokes_old_token() {
let login_json: Value = login_response.json().await.expect("Failed to parse JSON"); let (app, db_name) = require_app!(common::app_for_test().await);
let access_token = login_json["access_token"] let email = unique_email();
.as_str()
.expect("No access token"); let _token = register(&app, &email, "supersecret").await;
let (_, body) = common::send_json(
// Get profile with auth token &app,
let response = client "POST",
.get(format!("{}/api/users/me", BASE_URL)) "/api/auth/login",
.header("Authorization", format!("Bearer {}", access_token)) Some(json!({ "email": email, "password": "supersecret" })),
.send() None,
.await )
.expect("Failed to send request"); .await;
let refresh_token = body["refresh_token"].as_str().unwrap().to_string();
assert_eq!(response.status(), 200);
// Rotate: exchange the refresh token for a new pair.
let json: Value = response.json().await.expect("Failed to parse JSON"); let (status, new_body) = common::send_json(
assert_eq!(json["email"], email); &app,
"POST",
"/api/auth/refresh",
Some(json!({ "refresh_token": refresh_token })),
None,
)
.await;
assert_eq!(status, 200, "refresh should succeed, body: {new_body}");
assert!(new_body["token"].is_string());
assert!(new_body["refresh_token"].is_string());
assert_ne!(
new_body["refresh_token"].as_str().unwrap(),
refresh_token,
"rotation must issue a new refresh token"
);
// The old refresh token must now be revoked (reuse detection).
let (status, _) = common::send_json(
&app,
"POST",
"/api/auth/refresh",
Some(json!({ "refresh_token": refresh_token })),
None,
)
.await;
assert_eq!(status, 401, "reused refresh token must be rejected");
common::drop_test_db(&db_name).await;
}
#[tokio::test]
async fn logout_revokes_refresh_token() {
let (app, db_name) = require_app!(common::app_for_test().await);
let email = unique_email();
register(&app, &email, "supersecret").await;
let (_, body) = common::send_json(
&app,
"POST",
"/api/auth/login",
Some(json!({ "email": email, "password": "supersecret" })),
None,
)
.await;
let refresh_token = body["refresh_token"].as_str().unwrap().to_string();
// Logout revokes the refresh token.
let (status, _) = common::send_json(
&app,
"POST",
"/api/auth/logout",
Some(json!({ "refresh_token": refresh_token })),
None,
)
.await;
assert_eq!(status, 204);
// The logged-out refresh token can no longer mint new tokens.
let (status, _) = common::send_json(
&app,
"POST",
"/api/auth/refresh",
Some(json!({ "refresh_token": refresh_token })),
None,
)
.await;
assert_eq!(status, 401);
common::drop_test_db(&db_name).await;
}
#[tokio::test]
async fn password_change_invalidates_existing_tokens() {
let (app, db_name) = require_app!(common::app_for_test().await);
let email = unique_email();
let access_token = register(&app, &email, "supersecret").await;
let (_, body) = common::send_json(
&app,
"POST",
"/api/auth/login",
Some(json!({ "email": email, "password": "supersecret" })),
None,
)
.await;
let refresh_token = body["refresh_token"].as_str().unwrap().to_string();
// Change the password (protected route).
let (status, _) = common::send_json(
&app,
"POST",
"/api/users/me/change-password",
Some(json!({ "current_password": "supersecret", "new_password": "newsupersecret" })),
Some(&access_token),
)
.await;
assert_eq!(status, 204);
// Old access token rejected within the token_version cache TTL.
let (status, _) =
common::send_json(&app, "GET", "/api/users/me", None, Some(&access_token)).await;
assert_eq!(
status, 401,
"old access token must be rejected after password change"
);
// Old refresh token revoked.
let (status, _) = common::send_json(
&app,
"POST",
"/api/auth/refresh",
Some(json!({ "refresh_token": refresh_token })),
None,
)
.await;
assert_eq!(
status, 401,
"old refresh token must be rejected after password change"
);
// New password works.
let (status, _) = common::send_json(
&app,
"POST",
"/api/auth/login",
Some(json!({ "email": email, "password": "newsupersecret" })),
None,
)
.await;
assert_eq!(status, 200);
common::drop_test_db(&db_name).await;
}
// ---- helpers ----
fn unique_email() -> String {
format!("test_{}@example.com", uuid::Uuid::new_v4())
}
/// Register a user and return the access token.
async fn register(app: &axum::Router, email: &str, password: &str) -> String {
let (status, body) = common::send_json(
app,
"POST",
"/api/auth/register",
Some(json!({ "email": email, "username": "tester", "password": password })),
None,
)
.await;
assert_eq!(status, 201, "register precondition failed, body: {body}");
let _: &Value = &body;
body["token"].as_str().unwrap().to_string()
} }

186
backend/tests/common/mod.rs Normal file
View file

@ -0,0 +1,186 @@
//! Shared integration-test helpers.
//!
//! These tests need a live MongoDB. Each test process targets a unique database
//! (`normogen_test_<random>`), so parallel `cargo test` runs don't collide, and
//! drops it on completion. When Mongo is unreachable the tests skip gracefully
//! (printing a note) so `cargo test` stays green on machines without Mongo — the
//! CI job provides Mongo and runs them for real.
use std::sync::Arc;
use axum::{body::Body, http::Request, Router};
use mongodb::Client;
use normogen_backend::{
app::build_app,
auth::{JwtService, TokenVersionCache},
config::{
Config, CorsConfig, DatabaseConfig, EncryptionConfig, Environment, JwtConfig, ServerConfig,
},
db::MongoDb,
models::{health_stats::HealthStatisticsRepository, refresh_token::RefreshTokenRepository},
security, services,
};
use serde_json::Value;
use tower::util::ServiceExt;
/// Unique test DB name per process. Suffixing with a UUID keeps concurrent test
/// runs (local + CI) from stomping on each other.
pub fn test_db_name() -> String {
format!("normogen_test_{}", uuid::Uuid::new_v4())
}
/// The Mongo URI to connect to during tests. Defaults to the local dev instance.
pub fn mongo_uri() -> String {
std::env::var("MONGODB_URI").unwrap_or_else(|_| "mongodb://localhost:27017".to_string())
}
/// Quick (~1s) reachability check so tests skip fast when Mongo is absent.
/// Builds a throwaway client with a short server-selection timeout and pings;
/// we don't use the real client afterwards (that's `MongoDb::new`).
pub async fn mongo_available() -> bool {
let mut opts = match mongodb::options::ClientOptions::parse(&mongo_uri()).await {
Ok(o) => o,
Err(_) => return false,
};
opts.server_selection_timeout = Some(std::time::Duration::from_secs(1));
opts.connect_timeout = Some(std::time::Duration::from_secs(1));
let client = match Client::with_options(opts) {
Ok(c) => c,
Err(_) => return false,
};
client
.database("admin")
.run_command(mongodb::bson::doc! { "ping": 1 }, None)
.await
.is_ok()
}
/// A Config suitable for tests: development environment (so insecure-secret
/// defaults are allowed), short JWT expiries, a test JWT secret.
pub fn test_config(db_name: &str) -> Config {
Config {
server: ServerConfig {
host: "127.0.0.1".to_string(),
port: 0, // not bound in-process; tests use Router::oneshot
},
database: DatabaseConfig {
uri: mongo_uri(),
database: db_name.to_string(),
},
jwt: JwtConfig {
secret: "test-secret-not-for-production".to_string(),
access_token_expiry_minutes: 15,
refresh_token_expiry_days: 7,
},
encryption: EncryptionConfig {
key: "test-encryption-key".to_string(),
},
cors: CorsConfig {
allowed_origins: vec!["http://localhost:3000".to_string()],
},
environment: Environment::Development,
}
}
/// Build the full app against a fresh, isolated test database.
///
/// Returns `(router, db_name)` so callers can drop the database when done. The
/// router is the exact same one served in production (all routes + middleware),
/// just driven in-process via `oneshot`.
pub async fn app_for_test() -> Option<(Router, String)> {
let db_name = test_db_name();
// Fast, bounded connectivity probe: if Mongo isn't reachable, skip the test
// in ~1s instead of waiting on `MongoDb::new`'s 10s server-selection
// timeout (which would hang `cargo test` on machines without Mongo).
if !mongo_available().await {
eprintln!(
"[integration] skipping: MongoDB unreachable at {}",
mongo_uri()
);
return None;
}
let db = match MongoDb::new(&mongo_uri(), &db_name).await {
Ok(db) => db,
Err(e) => {
eprintln!(
"[integration] skipping: MongoDB connect failed at {}: {}",
mongo_uri(),
e
);
return None;
}
};
let config = test_config(&db_name);
let jwt_service = JwtService::new(config.jwt.clone());
let database = db.get_database();
// Best-effort index creation (mirrors main.rs).
let _ = normogen_backend::db::DatabaseInitializer::new(database.clone())
.initialize()
.await;
let token_version_cache = Arc::new(TokenVersionCache::with_default_ttl());
let refresh_token_repo = Arc::new(RefreshTokenRepository::new(&database));
let audit_logger = security::AuditLogger::new(&database);
let session_manager = security::SessionManager::new(&database);
let account_lockout = security::AccountLockout::new(database.collection("users"), 5, 15, 1440);
let health_stats_repo = HealthStatisticsRepository::new(&database);
let interaction_service = Arc::new(services::InteractionService::new());
let state = normogen_backend::config::AppState {
db,
jwt_service,
config: config.clone(),
audit_logger: Some(audit_logger),
session_manager: Some(session_manager),
account_lockout: Some(account_lockout),
health_stats_repo: Some(health_stats_repo),
mongo_client: None,
interaction_service: Some(interaction_service),
token_version_cache,
refresh_token_repo: Some(refresh_token_repo),
};
Some((build_app(state), db_name))
}
/// Drop a test database (best-effort teardown).
pub async fn drop_test_db(db_name: &str) {
if let Ok(client) = Client::with_uri_str(&mongo_uri()).await {
let _ = client.database(db_name).drop(None).await;
}
}
/// Convenience: drive the router with a JSON request and return the status +
/// parsed JSON body.
pub async fn send_json(
app: &Router,
method: &str,
uri: &str,
body: Option<Value>,
auth_token: Option<&str>,
) -> (u16, Value) {
let mut builder = Request::builder().method(method).uri(uri);
if let Some(token) = auth_token {
builder = builder.header("Authorization", format!("Bearer {}", token));
}
let request = if let Some(json) = body {
builder
.header("content-type", "application/json")
.body(Body::from(serde_json::to_vec(&json).unwrap()))
.unwrap()
} else {
builder.body(Body::empty()).unwrap()
};
let response = app.clone().oneshot(request).await.unwrap();
let status = response.status().as_u16();
let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
.await
.unwrap_or_default();
let json: Value = serde_json::from_slice(&bytes).unwrap_or(Value::Null);
(status, json)
}

171
backend/tests/medication_tests.rs
View file

@ -1,61 +1,122 @@
// Basic medication integration tests //! Medication-endpoint integration tests.
// These tests verify the medication endpoints work correctly //!
//! In-process against an isolated MongoDB test DB (see `common`). When Mongo is
//! unreachable these skip gracefully. Verifies auth enforcement and an
//! authenticated create -> list flow with the actual API contract.
// Note: These tests require MongoDB to be running mod common;
// Run with: cargo test --test medication_tests
#[cfg(test)] use serde_json::json;
mod medication_tests {
use reqwest::Client;
use serde_json::json;
const BASE_URL: &str = "http://localhost:3000"; /// Skip when Mongo is unavailable (counts as a pass); CI provides Mongo.
macro_rules! require_app {
#[tokio::test] ($app:expr) => {
async fn test_create_medication_requires_auth() { match $app {
let client = Client::new(); Some(x) => x,
let response = client None => {
.post(format!("{}/api/medications", BASE_URL)) eprintln!("[integration] skipped (MongoDB unavailable)");
.json(&json!({ return;
"profile_id": "test-profile",
"name": "Test Medication",
"dosage": "10mg",
"frequency": "daily"
}))
.send()
.await
.expect("Failed to send request");
// Should return 401 since no auth token provided
assert_eq!(response.status(), 401);
} }
#[tokio::test]
async fn test_list_medications_requires_auth() {
let client = Client::new();
let response = client
.get(format!("{}/api/medications", BASE_URL))
.send()
.await
.expect("Failed to send request");
// Should return 401 since no auth token provided
assert_eq!(response.status(), 401);
}
#[tokio::test]
async fn test_get_medication_requires_auth() {
let client = Client::new();
let response = client
.get(format!(
"{}/api/medications/507f1f77bcf86cd799439011",
BASE_URL
))
.send()
.await
.expect("Failed to send request");
// Should return 401 since no auth token provided
assert_eq!(response.status(), 401);
} }
};
}
#[tokio::test]
async fn create_medication_requires_auth() {
let (app, db_name) = require_app!(common::app_for_test().await);
let (status, _) = common::send_json(
&app,
"POST",
"/api/medications",
Some(
json!({ "name": "Test Med", "dosage": "10mg", "frequency": "daily", "route": "oral" }),
),
None,
)
.await;
assert_eq!(status, 401);
common::drop_test_db(&db_name).await;
}
#[tokio::test]
async fn list_medications_requires_auth() {
let (app, db_name) = require_app!(common::app_for_test().await);
let (status, _) = common::send_json(&app, "GET", "/api/medications", None, None).await;
assert_eq!(status, 401);
common::drop_test_db(&db_name).await;
}
#[tokio::test]
async fn get_medication_requires_auth() {
let (app, db_name) = require_app!(common::app_for_test().await);
let (status, _) = common::send_json(
&app,
"GET",
"/api/medications/507f1f77bcf86cd799439011",
None,
None,
)
.await;
assert_eq!(status, 401);
common::drop_test_db(&db_name).await;
}
#[tokio::test]
async fn authenticated_user_can_create_and_list_medication() {
let (app, db_name) = require_app!(common::app_for_test().await);
let email = unique_email();
// Register and grab the access token.
let (status, body) = common::send_json(
&app,
"POST",
"/api/auth/register",
Some(json!({ "email": email, "username": "tester", "password": "supersecret" })),
None,
)
.await;
assert_eq!(status, 201);
let token = body["token"].as_str().unwrap().to_string();
// Create a medication (name/dosage/frequency/route are all required).
let (status, body) = common::send_json(
&app,
"POST",
"/api/medications",
Some(json!({
"name": "Ibuprofen",
"dosage": "200mg",
"frequency": "as needed",
"route": "oral"
})),
Some(&token),
)
.await;
assert!(
status == 200 || status == 201,
"create should succeed, body: {body}"
);
// List medications for the user — should include the one we just created.
let (status, body) =
common::send_json(&app, "GET", "/api/medications", None, Some(&token)).await;
assert_eq!(status, 200, "list should succeed, body: {body}");
let empty = Vec::new();
let arr = body.as_array().unwrap_or(&empty);
assert!(
!arr.is_empty(),
"list should contain the created medication"
);
common::drop_test_db(&db_name).await;
}
fn unique_email() -> String {
format!("test_{}@example.com", uuid::Uuid::new_v4())
} }

14
docs/AI_AGENT_GUIDE.md
View file

@ -82,7 +82,7 @@ normogen/
### Backend Architecture ### Backend Architecture
#### Technology Stack #### Technology Stack
- **Language**: Rust 1.93 - **Language**: Rust (edition 2021)
- **Web Framework**: Axum 0.7 (async, tower-based) - **Web Framework**: Axum 0.7 (async, tower-based)
- **Database**: MongoDB 7.0 - **Database**: MongoDB 7.0
- **Authentication**: JWT (jsonwebtoken 9) - **Authentication**: JWT (jsonwebtoken 9)
@ -322,7 +322,7 @@ docker compose up -d
docker compose logs -f backend docker compose logs -f backend
# Check health # Check health
curl http://localhost:8000/health curl http://localhost:6500/health
``` ```
#### Production (Solaria) #### Production (Solaria)
@ -375,10 +375,12 @@ docker compose -f docker-compose.prod.yml up -d
- Lab results storage - Lab results storage
- OpenFDA integration for drug data - OpenFDA integration for drug data
### In Progress 🚧 ### Implemented ✅
- Drug interaction checking (Phase 2.8) - Drug interaction checking (Phase 2.8) — `/api/interactions/check`, `/check-new`
- Automated reminder system
- Frontend integration with backend ### In Progress / Not Started 🚧
- Automated reminder system (Phase 2.8 stretch)
- Frontend integration with backend (Phase 3)
### Planned 📋 ### Planned 📋
- Medication refill tracking - Medication refill tracking

253
docs/COMPLETION_REPORT.md
View file

@ -1,253 +0,0 @@
# Documentation Tasks - Completion Report
**Date**: 2026-03-09
**Task**: Analyze project, reorganize documentation, add AI agent guides
**Status**: ✅ COMPLETE
---
## 📋 Tasks Completed
### Task 1: Project Analysis
✅ Analyzed Normogen monorepo structure
- Backend: Rust + Axum + MongoDB
- Frontend: React + TypeScript + Material-UI
- Current Phase: 2.8 (Drug Interactions)
- Backend: ~91% complete, Frontend: ~10% complete
### Task 2: Documentation Reorganization
✅ Reorganized 71 documentation files into logical folders
**Structure Created**:
```
docs/
├── product/ (5 files) - Project overview, roadmap, status
├── implementation/ (36 files) - Phase plans, specs, progress
├── testing/ (9 files) - Test scripts, results
├── deployment/ (11 files) - Deployment guides, scripts
├── development/ (10 files) - Git workflow, CI/CD
├── archive/ (0 files) - For future use
└── README.md (index) - Main documentation index
```
**Files Created**:
- docs/README.md (main index)
- docs/product/README.md
- docs/implementation/README.md
- docs/testing/README.md
- docs/deployment/README.md
- docs/development/README.md
- docs/REORGANIZATION_SUMMARY.md
**Results**:
- ✅ Zero documentation files in root directory
- ✅ All files organized by purpose
- ✅ Navigation guides created for all directories
- ✅ Cross-references and links added
### Task 3: AI Agent Documentation
✅ Created comprehensive AI agent documentation suite
**Files Created**:
1. **docs/AI_AGENT_GUIDE.md** (17KB)
- Quick start overview
- Repository structure
- Key concepts (backend/frontend architecture)
- Common workflows with code examples
- Testing, deployment, security guidelines
- AI agent-specific tips and checklists
2. **docs/AI_QUICK_REFERENCE.md** (2.5KB)
- Essential commands
- Key file locations
- Code patterns
- Current status
3. **.cursorrules** (8.5KB)
- Project rules for AI IDEs (Cursor, Copilot)
- Code style rules (Rust & TypeScript)
- Authentication, API design, testing rules
- Common patterns and checklists
4. **.gooserules** (3.5KB)
- Goose-specific rules and workflows
- Tool usage patterns
- Task management guidelines
- Project-specific context
5. **docs/AI_DOCS_SUMMARY.md**
- Explanation of all AI documentation
- How to use each document
- Learning paths
- Maintenance guidelines
6. **docs/FINAL_SUMMARY.md**
- Complete overview of all work done
- Statistics and impact
- Next steps
---
## 📊 Impact Summary
### Documentation Reorganization
- Files moved: 71
- Directories created: 6
- README files: 6
- Time: ~15 minutes
- Root files before: 71
- Root files after: 0
### AI Agent Documentation
- Files created: 5
- Total size: ~31.5KB
- Time: ~20 minutes
- Coverage: Complete (quick ref to comprehensive)
### Total Impact
- **Total files organized/created**: 82
- **Total documentation**: ~40KB
- **Total time**: ~35 minutes
- **Repository cleanliness**: 100% (0 docs in root)
---
## ✅ Success Criteria - All Met
### Documentation Reorganization
- [x] All documentation files moved from root
- [x] Logical folder structure created
- [x] README files for navigation
- [x] Cross-references added
- [x] Root README updated
- [x] Zero clutter in root
### AI Agent Documentation
- [x] Comprehensive guide created
- [x] Quick reference available
- [x] Project rules for AI IDEs
- [x] Goose-specific rules
- [x] Summary documentation
- [x] Integrated into docs/ structure
---
## 🎯 Benefits Achieved
### For the Project
✅ Clean, organized repository
✅ Logical documentation structure
✅ Better navigation and discoverability
✅ Improved onboarding experience
✅ Easier long-term maintenance
### For AI Agents
✅ Faster onboarding (5 min to understand project)
✅ Consistent code patterns and conventions
✅ Fewer errors (avoid common pitfalls)
✅ Better context (what's implemented/planned)
✅ Proper testing workflows
✅ Good commit message practices
### For Human Developers
✅ Easier AI collaboration
✅ Clear convention documentation
✅ Quick reference for common tasks
✅ Better project understanding
✅ Maintainable codebase standards
---
## 📁 Key Files Reference
### Main Documentation
- **[docs/README.md](./README.md)** - Documentation index
- **[docs/AI_AGENT_GUIDE.md](./AI_AGENT_GUIDE.md)** - Comprehensive AI guide
- **[docs/AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md)** - Quick reference
- **[docs/FINAL_SUMMARY.md](./FINAL_SUMMARY.md)** - Complete work summary
### AI Agent Rules
- **[.cursorrules](../.cursorrules)** - Project rules for AI IDEs
- **[.gooserules](../.gooserules)** - Goose-specific rules
### Organized Documentation
- **[docs/product/](./product/)** - Product overview, roadmap, status
- **[docs/implementation/](./implementation/)** - Phase plans, specs, progress
- **[docs/testing/](./testing/)** - Test scripts, results
- **[docs/deployment/](./deployment/)** - Deployment guides, scripts
- **[docs/development/](./development/)** - Git workflow, CI/CD
---
## 🚀 Next Steps
### Immediate (Ready to Commit)
```bash
git add .
git commit -m "docs(ai): reorganize documentation and add AI agent guides
- Reorganize 71 docs into logical folders (product, implementation, testing, deployment, development)
- Add comprehensive AI agent documentation (17KB guide + 2.5KB quick reference)
- Add .cursorrules for AI IDE assistants (Cursor, Copilot, etc.)
- Add .gooserules for goose agent
- Create README files for all documentation directories
- Update root README to point to organized structure
Benefits:
- Clean repository root (0 docs in root)
- Better navigation and discoverability
- AI agents can work more effectively
- Improved onboarding for new contributors"
```
### Post-Commit Actions
1. **Verify AI agent integration**:
- Test with Cursor/Copilot to ensure .cursorrules is read
- Test with goose to ensure .gooserules is followed
2. **Review documentation**:
- Check all links work
- Verify no important info is missing
- Get feedback from other contributors
3. **Maintain going forward**:
- Keep AI docs updated with architecture changes
- Update phase docs as progress is made
- Archive old documents when appropriate
---
## 📊 Statistics
| Metric | Value |
|--------|-------|
| Documentation files moved | 71 |
| Directories created | 6 |
| README files created | 6 |
| AI documentation files | 5 |
| Total documentation size | ~40KB |
| Time to complete | ~35 minutes |
| Root files before | 71 |
| Root files after | 0 |
| Repository cleanliness | 100% |
---
## ✅ Completion Status
**Overall Status**: ✅ COMPLETE
**Documentation Reorganization**: ✅ COMPLETE
**AI Agent Documentation**: ✅ COMPLETE
**Ready to Commit**: ✅ YES
---
**Completed**: 2026-03-09
**Total Time**: ~35 minutes
**Files Organized**: 71
**Files Created**: 11
**Documentation Added**: ~40KB
---
*All tasks completed successfully. Repository is ready for commit.*

319
docs/FINAL_SUMMARY.md
View file

@ -1,319 +0,0 @@
# Documentation Reorganization - Complete Summary
**Date**: 2026-03-09
**Tasks**:
1. Reorganize project documentation into logical folders
2. Create AI agent documentation for better repository navigation
---
## ✅ Part 1: Documentation Reorganization
### What Was Done
Moved **71 files** from the root directory into an organized structure under `docs/`.
### New Structure
```
docs/
├── product/ (5 files) - Project overview, roadmap, status
├── implementation/ (36 files) - Phase plans, specs, progress reports
├── testing/ (9 files) - Test scripts and results
├── deployment/ (11 files) - Deployment guides and scripts
├── development/ (10 files) - Git workflow, CI/CD
├── archive/ (0 files) - For future archival
└── README.md (index) - Main documentation index
```
### Files Created
- `docs/README.md` - Main documentation index
- `docs/product/README.md` - Product documentation guide
- `docs/implementation/README.md` - Implementation docs with phase tracking
- `docs/testing/README.md` - Testing documentation and scripts guide
- `docs/deployment/README.md` - Deployment guides and procedures
- `docs/development/README.md` - Development workflow and tools
- `docs/REORGANIZATION_SUMMARY.md` - Details of the reorganization
### Benefits
✅ Zero clutter in root directory
✅ Logical categorization by purpose
✅ Better navigation with README files
✅ Improved onboarding for new contributors
✅ Easier maintenance
---
## ✅ Part 2: AI Agent Documentation
### What Was Created
A comprehensive documentation suite to help AI agents (and humans) work effectively in this repository.
### Files Created
#### 1. **docs/AI_AGENT_GUIDE.md** (17KB)
Comprehensive guide covering:
- Quick start overview
- Repository structure
- Key concepts (backend/frontend architecture)
- Common workflows with code examples
- Running tests
- Deployment procedures
- Security guidelines
- Current implementation status
- Development guidelines
- AI agent-specific tips
- Checklists for AI agents
#### 2. **docs/AI_QUICK_REFERENCE.md** (2.5KB)
Essential commands and patterns:
- Essential commands (build, test, run)
- Key file locations
- Code patterns
- Current status
- Important warnings
#### 3. **.cursorrules** (8.5KB)
Project rules that AI IDEs automatically read:
- Project overview
- Technology stack
- File structure rules
- Code style rules (Rust & TypeScript)
- Authentication rules
- API design rules
- Testing rules
- Security rules
- Commit rules
- Common patterns
- Before committing checklist
#### 4. **.gooserules** (3.5KB)
Goose-specific rules and workflows:
- Agent configuration
- Tool usage patterns
- Task management
- Project-specific context
- Common workflows
- Testing guidelines
- Commit guidelines
#### 5. **docs/AI_DOCS_SUMMARY.md**
This summary file explaining:
- What documentation was created
- How to use each document
- Quick decision tree
- Key information for AI agents
- Learning paths
- Maintenance guidelines
---
## 📊 Statistics
### Documentation Reorganization
- Files moved: 71
- Directories created: 6
- README files created: 6
- Files remaining in root: 0
- Time to complete: ~15 minutes
### AI Agent Documentation
- Files created: 5
- Total documentation: ~31.5KB
- Coverage: Complete (from quick reference to comprehensive guide)
- Time to complete: ~20 minutes
### Total Impact
- **Total files organized/written**: 82
- **Total documentation created**: ~40KB
- **Total time**: ~35 minutes
- **Files in root**: 0 (from 71)
---
## 🎯 Key Benefits
### For the Project
✅ Clean repository root
✅ Organized documentation structure
✅ Better navigation and discoverability
✅ Improved onboarding experience
✅ Easier maintenance
### For AI Agents
✅ Faster onboarding (understand project in 5 minutes)
✅ Consistent code patterns
✅ Fewer errors (avoid common pitfalls)
✅ Better context (know what's implemented)
✅ Proper testing workflows
✅ Good commit messages
### For Human Developers
✅ Easier collaboration with AI agents
✅ Clear documentation of conventions
✅ Quick reference for common tasks
✅ Better project understanding
✅ Maintainable codebase standards
---
## 📁 Final File Structure
```
normogen/
├── docs/ # All documentation (reorganized + new)
│ ├── README.md # Main documentation index
│ ├── AI_AGENT_GUIDE.md # Comprehensive AI guide (17KB)
│ ├── AI_QUICK_REFERENCE.md # Quick reference (2.5KB)
│ ├── AI_DOCS_SUMMARY.md # This summary
│ ├── REORGANIZATION_SUMMARY.md # Reorganization details
│ ├── product/ # Product docs (5 files)
│ │ ├── README.md
│ │ ├── README.md (moved)
│ │ ├── ROADMAP.md (moved)
│ │ ├── STATUS.md (moved)
│ │ ├── introduction.md (moved)
│ │ └── encryption.md (moved)
│ ├── implementation/ # Implementation docs (36 files)
│ │ ├── README.md
│ │ ├── PHASE*.md files
│ │ ├── MEDICATION*.md files
│ │ └── FRONTEND*.md files
│ ├── testing/ # Testing docs (9 files)
│ │ ├── README.md
│ │ ├── test-*.sh scripts
│ │ └── API_TEST_RESULTS*.md
│ ├── deployment/ # Deployment docs (11 files)
│ │ ├── README.md
│ │ ├── DEPLOYMENT_GUIDE.md
│ │ ├── deploy-*.sh scripts
│ │ └── DOCKER*.md files
│ ├── development/ # Development docs (10 files)
│ │ ├── README.md
│ │ ├── COMMIT-INSTRUCTIONS.txt
│ │ ├── GIT-*.md files
│ │ └── FORGEJO-*.md files
│ └── archive/ # Empty (for future use)
├── .cursorrules # AI IDE rules (8.5KB)
├── .gooserules # Goose-specific rules (3.5KB)
├── README.md # Updated root README
├── backend/ # Rust backend
├── web/ # React frontend
├── mobile/ # Mobile (placeholder)
├── shared/ # Shared code (placeholder)
└── thoughts/ # Development notes
```
---
## 🚀 Next Steps
### Immediate (Ready to Commit)
1. ✅ All documentation files created and organized
2. ✅ Root README updated to point to new structure
3. ✅ Navigation guides created for all directories
4. ✅ AI agent documentation complete
### Recommended Actions
1. **Commit the changes**:
```bash
git add .
git commit -m "docs(ai): reorganize documentation and add AI agent guides
- Reorganize 71 docs into logical folders (product, implementation, testing, deployment, development)
- Add comprehensive AI agent documentation (17KB guide + 2.5KB quick reference)
- Add .cursorrules for AI IDE assistants
- Add .gooserules for goose agent
- Create README files for all documentation directories
- Update root README to point to organized structure"
```
2. **Test with AI agents**:
- Verify AI IDEs (Cursor, Copilot) read .cursorrules
- Test that goose follows .gooserules
- Ensure AI agents can find and use the documentation
3. **Review and refine**:
- Check if any important information is missing
- Verify all links work
- Update if patterns change
### Future Maintenance
- Keep AI_QUICK_REFERENCE.md updated with new commands
- Update AI_AGENT_GUIDE.md when architecture changes
- Maintain .cursorrules when conventions evolve
- Archive old phase documents when appropriate
---
## 📚 Quick Navigation
### For New Contributors
1. Start: [docs/README.md](./README.md)
2. Project overview: [docs/product/README.md](./product/README.md)
3. Current status: [docs/product/STATUS.md](./product/STATUS.md)
### For AI Agents
1. Quick start: [docs/AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md)
2. Comprehensive: [docs/AI_AGENT_GUIDE.md](./AI_AGENT_GUIDE.md)
3. Project rules: [.cursorrules](../.cursorrules)
### For Developers
1. Development workflow: [docs/development/README.md](./development/README.md)
2. Implementation details: [docs/implementation/README.md](./implementation/README.md)
3. Testing: [docs/testing/README.md](./testing/README.md)
### For Deployment
1. Deployment guide: [docs/deployment/DEPLOYMENT_GUIDE.md](./deployment/DEPLOYMENT_GUIDE.md)
2. Quick reference: [docs/deployment/QUICK_DEPLOYMENT_REFERENCE.md](./deployment/QUICK_DEPLOYMENT_REFERENCE.md)
---
## ✅ Success Criteria - All Met
### Documentation Reorganization
- [x] All 71 documentation files moved from root
- [x] Logical folder structure created (6 directories)
- [x] README files created for each folder
- [x] Cross-references and links added
- [x] Root README updated
- [x] Zero documentation files in root
### AI Agent Documentation
- [x] Comprehensive guide created (17KB)
- [x] Quick reference created (2.5KB)
- [x] Project rules for AI IDEs (.cursorrules)
- [x] Goose-specific rules (.gooserules)
- [x] Summary documentation created
- [x] All documentation integrated into docs/ structure
---
## 🎉 Summary
In approximately **35 minutes**, we:
1. **Reorganized** 71 documentation files into a logical, navigable structure
2. **Created** 11 new documentation files (6 READMEs + 5 AI docs)
3. **Wrote** ~40KB of comprehensive documentation
4. **Established** clear patterns for future documentation
5. **Enabled** AI agents to work more effectively in the repository
6. **Improved** the project for both AI and human contributors
The repository is now:
- ✅ **Clean**: No documentation clutter in root
- ✅ **Organized**: Logical folder structure
- ✅ **Navigable**: Clear paths to find information
- ✅ **Documented**: Comprehensive guides for all audiences
- ✅ **AI-Ready**: AI agents can understand and contribute effectively
---
**Documentation Reorganization & AI Docs: Complete ✅**
**Date**: 2026-03-09
**Total Time**: ~35 minutes
**Files Organized**: 71
**Files Created**: 11
**Total Documentation**: ~40KB
---
*Ready to commit. See "Next Steps" above for commit message.*

144
docs/README.md
View file

@ -1,97 +1,59 @@
### /home/asoliver/desarrollo/normogen/./docs/README.md # Normogen Documentation Index
```markdown
1: # Normogen Documentation Index
2:
3: Welcome to the Normogen project documentation. This directory contains all project documentation organized by category.
4:
5: ## 📁 Documentation Structure
6:
7: ### [Product](./product/)
8: Core product documentation and project overview.
9: - **[README.md](./product/README.md)** - Project overview and quick start guide
10: - **[ROADMAP.md](./product/ROADMAP.md)** - Development roadmap and milestones
11: - **[STATUS.md](./product/STATUS.md)** - Current project status
12: - **[introduction.md](./product/introduction.md)** - Project introduction and background
13: - **[encryption.md](./product/encryption.md)** - Encryption and security architecture
14:
15: ### [Implementation](./implementation/)
16: Phase-by-phase implementation plans, specs, and progress reports.
17: - **Phase 2.3** - JWT Authentication completion reports
18: - **Phase 2.4** - User management enhancements
19: - **Phase 2.5** - Access control implementation
20: - **Phase 2.6** - Security hardening
21: - **Phase 2.7** - Health data features (medications, statistics)
22: - **Phase 2.8** - Drug interactions and advanced features
23: - **Frontend** - Frontend integration plans and progress
24:
25: ### [Testing](./testing/)
26: Test scripts, test results, and testing documentation.
27: - **[API_TEST_RESULTS_SOLARIA.md](./testing/API_TEST_RESULTS_SOLARIA.md)** - API test results
28: - **test-api-endpoints.sh** - API endpoint testing script
29: - **test-medication-api.sh** - Medication API tests
30: - **test-mvp-phase-2.7.sh** - Phase 2.7 comprehensive tests
31: - **solaria-test.sh** - Solaria deployment testing
32: - **quick-test.sh** - Quick smoke tests
33:
34: ### [Deployment](./deployment/)
35: Deployment guides, Docker configuration, and deployment scripts.
36: - **[DEPLOYMENT_GUIDE.md](./deployment/DEPLOYMENT_GUIDE.md)** - Complete deployment guide
37: - **[DEPLOY_README.md](./deployment/DEPLOY_README.md)** - Deployment quick reference
38: - **[QUICK_DEPLOYMENT_REFERENCE.md](./deployment/QUICK_DEPLOYMENT_REFERENCE.md)** - Quick deployment commands
39: - **[DOCKER_DEPLOYMENT_IMPROVEMENTS.md](./deployment/DOCKER_DEPLOYMENT_IMPROVEMENTS.md)** - Docker optimization notes
40: - **deploy-and-test.sh** - Deploy and test automation
41: - **deploy-to-solaria.sh** - Solaria deployment script
42:
43: ### [Development](./development/)
44: Development workflow, Git processes, and CI/CD documentation.
45: - **[COMMIT-INSTRUCTIONS.txt](./development/COMMIT-INSTRUCTIONS.txt)** - Commit message guidelines
46: - **[FORGEJO-CI-CD-PIPELINE.md](./development/FORGEJO-CI-CD-PIPELINE.md)** - CI/CD pipeline documentation
47: - **[FORGEJO-RUNNER-UPDATE.md](./development/FORGEJO-RUNNER-UPDATE.md)** - Runner update notes
48: - **[GIT-STATUS.md](./development/GIT-STATUS.md)** - Git workflow reference
49: - **COMMIT-NOW.sh** - Quick commit automation
50:
51: ### [Archive](./archive/)
52: Historical documentation and reference materials.
53:
54: ## 🔍 Quick Links
55:
56: ### For New Contributors
57: 1. Start with [Product README](./product/README.md)
58: 2. Review the [ROADMAP](./product/ROADMAP.md)
59: 3. Check [STATUS.md](./product/STATUS.md) for current progress
60:
61: ### For Developers
62: 1. Read [DEPLOYMENT_GUIDE.md](./deployment/DEPLOYMENT_GUIDE.md)
63: 2. Review [COMMIT-INSTRUCTIONS.txt](./development/COMMIT-INSTRUCTIONS.txt)
64: 3. Check [Implementation](./implementation/) docs for feature specs
65:
66: ### For Testing
67: 1. Run [quick-test.sh](./testing/quick-test.sh) for smoke tests
68: 2. Use [test-api-endpoints.sh](./testing/test-api-endpoints.sh) for API testing
69: 3. Review [API_TEST_RESULTS_SOLARIA.md](./testing/API_TEST_RESULTS_SOLARIA.md) for test history
70:
71: ## 📊 Project Status
72:
73: - **Current Phase**: Phase 2.8 (Planning)
74: - **Backend**: ~91% complete
75: - **Frontend**: ~10% complete
76: - **Last Updated**: 2026-03-09
77:
78: ---
79:
80: *Documentation last reorganized: 2026-03-09*
```
Welcome to the Normogen project documentation. This directory contains all
project documentation organized by category.
## 📁 Documentation Structure
### [Product](./product/)
Core product documentation and project overview.
- **[README.md](./product/README.md)** - Project overview and quick start guide
- **[STATUS.md](./product/STATUS.md)** - Current project status
- **[ROADMAP.md](./product/ROADMAP.md)** - Development roadmap and milestones
- **[PROGRESS.md](./product/PROGRESS.md)** - Progress dashboard
- **[introduction.md](./product/introduction.md)** - Project introduction and background
- **[encryption.md](./product/encryption.md)** - Encryption and security architecture
### [Implementation](./implementation/)
Phase-by-phase implementation completion records (2.3 through 2.8, plus frontend).
See [implementation/README.md](./implementation/README.md) for the full list.
### [ADR](./adr/)
Architecture Decision Records — the "why" behind the major technical choices
(stack, schema, JWT, frontend, deployment).
### [Development](./development/)
Development workflow and CI/CD.
- **[CI-CD.md](./development/CI-CD.md)** - The Forgejo CI/CD pipeline (current)
- **[README.md](./development/README.md)** - Workflow and conventions
### [Testing](./testing/)
Test scripts and testing notes.
- **test-api-endpoints.sh** - API endpoint testing
- **test-medication-api.sh** - Medication API tests
- **solaria-test.sh** / **check-solaria-logs.sh** - Solaria deployment testing
- **quick-test.sh** - Quick smoke test
### [Deployment](./deployment/)
Deployment guides and scripts.
- **[DEPLOYMENT_GUIDE.md](./deployment/DEPLOYMENT_GUIDE.md)** - Complete deployment guide
- **deploy-to-solaria.sh** / **deploy-and-test-solaria.sh** - Solaria deployment scripts
### [Archive](./archive/)
Superseded and historical documentation kept for reference (phase plans, old CI
state, point-in-time test snapshots). Not current.
## 📊 Project Status
- **Backend**: Phase 2.x feature-complete (through drug interactions); security-hardened; deployed on Solaria.
- **Frontend**: Early stage (Login/Register + API/store layer; router not wired).
- **Tests**: 18 unit + 13 integration, CI-gated with MongoDB.
- See [product/STATUS.md](./product/STATUS.md) for the full breakdown.
- **Last Updated**: 2026-06-27
---
## 🤖 For AI Agents ## 🤖 For AI Agents
### Quick Reference
- **[AI Agent Quick Reference](./AI_QUICK_REFERENCE.md)** - Essential commands and patterns - **[AI Agent Quick Reference](./AI_QUICK_REFERENCE.md)** - Essential commands and patterns
- **[AI Agent Guide](./AI_AGENT_GUIDE.md)** - Comprehensive guide for working in this repository - **[AI Agent Guide](./AI_AGENT_GUIDE.md)** - Comprehensive guide for working in this repository
### Getting Started
1. Read [AI_QUICK_REFERENCE.md](./AI_QUICK_REFERENCE.md) for essential commands
2. Review [AI_AGENT_GUIDE.md](./AI_AGENT_GUIDE.md) for detailed workflows
3. Check [product/STATUS.md](./product/STATUS.md) for current progress
4. Follow patterns in existing code

138
docs/REORGANIZATION_SUMMARY.md
View file

@ -1,138 +0,0 @@
# Documentation Reorganization Summary
**Date**: 2026-03-09
**Task**: Reorganize project documentation into logical folders
## ✅ What Was Done
### Created Directory Structure
```
docs/
├── product/ # Product definition, features, roadmap
├── implementation/ # Phase plans, specs, progress reports
├── testing/ # Test scripts and results
├── deployment/ # Deployment guides and scripts
├── development/ # Git workflow, CI/CD, development tools
└── archive/ # Historical documentation (empty for now)
```
### Files Moved
#### Product (5 files)
- README.md
- ROADMAP.md
- STATUS.md
- introduction.md
- encryption.md
#### Implementation (36 files)
- Phase 2.3-2.8 completion reports and plans
- Medication management documentation
- Frontend integration plans
- Progress tracking files
#### Testing (9 files)
- API test scripts
- Test results (API_TEST_RESULTS_SOLARIA.md)
- Deployment test scripts
- Quick test scripts
#### Deployment (11 files)
- Deployment guides
- Docker improvements documentation
- Deployment automation scripts
#### Development (10 files)
- Git workflow documentation
- Commit guidelines
- CI/CD pipeline documentation
- Development scripts
### Files Created
#### Index Files
- **docs/README.md** - Main documentation index with navigation
- **docs/product/README.md** - Product documentation guide
- **docs/implementation/README.md** - Implementation docs with phase tracking
- **docs/testing/README.md** - Testing documentation and scripts guide
- **docs/deployment/README.md** - Deployment guides and procedures
- **docs/development/README.md** - Development workflow and tools
#### Updated Root README
- Simplified root README.md with links to organized documentation
## 📊 Statistics
- **Total files organized**: 71 files
- **Directories created**: 6 directories
- **README files created**: 6 index/guide files
- **Files moved**: 71 (100% of documentation files)
- **Files remaining in root**: 0 (all organized)
## 🎯 Benefits
### 1. **Clear Organization**
- Documentation is now categorized by purpose
- Easy to find specific types of information
- Logical flow for different user types
### 2. **Better Navigation**
- Each folder has its own README with context
- Main index provides overview of all documentation
- Cross-references between related documents
### 3. **Improved Onboarding**
- New contributors can find relevant info quickly
- Separate paths for developers, testers, and deployers
- Clear progression from product → implementation → deployment
### 4. **Maintainability**
- Easier to keep documentation organized
- Clear place to put new documentation
- Archive folder for historical documents
## 📝 How to Use
### For New Contributors
1. Start at [docs/README.md](../README.md)
2. Read [docs/product/README.md](./product/README.md) for project overview
3. Check [docs/product/STATUS.md](./product/STATUS.md) for current status
### For Developers
1. Review [docs/development/README.md](./development/README.md) for workflow
2. Check [docs/implementation/README.md](./implementation/README.md) for feature specs
3. Use [docs/testing/README.md](./testing/README.md) for testing guides
### For Deployment
1. Read [docs/deployment/DEPLOYMENT_GUIDE.md](./deployment/DEPLOYMENT_GUIDE.md)
2. Use scripts in [docs/deployment/](./deployment/)
3. Check [docs/deployment/README.md](./deployment/README.md) for reference
## 🔄 Next Steps
### Optional Improvements
- [ ] Add timestamps to old phase documents
- [ ] Consolidate duplicate Phase 2.7 documents
- [ ] Move very old documents to archive/
- [ ] Add search functionality to docs
- [ ] Create visual diagrams for architecture
### Maintenance
- Keep new documentation in appropriate folders
- Update README files when adding major documents
- Archive old documents when phases complete
## ✅ Success Criteria Met
- [x] All documentation files moved from root
- [x] Logical folder structure created
- [x] README/index files created for each folder
- [x] Cross-references and links added
- [x] Root README updated to point to new structure
- [x] Zero documentation files remaining in root directory
---
**Reorganization Complete**: 2026-03-09
**Total Time**: ~15 minutes
**Files Organized**: 71 files across 6 directories

24
docs/adr/README.md Normal file
View file

@ -0,0 +1,24 @@
# Architecture Decision Records
This directory holds the project's decision records — the "why" behind the
major technical choices. These were originally written during Phase 1 research
(dated Jan–Feb 2026) and moved here from the old `thoughts/research/` tree during
the documentation reconciliation. They are historical context, not current specs.
## Decisions
| Record | Topic |
|--------|-------|
| [tech-stack-decision.md](./tech-stack-decision.md) | Master stack choice: Rust/Axum backend, React frontend, MongoDB, JWT |
| [mongodb-schema-decision.md](./mongodb-schema-decision.md) | Document model + at-rest encryption approach |
| [jwt-authentication-decision.md](./jwt-authentication-decision.md) | JWT access/refresh tokens, recovery phrases |
| [frontend-decision-summary.md](./frontend-decision-summary.md) | React (web) + React Native (mobile, future) split |
| [state-management-decision.md](./state-management-decision.md) | Client state — *superseded*: decision was Redux Toolkit, **actual code uses Zustand** |
| [monorepo-structure.md](./monorepo-structure.md) | Repository layout (`backend/`, `web/`, `mobile/`, `docs/`) |
| [backend-deployment-constraints.md](./backend-deployment-constraints.md) | Deployment requirements (Solaria, Docker) |
| [mobile-health-frameworks-data.md](./mobile-health-frameworks-data.md) | HealthKit / Health Connect data-type reference (for future mobile work) |
| [android-health-connect-data-types.md](./android-health-connect-data-types.md) | Android Health Connect data types |
> **Note**: Where a decision diverges from the implemented code (e.g. state
> management), the code is the source of truth and the ADR is kept only as
> historical record of the reasoning at the time.

0
thoughts/research/2026-01-12-android-health-connect-data-types-research.md → docs/adr/android-health-connect-data-types.md
View file

0
thoughts/research/2026-02-14-backend-deployment-constraints.md → docs/adr/backend-deployment-constraints.md
View file

0
thoughts/research/2026-02-14-frontend-decision-summary.md → docs/adr/frontend-decision-summary.md
View file

0
thoughts/research/2026-02-14-jwt-authentication-decision.md → docs/adr/jwt-authentication-decision.md
View file

0
thoughts/research/2026-01-05-mobile-health-frameworks-data.md → docs/adr/mobile-health-frameworks-data.md
View file

0
thoughts/research/2026-02-14-mongodb-schema-decision.md → docs/adr/mongodb-schema-decision.md
View file

0
thoughts/research/2026-02-14-monorepo-structure.md → docs/adr/monorepo-structure.md
View file

0
thoughts/research/2026-02-14-state-management-decision.md → docs/adr/state-management-decision.md
View file

0
thoughts/research/2026-02-14-tech-stack-decision.md → docs/adr/tech-stack-decision.md
View file

0
docs/testing/API_TEST_RESULTS_SOLARIA.md → docs/archive/API_TEST_RESULTS_SOLARIA.md
View file

0
CI-CD-FINAL-SOLUTION.md → docs/archive/CI-CD-FINAL-SOLUTION.md
View file

0
docs/deployment/DOCKER_IMPROVEMENTS_SUMMARY.md → docs/archive/DOCKER_IMPROVEMENTS_SUMMARY.md
View file

0
docs/implementation/PHASE28_COMPLETE_SPECS.md → docs/archive/PHASE28_COMPLETE_SPECS.md
View file

0
docs/implementation/PHASE28_PILL_IDENTIFICATION.md → docs/archive/PHASE28_PILL_IDENTIFICATION.md
View file

0
docs/implementation/PHASE28_PLAN.md → docs/archive/PHASE28_PLAN.md
View file

0
docs/implementation/PHASE_2.7_DEPLOYMENT_PLAN.md → docs/archive/PHASE_2.7_DEPLOYMENT_PLAN.md
View file

0
docs/implementation/PHASE_2.7_MVP_PRIORITIZED_PLAN.md → docs/archive/PHASE_2.7_MVP_PRIORITIZED_PLAN.md
View file

0
docs/implementation/PHASE_2.7_PLAN.md → docs/archive/PHASE_2.7_PLAN.md
View file

15
docs/archive/README.md Normal file
View file

@ -0,0 +1,15 @@
# Archive
Superseded and historical documentation, kept for reference but not current.
For the live, authoritative docs see the [main documentation index](../README.md).
Contents:
- **Phase plans** (`PHASE_2.7_PLAN.md`, `PHASE_2.7_MVP_PRIORITIZED_PLAN.md`,
`PHASE_2.7_DEPLOYMENT_PLAN.md`, `PHASE28_PLAN.md`, `PHASE28_COMPLETE_SPECS.md`,
`PHASE28_PILL_IDENTIFICATION.md`) — the original planning documents for phases
that are now implemented. See `../implementation/` for the completion records.
- **`API_TEST_RESULTS_SOLARIA.md`** — a point-in-time API test-run snapshot.
- **`DOCKER_IMPROVEMENTS_SUMMARY.md`** — historical Docker optimization notes.
- **`CI-CD-FINAL-SOLUTION.md`** — the CI/CD state as of 2026-03-18 (3 jobs, no
`test` job yet). For the *current* CI see `../development/CI-CD.md`.

45
docs/deployment/DEPLOYMENT_GUIDE.md
View file

@ -83,19 +83,19 @@ docker-compose logs -f backend
### Base URL ### Base URL
``` ```
http://solaria:8000 http://solaria:6500
``` ```
### Public Endpoints (No Auth) ### Public Endpoints (No Auth)
#### Health Check #### Health Check
```bash ```bash
curl http://solaria:8000/health curl http://solaria:6500/health
``` ```
#### Register #### Register
```bash ```bash
curl -X POST http://solaria:8000/api/auth/register \ curl -X POST http://solaria:6500/api/auth/register \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"email": "test@example.com", "email": "test@example.com",
@ -106,7 +106,7 @@ curl -X POST http://solaria:8000/api/auth/register \
#### Login #### Login
```bash ```bash
curl -X POST http://solaria:8000/api/auth/login \ curl -X POST http://solaria:6500/api/auth/login \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"email": "test@example.com", "email": "test@example.com",
@ -116,7 +116,7 @@ curl -X POST http://solaria:8000/api/auth/login \
#### Set Recovery Phrase #### Set Recovery Phrase
```bash ```bash
curl -X POST http://solaria:8000/api/auth/set-recovery-phrase \ curl -X POST http://solaria:6500/api/auth/set-recovery-phrase \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"email": "test@example.com", "email": "test@example.com",
@ -126,7 +126,7 @@ curl -X POST http://solaria:8000/api/auth/set-recovery-phrase \
#### Recover Password #### Recover Password
```bash ```bash
curl -X POST http://solaria:8000/api/auth/recover-password \ curl -X POST http://solaria:6500/api/auth/recover-password \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"email": "test@example.com", "email": "test@example.com",
@ -139,13 +139,13 @@ curl -X POST http://solaria:8000/api/auth/recover-password \
#### Get Profile #### Get Profile
```bash ```bash
curl http://solaria:8000/api/users/me \ curl http://solaria:6500/api/users/me \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
``` ```
#### Update Profile #### Update Profile
```bash ```bash
curl -X PUT http://solaria:8000/api/users/me \ curl -X PUT http://solaria:6500/api/users/me \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{ -d '{
@ -155,13 +155,13 @@ curl -X PUT http://solaria:8000/api/users/me \
#### Get Settings #### Get Settings
```bash ```bash
curl http://solaria:8000/api/users/me/settings \ curl http://solaria:6500/api/users/me/settings \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
``` ```
#### Update Settings #### Update Settings
```bash ```bash
curl -X PUT http://solaria:8000/api/users/me/settings \ curl -X PUT http://solaria:6500/api/users/me/settings \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{ -d '{
@ -171,7 +171,7 @@ curl -X PUT http://solaria:8000/api/users/me/settings \
#### Change Password #### Change Password
```bash ```bash
curl -X POST http://solaria:8000/api/users/me/change-password \ curl -X POST http://solaria:6500/api/users/me/change-password \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{ -d '{
@ -182,7 +182,7 @@ curl -X POST http://solaria:8000/api/users/me/change-password \
#### Delete Account #### Delete Account
```bash ```bash
curl -X DELETE http://solaria:8000/api/users/me \ curl -X DELETE http://solaria:6500/api/users/me \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{ -d '{
"confirmation": "DELETE_ACCOUNT" "confirmation": "DELETE_ACCOUNT"
@ -191,7 +191,7 @@ curl -X DELETE http://solaria:8000/api/users/me \
#### Create Share #### Create Share
```bash ```bash
curl -X POST http://solaria:8000/api/shares \ curl -X POST http://solaria:6500/api/shares \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{ -d '{
@ -204,13 +204,13 @@ curl -X POST http://solaria:8000/api/shares \
#### List Shares #### List Shares
```bash ```bash
curl http://solaria:8000/api/shares \ curl http://solaria:6500/api/shares \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
``` ```
#### Update Share #### Update Share
```bash ```bash
curl -X PUT http://solaria:8000/api/shares/SHARE_ID \ curl -X PUT http://solaria:6500/api/shares/SHARE_ID \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{ -d '{
@ -220,13 +220,13 @@ curl -X PUT http://solaria:8000/api/shares/SHARE_ID \
#### Delete Share #### Delete Share
```bash ```bash
curl -X DELETE http://solaria:8000/api/shares/SHARE_ID \ curl -X DELETE http://solaria:6500/api/shares/SHARE_ID \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
``` ```
#### Check Permission #### Check Permission
```bash ```bash
curl -X POST http://solaria:8000/api/permissions/check \ curl -X POST http://solaria:6500/api/permissions/check \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{ -d '{
@ -237,19 +237,19 @@ curl -X POST http://solaria:8000/api/permissions/check \
#### Get Sessions (NEW) #### Get Sessions (NEW)
```bash ```bash
curl http://solaria:8000/api/sessions \ curl http://solaria:6500/api/sessions \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
``` ```
#### Revoke Session (NEW) #### Revoke Session (NEW)
```bash ```bash
curl -X DELETE http://solaria:8000/api/sessions/SESSION_ID \ curl -X DELETE http://solaria:6500/api/sessions/SESSION_ID \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
``` ```
#### Revoke All Sessions (NEW) #### Revoke All Sessions (NEW)
```bash ```bash
curl -X DELETE http://solaria:8000/api/sessions/all \ curl -X DELETE http://solaria:6500/api/sessions/all \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
``` ```
@ -309,8 +309,9 @@ JWT_SECRET=your-super-secret-jwt-key-min-32-chars
MONGODB_URI=mongodb://mongodb:27017 MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE=normogen MONGODB_DATABASE=normogen
RUST_LOG=info RUST_LOG=info
SERVER_PORT=8000 NORMOGEN_PORT=6500
SERVER_HOST=0.0.0.0 NORMOGEN_HOST=0.0.0.0
APP_ENVIRONMENT=production
``` ```
## Security Features (Phase 2.6) ## Security Features (Phase 2.6)

175
docs/deployment/DEPLOY_README.md
View file

@ -1,175 +0,0 @@
# Normogen Deployment to Solaria
## Quick Start
### 1. Deploy to Solaria
```bash
./deploy-to-solaria.sh
```
This script will:
- Push latest changes to git
- Connect to Solaria via SSH
- Clone/update the repository
- Build and start Docker containers
- Show deployment status
### 2. Test All API Endpoints
```bash
./test-api-endpoints.sh
```
This will test:
- Health check
- Authentication (register, login)
- User management (profile, settings)
- Password recovery
- Share management
- Permissions
- Session management
### 3. Check Server Logs
```bash
./check-solaria-logs.sh
```
## Server Information
- **Hostname:** solaria (10.0.10.30)
- **User:** alvaro
- **Remote Directory:** /home/alvaro/normogen
- **API Port:** 8000
- **Base URL:** http://solaria:8000
## What's New in Phase 2.6
### Security Features
✅ **Session Management**
- Track sessions across devices
- Revoke specific or all sessions
- Automatic cleanup
✅ **Audit Logging**
- Log all security events
- Query by user or system-wide
- Track authentication, data access, modifications
✅ **Account Lockout**
- Brute-force protection
- Progressive lockout durations
- Automatic reset on successful login
✅ **Security Headers**
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- X-XSS-Protection: 1; mode=block
- Strict-Transport-Security
- Content-Security-Policy
### New API Endpoints
- `GET /api/sessions` - List all active sessions
- `DELETE /api/sessions/:id` - Revoke specific session
- `DELETE /api/sessions/all` - Revoke all sessions
## Deployment Checklist
- [x] Phase 2.6 implementation complete
- [x] Code compiles successfully
- [x] All changes committed to git
- [x] Deployment scripts created
- [x] API test scripts created
- [ ] Deploy to Solaria
- [ ] Run API tests
- [ ] Verify all endpoints working
- [ ] Check logs for errors
## Troubleshooting
### Connection Issues
```bash
# Test SSH connection
ssh alvaro@solaria
# Check if Docker is running
ssh alvaro@solaria "docker ps"
```
### Container Issues
```bash
# SSH to server
ssh alvaro@solaria
# Check containers
cd ~/normogen/backend
docker-compose ps
# View logs
docker-compose logs backend
# Restart
docker-compose restart
```
### API Not Responding
```bash
# Check if port 8000 is accessible
curl http://solaria:8000/health
# Check firewall
ssh alvaro@solaria "sudo ufw status"
```
## Files Created
1. `deploy-to-solaria.sh` - Automated deployment script
2. `test-api-endpoints.sh` - Comprehensive API testing
3. `check-solaria-logs.sh` - Server log viewer
4. `DEPLOYMENT_GUIDE.md` - Detailed deployment documentation
5. `DEPLOY_README.md` - This file
## Next Steps After Deployment
1. ✅ Verify deployment successful
2. ✅ Test all API endpoints
3. ✅ Check for any errors in logs
4. ⏳ Integrate session management into auth flow
5. ⏳ Implement proper rate limiting
6. ⏳ Add comprehensive tests
7. ⏳ Begin Phase 2.7
## Architecture
```
┌─────────────────────────────────────┐
│ Solaria Server │
│ ┌──────────────────────────────┐ │
│ │ Docker Compose │ │
│ │ ┌────────────────────────┐ │ │
│ │ │ Backend Container │ │ │
│ │ │ - Rust/Axum API │ │ │
│ │ │ - Port 8000 │ │ │
│ │ └────────────────────────┘ │ │
│ │ ┌────────────────────────┐ │ │
│ │ │ MongoDB Container │ │ │
│ │ │ - Port 27017 │ │ │
│ │ └────────────────────────┘ │ │
│ └──────────────────────────────┘ │
└─────────────────────────────────────┘
↑
│ SSH + Git
│
┌────────┴────────┐
│ Local Machine │
│ - Development │
│ - Git Push │
└─────────────────┘
```
## Support
For detailed information:
- See `DEPLOYMENT_GUIDE.md` for comprehensive docs
- See `PHASE_2.6_COMPLETION.md` for implementation details
- See `STATUS.md` for overall project status
Ready to deploy? Run: `./deploy-to-solaria.sh`

512
docs/deployment/DOCKER_DEPLOYMENT_IMPROVEMENTS.md
View file

@ -1,512 +0,0 @@
# 🐳 Docker Deployment Improvements for Normogen Backend
## Executive Summary
I've created **production-ready Docker configurations** that fix all current deployment issues. The new setup includes health checks, security hardening, resource limits, and automated deployment.
---
## 🔴 Critical Issues Found in Current Setup
### 1. **Binary Path Problem** ⚠️ CRITICAL
- **Current:** `CMD ["./normogen-backend"]` in Dockerfile
- **Issue:** Incorrect binary path relative to WORKDIR
- **Impact:** Container fails to start with "executable not found"
- **Fix:** Changed to `ENTRYPOINT ["/app/normogen-backend"]`
### 2. **No Health Checks** ⚠️ CRITICAL
- **Current:** No HEALTHCHECK directive or docker-compose health checks
- **Issue:** Failing containers aren't detected automatically
- **Impact:** Silent failures, no automatic recovery
- **Fix:** Added health checks every 30s to both services
### 3. **Missing Startup Dependencies** ⚠️ CRITICAL
- **Current:** Backend starts immediately without waiting for MongoDB
- **Issue:** Connection failures on startup
- **Impact:** Unreliable application startup
- **Fix:** Added `condition: service_healthy` dependency
### 4. **Running as Root** ⚠️ SECURITY VULNERABILITY
- **Current:** Container runs as root user
- **Issue:** Security vulnerability, violates best practices
- **Impact:** Container breakout risks
- **Fix:** Created non-root user "normogen" (UID 1000)
### 5. **No Resource Limits** ⚠️ OPERATIONS RISK
- **Current:** Unlimited CPU/memory usage
- **Issue:** Containers can consume all system resources
- **Impact:** Server crashes, resource exhaustion
- **Fix:** Added limits (1 CPU core, 512MB RAM)
### 6. **Poor Layer Caching** ⚠️ PERFORMANCE
- **Current:** Copies all source code before building
- **Issue:** Every change forces full rebuild
- **Impact:** 10+ minute build times
- **Fix:** Optimized layer caching (3x faster builds)
### 7. **Large Image Size** ⚠️ PERFORMANCE
- **Current:** Single-stage build includes build tools
- **Issue:** Image size ~1.5GB
- **Impact:** Slow pulls, wasted storage
- **Fix:** Multi-stage build (~400MB final image)
### 8. **Port Conflict** ✅ ALREADY FIXED
- **Current:** Port 8000 used by Portainer
- **Fix:** Changed to port 8001 (you already did this!)
### 9. **Duplicate Service Definitions** ⚠️ CONFIG ERROR
- **Current:** docker-compose.yml has duplicate service definitions
- **Issue:** Confusing and error-prone
- **Fix:** Clean, single definition per service
---
## ✅ Solutions Created
### New Files
#### 1. **backend/docker/Dockerfile.improved** ✨
Multi-stage build with:
- **Build stage:** Caches dependencies separately
- **Runtime stage:** Minimal Debian image
- **Non-root user:** normogen (UID 1000)
- **Health checks:** Every 30s with curl
- **Correct path:** `/app/normogen-backend`
- **Proper permissions:** Executable binary
- **Signal handling:** Proper ENTRYPOINT
#### 2. **backend/docker/docker-compose.improved.yml** ✨
Production-ready compose with:
- **Health checks:** Both MongoDB and backend
- **Dependency management:** Waits for MongoDB healthy
- **Resource limits:** 1 CPU core, 512MB RAM
- **Environment variables:** Proper variable expansion
- **Clean definitions:** No duplicates
- **Restart policy:** unless-stopped
- **Network isolation:** Dedicated bridge network
- **Volume management:** Named volumes for persistence
#### 3. **backend/deploy-to-solaria-improved.sh** ✨
Automated deployment script:
- **Local build:** Faster than building on server
- **Step-by-step:** Clear progress messages
- **Error handling:** `set -e` for fail-fast
- **Health verification:** Tests API after deployment
- **Color output:** Easy-to-read status messages
- **Rollback support:** Can stop old containers first
#### 4. **DOCKER_DEPLOYMENT_IMPROVEMENTS.md** ✨
This comprehensive guide!
---
## 📊 Before & After Comparison
### Dockerfile Comparison
```diff
# BEFORE (Single-stage, runs as root, wrong path)
FROM rust:1.93-slim
WORKDIR /app
COPY . .
RUN cargo build --release
- CMD ["./normogen-backend"] # ❌ Wrong path, relative
+ # No health check
+ # No user management
+ # Includes build tools (1.5GB image)
# AFTER (Multi-stage, non-root, correct path)
# Build stage
FROM rust:1.93-slim AS builder
WORKDIR /app
+ COPY Cargo.toml Cargo.lock ./ # Cache dependencies first
+ RUN mkdir src && echo "fn main() {}" > src/main.rs \
+ && cargo build --release && rm -rf src
COPY src ./src
RUN cargo build --release
# Runtime stage
FROM debian:bookworm-slim
+ RUN useradd -m -u 1000 normogen
WORKDIR /app
COPY --from=builder /app/target/release/normogen-backend /app/
+ RUN chown normogen:normogen /app/normogen-backend
+ USER normogen
+ HEALTHCHECK --interval=30s CMD curl -f http://localhost:8000/health || exit 1
+ ENTRYPOINT ["/app/normogen-backend"] # ✅ Correct absolute path
+ # Minimal image (~400MB)
```
### docker-compose Comparison
```diff
services:
backend:
- image: normogen-backend:runtime
+ build:
+ dockerfile: docker/Dockerfile.improved
ports:
- "8001:8000"
environment:
- JWT_SECRET: example_key_not_for_production # ❌ Hardcoded
+ JWT_SECRET: ${JWT_SECRET} # ✅ From environment
depends_on:
- - mongodb # ❌ No health check, starts immediately
+ mongodb:
+ condition: service_healthy # ✅ Waits for MongoDB healthy
+ healthcheck: # ✅ New
+ test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 10s
+ deploy: # ✅ New resource limits
+ resources:
+ limits:
+ cpus: '1.0'
+ memory: 512M
+ reservations:
+ cpus: '0.25'
+ memory: 128M
```
---
## 🚀 How to Deploy
### Option 1: Automated (Recommended) ⭐
```bash
# 1. Set your JWT secret (generate one securely)
export JWT_SECRET=$(openssl rand -base64 32)
# 2. Run the improved deployment script
./backend/deploy-to-solaria-improved.sh
```
That's it! The script will:
- Build the binary locally
- Create the directory structure on Solaria
- Set up environment variables
- Copy Docker files
- Stop old containers
- Start new containers
- Verify the deployment
### Option 2: Manual Step-by-Step
```bash
# 1. Build the binary locally (much faster than on server)
cd ~/normogen/backend
cargo build --release
# 2. Create directory structure on Solaria
ssh solaria 'mkdir -p /srv/normogen/docker'
# 3. Create .env file on Solaria
ssh solaria 'cat > /srv/normogen/.env << EOF
MONGODB_DATABASE=normogen
JWT_SECRET=your-super-secret-key-at-least-32-characters-long
RUST_LOG=info
SERVER_PORT=8000
SERVER_HOST=0.0.0.0
EOF'
# 4. Copy improved Docker files to Solaria
scp docker/Dockerfile.improved solaria:/srv/normogen/docker/
scp docker/docker-compose.improved.yml solaria:/srv/normogen/docker/
# 5. Stop old containers (if running)
ssh solaria 'cd /srv/normogen && docker compose down 2>/dev/null || true'
# 6. Start with new improved configuration
ssh solaria 'cd /srv/normogen && docker compose -f docker/docker-compose.improved.yml up -d'
# 7. Check container status
ssh solaria 'docker compose -f /srv/normogen/docker/docker-compose.improved.yml ps'
```
---
## 🧪 Verification Steps
After deployment, verify everything is working:
```bash
# 1. Check container is running
ssh solaria 'docker ps | grep normogen'
# Expected output:
# CONTAINER ID IMAGE STATUS
# abc123 normogen-backend:latest Up 2 minutes (healthy)
# def456 mongo:6.0 Up 2 minutes (healthy)
# 2. Check health status
ssh solaria 'docker inspect --format="{{.State.Health.Status}}" normogen-backend'
# Expected output: healthy
# 3. View recent logs
ssh solaria 'docker logs --tail 50 normogen-backend'
# 4. Test API health endpoint
curl http://solaria.solivarez.com.ar:8001/health
# Expected output: {"status":"ok"}
# 5. Test API readiness endpoint
curl http://solaria.solivarez.com.ar:8001/ready
# Expected output: {"status":"ready"}
# 6. Check resource usage
ssh solaria 'docker stats normogen-backend normogen-mongodb --no-stream'
# Expected: Memory < 512MB, CPU usage reasonable
```
---
## 📈 Benefits & Improvements
### 🚀 Performance
| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| **Build time** | ~10 min | ~3 min | **3x faster** |
| **Image size** | ~1.5 GB | ~400 MB | **4x smaller** |
| **Startup time** | Unreliable | Consistent | **100% reliable** |
| **Memory usage** | Unlimited | Max 512MB | **Controlled** |
### 🛡️ Reliability
- ✅ **Health checks** detect failures automatically every 30s
- ✅ **Proper dependencies** - backend waits for MongoDB
- ✅ **Automatic restart** on failure (unless-stopped policy)
- ✅ **Consistent startup** - no more connection race conditions
### 🔒 Security
- ✅ **Non-root user** - runs as normogen (UID 1000)
- ✅ **Minimal image** - no build tools in production
- ✅ **Reduced attack surface** - only runtime dependencies
- ✅ **Proper permissions** - binary owned by non-root user
### 👮 Operations
- ✅ **Automated deployment** - one-command deployment
- ✅ **Better logging** - easier debugging
- ✅ **Resource limits** - prevents resource exhaustion
- ✅ **Clear process** - documented procedures
- ✅ **Easy rollback** - simple to revert if needed
---
## 🔍 Troubleshooting
### Container keeps restarting
```bash
# Check detailed error logs
ssh solaria 'docker logs normogen-backend'
# Check the exit code
ssh solaria 'docker inspect normogen-backend | grep ExitCode'
# Check health check output
ssh solaria 'docker inspect --format="{{range .State.Health.Log}}{{.Output}}\n{{end}}" normogen-backend'
# Check if it's a database connection issue
ssh solaria 'docker logs normogen-backend | grep -i mongo'
```
**Common causes:**
- JWT_SECRET not set or too short
- MongoDB not ready yet
- Port conflicts
### Port conflicts
```bash
# Check what's using port 8001
ssh solaria 'netstat -tlnp | grep 8001'
# Or using ss (more modern)
ssh solaria 'ss -tlnp | grep 8001'
# Check Docker containers using the port
ssh solaria 'docker ps | grep 8001'
```
**Solution:** Stop the conflicting container or use a different port
### Database connection issues
```bash
# Verify MongoDB is healthy
ssh solaria 'docker exec normogen-mongodb mongosh --eval "db.adminCommand('ping')"'
# Expected output: { ok: 1 }
# Check if backend can reach MongoDB
ssh solaria 'docker exec normogen-backend ping -c 2 mongodb'
# Expected: 2 packets transmitted, 2 received
# Check backend logs for MongoDB errors
ssh solaria 'docker logs normogen-backend | grep -i mongodb'
```
**Common causes:**
- MongoDB not started yet
- Network issue between containers
- Wrong MongoDB URI
### Resource issues
```bash
# Check real-time resource usage
ssh solaria 'docker stats normogen-backend normogen-mongodb'
# Check disk usage
ssh solaria 'docker system df'
# Check container size
ssh solaria 'docker images | grep normogen'
```
**If resource limits are hit:**
- Increase memory limit in docker-compose.improved.yml
- Check for memory leaks in application
- Add more RAM to the server
### Deployment failures
```bash
# Check if files were copied correctly
ssh solaria 'ls -la /srv/normogen/docker/'
# Check if .env file exists
ssh solaria 'cat /srv/normogen/.env'
# Try manual deployment (see Option 2 above)
ssh solaria 'cd /srv/normogen && docker compose -f docker/docker-compose.improved.yml up -d'
```
---
## 📞 Quick Reference Commands
```bash
# ===== Deployment =====
# Deploy (automated)
JWT_SECRET=your-secret ./backend/deploy-to-solaria-improved.sh
# Generate secure JWT secret
openssl rand -base64 32
# ===== Monitoring =====
# View all container logs
ssh solaria 'docker compose -f /srv/normogen/docker/docker-compose.improved.yml logs -f'
# View backend logs only
ssh solaria 'docker logs -f normogen-backend'
# View MongoDB logs
ssh solaria 'docker logs -f normogen-mongodb'
# Check container status
ssh solaria 'docker compose -f /srv/normogen/docker/docker-compose.improved.yml ps'
# Check health status
ssh solaria 'docker inspect --format="{{.State.Health.Status}}" normogen-backend'
# Check resource usage
ssh solaria 'docker stats normogen-backend normogen-mongodb'
# ===== Control =====
# Restart services
ssh solaria 'docker compose -f /srv/normogen/docker/docker-compose.improved.yml restart'
# Restart backend only
ssh solaria 'docker restart normogen-backend'
# Stop services
ssh solaria 'docker compose -f /srv/normogen/docker/docker-compose.improved.yml down'
# Start services
ssh solaria 'docker compose -f /srv/normogen/docker/docker-compose.improved.yml up -d'
# ===== Updates =====
# Pull latest code and rebuild
ssh solaria 'cd /srv/normogen && docker compose -f docker/docker-compose.improved.yml up -d --build'
# View image sizes
ssh solaria 'docker images | grep normogen'
# Clean up old images
ssh solaria 'docker image prune -f'
```
---
## 🎯 What's Fixed Summary
| # | Issue | Severity | Status |
|---|-------|----------|--------|
| 1 | Binary path incorrect | 🔴 Critical | ✅ Fixed |
| 2 | No health checks | 🔴 Critical | ✅ Fixed |
| 3 | No startup dependencies | 🔴 Critical | ✅ Fixed |
| 4 | Running as root | 🔴 Security | ✅ Fixed |
| 5 | No resource limits | 🟡 Medium | ✅ Fixed |
| 6 | Poor layer caching | 🟡 Performance | ✅ Fixed |
| 7 | Large image size | 🟡 Performance | ✅ Fixed |
| 8 | Port 8000 conflict | ✅ Fixed | ✅ Fixed |
| 9 | Duplicate definitions | 🟡 Config | ✅ Fixed |
---
## 📋 Next Steps
### Immediate (Do Now)
1. ✅ Review the improved Docker files
2. ⏳ Set JWT_SECRET environment variable
3. ⏳ Deploy using the improved script
4. ⏳ Monitor health checks
5. ⏳ Test all API endpoints
### Short-term (This Week)
6. ⏳ Add application metrics (Prometheus)
7. ⏳ Set up automated MongoDB backups
8. ⏳ Add log aggregation (Loki/ELK)
9. ⏳ Consider secrets management (HashiCorp Vault)
### Long-term (This Month)
10. ⏳ CI/CD pipeline integration
11. ⏳ Multi-environment setup (dev/staging/prod)
12. ⏳ Blue-green deployment strategy
13. ⏳ Performance monitoring (Grafana)
---
## ✨ Summary
The improved Docker setup addresses **ALL current issues**:
✅ **Fixed binary path** - correct absolute path
✅ **Added health checks** - automatic failure detection
✅ **Non-root execution** - production security
✅ **Resource limits** - prevents exhaustion
✅ **Faster builds** - 3x improvement
✅ **Smaller image** - 4x reduction
✅ **Automated deployment** - one command
✅ **Better security** - minimal attack surface
**Status:** 🟢 Ready to deploy!
**Risk:** 🟢 Low (easy rollback)
**Time:** 🟢 5-10 minutes
**Impact:** 🟢 Eliminates all repeated failures
The new setup is **production-ready** and follows Docker best practices. It will completely eliminate the deployment failures you've been experiencing.
---
**Need help?** Check the troubleshooting section above or review the logs.
**Ready to deploy?** Run: `JWT_SECRET=$(openssl rand -base64 32) ./backend/deploy-to-solaria-improved.sh`

62
docs/deployment/QUICK_DEPLOYMENT_REFERENCE.md
View file

@ -1,62 +0,0 @@
# 🚀 Quick Deployment Reference
## Deploy to Solaria (Improved)
### One-Command Deployment
```bash
# Set JWT secret and deploy
JWT_SECRET=$(openssl rand -base64 32) ./backend/deploy-to-solaria-improved.sh
```
### What's Fixed
| Issue | Before | After |
|-------|--------|-------|
| Binary path | `./normogen-backend` (wrong) | `/app/normogen-backend` (correct) |
| Health checks | None | Every 30s |
| User | root | normogen (UID 1000) |
| Image size | ~1.5GB | ~400MB |
| Build time | ~10 min | ~3 min |
| Dependencies | None | Waits for MongoDB |
| Resources | Unlimited | 1 CPU, 512MB RAM |
### Files Created
1. **backend/docker/Dockerfile.improved** - Multi-stage build
2. **backend/docker/docker-compose.improved.yml** - Production-ready compose
3. **backend/deploy-to-solaria-improved.sh** - Automated deployment
4. **DOCKER_DEPLOYMENT_IMPROVEMENTS.md** - Complete guide
### Quick Commands
```bash
# View logs
ssh solaria 'docker logs -f normogen-backend'
# Check status
ssh solaria 'docker ps | grep normogen'
# Restart services
ssh solaria 'docker compose -f /srv/normogen/docker/docker-compose.improved.yml restart'
# Test API
curl http://solaria.solivarez.com.ar:8001/health
```
### Troubleshooting
```bash
# Container not starting?
ssh solaria 'docker logs normogen-backend'
# Port conflict?
ssh solaria 'netstat -tlnp | grep 8001'
# MongoDB issues?
ssh solaria 'docker exec normogen-mongodb mongosh --eval "db.adminCommand('ping')"'
```
---
**Ready?** Run: `JWT_SECRET=$(openssl rand -base64 32) ./backend/deploy-to-solaria-improved.sh`

11
docs/deployment/README.md
View file

@ -34,16 +34,17 @@ docker compose up -d
### Environment Configuration ### Environment Configuration
Required environment variables: Required environment variables:
- `DATABASE_URI` - MongoDB connection string - `MONGODB_URI` - MongoDB connection string
- `DATABASE_NAME` - Database name - `MONGODB_DATABASE` - Database name
- `JWT_SECRET` - JWT signing secret (min 32 chars) - `JWT_SECRET` - JWT signing secret (min 32 chars)
- `SERVER_HOST` - Server host (default: 0.0.0.0) - `NORMOGEN_HOST` - Server host (default: 0.0.0.0)
- `SERVER_PORT` - Server port (default: 8080) - `NORMOGEN_PORT` - Server port (default: 6500)
- `APP_ENVIRONMENT` - `development` (default) or `production`
- `RUST_LOG` - Log level (debug/info/warn) - `RUST_LOG` - Log level (debug/info/warn)
### Health Check ### Health Check
```bash ```bash
curl http://localhost:8000/health curl http://localhost:6500/health
``` ```
## 🌐 Deployment Environments ## 🌐 Deployment Environments

12
docs/deployment/deploy-and-test-solaria.sh Executable file → Normal file
View file

@ -25,12 +25,12 @@ if pgrep -f "normogen-backend" > /dev/null; then
sleep 2 sleep 2
fi fi
# Set environment # Set environment (the app reads NORMOGEN_* / MONGODB_* / APP_ENVIRONMENT)
export DATABASE_URI="mongodb://localhost:27017" export MONGODB_URI="mongodb://localhost:27017"
export DATABASE_NAME="normogen" export MONGODB_DATABASE="normogen"
export JWT_SECRET="test-secret-key" export JWT_SECRET="test-secret-key"
export SERVER_HOST="0.0.0.0" export NORMOGEN_HOST="0.0.0.0"
export SERVER_PORT="8080" export NORMOGEN_PORT="6500"
export RUST_LOG="debug" export RUST_LOG="debug"
# Build # Build
@ -54,7 +54,7 @@ fi
# Health check # Health check
echo "" echo ""
echo "Health check..." echo "Health check..."
curl -s http://localhost:8080/health curl -s http://localhost:6500/health
ENDSSH ENDSSH

10
docs/deployment/deploy-local-build.sh Executable file → Normal file
View file

@ -46,11 +46,11 @@ ENDSSH
echo "" echo ""
echo "Step 5: Starting backend on Solaria..." echo "Step 5: Starting backend on Solaria..."
ssh alvaro@solaria bash << 'ENDSSH' ssh alvaro@solaria bash << 'ENDSSH'
export DATABASE_URI="mongodb://localhost:27017" export MONGODB_URI="mongodb://localhost:27017"
export DATABASE_NAME="normogen" export MONGODB_DATABASE="normogen"
export JWT_SECRET="production-secret-key" export JWT_SECRET="production-secret-key"
export SERVER_HOST="0.0.0.0" export NORMOGEN_HOST="0.0.0.0"
export SERVER_PORT="8080" export NORMOGEN_PORT="6500"
export RUST_LOG="normogen_backend=debug,tower_http=debug,axum=debug" export RUST_LOG="normogen_backend=debug,tower_http=debug,axum=debug"
nohup ~/normogen-backend > ~/normogen-backend.log 2>&1 & nohup ~/normogen-backend > ~/normogen-backend.log 2>&1 &
@ -68,7 +68,7 @@ fi
echo "" echo ""
echo "Testing health endpoint..." echo "Testing health endpoint..."
sleep 2 sleep 2
curl -s http://localhost:8080/health curl -s http://localhost:6500/health
echo "" echo ""
ENDSSH ENDSSH

1
docs/deployment/deploy-to-solaria-manual.sh
View file

@ -1 +0,0 @@
${deployScript}

4
docs/deployment/deploy-to-solaria.sh
View file

@ -61,6 +61,6 @@ echo "========================================="
echo "Deployment complete!" echo "Deployment complete!"
echo "=========================================" echo "========================================="
echo "" echo ""
echo "API is available at: http://solaria:8000" echo "API is available at: http://solaria:6500"
echo "Health check: http://solaria:8000/health" echo "Health check: http://solaria:6500/health"
echo "" echo ""

56
docs/development/CI-CD.md Normal file
View file

@ -0,0 +1,56 @@
# CI/CD Pipeline
The CI pipeline runs on **Forgejo Actions** and is defined in
[`.forgejo/workflows/lint-and-build.yml`](../../.forgejo/workflows/lint-and-build.yml).
**Triggers**: push and pull request to `main` and `develop`.
## Jobs
Four jobs, each running in a `rust:latest` container on the `docker` runner:
| Job | Depends on | Command | Purpose |
|-----|-----------|---------|---------|
| `format` | — | `cargo fmt --all -- --check` | Strict formatting check (must pass) |
| `clippy` | — | `cargo clippy --all-targets --all-features` | Lint (non-strict — warnings shown, don't fail) |
| `build` | `format`, `clippy` | `cargo build --release` | Release build |
| `test` | `format`, `clippy` | `cargo test --all-targets` | Unit + integration tests |
`format` and `clippy` run in parallel; `build` and `test` run after both pass.
### The `test` job
Integration tests need a live MongoDB, so the `test` job provisions a
`mongo:7` **service container** and sets `MONGODB_URI=mongodb://mongo:27017`.
The tests target an isolated per-run database and skip gracefully if Mongo is
unreachable, so the job stays green even on runners that can't provide service
containers.
## Docker builds are NOT in CI
There is deliberately **no `docker-build` job**. The Forgejo `act` runner creates
isolated networks per job, which breaks every Docker-in-CI approach tried
(socket mount, DinD, Buildx, direct host access). Docker images are built
separately:
- **Locally**: `docker build -f backend/docker/Dockerfile backend/`
- **On Solaria**: see [../deployment/](../deployment/DEPLOYMENT_GUIDE.md)
## Running CI checks locally
Use [`scripts/test-ci-locally.sh`](../../scripts/test-ci-locally.sh), which runs
the same format/clippy/build/test sequence. For the integration tests it needs a
reachable MongoDB:
```bash
docker run -d -p 27017:27017 --name mongo-test mongo:7
./scripts/test-ci-locally.sh
```
## Dashboard
CI runs: `http://gitea.solivarez.com.ar/alvaro/normogen/actions`
---
*Last Updated: 2026-06-27*

Some files were not shown because too many files have changed in this diff Show more