tetframework · ztane · Jan 9, 2025 · Jan 14, 2025 · Jan 14, 2025 · Jan 16, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -10,26 +10,49 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    # 3.15 is an unreleased nightly; allow it to fail without breaking the build.
+    continue-on-error: ${{ endsWith(matrix.python-version, '-dev') }}
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: test_tet
+          POSTGRES_PASSWORD: test_tet
+          POSTGRES_DB: test_tet
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
     strategy:
       matrix:
         python-version:
-          - "3.8"
-          - "3.9"
           - "3.10"
           - "3.11"
           - "3.12"
           - "3.13"
           - "3.14"
+          - "3.15-dev"
     steps:
       - name: Checkout
         uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
       - name: Install dependencies
-        run: pip install -e '.[dev]'
-      - name: Run tests
-        run: pytest
+        run: |
+          pip install 'setuptools<82'
+          pip install -e '.[dev]'
+      - name: Run tests with coverage
+        run: |
+          pytest --cov=tet --cov-report=term-missing --cov-report=xml:coverage.xml -v
+      - name: Coverage summary
+        if: always()
+        run: |
+          echo "## Test Coverage" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          python -m coverage report --skip-covered --skip-empty >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
 
   # Publishing to PyPI is handled by release.yml (OIDC trusted publishing).
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,10 +1,9 @@
 repos:
-  # Python formatting and linting
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.4
+    rev: v0.9.3  # Use the latest stable version
     hooks:
       - id: ruff
-        args: [--fix]
+        args: [--fix]  # Automatically fix lint errors
       - id: ruff-format
 
   # reStructuredText checking

diff --git a/CHANGES.md b/CHANGES.md
@@ -1,6 +1,25 @@
 # Changes
 
 
+2026-06-17  Antti Haapala  <antti.haapala@anttipatterns.com>
+
+    * 0.6a2: Add ``tet.security`` module with JWT-based authentication,
+      refresh tokens, TOTP multi-factor authentication, login rate limiting,
+      password management, and Pyramid security policy integration.
+      Installable via the ``tet[security]`` extra.
+    * New SQLAlchemy model mixins: ``TokenMixin``,
+      ``MultiFactorAuthenticationMethodMixin``, ``TOTPUsedCodeMixin``,
+      ``RateLimitAttemptMixin``.
+    * Pyramid 2.0 compatibility for security/authorization imports.
+    * Auth views registered via ``config.include("tet.security.authentication")``.
+    * Event system for login, logout, password change, MFA, and token
+      revocation (``tet.security.events``).
+    * TOTP replay protection via UNLOGGED tables.
+    * Login rate limiting by client IP.
+    * Breached password checking via Have I Been Pwned API (k-anonymity).
+    * Drop Python 3.8, 3.9 support. Require Python >= 3.10.
+
+
 2026-06-16  Antti Haapala  <antti.haapala@anttipatterns.com>
 
     * 0.6a1: first 0.6 alpha. Migrated to a ``src/`` layout and replaced

diff --git a/TODO.md b/TODO.md
@@ -0,0 +1,59 @@
+# TODO
+
+## Upstream
+
+- Pyramid depends on `pkg_resources` which was removed in setuptools 82.
+  Pin `setuptools<82` until Pyramid releases a fix.
+
+## Security
+
+### TOTP replay protection — DONE
+- ~~Add an UNLOGGED PostgreSQL table to track used TOTP time steps per user~~
+- Implemented via `TOTPUsedCodeMixin` + `FOR UPDATE` on the MFA method row
+- `cleanup_used_codes()` method available for periodic cleanup
+
+### Rate limiting — DONE
+- ~~Login endpoint has no rate limiting~~
+- Implemented via `RateLimitAttemptMixin` (UNLOGGED table) + `TetRateLimitService`
+- Login endpoint rate-limited by client IP (configurable max attempts / window)
+- Rate limit records use a separate DB connection to survive transaction rollback
+- Extend to refresh, MFA, and password change endpoints as needed
+
+### Token cleanup — DONE
+- ~~No mechanism to purge expired long-term tokens~~
+- `TetTokenService.cleanup_expired_tokens()` available — call from a cron job or admin endpoint
+
+### Pyramid 2.0 compatibility — DONE
+- ~~`NO_PERMISSION_REQUIRED` still imported from `pyramid.security`~~
+- Now uses try/except compatibility import (pyramid.authorization → pyramid.security fallback)
+- CI matrix tests both Pyramid ~=1.9.0 and ~=2.0
+
+### TOTP secret encryption at rest
+- TOTP secrets are stored as plaintext in the `data` JSONB column
+- Consider encrypting with an application-level key before storing
+
+### Future rate limiting
+- Rate limit token refresh, MFA verify, and password change endpoints
+- Per-account rate limiting (in addition to per-IP)
+
+## Input validation
+- `create_long_term_token()` — validate `user_id` is not None
+- `retrieve_and_validate_token()` — validate token format before DB lookup
+- `create_short_term_jwt()` — validate user_id is JSON-serializable
+
+## Architecture
+
+### TOTP verification in PL/pgSQL (future)
+- Move TOTP verification into a PL/pgSQL function for fully atomic
+  verify + replay check + insert (requires `pgcrypto` for HMAC-SHA1)
+- Current approach (Python verify + FOR UPDATE + insert) is safe but
+  requires a round trip per step
+
+### Test infrastructure
+- Tests depend on a running PostgreSQL instance (`test_tet` database)
+- Consider testcontainers or similar for CI portability
+
+## Documentation
+- Document why `require_csrf=False` on all auth endpoints (stateless Bearer token auth)
+- Document the security model: token lifecycle, MFA flow, cookie handling
+- API endpoint documentation (beyond the existing `docs/authentication_apis.md`)
diff --git a/docs/api/modules.rst b/docs/api/modules.rst
@@ -15,8 +15,19 @@ API Reference
    tet.request
    tet.response
    tet.security
