feat(openspec): propose foundational infrastructure specs

Add three critical infrastructure proposals for implementation readiness: 1. Data Model v1 (Consolidated Schema) - All entities from approved features (User, Profile, Forum, Blog, etc.) - Field-level data classification (Public/PII/PHI) - Relationships, indexes, and retention policies - DSR support and migration strategy - Target: openspec/specs/data-model.md 2. Authentication & Authorization System - OAuth2/OIDC with PKCE for secure auth - RBAC (member, moderator, admin roles) - Pseudonym support for privacy - MFA (TOTP), password reset, account lockout - Audit logging for compliance - Target: openspec/specs/architecture.md 3. Design System & Component Library - Unified components for Android/iOS/Web parity - WCAG 2.2 AA+ accessibility built-in - Design tokens (colors, typography, spacing) - Theming (light/dark/high contrast) - Platform-specific adaptations (RN, Next.js) - Target: openspec/specs/architecture.md These proposals unblock implementation work across all features. /review areas=backend,security,compliance,accessibility,mobile,web,design
2025-11-18 00:17:49 +00:00 · 2025-11-18 00:17:49 +00:00 · 0afa81280e
commit 0afa81280e
parent 7fdc900f3b
3 changed files with 466 additions and 0 deletions
--- a/openspec/changes/2025-11-17-authentication-system/proposal.md
+++ b/openspec/changes/2025-11-17-authentication-system/proposal.md
@ -0,0 +1,153 @@
 # Proposal: Authentication & Authorization System
 Status: draft
 Authors: Security Team, Identity Team
 Owners: Security Lead, Identity Lead, Architecture Lead
 Created: 2025-11-17
 Scope: spec
 Related: openspec/specs/architecture.md, openspec/specs/privacy-compliance.md
 Summary
 - Implement OAuth2/OIDC-based authentication with role-based access control (RBAC), pseudonym support, session management, and compliance-friendly audit logging.
 Motivation
 - Secure user authentication is foundational for all features.
 - Support privacy-conscious identity (pseudonyms) while maintaining accountability.
 - Enable fine-grained authorization for member-only content, moderation, and admin actions.
 Goals / Non-Goals
 - Goals: OAuth2/OIDC auth flow, session management, RBAC, pseudonym handling, MFA support, password reset, account lockout, audit logging.
 - Non-Goals: custom auth protocol (use standards); biometric auth (future); SSO with external providers (future, but design for extensibility).
 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.
 Requirements
 Functional
 - Sign up: email/password registration with email verification.
 - Sign in: OAuth2 authorization code flow with PKCE (for mobile/SPA security).
 - Session management: access tokens (short-lived, 15 min) and refresh tokens (long-lived, 30 days, rotated).
 - Password management: secure hashing (Argon2 or bcrypt), reset flow with time-limited tokens.
 - MFA: TOTP (time-based one-time password) support for opt-in users.
 - Account lockout: after N failed login attempts (e.g., 5), lock for configurable duration (e.g., 30 min).
 - RBAC: roles (member, moderator, admin) with permissions (read_public, write_forum, moderate_content, admin_panel).
 - Pseudonym support: user can set pseudonym in profile; display in forum/community contexts.
 Accessibility
 - Sign-in/sign-up forms: keyboard accessible, screen reader labels, clear error messages.
 - MFA setup: accessible QR code alternatives (manual entry codes).
 - Password strength feedback: descriptive, not relying solely on color.
 Privacy & Compliance
 - Email is PII; hashed passwords never logged.
 - Audit log: login attempts, password resets, MFA changes (log user ID, timestamp, IP, outcome; no passwords).
 - Session tokens: stored securely (HttpOnly, Secure, SameSite cookies for web; secure storage for mobile).
 - DSR support: export auth history; delete user account purges tokens and auth records.
 Security & Threat Model
 - Password hashing: Argon2id (preferred) or bcrypt with high work factor.
 - Token security: JWT access tokens (signed, short-lived); refresh tokens (opaque, stored server-side, rotated).
 - PKCE: required for mobile/SPA to prevent authorization code interception.
 - Rate limiting: login endpoint (e.g., 10 attempts per IP per minute); password reset (e.g., 3 per hour per email).
 - Account lockout: protect against brute force; notify user via email on lockout.
 - Audit logging: all auth events logged with sanitized details (no credentials).
 Architecture & API
 Endpoints
 - `POST /api/v1/auth/signup` — register new user (email, password); returns user ID, sends verification email.
 - `POST /api/v1/auth/verify-email` — verify email with token.
 - `POST /api/v1/auth/login` — OAuth2 authorization code flow initiation (returns code).
 - `POST /api/v1/auth/token` — exchange code for access/refresh tokens (PKCE).
 - `POST /api/v1/auth/refresh` — rotate refresh token, get new access 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 (returns QR code + secret).
 - `POST /api/v1/auth/mfa/verify` — verify TOTP code.
 - `GET /api/v1/auth/me` — get current user info (requires access token).
 Data Model
 - User: id, email (PII, unique, hashed for lookup), password_hash, email_verified, mfa_enabled, mfa_secret (encrypted), locked_until (nullable), failed_login_attempts, created_at, updated_at, deleted_at.
 - Role: id, name (member, moderator, admin), permissions (JSON or relation table).
 - 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 (signup, login_success, login_fail, password_reset, etc.), ip_address, user_agent, created_at.
 Session Flow
 1. User signs in → backend generates authorization code.
 2. Client exchanges code (+ PKCE verifier) for access token (JWT, 15 min) and refresh token (opaque, 30 days).
 3. Client includes access token in Authorization header for API calls.
 4. On access token expiry, client uses refresh token to get new access/refresh tokens.
 5. On logout, client revokes refresh token; server invalidates it.
 Pseudonym Handling
 - User profile includes `pseudonym` field (nullable).
 - Forum/community contexts display pseudonym if set, otherwise display_name.
 - Moderation/admin views show both pseudonym and real identity (with audit logging).
 Observability & Telemetry
 - Metrics: login success/failure rates, MFA adoption, lockout frequency.
 - Alerts: spike in failed logins (possible attack), lockout rate exceeds threshold.
 - Traces: auth flow latency (signup, login, token exchange).
 Test Plan
 - Unit tests: password hashing, token generation/validation, RBAC checks.
 - Integration tests: full auth flows (signup, login, refresh, logout, password reset, MFA).
 - Security tests: brute force protection (lockout), PKCE validation, token expiry.
 - Accessibility tests: keyboard nav on auth forms, screen reader labels.
 - Compliance tests: DSR export includes auth history, delete purges tokens.
 Migration / Rollout Plan
 - Deploy auth service to staging; test with pilot users.
 - Migrate existing users (if any from Wix) with password reset flow (cannot import passwords).
 - Feature flag for MFA (opt-in, not mandatory initially).
 - Monitor login success rates; rollback on anomalies.
 Risks & Mitigations
 - Password database breach → use Argon2id, salted hashes; consider encrypted fields.
 - Token leakage → short-lived access tokens, secure storage, HttpOnly cookies.
 - Account enumeration → consistent error messages for signup/login ("email or password incorrect").
 - Lockout abuse → notify user via email, require CAPTCHA after multiple lockouts.
 Alternatives Considered
 - Custom auth vs OAuth2/OIDC → choosing OAuth2/OIDC for standards compliance and future SSO extensibility.
 - JWT vs opaque refresh tokens → choosing opaque (server-side validation) for better revocation control.
 Work Breakdown
 1. Implement password hashing and user registration
 2. Build OAuth2 authorization code + PKCE flow
 3. Token generation, validation, and refresh logic
 4. RBAC middleware and permission checks
 5. MFA (TOTP) setup and verification
 6. Password reset flow
 7. Account lockout logic
 8. Audit logging
 9. Client SDKs (mobile, web) for auth flows
 10. Security review and penetration testing
 Acceptance Criteria
 - Signup, login, refresh, logout flows functional and tested.
 - MFA (TOTP) opt-in working.
 - RBAC permissions enforced on protected endpoints.
 - Password reset flow with time-limited tokens.
 - Account lockout after failed attempts.
 - Audit logs capture all auth events (sanitized).
 - Accessibility checks pass on auth UI.
 - Security review completed with no critical findings.
 - Pseudonym display working in community contexts.
 Open Questions
 - Social login (Google, Apple) support timeline? (Future proposal)
 - Passkey/WebAuthn support? (Future proposal)
 - Session timeout for inactivity (in addition to token expiry)?
 Slash Commands
 - `/review areas=security,backend,mobile,web,accessibility,compliance`
 - `/apply spec=openspec/specs/architecture.md`
 - `/archive link=<PR>`
