py-auth-sqlalchemy 0.0.1__tar.gz

py_auth_sqlalchemy-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Olatunji Jamaldeen]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_auth_sqlalchemy-0.0.1/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: py-auth-sqlalchemy
+Version: 0.0.1
+Summary: High-performance, async SQLAlchemy adapter for py-auth-core.
+Author-email: Olatunji Jamaldeen Omotoyosi <jamaldeen.o@yahoo.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jamaldeen09/py-auth
+Project-URL: Repository, https://github.com/jamaldeen09/py-auth
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: greenlet>=3.0.0
+Requires-Dist: py-auth-core>=0.0.1
+Dynamic: license-file
+
+# py-auth-sqlalchemy
+
+**High-performance, async SQLAlchemy 2.0 adapter for [py-auth-core](https://pypi.org/project/py-auth-core/).**
+
+Plug this adapter into `PyAuth` to get automatic, async session persistence across PostgreSQL, MySQL, and SQLite — with built-in error translation from SQLAlchemy exceptions into `py-auth-core` exceptions.
+
+[![PyPI version](https://img.shields.io/pypi/v/py-auth-sqlalchemy.svg)](https://pypi.org/project/py-auth-sqlalchemy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/py-auth-sqlalchemy.svg)](https://pypi.org/project/py-auth-sqlalchemy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Supported Databases](#supported-databases)
+- [Quick Start](#quick-start)
+- [Session Model Requirements](#session-model-requirements)
+- [API Reference](#api-reference)
+  - [SqlAlchemyAdapter](#sqlalchemyadapter)
+  - [Error Translation](#error-translation)
+- [Full FastAPI Example](#full-fastapi-example)
+- [Security Notes](#security-notes)
+- [License](#license)
+
+---
+
+## Features
+
+- ✅ **Async-native** — built entirely on SQLAlchemy `AsyncEngine` + `AsyncSession`
+- ✅ **BYO model** — bring your own declarative SQLAlchemy model; extra columns are fine
+- ✅ **Strict validation at startup** — engine type and required model columns are checked immediately, before any request is served
+- ✅ **Automatic error translation** — `IntegrityError` → `DuplicateEntryError` / `ForeignKeyViolationError`, `NoResultFound` → `RecordNotFoundError`
+- ✅ **Session-only** — user lookup and creation live in your `authorize()` callback, giving you full control
+
+---
+
+## Installation
+
+```bash
+pip install py-auth-sqlalchemy
+```
+
+Then install the async driver for your database:
+
+```bash
+# PostgreSQL
+pip install asyncpg
+
+# MySQL / MariaDB
+pip install aiomysql
+
+# SQLite
+pip install aiosqlite
+```
+
+**Requirements:** Python ≥ 3.9, SQLAlchemy ≥ 2.0, py-auth-core ≥ 0.0.1.
+
+---
+
+## Supported Databases
+
+| Database | Async driver | Connection URL prefix |
+|---|---|---|
+| PostgreSQL | `asyncpg` | `postgresql+asyncpg://` |
+| MySQL / MariaDB | `aiomysql` | `mysql+aiomysql://` |
+| SQLite | `aiosqlite` | `sqlite+aiosqlite:///` |
+
+The adapter validates the driver at startup and raises `AdapterError` for unsupported drivers.
+
+---
+
+## Quick Start
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import DateTime, String
+import uuid, datetime
+
+from py_auth_sqlalchemy import SqlAlchemyAdapter
+from py_auth import PyAuth, CredentialsProvider
+
+# 1. Define your SQLAlchemy session model
+class Base(DeclarativeBase):
+    pass
+
+class Session(Base):
+    __tablename__ = "sessions"
+
+    # Required columns — do NOT rename these
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_token_hash: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    user_id: Mapped[str] = mapped_column(String, nullable=False)
+    csrf_token: Mapped[str] = mapped_column(String, nullable=False)
+    expires: Mapped[datetime.datetime] = mapped_column(DateTime, nullable=False)
+
+    # Any extra columns you want are fine
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime, default=datetime.datetime.utcnow
+    )
+
+# 2. Create the async engine
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+# 3. Create the adapter
+adapter = SqlAlchemyAdapter(engine=engine, session_model=Session)
+
+# 4. Wire up PyAuth
+auth = PyAuth(adapter=adapter, providers=[credentials_provider])
+```
+
+---
+
+## Session Model Requirements
+
+Your SQLAlchemy session model **must** define the following columns with exactly these names:
+
+| Column | Recommended type | Description |
+|---|---|---|
+| `id` | `String` / `UUID` (primary key) | Unique session identifier |
+| `session_token_hash` | `String` (unique, non-null) | SHA-256 hash of the raw session token |
+| `user_id` | `String` / `UUID` (non-null) | Reference to the owning user |
+| `csrf_token` | `String` (non-null) | Raw CSRF token for double-submit validation |
+| `expires` | `DateTime` (non-null) | Naive UTC datetime when the session expires |
+
+> **Extra columns are allowed.** You can freely add `created_at`, `ip_address`, `user_agent`, or any other columns your application needs.
+
+If any required column is missing, `SqlAlchemyAdapter.__init__` raises `AdapterError` with a descriptive message listing the missing columns.
+
+---
+
+## API Reference
+
+### `SqlAlchemyAdapter`
+
+```python
+SqlAlchemyAdapter(
+    engine: AsyncEngine,
+    session_model: Type[Any],
+)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `engine` | `AsyncEngine` | An async SQLAlchemy engine created via `create_async_engine` |
+| `session_model` | `Type[DeclarativeBase]` | Your SQLAlchemy declarative model class for sessions |
+
+Both parameters are validated immediately in `__init__`:
+- `engine` must be an `AsyncEngine` using a supported async driver (`asyncpg`, `aiomysql`, `aiosqlite`)
+- `session_model` must be a valid SQLAlchemy declarative class with all required columns present
+
+**Methods** (all async)
+
+| Method | Signature | Description |
+|---|---|---|
+| `create_session` | `(session_data: dict) -> dict` | Inserts a new session row and returns it as a dict |
+| `get_session_by_session_token_hash` | `(token_hash: str) -> dict \| None` | Fetches a session by hashed token, or `None` if not found |
+| `update_session` | `(session_id: str, updates: dict) -> dict \| None` | Updates fields on an existing session row and returns the updated record as a dict, or `None` if not found |
+| `delete_session_by_session_token_hash` | `(token_hash: str) -> None` | Deletes a session by hashed token |
+| `delete_session` | `(session_id: Any) -> None` | Deletes a session by its primary key / ID |
+
+---
+
+### Error Translation
+
+The adapter automatically maps SQLAlchemy exceptions to `py-auth-core` exceptions so `PyAuth` can handle them uniformly:
+
+| SQLAlchemy exception | py-auth-core exception | Trigger |
+|---|---|---|
+| `IntegrityError` (unique / duplicate) | `DuplicateEntryError` (409) | Duplicate `session_token_hash` |
+| `IntegrityError` (foreign key) | `ForeignKeyViolationError` (400) | `user_id` references a non-existent user |
+| `NoResultFound` | `RecordNotFoundError` (404) | Query returned no rows |
+| Any other `Exception` | `PyAuthError` (500) | Unexpected database error |
+
+`PyAuth.signin_with_credentials` automatically retries on `DuplicateEntryError` (up to 3 times with a fresh token) without any extra code on your part.
+
+---
+
+## Full FastAPI Example
+
+This example shows the full flow: user lookup, sign-in, and sign-up all handled inside a single `authorize()` callback — no separate signup endpoint needed.
+
+```python
+import datetime, uuid
+from fastapi import FastAPI, Request, Response
+from pydantic import BaseModel, EmailStr
+from passlib.context import CryptContext
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import DateTime, String, select
+
+from py_auth import PyAuth, CredentialsProvider
+from py_auth_sqlalchemy import SqlAlchemyAdapter
+
+pwd_ctx = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# --- SQLAlchemy models ---
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    email: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    hashed_password: Mapped[str] = mapped_column(String, nullable=False)
+
+class Session(Base):
+    __tablename__ = "sessions"
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_token_hash: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    user_id: Mapped[str] = mapped_column(String, nullable=False)
+    csrf_token: Mapped[str] = mapped_column(String, nullable=False)
+    expires: Mapped[datetime.datetime] = mapped_column(DateTime, nullable=False)
+
+# --- Engine and adapter ---
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+adapter = SqlAlchemyAdapter(engine=engine, session_model=Session)
+
+# --- Credentials schema ---
+class LoginSchema(BaseModel):
+    email: EmailStr
+    password: str
+
+# --- authorize() handles both sign-in and sign-up ---
+async def authorize(credentials: dict) -> dict | None:
+    """
+    Check if the user exists:
+      - If yes, verify their password and return their details.
+      - If no, create them and return the new user's details.
+      - Return None to reject (wrong password).
+    """
+    async with AsyncSession(engine) as db:
+        result = await db.execute(select(User).where(User.email == credentials["email"]))
+        user = result.scalar_one_or_none()
+
+        if user:
+            # Existing user — verify credentials
+            if not pwd_ctx.verify(credentials["password"], user.hashed_password):
+                return None
+            return {"id": user.id, "email": user.email}
+
+        # New user — create and return
+        async with db.begin():
+            new_user = User(
+                email=credentials["email"],
+                hashed_password=pwd_ctx.hash(credentials["password"]),
+            )
+            db.add(new_user)
+            await db.flush()
+            await db.refresh(new_user)
+        return {"id": new_user.id, "email": new_user.email}
+
+# --- Wire up PyAuth ---
+auth = PyAuth(
+    adapter=adapter,
+    providers=[CredentialsProvider(model=LoginSchema, authorize=authorize)],
+)
+
+# --- FastAPI routes ---
+app = FastAPI()
+
+@app.on_event("startup")
+async def startup():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+@app.post("/auth/signin")
+async def signin(request: Request, response: Response):
+    body = await request.json()
+    result = await auth.signin_with_credentials(body)
+    if result["error"]:
+        return result
+    data = result["data"]
+    response.set_cookie(auth.cookies["session_token"]["name"], data["session_token"],
+                        **auth.cookies["session_token"]["options"])
+    response.set_cookie(auth.cookies["csrf_token"]["name"], data["csrf_token"],
+                        **auth.cookies["csrf_token"]["options"])
+    return {"user": data["user"]}
+
+@app.get("/auth/verify")
+async def verify(request: Request):
+    session_token = request.cookies.get(auth.cookies["session_token"]["name"])
+    csrf_token = request.cookies.get(auth.cookies["csrf_token"]["name"])
+    return await auth.verify_session(session_token, csrf_token)
+
+@app.post("/auth/signout")
+async def signout(session_id: str):
+    return await auth.signout(session_id)
+```
+
+---
+
+## Security Notes
+
+- **Only hashed session tokens are stored in the database.** The raw token is set in a `httpOnly` cookie and never persisted.
+- **Always hash passwords** before persisting — use bcrypt, argon2, or scrypt. Never store plain text.
+- Use `expire_on_commit=False` (set by the adapter automatically) so ORM instances remain accessible after `session.commit()`.
+- For PostgreSQL, ensure your `Session` table has a **unique index** on `session_token_hash` at the database level to guarantee the uniqueness constraint that `DuplicateEntryError` depends on.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

py_auth_sqlalchemy-0.0.1/README.md

@@ -0,0 +1,306 @@
+# py-auth-sqlalchemy
+
+**High-performance, async SQLAlchemy 2.0 adapter for [py-auth-core](https://pypi.org/project/py-auth-core/).**
+
+Plug this adapter into `PyAuth` to get automatic, async session persistence across PostgreSQL, MySQL, and SQLite — with built-in error translation from SQLAlchemy exceptions into `py-auth-core` exceptions.
+
+[![PyPI version](https://img.shields.io/pypi/v/py-auth-sqlalchemy.svg)](https://pypi.org/project/py-auth-sqlalchemy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/py-auth-sqlalchemy.svg)](https://pypi.org/project/py-auth-sqlalchemy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Supported Databases](#supported-databases)
+- [Quick Start](#quick-start)
+- [Session Model Requirements](#session-model-requirements)
+- [API Reference](#api-reference)
+  - [SqlAlchemyAdapter](#sqlalchemyadapter)
+  - [Error Translation](#error-translation)
+- [Full FastAPI Example](#full-fastapi-example)
+- [Security Notes](#security-notes)
+- [License](#license)
+
+---
+
+## Features
+
+- ✅ **Async-native** — built entirely on SQLAlchemy `AsyncEngine` + `AsyncSession`
+- ✅ **BYO model** — bring your own declarative SQLAlchemy model; extra columns are fine
+- ✅ **Strict validation at startup** — engine type and required model columns are checked immediately, before any request is served
+- ✅ **Automatic error translation** — `IntegrityError` → `DuplicateEntryError` / `ForeignKeyViolationError`, `NoResultFound` → `RecordNotFoundError`
+- ✅ **Session-only** — user lookup and creation live in your `authorize()` callback, giving you full control
+
+---
+
+## Installation
+
+```bash
+pip install py-auth-sqlalchemy
+```
+
+Then install the async driver for your database:
+
+```bash
+# PostgreSQL
+pip install asyncpg
+
+# MySQL / MariaDB
+pip install aiomysql
+
+# SQLite
+pip install aiosqlite
+```
+
+**Requirements:** Python ≥ 3.9, SQLAlchemy ≥ 2.0, py-auth-core ≥ 0.0.1.
+
+---
+
+## Supported Databases
+
+| Database | Async driver | Connection URL prefix |
+|---|---|---|
+| PostgreSQL | `asyncpg` | `postgresql+asyncpg://` |
+| MySQL / MariaDB | `aiomysql` | `mysql+aiomysql://` |
+| SQLite | `aiosqlite` | `sqlite+aiosqlite:///` |
+
+The adapter validates the driver at startup and raises `AdapterError` for unsupported drivers.
+
+---
+
+## Quick Start
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import DateTime, String
+import uuid, datetime
+
+from py_auth_sqlalchemy import SqlAlchemyAdapter
+from py_auth import PyAuth, CredentialsProvider
+
+# 1. Define your SQLAlchemy session model
+class Base(DeclarativeBase):
+    pass
+
+class Session(Base):
+    __tablename__ = "sessions"
+
+    # Required columns — do NOT rename these
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_token_hash: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    user_id: Mapped[str] = mapped_column(String, nullable=False)
+    csrf_token: Mapped[str] = mapped_column(String, nullable=False)
+    expires: Mapped[datetime.datetime] = mapped_column(DateTime, nullable=False)
+
+    # Any extra columns you want are fine
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime, default=datetime.datetime.utcnow
+    )
+
+# 2. Create the async engine
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+# 3. Create the adapter
+adapter = SqlAlchemyAdapter(engine=engine, session_model=Session)
+
+# 4. Wire up PyAuth
+auth = PyAuth(adapter=adapter, providers=[credentials_provider])
+```
+
+---
+
+## Session Model Requirements
+
+Your SQLAlchemy session model **must** define the following columns with exactly these names:
+
+| Column | Recommended type | Description |
+|---|---|---|
+| `id` | `String` / `UUID` (primary key) | Unique session identifier |
+| `session_token_hash` | `String` (unique, non-null) | SHA-256 hash of the raw session token |
+| `user_id` | `String` / `UUID` (non-null) | Reference to the owning user |
+| `csrf_token` | `String` (non-null) | Raw CSRF token for double-submit validation |
+| `expires` | `DateTime` (non-null) | Naive UTC datetime when the session expires |
+
+> **Extra columns are allowed.** You can freely add `created_at`, `ip_address`, `user_agent`, or any other columns your application needs.
+
+If any required column is missing, `SqlAlchemyAdapter.__init__` raises `AdapterError` with a descriptive message listing the missing columns.
+
+---
+
+## API Reference
+
+### `SqlAlchemyAdapter`
+
+```python
+SqlAlchemyAdapter(
+    engine: AsyncEngine,
+    session_model: Type[Any],
+)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `engine` | `AsyncEngine` | An async SQLAlchemy engine created via `create_async_engine` |
+| `session_model` | `Type[DeclarativeBase]` | Your SQLAlchemy declarative model class for sessions |
+
+Both parameters are validated immediately in `__init__`:
+- `engine` must be an `AsyncEngine` using a supported async driver (`asyncpg`, `aiomysql`, `aiosqlite`)
+- `session_model` must be a valid SQLAlchemy declarative class with all required columns present
+
+**Methods** (all async)
+
+| Method | Signature | Description |
+|---|---|---|
+| `create_session` | `(session_data: dict) -> dict` | Inserts a new session row and returns it as a dict |
+| `get_session_by_session_token_hash` | `(token_hash: str) -> dict \| None` | Fetches a session by hashed token, or `None` if not found |
+| `update_session` | `(session_id: str, updates: dict) -> dict \| None` | Updates fields on an existing session row and returns the updated record as a dict, or `None` if not found |
+| `delete_session_by_session_token_hash` | `(token_hash: str) -> None` | Deletes a session by hashed token |
+| `delete_session` | `(session_id: Any) -> None` | Deletes a session by its primary key / ID |
+
+---
+
+### Error Translation
+
+The adapter automatically maps SQLAlchemy exceptions to `py-auth-core` exceptions so `PyAuth` can handle them uniformly:
+
+| SQLAlchemy exception | py-auth-core exception | Trigger |
+|---|---|---|
+| `IntegrityError` (unique / duplicate) | `DuplicateEntryError` (409) | Duplicate `session_token_hash` |
+| `IntegrityError` (foreign key) | `ForeignKeyViolationError` (400) | `user_id` references a non-existent user |
+| `NoResultFound` | `RecordNotFoundError` (404) | Query returned no rows |
+| Any other `Exception` | `PyAuthError` (500) | Unexpected database error |
+
+`PyAuth.signin_with_credentials` automatically retries on `DuplicateEntryError` (up to 3 times with a fresh token) without any extra code on your part.
+
+---
+
+## Full FastAPI Example
+
+This example shows the full flow: user lookup, sign-in, and sign-up all handled inside a single `authorize()` callback — no separate signup endpoint needed.
+
+```python
+import datetime, uuid
+from fastapi import FastAPI, Request, Response
+from pydantic import BaseModel, EmailStr
+from passlib.context import CryptContext
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import DateTime, String, select
+
+from py_auth import PyAuth, CredentialsProvider
+from py_auth_sqlalchemy import SqlAlchemyAdapter
+
+pwd_ctx = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# --- SQLAlchemy models ---
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    email: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    hashed_password: Mapped[str] = mapped_column(String, nullable=False)
+
+class Session(Base):
+    __tablename__ = "sessions"
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_token_hash: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    user_id: Mapped[str] = mapped_column(String, nullable=False)
+    csrf_token: Mapped[str] = mapped_column(String, nullable=False)
+    expires: Mapped[datetime.datetime] = mapped_column(DateTime, nullable=False)
+
+# --- Engine and adapter ---
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+adapter = SqlAlchemyAdapter(engine=engine, session_model=Session)
+
+# --- Credentials schema ---
+class LoginSchema(BaseModel):
+    email: EmailStr
+    password: str
+
+# --- authorize() handles both sign-in and sign-up ---
+async def authorize(credentials: dict) -> dict | None:
+    """
+    Check if the user exists:
+      - If yes, verify their password and return their details.
+      - If no, create them and return the new user's details.
+      - Return None to reject (wrong password).
+    """
+    async with AsyncSession(engine) as db:
+        result = await db.execute(select(User).where(User.email == credentials["email"]))
+        user = result.scalar_one_or_none()
+
+        if user:
+            # Existing user — verify credentials
+            if not pwd_ctx.verify(credentials["password"], user.hashed_password):
+                return None
+            return {"id": user.id, "email": user.email}
+
+        # New user — create and return
+        async with db.begin():
+            new_user = User(
+                email=credentials["email"],
+                hashed_password=pwd_ctx.hash(credentials["password"]),
+            )
+            db.add(new_user)
+            await db.flush()
+            await db.refresh(new_user)
+        return {"id": new_user.id, "email": new_user.email}
+
+# --- Wire up PyAuth ---
+auth = PyAuth(
+    adapter=adapter,
+    providers=[CredentialsProvider(model=LoginSchema, authorize=authorize)],
+)
+
+# --- FastAPI routes ---
+app = FastAPI()
+
+@app.on_event("startup")
+async def startup():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+@app.post("/auth/signin")
+async def signin(request: Request, response: Response):
+    body = await request.json()
+    result = await auth.signin_with_credentials(body)
+    if result["error"]:
+        return result
+    data = result["data"]
+    response.set_cookie(auth.cookies["session_token"]["name"], data["session_token"],
+                        **auth.cookies["session_token"]["options"])
+    response.set_cookie(auth.cookies["csrf_token"]["name"], data["csrf_token"],
+                        **auth.cookies["csrf_token"]["options"])
+    return {"user": data["user"]}
+
+@app.get("/auth/verify")
+async def verify(request: Request):
+    session_token = request.cookies.get(auth.cookies["session_token"]["name"])
+    csrf_token = request.cookies.get(auth.cookies["csrf_token"]["name"])
+    return await auth.verify_session(session_token, csrf_token)
+
+@app.post("/auth/signout")
+async def signout(session_id: str):
+    return await auth.signout(session_id)
+```
+
+---
+
+## Security Notes
+
+- **Only hashed session tokens are stored in the database.** The raw token is set in a `httpOnly` cookie and never persisted.
+- **Always hash passwords** before persisting — use bcrypt, argon2, or scrypt. Never store plain text.
+- Use `expire_on_commit=False` (set by the adapter automatically) so ORM instances remain accessible after `session.commit()`.
+- For PostgreSQL, ensure your `Session` table has a **unique index** on `session_token_hash` at the database level to guarantee the uniqueness constraint that `DuplicateEntryError` depends on.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

py_auth_sqlalchemy-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-auth-sqlalchemy"
+version = "0.0.1"
+authors = [
+  { name = "Olatunji Jamaldeen Omotoyosi", email = "jamaldeen.o@yahoo.com" },
+]
+description = "High-performance, async SQLAlchemy adapter for py-auth-core."
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+dependencies = [
+    "sqlalchemy>=2.0.0",
+    "greenlet>=3.0.0",
+    "py-auth-core>=0.0.1",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/jamaldeen09/py-auth"
+"Repository" = "https://github.com/jamaldeen09/py-auth"
+
+[tool.setuptools.packages.find]
+where = ["src"]

py_auth_sqlalchemy-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy/__init__.py

@@ -0,0 +1,10 @@
+"""
+py-auth-sqlalchemy: High-performance, async SQLAlchemy adapter for py-auth.
+"""
+
+
+from .core import SqlAlchemyAdapter
+
+
+__all__ = ["SqlAlchemyAdapter"]
+__version__ = "0.0.1"

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy/core.py

@@ -0,0 +1,111 @@
+from .utils import handle_db_errors, validate_async_engine, validate_sqlalchemy_model
+
+from typing import Any, Dict, Optional, Type
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+
+class SqlAlchemyAdapter:
+    """SQLAlchemy ORM adapter for py-auth.
+
+    Provides asynchronous session persistence using SQLAlchemy 2.0.
+    User lookup and creation is handled entirely within the authorize()
+    callback of your CredentialsProvider.
+    """
+
+    def __init__(
+        self,
+        engine: AsyncEngine,
+        session_model: Optional[Type[Any]] = None,
+    ):
+        self.session_model = validate_sqlalchemy_model(
+            model=session_model,
+            model_name="Session",
+            required_cols={
+                "id",
+                "session_token_hash",
+                "user_id",
+                "expires",
+                "csrf_token",
+            },
+        )
+
+        self.engine = validate_async_engine(engine=engine)
+        self.session_maker = async_sessionmaker(
+            bind=self.engine, class_=AsyncSession, expire_on_commit=False
+        )
+
+    def _row_to_dict(self, instance: Any) -> Optional[Dict[str, Any]]:
+        """Convert ORM instance to a dictionary using its table column names."""
+        if instance is None:
+            return None
+        cols = [c.name for c in instance.__table__.columns]
+        return {name: getattr(instance, name) for name in cols}
+
+    async def create_session(self, session_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Create and persist a new session record."""
+        async with handle_db_errors(operation="create_session"):
+            async with self.session_maker() as session:
+                async with session.begin():
+                    s = self.session_model(**session_data)
+                    session.add(s)
+                    await session.flush()
+                    await session.refresh(s)
+                return self._row_to_dict(s)
+
+    async def update_session(
+        self, session_id: str, updates: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        async with handle_db_errors(operation="update_session"):
+            async with self.session_maker() as session:
+                async with session.begin():
+                    stmt = (
+                        select(self.session_model)
+                        .where(self.session_model.id == session_id)
+                        .with_for_update()
+                    )
+                    result = await session.execute(stmt)
+                    s = result.scalars().first()
+                    if s is None:
+                        return None
+                    for k, v in updates.items():
+                        if hasattr(s, k) and k != "id":
+                            setattr(s, k, v)
+            await session.refresh(s)
+            return self._row_to_dict(s)
+
+    async def get_session_by_session_token_hash(
+        self, session_token_hash: str
+    ) -> Optional[Dict[str, Any]]:
+        """Retrieve a session record by its hashed session token."""
+        async with handle_db_errors(operation="get_session_by_session_token_hash"):
+            async with self.session_maker() as session:
+                stmt = select(self.session_model).where(
+                    self.session_model.session_token_hash == session_token_hash
+                )
+                result = await session.execute(stmt)
+                s = result.scalar_one_or_none()
+                if not s:
+                    return None
+                return self._row_to_dict(s)
+
+    async def delete_session_by_session_token_hash(
+        self, session_token_hash: str
+    ) -> None:
+        """Delete a session record by its hashed session token."""
+        async with handle_db_errors(operation="delete_session_by_session_token_hash"):
+            async with self.session_maker() as session:
+                async with session.begin():
+                    stmt = delete(self.session_model).where(
+                        self.session_model.session_token_hash == session_token_hash
+                    )
+                    await session.execute(stmt)
+
+    async def delete_session(self, session_id: Any) -> None:
+        """Delete a session record by its unique identifier."""
+        async with handle_db_errors(operation="delete_session_by_id"):
+            async with self.session_maker() as session:
+                async with session.begin():
+                    stmt = delete(self.session_model).where(
+                        self.session_model.id == session_id
+                    )
+                    await session.execute(stmt)

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy/utils.py

@@ -0,0 +1,100 @@
+from contextlib import asynccontextmanager
+from typing import Any
+
+from py_auth.exceptions import (
+    AdapterError,
+    DuplicateEntryError,
+    ForeignKeyViolationError,
+    PyAuthError,
+    RecordNotFoundError,
+)
+from sqlalchemy import inspect
+from sqlalchemy.exc import IntegrityError, NoResultFound
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+
+def validate_async_engine(engine: object) -> AsyncEngine:
+    """Validate that the engine is an asynchronous SQLAlchemy AsyncEngine
+    and uses a supported asynchronous database driver.
+    """
+    if not isinstance(engine, AsyncEngine):
+        raise TypeError(
+            "Invalid database engine. py-auth requires an asynchronous SQLAlchemy "
+            "'AsyncEngine' (created via create_async_engine)."
+        )
+
+    # Inspect the driver prefix from the engine's URL object
+    supported_drivers = ("asyncpg", "aiomysql", "aiosqlite")
+    driver = engine.url.get_driver_name()
+
+    if driver not in supported_drivers:
+        raise AdapterError(
+            f"Unsupported database driver '{driver}'. "
+            f"py-auth requires one of the following async drivers: {supported_drivers}"
+        )
+    return engine
+
+
+def validate_sqlalchemy_model(
+    model: type[Any],
+    required_cols: set[str],
+    model_name: str | None = None,
+) -> type[Any]:
+    """Validate that the provided class is a valid SQLAlchemy declarative model
+    and defines all required py-auth columns.
+    """
+    if model is None:
+        name = model_name or "Model"
+        raise AdapterError(f"'{name}' model is required and cannot be None.")
+
+    display_name = getattr(model, "__name__", None) or model_name or "Model"
+
+    try:
+        mapper = inspect(model)
+        col_names = {c.key for c in mapper.columns}
+    except Exception as e:
+        raise AdapterError(
+            f"Provided '{display_name}' must be a valid SQLAlchemy model class: {e}"
+        )
+
+    if not required_cols.issubset(col_names):
+        missing = sorted(required_cols - col_names)
+        raise AdapterError(
+            f"Custom {display_name} model is missing required py-auth columns: {missing}. "
+            "Extra custom columns are allowed, but these base columns are mandatory."
+        )
+    return model
+
+
+@asynccontextmanager
+async def handle_db_errors(operation: str):
+    """Context manager for the SQLAlchemy adapter to intercept database-specific
+    exceptions and translate them into py-auth core exceptions.
+    """
+    try:
+        yield
+    except IntegrityError as e:
+        error_msg = str(e.orig or e).lower()
+        if "foreign key" in error_msg or "violates foreign key" in error_msg:
+            raise ForeignKeyViolationError(
+                f"Failed to complete operation '{operation}': the referenced record does not exist."
+            ) from e
+        elif "unique" in error_msg or "duplicate" in error_msg:
+            raise DuplicateEntryError(
+                f"Failed to complete operation '{operation}': a record with this unique value already exists."
+            ) from e
+        raise PyAuthError(
+            f"Database integrity error occurred in operation '{operation}': {e}"
+        ) from e
+
+    except NoResultFound as e:
+        raise RecordNotFoundError(
+            f"Failed to complete operation '{operation}': the requested record was not found."
+        ) from e
+
+    except PyAuthError:
+        raise
+    except Exception as e:
+        raise PyAuthError(
+            f"An unexpected database error occurred in operation '{operation}': {e}"
+        ) from e

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy.egg-info/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: py-auth-sqlalchemy
+Version: 0.0.1
+Summary: High-performance, async SQLAlchemy adapter for py-auth-core.
+Author-email: Olatunji Jamaldeen Omotoyosi <jamaldeen.o@yahoo.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jamaldeen09/py-auth
+Project-URL: Repository, https://github.com/jamaldeen09/py-auth
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: greenlet>=3.0.0
+Requires-Dist: py-auth-core>=0.0.1
+Dynamic: license-file
+
+# py-auth-sqlalchemy
+
+**High-performance, async SQLAlchemy 2.0 adapter for [py-auth-core](https://pypi.org/project/py-auth-core/).**
+
+Plug this adapter into `PyAuth` to get automatic, async session persistence across PostgreSQL, MySQL, and SQLite — with built-in error translation from SQLAlchemy exceptions into `py-auth-core` exceptions.
+
+[![PyPI version](https://img.shields.io/pypi/v/py-auth-sqlalchemy.svg)](https://pypi.org/project/py-auth-sqlalchemy/)
+[![Python versions](https://img.shields.io/pypi/pyversions/py-auth-sqlalchemy.svg)](https://pypi.org/project/py-auth-sqlalchemy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Supported Databases](#supported-databases)
+- [Quick Start](#quick-start)
+- [Session Model Requirements](#session-model-requirements)
+- [API Reference](#api-reference)
+  - [SqlAlchemyAdapter](#sqlalchemyadapter)
+  - [Error Translation](#error-translation)
+- [Full FastAPI Example](#full-fastapi-example)
+- [Security Notes](#security-notes)
+- [License](#license)
+
+---
+
+## Features
+
+- ✅ **Async-native** — built entirely on SQLAlchemy `AsyncEngine` + `AsyncSession`
+- ✅ **BYO model** — bring your own declarative SQLAlchemy model; extra columns are fine
+- ✅ **Strict validation at startup** — engine type and required model columns are checked immediately, before any request is served
+- ✅ **Automatic error translation** — `IntegrityError` → `DuplicateEntryError` / `ForeignKeyViolationError`, `NoResultFound` → `RecordNotFoundError`
+- ✅ **Session-only** — user lookup and creation live in your `authorize()` callback, giving you full control
+
+---
+
+## Installation
+
+```bash
+pip install py-auth-sqlalchemy
+```
+
+Then install the async driver for your database:
+
+```bash
+# PostgreSQL
+pip install asyncpg
+
+# MySQL / MariaDB
+pip install aiomysql
+
+# SQLite
+pip install aiosqlite
+```
+
+**Requirements:** Python ≥ 3.9, SQLAlchemy ≥ 2.0, py-auth-core ≥ 0.0.1.
+
+---
+
+## Supported Databases
+
+| Database | Async driver | Connection URL prefix |
+|---|---|---|
+| PostgreSQL | `asyncpg` | `postgresql+asyncpg://` |
+| MySQL / MariaDB | `aiomysql` | `mysql+aiomysql://` |
+| SQLite | `aiosqlite` | `sqlite+aiosqlite:///` |
+
+The adapter validates the driver at startup and raises `AdapterError` for unsupported drivers.
+
+---
+
+## Quick Start
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import DateTime, String
+import uuid, datetime
+
+from py_auth_sqlalchemy import SqlAlchemyAdapter
+from py_auth import PyAuth, CredentialsProvider
+
+# 1. Define your SQLAlchemy session model
+class Base(DeclarativeBase):
+    pass
+
+class Session(Base):
+    __tablename__ = "sessions"
+
+    # Required columns — do NOT rename these
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_token_hash: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    user_id: Mapped[str] = mapped_column(String, nullable=False)
+    csrf_token: Mapped[str] = mapped_column(String, nullable=False)
+    expires: Mapped[datetime.datetime] = mapped_column(DateTime, nullable=False)
+
+    # Any extra columns you want are fine
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime, default=datetime.datetime.utcnow
+    )
+
+# 2. Create the async engine
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+# 3. Create the adapter
+adapter = SqlAlchemyAdapter(engine=engine, session_model=Session)
+
+# 4. Wire up PyAuth
+auth = PyAuth(adapter=adapter, providers=[credentials_provider])
+```
+
+---
+
+## Session Model Requirements
+
+Your SQLAlchemy session model **must** define the following columns with exactly these names:
+
+| Column | Recommended type | Description |
+|---|---|---|
+| `id` | `String` / `UUID` (primary key) | Unique session identifier |
+| `session_token_hash` | `String` (unique, non-null) | SHA-256 hash of the raw session token |
+| `user_id` | `String` / `UUID` (non-null) | Reference to the owning user |
+| `csrf_token` | `String` (non-null) | Raw CSRF token for double-submit validation |
+| `expires` | `DateTime` (non-null) | Naive UTC datetime when the session expires |
+
+> **Extra columns are allowed.** You can freely add `created_at`, `ip_address`, `user_agent`, or any other columns your application needs.
+
+If any required column is missing, `SqlAlchemyAdapter.__init__` raises `AdapterError` with a descriptive message listing the missing columns.
+
+---
+
+## API Reference
+
+### `SqlAlchemyAdapter`
+
+```python
+SqlAlchemyAdapter(
+    engine: AsyncEngine,
+    session_model: Type[Any],
+)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `engine` | `AsyncEngine` | An async SQLAlchemy engine created via `create_async_engine` |
+| `session_model` | `Type[DeclarativeBase]` | Your SQLAlchemy declarative model class for sessions |
+
+Both parameters are validated immediately in `__init__`:
+- `engine` must be an `AsyncEngine` using a supported async driver (`asyncpg`, `aiomysql`, `aiosqlite`)
+- `session_model` must be a valid SQLAlchemy declarative class with all required columns present
+
+**Methods** (all async)
+
+| Method | Signature | Description |
+|---|---|---|
+| `create_session` | `(session_data: dict) -> dict` | Inserts a new session row and returns it as a dict |
+| `get_session_by_session_token_hash` | `(token_hash: str) -> dict \| None` | Fetches a session by hashed token, or `None` if not found |
+| `update_session` | `(session_id: str, updates: dict) -> dict \| None` | Updates fields on an existing session row and returns the updated record as a dict, or `None` if not found |
+| `delete_session_by_session_token_hash` | `(token_hash: str) -> None` | Deletes a session by hashed token |
+| `delete_session` | `(session_id: Any) -> None` | Deletes a session by its primary key / ID |
+
+---
+
+### Error Translation
+
+The adapter automatically maps SQLAlchemy exceptions to `py-auth-core` exceptions so `PyAuth` can handle them uniformly:
+
+| SQLAlchemy exception | py-auth-core exception | Trigger |
+|---|---|---|
+| `IntegrityError` (unique / duplicate) | `DuplicateEntryError` (409) | Duplicate `session_token_hash` |
+| `IntegrityError` (foreign key) | `ForeignKeyViolationError` (400) | `user_id` references a non-existent user |
+| `NoResultFound` | `RecordNotFoundError` (404) | Query returned no rows |
+| Any other `Exception` | `PyAuthError` (500) | Unexpected database error |
+
+`PyAuth.signin_with_credentials` automatically retries on `DuplicateEntryError` (up to 3 times with a fresh token) without any extra code on your part.
+
+---
+
+## Full FastAPI Example
+
+This example shows the full flow: user lookup, sign-in, and sign-up all handled inside a single `authorize()` callback — no separate signup endpoint needed.
+
+```python
+import datetime, uuid
+from fastapi import FastAPI, Request, Response
+from pydantic import BaseModel, EmailStr
+from passlib.context import CryptContext
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import DateTime, String, select
+
+from py_auth import PyAuth, CredentialsProvider
+from py_auth_sqlalchemy import SqlAlchemyAdapter
+
+pwd_ctx = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# --- SQLAlchemy models ---
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    email: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    hashed_password: Mapped[str] = mapped_column(String, nullable=False)
+
+class Session(Base):
+    __tablename__ = "sessions"
+    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_token_hash: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    user_id: Mapped[str] = mapped_column(String, nullable=False)
+    csrf_token: Mapped[str] = mapped_column(String, nullable=False)
+    expires: Mapped[datetime.datetime] = mapped_column(DateTime, nullable=False)
+
+# --- Engine and adapter ---
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+adapter = SqlAlchemyAdapter(engine=engine, session_model=Session)
+
+# --- Credentials schema ---
+class LoginSchema(BaseModel):
+    email: EmailStr
+    password: str
+
+# --- authorize() handles both sign-in and sign-up ---
+async def authorize(credentials: dict) -> dict | None:
+    """
+    Check if the user exists:
+      - If yes, verify their password and return their details.
+      - If no, create them and return the new user's details.
+      - Return None to reject (wrong password).
+    """
+    async with AsyncSession(engine) as db:
+        result = await db.execute(select(User).where(User.email == credentials["email"]))
+        user = result.scalar_one_or_none()
+
+        if user:
+            # Existing user — verify credentials
+            if not pwd_ctx.verify(credentials["password"], user.hashed_password):
+                return None
+            return {"id": user.id, "email": user.email}
+
+        # New user — create and return
+        async with db.begin():
+            new_user = User(
+                email=credentials["email"],
+                hashed_password=pwd_ctx.hash(credentials["password"]),
+            )
+            db.add(new_user)
+            await db.flush()
+            await db.refresh(new_user)
+        return {"id": new_user.id, "email": new_user.email}
+
+# --- Wire up PyAuth ---
+auth = PyAuth(
+    adapter=adapter,
+    providers=[CredentialsProvider(model=LoginSchema, authorize=authorize)],
+)
+
+# --- FastAPI routes ---
+app = FastAPI()
+
+@app.on_event("startup")
+async def startup():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+@app.post("/auth/signin")
+async def signin(request: Request, response: Response):
+    body = await request.json()
+    result = await auth.signin_with_credentials(body)
+    if result["error"]:
+        return result
+    data = result["data"]
+    response.set_cookie(auth.cookies["session_token"]["name"], data["session_token"],
+                        **auth.cookies["session_token"]["options"])
+    response.set_cookie(auth.cookies["csrf_token"]["name"], data["csrf_token"],
+                        **auth.cookies["csrf_token"]["options"])
+    return {"user": data["user"]}
+
+@app.get("/auth/verify")
+async def verify(request: Request):
+    session_token = request.cookies.get(auth.cookies["session_token"]["name"])
+    csrf_token = request.cookies.get(auth.cookies["csrf_token"]["name"])
+    return await auth.verify_session(session_token, csrf_token)
+
+@app.post("/auth/signout")
+async def signout(session_id: str):
+    return await auth.signout(session_id)
+```
+
+---
+
+## Security Notes
+
+- **Only hashed session tokens are stored in the database.** The raw token is set in a `httpOnly` cookie and never persisted.
+- **Always hash passwords** before persisting — use bcrypt, argon2, or scrypt. Never store plain text.
+- Use `expire_on_commit=False` (set by the adapter automatically) so ORM instances remain accessible after `session.commit()`.
+- For PostgreSQL, ensure your `Session` table has a **unique index** on `session_token_hash` at the database level to guarantee the uniqueness constraint that `DuplicateEntryError` depends on.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/py_auth_sqlalchemy/__init__.py
+src/py_auth_sqlalchemy/core.py
+src/py_auth_sqlalchemy/py.typed
+src/py_auth_sqlalchemy/utils.py
+src/py_auth_sqlalchemy.egg-info/PKG-INFO
+src/py_auth_sqlalchemy.egg-info/SOURCES.txt
+src/py_auth_sqlalchemy.egg-info/dependency_links.txt
+src/py_auth_sqlalchemy.egg-info/requires.txt
+src/py_auth_sqlalchemy.egg-info/top_level.txt

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy.egg-info/requires.txt

@@ -0,0 +1,3 @@
+sqlalchemy>=2.0.0
+greenlet>=3.0.0
+py-auth-core>=0.0.1

py_auth_sqlalchemy-0.0.1/src/py_auth_sqlalchemy.egg-info/top_level.txt

@@ -0,0 +1 @@
+py_auth_sqlalchemy