KArtSell.Aegis/docs/contracts/architecture/VS-01_SLICE_SPEC.md

VS-01: Manage Identity and Roles - Vertical Slice Specification

Slice ID: VS-01
Batch: 1 (no dependencies)
Status: 📋 SPECIFICATION
Created: 2026-08-04

---

Executive Summary

Establish centralized Identity and Role Management (IAM) system for K-ArtSell platform.

User Goal: Administrators can manage user accounts, roles, and permissions from a single dashboard without manual database operations.

Non-Goal:

• SSO/LDAP integration (Phase 3)
• MFA implementation (Phase 3)
• Audit trail (separate feature)
• Password reset workflow (Phase 3)

---

Acceptance Criteria

1. User Management ✅

• Create User: Endpoint creates new user record with UUID, email, hashed password, roles
• Read Users: Paginated list, filterable by role/status
• Update User: Change email, roles (no password update here)
• Soft Delete: Mark user as inactive (no hard delete)
• Validation: Email unique per environment, password ≥12 chars

2. Role & Permission Model ✅

• Predefined Roles: Admin, Analyst, Trader, Viewer (immutable)
• Permissions: Read, Write, Approve, Execute (scoped to domain)
• User-Role Mapping: Many-to-many with assigned_at timestamp
• Permission Enforcement: Checked on every endpoint (via PermissionGuard)

3. Data Integrity ✅

• PIT Compliance: created_at (never future), updated_at, published_at (for CDC)
• Immutable: user_id, email_hash cannot change post-creation
• Revision Tracking: Each role change creates new record (append-only)
• Schema-Qualified: All queries use identity.users, identity.roles

4. API Contracts ✅

Endpoint: POST /api/users

Request: { email: string, password: string, roles: ["Admin", "Analyst"] }
Response: 201 Created { userId: UUID, email: string, roles: [string] }
Errors: 400 (invalid), 409 (exists), 422 (validation)
Idempotency: IdempotencyKey header

Endpoint: GET /api/users?page=1&limit=20&role=Admin

Response: 200 { items: [User], total: int, page: int, limit: int }
Errors: 401, 403 (insufficient permissions)

Endpoint: PATCH /api/users/:id

Request: { roles: ["Analyst", "Viewer"], status: "active" }
Response: 200 { userId: UUID, roles: [string], updated_at: timestamp }

5. UI/UX Acceptance Criteria ✅

• User List Page: Table with columns (Email, Roles, Status, Actions)
• Create Dialog: Form with email + password + role multi-select
• Edit Dialog: Change roles inline
• Delete Dialog: Confirm soft-delete with warning
• Accessibility: ARIA labels, keyboard nav, error messages

6. Security Acceptance Criteria ✅

• Password Hashing: bcrypt or argon2, never plaintext
• Auth Check: Every endpoint requires role (no anonymous)
• Authorization: Only Admin can modify users
• Audit Logging: User changes logged with correlationId
• No PII in Logs: Email, password NEVER logged

---

Failure Modes & Recovery

Scenario 1: Duplicate Email

Trigger: POST /api/users with existing email
Expected: 409 Conflict { error: "Email already exists" }
Recovery: User retries with different email

Scenario 2: Invalid Role

Trigger: POST /api/users with role="SuperAdmin" (not in predefined list)
Expected: 422 Unprocessable { error: "Invalid role: SuperAdmin" }
Recovery: User selects from dropdown of valid roles

Scenario 3: Concurrent Role Update

Trigger: 2 admins modify same user's roles simultaneously
Expected: Last-write-wins (UPDATE WHERE version = @version, increment version)
Recovery: Second request gets 409 Conflict, user retries with fresh data

---

Success Metrics

Metric	Target	Verification
Create latency	<200ms	Load test
List latency	<500ms (1000 users)	Stress test
Auth check latency	<50ms	Endpoint latency trace
Test coverage	≥95%	Code coverage report
Uptime	≥99.9%	Monitoring dashboard

---

Dependencies

Inbound (Block VS-01)

• ✅ VS-00: Platform foundation (complete)
• ✅ Authentication: DevelopmentHeader + FailClosed (Phase 1)

Outbound (Unblock)

• 🔄 VS-07: ManageClientIPS (depends on VS-01 for User/Role APIs)
• 🔄 VS-02~08: All slices use VS-01's permission model

---

Component Breakdown (7 items per slice)

Component	Owner	Duration	Status
GOV (this doc)	Architect	1-2 hrs	📋
DATA	Data Architect	2-3 hrs	⏳ Ready
DOMAIN	Quant Lead	2-3 hrs	⏳ Ready
BE	BE Lead	3-4 hrs	⏳ Ready
ASYNC	SRE	2-3 hrs	⏳ Ready
FE	FE Architect	3-4 hrs	⏳ Ready
TESTOPS	QA Lead	2-3 hrs	⏳ Ready

Total Duration: ~18-22 hours (wall-clock ~3 days)

---

Sign-Off

Role	Name	Status	Date
Product Owner	User	⏳ Approval	TBD
Architect	Claude Code	✅ Draft	2026-08-04
Security	Team	⏳ Review	TBD

---

Status: 📋 READY FOR DATA/DOMAIN/BE COMPONENTS

Next: VS-01_DATA_CONTRACT.md