fastapi-fullauth 0.3.0__tar.gz → 0.4.0__tar.gz

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.0
+
+### Added
+
+- **OAuth2 social login** — Google and GitHub out of the box, extensible for custom providers
+  - `GET /oauth/{provider}/authorize` — get authorization URL
+  - `POST /oauth/{provider}/callback` — exchange code for JWT tokens
+  - `GET /oauth/providers` — list configured providers
+  - `GET /oauth/accounts` — list linked OAuth accounts
+  - `DELETE /oauth/accounts/{provider}` — unlink a provider (with lockout prevention)
+- `OAuthProvider` abstract base class for implementing custom providers
+- `OAuthAccount` and `OAuthUserInfo` types
+- `OAuthAccountRecord` / `OAuthAccountModel` for SQLModel and SQLAlchemy adapters
+- OAuth adapter methods on all adapters (memory, SQLModel, SQLAlchemy)
+- `OAUTH_PROVIDERS`, `OAUTH_STATE_EXPIRE_SECONDS`, `OAUTH_AUTO_LINK_BY_EMAIL` config fields
+- `after_oauth_login` hook event
+- `oauth` optional dependency group (`pip install fastapi-fullauth[oauth]`)
+- Auto-link OAuth to existing user by email (configurable)
+- Auto-verify email when provider confirms it
+- Lockout prevention — can't unlink last login method
+- Multiple `redirect_uris` per OAuth provider — supports web, mobile, and production frontends from one config. Client passes `?redirect_uri=` on authorize, validated against allowed list.
+
 ## 0.3.0
 
 ### Breaking changes

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fullauth
-Version: 0.3.0
+Version: 0.4.0
 Summary: Production-grade, async-native authentication and authorization library for FastAPI
 Project-URL: Homepage, https://github.com/mdfarhankc/fastapi-fullauth
 Project-URL: Documentation, https://github.com/mdfarhankc/fastapi-fullauth
@@ -28,9 +28,12 @@ Requires-Dist: pyjwt>=2.8
 Requires-Dist: uuid-utils>=0.14.1
 Provides-Extra: all
 Requires-Dist: alembic>=1.13; extra == 'all'
+Requires-Dist: httpx>=0.25; extra == 'all'
 Requires-Dist: redis>=5.0; extra == 'all'
 Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
 Requires-Dist: sqlmodel>=0.0.16; extra == 'all'
+Provides-Extra: oauth
+Requires-Dist: httpx>=0.25; extra == 'oauth'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == 'redis'
 Provides-Extra: sqlalchemy
@@ -59,6 +62,8 @@ pip install fastapi-fullauth[sqlmodel]
 pip install fastapi-fullauth[sqlalchemy]
 # with redis for token blacklisting:
 pip install fastapi-fullauth[sqlmodel,redis]
+# with OAuth2 social login:
+pip install fastapi-fullauth[sqlmodel,oauth]
 ```
 
 ## Quick start
@@ -213,6 +218,45 @@ fullauth = FullAuth(
 
 When switching algorithms, existing users are transparently rehashed on their next login.
 
+## OAuth2 social login
+
+Add Google and/or GitHub login with a few config lines:
+
+```python
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    oauth_providers={
+        "google": {
+            "client_id": "your-google-client-id",
+            "client_secret": "your-google-secret",
+            "redirect_uris": [
+                "http://localhost:3000/auth/callback",
+                "https://myapp.com/auth/callback",
+                "myapp://auth/callback",  # Flutter deep link
+            ],
+        },
+        "github": {
+            "client_id": "your-github-client-id",
+            "client_secret": "your-github-secret",
+            "redirect_uri": "http://localhost:3000/auth/callback",  # single URI also works
+        },
+    },
+)
+```
+
+This registers these routes automatically:
+
+- `GET /auth/oauth/providers` — list configured providers
+- `GET /auth/oauth/{provider}/authorize?redirect_uri=...` — get the authorization URL (optional `redirect_uri` param, validated against allowed list, defaults to first)
+- `POST /auth/oauth/{provider}/callback` — exchange code for JWT tokens
+- `GET /auth/oauth/accounts` — list linked OAuth accounts
+- `DELETE /auth/oauth/accounts/{provider}` — unlink a provider
+
+Users can link multiple providers and keep email/password login alongside OAuth. New users are auto-created on first OAuth login, and existing users are auto-linked by email.
+
+Requires `httpx`: `pip install fastapi-fullauth[oauth]`
+
 ## Route control
 
 ```python

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/README.md

