ColaFlow/colaflow-api/DAY5-PRIORITY-AND-REQUIREMENTS.md

Day 5 Priority Analysis and Requirements Document

Date: 2025-11-03 Project: ColaFlow Authentication System Milestone: M1 - Core Project Module

---

Executive Summary

Based on Day 4's authentication implementation (JWT + BCrypt + Middleware) and ColaFlow's M1-M6 roadmap, this document prioritizes 4 pending features and defines Day 5 implementation focus.

Day 5 Recommendation: Focus on Refresh Token + Role-Based Authorization (RBAC)

---

1. Priority Analysis

Feature Priority Matrix

Feature	Business Value	Technical Complexity	MCP Dependency	Risk	Priority
Refresh Token	HIGH	LOW	HIGH	LOW	P0 (Must Have)
Role-Based Authorization	HIGH	MEDIUM	CRITICAL	MEDIUM	P0 (Must Have)
Email Verification	MEDIUM	LOW	LOW	LOW	P1 (Should Have)
SSO Integration	LOW	HIGH	LOW	HIGH	P2 (Nice to Have)

---

1.1 Refresh Token Implementation

Priority: P0 (Must Have)

Why P0?

1. Security Best Practice: Current 60-minute JWT is too long for production (increases vulnerability window)
2. User Experience: Prevents frequent re-logins (enables 7-day "Remember Me" functionality)
3. MCP Integration: AI tools need long-lived sessions to perform multi-step operations (create PRD → generate tasks → update progress)
4. Industry Standard: All production auth systems use refresh tokens

Business Value

• High: Essential for production security and UX
• MCP Relevance: Critical - AI agents need persistent sessions to complete multi-turn workflows

Technical Complexity

• Low: Interface already exists (GenerateRefreshTokenAsync())
• Effort: 2-3 hours
• Dependencies: Database or Redis storage

Risk

• Low: Well-defined pattern, no architectural changes needed

---

1.2 Role-Based Authorization (RBAC)

Priority: P0 (Must Have)

Why P0?

1. MCP Security Requirement: AI tools must have restricted permissions (read-only vs. read-write)
2. Multi-Tenant Architecture: Tenant Admins vs. Members vs. Guests need different access levels
3. Project Core Requirement: Epic/Story/Task management requires role-based access control
4. Audit & Compliance: ColaFlow's audit log system requires role tracking for accountability

Business Value

• High: Foundation for all access control in M1-M6
• MCP Relevance: Critical - AI agents must operate under restricted roles (e.g., "AI Agent" role with write-preview permissions)

Technical Complexity

• Medium: Requires database schema changes (User-Role mapping), claims modification, authorization policies
• Effort: 4-5 hours
• Dependencies: JWT claims, authorization middleware

Risk

• Medium: Requires migration of existing users, potential breaking changes

---

1.3 Email Verification

Priority: P1 (Should Have)

Why P1?

1. Security Enhancement: Prevents fake account registrations
2. User Validation: Ensures users own their email addresses
3. Password Reset Prerequisite: Required for secure password reset flow

Business Value

• Medium: Improves security but not blocking for M1
• MCP Relevance: Low - AI tools don't require email verification

Technical Complexity

• Low: Standard email verification flow
• Effort: 3-4 hours
• Dependencies: Email service (SendGrid/AWS SES), verification token storage

Risk

• Low: Non-breaking addition to registration flow

Deferral Justification

• Not blocking for M1 Core Project Module
• Can be added in M2 or M3 without architectural changes
• Focus on MCP-critical features first

---

1.4 SSO Integration

Priority: P2 (Nice to Have)

Why P2?

1. Enterprise Feature: Primarily for M5 Enterprise Pilot
2. High Complexity: Requires OAuth 2.0/OIDC implementation, multiple provider support
3. Not MCP-Critical: AI tools use API tokens, not SSO

Business Value

• Low: Enterprise convenience feature, not required for M1-M3
• MCP Relevance: None - AI tools don't use SSO