+   tet.security.auth
+   tet.security.authentication
    tet.security.authorization
+   tet.security.compat
+   tet.security.config
    tet.security.csrf
+   tet.security.events
+   tet.security.mfa
+   tet.security.models
+   tet.security.policy
+   tet.security.rate_limit
+   tet.security.tokens
+   tet.security.views
    tet.services
    tet.session
    tet.sqlalchemy

diff --git a/docs/api/tet.security.auth.rst b/docs/api/tet.security.auth.rst
@@ -0,0 +1,7 @@
+tet.security.auth module
+========================
+
+.. automodule:: tet.security.auth
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.authentication.rst b/docs/api/tet.security.authentication.rst
@@ -0,0 +1,7 @@
+tet.security.authentication module
+====================================
+
+.. automodule:: tet.security.authentication
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.authorization.rst b/docs/api/tet.security.authorization.rst
@@ -5,3 +5,4 @@ tet.security.authorization module
    :members:
    :show-inheritance:
    :undoc-members:
+   :no-index:
diff --git a/docs/api/tet.security.compat.rst b/docs/api/tet.security.compat.rst
@@ -0,0 +1,7 @@
+tet.security.compat module
+==========================
+
+.. automodule:: tet.security.compat
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.config.rst b/docs/api/tet.security.config.rst
@@ -0,0 +1,7 @@
+tet.security.config module
+==========================
+
+.. automodule:: tet.security.config
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.events.rst b/docs/api/tet.security.events.rst
@@ -0,0 +1,7 @@
+tet.security.events module
+==========================
+
+.. automodule:: tet.security.events
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.mfa.rst b/docs/api/tet.security.mfa.rst
@@ -0,0 +1,7 @@
+tet.security.mfa module
+=======================
+
+.. automodule:: tet.security.mfa
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.models.rst b/docs/api/tet.security.models.rst
@@ -0,0 +1,7 @@
+tet.security.models module
+==========================
+
+.. automodule:: tet.security.models
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.policy.rst b/docs/api/tet.security.policy.rst
@@ -0,0 +1,7 @@
+tet.security.policy module
+==========================
+
+.. automodule:: tet.security.policy
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.rate_limit.rst b/docs/api/tet.security.rate_limit.rst
@@ -0,0 +1,7 @@
+tet.security.rate_limit module
+==============================
+
+.. automodule:: tet.security.rate_limit
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.rst b/docs/api/tet.security.rst
@@ -5,3 +5,4 @@ tet.security
    :members:
    :show-inheritance:
    :undoc-members:
+   :no-index:
diff --git a/docs/api/tet.security.tokens.rst b/docs/api/tet.security.tokens.rst
@@ -0,0 +1,7 @@
+tet.security.tokens module
+==========================
+
+.. automodule:: tet.security.tokens
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/api/tet.security.views.rst b/docs/api/tet.security.views.rst
@@ -0,0 +1,7 @@
+tet.security.views module
+=========================
+
+.. automodule:: tet.security.views
+   :members:
+   :show-inheritance:
+   :undoc-members: