@ratim818/allyve-wellness-backend 1.0.0

package/.env.example

@@ -0,0 +1,49 @@
+# ============================================
+# ALLYVE WELLNESS AI — BACKEND CONFIGURATION
+# HIPAA-Compliant Environment Variables
+# ============================================
+# IMPORTANT: Never commit this file to version control.
+# Copy to .env and fill in your values.
+
+# ── Server ────────────────────────────────────
+NODE_ENV=development
+PORT=3001
+API_VERSION=v1
+CORS_ORIGIN=http://localhost:5173
+
+# ── Database (PostgreSQL with SSL) ────────────
+# Use a HIPAA-eligible provider: AWS RDS, GCP Cloud SQL, Azure DB, or Supabase Pro
+DATABASE_URL=postgresql://allyve_user:STRONG_PASSWORD@localhost:5432/allyve_wellness
+DATABASE_SSL=false
+DATABASE_POOL_MIN=2
+DATABASE_POOL_MAX=10
+
+# ── Encryption ────────────────────────────────
+# AES-256 key for encrypting PHI at rest (generate with: openssl rand -hex 32)
+ENCRYPTION_KEY=GENERATE_WITH_openssl_rand_hex_32
+ENCRYPTION_IV_LENGTH=16
+
+# ── Authentication ────────────────────────────
+# JWT secret (generate with: openssl rand -base64 64)
+JWT_SECRET=GENERATE_WITH_openssl_rand_base64_64
+JWT_EXPIRES_IN=15m
+JWT_REFRESH_EXPIRES_IN=7d
+
+# ── Session ───────────────────────────────────
+SESSION_SECRET=GENERATE_WITH_openssl_rand_base64_32
+SESSION_MAX_AGE=900000
+
+# ── HIPAA Audit ───────────────────────────────
+AUDIT_LOG_RETENTION_DAYS=2190
+AUDIT_LOG_LEVEL=info
+
+# ── Rate Limiting ─────────────────────────────
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX_REQUESTS=100
+
+# ── Wearable Integration (future) ────────────
+# APPLE_HEALTHKIT_KEY=
+# GOOGLE_FIT_CLIENT_ID=
+# GOOGLE_FIT_CLIENT_SECRET=
+# FITBIT_CLIENT_ID=
+# FITBIT_CLIENT_SECRET=

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npx vitest run --passWithNoTests