Technical Complexity

• High: Multiple providers (Azure AD, Google, GitHub), token exchange, user mapping
• Effort: 10-15 hours
• Dependencies: OAuth libraries, provider registrations, user linking logic

Risk

• High: Complex integration, provider-specific quirks, testing overhead

Deferral Justification

• Target for M4 (External Integration) or M5 (Enterprise Pilot)
• Does not block M1-M3 development
• Local authentication + API tokens sufficient for early milestones

---

2. Day 5 Focus: Refresh Token + RBAC

Recommended Scope

Day 5 Goals:

1. Implement Refresh Token mechanism (2-3 hours)
2. Implement Role-Based Authorization foundation (4-5 hours)

Total Effort: 6-8 hours (achievable in 1 day)

---

3. Feature Requirements

---

3.1 Refresh Token Implementation

3.1.1 Background & Goals

Business Context

• Current JWT tokens expire in 60 minutes, forcing users to re-login frequently
• AI agents performing long-running tasks (multi-step PRD generation) lose authentication mid-workflow
• Industry standard: Short-lived access tokens (15-30 min) + long-lived refresh tokens (7-30 days)

User Pain Points

• Users lose session while actively working
• AI tools fail mid-operation due to token expiration
• No "Remember Me" functionality

Project Objectives

• Reduce access token lifetime to 15 minutes (increase security)
• Implement 7-day refresh tokens (improve UX)
• Enable seamless token refresh for AI agents

---

3.1.2 Requirements

Core Functionality

FR-RT-1: JWT Access Token Generation

• Reduce JWT expiration to 15 minutes (configurable)
• Keep existing JWT structure and claims
• Access tokens remain stateless

FR-RT-2: Refresh Token Generation

• Generate cryptographically secure refresh tokens (GUID or random bytes)
• Store refresh tokens in database (or Redis)
• Associate refresh tokens with User + Tenant + Device/Client
• Set expiration to 7 days (configurable)

FR-RT-3: Refresh Token Storage

CREATE TABLE RefreshTokens (
    Id UUID PRIMARY KEY,
    UserId UUID NOT NULL FOREIGN KEY REFERENCES Users(Id),
    TenantId UUID NOT NULL FOREIGN KEY REFERENCES Tenants(Id),
    Token VARCHAR(500) NOT NULL UNIQUE,
    ExpiresAt TIMESTAMP NOT NULL,
    CreatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
    RevokedAt TIMESTAMP NULL,
    ReplacedByToken VARCHAR(500) NULL
);

CREATE INDEX IX_RefreshTokens_Token ON RefreshTokens(Token);
CREATE INDEX IX_RefreshTokens_UserId ON RefreshTokens(UserId);

FR-RT-4: Token Refresh Endpoint

• POST /api/auth/refresh
• Request Body: { "refreshToken": "..." }
• Response: New access token + new refresh token (token rotation)
• Validation:
  • Refresh token exists and not revoked
  • Refresh token not expired
  • User and Tenant still active
• Behavior: Issue new access token + rotate refresh token (invalidate old token)

FR-RT-5: Token Revocation

• POST /api/auth/logout
• Mark refresh token as revoked
• Prevent reuse of revoked tokens

FR-RT-6: Automatic Cleanup

• Background job to delete expired refresh tokens (older than 30 days)

---

User Scenarios

Scenario 1: User Login

1. User submits credentials → /api/auth/login
2. System validates credentials
3. System generates:
   • Access Token (15-minute JWT)
   • Refresh Token (7-day GUID stored in database)
4. System returns both tokens
5. Client stores refresh token securely (HttpOnly cookie or secure storage)

Expected Result: User receives short-lived access token + long-lived refresh token

---

Scenario 2: Access Token Expiration

1. Client makes API request with expired access token
2. API returns 401 Unauthorized
3. Client automatically calls /api/auth/refresh with refresh token
4. System validates refresh token and issues new access token + new refresh token
5. Client retries original API request with new access token

