appmanager-server 0.3.1__tar.gz → 0.4.1__tar.gz

{appmanager_server-0.3.1 → appmanager_server-0.4.1}/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+### Added
+- **SEO capabilities**: apps can declare SEO metadata in their manifest (`seo`
+  block) which the host persists to `InstalledApp` and renders into served HTML.
+  - New `InstalledApp` SEO columns (`seo_title`, `seo_description`, `seo_keywords`,
+    `seo_canonical_url`, `seo_og_image`, `seo_robots`, `seo_json_ld`) + auto-migration.
+  - `base.html` `head_meta` block renders portal SEO (title, description, keywords,
+    canonical, OG, Twitter, robots, JSON-LD).
+  - Dispatcher middleware injects app SEO into sub-app HTML `<head>` (no duplicate
+    tags; auth apps forced to `noindex` when configured).
+  - `/robots.txt` and `/sitemap.xml` routes (sitemap lists public apps).
+  - Admin app detail page shows a read-only **SEO** panel.
+- **Admin Settings page** (`/admin/settings`) with three sections:
+  - **SEO**: master toggle, portal SEO fields, per-app override, auth noindex,
+    sitemap toggle.
+  - **Dashboard & Login**: login-required toggle, dashboard on/off, default-app
+    redirect.
+  - **Visibility**: show/hide login-required apps; adaptive button labels
+    (Login / Permission Required / Launch).
+- **Host settings store**: new `HostSetting` model + `host_settings` table and
+  `appmanager.host_settings` helpers (typed get/set with canonical defaults).
+
+---
+
+## [0.4.1] - 2026-09-09
+
+### Performance
+- **Batch admin dashboard queries**: health-log fetch for all apps is now a single
+  batched query (was 2 queries per app) and role member counts use one `GROUP BY`
+  instead of one count query per role. Dashboard health: 60 → 21 queries;
+  role counts: 4 → 1 query.
+- **Batch permissions matrix update**: the `/admin/permissions` POST handler now
+  loads existing permissions into a lookup map once instead of issuing one query
+  per user × app cell (was O(users × apps) queries). 405 → 31 queries, ~4.2×
+  faster wall-clock on 20 apps × 10 users.
+- **Bulk-insert grant-all permissions on install**: `app_installer` now inserts
+  per-user permissions in a single `bulk_insert_mappings` statement (was one
+  INSERT per user), skipping users who already have a row.
+- **Windowed health-log purge**: the CLI maintenance command keeps the latest 100
+  health logs per app with a single windowed `DELETE` (was a per-app loop of
+  row-by-row deletes).
+- **Batch admin-panel sync**: `sync_panels` loads existing panels for an app once
+  into a map instead of one query per declared panel.
+
+---
+
+## [0.4.0] - 2026-08-28
+
+### Added
+- **Automatic Sub-App Root Module Resolution**: Automatically prepends sub-app root directory (`app_dir`) to `sys.path` during dynamic module loading in `load_wsgi_app_from_path`, enabling seamless relative/module imports within sub-app packages.
+
+---
+
 ## [0.3.1] - 2026-08-28
 
 ### Fixed