package/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Publish Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npx vitest run --passWithNoTests
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js for npm
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-gpr:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js for GitHub Packages
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@ratim818'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to GitHub Packages
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -0,0 +1,140 @@
+# 🩺 Allyve Wellness AI — HIPAA-Compliant Backend
+
+Production-grade backend for the Allyve maternal health monitoring platform.
+Built with Express, TypeScript, PostgreSQL, and full HIPAA technical safeguards.
+
+## Quick Start
+
+### Prerequisites
+
+- **Node.js** ≥ 18
+- **PostgreSQL** ≥ 15
+- **OpenSSL** (for generating keys)
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Generate your secrets:
+```bash
+# Encryption key (AES-256 — 32 bytes)
+openssl rand -hex 32
+
+# JWT secret
+openssl rand -base64 64
+
+# Session secret
+openssl rand -base64 32
+```
+
+Paste these into your `.env` file.
+
+### 3. Create the database
+
+```bash
+createdb allyve_wellness
+```
+
+### 4. Run migrations
+
+```bash
+npm run migrate
+```
+
+### 5. Seed demo data (optional)
+
+```bash
+npm run seed
+```
+
+Demo login: `sarah.johnson@example.com` / `SecureDemo123!`
+
+### 6. Start the server
+
+```bash
+npm run dev
+```
+
+Server starts at `http://localhost:3001`. API docs at `http://localhost:3001/api/v1`.
+
+---
+
+## Architecture
+
+```
+src/
+├── config/         # Environment config, database connection
+├── middleware/      # Auth (JWT), security (Helmet, CORS, rate limiting)
+├── migrations/     # Database schema, seed data
+├── routes/         # API endpoints (auth, health, appointments, sharing, audit)
+├── services/       # Core logic (auth, encryption, audit trail)
+├── utils/          # Logger (HIPAA-compliant, no PHI in logs)
+└── server.ts       # Express app entry point
+```
+
+## HIPAA Safeguards
+
+| Safeguard | Implementation |
+|---|---|
+| **Encryption at rest** | AES-256-GCM on all PHI fields |
+| **Encryption in transit** | HSTS, TLS required in production |
+| **Authentication** | JWT + bcrypt (12 rounds) + account lockout |
+| **Access control** | RBAC (patient/provider/admin) + ownership checks |
+| **Audit trail** | Immutable PostgreSQL table with DB-level triggers |
+| **Session management** | 15-min timeout, sliding window, revocation |
+| **Input validation** | Zod schemas on every endpoint |
+| **Rate limiting** | 100 req/15min general, 10/15min for auth |
+
+See `docs/HIPAA_COMPLIANCE.md` for the full compliance reference.
+
+## Connecting the Frontend
+
+Copy `docs/frontend-api-client.ts` into your Lovable frontend at `src/services/api.ts`.
+
+Add to your frontend `.env`:
+```
+VITE_API_URL=http://localhost:3001/api/v1
+```
+
+Then update your components to import from `services/api` instead of `data/mockData`.
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Auth | Description |
+|---|---|---|---|
+| POST | /auth/register | ✗ | Create account |
+| POST | /auth/login | ✗ | Login → JWT tokens |
+| POST | /auth/refresh | ✗ | Refresh access token |
+| POST | /auth/logout | ✓ | Logout + revoke session |
+| GET | /auth/me | ✓ | Current user profile |
+| GET | /health/metrics | ✓ | List health metrics |
+| POST | /health/metrics | ✓ | Record health metric |
+| GET | /health/symptoms | ✓ | List symptoms |
+| POST | /health/symptoms | ✓ | Record symptom |
+| GET | /health/mood | ✓ | List mood entries |
+| POST | /health/mood | ✓ | Record mood |
+| GET | /health/journal | ✓ | List journal entries |
+| POST | /health/journal | ✓ | Record journal entry |
+| GET | /health/cardiovascular-risk | ✓ | Latest CV risk |
+| GET | /appointments | ✓ | List appointments |
+| POST | /appointments | ✓ | Create appointment |
+| PUT | /appointments/:id | ✓ | Update appointment |
+| DELETE | /appointments/:id | ✓ | Soft-delete appointment |
+| GET | /share | ✓ | List shared data |
+| POST | /share | ✓ | Share data + consent |
+| POST | /share/:id/revoke | ✓ | Revoke sharing |
+| GET | /audit/logs | ✓ admin | Query audit trail |
+
+## License
+
+Proprietary — Allyve Wellness AI

package/docs/HIPAA_COMPLIANCE.md