Expected Result: Seamless token refresh without user re-login

---

Scenario 3: Refresh Token Expiration

1. User hasn't accessed app for 7+ days
2. Refresh token expired
3. Client attempts token refresh → System returns 401 Unauthorized
4. Client redirects user to login page

Expected Result: User must re-authenticate after 7 days of inactivity

---

Scenario 4: User Logout

1. User clicks "Logout"
2. Client calls /api/auth/logout with refresh token
3. System marks refresh token as revoked
4. Client clears stored tokens

Expected Result: Refresh token becomes invalid, user must re-login

---

Priority Levels

P0 (Must Have):

• Refresh token generation and storage
• /api/auth/refresh endpoint with token rotation
• Database schema for refresh tokens
• Token revocation on logout

P1 (Should Have):

• Automatic expired token cleanup job
• Multiple device/session support (one refresh token per device)
• Admin endpoint to revoke all user tokens

P2 (Nice to Have):

• Refresh token usage analytics
• Suspicious activity detection (token reuse, concurrent sessions)

---

3.1.3 Acceptance Criteria

Functional Criteria

• AC-RT-1: Access tokens expire in 15 minutes (configurable via appsettings.json)
• AC-RT-2: Refresh tokens expire in 7 days (configurable)
• AC-RT-3: /api/auth/login returns both access token and refresh token
• AC-RT-4: /api/auth/refresh validates refresh token and issues new tokens
• AC-RT-5: Old refresh token is revoked when new token is issued (token rotation)
• AC-RT-6: Revoked refresh tokens cannot be reused
• AC-RT-7: Expired refresh tokens cannot be used
• AC-RT-8: /api/auth/logout revokes refresh token
• AC-RT-9: Refresh tokens are stored securely (hashed or encrypted)

Security Criteria

• AC-RT-10: Refresh tokens are cryptographically secure (min 256-bit entropy)
• AC-RT-11: Token rotation prevents token replay attacks
• AC-RT-12: Refresh tokens are unique per user session
• AC-RT-13: Concurrent refresh attempts invalidate all tokens (suspicious activity detection - P1)

Performance Criteria

• AC-RT-14: Token refresh completes in < 200ms (database lookup + JWT generation)
• AC-RT-15: Database indexes on Token and UserId for fast lookups

---

3.1.4 Timeline

• Epic: Identity & Authentication
• Story: Refresh Token Implementation
• Tasks:
  1. Create RefreshToken entity and DbContext configuration (30 min)
  2. Add database migration for RefreshTokens table (15 min)
  3. Implement GenerateRefreshTokenAsync() in JwtService (30 min)
  4. Implement RefreshTokenRepository for storage (30 min)
  5. Update /api/auth/login to return refresh token (15 min)
  6. Implement /api/auth/refresh endpoint (45 min)
  7. Implement /api/auth/logout token revocation (15 min)
  8. Update JWT expiration to 15 minutes (5 min)
  9. Write integration tests (30 min)
  10. Update documentation (15 min)

Estimated Effort: 3 hours Target Milestone: M1

---

3.2 Role-Based Authorization (RBAC)

3.2.1 Background & Goals

Business Context

• ColaFlow is a multi-tenant system with hierarchical permissions
• Different users need different access levels (Tenant Admin, Project Admin, Member, Guest, AI Agent)
• MCP integration requires AI agents to operate under restricted roles
• Audit logs require role information for accountability

User Pain Points

• No granular access control (all users have same permissions)
• Cannot restrict AI agents to read-only or preview-only operations
• Cannot enforce tenant-level vs. project-level permissions

Project Objectives

• Implement role hierarchy: Tenant Admin > Project Admin > Member > Guest > AI Agent (Read-Only)
• Support role-based JWT claims for authorization
• Enable [Authorize(Roles = "Admin")] attribute usage
• Prepare for MCP-specific roles (AI agents with write-preview permissions)

