core-package 0.1.0__py3-none-any.whl

apps/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

apps/contacts/admin.py

@@ -0,0 +1,18 @@
+from django.contrib import admin
+from unfold.admin import ModelAdmin
+
+from apps.contacts.models import Contact, ContactForm
+
+
+@admin.register(Contact)
+class ContactAdmin(ModelAdmin):
+    list_display = ("name", "email", "phone", "created_at")
+    search_fields = ("name", "email", "phone", "address")
+    readonly_fields = ("id", "created_at", "updated_at")
+
+
+@admin.register(ContactForm)
+class ContactFormAdmin(ModelAdmin):
+    list_display = ("name", "email", "phone", "site", "created_at")
+    search_fields = ("name", "email", "phone", "site", "text")
+    readonly_fields = ("id", "created_at", "updated_at")

apps/contacts/api.py

@@ -0,0 +1,86 @@
+import uuid
+
+from ninja import Router, Status
+
+from apps.contacts import services
+from apps.contacts.schemas import ContactFormIn, ContactFormOut, ContactIn, ContactOut, ContactUpdateIn
+from apps.contacts.services import contact_form_queryset, contact_queryset
+from apps.core.pagination import PageParams, paginate_queryset
+from apps.core.permissions import require_role
+from apps.core.schemas import PagedResponse
+from apps.core.throttling import check_rate_limit
+from apps.core.utils import get_client_ip
+
+router = Router(tags=["contacts"])
+
+# NOTE: literal-path routes (/forms, /forms/{form_id}) are registered before
+# the "/{contact_id}" wildcard routes below. See AGENT.md §9 point 5: a
+# wildcard route registered first would swallow "/forms" and return 405.
+
+
+@router.post("/forms", response={201: ContactFormOut}, auth=None)
+async def submit_contact_form(request, payload: ContactFormIn):
+    await check_rate_limit(f"contact_form:{get_client_ip(request)}", limit=5, window_seconds=60)
+    form = await services.submit_contact_form(
+        name=payload.name, email=payload.email, phone=payload.phone, site=payload.site, text=payload.text
+    )
+    return Status(201, form)
+
+
+@router.get("/forms", response=PagedResponse[ContactFormOut])
+@require_role("admin")
+async def list_contact_forms(request, page: PageParams = PageParams()):  # noqa: B008 (ninja query-schema idiom)
+    items, meta = await paginate_queryset(contact_form_queryset(), page)
+    return {"items": items, "meta": meta}
+
+
+@router.get("/forms/{form_id}", response=ContactFormOut)
+@require_role("admin")
+async def get_contact_form(request, form_id: uuid.UUID):
+    return await services.get_contact_form_or_404(form_id)
+
+
+@router.delete("/forms/{form_id}", response={204: None})
+@require_role("admin")
+async def delete_contact_form(request, form_id: uuid.UUID):
+    await services.delete_contact_form(request.auth, form_id)
+    return Status(204, None)
+
+
+@router.get("/", response=PagedResponse[ContactOut])
+@require_role("admin")
+async def list_contacts(request, page: PageParams = PageParams()):  # noqa: B008 (ninja query-schema idiom)
+    items, meta = await paginate_queryset(contact_queryset(), page)
+    return {"items": items, "meta": meta}
+
+
+@router.post("/", response={201: ContactOut})
+@require_role("admin")
+async def create_contact(request, payload: ContactIn):
+    contact = await services.create_contact(
+        actor=request.auth,
+        name=payload.name,
+        email=payload.email,
+        phone=payload.phone,
+        address=payload.address,
+    )
+    return Status(201, contact)
+
+
+@router.get("/{contact_id}", response=ContactOut)
+@require_role("admin")
+async def get_contact(request, contact_id: uuid.UUID):
+    return await services.get_contact_or_404(contact_id)
+
+
+@router.patch("/{contact_id}", response=ContactOut)
+@require_role("admin")
+async def update_contact(request, contact_id: uuid.UUID, payload: ContactUpdateIn):
+    return await services.update_contact(request.auth, contact_id, **payload.model_dump())
+
+
+@router.delete("/{contact_id}", response={204: None})
+@require_role("admin")
+async def delete_contact(request, contact_id: uuid.UUID):
+    await services.delete_contact(request.auth, contact_id)
+    return Status(204, None)

