django-scoped-access 0.1.0__tar.gz

django_scoped_access-0.1.0/.claude/settings.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Read(//tmp/**)",
+      "Bash(xargs -I{} echo {})"
+    ]
+  }
+}

django_scoped_access-0.1.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(DJANGO_SETTINGS_MODULE=config.settings uv run python manage.py makemigrations helpdesk)",
+      "Bash(DJANGO_SETTINGS_MODULE=config.settings uv run *)",
+      "Bash(curl *)",
+      "Bash(python3 -m json.tool)",
+      "Bash(uv add *)"
+    ]
+  }
+}

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

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Quality and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Install development tools
+        run: uv sync --group dev --group lint
+      - name: Lint
+        run: uv run --no-sync ruff check .
+      - name: Check formatting
+        run: uv run --no-sync ruff format --check scoped_access tests example
+      - name: Check migrations
+        run: DJANGO_SETTINGS_MODULE=tests.settings uv run --no-sync python -m django makemigrations --check --dry-run
+      - name: Build package
+        run: uv build
+
+  test:
+    name: Python ${{ matrix.python-version }} / Django ${{ matrix.django-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.11"
+            django-version: "4.2"
+          - python-version: "3.14"
+            django-version: "5.2"
+          - python-version: "3.14"
+            django-version: "6.0"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install with pinned Django
+        run: |
+          uv sync --group dev
+          uv pip install "Django~=${{ matrix.django-version }}.0"
+      - name: Django system checks on the test project
+        run: DJANGO_SETTINGS_MODULE=tests.settings uv run --no-sync python -m django check
+      - name: Conformance + unit tests
+        run: uv run --no-sync pytest -q

django_scoped_access-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Obligatoire pour le Trusted Publishing PyPI (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Build package distributions
+        run: uv build
+      - name: Publish package distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

django_scoped_access-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+db.sqlite3
+.DS_Store
+site/

django_scoped_access-0.1.0/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

django_scoped_access-0.1.0/.idea/amazonq.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="qAccountSettings">
+    <option name="activeRegion" value="us-east-1" />
+    <option name="recentlyUsedRegions">
+      <list>
+        <option value="us-east-1" />
+      </list>
+    </option>
+  </component>
+</project>

django_scoped_access-0.1.0/.idea/auth-with-scoped-access.iml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/example" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (auth-with-scoped-access)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="PLAIN" />
+    <option name="myDocStringFormat" value="Plain" />
+  </component>
+  <component name="TestRunnerService">
+    <option name="PROJECT_TEST_RUNNER" value="py.test" />
+  </component>
+</module>

django_scoped_access-0.1.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,13 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyPackageRequirementsInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ignoredPackages">
+        <list>
+          <option value="zenml" />
+        </list>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>

django_scoped_access-0.1.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

django_scoped_access-0.1.0/.idea/material_theme_project_new.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MaterialThemeProjectNewConfig">
+    <option name="metadata">
+      <MTProjectMetadataState>
+        <option name="userId" value="6c267aca:19f218231cd:-7fc4" />
+      </MTProjectMetadataState>
+    </option>
+  </component>
+</project>

django_scoped_access-0.1.0/.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (auth-with-scoped-access)" />
+  </component>
+</project>

django_scoped_access-0.1.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/auth-with-scoped-access.iml" filepath="$PROJECT_DIR$/.idea/auth-with-scoped-access.iml" />
+    </modules>
+  </component>
+</project>

django_scoped_access-0.1.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

django_scoped_access-0.1.0/.idea/workspace.xml

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ChangeListManager">
+    <list default="true" id="e02d799e-46e2-451b-acc9-5f9c6e9efd2d" name="Changes" comment="">
+      <change afterPath="$PROJECT_DIR$/example/helpdesk/serializers.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/scoped_access/models.py" beforeDir="false" afterPath="$PROJECT_DIR$/scoped_access/models.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/uv.lock" beforeDir="false" afterPath="$PROJECT_DIR$/uv.lock" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="FileTemplateManagerImpl">
+    <option name="RECENT_TEMPLATES">
+      <list>
+        <option value="Python Script" />
+      </list>
+    </option>
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 1,
+  "fromUser": false
+}]]></component>
+  <component name="ProjectId" id="3G4hOWJ7c1UBLfEF6SFb95bXADr" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "codeWithMe.voiceChat.enabledByDefault": "false",
+    "git-widget-placeholder": "main",
+    "last_opened_file_path": "/Users/pc/Code/Projets/perso/auth-with-scoped-access",
+    "node.js.detected.package.eslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-python-sdk-b63d5a1f7c97-b61e75351b1f-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-261.22158.340" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="e02d799e-46e2-451b-acc9-5f9c6e9efd2d" name="Changes" comment="" />
+      <created>1783236716432</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1783236716432</updated>
+      <workItem from="1783236717604" duration="5960000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

