# Philosophy
## Why Cryden Exists
Authentication is not business logic, yet every project rewrites it. Developers face three painful choices:
1. **Rewrite auth logic** for every project — risky, inconsistent, time-consuming
2. **Use hosted auth services** — vendor lock-in, users aren't yours, requires internet
3. **Use framework-specific tools** — tied to Express, Django, Next.js — not reusable
Cryden exists to give developers a **standard, reusable auth engine they control**.
## Anti Lock-In Stance
> Your users belong to your application, not your auth provider.
- User tables live in **your database**
- Sessions live in **your database**
- Auth logic runs in **your application**
- Migrate anytime — no proprietary formats
## Offline-First Mindset
> If auth can't work offline, it's not developer-friendly.
- SQLite by default — zero setup
- Same code in development and production
- Test locally without internet
- Works in unstable network conditions
## Explicit Over Magic
- No hidden middleware
- No implicit database schemas
- No "auto-configuration" that breaks
- Every interface is explicit and swappable
## Core vs Platform
CrydenSync is a **library**, not a platform:
| CrydenSync Core (v1.0.0) | CrydenSync Platform (Future) |
|----------------------|--------------------------|
| Go library | Optional cloud sync |
| Your database | Managed service |
| Your infrastructure | Hosted option |
| Offline-first | Cloud when you're ready |
Think **Git** (offline) + **GitHub** (cloud) — but for authentication.
[Read Architecture →](architecture.md)
```markdown
## Core Principles
### 🏝️ Offline First
Auth should work without internet during development. Period.
*Why?* Because genius strikes in airplanes, cafes with spotty WiFi, and villages with 2G networks.
### 👑 You Own Your Users
Your users belong to **you**, not us. We don't want them. We have enough friends. 😉
### 🔓 No Forced Vendor Lock-In
Vendor lock-in is like a toxic relationship — hard to get out of and expensive. We're just here for the good times.
### 🧩 One Engine, Many Faces
Same auth logic everywhere — CLI, SDK, HTTP, cloud. Like a shapeshifter, but for authentication.
### 🌍 African-First, Global-Ready
Built for real-world constraints (unstable internet, affordable infra), but works everywhere. Think of it as "offline-first with global ambition."
## 🛠️ DIY Auth is Like...
Making your own bread. Sure, you *can* do it. But do you *really* want to?
**DIY auth is common and often insecure.** CrydenSync is the safe alternative — like buying bread from a bakery that's been doing it for years.
## 👥 Who CrydenSync is For
### 🚀 Indie & Startup Developers
- Want speed? We've got it.
- Hate repeated setup? Same.
- Don't want to commit to SaaS early? We don't either.
### 🌍 African Developers
- Deal with unstable internet? Offline-first.
- Prefer local-first tools? SQLite is your BFF.
- Want affordable infrastructure? Self-hosted, baby.
### 🏗️ Backend Engineers
- Care about architecture? Interfaces everywhere.
- Want DB flexibility? SQLite, PostgreSQL, MongoDB — take your pick.
- Want clean abstractions? We speak your language.
## 🧠 Why Framework-Agnostic?
### The Framework Problem
Frameworks are like fashion trends:
- They come and go (remember when everyone used Ruby on Rails for everything?)
- They change APIs (breaking changes = breaking weekends)
- They lock design decisions (your auth logic becomes their hostage)
**Auth logic should outlive frameworks.** It's the cockroach of your codebase — it should survive anything.
### What Others Do
- Express middleware
- Next.js plugins
- Django apps
- Laravel packages
**Result:** Your auth is tied to your routing layer like a bad tattoo — painful to remove and expensive to change.
### The CrydenSync Way
> Auth should not know about HTTP, Fiber, Gin, Express, Laravel, FastAPI or Next.js. It doesn't care if you're serving a website or controlling a toaster.
**So:**
- ❌ No request objects
- ❌ No response writers
- ❌ No cookies
- ❌ No headers
**Just:**
- ✅ Inputs
- ✅ Outputs
- ✅ Pure logic
**This is why:**
- HTTP is just a wrapper
- CLI is just a wrapper
- SDKs are just wrappers
- Even your grandma could wrap it (if she coded)
**The engine stays clean.** Like a Zen master in a world of chaos.
## 🌍 Why Offline-First?
### The Hidden Cost of Cloud-First Auth
Most auth tools assume you live in a tech utopia:
- 🌐 Infinite internet
- ☁️ Always-available cloud services
- 💰 Unlimited budget
**Reality:**
- ✈️ You code on planes
- 🏠 You work from home with spotty WiFi
- 🚀 You prototype in coffee shops
- 🌍 You develop in places where "the cloud" is just a fluffy thing in the sky
### What Others Do
"Please create an account to test auth locally."
"Please enter your API key."
"Please connect to the internet."
**Bro, I'm in a tunnel.**
### The CrydenSync Philosophy
> If auth can’t work offline, it’s not developer-friendly. It's just developer-ish.
**So we designed:**
- 📁 SQLite as default (it's just a file, bro)
- 🐘 Local Postgres optional (if you're fancy)
- 🔄 Same logic in production (no surprises)
**Offline does NOT mean insecure.** It means self-contained. Like a hermit crab, but for auth.
## 👑 Why You Own Your Users
### The Hidden Risk
When you use hosted auth:
- The provider owns your user identity
- You depend on their uptime
- Migration is like moving a cemetery — nobody helps you
- Pricing can change overnight (surprise! 🎉)
### What Others Do
- Centralize identity (give us your users)
- Lock user data (they're ours now)
- Abstract storage away (where did they go?)
**This is convenient, like a toxic relationship — feels good until it doesn't.**
### The CrydenSync Philosophy
> Your users belong to your application, not your auth provider. We're not a cult, we're just a tool.
**So:**
- 📊 User tables live in YOUR DB
- 🪪 Sessions live in YOUR DB
- ⚙️ Auth logic runs in YOUR app
**CrydenSync never owns user data.** We don't even know their names. We're like that friend who helps you move but doesn't ask what's in the boxes.
## 🔑 Why JWT + Opaque Tokens (Together)
*This is where the magic happens.*
### ❌ The JWT-Only Mistake
JWTs are great, like pizza:
- 🏃 Stateless (fast)
- 🚀 Fast (did we mention fast?)
- 📦 Self-contained (everything in one box)
**But they cannot:**
- 🔫 Revoke immediately (once it's out, it's out)
- 🚪 Logout all devices (they're all still valid)
- 🔐 Invalidate on password change (old passwords still work)
**This leads to:**
- 🎭 Fake logout (they're still logged in, you just don't know it)
- 🕵️ Long-lived stolen tokens (happy hunting, hacker!)
- 🕳️ Security holes (big enough to drive a truck through)
### ❌ The Opaque-Only Mistake
Opaque tokens are like a security guard:
- 🔍 Require DB lookup (slow)
- 🐢 Slower (did we mention slow?)
- 📈 Harder to scale alone (one guard for everyone)
### ✅ The CrydenSync Solution: Hybrid Model
> JWT for identity, opaque tokens for control. Like a good cop/bad cop setup.
**JWT (Access Token):**
- ⏱️ Short-lived (like a mayfly)
- 🆔 Proves who the user is (identity card)
- 🔑 Used for authorization (let them in)
**Opaque Token (Refresh Token):**
- 💾 Stored in DB (we know where it lives)
- 🪪 Represents the session (this is THE session)
- 🔫 Can be revoked (say goodbye)
- 🚪 Supports logout & logout-all (get out, ALL of you)
### 🔑 Core Rule
> JWT is NOT the session. The session is the opaque token. JWT is just wearing the session's hat.
*This mirrors how serious systems work. We're serious. Sometimes.*
## 🪪 Why Sessions Matter
### Why Sessions at All?
Because users expect:
- 🚪 Logout (I'm leaving)
- 🚪🚪 Logout all devices (I'm leaving EVERYWHERE)
- 🔐 Password change invalidates sessions (new password, who dis?)
- 🛡️ Security controls (I want to see where I'm logged in)
**Sessions make auth controllable.** Without them, it's chaos — like herding cats.
### What CrydenSync Does
- 🎟️ Each login creates a session (your ticket)
- 📦 Session stored in DB (we know where you are)
- 🪪 Session issues tokens (here's your badge)
- 🔫 Session can be revoked (you're fired)
**Auth becomes stateful where it matters, stateless where it helps.** Like a wise old sage.
## 🔓 Why Open Source
### Why Not Keep It Closed?
Auth is:
- 🔐 Security-sensitive (one bug = all your users)
- 🤝 Trust-based (you're trusting us with your users)
- 🏗️ Infrastructure-level (it's the foundation)
**Closed auth engines:**
- 🐛 Hide bugs (we can't see them)
- 🤔 Hide assumptions (we don't know what we don't know)
- 📉 Reduce trust (why should I trust you?)
### The CrydenSync Philosophy
> Security grows with transparency. Like plants, but with code.
**Open source means:**
- 👀 Devs can audit logic (find the bugs)
- 🐛 Bugs get found faster (more eyes = fewer bugs)
- 📈 Trust increases (you can see we're not stealing your data)
- 🚀 Adoption increases (people love free stuff)
*Plus, I (Raymond) like building in public. It's like reality TV, but for code.*
## 🤔 Why This is Different from Others
**CrydenSync is NOT:**
- ❌ An auth framework (too cool for school)
- ❌ A hosted service (we don't want your data)
- ❌ A UI product (we can't design to save our lives)
- ❌ A SaaS-first tool (we believe in options)
**CrydenSync IS:**
> An embeddable authentication engine. Reusable, embedded, offline-capable auth logic for developers who want control.
**Think of it as:**
- 🧱 **Infrastructure**, not application
- 🔧 **Tool**, not service
- 📚 **Library**, not framework
- 🌍 **Language-agnostic**, not Go-only
- 🏗️ **Framework-agnostic**, not tied to anything
- 👤 **Developer-agnostic** — we don't care who you are, where you're from, or what you code in. You could be coding on a potato in Timbuktu — it'll work.
*CrydenSync doesn't care about your:*
- *Gender* 🤷
- *Location* 🌍
- *Framework of the month* 🎭
- *Language preferences* 🗣️
- *DevOps maturity* 🏗️
- *Bank account balance* 💰
*It's the Switzerland of auth libraries — neutral, independent, and always there when you need it.*
## 🎯 The Bottom Line
**CrydenSync is auth for the rest of us.** The ones who:
- ✈️ Code on planes
- 🏠 Work from home with spotty WiFi
- 🌍 Build for emerging markets
- 🚀 Want to move fast without breaking things
- 🔐 Care about security but hate complexity
**Built with ❤️ in Nigeria, for the world. Now go build something awesome.**
---
*P.S. — If you read this far, you're awesome. Here's a virtual high-five 🖐️