apps/contacts/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class ContactsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.contacts"
+    label = "contacts"
+    verbose_name = "Contacts"

apps/contacts/migrations/0001_initial.py

@@ -0,0 +1,48 @@
+# Generated by Django 5.2.17 on 2026-09-16 09:44
+
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Contact',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('name', models.CharField(max_length=150)),
+                ('email', models.EmailField(blank=True, default='', max_length=254)),
+                ('phone', models.CharField(blank=True, default='', max_length=32)),
+                ('address', models.TextField(blank=True, default='')),
+            ],
+            options={
+                'db_table': 'contacts',
+                'ordering': ['name'],
+            },
+        ),
+        migrations.CreateModel(
+            name='ContactForm',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('name', models.CharField(max_length=150)),
+                ('email', models.EmailField(max_length=254)),
+                ('phone', models.CharField(blank=True, default='', max_length=32)),
+                ('site', models.URLField(blank=True, default='')),
+                ('text', models.TextField()),
+            ],
+            options={
+                'db_table': 'contact_forms',
+                'ordering': ['-created_at'],
+            },
+        ),
+    ]

apps/contacts/models.py

@@ -0,0 +1,40 @@
+from django.db import models
+
+from apps.core.models import BaseModel
+
+
+class Contact(BaseModel):
+    """An address-book style contact record.
+
+    Distinct from `ContactForm`: this is a directly-managed entry (e.g. an
+    admin's own contact book), not something a site visitor submits.
+    """
+
+    name = models.CharField(max_length=150)
+    email = models.EmailField(blank=True, default="")
+    phone = models.CharField(max_length=32, blank=True, default="")
+    address = models.TextField(blank=True, default="")
+
+    class Meta:
+        db_table = "contacts"
+        ordering = ["name"]
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class ContactForm(BaseModel):
+    """A submission from a public "contact us" form."""
+
+    name = models.CharField(max_length=150)
+    email = models.EmailField()
+    phone = models.CharField(max_length=32, blank=True, default="")
+    site = models.URLField(blank=True, default="")
+    text = models.TextField()
+
+    class Meta:
+        db_table = "contact_forms"
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return f"{self.name} <{self.email}>"

apps/contacts/schemas.py

@@ -0,0 +1,43 @@
+import uuid
+
+from ninja import Schema
+from pydantic import EmailStr
+
+
+class ContactOut(Schema):
+    id: uuid.UUID
+    name: str
+    email: str
+    phone: str
+    address: str
+
+
+class ContactIn(Schema):
+    name: str
+    email: str = ""
+    phone: str = ""
+    address: str = ""
+
+
+class ContactUpdateIn(Schema):
+    name: str | None = None
+    email: str | None = None
+    phone: str | None = None
+    address: str | None = None
+
+
+class ContactFormOut(Schema):
+    id: uuid.UUID
+    name: str
+    email: str
+    phone: str
+    site: str
+    text: str
+
+
+class ContactFormIn(Schema):
+    name: str
+    email: EmailStr
+    phone: str = ""
+    site: str = ""
+    text: str

apps/contacts/services.py

