managarten/.hive-mind/auth-research-decision-matrix.md

# Authentication System Decision Matrix
**Visual Decision Guide | Researcher Agent**
**Date:** 2025-11-25

---

## 🎯 Quick Decision Tree

```
Need Auth for Multi-App Monorepo?
│
├─ Budget < $100/month?
│  │
│  ├─ YES ──→ Better Auth + PostgreSQL ✅ RECOMMENDED
│  │          - FREE
│  │          - Full control
│  │          - All features included
│  │
│  └─ NO ──→  Consider Clerk (if budget > $500/mo)
│              - Best DX
│              - Managed solution
│              - Expensive
│
└─ Already using Supabase heavily?
   │
   ├─ YES ──→ Auth.js + Supabase ⚠️ WITH CAUTION
   │          - Leverage existing infra
   │          - Watch for reliability issues
   │
   └─ NO ──→  Better Auth + PostgreSQL ✅ RECOMMENDED
```

---

## 📊 Technology Comparison Matrix

### Authentication Libraries

|  | Better Auth | Auth.js | Supabase Auth | Clerk | Auth0 |
|---|:-----------:|:-------:|:-------------:|:-----:|:-----:|
| **Cost** | ✅ FREE | ✅ FREE | 💰 $25/mo | 💰💰 $550/mo | 💰💰 $35-240/mo |
| **Setup Complexity** | ⭐⭐⭐⭐ Easy | ⭐⭐⭐ Medium | ⭐⭐⭐⭐⭐ Very Easy | ⭐⭐⭐⭐⭐ Very Easy | ⭐⭐⭐ Medium |
| **TypeScript Support** | ✅ Excellent | ⚠️ Good | ⚠️ Good | ✅ Excellent | ⚠️ Good |
| **2FA Built-in** | ✅ Yes | ❌ No | ⚠️ Limited | ✅ Yes | ✅ Yes |
| **Multi-Session** | ✅ Yes | ⚠️ Custom | ⚠️ Limited | ✅ Yes | ✅ Yes |
| **Auto Schema** | ✅ Yes | ❌ No | ✅ Yes | N/A | N/A |
| **Self-Hosted** | ✅ Yes | ✅ Yes | ⚠️ Hybrid | ❌ No | ❌ No |
| **Vendor Lock-in** | ✅ None | ✅ None | ⚠️ High | ⚠️ High | ⚠️ High |
| **Maintenance Risk** | ⭐⭐⭐⭐ Low | ⚠️ High | ⭐⭐⭐ Medium | ⭐⭐⭐⭐ Low | ⭐⭐⭐⭐ Low |
| **Battle-Tested** | ⚠️ New (2024) | ✅ Mature | ✅ Mature | ✅ Mature | ✅ Mature |
| **Community** | ⭐⭐ Small | ⭐⭐⭐⭐ Large | ⭐⭐⭐ Medium | ⭐⭐⭐ Medium | ⭐⭐⭐⭐ Large |
| **Monorepo Fit** | ✅ Excellent | ⭐⭐⭐ Good | ⭐⭐⭐ Good | ⭐⭐ Limited | ⭐⭐ Limited |

#### Legend
- ✅ Excellent/Yes
- ⭐ Rating (more stars = better)
- ⚠️ Caution/Limited
- ❌ No/Poor
- 💰 Cost indicator (more = higher cost)

---

## 🔐 Security Features Comparison

| Feature | Better Auth | Auth.js | Supabase | Clerk | Auth0 |
|---------|:-----------:|:-------:|:--------:|:-----:|:-----:|
| **Passkeys (WebAuthn)** | ✅ | ⚠️ Plugin | ❌ | ✅ | ✅ |
| **2FA/TOTP** | ✅ | ⚠️ Custom | ⚠️ Limited | ✅ | ✅ |
| **Magic Links** | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Session Management** | ✅ Advanced | ⚠️ Basic | ⚠️ Basic | ✅ Advanced | ✅ Advanced |
| **Device Tracking** | ✅ | ⚠️ Custom | ❌ | ✅ | ✅ |
| **Rate Limiting** | ⚠️ External | ⚠️ External | ⚠️ Limited | ✅ Built-in | ✅ Built-in |
| **Breach Detection** | ❌ | ❌ | ❌ | ✅ | ✅ |
| **Bot Protection** | ⚠️ External | ⚠️ External | ⚠️ Limited | ✅ Built-in | ✅ Built-in |

