fahd-edx-plugin 1.0.0__tar.gz

fahd_edx_plugin-1.0.0/.gitignore

@@ -0,0 +1,57 @@
+# Secrets / env
+.env
+.env.*
+!.env.example
+!.env.staging.example
+*.pem
+*.key
+
+# Live LMS tenant credentials for the seed script (real values, per-machine /
+# secrets manager). Ignore the dir CONTENTS but keep the tracked .example template
+# (must be `secrets/*` not `secrets/`, or Git can't re-include the example).
+secrets/*
+!secrets/*.example
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.coverage
+htmlcov/
+
+# uv
+.uv/
+
+# Node / Next.js (frontend/)
+node_modules/
+.next/
+out/
+.turbo/
+
+# CodeGraph local DB/cache (config is committed; the index is per-machine)
+.codegraph/*.db
+.codegraph/*.db-*
+.codegraph/cache/
+.codegraph/*.log
+.codegraph/.dirty
+
+# Eval scorecards are committed in PRs intentionally; ignore only scratch runs
+tests/eval/results/_scratch/
+
+# Local dev server logs (backend/frontend run output — per-machine, never committed)
+*.log
+
+# OS / editor
+.DS_Store
+Thumbs.db
+*.swp
+
+# NOTE: fahd-agent-v1/ is vendored reference code (its nested .git was removed; original history
+# lives at github.com/QusaiiSaleem/eduarabia-agent). It is tracked as plain files in this repo.
+
+settings.local.json

fahd_edx_plugin-1.0.0/INSTALL.md

@@ -0,0 +1,402 @@
+# Fahd for Open edX — Integration Guide
+
+> Three methods, from simplest to most integrated. Choose based on your deployment.
+
+> **v2 retarget note:** Host URLs below (`https://<your-fahd-v2-host>`) and the Tutor dev
+> default (`http://host.docker.internal:8000`) are **deployment placeholders** — set the real
+> Fahd v2 host per deployment, never hardcode it (Architecture Rule #3). The GitHub remote is
+> `tajahdev/fahd-agent`.
+
+| Method | Works On | What You Get | Requires |
+|--------|----------|-------------|----------|
+| **A: LTI 1.3** | Any edX | Fahd in course navigation | Studio UI only |
+| **B: Django Plugin** | Any edX | Floating button on every page | pip install + restart |
+| **C: Tutor Plugin** | Tutor only | Same as B + easy config management | tutor CLI |
+
+> **Distribution note:** Packages are currently installed from GitHub. PyPI publishing (`pip install fahd-edx-plugin`) is planned for the stable release.
+
+---
+
+## Emergency Rollback
+
+If Fahd breaks your LMS after installation, remove it immediately:
+
+```bash
+# Method B — remove the package and restart:
+pip uninstall fahd-edx-plugin -y
+# Then restart your LMS (tutor local restart lms / systemctl restart edxapp / kubectl rollout restart)
+
+# Method C — disable the Tutor plugin:
+tutor plugins disable fahd
+tutor images build openedx
+tutor local launch
+```
+
+Fahd is a Django middleware — removing it restores your LMS to its original state with zero side effects.
+
+---
+
+## Method A: LTI 1.3 Integration (Simplest — Any Deployment)
+
+**No CLI. No downtime. No Docker rebuild.** Done entirely through edX Studio.
+
+Fahd appears as a link in course navigation. Students click to open the AI assistant. Authentication is handled via **LTI 1.3** (signed JWT launches, not shared secrets).
+
+### Setup
+
+1. In **edX Studio** → course → **Settings** → **Advanced Settings**
+2. **LTI Passports:** add `["fahd:YOUR_KEY:YOUR_SECRET"]` _(provided by EduArabia)_
+3. **Advanced Module List:** add `"lti_consumer"` if not already there
+4. Add an **LTI Consumer** component to your course:
+   - **LTI ID:** `fahd`
+   - **LTI URL:** `https://<your-fahd-v2-host>/lti/launch`
+   - **LTI Version:** `LTI 1.3` (Fahd v2 requires real JWKS verification)
+   - **Custom Parameters:** `tenant=YOUR_TENANT_ID`
+
+> **LTI 1.3:** Fahd v2 uses signed JWTs with full JWKS verification + nonce/replay defense. Contact EduArabia for the OIDC login URL and JWKS endpoint.
+
+### Limitations
+
+- Only inside courses (not on dashboard, profile, or grades pages)
+- Must be configured per course
+- Student clicks a link (no floating button)
+
+---
+
+## Method B: Django App Plugin (Recommended — Any Deployment)
+
+**Works on Tutor, Kubernetes, native installs, managed hosting.** Just pip install and restart.
+
+Fahd's floating button appears on **every legacy (server-rendered) HTML page** — dashboard, profile, grades, course about. (MFE/React pages are out of scope — see Known Limitations.)
+
+### Step 1: Install inside your edX environment
+
+```bash
+# Pin to a specific release (recommended):
+pip install "fahd-edx-plugin @ git+https://github.com/tajahdev/fahd-agent.git@v2.0.0#subdirectory=plugins/edx"
+
+# Or latest (development only):
+pip install "git+https://github.com/tajahdev/fahd-agent.git#subdirectory=plugins/edx"
+```
+
+### Step 2: Verify installation before restarting
+
+```bash
+# Check package is installed:
+pip show fahd-edx-plugin
+
+# Check middleware is importable:
+python -c "from fahd_edx.middleware import FahdMiddleware; print('OK')"
+```
+
+If both commands succeed, the plugin is ready.
+
+### Step 3: Register your institution with Fahd
+
+Before configuring the plugin, you need to register your edX instance with the Fahd v2 server. This gives you back the `FAHD_AUTH_SECRET` and `FAHD_TENANT_ID` that the plugin needs.
+
+**3a. Create OAuth2 credentials in your edX admin:**
+
+1. Go to `https://YOUR_EDX_DOMAIN/admin/oauth2_provider/application/add/`
+2. Fill in:
+   - **Name:** `Fahd AI Assistant`
+   - **Client type:** `Confidential`
+   - **Authorization grant type:** `Client credentials`
+   - **Redirect URIs:** _(leave blank)_
+3. Save and copy the **Client ID** and **Client Secret**
+
+**3b. Register with Fahd (one-time, takes 10 seconds):**
+
+EduArabia provides the registration key. Run this command (replace the placeholders):
+
+```bash
+curl -X POST https://<your-fahd-v2-host>/api/register \
+  -H "X-Registration-Key: <provided by EduArabia>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Your University Name",
+    "platform": "edx",
+    "lms_url": "https://YOUR_EDX_DOMAIN",
+    "credentials": {
+      "client_id": "<Client ID from step 3a>",
+      "client_secret": "<Client Secret from step 3a>"
+    }
+  }'
+```
+
+**You'll get back:**
+
+```json
+{
+  "tenant_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+  "auth_secret": "kT9x2mP...",
+  "fahd_url": "https://<your-fahd-v2-host>",
+  "status": "syncing"
+}
+```
+
+Save `tenant_id` and `auth_secret` — you need them in the next step.
+
+> **Note:** In Fahd v2 the `tenant_id` is a **bare UUID** (e.g.,
+> `3f2504e0-4f89-41d3-9a0c-0305e82c3301`). Use it exactly as returned. Do NOT add a
+> `tenant:` prefix — v2 stores tenant ids as Postgres UUIDs and a prefixed value
+> fails token verification.
+
+### Step 4: Set environment variables
+
+Use the values from Step 3b:
+
+```bash
+export FAHD_URL=https://<your-fahd-v2-host>
+export FAHD_TENANT_ID=<tenant_id from Step 3b>
+export FAHD_AUTH_SECRET=<auth_secret from Step 3b>
+```
+
+**Where to set these depends on your deployment:**
+
+| Deployment | Where to set |
+|-----------|-------------|
+| **Tutor** | Use Method C instead (easier) |
+| **Kubernetes** | Helm values or ConfigMap |
+| **Native** | `/edx/app/edxapp/edx-platform/lms/envs/private.py` |
+| **Managed hosting** | Ask your provider to set them |
+
+### Step 5: Restart LMS
+
+```bash
+# Tutor:
+tutor local restart lms
+
+# Kubernetes:
+kubectl rollout restart deployment/lms
+
+# Native:
+sudo systemctl restart edxapp
+```
+
+### Step 6: Verify
+
+Open any edX page. The floating blue button should appear in the bottom-right corner.
+
+If not, view page source (`Ctrl+U`) and search for `embed.js`.
+
+### How auto-discovery works
+
+```
+pip install fahd-edx-plugin
+    → Python registers lms.djangoapp entry point
+    → Open edX loads FahdPluginConfig (apps.py)
+    → apps.py declares plugin_app settings
+    → settings/common.py runs → appends FahdMiddleware to MIDDLEWARE
+    → settings/production.py runs → reads FAHD_* from env vars
+    → Middleware injects embed.js into every legacy HTML response
+    → No patches. No Tutor. No Docker rebuild.
+```
+
+---
+
+## Method C: Tutor Plugin (Easiest for Tutor Users)
+
+**Wraps Method B** with Tutor config management. Auto-generates the auth secret.
+
+### Step 1: Install the Tutor plugin
+
+```bash
+# Pin to a release (recommended):
+pip install "tutor-fahd @ git+https://github.com/tajahdev/fahd-agent.git@v2.0.0#subdirectory=plugins/edx/tutor-fahd"
+
+# Or latest (development only):
+pip install "git+https://github.com/tajahdev/fahd-agent.git#subdirectory=plugins/edx/tutor-fahd"
+```
+
+> You only install `tutor-fahd` here. It automatically installs `fahd-edx-plugin` inside the Docker container during the next build (Step 3).
+
+### Step 2: Register your institution
+
+Follow **Method B, Step 3** (3a + 3b) to create OAuth2 credentials and register with Fahd. You'll get back a `tenant_id` and `auth_secret`.
+
+### Step 3: Enable and configure
+
+```bash
+tutor plugins enable fahd
+tutor config save --set FAHD_URL=https://<your-fahd-v2-host>
+tutor config save --set FAHD_TENANT_ID=<tenant_id from registration>
+tutor config save --set FAHD_AUTH_SECRET=<auth_secret from registration>
+```
+
+> The Tutor wrapper's default `FAHD_URL` is `http://host.docker.internal:8000` — a
+> dev convenience that reaches a Fahd v2 server running on your host machine from
+> inside the edX container. Always override it with your real host in production.
+
+### Step 4: Build images and launch
+
+```bash
+# Build the Docker image first (installs fahd-edx-plugin inside container):
+tutor images build openedx
+
+# Then launch (restarts services with new image):
+tutor local launch
+```
+
+> **Downtime warning:** `tutor local launch` restarts all services. Expect 5-10 minutes of downtime. Schedule during a maintenance window.
+
+---
+
+## Updating
+
+### Method B (Django Plugin)
+
+```bash
+pip install --upgrade "fahd-edx-plugin @ git+https://github.com/tajahdev/fahd-agent.git@v2.1.0#subdirectory=plugins/edx"
+# Restart LMS (no Docker rebuild needed)
+```
+
+### Method C (Tutor Plugin)
+
+```bash
+pip install --upgrade "tutor-fahd @ git+https://github.com/tajahdev/fahd-agent.git@v2.1.0#subdirectory=plugins/edx/tutor-fahd"
+tutor images build openedx   # Rebuild image with updated fahd-edx-plugin
+tutor local launch            # Restart with new image
+```
+
+### Method A (LTI)
+
+No updates needed on your side. The Fahd server updates independently.
+
+> **Always pin to a version tag** (`@v2.0.0`) in production. Never install from `main` branch on a live LMS.
+
+---
+
+## Post-Install Testing Checklist
+
+Run these tests after installation to confirm everything works. Takes ~5 minutes.
+
+### Test 1: Plugin is installed
+
+```bash
+pip show fahd-edx-plugin
+# Expected: Name: fahd-edx-plugin
+
+python -c "from fahd_edx.middleware import FahdMiddleware; print('OK')"
+# Expected: OK
+```
+
+### Test 2: Floating button appears (admin account)
+
+1. Log in as **admin** to your edX LMS
+2. Go to the **Dashboard** page
+3. Look for a floating blue circle button in the bottom-right corner
+
+**If no button:** View page source (`Ctrl+U`), search for `embed.js`.
+
+### Test 3: Token has correct fields
+
+1. View page source on any logged-in page
+2. Find the `<script src="...embed.js" data-token="...">` tag
+3. Copy the `data-token` value (everything before the dot)
+4. Decode it:
+
+```bash
+echo "<paste the part BEFORE the dot>" | python3 -c "
+import base64, json, sys
+token_part = sys.stdin.read().strip()
+payload = json.loads(base64.urlsafe_b64decode(token_part + '=='))
+print(json.dumps(payload, indent=2, ensure_ascii=False))
+"
+```
+
+**Expected fields:**
+```json
+{
+  "cid": "",                          ← empty on dashboard, course ID on course pages
+  "cname": "",
+  "exp": 1710600000,                 ← ~1 hour in the future
+  "iat": 1710596400,                 ← current timestamp
+  "lang": "ar",
+  "platform": "edx",
+  "roles": ["admin"],                ← matches your role
+  "tid": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",  ← your tenant UUID (BARE — no "tenant:" prefix)
+  "uid": "2"                          ← your edX user ID
+}
+```
+
+### Test 4: Student sees their own context
+
+Log in as a **student**, decode the token, and confirm `roles` shows `["student"]`.
+
+### Test 5: Anonymous users don't see Fahd
+
+Open an incognito window on the login page — there should be **no** `embed.js` script tag.
+
+### Test 6: Chat works
+
+Log in, click the floating button, send a message. Fahd should respond.
+
+**If chat shows "401" or "unauthorized":** The `FAHD_AUTH_SECRET` doesn't match what registration returned.
+
+### Test 7: Course context detected
+
+Navigate to a course page and confirm `cid` now contains the course ID (e.g., `course-v1:Org+Course+Run`).
+
+---
+
+## Troubleshooting
+
+### Chat shows 401 error
+
+`FAHD_AUTH_SECRET` mismatch. The value in your edX plugin must exactly match what the registration API returned.
+
+- **Method B:** Check: `echo $FAHD_AUTH_SECRET`
+- **Method C:** Check: `tutor config printvalue FAHD_AUTH_SECRET`
+
+### Fahd server is down — does it affect edX?
+
+**No.** The script loads with `defer` (non-blocking). If the Fahd server is unreachable, the button appears grayed out. The middleware adds ~1ms overhead (string replacement only, zero network calls).
+
+---
+
+## Known Limitations
+
+### MFE (React) pages not covered — Phase 2 / out of scope
+
+The middleware only injects `embed.js` into **server-rendered Django (legacy) pages**
+(dashboard, profile, grades, course about, admin). It does **NOT** appear on **MFE
+React pages** (Learning MFE, Studio MFE, Discussions MFE, etc.) — those are separate
+React apps served as static files that Django middleware cannot reach.
+
+MFE coverage via Frontend Plugin Slots is **phase-2 / out of scope** for this port.
+The middleware deliberately only touches `text/html` responses; JSON / MFE responses
+pass through untouched (there is a test for this:
+`tests/integration/test_edx_token_verifies_on_v2.py::test_json_response_not_modified`).
+
+**What's covered now:** Dashboard, Profile, Grades, Account Settings, Course About,
+Admin pages, any server-rendered page.
+
+**What's NOT covered:** Learning MFE (courseware), Studio MFE, Discussions MFE.
+
+> For in-course access, use **Method A (LTI)** alongside Method B.
+
+---
+
+## Privacy & Data
+
+The middleware generates a signed token containing only:
+
+| Field | Value | Example |
+|-------|-------|---------|
+| `uid` | edX user ID | `42` |
+| `roles` | Role in current context | `["student"]` |
+| `tid` | Tenant UUID (bare) | `3f2504e0-4f89-41d3-9a0c-0305e82c3301` |
+| `cid` | Course ID (if in a course) | `course-v1:KSU+CS101+2026` |
+| `lang` | Interface language | `ar` |
+| `platform` | Always "edx" | `edx` |
+| `exp` | Token expiry (1 hour) | `1710600000` |
+
+**No passwords, emails, or personal information** are included in the token.
+
+---
+
+## Support
+
+- **Email:** support@eduarabia.com
+- **Documentation:** https://docs.eduarabia.com/fahd

fahd_edx_plugin-1.0.0/PKG-INFO

@@ -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/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_plugin-1.0.0/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_plugin-1.0.0/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_plugin-1.0.0/fahd_edx/settings/__init__.py

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

fahd_edx_plugin-1.0.0/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_plugin-1.0.0/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/pyproject.toml

@@ -0,0 +1,35 @@
+# ============================================================
+# fahd-edx-plugin — Django App Plugin for Open edX
+#
+# THE MAIN PACKAGE. Works on ANY edX deployment:
+# Tutor, Kubernetes, native, managed hosting.
+#
+# INSTALL:
+#   pip install fahd-edx-plugin
+#   # Set env vars: FAHD_URL, FAHD_TENANT_ID, FAHD_AUTH_SECRET
+#   # Restart LMS → Fahd appears on every page
+#
+# HOW IT WORKS:
+#   Open edX discovers this via lms.djangoapp entry point.
+#   apps.py → settings/common.py → appends middleware → done.
+# ============================================================
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fahd-edx-plugin"
+version = "1.0.0"
+description = "Fahd AI assistant for Open edX — floating chat on every page"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.entry-points."lms.djangoapp"]
+fahd_edx = "fahd_edx.apps:FahdPluginConfig"
+
+[project.entry-points."cms.djangoapp"]
+fahd_edx = "fahd_edx.apps:FahdPluginConfig"
+
+[tool.hatch.build.targets.wheel]
+packages = ["fahd_edx"]

fahd_edx_plugin-1.0.0/tutor-fahd/pyproject.toml

@@ -0,0 +1,31 @@
+# ============================================================
+# tutor-fahd — Optional Tutor wrapper for Fahd
+#
+# For Tutor users who want easy config management.
+# The actual plugin logic is in fahd-edx-plugin (separate package).
+#
+# INSTALL:
+#   pip install tutor-fahd
+#   tutor plugins enable fahd
+#   tutor config save --set FAHD_URL=https://fahd.eduarabia.com
+#   tutor local launch
+# ============================================================
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tutor-fahd"
+version = "1.0.0"
+description = "Tutor plugin wrapper for Fahd AI assistant"
+requires-python = ">=3.8"
+dependencies = [
+    "tutor>=18.0.0,<22.0.0",
+]
+
+[project.entry-points."tutor.plugin.v1"]
+fahd = "tutorfahd.plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tutorfahd"]

fahd_edx_plugin-1.0.0/tutor-fahd/tutorfahd/__init__.py

@@ -0,0 +1 @@
+"""Tutor plugin wrapper for Fahd — manages config and Docker installation."""

fahd_edx_plugin-1.0.0/tutor-fahd/tutorfahd/plugin.py

@@ -0,0 +1,87 @@
+# ============================================================
+# FILE: tutor-fahd/tutorfahd/plugin.py
+# PURPOSE: Thin Tutor wrapper — config management + pip install
+#
+# THIS IS OPTIONAL. The fahd-edx-plugin Django App Plugin works
+# without Tutor. This wrapper just makes it easier for Tutor users:
+# 1. Manages config vars (FAHD_URL, FAHD_TENANT_ID, FAHD_AUTH_SECRET)
+# 2. pip installs fahd-edx-plugin inside the Docker container
+#
+# NO settings patches needed — the Django App Plugin auto-registers
+# itself via lms.djangoapp entry points.
+#
+# PATTERN FROM: cookiecutter-tutor-plugin, tutor-mfe
+#
+# PORTED FROM fahd-agent-v1/plugins/edx/tutor-fahd/tutorfahd/plugin.py.
+# TWO v1->v2 retargets only (both are DEPLOYMENT PLACEHOLDERS — Rule #3,
+# never hardcode a real host/remote; set per deployment):
+#   (a) FAHD_URL default -> http://host.docker.internal:8000 (v2 dev host:
+#       reaches the host machine's Fahd dev server from inside the edX
+#       container).
+#   (b) pip git URL -> the v2 repo subdirectory on `tajahdev/fahd-agent`;
+#       pin a release tag per deployment.
+# The lms/cms env patches are unchanged.
+# ============================================================
+
+from tutor import hooks
+
+# ── Config defaults ──────────────────────────────────────────
+# Admins override via: tutor config save --set FAHD_URL=https://...
+
+hooks.Filters.CONFIG_DEFAULTS.add_items(
+    [
+        # v2 dev default: reach the host's Fahd dev server from the container.
+        # DEPLOYMENT PLACEHOLDER — set the real URL per deployment (Rule #3).
+        ("FAHD_URL", "http://host.docker.internal:8000"),
+        ("FAHD_TENANT_ID", "default"),
+    ]
+)
+
+# AUTH_SECRET uses CONFIG_UNIQUE — Tutor auto-generates a random
+# 24-character value. No insecure defaults.
+hooks.Filters.CONFIG_UNIQUE.add_items(
+    [
+        ("FAHD_AUTH_SECRET", "{{ 24|random_string }}"),
+    ]
+)
+
+# ── Install fahd-edx-plugin inside the Docker container ──────
+# The Django App Plugin package must exist inside the edX container
+# for auto-discovery to work. This Dockerfile patch adds it.
+#
+# The v2 repo remote is `tajahdev/fahd-agent`; pin a release tag per deployment
+# (never install from main on a live LMS) (Rule #3).
+
+hooks.Filters.ENV_PATCHES.add_item(
+    (
+        "openedx-dockerfile-post-python-requirements",
+        'RUN pip install "fahd-edx-plugin @ '
+        'git+https://github.com/tajahdev/fahd-agent.git#subdirectory=plugins/edx"',
+    )
+)
+
+# ── Pass config as environment variables ─────────────────────
+# The Django App Plugin reads FAHD_* from env vars (production.py).
+# This patch sets them in the LMS/CMS container environment.
+
+hooks.Filters.ENV_PATCHES.add_item(
+    (
+        "openedx-lms-common-settings",
+        """
+FAHD_URL = "{{ FAHD_URL }}"
+FAHD_TENANT_ID = "{{ FAHD_TENANT_ID }}"
+FAHD_AUTH_SECRET = "{{ FAHD_AUTH_SECRET }}"
+""",
+    )
+)
+
+hooks.Filters.ENV_PATCHES.add_item(
+    (
+        "openedx-cms-common-settings",
+        """
+FAHD_URL = "{{ FAHD_URL }}"
+FAHD_TENANT_ID = "{{ FAHD_TENANT_ID }}"
+FAHD_AUTH_SECRET = "{{ FAHD_AUTH_SECRET }}"
+""",
+    )
+)