@@ -16,6 +16,8 @@ pip install fastapi-fullauth[sqlmodel]
 pip install fastapi-fullauth[sqlalchemy]
 # with redis for token blacklisting:
 pip install fastapi-fullauth[sqlmodel,redis]
+# with OAuth2 social login:
+pip install fastapi-fullauth[sqlmodel,oauth]
 ```
 
 ## Quick start
@@ -170,6 +172,45 @@ fullauth = FullAuth(
 
 When switching algorithms, existing users are transparently rehashed on their next login.
 
+## OAuth2 social login
+
+Add Google and/or GitHub login with a few config lines:
+
+```python
+fullauth = FullAuth(
+    secret_key="...",
+    adapter=adapter,
+    oauth_providers={
+        "google": {
+            "client_id": "your-google-client-id",
+            "client_secret": "your-google-secret",
+            "redirect_uris": [
+                "http://localhost:3000/auth/callback",
+                "https://myapp.com/auth/callback",
+                "myapp://auth/callback",  # Flutter deep link
+            ],
+        },
+        "github": {
+            "client_id": "your-github-client-id",
+            "client_secret": "your-github-secret",
+            "redirect_uri": "http://localhost:3000/auth/callback",  # single URI also works
+        },
+    },
+)
+```
+
+This registers these routes automatically:
+
+- `GET /auth/oauth/providers` — list configured providers
+- `GET /auth/oauth/{provider}/authorize?redirect_uri=...` — get the authorization URL (optional `redirect_uri` param, validated against allowed list, defaults to first)
+- `POST /auth/oauth/{provider}/callback` — exchange code for JWT tokens
+- `GET /auth/oauth/accounts` — list linked OAuth accounts
+- `DELETE /auth/oauth/accounts/{provider}` — unlink a provider
+
+Users can link multiple providers and keep email/password login alongside OAuth. New users are auto-created on first OAuth login, and existing users are auto-linked by email.
+
+Requires `httpx`: `pip install fastapi-fullauth[oauth]`
+
 ## Route control
 
 ```python

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from fastapi_fullauth.config import FullAuthConfig
 from fastapi_fullauth.fullauth import FullAuth

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/adapters/base.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Any
 
-from fastapi_fullauth.types import CreateUserSchema, RefreshToken, UserSchema
+from fastapi_fullauth.types import CreateUserSchema, OAuthAccount, RefreshToken, UserSchema
 
 
 class AbstractUserAdapter(ABC):
@@ -66,3 +66,22 @@ class AbstractUserAdapter(ABC):
 
     @abstractmethod
     async def remove_role(self, user_id: str, role_name: str) -> None: ...
+
+    # ── OAuth (optional — override when using OAuth) ─────────────────
+
+    async def get_oauth_account(self, provider: str, provider_user_id: str) -> OAuthAccount | None:
+        raise NotImplementedError("Implement OAuth adapter methods to use OAuth")
+
+    async def get_user_oauth_accounts(self, user_id: str) -> list[OAuthAccount]:
+        raise NotImplementedError("Implement OAuth adapter methods to use OAuth")
+
+    async def create_oauth_account(self, data: OAuthAccount) -> OAuthAccount:
+        raise NotImplementedError("Implement OAuth adapter methods to use OAuth")
+
+    async def update_oauth_account(
+        self, provider: str, provider_user_id: str, data: dict[str, Any]
+    ) -> OAuthAccount | None:
+        raise NotImplementedError("Implement OAuth adapter methods to use OAuth")
+
+    async def delete_oauth_account(self, provider: str, provider_user_id: str) -> None:
+        raise NotImplementedError("Implement OAuth adapter methods to use OAuth")

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/adapters/memory.py

@@ -3,7 +3,7 @@ from typing import Any
 from uuid_utils import uuid7
 
 from fastapi_fullauth.adapters.base import AbstractUserAdapter
-from fastapi_fullauth.types import CreateUserSchema, RefreshToken, UserSchema
+from fastapi_fullauth.types import CreateUserSchema, OAuthAccount, RefreshToken, UserSchema
 
 
 class InMemoryAdapter(AbstractUserAdapter):
@@ -13,6 +13,7 @@ class InMemoryAdapter(AbstractUserAdapter):
         self._passwords: dict[str, str] = {}
         self._refresh_tokens: dict[str, RefreshToken] = {}
         self._roles: dict[str, list[str]] = {}
+        self._oauth_accounts: dict[tuple[str, str], OAuthAccount] = {}
 
     async def get_user_by_id(self, user_id: str) -> UserSchema | None:
         data = self._users.get(user_id)