---

## 💾 Database & ORM Options

### PostgreSQL Features

| Feature | PostgreSQL | MySQL | MongoDB |
|---------|:----------:|:-----:|:-------:|
| **RLS Support** | ✅ Native | ❌ No | ❌ No |
| **ACID Compliance** | ✅ Full | ✅ Full | ⚠️ Limited |
| **JSON Support** | ✅ Excellent | ⚠️ Basic | ✅ Native |
| **Full-Text Search** | ✅ Advanced | ⚠️ Basic | ✅ Good |
| **Better Auth Support** | ✅ Primary | ✅ Yes | ✅ Yes |
| **Maturity** | ✅ 25+ years | ✅ 25+ years | ⭐ 15 years |

**Verdict:** PostgreSQL for multi-tenant security (RLS) and financial accuracy

---

### ORM Comparison

| Feature | Drizzle | Prisma | TypeORM |
|---------|:-------:|:------:|:-------:|
| **Better Auth Support** | ✅ Official | ✅ Official | ⚠️ Generic |
| **Performance** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **Type Safety** | ✅ Excellent | ✅ Excellent | ⚠️ Good |
| **Migration Tools** | ✅ Built-in | ✅ Excellent | ⚠️ Basic |
| **Learning Curve** | ⭐⭐⭐⭐ Easy | ⭐⭐⭐ Medium | ⭐⭐ Hard |
| **Raw SQL Support** | ✅ Excellent | ⚠️ Limited | ✅ Good |

**Verdict:** Drizzle for performance and Better Auth integration

---

## 💳 Payment Gateway Comparison

| Feature | Stripe | PayPal | Square |
|---------|:------:|:------:|:------:|
| **Transaction Fee** | 2.9% + $0.30 | 3.49% + $0.49 | 2.9% + $0.30 |
| **Global Reach** | ✅ 47+ countries | ✅ 200+ countries | ⚠️ Limited |
| **Developer Experience** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| **Documentation** | ✅ Excellent | ⚠️ Good | ✅ Good |
| **Webhook Reliability** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| **Digital Wallets** | ✅ All major | ✅ All major | ⚠️ Limited |
| **Marketplace Features** | ✅ Connect | ⚠️ Limited | ❌ No |
| **Credit Top-ups** | ✅ Perfect fit | ⚠️ Complex | ✅ Good |

**Verdict:** Stripe for best developer experience and features

---

## 🎨 Architecture Patterns Scorecard

### Pattern 1: Centralized Auth + App Tokens (RECOMMENDED)

```
                 ┌──────────────────┐
                 │  Mana Core Auth  │
                 │  - User DB       │
                 │  - Credit System │
                 │  - Issues JWTs   │
                 └────────┬─────────┘
                          │
         ┌────────────────┼────────────────┐
         │                │                │
    ┌────▼────┐     ┌────▼────┐     ┌────▼────┐
    │  App A  │     │  App B  │     │  App C  │
    │Validates│     │Validates│     │Validates│
    │   JWT   │     │   JWT   │     │   JWT   │
    └─────────┘     └─────────┘     └─────────┘
```

**Score: 9/10**
- ✅ Single source of truth
- ✅ Unified credit system
- ✅ Cross-app SSO
- ✅ Consistent security
- ⚠️ Single point of failure (mitigate with HA)

---

### Pattern 2: Federated Auth (Each App Manages Own)

```
    ┌─────────┐     ┌─────────┐     ┌─────────┐
    │  App A  │     │  App B  │     │  App C  │
    │  Auth   │     │  Auth   │     │  Auth   │
    └─────────┘     └─────────┘     └─────────┘
         │               │               │
         └───────────────┼───────────────┘
                         │
                  ┌──────▼──────┐
                  │   Sync DB   │
                  └─────────────┘
```

