epok-auth 0.1.0__tar.gz

epok_auth-0.1.0/.env.secret.example

@@ -0,0 +1,4 @@
+# Copy this file to `.env.secret` and replace the placeholder locally.
+# `.env.secret` is ignored by Git and must never be committed.
+# The release script accepts only this variable and comments; it never executes the file as shell code.
+UV_PUBLISH_TOKEN="pypi-REPLACE_WITH_YOUR_TOKEN"

epok_auth-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,247 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: epok-auth-beta-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUNBUFFERED: "1"
+
+jobs:
+  quality:
+    name: quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 12
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          version: "0.12.1"
+          enable-cache: true
+      - run: uv python install 3.12
+      - name: Require reproducible lockfile
+        run: |
+          test -f uv.lock
+          uv lock --check
+      - name: Validate release safeguards and CLI
+        run: |
+          git check-ignore -q .env.secret
+          ! git ls-files --error-unmatch .env.secret 2>/dev/null
+          bash -n scripts/publish.sh
+          uv run scripts/publish.py --help
+      - name: Install all dependencies
+        run: uv sync --locked --all-extras --group dev --python 3.12
+      - name: Formatting
+        run: uv run ruff format --check .
+      - name: Lint and security rules
+        run: uv run ruff check .
+      - name: Strict typing
+        run: uv run pyright
+      - name: Compile all modules
+        run: uv run python -m compileall -q src tests examples/minimal scripts/publish.py
+      - name: Dependency vulnerability audit
+        run: uv run pip-audit --local --progress-spinner off
+
+  tests:
+    name: tests-py${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          version: "0.12.1"
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --locked --all-extras --group dev --python ${{ matrix.python-version }}
+      - name: Unit, HTTP and adversarial suite
+        run: uv run --python ${{ matrix.python-version }} pytest -m "not integration" -q
+
+  postgres:
+    name: postgres-17
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      TEST_DATABASE_URL: postgresql+psycopg://epok_auth:epok_auth@127.0.0.1:5432/epok_auth_test
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: epok_auth
+          POSTGRES_PASSWORD: epok_auth
+          POSTGRES_DB: epok_auth_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U epok_auth -d epok_auth_test"
+          --health-interval 2s
+          --health-timeout 3s
+          --health-retries 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          version: "0.12.1"
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --locked --all-extras --group dev --python 3.12
+      - name: Migrate from an empty database
+        run: |
+          uv run python - <<'PY'
+          import os
+          from epok_auth.migrate import upgrade_database
+
+          upgrade_database(os.environ["TEST_DATABASE_URL"])
+          PY
+      - name: Assert metadata has no migration drift
+        run: |
+          uv run python - <<'PY'
+          import os
+          from epok_auth.migrate import check_database
+
+          check_database(os.environ["TEST_DATABASE_URL"])
+          PY
+      - name: PostgreSQL integration and concurrency suite
+        run: uv run pytest -m integration -q
+
+  coverage:
+    name: coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      TEST_DATABASE_URL: postgresql+psycopg://epok_auth:epok_auth@127.0.0.1:5432/epok_auth_test
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: epok_auth
+          POSTGRES_PASSWORD: epok_auth
+          POSTGRES_DB: epok_auth_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U epok_auth -d epok_auth_test"
+          --health-interval 2s
+          --health-timeout 3s
+          --health-retries 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          version: "0.12.1"
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --locked --all-extras --group dev --python 3.12
+      - name: Migrate from an empty database
+        run: |
+          uv run python - <<'PY'
+          import os
+          from epok_auth.migrate import upgrade_database
+
+          upgrade_database(os.environ["TEST_DATABASE_URL"])
+          PY
+      - name: Enforce branch coverage across unit and PostgreSQL paths
+        run: >-
+          uv run pytest
+          --cov=epok_auth
+          --cov-branch
+          --cov-report=term-missing
+          --cov-report=xml
+          --cov-fail-under=90
+
+  package:
+    name: package
+    runs-on: ubuntu-latest
+    timeout-minutes: 18
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          version: "0.12.1"
+          enable-cache: true
+      - run: uv python install 3.12
+      - name: Build wheel and source distribution without local sources
+        run: uv build --no-sources
+      - name: Verify packaged files
+        shell: bash
+        run: |
+          set -euo pipefail
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          sdist="$(find dist -maxdepth 1 -name '*.tar.gz' -print -quit)"
+          test -n "$wheel"
+          test -n "$sdist"
+          test "$(find dist -maxdepth 1 -name '*.whl' | wc -l)" -eq 1
+          test "$(find dist -maxdepth 1 -name '*.tar.gz' | wc -l)" -eq 1
+          python -m zipfile -l "$wheel" | grep 'epok_auth/migrations/versions/0001_initial.py'
+          python -m zipfile -l "$wheel" | grep 'epok_auth/py.typed'
+          tar -tzf "$sdist" | grep 'src/epok_auth/migrations/versions/0001_initial.py'
+          tar -tzf "$sdist" | grep 'src/epok_auth/py.typed'
+      - name: Isolated wheel and sdist smoke tests
+        shell: bash
+        run: |
+          set -euo pipefail
+          expected_version="$(uv version --short)"
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          sdist="$(find dist -maxdepth 1 -name '*.tar.gz' -print -quit)"
+
+          smoke_test() {
+            artifact="$1"
+            environment="$2"
+            uv venv "$environment" --python 3.12
+            uv pip install --python "$environment/bin/python" "$artifact"
+            EPOK_AUTH_EXPECTED_VERSION="$expected_version" \
+              "$environment/bin/python" - <<'PY'
+          import os
+          from importlib.metadata import version
+
+          import epok_auth
+          from epok_auth import AuthSettings, EpokAuth
+
+          expected = os.environ["EPOK_AUTH_EXPECTED_VERSION"]
+          assert version("epok-auth") == expected
+          assert epok_auth.__version__ == expected
+          assert AuthSettings is not None
+          assert EpokAuth is not None
+          PY
+            "$environment/bin/epok-auth" --help >/dev/null
+            "$environment/bin/epok-auth" generate-secret --bytes 32 | grep -E '.{40,}'
+          }
+
+          smoke_test "$wheel" /tmp/epok-auth-wheel-smoke
+          smoke_test "$sdist" /tmp/epok-auth-sdist-smoke
+
+  merge-gate:
+    name: merge-gate
+    if: always()
+    needs: [quality, tests, postgres, coverage, package]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require every beta gate to pass
+        shell: bash
+        env:
+          QUALITY: ${{ needs.quality.result }}
+          TESTS: ${{ needs.tests.result }}
+          POSTGRES: ${{ needs.postgres.result }}
+          COVERAGE: ${{ needs.coverage.result }}
+          PACKAGE: ${{ needs.package.result }}
+        run: |
+          set -euo pipefail
+          printf '%-12s %s\n' quality "$QUALITY" tests "$TESTS" postgres "$POSTGRES" coverage "$COVERAGE" package "$PACKAGE"
+          test "$QUALITY" = success
+          test "$TESTS" = success
+          test "$POSTGRES" = success
+          test "$COVERAGE" = success
+          test "$PACKAGE" = success

epok_auth-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: github/codeql-action/init@0daab03d71ff584ef619d027a3fd9146679c5d84
+        with:
+          languages: python
+          queries: security-extended
+      - uses: github/codeql-action/analyze@0daab03d71ff584ef619d027a3fd9146679c5d84

epok_auth-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Local environments and secrets
+.env
+.env.*
+!.env.example
+!.env.secret.example
+.envrc
+.secrets/
+*credentials*.json
+*service-account*.json
+application_default_credentials.json
+adc.json
+token*.json
+*.pem
+*.key
+*.p12
+*.pfx
+*.jks
+*.keystore
+
+# Python and tooling
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.coverage
+coverage.xml
+htmlcov/
+
+# Build and local data
+dist/
+build/
+*.egg-info/
+*.sqlite
+*.sqlite3
+*.db
+*.log
+
+# Operating systems and editors
+.DS_Store
+.idea/
+.vscode/

epok_auth-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## Unreleased
+
+- replace the duplicated shell release implementation with a Rich/Typer Python orchestrator;
+- run the release CLI through isolated PEP 723 dependencies;
+- validate Python 3.12, 3.13 and 3.14 locally without replacing the project `.venv`;
+- execute PostgreSQL 17 migrations, drift, integration, concurrency and coverage locally;
+- build and smoke-test both wheel and source distribution;
+- publish, create the annotated tag and verify the public PyPI installation in one command;
+- add regression tests for `.env.secret` parsing and Docker port discovery;
+- retain `scripts/publish.sh` as a compatibility alias.
+
+## 0.1.0b1 — 2026-08-04
+
+First public beta and production-candidate foundation for the Colors integration:
+
+- local user administration;
+- Argon2id credentials with dummy verification and rehash support;
+- strict short-lived access JWTs;
+- opaque rotating refresh sessions;
+- session families, reuse detection and immediate revocation;
+- idle and absolute session deadlines;
+- CSRF correlation and Origin protection;
+- PostgreSQL-authoritative sessions and security events;
+- packaged Alembic migrations with drift checking;
+- FastAPI routers, dependencies and administrative endpoints;
+- operational CLI and Nuxt BFF reference;
+- reproducible `uv.lock` and isolated package installation;
+- single-source versioning through `pyproject.toml`, `uv version` and `importlib.metadata`;
+- guarded local publication through `uv build --no-sources` and `uv publish`;
+- ignored local PyPI credentials with repository safeguards;
+- CodeQL, dependency audit, strict typing and Ruff security rules;
+- branch-aware coverage above 90%;
+- Python 3.12, 3.13 and 3.14 validation;
+- PostgreSQL 17 integration and concurrency validation.
+
+The standalone beta is published on PyPI and tagged as `v0.1.0b1`. Colors backend/frontend parity, deployment configuration and application authorization remain required before product rollout.

epok_auth-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+All changes enter through a pull request. Direct pushes to `main` are not part of the supported workflow.
+
+Authentication, cryptography, cookie, CSRF, migration and concurrency changes require:
+
+1. a stated security invariant;
+2. a functional test;
+3. an adversarial or regression test;
+4. PostgreSQL coverage when persistence semantics change;
+5. an update to the assurance manifest when the threat model changes.
+
+Run:
+
+```bash
+uv sync --all-extras --group dev
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run pytest
+```
+
+No contribution may introduce custom cryptographic algorithms or log credential material.

epok_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EPOK
+
+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.

epok_auth-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: epok-auth
+Version: 0.1.0
+Summary: FastAPI-first authentication with PostgreSQL-authoritative, revocable sessions.
+Project-URL: Documentation, https://github.com/epok200/epok_auth/blob/main/docs/USAGE_ES.md
+Project-URL: Changelog, https://github.com/epok200/epok_auth/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/epok200/epok_auth
+Project-URL: Issues, https://github.com/epok200/epok_auth/issues
+Project-URL: Security, https://github.com/epok200/epok_auth/security/policy
+Author: EPOK
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,fastapi,jwt,postgresql,security,sessions
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: email-validator<3,>=2.2
+Requires-Dist: fastapi<1,>=0.128
+Requires-Dist: pwdlib[argon2]<0.4,>=0.3
+Requires-Dist: pydantic-settings<3,>=2.11
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: pyjwt<3,>=2.10
+Requires-Dist: typer<1,>=0.20
+Provides-Extra: all
+Requires-Dist: alembic<2,>=1.17; extra == 'all'
+Requires-Dist: greenlet<4,>=3.0; extra == 'all'
+Requires-Dist: psycopg[binary,pool]<4,>=3.2; extra == 'all'
+Requires-Dist: sqlalchemy<2.1,>=2.0.45; extra == 'all'
+Provides-Extra: postgres
+Requires-Dist: alembic<2,>=1.17; extra == 'postgres'
+Requires-Dist: greenlet<4,>=3.0; extra == 'postgres'
+Requires-Dist: psycopg[binary,pool]<4,>=3.2; extra == 'postgres'
+Requires-Dist: sqlalchemy<2.1,>=2.0.45; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# epok-auth
+
+**FastAPI-first authentication with PostgreSQL-authoritative, revocable sessions.**
+
+`epok-auth` is designed for private B2B web applications that need secure local accounts without rebuilding password handling, session rotation, revocation, CSRF protection, administration, and FastAPI dependencies for every product.
+
+> **Status:** `0.1.0b1` public beta on PyPI. The standalone library gate is green. Colors integration and application-level parity remain required before using this beta in that product. Public APIs may still change before `1.0`.
+>
+> **Practical testing:** see the Spanish step-by-step guide in [`docs/USAGE_ES.md`](docs/USAGE_ES.md).
+
+## Validated beta gate
+
+The clean beta tree is continuously validated by GitHub Actions. The current candidate has passed:
+
+| Gate | Evidence |
+|---|---|
+| Functional and adversarial tests | 101/101 passing |
+| Branch coverage | 94.80% |
+| Python compatibility | 3.12, 3.13 and 3.14 |
+| PostgreSQL | PostgreSQL 17 migration, zero Alembic drift, integration and concurrency tests |
+| Static quality | Ruff formatting/lint/security rules and Pyright strict on production source |
+| Dependencies | Reproducible `uv.lock` and `pip-audit` |
+| Distribution | Wheel and sdist build, packaged migrations, `py.typed`, isolated install and CLI smoke test |
+| Code scanning | CodeQL `security-extended` |
+
+The repository does not claim that vulnerabilities are impossible. The green gate establishes reproducible evidence for the defined beta threat model and invariants.
+
+## What the beta includes
+
+- Argon2id password hashing through `pwdlib`, with rehash support and dummy verification;
+- local users, active/disabled state, roles, scopes, administrative provisioning and reset;
+- short-lived access JWTs with strict issuer, audience, algorithm, type and time validation;
+- opaque refresh credentials stored only as SHA-256 hashes;
+- refresh rotation, session families and reuse detection;
+- immediate access revocation through authoritative PostgreSQL session state;
+- inactivity and absolute session deadlines;
+- secure cookies, CSRF correlation and strict Origin allowlists;
+- account lockout, uniform login failures and security-event persistence;
+- plug-and-play FastAPI routers and dependencies;
+- packaged Alembic migrations and an operational CLI;
+- a Nuxt/Nitro BFF reference where Vue never receives access or refresh tokens.
+
+Google OIDC, TOTP/MFA, passkeys, Redis coordination, multi-tenancy and service-to-service authentication remain outside this beta. See [ROADMAP.md](ROADMAP.md).
+
+## Installation
+
+```bash
+uv add "epok-auth[postgres]==0.1.0b1"
+```
+
+Generate a secret and configure the application:
+
+```bash
+uv run epok-auth generate-secret
+```
+
+```dotenv
+EPOK_AUTH_ENVIRONMENT=production
+EPOK_AUTH_DATABASE_URL=postgresql://colors:password@postgres/colors
+EPOK_AUTH_JWT_SECRET=<generated-secret>
+EPOK_AUTH_ISSUER=colors-auth
+EPOK_AUTH_AUDIENCE=colors-api
+EPOK_AUTH_TRUSTED_ORIGINS=https://colors.example.com
+```
+
+Production configuration is **fail-closed**: weak secrets, insecure cookies, generic issuer/audience values, missing PostgreSQL, and ambiguous origins prevent startup.
+
+## Publication
+
+The version has one source of truth in `pyproject.toml` and is exposed at runtime through `importlib.metadata`:
+
+```bash
+uv version --short
+uv version --bump beta
+uv version --bump stable
+uv version --bump patch
+```
+
+`uv version --short` prints the current project version, not the installed version of `uv`.
+
+Local PyPI credentials belong in an ignored `.env.secret` file. The complete release pipeline is a single Python command:
+
+```bash
+cp .env.secret.example .env.secret
+uv run scripts/publish.py --validate-only
+uv run scripts/publish.py --dry-run
+uv run scripts/publish.py
+```
+
+The normal command validates Python 3.12–3.14, launches disposable PostgreSQL 17, runs migrations, drift checks, integration, concurrency and coverage, builds and installs wheel/sdist, simulates the upload, publishes after an exact-version confirmation, pushes the tag and verifies the public PyPI installation.
+
+The script uses inline PEP 723 dependencies and `uv run --isolated`, so it does not replace the developer's project `.venv`. The legacy `bash scripts/publish.sh` command remains as a thin alias. See [docs/PUBLISHING.md](docs/PUBLISHING.md) for the complete procedure.
+
+## Database and initial administrator
+
+```bash
+uv run epok-auth check-config
+uv run epok-auth upgrade-db
+uv run epok-auth check-db
+uv run epok-auth create-admin
+```
+
+The first administrator is serialized transactionally. A second initial-admin creation attempt fails rather than racing.
+
+## FastAPI integration
+
+```python
+from fastapi import Depends, FastAPI
+
+from epok_auth import AuthSettings, EpokAuth, Principal
+
+settings = AuthSettings()
+auth = EpokAuth.postgres(settings=settings)
+
+app = FastAPI()
+auth.install(
+    app,
+    prefix="/api/v1/auth",
+    include_admin=True,
+)
+
+catalog = auth.protected_router(prefix="/api/v1/catalog")
+
+
+@catalog.get("")
+async def get_catalog(
+    principal: Principal = Depends(auth.authenticated),
+) -> dict[str, str]:
+    return {"viewer": principal.email}
+
+
+@catalog.post("")
+async def update_catalog(
+    principal: Principal = Depends(auth.require_scopes("catalog:write")),
+) -> dict[str, str]:
+    return {"editor": principal.email}
+
+
+app.include_router(catalog)
+```
+
+`auth.install()` exposes:
+
+```text
+POST /api/v1/auth/login
+POST /api/v1/auth/refresh
+POST /api/v1/auth/logout
+POST /api/v1/auth/change-password
+GET  /api/v1/auth/me
+```
+
+With `include_admin=True` it also exposes protected user administration under `/api/v1/auth/users`.
+
+## Application boundary
+
+`epok-auth` owns authentication capabilities:
+
+- credentials and account state;
+- sessions, rotation and revocation;
+- generic roles/scopes;
+- browser transport protections;
+- authentication audit events.
+
+The consuming product still owns:
+
+- tenants and memberships;
+- domain permissions;
+- resource-level authorization;
+- business profiles and data;
+- frontend UI and infrastructure.
+
+A role named `editor` has no meaning until Colors decides what an editor can do.
+
+## Nuxt BFF
+
+The BFF is **not implemented inside the Python library**. The repository includes a reference integration under [`examples/nuxt-bff`](examples/nuxt-bff) that demonstrates this boundary:
+
+```text
+Browser ── HttpOnly opaque session cookie ──> Nuxt/Nitro
+Nuxt/Nitro ── protected access/refresh ──> FastAPI + epok-auth
+```
+
+Vue receives only safe user/session state. Access and refresh credentials remain server-side.
+
+## Documentation
+
+- [Minimal usage and test guide in Spanish](docs/USAGE_ES.md)
+- [Publishing and versioning](docs/PUBLISHING.md)
+- [Threat model](docs/THREAT_MODEL.md)
+- [Security assurance](docs/SECURITY_ASSURANCE.md)
+- [Security policy](SECURITY.md)
+
+## Security model
+
+The beta is designed around these invariants:
+
+- knowledge of the source code does not grant access;
+- PostgreSQL is the authority for session validity;
+- refresh credentials are one-time, opaque and hashed at rest;
+- replay revokes the whole session family;
+- changing a password, disabling or locking a user revokes sessions;
+- unsafe production configuration fails before serving traffic;
+- authentication errors do not echo secrets or distinguish unknown users.
+
+## Development
+
+```bash
+uv sync --locked --all-extras --group dev
+uv run ruff format --check .
+uv run ruff check .
+uv run pyright
+uv run pytest
+```
+
+Pull requests must pass the GitHub Actions `CI / merge-gate`, including PostgreSQL 17, Python 3.12–3.14, branch coverage, dependency auditing, packaging and isolated installation. `CodeQL` must also pass.