@@ -104,3 +105,29 @@ class InMemoryAdapter(AbstractUserAdapter):
             roles.remove(role_name)
         if user_id in self._users:
             self._users[user_id]["roles"] = roles
+
+    # ── OAuth ────────────────────────────────────────────────────────
+
+    async def get_oauth_account(self, provider: str, provider_user_id: str) -> OAuthAccount | None:
+        return self._oauth_accounts.get((provider, provider_user_id))
+
+    async def get_user_oauth_accounts(self, user_id: str) -> list[OAuthAccount]:
+        return [a for a in self._oauth_accounts.values() if a.user_id == user_id]
+
+    async def create_oauth_account(self, data: OAuthAccount) -> OAuthAccount:
+        self._oauth_accounts[(data.provider, data.provider_user_id)] = data
+        return data
+
+    async def update_oauth_account(
+        self, provider: str, provider_user_id: str, data: dict[str, Any]
+    ) -> OAuthAccount | None:
+        key = (provider, provider_user_id)
+        account = self._oauth_accounts.get(key)
+        if account is None:
+            return None
+        updated = account.model_copy(update=data)
+        self._oauth_accounts[key] = updated
+        return updated
+
+    async def delete_oauth_account(self, provider: str, provider_user_id: str) -> None:
+        self._oauth_accounts.pop((provider, provider_user_id), None)

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/adapters/sqlalchemy/adapter.py

@@ -6,11 +6,12 @@ from sqlalchemy.orm import selectinload
 
 from fastapi_fullauth.adapters.base import AbstractUserAdapter
 from fastapi_fullauth.adapters.sqlalchemy.models import (
+    OAuthAccountModel,
     RefreshTokenModel,
     RoleModel,
     UserBase,
 )
-from fastapi_fullauth.types import CreateUserSchema, RefreshToken, UserSchema
+from fastapi_fullauth.types import CreateUserSchema, OAuthAccount, RefreshToken, UserSchema
 
 # Map SQLAlchemy column types to Python types for schema auto-derivation
 _SA_TYPE_MAP: dict[type, type] = {}
@@ -253,3 +254,77 @@ class SQLAlchemyAdapter(AbstractUserAdapter):
             if user:
                 user.roles = [r for r in user.roles if r.name != role_name]
                 await session.commit()
+
+    # ── OAuth ────────────────────────────────────────────────────────
+
+    def _to_oauth_account(self, row: OAuthAccountModel) -> OAuthAccount:
+        return OAuthAccount(
+            provider=row.provider,
+            provider_user_id=row.provider_user_id,
+            user_id=str(row.user_id),
+            provider_email=row.provider_email,
+            access_token=row.access_token,
+            refresh_token=row.refresh_token,
+            expires_at=row.expires_at,
+        )
+
+    async def get_oauth_account(self, provider: str, provider_user_id: str) -> OAuthAccount | None:
+        async with self._session_maker() as session:
+            result = await session.execute(
+                select(OAuthAccountModel).where(
+                    OAuthAccountModel.provider == provider,
+                    OAuthAccountModel.provider_user_id == provider_user_id,
+                )
+            )
+            row = result.scalars().first()
+            return self._to_oauth_account(row) if row else None
+
+    async def get_user_oauth_accounts(self, user_id: str) -> list[OAuthAccount]:
+        async with self._session_maker() as session:
+            result = await session.execute(
+                select(OAuthAccountModel).where(OAuthAccountModel.user_id == user_id)
+            )
+            return [self._to_oauth_account(row) for row in result.scalars().all()]
+
+    async def create_oauth_account(self, data: OAuthAccount) -> OAuthAccount:
+        async with self._session_maker() as session:
+            record = OAuthAccountModel(
+                provider=data.provider,
+                provider_user_id=data.provider_user_id,
+                user_id=data.user_id,
+                provider_email=data.provider_email,
+                access_token=data.access_token,
+                refresh_token=data.refresh_token,
+                expires_at=data.expires_at,
+            )
+            session.add(record)
+            await session.commit()
+            return data
+
+    async def update_oauth_account(
+        self, provider: str, provider_user_id: str, data: dict[str, Any]
+    ) -> OAuthAccount | None:
+        async with self._session_maker() as session:
+            await session.execute(
+                update(OAuthAccountModel)
+                .where(
+                    OAuthAccountModel.provider == provider,
+                    OAuthAccountModel.provider_user_id == provider_user_id,
+                )
+                .values(**data)
+            )
+            await session.commit()
+            return await self.get_oauth_account(provider, provider_user_id)
+
+    async def delete_oauth_account(self, provider: str, provider_user_id: str) -> None:
+        async with self._session_maker() as session:
+            result = await session.execute(
+                select(OAuthAccountModel).where(
+                    OAuthAccountModel.provider == provider,
+                    OAuthAccountModel.provider_user_id == provider_user_id,
+                )
+            )
+            row = result.scalars().first()
+            if row:
+                await session.delete(row)
+                await session.commit()

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/adapters/sqlalchemy/models.py