@@ -0,0 +1,141 @@
+# Allyve Wellness AI — HIPAA Compliance Reference
+
+## Overview
+
+This backend implements the **HIPAA Security Rule** technical safeguards
+(45 CFR §164.312) for protecting electronic Protected Health Information (ePHI).
+
+---
+
+## Technical Safeguards Implemented
+
+### §164.312(a)(1) — Access Control
+
+| Requirement | Implementation |
+|---|---|
+| Unique user identification | UUID-based user IDs, unique email (HMAC-indexed) |
+| Emergency access procedure | `EMERGENCY_ACCESS` audit action, admin override role |
+| Automatic logoff | 15-min session timeout with sliding window |
+| Encryption/decryption | AES-256-GCM for all PHI at rest |
+
+**Files:** `middleware/auth.ts`, `services/encryption.ts`, `services/auth.ts`
+
+### §164.312(b) — Audit Controls
+
+| Requirement | Implementation |
+|---|---|
+| Hardware/software/procedure audit | Immutable `audit_logs` table with DB-level triggers |
+| Tamper evidence | PostgreSQL triggers prevent UPDATE/DELETE on audit_logs |
+| 6-year retention | Configurable retention, default 2190 days (6 years) |
+| Audit trail contents | WHO, WHAT, WHEN, WHERE, OUTCOME for every action |
+
+**Files:** `services/audit.ts`, `routes/audit.ts`, `migrations/schema.ts`
+
+### §164.312(c)(1) — Integrity Controls
+
+| Requirement | Implementation |
+|---|---|
+| Data integrity | AES-256-GCM provides authenticated encryption (tamper detection) |
+| Soft deletes | `is_deleted` flags — no hard deletes of PHI |
+| Input validation | Zod schemas on all API inputs |
+
+**Files:** `services/encryption.ts`, `routes/health.ts`
+
+### §164.312(d) — Authentication
+
+| Requirement | Implementation |
+|---|---|
+| Person/entity authentication | JWT tokens (short-lived) + refresh tokens |
+| Password requirements | 12+ chars, upper, lower, number, special character |
+| Account lockout | 5 failed attempts → 30-minute lockout |
+| Brute force protection | Rate limiting (10 auth requests / 15 min) |
+
+**Files:** `services/auth.ts`, `middleware/security.ts`
+
+### §164.312(e)(1) — Transmission Security
+
+| Requirement | Implementation |
+|---|---|
+| Encryption in transit | HSTS headers, TLS required in production |
+| Integrity controls | Helmet security headers, CORS restrictions |
+| Cookie security | httpOnly, secure, sameSite=strict |
+
+**Files:** `middleware/security.ts`
+
+---
+
+## Data Encryption Map
+
+| Data Field | Storage | Encryption |
+|---|---|---|
+| Email | `email_encrypted` | AES-256-GCM |
+| Email (lookup) | `email_hash` | HMAC-SHA256 |
+| Password | `password_hash` | bcrypt (12 rounds) |
+| Full name | `full_name_encrypted` | AES-256-GCM |
+| Date of birth | `date_of_birth_encrypted` | AES-256-GCM |
+| Phone number | `phone_encrypted` | AES-256-GCM |
+| Health metric values | `value_encrypted` | AES-256-GCM |
+| ECG waveform data | `waveform_encrypted` | AES-256-GCM |
+| Symptom notes | `notes_encrypted` | AES-256-GCM |
+| Mood notes | `notes_encrypted` | AES-256-GCM |
+| Journal content | `content_encrypted` | AES-256-GCM |
+| Appointment location | `location_encrypted` | AES-256-GCM |
+| Provider contact info | `*_encrypted` | AES-256-GCM |
+
+---
+
+## Remaining Steps for Full HIPAA Compliance
+
+> ⚠️ **This codebase provides the technical safeguards. Full HIPAA compliance
+> also requires administrative and physical safeguards.**
+
+### Before Production
+
+- [ ] **Business Associate Agreement (BAA)** — Sign with your cloud provider
+  (AWS, GCP, Azure, or Supabase Pro all offer HIPAA BAAs)
+- [ ] **SSL/TLS Certificate** — Enforce HTTPS in production (nginx/Caddy/CloudFront)
+- [ ] **Database encryption at rest** — Enable at the infrastructure level
+  (AWS RDS encryption, GCP Cloud SQL encryption)
+- [ ] **Key management** — Move `ENCRYPTION_KEY` to a KMS (AWS KMS, GCP KMS, HashiCorp Vault)
+- [ ] **Backup encryption** — All database backups must be encrypted
+- [ ] **Penetration testing** — Annual security assessment
+- [ ] **Risk assessment** — Document threats, vulnerabilities, and mitigations
+- [ ] **Workforce training** — All team members handling PHI must be trained
+- [ ] **Incident response plan** — Document breach notification procedures
+- [ ] **Privacy officer** — Designate a HIPAA privacy officer
+
+### Administrative Safeguards (Organizational)
+
+- [ ] Written security policies and procedures
+- [ ] Workforce access management procedures
+- [ ] Security incident response procedures
+- [ ] Contingency / disaster recovery plan
+- [ ] Regular security evaluations
+
+### Physical Safeguards
+
+- [ ] Facility access controls (if self-hosting)
+- [ ] Workstation security policies
+- [ ] Device and media disposal procedures
+
+---
+
+## API Security Headers
+
+All responses include these security headers (via Helmet):
+
+```
+Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+X-XSS-Protection: 1; mode=block
+Content-Security-Policy: default-src 'self'
+Referrer-Policy: strict-origin-when-cross-origin
+```
+
+---
+
+## Contact
+
+For HIPAA compliance questions or to report a security concern,
+contact your designated Security Officer.