---

3.2.2 Requirements

Core Functionality

FR-RBAC-1: Role Definitions

Define 5 core roles:

Role	Scope	Permissions
TenantAdmin	Tenant-wide	Full control: manage users, roles, projects, billing
ProjectAdmin	Project-specific	Manage project: create/edit/delete tasks, assign members
Member	Project-specific	Create/edit own tasks, view all project data
Guest	Project-specific	Read-only access to assigned tasks
AIAgent	Tenant-wide	Read all + Write with preview (requires human approval)

FR-RBAC-2: Database Schema

-- Enum or lookup table for roles
CREATE TABLE Roles (
    Id UUID PRIMARY KEY,
    Name VARCHAR(50) NOT NULL UNIQUE, -- TenantAdmin, ProjectAdmin, Member, Guest, AIAgent
    Description VARCHAR(500),
    IsSystemRole BOOLEAN NOT NULL DEFAULT TRUE
);

-- User-Role mapping (many-to-many)
CREATE TABLE UserRoles (
    Id UUID PRIMARY KEY,
    UserId UUID NOT NULL FOREIGN KEY REFERENCES Users(Id) ON DELETE CASCADE,
    RoleId UUID NOT NULL FOREIGN KEY REFERENCES Roles(Id) ON DELETE CASCADE,
    TenantId UUID NOT NULL FOREIGN KEY REFERENCES Tenants(Id) ON DELETE CASCADE,
    ProjectId UUID NULL FOREIGN KEY REFERENCES Projects(Id) ON DELETE CASCADE, -- NULL for tenant-level roles
    GrantedAt TIMESTAMP NOT NULL DEFAULT NOW(),
    GrantedBy UUID NULL FOREIGN KEY REFERENCES Users(Id), -- Who assigned this role
    UNIQUE(UserId, RoleId, TenantId, ProjectId)
);

CREATE INDEX IX_UserRoles_UserId ON UserRoles(UserId);
CREATE INDEX IX_UserRoles_TenantId ON UserRoles(TenantId);
CREATE INDEX IX_UserRoles_ProjectId ON UserRoles(ProjectId);

FR-RBAC-3: JWT Claims Enhancement

Add role claims to JWT:

{
  "sub": "user-guid",
  "email": "user@example.com",
  "role": "TenantAdmin", // Primary role
  "roles": ["TenantAdmin", "ProjectAdmin"], // All roles (array)
  "tenant_id": "tenant-guid",
  "permissions": ["users:read", "users:write", "projects:admin"] // Optional: fine-grained permissions
}

FR-RBAC-4: Authorization Policies

Configure policies in Program.cs:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("RequireTenantAdmin", policy =>
        policy.RequireRole("TenantAdmin"));

    options.AddPolicy("RequireProjectAdmin", policy =>
        policy.RequireRole("TenantAdmin", "ProjectAdmin"));

    options.AddPolicy("RequireMemberOrHigher", policy =>
        policy.RequireRole("TenantAdmin", "ProjectAdmin", "Member"));

    options.AddPolicy("RequireHumanUser", policy =>
        policy.RequireAssertion(ctx =>
            !ctx.User.HasClaim("role", "AIAgent")));
});

FR-RBAC-5: Controller Protection

Apply role-based authorization to endpoints:

[Authorize(Roles = "TenantAdmin")]
[HttpPost("api/tenants/{tenantId}/users")]
public async Task<IActionResult> CreateUser(...) { }

[Authorize(Policy = "RequireProjectAdmin")]
[HttpDelete("api/projects/{projectId}")]
public async Task<IActionResult> DeleteProject(...) { }

[Authorize(Policy = "RequireMemberOrHigher")]
[HttpPost("api/projects/{projectId}/tasks")]
public async Task<IActionResult> CreateTask(...) { }

FR-RBAC-6: Default Role Assignment

