deeptutor-server 1.7.0__py3-none-any.whl

deeptutor/api/routers/multi_user.py

@@ -0,0 +1,943 @@
+"""Admin APIs for the optional multi-user layer."""
+
+from __future__ import annotations
+
+import asyncio
+from copy import deepcopy
+import os
+from pathlib import Path
+import shutil
+from typing import Any
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field, StrictBool, field_validator
+
+from deeptutor.api.routers.auth import require_admin, require_auth
+from deeptutor.modules.catalog import module_enabled, require_module
+from deeptutor.multi_user.audit import log_admin_action, log_guardian_action
+from deeptutor.multi_user.book_permission import (
+    BookDefaultLevel,
+    BookPermission,
+    BookPermissionLevel,
+)
+from deeptutor.multi_user.context import get_current_user
+from deeptutor.multi_user.device_credentials import revoke_device_credentials_for_user
+from deeptutor.multi_user.grants import (
+    LEARNING_AGE_BANDS,
+    LEARNING_SURFACES,
+    learner_grant,
+    load_grant,
+    normalize_grant,
+    restore_grant_if_unchanged,
+    save_grant,
+    save_grant_with_receipt,
+    validate_grant,
+)
+from deeptutor.multi_user.guardians import (
+    GUARDIAN_PERMISSIONS,
+    authorize_guardian,
+    guardian_can_access,
+    list_relationships,
+    relationship_by_id,
+    revoke_guardian,
+)
+from deeptutor.multi_user.identity import (
+    get_user_by_id,
+    list_user_info,
+    set_book_permission,
+    set_password,
+    set_preset,
+)
+from deeptutor.multi_user.knowledge_access import admin_kb_base_dir
+from deeptutor.multi_user.model_access import is_owner_bound
+from deeptutor.multi_user.paths import (
+    get_admin_path_service,
+    get_path_service_for_scope,
+    scope_for_user,
+)
+from deeptutor.services.auth import POCKETBASE_ENABLED, hash_password
+from deeptutor.services.config.model_catalog import ModelCatalogService
+
+router = APIRouter()
+
+
+class GrantPayload(BaseModel):
+    grant: dict[str, Any]
+
+
+class BookPermissionPayload(BaseModel):
+    create: StrictBool = True
+    default: BookDefaultLevel = "none"
+    books: dict[str, BookPermissionLevel] = Field(default_factory=dict)
+
+
+class GuardianAuthorizationPayload(BaseModel):
+    guardian_user_id: str = Field(min_length=1, max_length=64)
+    learner_user_id: str = Field(min_length=1, max_length=64)
+    permissions: list[str] = Field(default_factory=lambda: sorted(GUARDIAN_PERMISSIONS))
+
+    @field_validator("permissions")
+    @classmethod
+    def permissions_valid(cls, value: list[str]) -> list[str]:
+        permissions = sorted(set(value))
+        if not permissions or not set(permissions).issubset(GUARDIAN_PERMISSIONS):
+            raise ValueError("Unknown guardian permission")
+        return permissions
+
+
+class GuardianMaterialsPayload(BaseModel):
+    book_ids: list[str]
+
+    @field_validator("book_ids")
+    @classmethod
+    def book_ids_valid(cls, value: list[str]) -> list[str]:
+        book_ids: list[str] = []
+        for raw_id in value:
+            book_id = raw_id.strip()
+            if not book_id:
+                raise ValueError("Book ids cannot be empty")
+            if book_id not in book_ids:
+                book_ids.append(book_id)
+        return book_ids
+
+
+class GuardianRestrictionsPayload(BaseModel):
+    age_band: str
+    allow_upload: StrictBool
+    allowed_surfaces: list[str]
+    extensions: list[str]
+
+    @field_validator("age_band")
+    @classmethod
+    def age_band_valid(cls, value: str) -> str:
+        if value not in LEARNING_AGE_BANDS:
+            raise ValueError("Unknown learning age band")
+        return value
+
+    @field_validator("allowed_surfaces")
+    @classmethod
+    def surfaces_valid(cls, value: list[str]) -> list[str]:
+        surfaces = list(dict.fromkeys(value))
+        if not surfaces or not set(surfaces).issubset(LEARNING_SURFACES):
+            raise ValueError("Unknown or empty learning surface")
+        return surfaces
+
+    @field_validator("extensions")
+    @classmethod
+    def extensions_valid(cls, value: list[str]) -> list[str]:
+        extensions: list[str] = []
+        for raw_id in value:
+            extension_id = raw_id.strip()
+            if not extension_id:
+                raise ValueError("Reading extension ids cannot be empty")
+            if extension_id not in extensions:
+                extensions.append(extension_id)
+        return extensions
+
+
+class GuardianCredentialResetPayload(BaseModel):
+    new_password: str = Field(min_length=8, max_length=128)
+
+
+class SkillInstallPayload(BaseModel):
+    ref: str
+    name: str | None = None
+    force: bool = False
+    allow_unverified: bool = False
+
+
+def _admin_catalog_summary() -> dict[str, list[dict[str, Any]]]:
+    catalog = ModelCatalogService(
+        path=get_admin_path_service().get_settings_file("model_catalog")
+    ).load()
+    out: dict[str, list[dict[str, Any]]] = {"llm": []}
+    for service, state in (catalog.get("services") or {}).items():
+        if service not in out:
+            continue
+        for profile in state.get("profiles", []) or []:
+            if is_owner_bound(profile):
+                # Bound to one person's OAuth identity, so it is not assignable.
+                # Listing it here would offer admins a grant the server drops.
+                continue
+            profile_id = str(profile.get("id") or "")
+            models = []
+            for model in profile.get("models", []) or []:
+                from deeptutor.services.config.provider_links import resolve_profile_provider
+
+                try:
+                    effective = resolve_profile_provider(catalog, service, profile, model)
+                except ValueError:
+                    continue
+                if is_owner_bound(effective):
+                    continue
+                models.append(
+                    {
+                        "model_id": model.get("id", ""),
+                        "name": model.get("name") or model.get("model") or model.get("id"),
+                        "model": model.get("model", ""),
+                    }
+                )
+            if profile.get("models") and not models:
+                continue
+            out[service].append(
+                {
+                    "profile_id": profile_id,
+                    "name": profile.get("name") or profile_id,
+                    "models": models,
+                }
+            )
+    return out
+
+
+def _admin_kb_summary() -> list[dict[str, Any]]:
+    if not module_enabled("knowledge"):
+        return []
+    from deeptutor.knowledge.manager import KnowledgeBaseManager
+
+    manager = KnowledgeBaseManager(base_dir=str(admin_kb_base_dir()))
+    return [
+        {
+            "resource_id": f"admin:kb:{name}",
+            "name": name,
+            "source": "admin",
+        }
+        for name in manager.list_knowledge_bases()
+    ]
+
+
+def _admin_skill_summary() -> list[dict[str, Any]]:
+    from deeptutor.services.skill.service import get_admin_skill_service
+
+    service = get_admin_skill_service()
+    return [item.to_dict() for item in service.list_skills()]
+
+
+def _admin_partner_summary() -> list[dict[str, Any]]:
+    """The partners an admin can hand to someone else.
+
+    Admin-managed partners only — the ones with no owner, or that the admin
+    created. A partner someone built for themselves is theirs to share or not;
+    listing it here would let an admin lend out a private companion (and its
+    soul, which people write personally) by a single click. Identity only: no
+    channel wiring or model selection leaks into the assignable summary.
+    """
+    if not module_enabled("partners"):
+        return []
+    from deeptutor.services.partners import get_partner_manager
+
+    admin_id = get_current_user().id
+    return [
+        {
+            "partner_id": str(item.get("partner_id") or ""),
+            "name": item.get("name") or item.get("partner_id") or "",
+            "description": item.get("description") or "",
+            "emoji": item.get("emoji") or "",
+        }
+        for item in get_partner_manager().list_partners()
+        if str(item.get("owner_id") or "") in ("", admin_id)
+    ]
+
+
+def _reading_root(service: Any) -> Path:
+    return service.get_workspace_feature_dir("reading")
+
+
+def _admin_reading_summary() -> list[dict[str, Any]]:
+    if not module_enabled("reading"):
+        return []
+    from deeptutor.reading import ReadingStore
+
+    store = ReadingStore(_reading_root(get_admin_path_service()))
+    return [manifest.to_dict() for manifest in store.list_materials()]
+
+
+def _stage_assigned_materials(user_id: str, grant: dict[str, Any]) -> None:
+    """Copy newly assigned admin books without touching learner-owned state."""
+    policy = grant.get("learning_policy")
+    reading = policy.get("reading") if isinstance(policy, dict) else None
+    if not isinstance(reading, dict):
+        return
+    material_ids = set(reading.get("material_ids") or [])
+    material_ids.discard("*")
+    if not material_ids:
+        return
+
+    require_module("reading")
+    from deeptutor.reading import ReadingStore
+
+    admin_root = _reading_root(get_admin_path_service())
+    admin_store = ReadingStore(admin_root)
+    user_service = get_path_service_for_scope(scope_for_user(user_id, is_admin=False))
+    target_root = _reading_root(user_service)
+    target_root.mkdir(parents=True, exist_ok=True)
+    for material_id in sorted(material_ids):
+        try:
+            admin_store.manifest(material_id)
+        except Exception as exc:
+            raise ValueError(f"Unknown admin reading material: {material_id}") from exc
+        target = target_root / material_id
+        if target.exists():
+            continue
+        stage = target_root / f".{material_id}.{uuid.uuid4().hex[:8]}.staging"
+        try:
+            shutil.copytree(admin_root / material_id, stage)
+            os.replace(stage, target)
+        finally:
+            shutil.rmtree(stage, ignore_errors=True)
+
+
+def _validate_reading_policy(grant: dict[str, Any]) -> None:
+    policy = grant.get("learning_policy")
+    reading = policy.get("reading") if isinstance(policy, dict) else None
+    if not isinstance(reading, dict):
+        return
+    allowed_extensions = {extension.manifest.id for extension in _reading_extensions()}
+    unknown = sorted(set(reading.get("extensions") or []) - allowed_extensions)
+    if unknown:
+        raise ValueError(f"Unknown reading extensions: {', '.join(unknown)}")
+
+
+def _require_assignable_user(user_id: str) -> tuple[str, dict[str, Any]]:
+    user_record = get_user_by_id(user_id)
+    if user_record is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    username, record = user_record
+    if str(record.get("role") or "user") == "admin":
+        raise HTTPException(
+            status_code=403,
+            detail="Admin users use the main workspace and cannot receive assignments.",
+        )
+    return username, record
+
+
+def _users_by_id() -> dict[str, dict[str, Any]]:
+    return {str(user.get("id") or ""): user for user in list_user_info()}
+
+
+def _relationship_view(
+    relationship: dict[str, Any], users: dict[str, dict[str, Any]]
+) -> dict[str, Any]:
+    guardian = users.get(relationship["guardian_user_id"], {})
+    learner = users.get(relationship["learner_user_id"], {})
+    return {
+        **relationship,
+        "guardian_username": str(guardian.get("username") or ""),
+        "learner_username": str(learner.get("username") or ""),
+    }
+
+
+def _require_guardian_access(
+    current: object, learner_user_id: str, permission: str
+) -> tuple[str, dict[str, Any], str, bool]:
+    actor_user_id = str(getattr(current, "user_id", "") or "")
+    learner_username, learner_record = _require_assignable_user(learner_user_id)
+    is_admin = str(getattr(current, "role", "") or "") == "admin"
+    if is_admin:
+        return learner_username, learner_record, actor_user_id, True
+    _guardian_username, _guardian_record = _require_assignable_user(actor_user_id)
+    if not guardian_can_access(actor_user_id, learner_user_id, permission):
+        raise HTTPException(status_code=403, detail="Guardian authorization required")
+    return learner_username, learner_record, actor_user_id, False
+
+
+def _log_supervisor_action(
+    action: str,
+    *,
+    actor_user_id: str,
+    learner_user_id: str,
+    is_admin: bool,
+    summary: dict[str, Any] | None = None,
+) -> None:
+    if is_admin:
+        log_admin_action(action, target_user_id=learner_user_id, summary=summary)
+        return
+    log_guardian_action(
+        action,
+        guardian_user_id=actor_user_id,
+        learner_user_id=learner_user_id,
+        summary=summary,
+    )
+
+
+@router.get("/admin/resources")
+async def admin_resources(_: object = Depends(require_admin)) -> dict[str, Any]:
+    """Everything an admin can assign to a user: models, KBs, skills, and
+    the tool surface (system tools + MCP tools, same pool partners use)."""
+    from deeptutor.api.utils.tool_options import build_tool_options
+
+    tool_options = await build_tool_options()
+    return {
+        "models": _admin_catalog_summary(),
+        "knowledge_bases": _admin_kb_summary(),
+        "skills": _admin_skill_summary(),
+        "partners": _admin_partner_summary(),
+        "reading_materials": _admin_reading_summary(),
+        "reading_extensions": [
+            extension.manifest.model_dump() for extension in _reading_extensions()
+        ],
+        "tools": tool_options["tools"],
+        "mcp_tools": tool_options["mcp_tools"],
+    }
+
+
+@router.get("/admin/books")
+async def admin_books(_: object = Depends(require_admin)) -> dict[str, Any]:
+    from deeptutor.multi_user.book_access import admin_book_catalog
+
+    return {"books": admin_book_catalog()}
+
+
+@router.get("/guardians")
+async def list_guardian_relationships(
+    include_revoked: bool = False,
+    _: object = Depends(require_admin),
+) -> dict[str, Any]:
+    users = _users_by_id()
+    relationships = [
+        _relationship_view(relationship, users)
+        for relationship in list_relationships(include_revoked=include_revoked)
+    ]
+    return {"relationships": relationships}
+
+
+@router.post("/guardians", status_code=201)
+async def authorize_guardian_relationship(
+    payload: GuardianAuthorizationPayload,
+    current: object = Depends(require_admin),
+) -> dict[str, Any]:
+    _require_assignable_user(payload.guardian_user_id)
+    _require_assignable_user(payload.learner_user_id)
+    try:
+        relationship = authorize_guardian(
+            payload.guardian_user_id,
+            payload.learner_user_id,
+            payload.permissions,
+        )
+    except ValueError as exc:
+        message = str(exc)
+        status_code = 409 if "already authorized" in message else 400
+        raise HTTPException(status_code=status_code, detail=message) from exc
+    log_admin_action(
+        "guardian_authorize",
+        target_user_id=payload.learner_user_id,
+        summary={
+            "relationship_id": relationship["id"],
+            "guardian_user_id": payload.guardian_user_id,
+            "permissions": relationship["permissions"],
+        },
+    )
+    return {
+        "relationship": _relationship_view(relationship, _users_by_id()),
+        "actor_username": str(getattr(current, "username", "") or ""),
+    }
+
+
+@router.delete("/guardians/{relationship_id}")
+async def revoke_guardian_relationship(
+    relationship_id: str,
+    current: object = Depends(require_admin),
+) -> dict[str, Any]:
+    revoked_by = str(getattr(current, "user_id", "") or "")
+    relationship = revoke_guardian(relationship_id, revoked_by=revoked_by)
+    if relationship is None:
+        raise HTTPException(status_code=404, detail="Guardian relationship not found")
+    log_admin_action(
+        "guardian_revoke",
+        target_user_id=relationship["learner_user_id"],
+        summary={
+            "relationship_id": relationship["id"],
+            "guardian_user_id": relationship["guardian_user_id"],
+        },
+    )
+    return {
+        "relationship": _relationship_view(relationship, _users_by_id()),
+        "ok": True,
+    }
+
+
+@router.get("/me/guardianships")
+async def my_guardianships(
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    guardian_user_id = str(getattr(current, "user_id", "") or "")
+    _require_assignable_user(guardian_user_id)
+    users = _users_by_id()
+    relationships = [
+        _relationship_view(relationship, users)
+        for relationship in list_relationships(guardian_user_id=guardian_user_id)
+    ]
+    return {"relationships": relationships}
+
+
+@router.delete("/me/guardianships/{relationship_id}")
+async def revoke_my_guardianship(
+    relationship_id: str,
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    guardian_user_id = str(getattr(current, "user_id", "") or "")
+    _require_assignable_user(guardian_user_id)
+    relationship = relationship_by_id(relationship_id)
+    if (
+        relationship is None
+        or relationship["guardian_user_id"] != guardian_user_id
+        or relationship["revoked_at"] is not None
+    ):
+        raise HTTPException(status_code=404, detail="Active guardian relationship not found")
+    revoked = revoke_guardian(relationship_id, revoked_by=guardian_user_id, reason="self_revoked")
+    assert revoked is not None
+    log_guardian_action(
+        "guardian_self_revoke",
+        guardian_user_id=guardian_user_id,
+        learner_user_id=relationship["learner_user_id"],
+        summary={"relationship_id": relationship_id},
+    )
+    return {"relationship": _relationship_view(revoked, _users_by_id()), "ok": True}
+
+
+@router.get("/learners/{learner_user_id}/guardian-report")
+async def guardian_report(
+    learner_user_id: str,
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    learner_username, learner_record, actor_user_id, is_admin = _require_guardian_access(
+        current, learner_user_id, "view_reports"
+    )
+    from deeptutor.multi_user.book_access import admin_book_catalog
+    from deeptutor.multi_user.book_permission import (
+        normalize_book_permission,
+        public_permission_dict,
+    )
+
+    permission = normalize_book_permission(learner_record.get("book_permission"))
+    permission_dict = public_permission_dict(permission)
+    assigned_materials = [
+        {**book, "permission": permission.level_for(book["book_id"])}
+        for book in admin_book_catalog()
+        if permission.level_for(book["book_id"]) != "none"
+    ]
+    grant = load_grant(learner_user_id)
+    _log_supervisor_action(
+        "guardian_report_view",
+        actor_user_id=actor_user_id,
+        learner_user_id=learner_user_id,
+        is_admin=is_admin,
+        summary={"assigned_material_count": len(assigned_materials)},
+    )
+    return {
+        "learner": {
+            "id": learner_user_id,
+            "username": learner_username,
+            "disabled": bool(learner_record.get("disabled", False)),
+        },
+        "book_permission": permission_dict,
+        "assigned_materials": assigned_materials,
+        "grant_summary": {
+            "model_count": len(grant.get("models", {}).get("llm", []) or []),
+            "knowledge_base_count": len(grant.get("knowledge_bases") or []),
+            "skill_count": len(grant.get("skills") or []),
+            "enabled_tools": grant.get("enabled_tools"),
+        },
+    }
+
+
+@router.get("/learners/{learner_user_id}/materials")
+async def guardian_material_catalog(
+    learner_user_id: str,
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    _learner_username, learner_record, actor_user_id, is_admin = _require_guardian_access(
+        current, learner_user_id, "assign_materials"
+    )
+    from deeptutor.multi_user.book_access import admin_book_catalog
+    from deeptutor.multi_user.book_permission import normalize_book_permission
+
+    permission = normalize_book_permission(learner_record.get("book_permission"))
+    materials = [
+        {
+            **book,
+            "assigned": permission.level_for(book["book_id"]) != "none",
+            "permission": permission.level_for(book["book_id"]),
+        }
+        for book in admin_book_catalog()
+    ]
+    _log_supervisor_action(
+        "guardian_material_catalog_view",
+        actor_user_id=actor_user_id,
+        learner_user_id=learner_user_id,
+        is_admin=is_admin,
+        summary={"material_count": len(materials)},
+    )
+    return {"materials": materials}
+
+
+@router.put("/learners/{learner_user_id}/materials")
+async def assign_guardian_materials(
+    learner_user_id: str,
+    payload: GuardianMaterialsPayload,
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    learner_username, learner_record, actor_user_id, is_admin = _require_guardian_access(
+        current, learner_user_id, "assign_materials"
+    )
+    from deeptutor.multi_user.book_access import admin_book_catalog
+    from deeptutor.multi_user.book_permission import (
+        BookPermission,
+        normalize_book_permission,
+        public_permission_dict,
+    )
+
+    catalog = admin_book_catalog()
+    catalog_ids = {book["book_id"] for book in catalog}
+    unknown = next((book_id for book_id in payload.book_ids if book_id not in catalog_ids), None)
+    if unknown:
+        raise HTTPException(status_code=400, detail=f"Unknown approved book id: {unknown}")
+
+    # Guardians hand out the admin-approved catalogue as read-only material.
+    # Admins remain the only source of edit/create capability.
+    existing = normalize_book_permission(learner_record.get("book_permission"))
+    selected_ids = set(payload.book_ids)
+    permission = BookPermission(
+        create=existing.create,
+        default=existing.default,
+        books=tuple(
+            (book["book_id"], "read" if book["book_id"] in selected_ids else "none")
+            for book in catalog
+            if (book["book_id"] in selected_ids) != (existing.default == "read")
+        ),
+    )
+    if not set_book_permission(learner_username, permission):
+        raise HTTPException(status_code=404, detail="User not found")
+    result = public_permission_dict(permission)
+    _log_supervisor_action(
+        "guardian_material_assign",
+        actor_user_id=actor_user_id,
+        learner_user_id=learner_user_id,
+        is_admin=is_admin,
+        summary={"book_ids": payload.book_ids, "read_only": True},
+    )
+    return {"book_permission": result}
+
+
+def _guardian_restrictions(grant: dict[str, Any]) -> dict[str, Any]:
+    policy = grant.get("learning_policy")
+    if not isinstance(policy, dict):
+        raise HTTPException(status_code=409, detail="Learner account has no learning policy")
+    reading = policy.get("reading") if isinstance(policy.get("reading"), dict) else {}
+    return {
+        "age_band": policy.get("age_band"),
+        "allow_upload": bool(reading.get("allow_upload", False)),
+        "allowed_surfaces": list(policy.get("allowed_surfaces") or ["chat", "reading"]),
+        "extensions": list(reading.get("extensions") or []),
+    }
+
+
+def _restriction_grant(learner_user_id: str, learner_record: dict[str, Any]) -> dict[str, Any]:
+    grant = load_grant(learner_user_id)
+    if grant.get("learning_policy") is None and learner_record.get("preset") == "learner":
+        return learner_grant(learner_user_id)
+    return grant
+
+
+@router.get("/learners/{learner_user_id}/restrictions")
+async def get_guardian_restrictions(
+    learner_user_id: str,
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    _learner_username, learner_record, actor_user_id, is_admin = _require_guardian_access(
+        current, learner_user_id, "manage_restrictions"
+    )
+    restrictions = _guardian_restrictions(_restriction_grant(learner_user_id, learner_record))
+    _log_supervisor_action(
+        "guardian_restrictions_view",
+        actor_user_id=actor_user_id,
+        learner_user_id=learner_user_id,
+        is_admin=is_admin,
+    )
+    return {
+        "restrictions": restrictions,
+        "available_extensions": [
+            extension.manifest.model_dump() for extension in _reading_extensions()
+        ],
+    }
+
+
+@router.put("/learners/{learner_user_id}/restrictions")
+async def put_guardian_restrictions(
+    learner_user_id: str,
+    payload: GuardianRestrictionsPayload,
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    learner_username, learner_record, actor_user_id, is_admin = _require_guardian_access(
+        current, learner_user_id, "manage_restrictions"
+    )
+    available_extensions = {extension.manifest.id for extension in _reading_extensions()}
+    unknown_extensions = sorted(set(payload.extensions) - available_extensions)
+    if unknown_extensions:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown reading extensions: {', '.join(unknown_extensions)}",
+        )
+    grant = deepcopy(_restriction_grant(learner_user_id, learner_record))
+    policy = grant.get("learning_policy")
+    if not isinstance(policy, dict):
+        # Assigning guardian restrictions is what makes an account a learning
+        # account. Seed the default learning policy; the preset is switched
+        # only after the updated grant has passed validation and been saved.
+        grant = deepcopy(learner_grant(learner_user_id))
+        policy = grant.get("learning_policy")
+    if not isinstance(policy, dict):
+        raise HTTPException(status_code=409, detail="Learner account has no learning policy")
+    reading = policy.get("reading")
+    if not isinstance(reading, dict):
+        reading = {}
+        policy["reading"] = reading
+    policy["age_band"] = payload.age_band
+    policy["allowed_surfaces"] = payload.allowed_surfaces
+    reading["allow_upload"] = payload.allow_upload
+    reading["extensions"] = payload.extensions
+    needs_preset_update = learner_record.get("preset") != "learner"
+    try:
+        grant = normalize_grant(learner_user_id, grant)
+        validate_grant(grant)
+        _validate_reading_policy(grant)
+        if needs_preset_update:
+            grant, receipt = save_grant_with_receipt(learner_user_id, grant)
+        else:
+            grant = save_grant(learner_user_id, grant)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Learner grant could not be saved") from exc
+    if needs_preset_update:
+        preset_error: Exception | None = None
+        try:
+            preset_saved = set_preset(learner_username, "learner", expected_user_id=learner_user_id)
+        except Exception as exc:
+            preset_saved = False
+            preset_error = exc
+        if not preset_saved:
+            try:
+                restored = restore_grant_if_unchanged(learner_user_id, receipt)
+            except OSError as exc:
+                raise HTTPException(
+                    status_code=500,
+                    detail="Learner preset update failed and the prior grant could not be restored",
+                ) from exc
+            if not restored:
+                raise HTTPException(
+                    status_code=409,
+                    detail="Learner preset update failed; a later grant change was preserved",
+                ) from preset_error
+            raise HTTPException(
+                status_code=500 if preset_error is not None else 409,
+                detail="Learner preset update failed; the prior grant was restored",
+            ) from preset_error
+    restrictions = _guardian_restrictions(grant)
+    _log_supervisor_action(
+        "guardian_restrictions_set",
+        actor_user_id=actor_user_id,
+        learner_user_id=learner_user_id,
+        is_admin=is_admin,
+        summary=restrictions,
+    )
+    return {"restrictions": restrictions}
+
+
+@router.post("/learners/{learner_user_id}/credentials/reset")
+async def reset_learner_credentials(
+    learner_user_id: str,
+    payload: GuardianCredentialResetPayload,
+    current: object = Depends(require_auth),
+) -> dict[str, Any]:
+    learner_username, _learner_record, actor_user_id, is_admin = _require_guardian_access(
+        current, learner_user_id, "reset_credentials"
+    )
+    if POCKETBASE_ENABLED:
+        raise HTTPException(
+            status_code=400,
+            detail="Guardian credential reset requires built-in local authentication.",
+        )
+    revoked_devices = revoke_device_credentials_for_user(
+        learner_user_id,
+        revoked_by=actor_user_id,
+    )
+    if set_password(learner_username, hash_password(payload.new_password)) is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    _log_supervisor_action(
+        "guardian_credential_reset",
+        actor_user_id=actor_user_id,
+        learner_user_id=learner_user_id,
+        is_admin=is_admin,
+        summary={
+            "credential_reset": True,
+            "device_credentials_revoked": revoked_devices,
+        },
+    )
+    return {"ok": True, "device_credentials_revoked": revoked_devices}
+
+
+@router.get("/users/{user_id}/grants")
+async def get_user_grants(user_id: str, _: object = Depends(require_admin)) -> dict[str, Any]:
+    _require_assignable_user(user_id)
+    return {"grant": load_grant(user_id)}
+
+
+@router.put("/users/{user_id}/grants")
+async def put_user_grants(
+    user_id: str,
+    payload: GrantPayload,
+    _: object = Depends(require_admin),
+) -> dict[str, Any]:
+    user_record = _require_assignable_user(user_id)
+    try:
+        grant = normalize_grant(user_id, payload.grant)
+        if (
+            str(user_record[1].get("preset") or "standard") == "learner"
+            and grant.get("learning_policy") is None
+        ):
+            raise ValueError("Learner accounts must retain a learning policy.")
+        validate_grant(grant)
+        _validate_reading_policy(grant)
+        _stage_assigned_materials(user_id, grant)
+        grant = save_grant(user_id, grant)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    log_admin_action(
+        "grant_set",
+        target_user_id=user_id,
+        summary={
+            "model_count": len(grant.get("models", {}).get("llm", []) or []),
+            "kb_count": len(grant.get("knowledge_bases", []) or []),
+            "skill_count": len(grant.get("skills", []) or []),
+            "partner_count": len(grant.get("partners", []) or []),
+            "enabled_tools": grant.get("enabled_tools"),
+            "mcp_tool_count": (
+                None if grant.get("mcp_tools") is None else len(grant.get("mcp_tools") or [])
+            ),
+            "exec_enabled": grant.get("exec_enabled"),
+            "learning_policy": grant.get("learning_policy"),
+        },
+    )
+    return {"grant": grant}
+
+
+@router.get("/users/{user_id}/book-permission")
+async def get_user_book_permission(
+    user_id: str,
+    _: object = Depends(require_admin),
+) -> dict[str, Any]:
+    from deeptutor.multi_user.book_permission import (
+        normalize_book_permission,
+        public_permission_dict,
+    )
+
+    _, record = _require_assignable_user(user_id)
+    return {
+        "permission": public_permission_dict(
+            normalize_book_permission(record.get("book_permission"))
+        )
+    }
+
+
+@router.put("/users/{user_id}/book-permission")
+async def put_user_book_permission(
+    user_id: str,
+    payload: BookPermissionPayload,
+    _: object = Depends(require_admin),
+) -> dict[str, Any]:
+    from deeptutor.multi_user.book_access import shared_book_exists
+    from deeptutor.multi_user.book_permission import public_permission_dict
+
+    username, _record = _require_assignable_user(user_id)
+    unknown = sorted(book_id for book_id in payload.books if not shared_book_exists(book_id))
+    if unknown:
+        raise HTTPException(status_code=400, detail=f"Unknown book id: {unknown[0]}")
+    permission = BookPermission(
+        create=bool(payload.create),
+        default=payload.default,
+        books=tuple(payload.books.items()),
+    )
+    if not set_book_permission(username, permission):
+        raise HTTPException(status_code=404, detail="User not found")
+    result = public_permission_dict(permission)
+    log_admin_action(
+        "book_permission_set",
+        target_user_id=user_id,
+        summary={
+            "create": permission.create,
+            "default": permission.default,
+            "book_count": len(permission.books),
+        },
+    )
+    return {"permission": result}
+
+
+@router.post("/admin/skills/install")
+async def admin_install_skill(
+    payload: SkillInstallPayload,
+    _: object = Depends(require_admin),
+) -> dict[str, Any]:
+    """Install a hub skill into the admin catalog (``<hub>:<slug>[@version]``).
+
+    The skill lands in the admin workspace — the same pool ``/admin/resources``
+    lists — so it stays invisible to non-admin users until a grant assigns it.
+    The install pipeline (verdict gate, safe extraction, ``always`` stripping)
+    lives in :func:`deeptutor.services.skill.hub.install_from_hub`; this
+    endpoint only chooses the target root and audits the action.
+    """
+    from deeptutor.services.skill.hub import HubError, install_from_hub
+    from deeptutor.services.skill.service import (
+        InvalidSkillNameError,
+        SkillExistsError,
+        SkillImportError,
+        get_admin_skill_service,
+    )
+
+    service = get_admin_skill_service()
+    try:
+        outcome = await asyncio.to_thread(
+            install_from_hub,
+            payload.ref,
+            service=service,
+            rename_to=payload.name,
+            force=payload.force,
+            allow_unverified=payload.allow_unverified,
+        )
+    except SkillExistsError as exc:
+        raise HTTPException(status_code=409, detail=f"Skill already exists: {exc}") from exc
+    except (SkillImportError, InvalidSkillNameError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except HubError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    log_admin_action(
+        "skill_hub_install",
+        summary={
+            "ref": payload.ref,
+            "installed_as": outcome.result.info.name,
+            "version": outcome.ref.version,
+            "verdict": outcome.verdict.status,
+            "forced": payload.force,
+            "allow_unverified": payload.allow_unverified,
+        },
+    )
+    return {
+        "skill": outcome.result.info.to_dict(),
+        "verdict": {"status": outcome.verdict.status, "detail": outcome.verdict.detail},
+        "version": outcome.ref.version,
+        "skipped": [{"path": rel, "reason": reason} for rel, reason in outcome.result.skipped],
+    }
+
+
+@router.get("/users")
+async def multi_user_list_users(_: object = Depends(require_admin)) -> dict[str, Any]:
+    return {"users": list_user_info()}
+
+
+def _reading_extensions():
+    if not module_enabled("reading"):
+        return ()
+    from deeptutor.reading.extensions import get_reading_extension_registry
+
+    return get_reading_extension_registry().all()