@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/fastapi-expert/steering/authentication.md

@@ -0,0 +1,159 @@
+# Authentication
+
+## OAuth2 Password Flow
+
+```python
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from typing import Annotated
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/token")
+
+@router.post("/token")
+async def login(
+    db: DB,
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+) -> Token:
+    user = await authenticate_user(db, form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status.HTTP_401_UNAUTHORIZED,
+            "Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return Token(
+        access_token=create_access_token(sub=str(user.id)),
+        token_type="bearer",
+    )
+```
+
+## JWT Token Creation
+
+```python
+from datetime import datetime, timedelta, UTC
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def create_access_token(
+    sub: str,
+    expires_delta: timedelta | None = None,
+) -> str:
+    expire = datetime.now(UTC) + (expires_delta or timedelta(minutes=15))
+    return jwt.encode(
+        {"sub": sub, "exp": expire, "type": "access"},
+        settings.SECRET_KEY,
+        algorithm="HS256",
+    )
+
+def create_refresh_token(sub: str) -> str:
+    expire = datetime.now(UTC) + timedelta(days=7)
+    return jwt.encode(
+        {"sub": sub, "exp": expire, "type": "refresh"},
+        settings.SECRET_KEY,
+        algorithm="HS256",
+    )
+```
+
+## Get Current User
+
+```python
+async def get_current_user(
+    db: DB,
+    token: Annotated[str, Depends(oauth2_scheme)],
+) -> User:
+    credentials_exception = HTTPException(
+        status.HTTP_401_UNAUTHORIZED,
+        "Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
+        user_id = int(payload.get("sub"))
+        if payload.get("type") != "access":
+            raise credentials_exception
+    except (JWTError, ValueError, TypeError):
+        raise credentials_exception
+
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise credentials_exception
+    return user
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+```
+
+## Role-Based Access
+
+```python
+from enum import Enum
+
+class UserRole(str, Enum):
+    USER = "user"
+    ADMIN = "admin"
+    MODERATOR = "moderator"
+
+def require_roles(*roles: UserRole):
+    async def role_checker(current_user: CurrentUser) -> User:
+        if current_user.role not in roles:
+            raise HTTPException(
+                status.HTTP_403_FORBIDDEN,
+                f"Required roles: {[r.value for r in roles]}",
+            )
+        return current_user
+    return role_checker
+
+# Usage
+@router.delete("/{id}")
+async def delete_user(
+    user_id: int,
+    admin: Annotated[User, Depends(require_roles(UserRole.ADMIN))],
+) -> None:
+    ...
+```
+
+## Refresh Token
+
+```python
+@router.post("/refresh", response_model=Token)
+async def refresh_token(
+    db: DB,
+    refresh_token: str = Body(..., embed=True),
+) -> Token:
+    try:
+        payload = jwt.decode(refresh_token, settings.SECRET_KEY, algorithms=["HS256"])
+        if payload.get("type") != "refresh":
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid token type")
+        user_id = int(payload.get("sub"))
+    except (JWTError, ValueError):
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid refresh token")
+
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "User not found")
+
+    return Token(
+        access_token=create_access_token(sub=str(user.id)),
+        token_type="bearer",
+    )
+```
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| `OAuth2PasswordBearer` | Extract token from header |
+| `OAuth2PasswordRequestForm` | Login form data |
+| `jwt.encode()` | Create JWT |
+| `jwt.decode()` | Verify JWT |
+| `pwd_context.hash()` | Hash password |
+| `pwd_context.verify()` | Check password |
+| `Depends(get_current_user)` | Require auth |
+| `require_roles()` | Role-based access |

package/Ai Agent Workflow/powers/fastapi-expert/steering/endpoints-routing.md