**Score: 4/10**
- ❌ User data fragmentation
- ❌ Complex credit system
- ❌ No cross-app SSO
- ❌ Inconsistent security
- ✅ Independent scaling

**Verdict:** NOT recommended for Mana ecosystem

---

### Pattern 3: Managed Service (Clerk/Auth0)

```
    ┌───────────────────┐
    │   Clerk/Auth0     │ (External)
    │   - User DB       │
    │   - Session Mgmt  │
    └────────┬──────────┘
             │
    ┌────────┼────────┐
    │        │        │
┌───▼──┐ ┌──▼──┐ ┌───▼──┐
│App A │ │App B│ │App C │
└──────┘ └─────┘ └──────┘
```

**Score: 6/10**
- ✅ Managed infrastructure
- ✅ Advanced features
- ❌ Expensive ($550+/mo)
- ❌ Vendor lock-in
- ⚠️ Less control over flow

**Verdict:** Only if budget allows and team wants managed solution

---

## 🔄 JWT Token Strategies

### Strategy 1: Short-Lived Access + Refresh (RECOMMENDED)

```
Access Token:  15 minutes  ⚡ Fast validation
Refresh Token: 7 days      🔄 Rotate on use
```

**Pros:**
- ✅ Best security (short exposure window)
- ✅ Detects token theft via rotation
- ✅ Industry standard

**Cons:**
- ⚠️ More complexity (refresh flow)
- ⚠️ Database lookups for refresh

**Score: 9/10** - Industry best practice

---

### Strategy 2: Long-Lived Tokens

```
Access Token:  7 days  ⚠️ High risk if stolen
```

**Pros:**
- ✅ Simple implementation
- ✅ No refresh logic needed

**Cons:**
- ❌ High security risk
- ❌ Hard to revoke
- ❌ Violates best practices

**Score: 3/10** - NOT recommended

---

### Strategy 3: Stateful Sessions (Database)

```
Session ID: Stored in DB  🗄️ Always check DB
```

**Pros:**
- ✅ Easy revocation
- ✅ Fine-grained control

**Cons:**
- ❌ Database lookup on every request
- ❌ Doesn't scale well
- ❌ Not suitable for microservices

**Score: 5/10** - Only for monoliths

---

## 💰 Cost Breakdown (10k Active Users)

### Option 1: Recommended Stack

| Component | Monthly Cost |
|-----------|-------------|
| Better Auth | $0 (open-source) |
| PostgreSQL (Supabase Pro) | $25 |
| Auth Service Hosting | $20-50 |
| Stripe Fees (500 txns × $10 avg) | $145-170 |
| **Total** | **$190-245/month** |

---

### Option 2: Clerk

| Component | Monthly Cost |
|-----------|-------------|
| Clerk Business Plan | $550 |
| PostgreSQL (Credit System) | $25 |
| Stripe Fees | $145-170 |
| **Total** | **$720-745/month** |

**Extra Cost:** $530-500/month (265% more expensive)

---

### Option 3: Auth0

| Component | Monthly Cost |
|-----------|-------------|
| Auth0 Essentials | $35-240 |
| PostgreSQL (Credit System) | $25 |
| Stripe Fees | $145-170 |
| **Total** | **$205-435/month** |

**Extra Cost:** $15-190/month

---

### Option 4: Supabase Auth

| Component | Monthly Cost |
|-----------|-------------|
| Supabase Pro | $25 |
| Stripe Fees | $145-170 |
| **Total** | **$170-195/month** |

**Savings:** $20-50/month BUT with reliability concerns

---

## 🎯 Final Recommendations by Scenario

### Scenario 1: Startup/MVP (Current Mana Status)
**Recommendation:** Better Auth + PostgreSQL + Stripe

