fahd-edx-plugin 1.0.0__py3-none-any.whl

fahd_edx/__init__.py

@@ -0,0 +1,3 @@
+"""Fahd AI assistant — Django App Plugin for Open edX."""
+
+default_app_config = "fahd_edx.apps.FahdPluginConfig"

fahd_edx/apps.py

@@ -0,0 +1,53 @@
+# ============================================================
+# FILE: fahd_edx/apps.py
+# PURPOSE: Django App Plugin registration for Open edX
+#
+# HOW THIS WORKS:
+# Open edX discovers this via the lms.djangoapp / cms.djangoapp
+# entry points in pyproject.toml. At startup, it reads plugin_app
+# and auto-loads our settings (which register the middleware).
+#
+# No Tutor patches needed. No manual MIDDLEWARE.append().
+# Just: pip install fahd-edx-plugin → restart → Fahd appears.
+#
+# PATTERN FROM:
+# - github.com/openedx/sample-plugin (official reference)
+# - github.com/mitodl/open-edx-plugins (MIT production)
+# ============================================================
+
+from django.apps import AppConfig
+
+try:
+    from edx_django_utils.plugins.constants import PluginSettings
+except ImportError:
+    # Fallback if edx-django-utils is not installed (e.g., local testing).
+    # These are just string constants — the actual values don't matter
+    # as long as they match what edx-django-utils expects.
+    class PluginSettings:
+        CONFIG = "settings_config"
+        RELATIVE_PATH = "relative_path"
+
+
+class FahdPluginConfig(AppConfig):
+    """
+    Django App Plugin: Fahd AI assistant for Open edX.
+
+    Auto-discovered via lms.djangoapp / cms.djangoapp entry points.
+    Just pip install and restart — no Tutor patches needed.
+    """
+
+    name = "fahd_edx"
+    verbose_name = "Fahd AI Assistant"
+
+    plugin_app = {
+        PluginSettings.CONFIG: {
+            "lms.djangoapp": {
+                "common": {PluginSettings.RELATIVE_PATH: "settings.common"},
+                "production": {PluginSettings.RELATIVE_PATH: "settings.production"},
+            },
+            "cms.djangoapp": {
+                "common": {PluginSettings.RELATIVE_PATH: "settings.common"},
+                "production": {PluginSettings.RELATIVE_PATH: "settings.production"},
+            },
+        },
+    }

fahd_edx/middleware.py