• New tenant registration: First user gets TenantAdmin role
• Invited users: Get Member role by default
• AI agents: Require explicit AIAgent role assignment

---

User Scenarios

Scenario 1: Tenant Admin Creates User

1. Tenant Admin invites new user via /api/tenants/{tenantId}/users
2. System validates requester has TenantAdmin role
3. System creates user with Member role by default
4. System sends invitation email

Expected Result: User created successfully, assigned Member role

---

Scenario 2: Member Attempts Tenant Admin Action

1. Member user attempts to delete tenant via /api/tenants/{tenantId}
2. System validates JWT role claim
3. System returns 403 Forbidden (insufficient permissions)

Expected Result: Request rejected with clear error message

---

Scenario 3: Project Admin Assigns Roles

1. Project Admin assigns user to project with ProjectAdmin role
2. System validates requester has TenantAdmin or ProjectAdmin role for this project
3. System creates UserRoles entry (UserId, ProjectAdmin, ProjectId)
4. User receives notification

Expected Result: User gains ProjectAdmin role for specific project

---

Scenario 4: AI Agent Creates Task (MCP Integration)

1. AI agent calls /api/projects/{projectId}/tasks with AIAgent role token
2. System detects AIAgent role → triggers diff preview mode
3. System generates task preview (not committed to database)
4. System returns preview to AI agent → AI presents to human for approval
5. Human approves → AI agent calls /api/tasks/preview/{previewId}/commit
6. System validates approval and commits task

Expected Result: AI agent creates task only after human approval

---

Priority Levels

P0 (Must Have):

• Role definitions (TenantAdmin, ProjectAdmin, Member, Guest, AIAgent)
• Database schema: Roles + UserRoles tables
• JWT role claims
• Authorization policies in Program.cs
• Controller-level [Authorize(Roles = "...")] protection
• Default role assignment (TenantAdmin for first user, Member for new users)

P1 (Should Have):

• Project-specific role assignment (UserRoles with ProjectId)
• Role management API (assign/revoke roles)
• Admin UI for role management
• Role-based audit logging

P2 (Nice to Have):

• Fine-grained permissions (users:read, users:write, etc.)
• Custom role creation
• Role inheritance (ProjectAdmin inherits Member permissions)

---

3.2.3 Acceptance Criteria

Functional Criteria

• AC-RBAC-1: 5 system roles exist in database (TenantAdmin, ProjectAdmin, Member, Guest, AIAgent)
• AC-RBAC-2: First user in new tenant is automatically assigned TenantAdmin role
• AC-RBAC-3: JWT tokens include role and roles claims
• AC-RBAC-4: Endpoints protected with [Authorize(Roles = "...")] reject unauthorized users with 403 Forbidden
• AC-RBAC-5: TenantAdmin can access all tenant-level endpoints
• AC-RBAC-6: Member cannot access admin endpoints (returns 403)
• AC-RBAC-7: Role assignment is logged in audit trail (P1)

Security Criteria

• AC-RBAC-8: Role claims are cryptographically signed in JWT (tamper-proof)
• AC-RBAC-9: Role validation happens on every request (no role caching vulnerabilities)
• AC-RBAC-10: AI agents cannot access endpoints requiring human user (RequireHumanUser policy)

MCP Integration Criteria

• AC-RBAC-11: AIAgent role is distinguishable in authorization logic
• AC-RBAC-12: Endpoints can detect AI agent role and trigger preview mode (P0 for M2)
• AC-RBAC-13: Human-only endpoints (e.g., approve preview) reject AI agent tokens

Performance Criteria

• AC-RBAC-14: Role lookup from JWT claims (no database query per request)
• AC-RBAC-15: Authorization decision completes in < 10ms

---

3.2.4 Timeline