@@ -1,7 +1,7 @@
 from datetime import datetime, timezone
 from uuid import UUID
 
-from sqlalchemy import Boolean, DateTime, ForeignKey, Text, Uuid
+from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text, Uuid
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 from uuid_utils import uuid7
 
@@ -52,6 +52,24 @@ class UserRoleModel(FullAuthBase):
     )
 
 
+class OAuthAccountModel(FullAuthBase):
+    __tablename__ = "fullauth_oauth_accounts"
+
+    id: Mapped[UUID] = mapped_column(Uuid, primary_key=True, default=uuid7)
+    provider: Mapped[str] = mapped_column(String(50), index=True, nullable=False)
+    provider_user_id: Mapped[str] = mapped_column(String(320), index=True, nullable=False)
+    user_id: Mapped[UUID] = mapped_column(
+        Uuid, ForeignKey("fullauth_users.id", ondelete="CASCADE"), nullable=False
+    )
+    provider_email: Mapped[str | None] = mapped_column(String(320), nullable=True)
+    access_token: Mapped[str | None] = mapped_column(Text, nullable=True)
+    refresh_token: Mapped[str | None] = mapped_column(Text, nullable=True)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+
 class RefreshTokenModel(FullAuthBase):
     __tablename__ = "fullauth_refresh_tokens"
 

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/adapters/sqlmodel/adapter.py

@@ -5,8 +5,13 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from sqlalchemy.orm import selectinload
 
 from fastapi_fullauth.adapters.base import AbstractUserAdapter
-from fastapi_fullauth.adapters.sqlmodel.models import RefreshTokenRecord, Role, UserBase
-from fastapi_fullauth.types import CreateUserSchema, RefreshToken, UserSchema
+from fastapi_fullauth.adapters.sqlmodel.models import (
+    OAuthAccountRecord,
+    RefreshTokenRecord,
+    Role,
+    UserBase,
+)
+from fastapi_fullauth.types import CreateUserSchema, OAuthAccount, RefreshToken, UserSchema
 
 
 class SQLModelAdapter(AbstractUserAdapter):
@@ -222,3 +227,77 @@ class SQLModelAdapter(AbstractUserAdapter):
                 user.roles = [r for r in user.roles if r.name != role_name]
                 session.add(user)
                 await session.commit()
+
+    # ── OAuth ────────────────────────────────────────────────────────
+
+    def _to_oauth_account(self, row: OAuthAccountRecord) -> OAuthAccount:
+        return OAuthAccount(
+            provider=row.provider,
+            provider_user_id=row.provider_user_id,
+            user_id=str(row.user_id),
+            provider_email=row.provider_email,
+            access_token=row.access_token,
+            refresh_token=row.refresh_token,
+            expires_at=row.expires_at,
+        )
+
+    async def get_oauth_account(self, provider: str, provider_user_id: str) -> OAuthAccount | None:
+        async with self._session_maker() as session:
+            result = await session.execute(
+                select(OAuthAccountRecord).where(
+                    OAuthAccountRecord.provider == provider,
+                    OAuthAccountRecord.provider_user_id == provider_user_id,
+                )
+            )
+            row = result.scalars().first()
+            return self._to_oauth_account(row) if row else None
+
+    async def get_user_oauth_accounts(self, user_id: str) -> list[OAuthAccount]:
+        async with self._session_maker() as session:
+            result = await session.execute(
+                select(OAuthAccountRecord).where(OAuthAccountRecord.user_id == user_id)
+            )
+            return [self._to_oauth_account(row) for row in result.scalars().all()]
+
+    async def create_oauth_account(self, data: OAuthAccount) -> OAuthAccount:
+        async with self._session_maker() as session:
+            record = OAuthAccountRecord(
+                provider=data.provider,
+                provider_user_id=data.provider_user_id,
+                user_id=data.user_id,
+                provider_email=data.provider_email,
+                access_token=data.access_token,
+                refresh_token=data.refresh_token,
+                expires_at=data.expires_at,
+            )
+            session.add(record)
+            await session.commit()
+            return data
+
+    async def update_oauth_account(
+        self, provider: str, provider_user_id: str, data: dict[str, Any]
+    ) -> OAuthAccount | None:
+        async with self._session_maker() as session:
+            await session.execute(
+                update(OAuthAccountRecord)
+                .where(
+                    OAuthAccountRecord.provider == provider,
+                    OAuthAccountRecord.provider_user_id == provider_user_id,
+                )
+                .values(**data)
+            )
+            await session.commit()
+            return await self.get_oauth_account(provider, provider_user_id)
+
+    async def delete_oauth_account(self, provider: str, provider_user_id: str) -> None:
+        async with self._session_maker() as session:
+            result = await session.execute(
+                select(OAuthAccountRecord).where(
+                    OAuthAccountRecord.provider == provider,
+                    OAuthAccountRecord.provider_user_id == provider_user_id,
+                )
+            )
+            row = result.scalars().first()
+            if row:
+                await session.delete(row)
+                await session.commit()

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/adapters/sqlmodel/models.py