--- a/openspec/changes/2025-11-17-data-model-v1/proposal.md
+++ b/openspec/changes/2025-11-17-data-model-v1/proposal.md
@ -0,0 +1,140 @@
 # Proposal: Data Model v1 (Consolidated Schema)
 Status: draft
 Authors: Architecture Team, Data Team
 Owners: Architecture Lead, Data Lead, Compliance Lead
 Created: 2025-11-17
 Scope: spec
 Related: openspec/specs/data-model.md
 Summary
 - Consolidate all entity schemas from approved feature specs into a unified data model with field-level data classification, relationships, and migration strategy.
 Motivation
 - Ensure consistent data modeling across all features before implementation begins.
 - Establish clear PHI/PII boundaries and retention policies at the schema level.
 - Enable efficient backend development with well-defined entities and relationships.
 Goals / Non-Goals
 - Goals: consolidated entity schemas, field-level data classes (Public/PII/PHI), relationships/foreign keys, indexing strategy, retention/soft-delete rules, migration versioning.
 - Non-Goals: vendor-specific schema syntax (use portable DDL concepts); performance tuning (covered in implementation).
 Requirements
 Functional
 - All entities from approved specs: User, Profile, ForumCategory, ForumThread, ForumPost, ForumReaction, ForumReport, BlogPost, PodcastEpisode, TributeEntry, Resource, MerchProduct, etc.
 - Relationships clearly defined with foreign keys and cascade rules.
 - Indexes for common query patterns (user lookups, thread pagination, search, etc.).
 Privacy & Compliance
 - Every field tagged with data class: Public, PII, or PHI.
 - PHI fields isolated where possible; encryption requirements noted.
 - Retention policies per entity (e.g., soft-delete window, hard-delete rules).
 - DSR support: export and delete operations mapped to entities.
 Data Model
 Core Entities
 - User: id, email (PII), created_at, updated_at, deleted_at
 - Profile: id, user_id (FK), display_name, pseudonym, pronouns, avatar_url, bio, health_journey (PHI, private by default), consent_flags, created_at, updated_at
 - 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 ForumPost, nullable), 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
 - BlogPost: id, author_id (FK User), title, slug, content, published_at, created_at, updated_at
 - 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
 - Resource: id, title, slug, content, access_tier (public/members), tags, created_at, updated_at
 - 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
 - Consent: id, user_id (FK), consent_type, granted, granted_at, revoked_at
 Relationships
 - 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)
 Data Classification Summary
 - 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)
 Indexing Strategy
 - User: email (unique), created_at
 - Profile: user_id (unique FK)
 - ForumThread: category_id, author_id, created_at, updated_at
 - ForumPost: thread_id, author_id, created_at
 - BlogPost: slug (unique), author_id, published_at
 - Resource: slug (unique), access_tier, tags (GIN/array index)
 - Order: user_id, created_at
 Retention & Soft-Delete
 - User: soft-delete (deleted_at); 90-day window before hard-delete; anonymize posts.
 - ForumPost: soft-delete (deleted_at); 90-day window; on user delete → replace author with "[deleted]".
 - BlogPost, TributeEntry: indefinite retention unless user requests DSR delete.
 - Order: 7-year retention for compliance (tax/commerce), then hard-delete.
 Migration Strategy
 - Versioned migrations (e.g., Alembic, Flyway, or similar).
 - Idempotent scripts for rollback safety.
 - Seed data for initial categories, default consents, sample resources.
 Security & Threat Model
 - Encryption at rest: PII/PHI fields encrypted at database level or app level.
 - Access controls: RBAC enforced at API layer; row-level security (RLS) for multi-tenancy if needed.
 - Audit logging: all mutations on PHI/PII entities logged (excluding PHI content itself).
 Observability & Telemetry
 - Schema change tracking in migration logs.
 - Query performance metrics for critical paths (thread list, user profile fetch).
 Test Plan
 - Unit tests for schema constraints (foreign keys, unique indexes).
 - Integration tests for cascade deletes and soft-delete behavior.
 - DSR export/delete tests: verify all user data is captured or purged.
 - Retention tests: simulate time-based purges.
 Migration / Rollout Plan
 - Deploy schema migrations to staging; run dry-run seeds.
 - Validate with read-only queries before enabling writes.
 - Rollback plan: revert migration, restore from backup if needed.
 Risks & Mitigations
 - Schema drift across features → enforce single source of truth in data-model.md.
 - PHI leakage → code reviews and automated scanning for PHI in logs.
 Alternatives Considered
 - NoSQL vs relational: choosing relational (Postgres) for strong consistency, relationships, and mature tooling.
 - Schema-per-feature vs unified: choosing unified for easier joins and data integrity.
 Work Breakdown
 1. Document all entity schemas in `data-model.md`
 2. Generate migration scripts from schema
 3. Seed test data for development
 4. Validate DSR export/delete coverage
 5. Review with compliance and security teams
 Acceptance Criteria
 - All approved feature entities documented in `data-model.md` with field-level data classes.
 - Relationships and indexes defined.
 - Retention and soft-delete rules specified.
 - DSR export/delete coverage verified.
 - Sign-off from compliance and security teams.
 Open Questions
 - Specific database vendor (Postgres assumed, but could be vendor-specific features)?
 - Multi-region replication strategy (future proposal)?
 - Real-time sync requirements for forum (WebSocket state management)?
 Slash Commands
 - `/review areas=backend,compliance,security,data`
 - `/apply spec=openspec/specs/data-model.md`
 - `/archive link=<PR>`
