trachea-login 0.1.0__tar.gz

trachea_login-0.1.0/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(venv/bin/python -c \"import sys; print\\(sys.version\\)\")",
+      "Bash(venv/bin/pytest --collect-only)",
+      "Bash(python -m pytest tests/test_exceptions.py -v)",
+      "Bash(python3 -m pytest tests/test_exceptions.py -v)",
+      "Bash(pip3 show:*)",
+      "Bash(venv/bin/pytest tests/test_exceptions.py -v)",
+      "Bash(python -m pytest tests/test_config.py -v)",
+      "Bash(pytest tests/test_config.py -v)",
+      "Bash(python3 -m pytest tests/test_config.py -v)",
+      "Bash(.venv/bin/pytest tests/test_config.py -v)",
+      "Bash(venv/bin/pytest tests/test_config.py -v)",
+      "Bash(ls \"/Volumes/SSD-Yogesh 1/Study-Material-Mac/Trachea-Inc/trachea-login/\"*.json)",
+      "Bash(python3:*)",
+      "Bash(curl -s https://pypi.org/pypi/trachea-login/json)",
+      "Bash(python -m build)"
+    ]
+  }
+}

trachea_login-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# Required
+TRACHEA_APP_ID=app1
+TRACHEA_APP_SECRET=your-app-secret-key
+TRACHEA_MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/trachea
+TRACHEA_FIREBASE_CREDENTIALS=path/to/firebase-service-account.json
+TRACHEA_JWT_SECRET=your-super-secret-jwt-key-min-32-chars
+
+# Optional (defaults shown)
+TRACHEA_ACCESS_TOKEN_EXPIRE_MINUTES=15
+TRACHEA_REFRESH_TOKEN_EXPIRE_DAYS=30
+TRACHEA_PASSWORD_MIN_LENGTH=8
+TRACHEA_DB_NAME=trachea

trachea_login-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest tests/ -v --cov=trachea_login --cov-report=term-missing --cov-fail-under=80

trachea_login-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+# .github/workflows/publish.yml
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Run tests
+        run: |
+          pip install -e ".[dev]"
+          pytest tests/ -v --cov=trachea_login --cov-fail-under=80
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

trachea_login-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+*.egg-info/
+.pytest_cache/
+.coverage
+dist/
+build/
+venv/
+.venv/
+.env
+
+# macOS
+.DS_Store
+**/.DS_Store

trachea_login-0.1.0/Discussion.md