@@ -43,6 +43,25 @@ class UserBase(SQLModel):
     )
 
 
+class OAuthAccountRecord(SQLModel, table=True):
+    __tablename__ = "fullauth_oauth_accounts"
+
+    id: UUID = Field(default_factory=uuid7, primary_key=True)
+    provider: str = Field(index=True, max_length=50)
+    provider_user_id: str = Field(index=True, max_length=320)
+    user_id: UUID = Field(foreign_key="fullauth_users.id")
+    provider_email: str | None = Field(default=None, max_length=320)
+    access_token: str | None = Field(default=None)
+    refresh_token: str | None = Field(default=None)
+    expires_at: datetime | None = Field(
+        default=None, sa_column=Column(DateTime(timezone=True), nullable=True)
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+
 class RefreshTokenRecord(SQLModel, table=True):
     __tablename__ = "fullauth_refresh_tokens"
 

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/config.py

@@ -1,5 +1,5 @@
 import warnings
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -48,6 +48,10 @@ class FullAuthConfig(BaseSettings):
     COOKIE_SAMESITE: Literal["lax", "strict", "none"] = "lax"
     COOKIE_DOMAIN: str | None = None
 
+    OAUTH_PROVIDERS: dict[str, dict[str, Any]] = {}
+    OAUTH_STATE_EXPIRE_SECONDS: int = 300
+    OAUTH_AUTO_LINK_BY_EMAIL: bool = True
+
     API_PREFIX: str = "/api/v1"
     AUTH_ROUTER_PREFIX: str = "/auth"
     ROUTER_TAGS: list[str] = ["Auth"]

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/dependencies/__init__.py

@@ -1,14 +1,13 @@
 from fastapi_fullauth.dependencies.current_user import (
+    CurrentUser,
+    SuperUser,
+    VerifiedUser,
     current_active_verified_user,
     current_superuser,
     current_user,
-    CurrentUser,
-    VerifiedUser,
-    SuperUser,
 )
 from fastapi_fullauth.dependencies.require_role import require_permission, require_role
 
-
 __all__ = [
     "CurrentUser",
     "VerifiedUser",

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/dependencies/current_user.py

@@ -6,7 +6,6 @@ from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from fastapi_fullauth.exceptions import CREDENTIALS_EXCEPTION
 from fastapi_fullauth.types import UserSchema
 
-
 if TYPE_CHECKING:
     from fastapi_fullauth.fullauth import FullAuth
 

{fastapi_fullauth-0.3.0 → fastapi_fullauth-0.4.0}/fastapi_fullauth/exceptions.py

@@ -45,6 +45,18 @@ class RefreshTokenReuseError(TokenError):
     pass
 
 
+class OAuthError(FullAuthError):
+    pass
+
+
+class OAuthProviderError(OAuthError):
+    pass
+
+
+class OAuthAccountAlreadyLinkedError(OAuthError):
+    pass
+
+
 CREDENTIALS_EXCEPTION = HTTPException(
     status_code=status.HTTP_401_UNAUTHORIZED,
     detail="Could not validate credentials",
@@ -65,3 +77,8 @@ ACCOUNT_LOCKED_EXCEPTION = HTTPException(
     status_code=status.HTTP_423_LOCKED,
     detail="Account is temporarily locked due to too many failed login attempts",
 )
+
+OAUTH_ERROR_EXCEPTION = HTTPException(
+    status_code=status.HTTP_400_BAD_REQUEST,
+    detail="OAuth authentication failed",
+)