--- a/openspec/changes/2025-11-17-design-system/proposal.md
+++ b/openspec/changes/2025-11-17-design-system/proposal.md
@ -0,0 +1,173 @@
 # Proposal: Design System & Component Library
 Status: draft
 Authors: Design Team, Accessibility Team
 Owners: Design Lead, Accessibility Lead, Mobile Lead, Web Lead
 Created: 2025-11-17
 Scope: spec
 Related: openspec/specs/architecture.md, openspec/specs/accessibility.md
 Summary
 - Build a unified design system and component library for Android, iOS, and Web that ensures platform parity, accessibility (WCAG 2.2 AA+), and consistent brand identity.
 Motivation
 - Accelerate feature development with reusable, accessible components.
 - Ensure consistent UX and visual language across all platforms.
 - Embed accessibility best practices at the component level.
 - Support theming for future customization (light/dark mode, high contrast).
 Goals / Non-Goals
 - Goals: component library (buttons, inputs, cards, modals, navigation), design tokens (colors, typography, spacing), accessibility built-in, platform adapters, documentation/Storybook, versioning.
 - Non-Goals: final brand identity (can be iterated); advanced animations (keep simple initially); custom illustrations (use placeholders).
 User Stories
 - As a developer, I can import pre-built, accessible components to build features quickly.
 - As a user with low vision, I can enable high contrast mode and components adapt automatically.
 - As a user, I experience consistent visual design whether I'm on mobile or web.
 - As a designer, I have a single source of truth for design tokens and component specs.
 Requirements
 Functional
 - Core components: Button, Input (text, email, password, textarea), Checkbox, Radio, Select/Dropdown, Card, Modal/Dialog, Toast/Snackbar, Tabs, Accordion, Navigation (app bar, bottom nav, sidebar), List (virtualized), Avatar, Badge, Chip/Tag, Spinner/Loading, Progress bar, Form (validation helpers), Link.
 - Platform implementations: React Native components (mobile), Next.js/React components (web), with shared design tokens.
 - Theming: light mode (default), dark mode, high contrast mode.
 - Design tokens: colors (primary, secondary, background, text, error, success, etc.), typography (font families, sizes, weights, line heights), spacing (4px grid), border radius, shadows.
 Accessibility (WCAG 2.2 AA+)
 - All components support:
  - Keyboard navigation (tab order, focus indicators, enter/space activation).
  - Screen reader labels (accessible names, roles, states).
  - Color contrast: minimum 4.5:1 for text, 3:1 for UI components.
  - Dynamic type: components scale with user font size preferences.
  - Reduced motion: animations respect `prefers-reduced-motion`.
  - Touch targets: minimum 44x44pt (mobile), 44x44px (web).
 - High contrast mode: boost contrast ratios to 7:1+.
 - Focus management: modals trap focus, dismissible with Esc, return focus on close.
 Design Tokens
 Colors
 - Primary: `#3B82F6` (blue, adjust for brand)
 - Secondary: `#8B5CF6` (purple)
 - Background: `#FFFFFF` (light), `#1F2937` (dark)
 - Text: `#111827` (light mode), `#F9FAFB` (dark mode)
 - Error: `#EF4444`
 - Success: `#10B981`
 - Warning: `#F59E0B`
 - Border: `#D1D5DB` (light), `#4B5563` (dark)
 Typography
 - Font family: system fonts (SF Pro for iOS, Roboto for Android, Inter/system-ui for web)
 - 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)`
 Component Specifications
 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, focus ring
 - Touch target: min 44x44
 Input
 - Types: text, email, password, textarea, number
 - States: default, focus, error, disabled
 - Accessibility: label (visible or aria-label), aria-describedby for errors, role="textbox" for textarea
 - Validation: inline error messages with icon, clear error state styling
 Card
 - Variants: elevated (shadow), outlined (border), flat
 - Structure: header (optional), body, footer (optional)
 - Accessibility: semantic sectioning (article/section), focus ring if interactive
 Modal
 - Structure: overlay (backdrop), dialog container, close button
 - Accessibility: role="dialog", aria-modal="true", trap focus, Esc to close, return focus on close, aria-labelledby for title
 - Animations: respect prefers-reduced-motion
 Navigation
 - Mobile: bottom tab bar, app bar (top), drawer (side)
 - Web: top nav, sidebar (collapsible), breadcrumbs
 - Accessibility: role="navigation", aria-current for active route, keyboard nav (arrow keys for tabs)
 Platform-Specific Considerations
 - iOS: use SF Symbols for icons, native haptics for interactions, iOS navigation patterns (back swipe).
 - Android: use Material icons, ripple effects, Android navigation patterns (drawer, bottom nav).
 - Web: use accessible HTML (semantic tags), focus-visible CSS, responsive breakpoints.
 Observability & Telemetry
 - Component usage analytics (opt-in): track which components are most used to prioritize improvements.
 - Accessibility metrics: track high contrast mode adoption, screen reader usage (if detectable).
 Test Plan
 - Unit tests: component prop variations, state changes, event handlers.
 - Accessibility tests:
  - Automated: axe (web), react-native-a11y linters (mobile).
  - Manual: VoiceOver (iOS), TalkBack (Android), NVDA/JAWS (web), keyboard-only nav.
 - Visual regression: screenshot tests for all component variants (light/dark/high contrast).
 - Cross-platform parity: ensure components look consistent on Android, iOS, Web.
 Migration / Rollout Plan
 - Phase 1: Design tokens + core components (Button, Input, Card, Modal).
 - Phase 2: Navigation, Form helpers, List.
 - Phase 3: Advanced components (Tabs, Accordion, etc.).
 - Versioning: semantic versioning (1.0.0), changelog for breaking changes.
 - Migration guide for existing components (if any from early development).
 Risks & Mitigations
 - Platform drift → enforce design review for all component changes; automated visual regression tests.
 - Accessibility regressions → CI gates for a11y linters; manual audits per release.
 - Over-engineering → start with MVP components; add complexity only when needed.
 Alternatives Considered
 - Custom vs existing design system (Material, Chakra, Ant Design) → choosing custom for brand control and accessibility customization, but borrowing patterns from established systems.
 - Shared components vs platform-specific → choosing shared design tokens with platform-specific implementations for best native UX.
 Work Breakdown
 1. Define design tokens (colors, typography, spacing) in config files
 2. Build core components: Button, Input, Card, Modal
 3. Platform adapters: React Native (mobile), Next.js/React (web)
 4. Accessibility audit and fixes
 5. Documentation: Storybook (web), example app (mobile)
 6. Visual regression test setup
 7. Versioning and release process
 8. Design review and feedback iteration
 9. Theming implementation (light/dark/high contrast)
 10. Rollout to first feature (e.g., Forum MVP)
 Acceptance Criteria
 - Core components implemented and documented.
 - All components pass WCAG 2.2 AA automated checks (axe).
 - Manual accessibility audit completed with VoiceOver, TalkBack, NVDA.
 - Visual regression tests passing for all variants.
 - Design tokens consistent across mobile and web.
 - Documentation (Storybook/example app) published.
 - At least one feature (e.g., Forum MVP) uses design system components.
 Open Questions
 - Final brand colors and logo (can use placeholders initially)?
 - Icon library choice (SF Symbols for iOS, Material for Android, custom SVG for web)?
 - Animation library (Framer Motion for web, Reanimated for mobile)?
 Slash Commands
 - `/review areas=mobile,web,accessibility,design`
 - `/apply spec=openspec/specs/architecture.md`
 - `/archive link=<PR>`