feat(#4): Implement Authentik OIDC authentication with BetterAuth

- Integrated BetterAuth library for modern authentication
- Added Session, Account, and Verification database tables
- Created complete auth module with service, controller, guards, and decorators
- Implemented shared authentication types in @mosaic/shared package
- Added comprehensive test coverage (26 tests passing)
- Documented type sharing strategy for monorepo
- Updated environment configuration with OIDC and JWT settings

Key architectural decisions:
- BetterAuth over Passport.js for better TypeScript support
- Separation of User (DB entity) vs AuthUser (client-safe subset)
- Shared types package to prevent FE/BE drift
- Factory pattern for auth config to use shared Prisma instance

Ready for frontend integration (Issue #6).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Fixes #4

docs/scratchpads/4-authentik-oidc.md

@@ -0,0 +1,75 @@
+# Issue #4: Authentik OIDC integration
+
+## Objective
+Implement Authentik OIDC (OpenID Connect) authentication integration for the Mosaic Stack API. This will enable secure user authentication via the Authentik identity provider, supporting multi-tenant workspaces.
+
+## Approach
+1. Install BetterAuth library and dependencies
+2. Configure BetterAuth with Authentik OIDC provider
+3. Create auth module using BetterAuth
+4. Add authentication middleware and guards
+5. Configure environment variables for Authentik
+6. Create user management service integrated with BetterAuth
+7. Write comprehensive tests (TDD approach)
+
+## BetterAuth Configuration
+- Use BetterAuth's built-in OIDC support for Authentik
+- Leverage BetterAuth's session management
+- Integrate with Prisma ORM for user storage
+
+## Progress
+- [x] Create scratchpad
+- [x] Explore existing codebase
+- [x] Install BetterAuth dependencies
+- [x] Implement BetterAuth configuration
+- [x] Create auth guards and decorators
+- [x] Add auth service
+- [x] Configure environment
+- [x] Write tests (26 tests passing)
+- [x] Build and verify
+- [x] Code review (all critical issues fixed)
+- [x] QA testing (identified improvements for future)
+- [x] Fix code review issues
+
+## Testing
+- Unit tests for auth service and strategy
+- Integration tests for OIDC flow
+- E2E tests for protected endpoints
+- Target: 85% coverage minimum
+
+## Implementation Summary
+
+### Completed
+1. **BetterAuth Integration**: Implemented using BetterAuth library for modern, type-safe authentication
+2. **Database Schema**: Added Session, Account, and Verification tables for BetterAuth
+3. **Auth Module**: Created complete NestJS auth module with service, controller, guards, and decorators
+4. **Shared Prisma Client**: Fixed duplicate PrismaClient issue by using shared instance
+5. **Type Safety**: Added proper TypeScript types for AuthUser interface
+6. **Error Handling**: Sanitized error logging to prevent sensitive data exposure
+7. **Test Coverage**: 26 tests passing covering service, controller, and guards
+8. **Code Review**: All critical issues from code review have been addressed
+
+### Key Files Created/Modified
+- `apps/api/src/auth/auth.config.ts` - BetterAuth configuration
+- `apps/api/src/auth/auth.service.ts` - Authentication service
+- `apps/api/src/auth/auth.controller.ts` - Auth routes handler
+- `apps/api/src/auth/guards/auth.guard.ts` - Session validation guard
+- `apps/api/src/auth/decorators/current-user.decorator.ts` - User extraction decorator
+- `apps/api/src/auth/types/auth-user.interface.ts` - Type definitions
+- `apps/api/prisma/schema.prisma` - Added auth tables
+- Multiple test files with comprehensive coverage
+
+### Future Improvements (from QA)
+- Add token format validation tests (Priority 10)
+- Add database error handling tests (Priority 9)
+- Add session data integrity tests (Priority 9)
+- Add request mutation verification (Priority 8)
+- Create E2E/integration tests for full OAuth flow
+- Add CurrentUser decorator tests
+
+## Notes
+- Using BetterAuth instead of custom Passport implementation for modern, maintained solution
+- BetterAuth handles OIDC, session management, and user provisioning automatically
+- Environment variables configured in `.env.example` for Authentik
+- All code review findings addressed
+- Build and tests passing successfully (26/26 tests)