@@ -0,0 +1,72 @@
+import uuid
+
+from apps.contacts.models import Contact, ContactForm
+from apps.core.exceptions import NotFoundError
+from apps.core.logging import log_action
+from apps.events.services import record_event
+
+
+def contact_queryset():
+    return Contact.objects.all()
+
+
+async def get_contact_or_404(contact_id: uuid.UUID) -> Contact:
+    try:
+        return await contact_queryset().aget(id=contact_id)
+    except Contact.DoesNotExist as exc:
+        raise NotFoundError("Contact not found.") from exc
+
+
+async def create_contact(actor, name: str, email: str, phone: str, address: str) -> Contact:
+    contact = Contact(name=name, email=email, phone=phone, address=address)
+    await contact.asave()
+    log_action(actor=actor.email, action="contact_created", target=contact.name)
+    await record_event(user=actor, action="create_contact", target=str(contact.id))
+    return contact
+
+
+async def update_contact(actor, contact_id: uuid.UUID, **fields) -> Contact:
+    contact = await get_contact_or_404(contact_id)
+    for field, value in fields.items():
+        if value is not None:
+            setattr(contact, field, value)
+    await contact.asave()
+    log_action(actor=actor.email, action="contact_updated", target=contact.name)
+    await record_event(user=actor, action="update_contact", target=str(contact.id))
+    return contact
+
+
+async def delete_contact(actor, contact_id: uuid.UUID) -> None:
+    contact = await get_contact_or_404(contact_id)
+    name = contact.name
+    await contact.adelete()
+    log_action(actor=actor.email, action="contact_deleted", target=name)
+    await record_event(user=actor, action="delete_contact", target=str(contact_id))
+
+
+def contact_form_queryset():
+    return ContactForm.objects.all()
+
+
+async def get_contact_form_or_404(form_id: uuid.UUID) -> ContactForm:
+    try:
+        return await contact_form_queryset().aget(id=form_id)
+    except ContactForm.DoesNotExist as exc:
+        raise NotFoundError("Contact form submission not found.") from exc
+
+
+async def submit_contact_form(name: str, email: str, phone: str, site: str, text: str) -> ContactForm:
+    form = ContactForm(name=name, email=email, phone=phone, site=site, text=text)
+    await form.asave()
+    log_action(actor="anonymous", action="contact_form_submitted", target=form.email)
+    await record_event(user=None, action="create_contact_form", target=str(form.id))
+    return form
+
+
+async def delete_contact_form(actor, form_id: uuid.UUID) -> None:
+    form = await get_contact_form_or_404(form_id)
+    email = form.email
+    form_id_str = str(form.id)
+    await form.adelete()
+    log_action(actor=actor.email, action="contact_form_deleted", target=email)
+    await record_event(user=actor, action="delete_contact_form", target=form_id_str)

apps/contacts/tests/test_contacts_api.py