@@ -0,0 +1,165 @@
+# ============================================================
+# FILE: fahd_edx/middleware.py
+# PURPOSE: Inject Fahd embed.js into every legacy HTML page
+#
+# COVERS: Dashboard, Grades, Course About, Profile, Admin, etc.
+# DOES NOT COVER: MFE React pages (Phase 2 — footer slot)
+#
+# HOW IT WORKS:
+# 1. Django renders an HTML response
+# 2. This middleware intercepts it
+# 3. If user is authenticated and Fahd is configured:
+#    - Extract user identity (uid, role, course)
+#    - Generate HMAC-SHA256 token (same format as Moodle/BB plugins)
+#    - Inject <script src="embed.js" data-token="..."> before </head>
+# 4. embed.js creates the floating Fahd button
+#
+# PERFORMANCE:
+# - ~1ms overhead (string replacement, no network calls)
+# - Script loads with `defer` (non-blocking)
+# - If Fahd server is down, button shows grayed out (no page impact)
+#
+# TOKEN FORMAT (must match v2 core/auth.py and PHP token_generator.php):
+# - json.dumps with ensure_ascii=False + sort_keys=True + COMPACT separators
+# - PHP equivalent: ksort() + JSON_UNESCAPED_UNICODE (compact, no spaces)
+#
+# PORTED FROM fahd-agent-v1/plugins/edx/fahd_edx/middleware.py. TWO semantic
+# changes only (see _create_token): (a) `tid` is the BARE tenant id (v1's
+# "tenant:" prefix breaks v2 auth's CAST(:tid AS uuid)); (b) compact JSON
+# separators (v1 used the default spaced separators, which were NOT byte-equal
+# to v2 core/auth.py — the latent v1 byte-equivalence bug that v2 fixed).
+# ============================================================
+
+import base64
+import hashlib
+import hmac
+import html
+import json
+import re
+import time
+
+from django.conf import settings as django_settings
+
+
+class FahdMiddleware:
+    """Inject Fahd embed.js into every HTML response."""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self.fahd_url = getattr(django_settings, "FAHD_URL", "")
+        self.tenant_id = getattr(django_settings, "FAHD_TENANT_ID", "")
+        self.auth_secret = getattr(django_settings, "FAHD_AUTH_SECRET", "")
+
+    def __call__(self, request):
+        response = self.get_response(request)
+
+        if "text/html" not in response.get("Content-Type", ""):
+            return response
+        if not hasattr(request, "user") or not request.user.is_authenticated:
+            return response
+        # Fail-closed: a misconfigured install missing the URL, signing secret, OR
+        # tenant id injects NOTHING rather than minting permanently-invalid tokens
+        # (e.g. a "default" tid that no tenant row will ever match).
+        if not self.fahd_url or not self.auth_secret or not self.tenant_id:
+            return response
+
+        user = request.user
+        course_id = self._extract_course_id(request.path)
+        role = self._detect_role(user, course_id)
+        token = self._create_token(user, role, course_id)
+
+        # XSS defense-in-depth: escape settings-sourced values placed into HTML
+        # attributes (mirrors the M5-T01 view.php s() fix). `token` is base64url and
+        # therefore already attribute-safe (its alphabet excludes <>&"'), so it is
+        # left as-is.
+        safe_url = html.escape(self.fahd_url, quote=True)
+        safe_tenant = html.escape(self.tenant_id, quote=True)
+        script = (
+            f'<script src="{safe_url}/embed.js" '
+            f'data-tenant="{safe_tenant}" '
+            f'data-token="{token}" data-lang="ar" defer></script>'
+        )
+
+        # Guard non-UTF-8 legacy pages: if the body is not valid UTF-8, pass it
+        # through unchanged (no injection) rather than 500-ing on every such page.
+        try:
+            content = response.content.decode("utf-8")
+        except UnicodeDecodeError:
+            return response
+
+        # Inject ONCE, before the FIRST `</head>` only. replace-all would also
+        # rewrite stray `</head>` occurrences inside JS strings or <pre> blocks.
+        content = content.replace("</head>", f"{script}\n</head>", 1)
+        response.content = content.encode("utf-8")
+        response["Content-Length"] = len(response.content)
+        return response
+
+    def _extract_course_id(self, path):
+        """Extract course ID from URL path if inside a course."""
+        match = re.search(r"/courses/(course-v1:[^/]+)", path)
+        return match.group(1) if match else ""
+
+    def _detect_role(self, user, course_id):
+        """Detect user's role (student/teacher/admin) in the course."""
+        if user.is_staff or user.is_superuser:
+            return "admin"
+        if course_id:
+            try:
+                from opaque_keys.edx.keys import CourseKey
+                from student.roles import CourseInstructorRole, CourseStaffRole
+
+                key = CourseKey.from_string(course_id)
+                if CourseInstructorRole(key).has_user(user) or CourseStaffRole(key).has_user(user):
+                    return "teacher"
+            except Exception:
+                # Graceful degradation (Architecture Rule #15): ANY failure here —
+                # a malformed course_id, the edX role imports being absent (e.g. when
+                # this middleware runs outside a full edX install), or a role-lookup
+                # DB error — degrades to "student". This token only carries a UI hint;
+                # the adapter's get_user_role stays the source of truth (Rule #9), so
+                # under-claiming the role here cannot grant unauthorized access.
+                pass
+        return "student"
+
+    def _create_token(self, user, role, course_id):
+        """Generate HMAC-SHA256 signed token for Fahd.
+
+        TWO v1->v2 retarget changes (the rest is verbatim from v1):
+
+        1. BARE `tid`. v1 set `tid = f"tenant:{self.tenant_id}"` (a SurrealDB
+           record-id convention). v2 auth does `CAST(:tid AS uuid)`, which raises
+           on `"tenant:<uuid>"`, so a prefixed token would fail
+           verify_token_for_tenant. We emit the bare tenant id, matching v2
+           core/auth.py and core/moodle_bridge.build_fahd_payload.
+
+        2. COMPACT separators=(",", ":"). v1 signed
+           `json.dumps(payload, ensure_ascii=False, sort_keys=True)` with the
+           DEFAULT separators (a space after every ":" and ","). PHP's
+           json_encode and v2 core/auth.py both emit COMPACT JSON (no spaces),
+           so v1's bytes — and therefore its HMAC — did NOT match. This is the
+           latent v1 byte-equivalence bug that v2 fixed; the compact separators
+           here make the inline token byte-identical to create_fahd_token.
+        """
+        now = int(time.time())
+        payload = {
+            "uid": str(user.id),
+            "roles": [role],
+            "tid": self.tenant_id,
+            "cid": course_id,
+            "cname": "",
+            "lang": "ar",
+            "platform": "edx",
+            "iat": now,
+            "exp": now + 3600,
+        }
+        # CRITICAL: must match v2 core/auth.py — ensure_ascii=False + sort_keys=True
+        # + COMPACT separators (no spaces). The separators are the load-bearing fix.
+        payload_bytes = json.dumps(
+            payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+        ).encode("utf-8")
+        sig = hmac.new(self.auth_secret.encode(), payload_bytes, hashlib.sha256).digest()
+        return (
+            base64.urlsafe_b64encode(payload_bytes).rstrip(b"=").decode()
+            + "."
+            + base64.urlsafe_b64encode(sig).rstrip(b"=").decode()
+        )

