ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(ai): add attachment resolver registry
Juan Denis17a480aba083
diff --git a/backend/app/plugins_sdk/ai.py b/backend/app/plugins_sdk/ai.pyindex 4baa364f..92731ca0 100644--- a/backend/app/plugins_sdk/ai.py+++ b/backend/app/plugins_sdk/ai.py@@ -80,6 +80,18 @@ class PluginToolBinder:system prompt for pages matching *route_pattern* (fnmatch glob)."""ai_tool_registry.register_context_provider(route_pattern, func, plugin_slug=self.slug)+ def register_attachment_resolver(+ self, attachment_type: str, func: Callable[..., Any]) -> None:+ """Register ``fn(user, id) -> {label, source, observed_at, summary}``.++ Attachment types must be namespaced after the plugin slug, for example+ ``minecraft.world`` for the ``minecraft`` plugin.+ """+ from app.services.ai_attachment_registry import ai_attachment_registry+ ai_attachment_registry.register(+ attachment_type, func, plugin_slug=self.slug, replace=True,+ )+# Module-level convenience so a plugin can also register a context provider# without holding the binder (defaults to no plugin slug → cleared only globally).diff --git a/backend/app/services/ai_attachment_registry.py b/backend/app/services/ai_attachment_registry.pynew file mode 100644index 00000000..89894e9a--- /dev/null+++ b/backend/app/services/ai_attachment_registry.py@@ -0,0 +1,434 @@+"""Authorization-first context attachments for the in-panel AI assistant.++An attachment is a reference (``type`` + stable ``id``), never a client-sent+resource dump. The resolver registered for that type reloads the resource for+the current user on every turn and returns a compact allowlisted summary. This+keeps stale permissions, deleted rows, and secret-bearing model serializers out+of the model prompt.+"""+from __future__ import annotations++import json+import logging+import re+from datetime import datetime, timezone+from threading import RLock+from typing import Any, Callable++from app.utils.sensitive_data_filter import mask_payload++logger = logging.getLogger(__name__)++MAX_ATTACHMENTS = 8+MAX_CONTEXT_CHARS = 12_000+MAX_REFERENCE_ID_CHARS = 128+MAX_LABEL_CHARS = 160+_TYPE_RE = re.compile(r'^[a-z0-9][a-z0-9._-]{0,63}$')+++class AttachmentValidationError(ValueError):+ """The submitted attachment manifest is malformed or exceeds its cap."""+++class AttachmentDeniedError(PermissionError):+ """The current caller cannot read the referenced resource."""+++class AttachmentNotFoundError(LookupError):+ """The referenced resource no longer exists."""+++Resolver = Callable[[Any, str], dict]+++class AiAttachmentRegistry:+ """Type-keyed resolver registry with plugin ownership and teardown."""++ def __init__(self):+ self._resolvers: dict[str, tuple[Resolver, str | None]] = {}+ self._lock = RLock()++ def register(self, attachment_type: str, resolver: Resolver, *,+ plugin_slug: str | None = None, replace: bool = False):+ attachment_type = _clean_type(attachment_type)+ if not callable(resolver):+ raise ValueError('AI attachment resolver must be callable')+ if plugin_slug and not attachment_type.startswith(f'{plugin_slug}.'):+ raise ValueError('plugin attachment types must be namespaced by plugin slug')+ with self._lock:+ if attachment_type in self._resolvers and not replace:+ raise ValueError(+ f'AI attachment resolver for {attachment_type!r} already exists'+ )+ self._resolvers[attachment_type] = (resolver, plugin_slug)+ return resolver++ def get(self, attachment_type: str):+ with self._lock:+ entry = self._resolvers.get(attachment_type)+ return entry[0] if entry else None++ def types(self):+ with self._lock:+ return sorted(self._resolvers)++ def unregister_plugin(self, plugin_slug: str):+ with self._lock:+ doomed = [kind for kind, (_, owner) in self._resolvers.items()+ if owner == plugin_slug]+ for kind in doomed:+ self._resolvers.pop(kind, None)++ def clear(self):+ """Drop registrations. Tests only; boot registration is idempotent."""+ with self._lock:+ self._resolvers.clear()+++ai_attachment_registry = AiAttachmentRegistry()+++def normalize_references(references) -> list[dict]:+ if references in (None, []):+ return []+ if not isinstance(references, list):+ raise AttachmentValidationError('attachments must be a list')+ if len(references) > MAX_ATTACHMENTS:+ raise AttachmentValidationError(+ f'attachments may contain at most {MAX_ATTACHMENTS} items'+ )++ normalized = []+ seen = set()+ for index, reference in enumerate(references):+ if not isinstance(reference, dict):+ raise AttachmentValidationError(f'attachment {index} must be an object')+ try:+ attachment_type = _clean_type(reference.get('type'))+ except ValueError as exc:+ raise AttachmentValidationError(f'attachment {index}: {exc}') from exc+ resource_id = str(reference.get('id') or '').strip()+ if not resource_id or len(resource_id) > MAX_REFERENCE_ID_CHARS:+ raise AttachmentValidationError(+ f'attachment {index} requires an id up to {MAX_REFERENCE_ID_CHARS} characters'+ )+ key = (attachment_type, resource_id)+ if key in seen:+ continue+ seen.add(key)+ label = str(reference.get('label') or '').strip()[:MAX_LABEL_CHARS] or None+ normalized.append({'type': attachment_type, 'id': resource_id, 'label': label})+ return normalized+++def resolve_attachments(user, references, *, registry=None) -> dict:+ """Resolve references into a safe manifest, model context, and warnings."""+ registry = registry or ai_attachment_registry+ normalized = normalize_references(references)+ manifest = []+ context = []+ warnings = []+ used_chars = 0++ for reference in normalized:+ attachment_type = reference['type']+ resource_id = reference['id']+ resolver = registry.get(attachment_type)+ if resolver is None:+ warning = _warning(reference, 'unknown', 'Attachment type is not supported')+ warnings.append(warning)+ manifest.append(_manifest(reference, 'unknown'))+ _audit_resolution(user, reference, 'unknown')+ continue++ try:+ resolved = _clean_resolution(resolver(user, resource_id))+ except AttachmentDeniedError:+ warnings.append(_warning(reference, 'denied', 'Access to this attachment was denied'))+ manifest.append(_manifest(reference, 'denied'))+ _audit_resolution(user, reference, 'denied')+ continue+ except AttachmentNotFoundError:+ warnings.append(_warning(reference, 'stale', 'Attachment no longer exists'))+ manifest.append(_manifest(reference, 'stale'))+ continue+ except Exception:+ logger.exception('AI attachment resolver failed for %s', attachment_type)+ warnings.append(_warning(reference, 'unavailable', 'Attachment could not be resolved'))+ manifest.append(_manifest(reference, 'unavailable'))+ continue++ item = {+ 'type': attachment_type,+ 'id': resource_id,+ 'source': resolved['source'],+ 'label': resolved['label'],+ 'observed_at': resolved['observed_at'],+ # Even trusted core/plugin resolvers pass through unconditional+ # key-based masking before model context is assembled.+ 'summary': mask_payload(resolved['summary']),+ }+ encoded_size = len(json.dumps(item, ensure_ascii=False, default=str))+ if used_chars + encoded_size > MAX_CONTEXT_CHARS:+ warnings.append(_warning(+ reference, 'omitted', 'Attachment context limit reached',+ ))+ manifest.append(_manifest(reference, 'omitted', label=resolved['label']))+ continue+ used_chars += encoded_size+ context.append(item)+ manifest.append(_manifest(+ reference,+ 'resolved',+ label=resolved['label'],+ observed_at=resolved['observed_at'],+ source=resolved['source'],+ ))++ return {'manifest': manifest, 'context': context, 'warnings': warnings}+++def register_builtin_attachment_resolvers():+ """Register the core ResourcePicker entity types, idempotently."""+ builtins = {+ 'service': _resolve_service,+ 'server': _resolve_server,+ 'project': _resolve_project,+ 'environment': _resolve_environment,+ 'domain': _resolve_domain,+ 'incident': _resolve_incident,+ }+ for attachment_type, resolver in builtins.items():+ ai_attachment_registry.register(+ attachment_type, resolver, replace=True,+ )+++def _clean_type(value):+ attachment_type = str(value or '').strip().lower()+ if not _TYPE_RE.fullmatch(attachment_type):+ raise ValueError('attachment type is invalid')+ return attachment_type+++def _clean_resolution(resolved):+ if not isinstance(resolved, dict) or not isinstance(resolved.get('summary'), dict):+ raise ValueError('attachment resolver returned an invalid summary')+ label = str(resolved.get('label') or '').strip()[:MAX_LABEL_CHARS]+ if not label:+ raise ValueError('attachment resolver returned no label')+ return {+ 'label': label,+ 'source': str(resolved.get('source') or 'ServerKit').strip()[:80],+ 'observed_at': str(resolved.get('observed_at') or _now()),+ 'summary': resolved['summary'],+ }+++def _manifest(reference, status, *, label=None, observed_at=None, source=None):+ return {+ 'type': reference['type'],+ 'id': reference['id'],+ 'label': label or reference.get('label'),+ 'status': status,+ 'source': source,+ 'observed_at': observed_at,+ }+++def _warning(reference, status, message):+ return {+ 'type': reference['type'],+ 'id': reference['id'],+ 'status': status,+ 'message': message,+ }+++def _audit_resolution(user, reference, reason):+ """Audit identity and reason only; never record labels or resolver data."""+ try:+ from app.services.audit_service import AuditService+ AuditService.log(+ action=f'ai.attachment.{reason}',+ user_id=getattr(user, 'id', None),+ target_type='ai_attachment',+ details={'attachment_type': reference['type'], 'reason': reason},+ )+ except Exception:+ logger.warning('Failed to audit AI attachment %s', reason, exc_info=True)+++def _now():+ return datetime.now(timezone.utc).isoformat()+++def _stamp(row):+ value = getattr(row, 'updated_at', None) or getattr(row, 'created_at', None)+ return value.isoformat() if value else _now()+++def _parse_int(resource_id):+ try:+ return int(resource_id)+ except (TypeError, ValueError) as exc:+ raise AttachmentNotFoundError from exc+++def _workspace_access(user, workspace_id):+ if getattr(user, 'is_admin', False):+ return True+ if workspace_id is None:+ return False+ from app.services.workspace_service import WorkspaceService+ return WorkspaceService.get_user_role(workspace_id, user.id) is not None+++def _resolve_service(user, resource_id):+ from app.middleware.rbac import app_access_tier+ from app.models.application import Application++ row = Application.query_active().filter_by(id=_parse_int(resource_id)).first()+ if row is None:+ raise AttachmentNotFoundError+ if app_access_tier(user, row) is None:+ raise AttachmentDeniedError+ return {+ 'label': row.name,+ 'source': 'ServerKit service inventory',+ 'observed_at': _stamp(row),+ 'summary': {+ 'name': row.name,+ 'application_type': row.app_type,+ 'status': row.status,+ 'workspace_id': row.workspace_id,+ 'project_id': row.project_id,+ 'environment_id': row.environment_id,+ 'port': row.port,+ },+ }+++def _resolve_server(user, resource_id):+ from app.models.server import Server++ row = Server.query.filter_by(id=resource_id).first()+ if row is None:+ raise AttachmentNotFoundError+ # Servers are a global authenticated read surface today, matching search.+ return {+ 'label': row.name or row.hostname or resource_id,+ 'source': 'ServerKit server inventory',+ 'observed_at': _stamp(row),+ 'summary': {+ 'name': row.name,+ 'hostname': row.hostname,+ 'status': row.status,+ 'last_seen': row.last_seen.isoformat() if row.last_seen else None,+ 'operating_system': row.os_type,+ 'os_version': row.os_version,+ 'architecture': row.architecture,+ 'cpu_cores': row.cpu_cores,+ 'total_memory_bytes': row.total_memory,+ 'total_disk_bytes': row.total_disk,+ 'docker_version': row.docker_version,+ 'tags': list(row.tags or []),+ },+ }+++def _resolve_project(user, resource_id):+ from app.models.project import Project++ row = Project.query.filter_by(id=_parse_int(resource_id)).first()+ if row is None:+ raise AttachmentNotFoundError+ if not _workspace_access(user, row.workspace_id):+ raise AttachmentDeniedError+ return {+ 'label': row.name,+ 'source': 'ServerKit project inventory',+ 'observed_at': _stamp(row),+ 'summary': {+ 'name': row.name,+ 'description': (row.description or '')[:1000],+ 'workspace_id': row.workspace_id,+ 'environment_count': row.environments.count(),+ },+ }+++def _resolve_environment(user, resource_id):+ from app.models.environment import Environment++ row = Environment.query.filter_by(id=_parse_int(resource_id)).first()+ if row is None:+ raise AttachmentNotFoundError+ project = row.project+ if project is None or not _workspace_access(user, project.workspace_id):+ raise AttachmentDeniedError+ return {+ 'label': row.name,+ 'source': 'ServerKit environment inventory',+ 'observed_at': _stamp(row),+ 'summary': {+ 'name': row.name,+ 'project_id': row.project_id,+ 'project_name': project.name,+ 'workspace_id': project.workspace_id,+ 'is_default': bool(row.is_default),+ },+ }+++def _resolve_domain(user, resource_id):+ from app.middleware.rbac import app_access_tier+ from app.models.domain import Domain++ row = Domain.query_active().filter_by(id=_parse_int(resource_id)).first()+ if row is None:+ raise AttachmentNotFoundError+ if row.application is None or app_access_tier(user, row.application) is None:+ raise AttachmentDeniedError+ return {+ 'label': row.name,+ 'source': 'ServerKit domain inventory',+ 'observed_at': _stamp(row),+ 'summary': {+ 'name': row.name,+ 'application_id': row.application_id,+ 'application_name': row.application.name,+ 'is_primary': bool(row.is_primary),+ 'ssl_enabled': bool(row.ssl_enabled),+ 'ssl_expires_at': (+ row.ssl_expires_at.isoformat() if row.ssl_expires_at else None+ ),+ 'ssl_auto_renew': bool(row.ssl_auto_renew),+ },+ }+++def _resolve_incident(user, resource_id):+ from app.models.status_page import StatusIncident++ row = StatusIncident.query.filter_by(id=_parse_int(resource_id)).first()+ if row is None:+ raise AttachmentNotFoundError+ return {+ 'label': row.title,+ 'source': 'ServerKit incident ledger',+ 'observed_at': _stamp(row),+ 'summary': {+ 'title': row.title,+ 'status': row.status,+ 'impact': row.impact,+ 'is_maintenance': bool(row.is_maintenance),+ 'scheduled_start': (+ row.scheduled_start.isoformat() if row.scheduled_start else None+ ),+ 'scheduled_end': (+ row.scheduled_end.isoformat() if row.scheduled_end else None+ ),+ 'resolved_at': row.resolved_at.isoformat() if row.resolved_at else None,+ },+ }diff --git a/backend/app/services/ai_service.py b/backend/app/services/ai_service.pyindex d7636527..a69ae7d6 100644--- a/backend/app/services/ai_service.py+++ b/backend/app/services/ai_service.py@@ -162,6 +162,10 @@ def ensure_initialized() -> None:returnfrom app.services.ai_tools_builtin import register_builtin_toolsregister_builtin_tools()+ from app.services.ai_attachment_registry import (+ register_builtin_attachment_resolvers,+ )+ register_builtin_attachment_resolvers()try:ai_tool_registry.discover_plugins()except Exception:diff --git a/backend/app/services/ai_tool_registry.py b/backend/app/services/ai_tool_registry.pyindex fd29fd91..3ded15d5 100644--- a/backend/app/services/ai_tool_registry.py+++ b/backend/app/services/ai_tool_registry.py@@ -143,13 +143,15 @@ class AiToolRegistry:# Lifecycle (called by plugin_service on install/enable/disable/uninstall)# ------------------------------------------------------------------def unregister_plugin(self, slug: str) -> None:- """Drop all tools + context providers contributed by a plugin."""+ """Drop all AI contributions supplied by a plugin."""with self._mutex:for qn in self._by_plugin.pop(slug, set()):self._tools.pop(qn, None)self._context_providers = [cp for cp in self._context_providers if cp.plugin_slug != slug]+ from app.services.ai_attachment_registry import ai_attachment_registry+ ai_attachment_registry.unregister_plugin(slug)logger.info("Unregistered AI tools for plugin '%s'", slug)def reload_plugin(self, slug: str) -> None:diff --git a/backend/tests/test_ai_attachments.py b/backend/tests/test_ai_attachments.pynew file mode 100644index 00000000..163f8ab0--- /dev/null+++ b/backend/tests/test_ai_attachments.py@@ -0,0 +1,119 @@+"""Plan 80 D1 — authorization-first AI attachment resolver contract."""+import json++import pytest++from app.services.ai_attachment_registry import (+ AttachmentValidationError,+ AiAttachmentRegistry,+ MAX_ATTACHMENTS,+ ai_attachment_registry,+ normalize_references,+ register_builtin_attachment_resolvers,+ resolve_attachments,+)+++def test_reference_manifest_is_bounded_validated_and_deduplicated():+ refs = normalize_references([+ {'type': 'service', 'id': 7, 'label': 'API'},+ {'type': 'SERVICE', 'id': '7', 'label': 'duplicate'},+ ])+ assert refs == [{'type': 'service', 'id': '7', 'label': 'API'}]++ with pytest.raises(AttachmentValidationError, match='at most'):+ normalize_references([+ {'type': 'service', 'id': str(index)}+ for index in range(MAX_ATTACHMENTS + 1)+ ])+ with pytest.raises(AttachmentValidationError, match='type is invalid'):+ normalize_references([{'type': '../../secret', 'id': '1'}])+++def test_resolver_masks_sensitive_keys_and_caps_context():+ registry = AiAttachmentRegistry()+ registry.register('demo', lambda user, resource_id: {+ 'label': 'Demo resource',+ 'source': 'test fixture',+ 'observed_at': '2026-08-21T00:00:00Z',+ 'summary': {'status': 'ok', 'password': 'never-send-me'},+ })++ result = resolve_attachments(+ object(), [{'type': 'demo', 'id': 'one'}], registry=registry,+ )+ assert result['manifest'][0]['status'] == 'resolved'+ assert result['context'][0]['summary']['password'] == '[redacted]'+ assert 'never-send-me' not in json.dumps(result)++ registry.register('large', lambda user, resource_id: {+ 'label': 'Large', 'source': 'test', 'summary': {'text': 'x' * 13_000},+ })+ capped = resolve_attachments(+ object(), [{'type': 'large', 'id': 'two'}], registry=registry,+ )+ assert capped['context'] == []+ assert capped['manifest'][0]['status'] == 'omitted'+ assert capped['warnings'][0]['status'] == 'omitted'+++def test_unknown_attachment_is_audited_without_untrusted_label(app):+ from app import db+ from app.models import AuditLog+ from factories import make_user++ user = make_user(db, 'attachment_auditor')+ secret_label = 'TOKEN=should-never-enter-audit'+ result = resolve_attachments(user, [{+ 'type': 'missing.kind', 'id': '42', 'label': secret_label,+ }], registry=AiAttachmentRegistry())++ assert result['manifest'][0]['status'] == 'unknown'+ row = AuditLog.query.filter_by(action='ai.attachment.unknown').one()+ encoded = json.dumps(row.to_dict())+ assert secret_label not in encoded+ assert row.get_details() == {+ 'attachment_type': 'missing.kind', 'reason': 'unknown',+ }+++def test_service_resolver_rechecks_workspace_access(app, scoping_rbac):+ from app.models import AuditLog, User++ register_builtin_attachment_resolvers()+ owner = User.query.filter_by(username='scope_owner').one()+ viewer = User.query.filter_by(username='scope_viewer').one()+ foreign = User.query.filter_by(username='scope_foreign').one()+ reference = [{'type': 'service', 'id': str(scoping_rbac.app_id)}]++ owner_result = resolve_attachments(owner, reference)+ viewer_result = resolve_attachments(viewer, reference)+ denied_result = resolve_attachments(foreign, reference)++ assert owner_result['context'][0]['summary']['name'] == 'scope-app'+ assert viewer_result['manifest'][0]['status'] == 'resolved'+ assert denied_result['context'] == []+ assert denied_result['manifest'][0]['status'] == 'denied'+ audit = AuditLog.query.filter_by(action='ai.attachment.denied').one()+ assert audit.user_id == foreign.id+ assert audit.get_details() == {+ 'attachment_type': 'service', 'reason': 'denied',+ }+++def test_plugin_binder_namespaces_attachment_types():+ from app.plugins_sdk.ai import PluginToolBinder+ from app.services.ai_tool_registry import ai_tool_registry++ binder = PluginToolBinder('demo')+ binder.register_attachment_resolver('demo.node', lambda user, resource_id: {+ 'label': 'Node', 'source': 'demo', 'summary': {'id': resource_id},+ })+ try:+ assert ai_attachment_registry.get('demo.node') is not None+ with pytest.raises(ValueError, match='namespaced'):+ binder.register_attachment_resolver('other.node', lambda user, resource_id: {})+ ai_tool_registry.unregister_plugin('demo')+ assert ai_attachment_registry.get('demo.node') is None+ finally:+ ai_attachment_registry.unregister_plugin('demo')