@@ -0,0 +1,100 @@
+import pytest
+from asgiref.sync import sync_to_async
+from django.test import AsyncClient
+
+from apps.contacts.models import Contact, ContactForm
+from apps.users.models import User
+
+pytestmark = pytest.mark.django_db(transaction=True)
+
+
+async def _login_as(client, email, password):
+    return await client.post(
+        "/api/auth/login", data={"email": email, "password": password}, content_type="application/json"
+    )
+
+
+async def make_superuser(email="admin@example.com", password="AdminPass123"):
+    return await sync_to_async(User.objects.create_superuser)(email=email, password=password)
+
+
+async def test_anyone_can_submit_contact_form():
+    client = AsyncClient()
+    payload = {
+        "name": "Jane Visitor",
+        "email": "jane@example.com",
+        "phone": "555-0100",
+        "site": "https://example.com",
+        "text": "I'd like a quote.",
+    }
+    response = await client.post("/api/contacts/forms", data=payload, content_type="application/json")
+    assert response.status_code == 201
+    assert response.json()["email"] == "jane@example.com"
+    assert await ContactForm.objects.filter(email="jane@example.com").aexists()
+
+
+async def test_anonymous_cannot_list_contact_forms():
+    client = AsyncClient()
+    response = await client.get("/api/contacts/forms")
+    assert response.status_code == 401
+
+
+async def test_non_admin_cannot_list_contacts(default_user_role):
+    client = AsyncClient()
+    payload = {"email": "plain@example.com", "password": "StrongPass123"}
+    await client.post("/api/auth/register", data=payload, content_type="application/json")
+    await _login_as(client, **payload)
+
+    response = await client.get("/api/contacts/")
+    assert response.status_code == 403
+
+
+async def test_superuser_can_crud_contacts(default_user_role):
+    await make_superuser()
+    client = AsyncClient()
+    await _login_as(client, "admin@example.com", "AdminPass123")
+
+    create_resp = await client.post(
+        "/api/contacts/",
+        data={"name": "Acme Corp", "email": "hello@acme.test", "phone": "555-0101", "address": "1 Main St"},
+        content_type="application/json",
+    )
+    assert create_resp.status_code == 201
+    contact_id = create_resp.json()["id"]
+
+    list_resp = await client.get("/api/contacts/")
+    assert list_resp.status_code == 200
+    assert list_resp.json()["meta"]["total"] == 1
+
+    update_resp = await client.patch(
+        f"/api/contacts/{contact_id}",
+        data={"phone": "555-0199"},
+        content_type="application/json",
+    )
+    assert update_resp.status_code == 200
+    assert update_resp.json()["phone"] == "555-0199"
+
+    delete_resp = await client.delete(f"/api/contacts/{contact_id}")
+    assert delete_resp.status_code == 204
+    assert not await Contact.objects.filter(id=contact_id).aexists()
+
+
+async def test_superuser_can_review_and_delete_contact_form_submissions(default_user_role):
+    await make_superuser()
+    admin_client = AsyncClient()
+    await _login_as(admin_client, "admin@example.com", "AdminPass123")
+
+    submit_resp = await AsyncClient().post(
+        "/api/contacts/forms",
+        data={"name": "Jane Visitor", "email": "jane@example.com", "text": "Hello there."},
+        content_type="application/json",
+    )
+    form_id = submit_resp.json()["id"]
+
+    get_resp = await admin_client.get(f"/api/contacts/forms/{form_id}")
+    assert get_resp.status_code == 200
+    assert get_resp.json()["text"] == "Hello there."
+
+    delete_resp = await admin_client.delete(f"/api/contacts/forms/{form_id}")
+    assert delete_resp.status_code == 204
+    assert not await ContactForm.objects.filter(id=form_id).aexists()

apps/core/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class CoreConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.core"
+    label = "core"
+    verbose_name = "Core"

apps/core/auth.py

@@ -0,0 +1,86 @@
+"""Session-bound JWT authentication.
+
+See AGENT.md §5 for the full rationale. Short version: the client only ever
+holds an httponly session cookie. The server issues a JWT on login, stores it
+in `request.session`, and validates it there on every request — giving JWT's
+self-contained payload plus real server-side revocation via session flush.
+"""
+
+import uuid
+from datetime import datetime, timedelta, timezone
+
+import jwt
+from django.conf import settings
+from ninja.utils import check_csrf
+
+from apps.core.exceptions import AuthenticationError, PermissionDeniedError
+
+ALGORITHM = "HS256"
+
+
+def issue_token(user) -> tuple[str, str]:
+    """Create a signed JWT for `user`. Returns (token, jti)."""
+    jti = uuid.uuid4().hex
+    now = datetime.now(timezone.utc)
+    payload = {
+        "sub": str(user.pk),
+        "jti": jti,
+        "iat": now,
+        "exp": now + timedelta(minutes=settings.JWT_ACCESS_TOKEN_LIFETIME_MINUTES),
+    }
+    token = jwt.encode(payload, settings.JWT_SIGNING_KEY, algorithm=ALGORITHM)
+    return token, jti
+
+
+def decode_token(token: str) -> dict:
+    try:
+        return jwt.decode(token, settings.JWT_SIGNING_KEY, algorithms=[ALGORITHM])
+    except jwt.PyJWTError as exc:
+        raise AuthenticationError("Invalid or expired session token.") from exc
+
+
+class SessionTokenAuth:
+    """Ninja auth backend validating the JWT stored server-side in the session."""
+
+    openapi_security_schema = {
+        "type": "apiKey",
+        "in": "cookie",
+        "name": "sessionid",
+        "description": "Django session cookie, set by POST /api/auth/login.",
+    }
+
+    async def __call__(self, request):
+        # Cookie-based auth is vulnerable to CSRF unless every unsafe request
+        # proves it isn't a cross-site form/script (see AGENT.md §5, point 3).
+        if not getattr(request, "_ninja_csrf_exempt", False):
+            csrf_error = check_csrf(request)
+            if csrf_error:
+                raise PermissionDeniedError("CSRF check failed.")
+
+        # Session reads/writes must go through the async session API (aget/aset/
+        # etc.) — the sync dict-style API (`request.session["x"]`, `.get(...)`)
+        # does a synchronous DB/cache lookup on first access and raises
+        # SynchronousOnlyOperation when called from inside an async view.
+        token = await request.session.aget("auth_token")
+        if not token:
+            raise AuthenticationError("Not authenticated.")
+
+        payload = decode_token(token)
+        if payload.get("jti") != await request.session.aget("auth_token_jti"):
+            raise AuthenticationError("Session token has been revoked.")
+
+        from apps.users.models import User
+
+        try:
+            # `roles` is prefetched because handlers commonly return `request.auth`
+            # straight through a schema that serializes `.roles` — without this,
+            # that serialization would issue a synchronous query mid-async-request.
+            user = await User.objects.prefetch_related("roles").aget(pk=payload["sub"], is_active=True)
+        except User.DoesNotExist as exc:
+            raise AuthenticationError("User not found or inactive.") from exc
+
+        request.user = user
+        return user
+
+
+session_token_auth = SessionTokenAuth()

