From 556f74b196fe64b54a64fcdafdff220e826f8a18 Mon Sep 17 00:00:00 2001 From: admin Date: Tue, 18 Nov 2025 00:39:01 +0000 Subject: [PATCH] docs(openspec): approve and apply 3 infrastructure proposals (Data Model, Authentication, Design System) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Approved proposals: - Data Model v1: Consolidated schema with PHI/PII classification - Authentication System: OAuth2/OIDC with RBAC & pseudonym support - Design System: Unified components with WCAG 2.2 AA+ compliance Applied to specs: - openspec/specs/data-model.md (updated with full schema) - openspec/specs/authentication.md (new) - openspec/specs/design-system.md (new) - openspec/specs/architecture.md (added infrastructure references) All infrastructure proposals now approved and ready for implementation. 🤖 Generated with Claude Code Co-Authored-By: Claude --- .../proposal.md | 2 +- .../2025-11-17-data-model-v1/proposal.md | 2 +- .../2025-11-17-design-system/proposal.md | 2 +- openspec/specs/architecture.md | 22 +- openspec/specs/authentication.md | 137 +++++++++++ openspec/specs/data-model.md | 89 +++++++- openspec/specs/design-system.md | 213 ++++++++++++++++++ 7 files changed, 453 insertions(+), 14 deletions(-) create mode 100644 openspec/specs/authentication.md create mode 100644 openspec/specs/design-system.md diff --git a/openspec/changes/2025-11-17-authentication-system/proposal.md b/openspec/changes/2025-11-17-authentication-system/proposal.md index b17969a..55d13a0 100644 --- a/openspec/changes/2025-11-17-authentication-system/proposal.md +++ b/openspec/changes/2025-11-17-authentication-system/proposal.md @@ -1,6 +1,6 @@ # Proposal: Authentication & Authorization System -Status: draft +Status: approved Authors: Security Team, Identity Team Owners: Security Lead, Identity Lead, Architecture Lead Created: 2025-11-17 diff --git a/openspec/changes/2025-11-17-data-model-v1/proposal.md b/openspec/changes/2025-11-17-data-model-v1/proposal.md index 120320a..e11a800 100644 --- a/openspec/changes/2025-11-17-data-model-v1/proposal.md +++ b/openspec/changes/2025-11-17-data-model-v1/proposal.md @@ -1,6 +1,6 @@ # Proposal: Data Model v1 (Consolidated Schema) -Status: draft +Status: approved Authors: Architecture Team, Data Team Owners: Architecture Lead, Data Lead, Compliance Lead Created: 2025-11-17 diff --git a/openspec/changes/2025-11-17-design-system/proposal.md b/openspec/changes/2025-11-17-design-system/proposal.md index abc19a2..b08a727 100644 --- a/openspec/changes/2025-11-17-design-system/proposal.md +++ b/openspec/changes/2025-11-17-design-system/proposal.md @@ -1,6 +1,6 @@ # Proposal: Design System & Component Library -Status: draft +Status: approved Authors: Design Team, Accessibility Team Owners: Design Lead, Accessibility Lead, Mobile Lead, Web Lead Created: 2025-11-17 diff --git a/openspec/specs/architecture.md b/openspec/specs/architecture.md index ebfc6cd..107187c 100644 --- a/openspec/specs/architecture.md +++ b/openspec/specs/architecture.md @@ -31,7 +31,27 @@ Implementation notes - Platform decision path: compare RN/Expo vs Flutter (mobile) and Next.js vs Flutter Web (web) in focused proposals; both must meet a11y and parity requirements. - Feature flags for risky changes; explicit rollback procedures in each proposal. -Decisions +## Supporting Infrastructure Specs + +### Data Model +- Consolidated schema with all entities across features +- Field-level data classification (Public/PII/PHI) +- Relationships, indexing, retention policies +- See: `openspec/specs/data-model.md` + +### Authentication & Authorization +- OAuth2/OIDC with RBAC and pseudonym support +- Session management, MFA, account security +- Compliance-friendly audit logging +- See: `openspec/specs/authentication.md` + +### Design System +- Unified component library across Android/iOS/Web +- Design tokens (colors, typography, spacing) +- WCAG 2.2 AA+ accessibility built-in +- See: `openspec/specs/design-system.md` + +## Decisions - Client platform decisions diff --git a/openspec/specs/authentication.md b/openspec/specs/authentication.md new file mode 100644 index 0000000..01b8f09 --- /dev/null +++ b/openspec/specs/authentication.md @@ -0,0 +1,137 @@ +# Authentication & Authorization System + +Status: approved +Owners: Security, Identity, Architecture +Last updated: 2025-11-18 +Related proposal: `openspec/changes/2025-11-17-authentication-system/proposal.md` + +## Overview + +OAuth2/OIDC-based authentication system with role-based access control (RBAC), pseudonym support, session management, and compliance-friendly audit logging. + +## User Stories + +- As a user, I can sign up with email/password and verify my email +- As a user, I can log in securely and stay logged in across devices +- As a user, I can use a pseudonym in the community without exposing my real name +- As a moderator, I have elevated permissions to manage flagged content +- As an admin, I can view audit logs of authentication events + +## Authentication Flow + +### Sign Up +- Email/password registration with email verification +- Password hashing: Argon2id (preferred) or bcrypt with high work factor +- Verification email with time-limited token + +### Sign In +- OAuth2 authorization code flow with PKCE +- Support for refresh token rotation (30-day expiry) +- Access tokens: short-lived (15 min), JWT signed +- Refresh tokens: opaque, stored server-side, rotated + +### Session Management +- Access tokens: 15 min expiry +- Refresh tokens: 30 days, rotated on use +- HttpOnly, Secure, SameSite cookies for web +- Secure storage for mobile apps + +## API Endpoints + +- `POST /api/v1/auth/signup` — register new user +- `POST /api/v1/auth/verify-email` — verify email with token +- `POST /api/v1/auth/login` — OAuth2 authorization code flow +- `POST /api/v1/auth/token` — exchange code for tokens (PKCE) +- `POST /api/v1/auth/refresh` — rotate refresh token +- `POST /api/v1/auth/logout` — revoke refresh token +- `POST /api/v1/auth/password-reset-request` — send reset email +- `POST /api/v1/auth/password-reset-confirm` — reset password with token +- `POST /api/v1/auth/mfa/enable` — enable TOTP MFA +- `POST /api/v1/auth/mfa/verify` — verify TOTP code +- `GET /api/v1/auth/me` — get current user info + +## Roles & Permissions + +### Roles +- **member**: read public content, write forum, read own profile +- **moderator**: manage flagged content, moderate forum +- **admin**: admin panel, user management, system audit logs + +### RBAC Enforcement +- Middleware-based permission checks on protected endpoints +- Role-based scopes in JWT tokens +- Fine-grained permissions per resource + +## Multi-Factor Authentication (MFA) + +- TOTP (time-based one-time password) support +- Opt-in (not mandatory initially) +- QR code + manual entry for setup +- Accessible to users with assistive tech + +## Account Security + +- Password reset: time-limited tokens (15 min) +- Account lockout: after 5 failed login attempts, lock for 30 min +- Brute force protection: rate limit login endpoint (10 attempts per IP per minute) +- Password reset rate limit: 3 per hour per email +- Lockout notification via email + +## Pseudonym Support + +- User profile includes optional `pseudonym` field +- Forum/community contexts display pseudonym (if set), otherwise display_name +- Moderation/admin views show both pseudonym and real identity +- Audit logging for identity reveals + +## Privacy & Compliance + +- Email is PII, never logged in plain text +- Passwords never logged +- Audit log: login attempts, password resets, MFA changes (no credentials) +- DSR support: export auth history, delete purges tokens and auth records +- Consistent error messages for signup/login (prevent email enumeration) + +## Data Model + +- **User**: id, email (PII, unique), password_hash, email_verified, mfa_enabled, mfa_secret (encrypted), locked_until, failed_login_attempts, created_at, updated_at, deleted_at +- **Role**: id, name, permissions +- **UserRole**: id, user_id (FK), role_id (FK) +- **RefreshToken**: id, user_id (FK), token_hash, expires_at, created_at, revoked_at +- **AuthAuditLog**: id, user_id (FK, nullable), event_type, ip_address, user_agent, created_at + +## Security Standards + +- PKCE required for mobile/SPA +- No custom auth protocol; OAuth2/OIDC standards only +- Rate limiting on all auth endpoints +- Token rotation for refresh tokens +- Session invalidation on logout +- Audit trail for all auth events + +## Observability & Telemetry + +- Metrics: login success/failure rates, MFA adoption, lockout frequency +- Alerts: spike in failed logins, lockout rate anomalies +- Traces: auth flow latency (signup, login, token exchange) + +## Testing + +- Unit tests: password hashing, token generation/validation, RBAC +- Integration tests: full auth flows (signup, login, refresh, logout, MFA) +- Security tests: brute force protection, PKCE validation, token expiry +- Accessibility tests: keyboard nav on auth forms, screen reader labels +- Compliance tests: DSR export includes auth history, delete purges tokens + +## Rollout Plan + +- Deploy to staging; test with pilot users +- Migrate existing users with password reset flow +- Feature flag for MFA (opt-in) +- Monitor login success rates; rollback on anomalies + +## Open Questions + +- Social login (Google, Apple) support timeline? (Future proposal) +- Passkey/WebAuthn support? (Future proposal) +- Session timeout for inactivity? diff --git a/openspec/specs/data-model.md b/openspec/specs/data-model.md index f941110..078f557 100644 --- a/openspec/specs/data-model.md +++ b/openspec/specs/data-model.md @@ -1,15 +1,84 @@ -# Data Model +# Data Model v1 (Consolidated Schema) -Status: draft -Owners: Architecture, Data +Status: approved +Owners: Architecture, Data, Compliance +Last updated: 2025-11-18 +Related proposal: `openspec/changes/2025-11-17-data-model-v1/proposal.md` -Entities (initial) -- User, Profile, Consent, ForumCategory, ForumThread, ForumPost, BlogPost, Resource, PodcastEpisode, Tribute, Product, Order, MediaAsset. +## Core Entities -Notes -- Mark each field with data class (Public/PII/PHI) and retention policy. -- Define soft‑delete vs hard‑delete behavior for user‑generated content. +### User & Identity +- **User**: id, email (PII), password_hash, created_at, updated_at, deleted_at +- **Profile**: id, user_id (FK), display_name, pseudonym, pronouns, avatar_url, bio, health_journey (PHI), consent_flags, created_at, updated_at +- **Role**: id, name (member, moderator, admin), permissions +- **UserRole**: id, user_id (FK), role_id (FK) +- **Consent**: id, user_id (FK), consent_type, granted, granted_at, revoked_at -Migrations -- Version every schema change; ensure reversible steps; seed data for initial categories/resources. +### Forum Domain +- **ForumCategory**: id, name, description, order, created_at +- **ForumThread**: id, category_id (FK), author_id (FK User), title, pinned, locked, created_at, updated_at +- **ForumPost**: id, thread_id (FK), author_id (FK User), parent_post_id (FK), content (may contain PHI), deleted_at, created_at, updated_at +- **ForumReaction**: id, post_id (FK), user_id (FK), emoji_code, created_at +- **ForumReport**: id, post_id (FK), reporter_id (FK User), reason, status, moderator_notes, resolved_at, created_at + +### Content Domain +- **BlogPost**: id, author_id (FK User), title, slug, content, published_at, created_at, updated_at +- **Resource**: id, title, slug, content, access_tier (public/members), tags, created_at, updated_at + +### Media & Tributes +- **PodcastEpisode**: id, title, description, audio_url, duration, published_at, created_at +- **TributeEntry**: id, author_id (FK User), subject_name, memorial_text (may contain PHI), published, created_at, updated_at + +### Commerce +- **MerchProduct**: id, name, description, price, stock_count, created_at, updated_at +- **Order**: id, user_id (FK), total, status, shipping_address (PII), created_at, updated_at + +## Data Classification + +- **Public**: ForumCategory, PodcastEpisode, Resource (public tier), MerchProduct, BlogPost (published) +- **PII**: User.email, Profile.display_name, Order.shipping_address, Profile.avatar_url +- **PHI**: Profile.health_journey, ForumPost.content (context-dependent), TributeEntry.memorial_text (context-dependent) + +## Relationships & Constraints + +- User → Profile (1:1, cascade delete) +- User → ForumPost (1:N, soft-delete user → anonymize posts) +- User → ForumThread (1:N) +- ForumCategory → ForumThread (1:N) +- ForumThread → ForumPost (1:N, cascade delete) +- ForumPost → ForumReaction (1:N, cascade delete) +- ForumPost → ForumReport (1:N) +- User → BlogPost (1:N) +- User → TributeEntry (1:N) +- User → Order (1:N) + +## Indexing Strategy + +- User: email (unique), created_at +- Profile: user_id (unique FK) +- ForumThread: category_id, author_id, created_at +- ForumPost: thread_id, author_id, created_at +- BlogPost: slug (unique), author_id, published_at +- Resource: slug (unique), access_tier, tags (GIN/array) +- Order: user_id, created_at + +## Retention & Soft-Delete + +- **User**: soft-delete (90-day window); anonymize posts on hard-delete +- **ForumPost**: soft-delete (90-day window); replace author with "[deleted]" on user delete +- **BlogPost, TributeEntry**: indefinite retention unless user requests DSR delete +- **Order**: 7-year retention (tax compliance), then hard-delete + +## Migrations + +- Versioned migrations (Alembic, Flyway, or similar) +- Idempotent scripts for rollback safety +- Seed data: initial categories, default consents, sample resources + +## Security & Compliance + +- Encryption at rest: PII/PHI fields encrypted at database or app level +- Access controls: RBAC at API layer; RLS for multi-tenancy if needed +- Audit logging: all PHI/PII mutations logged (excluding content) +- DSR support: export and delete operations mapped to all entities diff --git a/openspec/specs/design-system.md b/openspec/specs/design-system.md new file mode 100644 index 0000000..937833e --- /dev/null +++ b/openspec/specs/design-system.md @@ -0,0 +1,213 @@ +# Design System & Component Library + +Status: approved +Owners: Design, Accessibility, Mobile, Web +Last updated: 2025-11-18 +Related proposal: `openspec/changes/2025-11-17-design-system/proposal.md` + +## Overview + +Unified design system and component library for Android, iOS, and Web that ensures platform parity, accessibility (WCAG 2.2 AA+), and consistent brand identity. + +## Design Tokens + +### Colors + +**Primary Palette** +- Primary: `#3B82F6` (blue, adjust for brand) +- Secondary: `#8B5CF6` (purple) +- Error: `#EF4444` +- Success: `#10B981` +- Warning: `#F59E0B` + +**Background & Text** +- Light background: `#FFFFFF` +- Dark background: `#1F2937` +- Light text: `#111827` +- Dark text: `#F9FAFB` +- Border light: `#D1D5DB` +- Border dark: `#4B5563` + +### Typography + +**Font Family** +- iOS: SF Pro +- Android: Roboto +- Web: Inter / system-ui + +**Font Sizes** +- 12px, 14px, 16px (base), 18px, 20px, 24px, 32px, 48px + +**Font Weights** +- 400 (normal), 600 (semibold), 700 (bold) + +**Line Heights** +- 1.5 (body), 1.25 (headings) + +### Spacing + +**Base Unit**: 4px + +**Scale** +- 0 (0px), 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px), 20 (80px) + +### Border Radius + +- sm: 4px +- md: 8px +- lg: 12px +- full: 9999px (pills/circles) + +### Shadows + +- sm: `0 1px 2px rgba(0,0,0,0.05)` +- md: `0 4px 6px rgba(0,0,0,0.1)` +- lg: `0 10px 15px rgba(0,0,0,0.15)` + +## Core Components + +### Button +- Variants: primary, secondary, ghost, danger +- Sizes: sm, md, lg +- States: default, hover, active, disabled, loading +- Accessibility: role="button", aria-label if icon-only, keyboard enter/space +- Touch target: min 44x44pt + +### Input +- Types: text, email, password, textarea, number +- States: default, focus, error, disabled +- Validation: inline error messages with icon +- Accessibility: visible or aria-label, aria-describedby for errors + +### Card +- Variants: elevated (shadow), outlined (border), flat +- Structure: header (optional), body, footer (optional) +- Accessibility: semantic sectioning (article/section) + +### Modal / Dialog +- Backdrop overlay with dialog container +- Close button with clear affordance +- Accessibility: role="dialog", aria-modal, focus trap, Esc to close +- Focus management: return focus on close + +### Navigation +- **Mobile**: bottom tab bar, app bar (top), drawer (side) +- **Web**: top nav, sidebar (collapsible), breadcrumbs +- Accessibility: role="navigation", aria-current for active route + +### Form +- Validation helpers +- Error state styling +- Field grouping +- Accessibility: associated labels, error announcements + +### Additional Components +- Checkbox, Radio, Select/Dropdown +- Avatar, Badge, Chip/Tag +- Spinner/Loading, Progress bar +- Tabs, Accordion +- List (virtualized), Link +- Toast/Snackbar + +## Accessibility (WCAG 2.2 AA+) + +### Core Requirements +- **Keyboard navigation**: tab order, focus indicators, enter/space activation +- **Screen readers**: accessible names, roles, states via ARIA +- **Color contrast**: 4.5:1 for text, 3:1 for UI components +- **Dynamic type**: components scale with user font size +- **Reduced motion**: animations respect `prefers-reduced-motion` +- **Touch targets**: minimum 44x44pt (mobile), 44x44px (web) + +### Theme Support +- **Light mode** (default) +- **Dark mode** +- **High contrast mode** (7:1+ contrast ratios) + +### Platform-Specific +- **iOS**: VoiceOver support, SF Symbols, native haptics +- **Android**: TalkBack support, Material icons, ripple effects +- **Web**: semantic HTML, focus-visible CSS, responsive + +## Platform Adapters + +### Mobile (React Native) +- Shared design tokens in JavaScript/JSON +- Platform-specific implementations for iOS/Android +- Expo modules for advanced features +- E2E testing via Detox + +### Web (Next.js/React) +- Design tokens in CSS custom properties +- Semantic HTML with ARIA +- Responsive design (mobile-first) +- Storybook for documentation + +## Theming System + +- Design tokens in single source of truth +- Light/dark/high-contrast variants +- Runtime theme switching +- CSS variables for web, object config for mobile +- Support for future brand customization + +## Testing & Quality Assurance + +### Automated Tests +- Unit tests: component prop variations, state changes +- Accessibility tests: + - Web: axe, react-native-a11y linters (mobile) + - Automated checks in CI +- Visual regression: screenshot tests for all variants (light/dark/high contrast) +- Cross-platform parity checks + +### Manual Testing +- VoiceOver (iOS) / TalkBack (Android) / NVDA/JAWS (web) +- Keyboard-only navigation +- High contrast mode verification +- Touch interaction validation + +## Documentation + +- **Storybook** for web component showcase +- **Example app** for mobile components +- **Design specifications** for each component +- **Accessibility guidelines** per platform +- **Brand guidelines** and usage patterns + +## Release & Versioning + +- Semantic versioning (1.0.0) +- Changelog for breaking changes +- Migration guides for component updates +- Quarterly release cycle with patches as needed + +## Rollout Plan + +**Phase 1 (Core Components)** +- Design tokens + colors, typography, spacing +- Button, Input, Card, Modal +- Basic theming (light/dark) + +**Phase 2 (Navigation & Forms)** +- Navigation components +- Form helpers +- List (virtualized) + +**Phase 3 (Advanced Components)** +- Tabs, Accordion +- Complex interactions +- Advanced theming (high contrast) + +## Integration with Features + +- Forum MVP uses design system components +- All new features must use design system +- No custom component creation without approval +- Design review for component additions + +## Open Questions + +- Final brand colors and logo? (use placeholders initially) +- Icon library choice (SF Symbols, Material, custom SVG)? +- Animation library (Framer Motion for web, Reanimated for mobile)?