• Epic: Identity & Authentication
• Story: Role-Based Authorization (RBAC)
• Tasks:
  1. Design role hierarchy and permissions matrix (30 min)
  2. Create Role and UserRole entities (30 min)
  3. Add database migration for RBAC tables (15 min)
  4. Seed default roles (TenantAdmin, ProjectAdmin, Member, Guest, AIAgent) (15 min)
  5. Update JwtService to include role claims (30 min)
  6. Update RegisterTenantCommandHandler to assign TenantAdmin role (15 min)
  7. Configure authorization policies in Program.cs (30 min)
  8. Add [Authorize(Roles = "...")] to existing controllers (30 min)
  9. Implement role assignment/revocation API (P1) (45 min)
  10. Write integration tests for RBAC (45 min)
  11. Update API documentation (15 min)

Estimated Effort: 4.5 hours Target Milestone: M1

---

4. MCP Integration Requirements

4.1 Authentication System Capabilities for MCP

To support M2 (MCP Server Implementation) and M3 (ChatGPT Integration PoC), the authentication system must provide:

---

MCP-1: AI Agent Authentication

Requirement: AI tools must authenticate with ColaFlow using API tokens (not username/password)

Implementation:

• Generate long-lived API tokens (30-90 days) for AI agents
• API tokens stored in database (hashed) with metadata (agent name, permissions, expiration)
• API tokens map to User with AIAgent role
• Endpoint: POST /api/auth/tokens (generate API token for AI agent)

Example:

POST /api/auth/tokens
{
  "agentName": "ChatGPT-PRD-Generator",
  "permissions": ["projects:read", "tasks:write_preview"],
  "expiresInDays": 90
}

Response:
{
  "token": "cola_live_sk_abc123...",
  "expiresAt": "2026-02-01T00:00:00Z"
}

---

MCP-2: AI Agent Role & Permissions

Requirement: AI agents must have restricted permissions (read + write-preview only)

Implementation:

• AIAgent role defined with permissions:
  • Read: All projects, tasks, docs (tenant-scoped)
  • Write Preview: Generate diffs for tasks/docs (not committed)
  • No Direct Write: Cannot commit changes without human approval
• Authorization policies detect AIAgent role and enforce preview mode

Example:

[Authorize(Roles = "Member,ProjectAdmin,TenantAdmin")]
[HttpPost("api/projects/{projectId}/tasks")]
public async Task<IActionResult> CreateTask(...)
{
    if (User.IsInRole("AIAgent"))
    {
        // Generate preview, return for human approval
        return Ok(new { preview: taskPreview, requiresApproval: true });
    }

    // Direct commit for human users
    await _taskService.CreateTaskAsync(...);
    return Created(...);
}

---

MCP-3: Multi-Turn Session Management

Requirement: AI agents need persistent sessions for multi-turn workflows (e.g., create PRD → generate tasks → update status)

Implementation:

• Refresh tokens for AI agents (90-day expiration)
• Session storage for AI agent context (e.g., current project, draft document ID)
• Session cleanup after 24 hours of inactivity

Example Workflow:

1. AI: Generate PRD draft → System: Creates draft (not committed), returns previewId
2. AI: Review PRD draft → System: Returns preview with previewId
3. Human: Approve PRD → System: Commits draft to database
4. AI: Generate tasks from PRD → System: Creates task previews
5. Human: Approve tasks → System: Commits tasks

---

MCP-4: Audit Trail for AI Actions

Requirement: All AI agent actions must be logged for compliance and debugging

Implementation:

• Audit log entries include:
  • Actor: AI agent name (from JWT sub or agent_name claim)
  • Action: Resource + Operation (e.g., "tasks.create_preview")
  • Timestamp
  • Request payload (diff)
  • Approval status (pending, approved, rejected)
• Queryable audit log: GET /api/audit?actorType=AIAgent

---

MCP-5: Human Approval Workflow

Requirement: All AI write operations require human approval

Implementation:

• Preview storage: Store AI-generated changes in temporary table
• Approval API:
  • GET /api/previews/{previewId} - View diff
  • POST /api/previews/{previewId}/approve - Commit changes
  • POST /api/previews/{previewId}/reject - Discard changes