@@ -0,0 +1,142 @@
+# Endpoints & Routing
+
+## Router Setup
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Path
+from typing import Annotated
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+# Type aliases for common dependencies
+DB = Annotated[AsyncSession, Depends(get_db)]
+CurrentUser = Annotated[User, Depends(get_current_user)]
+Pagination = Annotated[int, Query(ge=1, le=100)]
+```
+
+## CRUD Endpoints
+
+```python
+@router.post("/", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+async def create_user(db: DB, user_in: UserCreate) -> User:
+    if await get_user_by_email(db, user_in.email):
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "Email already registered")
+    return await create_user_db(db, user_in)
+
+@router.get("/", response_model=list[UserOut])
+async def list_users(
+    db: DB,
+    current_user: CurrentUser,
+    skip: int = Query(0, ge=0),
+    limit: Pagination = 20,
+) -> list[User]:
+    return await get_users(db, skip=skip, limit=limit)
+
+@router.get("/{user_id}", response_model=UserOut)
+async def get_user(
+    db: DB,
+    user_id: Annotated[int, Path(gt=0)],
+) -> User:
+    user = await get_user_db(db, user_id)
+    if not user:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "User not found")
+    return user
+
+@router.patch("/{user_id}", response_model=UserOut)
+async def update_user(
+    db: DB,
+    user_id: int,
+    user_in: UserUpdate,
+    current_user: CurrentUser,
+) -> User:
+    if current_user.id != user_id and not current_user.is_admin:
+        raise HTTPException(status.HTTP_403_FORBIDDEN, "Not authorized")
+    return await update_user_db(db, user_id, user_in)
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(db: DB, user_id: int, current_user: CurrentUser) -> None:
+    if not await delete_user_db(db, user_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "User not found")
+```
+
+## Custom Dependencies
+
+```python
+from fastapi import Depends
+
+async def get_current_active_user(
+    current_user: CurrentUser,
+) -> User:
+    if not current_user.is_active:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "Inactive user")
+    return current_user
+
+ActiveUser = Annotated[User, Depends(get_current_active_user)]
+
+async def require_admin(current_user: CurrentUser) -> User:
+    if not current_user.is_admin:
+        raise HTTPException(status.HTTP_403_FORBIDDEN, "Admin required")
+    return current_user
+
+AdminUser = Annotated[User, Depends(require_admin)]
+```
+
+## Query Parameters
+
+```python
+@router.get("/search")
+async def search_users(
+    db: DB,
+    q: str = Query(min_length=1, max_length=100),
+    is_active: bool | None = None,
+    role: UserRole | None = None,
+    created_after: datetime | None = None,
+    sort_by: Annotated[str, Query(pattern="^(name|email|created_at)$")] = "created_at",
+    order: Annotated[str, Query(pattern="^(asc|desc)$")] = "desc",
+) -> list[User]:
+    return await search_users_db(db, q, is_active, role, created_after, sort_by, order)
+```
+
+## Include Router
+
+```python
+# main.py
+from fastapi import FastAPI
+from app.api.v1 import users, auth, posts
+
+app = FastAPI()
+
+app.include_router(users.router, prefix="/api/v1")
+app.include_router(auth.router, prefix="/api/v1")
+app.include_router(posts.router, prefix="/api/v1")
+```
+
+## Response Models
+
+```python
+from fastapi import Response
+
+@router.get("/", response_model=list[UserOut], response_model_exclude_unset=True)
+async def list_users(...) -> list[User]:
+    ...
+
+@router.get("/{id}", responses={
+    200: {"model": UserOut},
+    404: {"description": "User not found"},
+})
+async def get_user(...) -> User:
+    ...
+```
+
+## Quick Reference
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@router.get("/")` | GET endpoint |
+| `@router.post("/", status_code=201)` | POST with status |
+| `Query(ge=0)` | Query param validation |
+| `Path(gt=0)` | Path param validation |
+| `Depends(func)` | Dependency injection |
+| `Annotated[T, Depends()]` | Type alias pattern |
+| `response_model=Model` | Response schema |
+| `HTTPException(status, detail)` | Error response |