django_scoped_access-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff (uv)
+        entry: uv run --group lint -- ruff check --preview --force-exclude
+        language: system
+        types_or: [python, pyi]
+        exclude: '^(migrations/|example/migrations/)'
+      - id: ruff-format
+        name: ruff-format (uv)
+        entry: uv run --group lint -- ruff format --preview --force-exclude
+        language: system
+        types_or: [python, pyi]
+        exclude: '^(migrations/|example/migrations/)'

django_scoped_access-0.1.0/.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+python:
+  install:
+    - requirements: docs/requirements.txt
+mkdocs:
+  configuration: mkdocs.yml

django_scoped_access-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

django_scoped_access-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2026-08-20
+
+### Added
+- Reference implementation of the **Scoped Access Specification** (`SPEC.md`).
+- **Hierarchy Engine**: Declarative hierarchy configuration supporting arbitrary tree depth, parent accessors, and model discriminators.
+- **Resource Registry**: Declarative anchoring mechanism connecting domain models to hierarchy nodes.
+- **RBAC & Multi-Tenant Scoping**: Support for universal system roles and tenant-owned custom roles.
+- **Anti-Escalation (Rule R5)**: Strict checks preventing role managers from granting permissions they do not effectively hold.
+- **Assignment Lifecycle**: State machine (`ACTIVE` ⇄ `SUSPENDED` → `REVOKED`) with immutable audit trails and temporal validity (`valid_from` / `valid_until`).
+- **Step-Up Re-Authentication (ReAuth)**: Single-use, time-limited tokens with pluggable verifiers (password, PIN, TOTP, WebAuthn) and automatic invalidation on password changes.
+- **Django REST Framework (DRF) Integration**:
+  - `ScopedModelPermission`: Method-to-permission mapping with strict read-access enforcement.
+  - `ScopeObjectPermission`: Object-level scope verification.
+  - `ScopeQuerySetMixin`: Database-level SQL filtering for collection endpoints.
+  - `ScopeWriteGuardMixin`: Target-scope validation on create/update mutations to prevent scope injection.
+  - `RequireReAuth`: Gated action permission requiring a valid `X-ReAuth-Token`.
+  - `MeAccessView`: Standard `GET /me/access/` introspection endpoint.
+  - `ReAuthView`: Standard `POST /auth/reauth/` credential exchange view.
+- **Django Authentication Backend**: `ScopedPermissionBackend` integrating with `user.has_perm()` and Django Admin.
+- **Per-Request Caching**: ContextVar-backed `ScopedAccessCacheMiddleware` with in-request lifecycle invalidation.
+- **Swappable Models**: Support for customizing `Role` (`SCOPED_ACCESS_ROLE_MODEL`) and `ScopeAssignment` (`SCOPED_ACCESS_ASSIGNMENT_MODEL`).
+- **Django System Checks**: Comprehensive startup validation of hierarchy and settings consistency.
+- **Language-Agnostic Conformance Test Suite**: 100% test pass rate across 102 test cases.
+- **Complete Documentation**: Full Material for MkDocs suite with guides, tutorials, threat model, and API references.

django_scoped_access-0.1.0/LICENSE

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