**Why:**
- ✅ Zero auth licensing costs
- ✅ Full control and customization
- ✅ Scales to 100k+ users
- ✅ No vendor lock-in
- ✅ Perfect for monorepo

**Risk:** New library (2024), but YC-backed and active

---

### Scenario 2: Well-Funded Startup (>$1M ARR)
**Recommendation:** Better Auth or Clerk

**Why:**
- Better Auth if team wants control
- Clerk if team wants managed solution and has budget
- Both provide excellent developer experience

---

### Scenario 3: Enterprise (Compliance Requirements)
**Recommendation:** Auth0 or Custom (Better Auth)

**Why:**
- Auth0 for compliance certifications
- Better Auth if building custom compliance layer
- Both support SSO, SAML, etc.

---

### Scenario 4: Already Deep in Supabase
**Recommendation:** Auth.js + Supabase

**Why:**
- Leverage existing Supabase infrastructure
- Auth.js provides better control than Supabase Auth
- Monitor for reliability issues

---

## ⚡ Quick Implementation Checklist

### Week 1-2: Core Auth
- [ ] Install Better Auth
- [ ] Configure PostgreSQL with RLS
- [ ] Generate RS256 key pair
- [ ] Implement login/register endpoints
- [ ] Create JWT validation middleware

### Week 3-4: Multi-App
- [ ] Create @manacore/shared-auth package
- [ ] Implement app-token generation
- [ ] Add session management
- [ ] Configure RLS for each app

### Week 5-6: Credits
- [ ] Design ledger schema (double-entry)
- [ ] Implement credit purchase API
- [ ] Add idempotency handling
- [ ] Build credit usage API

### Week 7-8: Payments
- [ ] Set up Stripe account
- [ ] Implement payment intents
- [ ] Build webhook handlers
- [ ] Add credit packages

---

## 🚨 Critical Success Factors

### Must-Haves
1. ✅ Short-lived access tokens (15-30 min)
2. ✅ Refresh token rotation
3. ✅ httpOnly cookies (web) / SecureStore (mobile)
4. ✅ PostgreSQL RLS for multi-tenancy
5. ✅ Idempotency for all financial transactions
6. ✅ Stripe webhook signature verification
7. ✅ Double-entry ledger for credits
8. ✅ Comprehensive testing (especially RLS)

### Nice-to-Haves
- ⭐ 2FA for all users
- ⭐ Device tracking and management
- ⭐ Organization/team support
- ⭐ Multiple credit types (paid, bonus, promo)
- ⭐ Credit expiration handling
- ⭐ Subscription model

---

## 📈 Scalability Projections

| Metric | Current | 1 Year | 3 Years |
|--------|---------|--------|---------|
| **Users** | 100 | 10,000 | 100,000 |
| **Auth Requests/Day** | 1,000 | 100,000 | 1,000,000 |
| **Credit Transactions/Day** | 50 | 5,000 | 50,000 |
| **Monthly Cost** | $50 | $200 | $500 |
| **DB Size** | 100MB | 10GB | 100GB |

**Bottleneck Analysis:**
- 🟢 100-10k users: Single server sufficient
- 🟡 10k-100k users: Need load balancing + connection pooling
- 🔴 100k+ users: Requires distributed architecture

**Recommended Stack Handles:** Up to 100k users with optimization

---

## ✅ Decision Summary

### For Mana Universe Monorepo

**RECOMMENDED ARCHITECTURE:**

```
Better Auth + PostgreSQL + Drizzle + Stripe
```

**Confidence Level:** ⭐⭐⭐⭐⭐ (5/5)

**Key Reasons:**
1. Perfect fit for monorepo architecture
2. Zero licensing costs (100% open-source)
3. Full control and customization
4. Comprehensive features built-in
5. Excellent TypeScript support
6. No vendor lock-in
7. YC-backed with active development
8. Scales to 100k+ users

**Total Implementation Time:** 14 weeks
**Monthly Operating Cost:** $190-245 at 10k users

---

**Next Step:** Run Better Auth proof-of-concept (2-3 days)

---

*End of Decision Matrix*