@@ -0,0 +1,383 @@
+# trachea-login — Design Discussion Log
+
+> **Session Date:** 2026-04-01
+> **Participants:** Architect (Claude), Product Owner
+> **Purpose:** Design and architecture decisions for the `trachea-login` Python package
+
+---
+
+## Session Summary
+
+This session covers all architectural discussions, questions, decisions, and rationale for the `trachea-login` package design. Use this as a reference for onboarding, future decisions, and Confluence knowledge base.
+
+---
+
+## Q1 — Package Type: Embedded Library vs Microservice
+
+**Question asked:**
+> Should `trachea-login` be an embedded library, a standalone auth microservice, or both?
+
+**Options presented:**
+
+| Option | Description |
+|---|---|
+| A) Embedded library | Installed via pip into each app; each app runs its own auth endpoints |
+| B) Standalone microservice | One central server deployed independently; apps call it over HTTP |
+| C) Both | Library that can be embedded OR deployed as a standalone service |
+
+**Decision:** Option A — Embedded library
+
+**Refinement:** Designed as a **mountable FastAPI router** (not plain library):
+- `pip install trachea-login` → mount router in 2 lines
+- All apps share same MongoDB cluster
+- Can be wrapped as standalone service later if needed (YAGNI)
+
+**Rationale:** Best of both worlds. Simple integration, shared DB, extensible to microservice later.
+
+---
+
+## Q2 — Web Framework
+
+**Question asked:**
+> What Python web frameworks do your apps use?
+
+**Options presented:**
+
+| Option | Framework |
+|---|---|
+| A | FastAPI (all or most) |
+| B | Flask (all or most) |
+| C | Django (all or most) |
+| D | Mixed |
+| E | Not sure / framework-agnostic |
+
+**Decision:** FastAPI
+
+---
+
+## Q2b — Firebase Integration
+
+**Topic raised by product owner:**
+> Can we use Firebase Authentication somehow?
+
+**Architect recommendation:**
+Use Firebase as the **identity provider** for social logins and email/password. After Firebase verifies identity:
+- `trachea-login` receives Firebase ID token from client
+- Verifies token server-side using Firebase Admin SDK
+- Creates/updates MongoDB user record with `AppId`
+- Issues its own app JWT (access + refresh tokens)
+
+**Benefits:**
+- Firebase handles OAuth complexity (Google, Facebook, Apple, email/password)
+- Mobile clients use native Firebase SDK — zero custom OAuth code
+- trachea-login owns user data and tokens — decoupled from Firebase after login
+- If Firebase is replaced later, only the login step changes
+
+**Flow:**
+```
+Firebase handles identity → trachea-login handles user data + app context → MongoDB stores everything
+```
+
+---
+
+## Q3 — Token Strategy
+
+**Question asked:**
+> After Firebase verifies the user, what token should subsequent API calls use?
+
+**Options presented:**
+
+| Option | Description |
+|---|---|
+| A | Firebase ID tokens only — always pass Firebase token |
+| B | trachea-login issues its own JWT (access + refresh) after Firebase verification |
+| C | Same as B + supports email/password natively without Firebase |
+
+**Decision:** Option B
+
+**Rationale:**
+- Apps are decoupled from Firebase after initial login
+- Full control over token expiry, payload, and revocation
+- If Firebase is swapped out, only the login step changes
+
+**Follow-up question from product owner:**
+> If we take B, will users be able to login/register via email/password?
+
+**Answer:** Yes — via **Firebase email/password auth** (B1):
+- Client authenticates with Firebase using email+password → gets Firebase ID Token
+- Same flow as social login from trachea-login's perspective
+- Firebase handles password reset emails and email verification automatically
+- Consistent single flow for all auth methods
+
+---
+
+## Q4 — Role-Based Access Control (RBAC)
+
+**Question asked:**
+> Do your apps need role-based access control?
+
+**Options presented:**
+
+| Option | Description |
+|---|---|
+| A | No roles — authentication only |
+| B | Simple roles — admin, user, guest per app |
+| C | Fine-grained permissions — per action per app per user |
+| D | Not sure — keep extensible |
+
+**Follow-up question from product owner:**
+> If I choose No roles, can I still do free user or paid users?
+
+**Architect clarification:**
+- Free vs Paid is a **subscription plan/tier**, not a role
+- Roles = what actions a user can perform
+- Plan = what features they have access to based on payment
+- Both needed to cover real-world requirements
+
+**Decision:** Simple roles (Option B) with two fields:
+
+| Field | Values |
+|---|---|
+| `role` | `admin`, `member`, `guest` |
+| `plan` | `free`, `pro`, `enterprise` |
+
+Both stored in MongoDB per user per app. Both included in JWT payload — no MongoDB hit on every request.
+
+---
+
+## Q5 — User Data Fields
+
+**Question asked:**
+> What profile information should trachea-login store in MongoDB?
+
+**Options presented:**
+
+| Option | Fields |
+|---|---|
+| A | Minimal: email, name, avatar, provider |
+| B | Standard: A + phone, date_of_birth, address |
+| C | Custom fields: apps define extra fields |
+| D | A + C: minimal core + custom metadata |
+
+**Decision:** Option B — Standard fields
+
+**Fields included:**
+- `email`, `name`, `avatar`, `provider`
+- `phone`, `date_of_birth`
+- `address` (street, city, state, country, zip)
+
+---
+
+## Q6 — App Registration (AppId Management)
+
+**Question asked:**
+> How should apps identify themselves to trachea-login?
+
+**Options presented:**
+
+| Option | Description |
+|---|---|
+| A | Config at initialization — pass app_id + secret in code/env vars |
+| B | Apps registered in MongoDB — `apps` collection with app_id, secret, name, domains |
+| C | Both — env vars + MongoDB validation at startup |
+
+**Follow-up question from product owner:**
+> Which option is easier to maintain from B and C?
+
+**Architect recommendation:** **Option B** (with env vars pattern)
+
+**Rationale:**
+- Option C has a maintenance trap: two sources of truth (env vars + MongoDB) can drift
+- Option B = single source of truth (MongoDB)
+- Secrets still stay out of code: read from env vars, passed to trachea-login, validated against MongoDB
+- Central registry — disable/update App1 from MongoDB without touching App1's code
+
+**Pattern:**
+```bash
+# App1/.env
+APP_ID=app1
+APP_SECRET=your-secret-key
+```
+App reads from env vars → passes to TracheaLogin() → validated against MongoDB at startup.
+
+---
+
+## Q7 — Cross-App User Identity
+
+**Question asked:**
+> What should happen when a user who exists in App1 logs into App2 for the first time?
+
+**Options presented:**
+
+| Option | Description |
+|---|---|
+| A | Separate user records — App1 and App2 users fully isolated |
+| B | Linked user — one user document, array of apps they belong to |
+| C | Architect's call |
+
+**Follow-up question from product owner:**
+> Which one is easier to maintain in the long run?
+
+**Decision:** Option B — Linked user
+
+**Rationale:**
+
+| Concern | Option A | Option B |
+|---|---|---|
+| Profile update | Must update in every app | One write, all apps see it |
+| Account deletion | Orphaned records across apps | One document deleted |
+| Same email in 2 apps | Don't know it's same person | Naturally linked via firebase_uid |
+| Cross-app analytics | Very difficult | Simple query |
+| Firebase UID mapping | One UID → multiple documents (unnatural) | One UID → one document (natural) |
+
+**User document structure:**
+```json
+{
+  "firebase_uid": "abc123",
+  "email": "user@example.com",
+  "apps": [
+    { "app_id": "app1", "role": "admin", "plan": "pro" },
+    { "app_id": "app2", "role": "member", "plan": "free" }
+  ]
+}
+```
+
+---
+
+## Q8 — Username-Only Registration
+
+**Question raised by product owner:**
+> If some user wants to register without email/password or social login, but with username and password only — is it possible?
+
+**Architect answer:** Yes — as a **native auth path** in trachea-login.
+
+**Why Firebase can't handle this:**
+Firebase requires an email address for all auth methods. Username-only login must be handled natively.
+
+**Additional context provided by product owner:**
+- Username/password is for **free users only**
+- No forget password needed (no email = no reset email)
+- Once user moves to paid plan, email becomes required
+- Apps should control which auth methods they allow
+
+**Impact on data model:**
+
+| Field | Change |
+|---|---|
+| `email` | Optional for free/username users; required when upgrading to paid |
+| `username` | New field — unique, optional, only for username auth |
+| `password_hash` | New field — bcrypt hashed, only for username auth |
+| `provider` | New value: `"username"` |
+| `firebase_uid` | `null` for username users |
+
+**App-level auth method control:**
+```json
+"allowed_auth_methods": ["google", "facebook", "apple", "password", "username"]
+```
+Each app decides which methods it enables.
+
+---
+
+## Architecture Approach Selection
+
+**Three approaches were evaluated:**
+
+### Approach 1 — Thin Wrapper (Firebase-heavy)
+- trachea-login is a minimal router
+- All auth logic lives in Firebase
+- **Rejected:** Apps permanently coupled to Firebase, limited customization
+
+### Approach 2 — Layered Auth Package (selected)
+- Firebase handles identity verification only
+- trachea-login owns tokens, user data, roles, plans
+- Firebase is swappable after the login step
+- **Selected:** Clean separation, full control, extensible
+
+### Approach 3 — Auth Microservice Kit
+- Package + CLI to run as standalone service
+- **Rejected for now:** YAGNI — can add CLI later if needed
+
+---
+
+## Final Design Summary
+
+| Decision | Choice |
+|---|---|
+| Package type | Pip-installable, mountable FastAPI router |
+| Identity provider | Firebase (social + email/password) |
+| Native auth | Username + password (free users only, no Firebase) |
+| Token strategy | App-owned JWT — access (15min) + refresh (30d, rotated) |
+| Refresh tokens | Stored hashed in MongoDB, TTL auto-expiry, rotation on use |
+| Database | MongoDB (Motor async), shared across all apps |
+| Multi-app user model | Single user document, `apps[]` array per user |
+| Roles | `role` (admin/member/guest) + `plan` (free/pro/enterprise) |
+| App registration | MongoDB `apps` collection, validated at startup |
+| Auth methods | Controlled per app via `allowed_auth_methods` |
+| Email requirement | Optional for free/username; required for paid plan |
+| PyPI | Published as `trachea-login`, auto-publish via GitHub Actions on tag |
+| Python version | >= 3.10 |
+| Key dependencies | FastAPI, Motor, Firebase Admin SDK, python-jose, passlib, pydantic-settings |
+
+---
+
+## Auth Method Rules (Quick Reference)
+
+| Auth Method | Email Required | Firebase Used | Plan Allowed | Password Storage |
+|---|---|---|---|---|
+| `google` | Auto-filled | Yes | All | Firebase |
+| `facebook` | Auto-filled | Yes | All | Firebase |
+| `apple` | Auto-filled | Yes | All | Firebase |
+| `password` | Yes | Yes | All | Firebase |
+| `username` | No | No | `free` only | bcrypt in MongoDB |
+
+---
+
+## Error Codes (Quick Reference)
+
+| Error Code | HTTP | When |
+|---|---|---|
+| `APP_NOT_FOUND` | 404 | app_id not registered |
+| `APP_INACTIVE` | 403 | app is disabled |
+| `AUTH_METHOD_NOT_ALLOWED` | 403 | app doesn't allow this method |
+| `INVALID_FIREBASE_TOKEN` | 401 | Firebase verification failed |
+| `INVALID_CREDENTIALS` | 401 | Wrong username or password |
+| `USERNAME_TAKEN` | 409 | Username already exists |
+| `EMAIL_TAKEN` | 409 | Email already registered |
+| `INVALID_TOKEN` | 401 | JWT invalid or malformed |
+| `TOKEN_EXPIRED` | 401 | JWT expired |
+| `REFRESH_TOKEN_INVALID` | 401 | Refresh token not found or revoked |
+| `REFRESH_TOKEN_REUSE` | 401 | Reuse attack — all tokens revoked |
+| `INSUFFICIENT_ROLE` | 403 | Role too low |
+| `INSUFFICIENT_PLAN` | 403 | Plan too low |
+| `EMAIL_REQUIRED_FOR_PAID` | 422 | No email when upgrading plan |
+| `USER_INACTIVE` | 403 | Account deactivated |
+| `VALIDATION_ERROR` | 422 | Request body invalid |
+
+---
+
+## API Routes (Quick Reference)
+
+| Method | Endpoint | Auth | Description |
+|---|---|---|---|
+| `POST` | `/auth/login` | No | Firebase token OR username/password |
+| `POST` | `/auth/register` | No | Username/password only |
+| `POST` | `/auth/refresh` | No | Rotate refresh token |
+| `POST` | `/auth/logout` | Yes | Revoke all refresh tokens |
+| `GET` | `/users/me` | Yes | Get current user profile |
+| `PATCH` | `/users/me` | Yes | Update profile |
+| `DELETE` | `/users/me` | Yes | Deactivate account |
+| `PATCH` | `/users/me/plan` | Yes | Upgrade plan |
+
+---
+
+## MongoDB Collections (Quick Reference)
+
+| Collection | Purpose | Key Indexes |
+|---|---|---|
+| `users` | All user data across all apps | firebase_uid (sparse unique), email (sparse unique), username (sparse unique), apps.app_id |
+| `apps` | Registered apps | app_id (unique) |
+| `refresh_tokens` | Active refresh tokens | token_hash, expires_at (TTL) |
+
+---
+
+*End of discussion log. For full technical spec see `trachea-login.md` in project root.*