• Preview expiration: Auto-delete after 24 hours

Database Schema:

CREATE TABLE Previews (
    Id UUID PRIMARY KEY,
    EntityType VARCHAR(50) NOT NULL, -- Task, Document, etc.
    Operation VARCHAR(50) NOT NULL, -- Create, Update, Delete
    Payload JSONB NOT NULL, -- Full entity data or diff
    CreatedBy UUID NOT NULL FOREIGN KEY REFERENCES Users(Id), -- AI agent user
    CreatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
    ExpiresAt TIMESTAMP NOT NULL,
    ApprovedBy UUID NULL FOREIGN KEY REFERENCES Users(Id),
    ApprovedAt TIMESTAMP NULL,
    RejectedBy UUID NULL FOREIGN KEY REFERENCES Users(Id),
    RejectedAt TIMESTAMP NULL,
    Status VARCHAR(20) NOT NULL DEFAULT 'Pending' -- Pending, Approved, Rejected, Expired
);

---

MCP-6: Rate Limiting for AI Agents

Requirement: Prevent AI agents from overwhelming the system

Implementation:

• Rate limits per AI agent token:
  • Read operations: 100 requests/minute
  • Write preview operations: 10 requests/minute
  • Commit operations: N/A (human-initiated)
• Return 429 Too Many Requests when limit exceeded
• Use Redis or in-memory cache for rate limit tracking

---

4.2 MCP Integration Readiness Checklist

For Day 5 implementation, ensure authentication system supports:

• MCP-Ready-1: AI agent user creation (User with AIAgent role)
• MCP-Ready-2: API token generation and validation (long-lived tokens)
• MCP-Ready-3: Role-based authorization (AIAgent role defined)
• MCP-Ready-4: Refresh tokens for multi-turn AI sessions
• MCP-Ready-5: Audit logging foundation (log actor role in all operations)
• MCP-Ready-6: Preview storage schema (P1 - can be added in M2)

---

5. Technical Constraints & Dependencies

5.1 Technology Stack

• .NET 9.0: Use latest C# 13 features
• PostgreSQL: Primary database (RBAC tables, refresh tokens)
• Entity Framework Core 9.0: ORM for database access
• System.IdentityModel.Tokens.Jwt: JWT token handling
• Redis (Optional): For refresh token storage (if high throughput needed)

---

5.2 Dependencies

Internal Dependencies

• Day 4 Completion: JWT service, password hashing, authentication middleware
• Database Migrations: Existing IdentityDbContext must be migrated
• Tenant & User Entities: Must support role relationships

External Dependencies

• PostgreSQL Instance: Running and accessible
• Configuration: appsettings.json updated with token lifetimes
• Testing Environment: Integration tests require test database

---

5.3 Breaking Changes

Refresh Token Implementation

• Breaking: Access token lifetime changes from 60 min → 15 min
• Migration Path: Clients must implement token refresh logic
• Backward Compatibility: Old tokens valid until expiration (no immediate break)

RBAC Implementation

• Breaking: Existing users have no roles (must assign default role in migration)
• Migration Path: Data migration to assign TenantAdmin to first user per tenant
• Backward Compatibility: Endpoints without [Authorize(Roles)] remain accessible

---

5.4 Testing Requirements

Refresh Token Tests

1. Token refresh succeeds with valid refresh token
2. Token refresh fails with expired refresh token
3. Token refresh fails with revoked refresh token
4. Token rotation invalidates old refresh token
5. Logout revokes refresh token
6. Concurrent refresh attempts handled correctly (P1)

RBAC Tests

1. TenantAdmin can access admin endpoints
2. Member cannot access admin endpoints (403 Forbidden)
3. Guest has read-only access
4. AIAgent role triggers preview mode
5. Role claims present in JWT
6. Authorization policies enforce role requirements

---

6. Next Steps After Day 5