django_scoped_access-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.5
+Name: django-scoped-access
+Version: 0.1.0
+Summary: RBAC + hierarchical scope-based authorization (ABAC) + step-up re-authentication for Django. Reference implementation of the Scoped Access specification.
+Project-URL: Homepage, https://github.com/joelnguemeta/django-auth-with-scoped-access
+Project-URL: Documentation, https://django-scoped-access.readthedocs.io/
+Project-URL: Repository, https://github.com/joelnguemeta/django-auth-with-scoped-access
+Project-URL: Issues, https://github.com/joelnguemeta/django-auth-with-scoped-access/issues
+Project-URL: Changelog, https://github.com/joelnguemeta/django-auth-with-scoped-access/blob/main/CHANGELOG.md
+Author: Joel Edmond Nguemeta
+License-Expression: MIT
+License-File: LICENSE
+Keywords: abac,authorization,django,hierarchical-roles,multi-tenancy,permissions,rbac,re-authentication,security,step-up-auth
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: django>=4.2
+Provides-Extra: drf
+Requires-Dist: djangorestframework>=3.14; extra == 'drf'
+Description-Content-Type: text/markdown
+
+# django-scoped-access
+
+<p align="center">
+  <a href="https://pypi.org/project/django-scoped-access/"><img src="https://img.shields.io/pypi/v/django-scoped-access.svg?color=blue" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/django-scoped-access/"><img src="https://img.shields.io/pypi/pyversions/django-scoped-access.svg" alt="Python Versions"></a>
+  <a href="https://pypi.org/project/django-scoped-access/"><img src="https://img.shields.io/pypi/djversions/django-scoped-access.svg" alt="Django Versions"></a>
+  <a href="https://django-scoped-access.readthedocs.io/"><img src="https://img.shields.io/readthedocs/django-scoped-access.svg" alt="Documentation Status"></a>
+  <a href="https://github.com/joelnguemeta/django-auth-with-scoped-access/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <strong>Hierarchical Scoped Authorization (ABAC) + RBAC + Temporal Lifecycle + Step-Up Re-Authentication for Django & DRF.</strong><br>
+  <em>Reference implementation of the <a href="SPEC.md">Scoped Access Specification</a>.</em>
+</p>
+
+---
+
+## 📖 Overview
+
+**django-scoped-access** brings fine-grained, hierarchical multi-tenant access control to Django without polluting your business models or hardcoding organizational trees into database schemas.
+
+Whether building a single-tenant app (flat RBAC), a multi-tenant B2B SaaS (Organization → Team), or a complex organizational system (National → Regional → District → Facility → Department), **the hierarchy is pure configuration**.
+
+```
+                   ┌──────────────────────────────┐
+                   │           NATIONAL           │ (Root level)
+                   └──────────────┬───────────────┘
+                                  │
+                   ┌──────────────▼──────────────┐
+                   │           REGIONAL          │
+                   └──────────────┬───────────────┘
+                                  │
+                   ┌──────────────▼──────────────┐
+                   │           DISTRICT          │
+                   └──────────────┬───────────────┘
+                                  │
+                   ┌──────────────▼──────────────┐
+                   │           FACILITY          │ (Can manage custom roles)
+                   └─────────────────────────────┘
+```
+
+---
+
+## ✨ Key Features
+
+- 🌲 **Hierarchy as Configuration, Not Schema**: Configure any arbitrary tree depth or degrade to standard RBAC at depth 0.
+- 🎯 **Domain Agnostic**: The engine never owns your models. Hierarchy nodes and role owners link via generic relations (`GenericForeignKey`).
+- 🔒 **Inclusive Downward Scope Coverage**: A role grant at `REGIONAL` covers all descendant nodes (Districts, Facilities, Units) in that subtree, and never upwards.
+- 🛡️ **Anti-Escalation Protection (Rule R5)**: Tenant admins can manage custom roles within their scope, but can **never** grant permissions they do not possess themselves.
+- ⏱️ **Temporal Validity & Audit Trail**: Assignments support `valid_from` / `valid_until` windows and status transitions (`ACTIVE` ⇄ `SUSPENDED` → `REVOKED`). Assignments are **never hard-deleted**.
+- 🔐 **Step-Up Re-Authentication (ReAuth)**: Require fresh, single-use proof of identity (passwords, PIN, WebAuthn, TOTP) for high-risk actions. Superusers are not exempt.
+- ⚡ **Database-Level Query Filtering**: SQL-level filtering (`scope_filter_q()`) for collection views—no in-memory Python iteration.
+- 🚀 **Full Django REST Framework (DRF) Integration**: Drop-in permissions (`ScopedModelPermission`, `ScopeObjectPermission`), query mixins (`ScopeQuerySetMixin`), write guards (`ScopeWriteGuardMixin`), and introspection endpoints (`GET /me/access/`).
+
+---
+
+## ⚡ Quickstart (5 Minutes)
+
+### 1. Installation
+
+```bash
+# With pip
+pip install "django-scoped-access[drf]"
+
+# With uv
+uv add "django-scoped-access[drf]"
+```
+
+### 2. Configuration (`settings.py`)
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "scoped_access",
+    "rest_framework",
+]
+
+AUTHENTICATION_BACKENDS = [
+    "django.contrib.auth.backends.ModelBackend",
+    "scoped_access.backends.ScopedPermissionBackend",
+]
+
+SCOPED_ACCESS = {
+    "HIERARCHY": [
+        {"level": "GLOBAL"},
+        {"level": "ORGANIZATION", "model": "accounts.Organization"},
+        {"level": "TEAM", "model": "accounts.Team", "parent": "organization"},
+    ],
+    "ROLE_OWNER_LEVELS": ["ORGANIZATION"],
+    "GRANTABLE_PERMISSIONS": "self",
+    "REAUTH": {"ENABLED": True, "TTL": 300},
+}
+```
+
+Apply database migrations:
+
+```bash
+python manage.py migrate
+```
+
+### 3. Register Resource Anchors
+
+Declare the path from your business models to their hierarchy node:
+
+```python
+# helpdesk/apps.py
+from django.apps import AppConfig
+
+class HelpdeskConfig(AppConfig):
+    name = "helpdesk"
+
+    def ready(self):
+        from scoped_access import register
+        from helpdesk.models import Ticket
+
+        # A Ticket is anchored to a Team
+        register(Ticket, anchor="team")
+```
+
+### 4. Create Roles & Grant Assignments
+
+```python
+from scoped_access import RoleService, ScopeAssignment
+from helpdesk.models import Team
+
+support_team = Team.objects.get(name="Support")
+
+# 1. Create a System Role
+agent_role = RoleService.create(
+    name="Support Agent",
+    permissions=[view_ticket_perm, change_ticket_perm],
+    by=admin_user,
+)
+
+# 2. Grant the role to Alice at the Team scope
+ScopeAssignment.objects.grant(
+    user=alice,
+    role=agent_role,
+    scope=support_team,
+    by=admin_user,
+)
+```
+
+### 5. Protect DRF Endpoints
+
+```python
+# helpdesk/views.py
+from rest_framework.viewsets import ModelViewSet
+from scoped_access.drf import (
+    RequireReAuth,
+    ScopedModelPermission,
+    ScopeObjectPermission,
+    ScopeQuerySetMixin,
+    ScopeWriteGuardMixin,
+)
+
+class TicketViewSet(ScopeWriteGuardMixin, ScopeQuerySetMixin, ModelViewSet):
+    queryset = Ticket.objects.all()
+    serializer_class = TicketSerializer
+    permission_classes = [ScopedModelPermission, ScopeObjectPermission]
+
+    def get_permissions(self):
+        permissions = super().get_permissions()
+        if self.action == "destroy":
+            # Deleting tickets requires Step-Up Re-Authentication
+            permissions.append(RequireReAuth())
+        return permissions
+```
+
+---
+
+## 🔍 Introspection Endpoint (`GET /me/access/`)
+
+Wire the standard introspection and reauth views in `urls.py`:
+
+```python
+from django.urls import path
+from scoped_access.drf import MeAccessView, ReAuthView
+
+urlpatterns = [
+    path("api/me/access/", MeAccessView.as_view(), name="me-access"),
+    path("api/auth/reauth/", ReAuthView.as_view(), name="reauth"),
+]
+```
+
+Example JSON output from `GET /api/me/access/`:
+
+```json
+{
+  "principal": {"id": "42", "superuser": false, "active": true},
+  "permissions": ["helpdesk.view_ticket", "helpdesk.change_ticket"],
+  "assignments": [
+    {
+      "role": {"id": "7", "name": "Support Agent", "system": true},
+      "level": "TEAM",
+      "scope": {"id": "12", "label": "Customer Support — Acme Corp"},
+      "status": "ACTIVE",
+      "valid_until": null,
+      "permissions": ["helpdesk.view_ticket", "helpdesk.change_ticket"]
+    }
+  ]
+}
+```
+
+---
+
+## 🧪 Testing & Conformance
+
+Django Scoped Access is verified against a language-agnostic test suite defined in [SPEC.md](SPEC.md) and [`conformance/`](conformance/):
+
+```bash
+uv run pytest
+```
+
+---
+
+## 📚 Documentation
+
+Complete documentation is available at [https://django-scoped-access.readthedocs.io/](https://django-scoped-access.readthedocs.io/):
+
+- [Quickstart Guide](https://django-scoped-access.readthedocs.io/quickstart/)
+- [Core Concepts & Architecture](https://django-scoped-access.readthedocs.io/concepts/)
+- [Configuration Reference](https://django-scoped-access.readthedocs.io/configuration/)
+- [Django REST Framework (DRF) Integration](https://django-scoped-access.readthedocs.io/drf/)
+- [Step-Up Re-Authentication (ReAuth)](https://django-scoped-access.readthedocs.io/reauth/)
+- [Lifecycle & Auditability](https://django-scoped-access.readthedocs.io/lifecycle/)
+- [Security Guide & Threat Model](https://django-scoped-access.readthedocs.io/security/)
+- [Formal Specification (SPEC)](https://django-scoped-access.readthedocs.io/spec/)
+
+---
+
+## 📄 License
+
+This project is licensed under the terms of the [MIT License](LICENSE).