{appmanager_server-0.3.1/appmanager_server.egg-info → appmanager_server-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: appmanager-server
-Version: 0.3.1
+Version: 0.4.1
 Summary: High-performance multi-tenant WSGI portal, dynamic sub-app dispatcher, and extension framework for Python/Flask.
 Author: AppManager Contributors
 License: MIT
@@ -120,6 +120,11 @@ graph LR
 - 🩺 **Automated Health Monitoring**: Sub-app health evaluation contract (`/health` endpoint or `get_health()` callable) tracked in `AppHealthLog` with one-click admin execution.
 - 📊 **In-Process Telemetry Bridge**: High-performance telemetry reporting allowing sub-apps to record events and metrics directly to the host database with zero network overhead.
 - 🔒 **Granular Role & Permissions Matrix**: Full RBAC role management and per-user permission matrix controlling access to every installed sub-app.
+- 🗄️ **Per-App Database Access**: Apps can request scoped or full access to the host database; the admin approves/denies at install and can adjust later (with optional data migration).
+- 🔐 **Read-Only Auth Access**: Apps can request a narrow read-only auth subset (login state, display name, role) — never email, id, or tokens.
+- 🔑 **Per-App API Keys**: Each installed app gets a generated API key for service-to-service auth back to the host REST API.
+- 📜 **Audit Log**: Append-only trail of install/uninstall, permission grants/revokes, config changes, and API key rotation.
+- 🚦 **Bridge Rate Limiting**: Token-bucket rate limiting on in-process telemetry/storage calls to stop one app from flooding the host.
 
 ---
 
@@ -177,6 +182,21 @@ Debug and test your sub-app locally with mock user authentication headers:
 appmanager dev analytics --port 5001 --email dev@example.com --role admin
 ```
 
+### Cryptographic Token & Secrets Generator
+
+Generate production-ready secrets (`SECRET_KEY`, `JWT_SECRET`, `AIC_TOKEN_SECRET`) or individual secure tokens:
+
+```bash
+# Generate complete set of formatted .env secrets
+appmanager generate-tokens --env
+
+# Generate a single 256-bit URL-safe token
+appmanager generate-tokens
+
+# Generate a 256-bit Hexadecimal token
+appmanager generate-tokens -f hex
+```
+
 ---
 
 ## 🛠️ Sub-App Specification (`manifest.json`)
@@ -246,6 +266,80 @@ if __name__ == "__main__":
 
 ---
 
+## 🗄️ Per-App Database Access & Permissions
+
+An app can request access to the host's shared database by declaring it in its
+manifest. On install, the admin approves or denies the request (default is
+**deny**). Permissions are stored in the `app_db_permissions` table and can be
+adjusted after install from the app's **Permissions** panel.
+
+### Manifest fields
+
+```json
+{
+  "requests_database": true,
+  "database_access_level": "scoped",
+  "database_description": "Stores user preferences in a scoped table.",
+  "requests_auth_readonly": true
+}
+```
+
+- `requests_database` — request shared DB access.
+- `database_access_level` — `"scoped"` (own table prefix / MySQL schema) or
+  `"full"` (raw host DB, trusted only).
+- `database_description` — shown to the admin at approval time.
+- `requests_auth_readonly` — request read-only access to login state, display
+  name, and role only.
+
+### Approval flow
+
+1. The install security report shows a **Permission Requests** panel.
+2. The admin chooses **Deny**, **Scoped**, or **Full** for DB access, and
+   **Deny**/**Grant** for read-only auth access.
+3. The decision is stored; the app's SDK receives an in-process engine (never
+   raw credentials) when granted, or falls back to its own local SQLite when
+   denied.
+
+### Adjusting permissions after install
+
+From the app's **Permissions** panel, the admin can change the DB scope or
+revoke auth access at any time. If the DB scope changes, the admin is asked
+whether to **migrate** the app's existing data (migration is a distinct,
+confirmable action — never automatic).
+
+### Security model
+
+- **Scoped** access hands the app a SQLAlchemy engine with its own table prefix
+  (`app_<slug>_`) or dedicated MySQL schema.
+- **Full** access hands a raw engine to the host DB and shows a prominent
+  warning at approval.
+- **Auth read-only** exposes only login state, display name, and role — never
+  email, user id, passwords, or tokens.
+- Credentials never exist as strings in app memory and are never sent over the
+  network or written to files.
+
+### Per-app API keys
+
+Each installed app gets a generated API key (stored as a secret config row).
+The SDK sends it in `X-AppManager-App-Key` to authenticate service-to-service
+calls back to the host REST API. The key is injected by the dispatcher, so the
+app never stores or manages credentials itself.
+
+### Audit log
+
+Security-relevant actions (install/uninstall, permission grants/revokes, API
+key rotation) are recorded in the `audit_log` table and viewable at
+`/admin/audit-log`.
+
+### Bridge rate limiting
+
+In-process telemetry/storage calls (`report_event`, `report_metric`) are
+rate-limited per app via a token bucket (default 100 events/min, configurable
+via `BRIDGE_RATE_LIMIT_RATE` / `BRIDGE_RATE_LIMIT_BURST` /
+`BRIDGE_RATE_LIMIT_ENABLED`).
+
+---
+
 ## 🧩 Pluggable UI Slots & Extension Hooks
 
 Extensions can inject components into host slots:

{appmanager_server-0.3.1 → appmanager_server-0.4.1}/README.md

@@ -59,6 +59,11 @@ graph LR
 - 🩺 **Automated Health Monitoring**: Sub-app health evaluation contract (`/health` endpoint or `get_health()` callable) tracked in `AppHealthLog` with one-click admin execution.
 - 📊 **In-Process Telemetry Bridge**: High-performance telemetry reporting allowing sub-apps to record events and metrics directly to the host database with zero network overhead.
 - 🔒 **Granular Role & Permissions Matrix**: Full RBAC role management and per-user permission matrix controlling access to every installed sub-app.
+- 🗄️ **Per-App Database Access**: Apps can request scoped or full access to the host database; the admin approves/denies at install and can adjust later (with optional data migration).
+- 🔐 **Read-Only Auth Access**: Apps can request a narrow read-only auth subset (login state, display name, role) — never email, id, or tokens.
+- 🔑 **Per-App API Keys**: Each installed app gets a generated API key for service-to-service auth back to the host REST API.
+- 📜 **Audit Log**: Append-only trail of install/uninstall, permission grants/revokes, config changes, and API key rotation.
+- 🚦 **Bridge Rate Limiting**: Token-bucket rate limiting on in-process telemetry/storage calls to stop one app from flooding the host.
 
 ---
 
@@ -116,6 +121,21 @@ Debug and test your sub-app locally with mock user authentication headers:
 appmanager dev analytics --port 5001 --email dev@example.com --role admin
 ```
 
+### Cryptographic Token & Secrets Generator
+
+Generate production-ready secrets (`SECRET_KEY`, `JWT_SECRET`, `AIC_TOKEN_SECRET`) or individual secure tokens:
+
+```bash
+# Generate complete set of formatted .env secrets
+appmanager generate-tokens --env
+
+# Generate a single 256-bit URL-safe token
+appmanager generate-tokens
+
+# Generate a 256-bit Hexadecimal token
+appmanager generate-tokens -f hex
+```
+
 ---
 
 ## 🛠️ Sub-App Specification (`manifest.json`)
@@ -185,6 +205,80 @@ if __name__ == "__main__":
 
 ---
 
+## 🗄️ Per-App Database Access & Permissions
+
+An app can request access to the host's shared database by declaring it in its
+manifest. On install, the admin approves or denies the request (default is
+**deny**). Permissions are stored in the `app_db_permissions` table and can be
+adjusted after install from the app's **Permissions** panel.
+
+### Manifest fields
+
+```json
+{
+  "requests_database": true,
+  "database_access_level": "scoped",
+  "database_description": "Stores user preferences in a scoped table.",
+  "requests_auth_readonly": true
+}
+```
+
+- `requests_database` — request shared DB access.
+- `database_access_level` — `"scoped"` (own table prefix / MySQL schema) or
+  `"full"` (raw host DB, trusted only).
+- `database_description` — shown to the admin at approval time.
+- `requests_auth_readonly` — request read-only access to login state, display
+  name, and role only.
+
+### Approval flow
+
+1. The install security report shows a **Permission Requests** panel.
+2. The admin chooses **Deny**, **Scoped**, or **Full** for DB access, and
+   **Deny**/**Grant** for read-only auth access.
+3. The decision is stored; the app's SDK receives an in-process engine (never
+   raw credentials) when granted, or falls back to its own local SQLite when
+   denied.
+
+### Adjusting permissions after install
+
+From the app's **Permissions** panel, the admin can change the DB scope or
+revoke auth access at any time. If the DB scope changes, the admin is asked
+whether to **migrate** the app's existing data (migration is a distinct,
+confirmable action — never automatic).
+
+### Security model
+
+- **Scoped** access hands the app a SQLAlchemy engine with its own table prefix
+  (`app_<slug>_`) or dedicated MySQL schema.
+- **Full** access hands a raw engine to the host DB and shows a prominent
+  warning at approval.
+- **Auth read-only** exposes only login state, display name, and role — never
+  email, user id, passwords, or tokens.
+- Credentials never exist as strings in app memory and are never sent over the
+  network or written to files.
+
+### Per-app API keys
+
+Each installed app gets a generated API key (stored as a secret config row).
+The SDK sends it in `X-AppManager-App-Key` to authenticate service-to-service
+calls back to the host REST API. The key is injected by the dispatcher, so the
+app never stores or manages credentials itself.
+
+### Audit log
+
+Security-relevant actions (install/uninstall, permission grants/revokes, API
+key rotation) are recorded in the `audit_log` table and viewable at
+`/admin/audit-log`.
+
+### Bridge rate limiting
+
+In-process telemetry/storage calls (`report_event`, `report_metric`) are
+rate-limited per app via a token bucket (default 100 events/min, configurable
+via `BRIDGE_RATE_LIMIT_RATE` / `BRIDGE_RATE_LIMIT_BURST` /
+`BRIDGE_RATE_LIMIT_ENABLED`).
+
+---
+
 ## 🧩 Pluggable UI Slots & Extension Hooks
 
 Extensions can inject components into host slots:

{appmanager_server-0.3.1 → appmanager_server-0.4.1}/appmanager/__init__.py

@@ -8,7 +8,7 @@ from appmanager.database import db
 from appmanager.extension import AppManager
 from appmanager.middleware import DynamicAppDispatcherMiddleware
 
-__version__ = "0.3.1"
+__version__ = "0.4.1"
 
 __all__ = [
     "AppManager",

{appmanager_server-0.3.1 → appmanager_server-0.4.1}/appmanager/admin/app_installer.py

@@ -296,6 +296,8 @@ def load_wsgi_app_from_path(app_dir: str, entry_point: str = "app:app") -> Any:
 
     mod = importlib.util.module_from_spec(spec)
     sys.modules[scoped_module_name] = mod
+    if app_dir not in sys.path:
+        sys.path.insert(0, app_dir)
     spec.loader.exec_module(mod)
 
     # Check for Flask app instance, callable create_app factory, or WSGI middleware
@@ -594,15 +596,53 @@ def stage_zip_file(
     return staging_id, scan_report, manifest
 
 
+def slug_conflict_info(
+    slug: str, new_manifest: Optional[Dict[str, Any]] = None
+) -> Optional[Dict[str, Any]]:
+    """
+    If an app with ``slug`` is already installed, returns a dict describing the
+    conflict (existing app id/name/version vs the incoming manifest's version).
+    Returns None when there is no conflict.
+    """
+    if not slug:
+        return None
+    existing = InstalledApp.query.filter_by(slug=slug).first()
+    if not existing:
+        return None
+
+    existing_version = None
+    try:
+        from appmanager.admin.registry import manifest_for
+
+        existing_version = (manifest_for(existing) or {}).get("version")
+    except Exception:
+        pass
+
+    new_version = (new_manifest or {}).get("version")
+    return {
+        "slug_conflict": True,
+        "existing_app_id": existing.id,
+        "existing_name": existing.name,
+        "existing_version": existing_version,
+        "new_version": new_version,
+        "versions_differ": (existing_version or "") != (new_version or ""),
+    }
+
+
 def finalize_staged_installation(
     staging_id: str,
     name: Optional[str] = None,
     slug: Optional[str] = None,
     entry_point: Optional[str] = None,
+    replace_existing: bool = False,
 ) -> InstalledApp:
     """
     Finalizes installation of a staged application: moves files into INSTALLED_APPS_DIR,
     installs requirements, registers in database, configures settings and permissions.
+
+    If ``replace_existing`` is True and an app with the target slug is already installed,
+    its files are atomically replaced (preserving the app record, permissions, and settings)
+    instead of raising a conflict error.
     """
     session = get_staged_session(staging_id)
     if not session:
@@ -620,10 +660,53 @@ def finalize_staged_installation(
     target_dir = os.path.join(current_app.config["INSTALLED_APPS_DIR"], final_slug)
     logger.info("Finalizing installation of staged app '%s' into '%s'", final_slug, target_dir)
 
-    if os.path.exists(target_dir):
-        if os.path.exists(staging_dir):
-            shutil.rmtree(staging_dir, ignore_errors=True)
-        raise ValueError(f"An app with slug '{final_slug}' is already installed.")
+    existing_app = InstalledApp.query.filter_by(slug=final_slug).first()
+    if os.path.exists(target_dir) or existing_app:
+        if not replace_existing:
+            if os.path.exists(staging_dir):
+                shutil.rmtree(staging_dir, ignore_errors=True)
+            raise ValueError(f"An app with slug '{final_slug}' is already installed.")
+
+        # ---- Replace existing app's files atomically (preserve record/permissions) ----
+        if not existing_app:
+            raise ValueError(
+                f"App directory for slug '{final_slug}' exists but no matching app record was found."
+            )
+        _replace_staged_files(staging_dir, target_dir)
+
+        # Refresh manifest-derived metadata on the existing record.
+        manifest = parse_manifest(target_dir) or session.get("manifest") or {}
+        if manifest.get("name"):
+            existing_app.name = manifest["name"]
+        if manifest.get("description"):
+            existing_app.description = manifest["description"]
+        if manifest.get("entry_point"):
+            existing_app.entry_point = manifest["entry_point"]
+        existing_app.set_seo(manifest.get("seo"))
+        db.session.commit()
+
+        # Clear WSGI cache and trigger reload signals.
+        if hasattr(current_app, "extensions") and "appmanager" in current_app.extensions:
+            current_app.extensions["appmanager"].clear_cache(slug=existing_app.slug)
+        try:
+            subapp_reloaded.send(None, slug=existing_app.slug)
+            subapp_updated.send(
+                None, app_slug=existing_app.slug, app_id=existing_app.id, update_type="install"
+            )
+        except Exception:
+            pass
+        try:
+            from appmanager.hooks import trigger_hook
+
+            trigger_hook(
+                "on_app_updated",
+                app_id=existing_app.id,
+                app_slug=existing_app.slug,
+                update_type="install",
+            )
+        except Exception:
+            pass
+        return existing_app
 
     # Remove staging metadata file before moving into installed_apps
     meta_path = os.path.join(staging_dir, "_staging_meta.json")
@@ -687,13 +770,55 @@ def finalize_staged_installation(
     if initial_settings:
         installed_app.set_settings(initial_settings)
 
+    # Persist declarative SEO metadata from the manifest (if any).
+    installed_app.set_seo(manifest.get("seo"))
+
     db.session.add(installed_app)
     db.session.commit()
 
+    # Create default (denied) permission rows for DB / auth-readonly requests.
+    try:
+        from appmanager.db_access import ensure_permission_rows
+
+        ensure_permission_rows(installed_app, manifest)
+    except Exception as e:
+        logger.warning("Failed to seed permission rows for '%s': %s", final_slug, e)
+
+    # Generate a per-app API key (stored as a secret config row).
+    try:
+        from appmanager.app_config import generate_app_api_key
+
+        generate_app_api_key(installed_app.id)
+    except Exception as e:
+        logger.warning("Failed to generate API key for '%s': %s", final_slug, e)
+
+    # Record the install in the audit log.
+    try:
+        from appmanager.audit import log_action
+
+        log_action(
+            "app_install",
+            actor_type="admin",
+            actor_id=getattr(installed_app, "installed_by", None),
+            app_id=installed_app.id,
+            details={"slug": final_slug, "source_type": session.get("source_type")},
+        )
+    except Exception:
+        pass
+
     users = User.query.all()
-    for u in users:
-        perm = UserAppPermission(user_id=u.id, app_id=installed_app.id, can_access=True)
-        db.session.add(perm)
+    # Bulk-insert a grant-all permission for every user (one statement instead
+    # of one INSERT per user). Skip users who already have a row for this app.
+    existing_user_ids = {
+        p.user_id for p in UserAppPermission.query.filter_by(app_id=installed_app.id).all()
+    }
+    new_perms = [
+        {"user_id": u.id, "app_id": installed_app.id, "can_access": True}
+        for u in users
+        if u.id not in existing_user_ids
+    ]
+    if new_perms:
+        db.session.bulk_insert_mappings(UserAppPermission, new_perms)
     db.session.commit()
 
     # Sync declared admin panels from the manifest
@@ -881,6 +1006,7 @@ def update_app_from_git(app_id_or_slug: Any) -> Tuple[bool, str, Dict[str, Any]]
             app_record.description = manifest["description"]
         if manifest.get("entry_point"):
             app_record.entry_point = manifest["entry_point"]
+        app_record.set_seo(manifest.get("seo"))
 
     db.session.commit()
 
@@ -913,6 +1039,46 @@ def update_app_from_git(app_id_or_slug: Any) -> Tuple[bool, str, Dict[str, Any]]
     )
 
 
+def _replace_staged_files(staging_dir: str, target_dir: str) -> None:
+    """
+    Atomically replaces the contents of ``target_dir`` with the staged files in
+    ``staging_dir``. On failure, restores the original target contents.
+    """
+    import tempfile
+
+    temp_backup_dir = None
+    try:
+        if os.path.exists(target_dir):
+            temp_backup_dir = tempfile.mkdtemp(prefix="app_backup_")
+            for item in os.listdir(target_dir):
+                shutil.move(os.path.join(target_dir, item), os.path.join(temp_backup_dir, item))
+
+        # Remove staging metadata before moving files in.
+        meta_path = os.path.join(staging_dir, "_staging_meta.json")
+        if os.path.exists(meta_path):
+            try:
+                os.remove(meta_path)
+            except Exception:
+                pass
+
+        os.makedirs(target_dir, exist_ok=True)
+        for item in os.listdir(staging_dir):
+            shutil.move(os.path.join(staging_dir, item), os.path.join(target_dir, item))
+
+        if os.path.exists(staging_dir):
+            shutil.rmtree(staging_dir, ignore_errors=True)
+        if temp_backup_dir and os.path.exists(temp_backup_dir):
+            shutil.rmtree(temp_backup_dir, ignore_errors=True)
+    except Exception as e:
+        if temp_backup_dir and os.path.exists(temp_backup_dir) and os.path.exists(target_dir):
+            shutil.rmtree(target_dir, ignore_errors=True)
+            os.makedirs(target_dir, exist_ok=True)
+            for item in os.listdir(temp_backup_dir):
+                shutil.move(os.path.join(temp_backup_dir, item), os.path.join(target_dir, item))
+            shutil.rmtree(temp_backup_dir, ignore_errors=True)
+        raise RuntimeError(f"Failed to replace application files: {e}")
+
+
 def stage_zip_replacement(
     app_id_or_slug: Any,
     zip_file_storage: Any,
@@ -1025,6 +1191,7 @@ def finalize_zip_replacement(staging_id: str) -> InstalledApp:
             app_record.description = manifest["description"]
         if manifest.get("entry_point"):
             app_record.entry_point = manifest["entry_point"]
+        app_record.set_seo(manifest.get("seo"))
 
     db.session.commit()
 
@@ -1060,6 +1227,27 @@ def uninstall_app(app_id: int) -> Tuple[bool, str]:
     if hasattr(current_app, "extensions") and "appmanager" in current_app.extensions:
         current_app.extensions["appmanager"].clear_cache(slug=slug)
 
+    # Clean up DB permissions and any scoped tables created for this app.
+    try:
+        from appmanager.db_access import cleanup_app_data
+
+        cleanup_app_data(app_record.id, slug)
+    except Exception as e:
+        logger.warning("Failed to clean up DB data for '%s': %s", slug, e)
+
+    # Record the uninstall in the audit log.
+    try:
+        from appmanager.audit import log_action
+
+        log_action(
+            "app_uninstall",
+            actor_type="admin",
+            app_id=app_id,
+            details={"slug": slug, "name": app_record.name},
+        )
+    except Exception:
+        pass
+
     db.session.delete(app_record)
     db.session.commit()
 

{appmanager_server-0.3.1 → appmanager_server-0.4.1}/appmanager/admin/registry.py

@@ -86,11 +86,14 @@ def sync_panels(app_record, manifest=None):
         ~AppAdminPanel.panel_id.in_(declared_ids) if declared_ids else True
     ).delete(synchronize_session=False)
 
+    # Load existing panels for this app once (avoids one query per declared panel).
+    existing = {p.panel_id: p for p in AppAdminPanel.query.filter_by(app_id=app_record.id).all()}
+
     for i, p in enumerate(declared):
         pid = p.get("id")
         if not pid:
             continue
-        row = AppAdminPanel.query.filter_by(app_id=app_record.id, panel_id=pid).first()
+        row = existing.get(pid)
         if not row:
             row = AppAdminPanel(app_id=app_record.id, panel_id=pid)
             db.session.add(row)