Day 6-7: Complete M1 Core Project Module

• Implement Project/Epic/Story/Task entities
• Implement Kanban workflow (To Do → In Progress → Done)
• Basic audit log for entity changes

Day 8-9: Email Verification + Password Reset

• Email verification flow (P1 from this document)
• Password reset with secure tokens
• Email service integration (SendGrid)

Day 10-12: M2 MCP Server Foundation

• Implement Preview storage and approval API (MCP-5)
• Implement API token generation for AI agents (MCP-1)
• Rate limiting for AI agents (MCP-6)
• MCP protocol implementation (Resources + Tools)

---

7. Success Metrics

Day 5 Success Criteria

Refresh Token

• Access token lifetime: 15 minutes
• Refresh token lifetime: 7 days
• Token refresh endpoint response time: < 200ms
• All refresh token tests passing

RBAC

• 5 system roles seeded in database
• JWT includes role claims
• Admin endpoints protected with role-based authorization
• All RBAC tests passing

MCP Readiness

• AIAgent role defined and assignable
• Role-based authorization policies configured
• Audit logging includes actor role (foundation)

---

8. Risk Mitigation

Risk 1: Refresh Token Implementation Complexity

Risk: Token rotation logic may introduce race conditions Mitigation: Use database transactions, test concurrent refresh attempts Fallback: Implement simple refresh without rotation (P0), add rotation in P1

Risk 2: RBAC Migration Breaks Existing Users

Risk: Existing users have no roles, break auth flow Mitigation: Data migration assigns default roles before deploying RBAC Fallback: Add fallback logic (users without roles get Member role temporarily)

Risk 3: Day 5 Scope Too Large

Risk: Cannot complete both features in 1 day Mitigation: Prioritize Refresh Token (P0), defer RBAC project-level roles to Day 6 Fallback: Complete Refresh Token only, move RBAC to Day 6

---

9. Approval & Sign-Off

Stakeholders

• Product Manager: Approved
• Architect: Pending review
• Backend Lead: Pending review
• Security Team: Pending review (refresh token security)

Next Steps

1. Review this PRD with architect and backend lead
2. Create detailed technical design for refresh token storage (database vs. Redis)
3. Begin Day 5 implementation

---

Appendix A: Alternative Approaches Considered

Refresh Token Storage: Database vs. Redis

Option 1: PostgreSQL (Recommended)

Pros:

• Simple setup, no additional infrastructure
• ACID guarantees for token rotation
• Easy audit trail integration

Cons:

• Slower than Redis (but < 200ms acceptable)
• Database load for high-traffic scenarios

Decision: Use PostgreSQL for M1-M3, evaluate Redis for M4-M6 if needed

---

Option 2: Redis

Pros:

• Extremely fast (< 10ms lookup)
• TTL-based automatic expiration
• Scales horizontally

Cons:

• Additional infrastructure complexity
• No ACID transactions (potential race conditions)
• Audit trail requires separate logging

Decision: Defer to M4+ if performance bottleneck identified

---

RBAC Implementation: Enum vs. Database Roles

Option 1: Database Roles (Recommended)

Pros:

• Flexible, supports custom roles in future
• Queryable, auditable
• Supports project-level roles

Cons:

• More complex schema
• Requires migration for role changes

Decision: Use database roles for extensibility

---

Option 2: Enum Roles

Pros:

• Simple, type-safe in C#
• No database lookups

Cons:

• Cannot add custom roles without code changes
• No project-level role support

Decision: Rejected - too rigid for M2+ requirements

---

Appendix B: References

• RFC 6749: OAuth 2.0 - Refresh token spec
• OWASP Authentication Cheat Sheet
• ASP.NET Core Authorization
• ColaFlow Product Plan: product.md
• Day 4 Implementation: DAY4-IMPLEMENTATION-SUMMARY.md

---

Document Version: 1.0 Last Updated: 2025-11-03 Next Review: Day 6 (Post-Implementation Review)