fahd_edx/settings/__init__.py

@@ -0,0 +1 @@
+"""Fahd edX plugin settings package (loaded by Open edX via apps.py plugin_app)."""

fahd_edx/settings/common.py

@@ -0,0 +1,28 @@
+# ============================================================
+# FILE: fahd_edx/settings/common.py
+# PURPOSE: Register Fahd middleware and set config defaults
+#
+# HOW THIS WORKS:
+# Open edX calls plugin_settings(settings) during startup.
+# We append our middleware to the MIDDLEWARE list and set
+# default config values. No Tutor patches needed.
+#
+# This runs for BOTH LMS and CMS (Studio).
+# ============================================================
+
+
+def plugin_settings(settings):
+    """
+    Called by Open edX during startup.
+    Appends Fahd middleware and sets config defaults.
+    """
+    # Register middleware — injects embed.js into every HTML page
+    settings.MIDDLEWARE.append("fahd_edx.middleware.FahdMiddleware")
+
+    # Config defaults (overridden by production.py or env vars)
+    settings.FAHD_URL = getattr(settings, "FAHD_URL", "http://localhost:8000")
+    # Fail-closed default: empty (not the non-UUID sentinel "default") so the
+    # middleware guard (`not self.tenant_id`) skips injection on a misconfigured
+    # install instead of minting tokens that fail server-side CAST(:tid AS uuid).
+    settings.FAHD_TENANT_ID = getattr(settings, "FAHD_TENANT_ID", "")
+    settings.FAHD_AUTH_SECRET = getattr(settings, "FAHD_AUTH_SECRET", "")

fahd_edx/settings/production.py

@@ -0,0 +1,24 @@
+# ============================================================
+# FILE: fahd_edx/settings/production.py
+# PURPOSE: Production overrides — reads config from environment
+#
+# HOW THIS WORKS:
+# Open edX calls plugin_settings(settings) AFTER common.py.
+# We override defaults with environment variables if set.
+#
+# ENVIRONMENT VARIABLES:
+#   FAHD_URL          — Fahd server URL (e.g., https://fahd.eduarabia.com)
+#   FAHD_TENANT_ID    — Institution tenant ID
+#   FAHD_AUTH_SECRET   — HMAC signing secret (must match Fahd server)
+# ============================================================
+
+import os
+
+
+def plugin_settings(settings):
+    """
+    Production overrides — reads from environment variables.
+    """
+    settings.FAHD_URL = os.environ.get("FAHD_URL", settings.FAHD_URL)
+    settings.FAHD_TENANT_ID = os.environ.get("FAHD_TENANT_ID", settings.FAHD_TENANT_ID)
+    settings.FAHD_AUTH_SECRET = os.environ.get("FAHD_AUTH_SECRET", settings.FAHD_AUTH_SECRET)

fahd_edx_plugin-1.0.0.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: fahd-edx-plugin
+Version: 1.0.0
+Summary: Fahd AI assistant for Open edX — floating chat on every page
+Requires-Python: >=3.11

fahd_edx_plugin-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fahd_edx/__init__.py,sha256=vuJ_N8J1-OdxRp5r_tMg07oZDxTWHtlk5linlF1gTQk,115
+fahd_edx/apps.py,sha256=bOOB-LJ4sLoNPD_EhKGWI9ZtBzVhWyzjEe4rxcBqsYE,1899
+fahd_edx/middleware.py,sha256=0lrzJ9u8UfHve50wt5iH8iiREZE13paYEnWsloLKkdw,7444
+fahd_edx/settings/__init__.py,sha256=Dtx-CgBO7a7Kq3THEEMfH8ll5LlHVn4hnE__sxVfNc8,84
+fahd_edx/settings/common.py,sha256=xedhZ9idOHMkAwztPHIdjYZ_WsSBcDFkuc5QtEzSjBg,1262
+fahd_edx/settings/production.py,sha256=porecd1_x619YP8ZOGPkYqDjmQAF8m7fz8pecCcLEfQ,969
+fahd_edx_plugin-1.0.0.dist-info/METADATA,sha256=ZZbBWLyj8nqW5xFYo4ArPi-hZlhh7wWyq_-yVWlDXb8,155
+fahd_edx_plugin-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fahd_edx_plugin-1.0.0.dist-info/entry_points.txt,sha256=_tXDhd853PL-TeITwepu5Ft9gsCLTKKCiH4Os0jTOIg,117
+fahd_edx_plugin-1.0.0.dist-info/RECORD,,

fahd_edx_plugin-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fahd_edx_plugin-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[cms.djangoapp]
+fahd_edx = fahd_edx.apps:FahdPluginConfig
+
+[lms.djangoapp]
+fahd_edx = fahd_edx.apps:FahdPluginConfig