apps/core/exceptions.py

@@ -0,0 +1,80 @@
+from ninja import NinjaAPI
+from ninja.errors import ValidationError as NinjaValidationError
+
+
+class APIError(Exception):
+    """Base for all deliberately-raised API errors.
+
+    Carries an HTTP status code and a stable machine-readable `code` so
+    clients can branch on it without parsing message strings.
+    """
+
+    status_code = 400
+    code = "error"
+    default_detail = "An error occurred."
+
+    def __init__(self, detail: str | None = None):
+        self.detail = detail or self.default_detail
+        super().__init__(self.detail)
+
+
+class NotFoundError(APIError):
+    status_code = 404
+    code = "not_found"
+    default_detail = "The requested resource was not found."
+
+
+class PermissionDeniedError(APIError):
+    status_code = 403
+    code = "permission_denied"
+    default_detail = "You do not have permission to perform this action."
+
+
+class AuthenticationError(APIError):
+    status_code = 401
+    code = "authentication_failed"
+    default_detail = "Authentication credentials were not provided or are invalid."
+
+
+class ConflictError(APIError):
+    status_code = 409
+    code = "conflict"
+    default_detail = "The request conflicts with the current state of the resource."
+
+
+class ThrottledError(APIError):
+    status_code = 429
+    code = "throttled"
+    default_detail = "Too many requests. Please try again later."
+
+
+def register_exception_handlers(api: NinjaAPI) -> None:
+    @api.exception_handler(APIError)
+    def handle_api_error(request, exc: APIError):
+        return api.create_response(
+            request,
+            {"code": exc.code, "detail": exc.detail},
+            status=exc.status_code,
+        )
+
+    @api.exception_handler(NinjaValidationError)
+    def handle_validation_error(request, exc: NinjaValidationError):
+        return api.create_response(
+            request,
+            {"code": "validation_error", "detail": exc.errors},
+            status=422,
+        )
+
+    @api.exception_handler(Exception)
+    def handle_unhandled_exception(request, exc: Exception):
+        import logging
+
+        logging.getLogger("app").exception(
+            "Unhandled exception while processing request",
+            extra={"path": request.path, "method": request.method},
+        )
+        return api.create_response(
+            request,
+            {"code": "internal_error", "detail": "An unexpected error occurred."},
+            status=500,
+        )