package/docs/frontend-api-client.ts

@@ -0,0 +1,259 @@
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * ALLYVE API CLIENT
+ * ═══════════════════════════════════════════════════════════════
+ * Drop this file into your Lovable frontend at:
+ *   src/services/api.ts
+ *
+ * Then update your hooks and components to use these functions
+ * instead of importing from data/mockData.ts.
+ * ═══════════════════════════════════════════════════════════════
+ */
+
+const API_BASE = import.meta.env.VITE_API_URL || "http://localhost:3001/api/v1";
+
+// ── Token Management ────────────────────────────────────────
+
+let accessToken: string | null = null;
+
+export function setAccessToken(token: string | null) {
+  accessToken = token;
+}
+
+export function getAccessToken(): string | null {
+  return accessToken;
+}
+
+// ── HTTP Client with Auto-Refresh ───────────────────────────
+
+async function apiRequest<T>(
+  endpoint: string,
+  options: RequestInit = {}
+): Promise<T> {
+  const url = `${API_BASE}${endpoint}`;
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...(options.headers as Record<string, string>),
+  };
+
+  if (accessToken) {
+    headers["Authorization"] = `Bearer ${accessToken}`;
+  }
+
+  let response = await fetch(url, { ...options, headers, credentials: "include" });
+
+  // Auto-refresh on 401 with TOKEN_EXPIRED
+  if (response.status === 401) {
+    const body = await response.json();
+    if (body.code === "TOKEN_EXPIRED") {
+      const refreshed = await refreshToken();
+      if (refreshed) {
+        headers["Authorization"] = `Bearer ${accessToken}`;
+        response = await fetch(url, { ...options, headers, credentials: "include" });
+      }
+    }
+  }
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: "Request failed" }));
+    throw new Error(error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+// ── Auth API ────────────────────────────────────────────────
+
+export async function login(email: string, password: string) {
+  const data = await apiRequest<{ accessToken: string; expiresIn: string }>("/auth/login", {
+    method: "POST",
+    body: JSON.stringify({ email, password }),
+  });
+  setAccessToken(data.accessToken);
+  return data;
+}
+
+export async function register(data: {
+  email: string;
+  password: string;
+  fullName: string;
+  dateOfBirth: string;
+  phone?: string;
+}) {
+  return apiRequest<{ userId: string }>("/auth/register", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}
+
+export async function refreshToken(): Promise<boolean> {
+  try {
+    const data = await apiRequest<{ accessToken: string }>("/auth/refresh", {
+      method: "POST",
+    });
+    setAccessToken(data.accessToken);
+    return true;
+  } catch {
+    setAccessToken(null);
+    return false;
+  }
+}
+
+export async function logout() {
+  try {
+    await apiRequest("/auth/logout", { method: "POST" });
+  } finally {
+    setAccessToken(null);
+  }
+}
+
+export async function getProfile() {
+  return apiRequest<{
+    id: string;
+    email: string;
+    fullName: string;
+    dateOfBirth: string;
+    phone: string | null;
+    pregnancyWeek: number | null;
+    role: string;
+  }>("/auth/me");
+}
+
+// ── Health Metrics API ──────────────────────────────────────
+
+export async function getHealthMetrics(params?: { limit?: number; metric?: string; since?: string }) {
+  const query = new URLSearchParams();
+  if (params?.limit) query.set("limit", String(params.limit));
+  if (params?.metric) query.set("metric", params.metric);
+  if (params?.since) query.set("since", params.since);
+
+  return apiRequest<{ data: any[]; total: number }>(`/health/metrics?${query}`);
+}
+
+export async function recordHealthMetric(data: {
+  metricName: string;
+  value: number | string;
+  unit: string;
+  status: "normal" | "warning" | "critical" | "unknown";
+  trend?: string;
+}) {
+  return apiRequest<{ id: string }>("/health/metrics", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}
+
+// ── Symptoms API ────────────────────────────────────────────
+
+export async function getSymptoms(limit?: number) {
+  return apiRequest<{ data: any[] }>(`/health/symptoms?limit=${limit || 50}`);
+}
+
+export async function recordSymptom(data: {
+  name: string;
+  severity: number;
+  notes?: string;
+  isCardiovascularRelated: boolean;
+}) {
+  return apiRequest<{ id: string }>("/health/symptoms", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}
+
+// ── Mood API ────────────────────────────────────────────────
+
+export async function getMoodEntries(limit?: number) {
+  return apiRequest<{ data: any[] }>(`/health/mood?limit=${limit || 50}`);
+}
+
+export async function recordMood(data: {
+  mood: string;
+  notes?: string;
+  anxietyLevel?: number;
+}) {
+  return apiRequest<{ id: string }>("/health/mood", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}
+
+// ── Journal API ─────────────────────────────────────────────
+
+export async function getJournalEntries(limit?: number) {
+  return apiRequest<{ data: any[] }>(`/health/journal?limit=${limit || 50}`);
+}
+
+export async function recordJournalEntry(data: {
+  content: string;
+  tags?: string[];
+  painScore?: number;
+  anxietyLevel?: number;
+}) {
+  return apiRequest<{ id: string }>("/health/journal", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}
+
+// ── Cardiovascular Risk API ─────────────────────────────────
+
+export async function getCardiovascularRisk() {
+  return apiRequest<{ data: any }>("/health/cardiovascular-risk");
+}
+
+// ── Appointments API ────────────────────────────────────────
+
+export async function getAppointments() {
+  return apiRequest<{ data: any[] }>("/appointments");
+}
+
+export async function createAppointment(data: {
+  title: string;
+  providerName: string;
+  providerType: string;
+  date: string;
+  location?: string;
+  notes?: string;
+  isTelehealth?: boolean;
+}) {
+  return apiRequest<{ id: string }>("/appointments", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}
+
+export async function updateAppointment(id: string, data: Record<string, unknown>) {
+  return apiRequest(`/appointments/${id}`, {
+    method: "PUT",
+    body: JSON.stringify(data),
+  });
+}
+
+export async function deleteAppointment(id: string) {
+  return apiRequest(`/appointments/${id}`, { method: "DELETE" });
+}
+
+// ── Data Sharing API ────────────────────────────────────────
+
+export async function getSharedData() {
+  return apiRequest<{ data: any[] }>("/share");
+}
+
+export async function shareData(data: {
+  recipientName: string;
+  recipientType: "provider" | "family" | "other";
+  recipientEmail?: string;
+  dataTypes: string[];
+  expiresInDays?: number;
+}) {
+  return apiRequest<{ id: string }>("/share", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}
+
+export async function revokeShare(id: string) {
+  return apiRequest(`/share/${id}/revoke`, { method: "POST" });
+}