keywright-server 0.0.1__py3-none-any.whl

keywright_server/web/inventory_ui.py

@@ -0,0 +1,192 @@
+"""Authenticated inventory forms; manual changes are recorded in the existing audit log."""
+from fastapi import APIRouter, Depends, Request
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from .. import audit
+from .. import inventory as inv
+from ..db import session
+from ..models import DiscoveryLink, DiscoveryObservation, Resource
+from . import auth
+from .admin import redirect, render
+from .security import require_same_origin
+
+router = APIRouter(dependencies=[Depends(require_same_origin), Depends(auth.require_admin)])
+
+
+async def context():
+    async with session() as db:
+        data = await inv.snapshot(db)
+        sources = (await db.execute(select(DiscoveryLink, DiscoveryObservation, Resource)
+                   .join(DiscoveryObservation, DiscoveryLink.observation_id == DiscoveryObservation.id)
+                   .join(Resource, DiscoveryObservation.resource_id == Resource.id))).all()
+        data['discovery_sources'] = {}
+        for link, observation, resource in sources:
+            data['discovery_sources'].setdefault(link.asset_id, []).append(
+                {'link': link, 'observation': observation, 'resource': resource})
+    return {**data, "kinds": inv.KINDS, "media": inv.MEDIA, "states": inv.STATES}
+
+
+@router.get("/ui/inventory")
+async def inventory_page(request: Request, q: str = "", sort: str = "name", group: str = "none"):
+    data = await context()
+    return render(request, "inventory.html", **data, rows=inv.asset_rows(data, q, sort, group),
+                  q=q, sort=sort, group=group)
+
+
+@router.get("/ui/inventory/topology")
+async def topology_page(request: Request):
+    data = await context()
+    return render(request, "inventory_topology.html", **data, tree=inv.hosting_tree(data))
+
+
+@router.get("/ui/inventory/networks")
+async def networks_page(request: Request):
+    data = await context()
+    summaries = {s.id: inv.subnet_summary(s, data["allocations"]) for s in data["subnets"]}
+    return render(request, "inventory_networks.html", **data, summaries=summaries)
+
+
+def asset_context(data, asset, values=None):
+    asset_id = asset.id if asset else None
+    interfaces = [i for i in data["interfaces"] if i.asset_id == asset_id]
+    linked_ids = {x.resource_id for x in data["links"]}
+    return {**data, "asset": asset, "values": values or {}, "asset_interfaces": interfaces,
+            "asset_allocations": [a for a in data["allocations"] if a.interface_id in {i.id for i in interfaces}],
+            "asset_resources": [data["resource_map"][x.resource_id] for x in data["links"]
+                                if x.asset_id == asset_id and x.resource_id in data["resource_map"]],
+            "unlinked_resources": [r for r in data["resources"] if r.id not in linked_ids],
+            "children": [a for a in data["assets"] if a.parent_id == asset_id] if asset else []}
+
+
+@router.get("/ui/inventory/assets/new")
+async def asset_new(request: Request, resource: str = ""):
+    data = await context()
+    res = data["resource_map"].get(resource)
+    values = {"name": res.name, "resource_id": res.id} if res else {}
+    return render(request, "inventory_asset.html", **asset_context(data, None, values))
+
+
+@router.get("/ui/inventory/assets/{asset_id}")
+async def asset_page(request: Request, asset_id: str):
+    data = await context()
+    asset = data["asset_map"].get(asset_id)
+    if not asset:
+        return redirect("/ui/inventory", "Infrastructure record not found.")
+    return render(request, "inventory_asset.html", **asset_context(data, asset))
+
+
+@router.get("/ui/inventory/networks/new")
+async def network_new(request: Request):
+    return render(request, "inventory_subnet.html", **await context(), subnet=None, values={}, summary=None)
+
+
+@router.get("/ui/inventory/networks/{subnet_id}")
+async def network_page(request: Request, subnet_id: str):
+    data = await context()
+    subnet = data["subnet_map"].get(subnet_id)
+    if not subnet:
+        return redirect("/ui/inventory/networks", "Subnet not found.")
+    summary = inv.subnet_summary(subnet, data["allocations"])
+    return render(request, "inventory_subnet.html", **data, subnet=subnet, values={}, summary=summary)
+
+
+@router.post("/ui/inventory/assets")
+async def asset_save(request: Request):
+    form = await request.form()
+    try:
+        async with session() as db:
+            await inv.lock_writes(db)
+            asset = await inv.save_asset(db, form)
+            if form.get("resource_id"):
+                await inv.link_resource(db, {"asset_id": asset.id, "resource_id": form["resource_id"]})
+            await audit.record(db, tool="inventory.asset.save", decision="saved",
+                               detail={"id": asset.id, "name": asset.name})
+            asset_id = asset.id
+    except (inv.InventoryError, IntegrityError) as exc:
+        data = await context()
+        error = str(exc) if isinstance(exc, inv.InventoryError) else "A conflicting record was saved. Refresh and try again."
+        return render(request, "inventory_asset.html", error=error,
+                      **asset_context(data, data["asset_map"].get(form.get("id")), dict(form)))
+    return redirect(f"/ui/inventory/assets/{asset_id}", "Infrastructure record saved.")
+
+
+@router.post("/ui/inventory/networks")
+async def network_save(request: Request):
+    form = await request.form()
+    try:
+        async with session() as db:
+            await inv.lock_writes(db)
+            subnet = await inv.save_subnet(db, form)
+            await audit.record(db, tool="inventory.subnet.save", decision="saved",
+                               detail={"id": subnet.id, "cidr": subnet.cidr, "scope": subnet.scope})
+            subnet_id = subnet.id
+    except (inv.InventoryError, IntegrityError) as exc:
+        data = await context()
+        subnet = data["subnet_map"].get(form.get("id"))
+        error = str(exc) if isinstance(exc, inv.InventoryError) else "A conflicting subnet was saved. Refresh and try again."
+        return render(request, "inventory_subnet.html", **data, subnet=subnet, values=dict(form), error=error,
+                      summary=inv.subnet_summary(subnet, data["allocations"]) if subnet else None)
+    return redirect(f"/ui/inventory/networks/{subnet_id}", "Subnet saved.")
+
+
+@router.post("/ui/inventory/interfaces")
+async def interface_save(request: Request):
+    return await detail_save(request, "interface", inv.save_interface)
+
+
+@router.post("/ui/inventory/allocations")
+async def allocation_save(request: Request):
+    return await detail_save(request, "allocation", inv.save_allocation)
+
+
+@router.post("/ui/inventory/links")
+async def link_save(request: Request):
+    return await detail_save(request, "link", inv.link_resource)
+
+
+async def detail_save(request, kind, save):
+    form = await request.form()
+    try:
+        async with session() as db:
+            await inv.lock_writes(db)
+            row = await save(db, form)
+            row_id = row.resource_id if kind == "link" else row.id
+            await audit.record(db, tool=f"inventory.{kind}.save", decision="saved",
+                               detail={"id": row_id, "record": dict(form)})
+    except (inv.InventoryError, IntegrityError) as exc:
+        error = str(exc) if isinstance(exc, inv.InventoryError) else "A conflicting record was saved. Refresh and try again."
+        data = await context()
+        if kind == "allocation":
+            subnet = data["subnet_map"].get(form.get("subnet_id"))
+            if subnet:
+                return render(request, "inventory_subnet.html", **data, subnet=subnet, values={},
+                              summary=inv.subnet_summary(subnet, data["allocations"]), error=error,
+                              allocation_values=dict(form))
+        else:
+            asset = data["asset_map"].get(form.get("asset_id"))
+            if asset:
+                return render(request, "inventory_asset.html", **asset_context(data, asset), error=error,
+                              interface_values=dict(form) if kind == "interface" else {})
+        return redirect("/ui/inventory", error)
+    destination = (f"/ui/inventory/networks/{row.subnet_id}" if kind == "allocation"
+                   else f"/ui/inventory/assets/{row.asset_id}")
+    return redirect(destination, f"{kind.capitalize()} saved.")
+
+
+@router.post("/ui/inventory/{kind}/{row_id}/delete")
+async def record_delete(request: Request, kind: str, row_id: str):
+    form = await request.form()
+    try:
+        async with session() as db:
+            await inv.lock_writes(db)
+            row = await inv.delete_record(db, kind, row_id)
+            destination = {"asset": "/ui/inventory", "subnet": "/ui/inventory/networks"}.get(kind)
+            if destination is None:
+                destination = (f"/ui/inventory/networks/{row.subnet_id}" if kind == "allocation"
+                               else f"/ui/inventory/assets/{row.asset_id}")
+            await audit.record(db, tool=f"inventory.{kind}.delete", decision="deleted", detail={"id": row_id})
+    except (inv.InventoryError, IntegrityError) as exc:
+        error = str(exc) if isinstance(exc, inv.InventoryError) else "This record is still in use."
+        return redirect(str(form.get("next", "/ui/inventory")), error)
+    return redirect(destination, "Record removed from inventory.")

keywright_server/web/knowledge_ui.py

@@ -0,0 +1,177 @@
+"""Admin knowledge publishing and proposal review; agent access stays behind MCP policy."""
+import difflib
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import PlainTextResponse
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from .. import audit, knowledge_index
+from .. import knowledge as k
+from ..db import session
+from ..models import Resource, now
+from . import auth
+from .admin import redirect, render
+from .security import require_same_origin
+
+router = APIRouter(dependencies=[Depends(require_same_origin), Depends(auth.require_admin)])
+
+
+@router.get("/ui/knowledge")
+async def home(request: Request, collection: str = "", q: str = "", offset: int = 0):
+    async with session() as db:
+        collections = list(await db.scalars(select(Resource).where(Resource.kind == "mcp").order_by(Resource.name)))
+        collections = [r for r in collections if r.config.get("adapter") == "knowledge"]
+        selected = next((r for r in collections if r.id == collection), None)
+        documents, proposals, results = {"documents": [], "next_offset": None}, [], None
+        if selected:
+            documents = await k.list_documents(db, selected.id, max(0, offset), 50)
+            proposals = (await db.execute(select(k.Revision, k.Document).join(k.Document)
+                .where(k.Document.resource_id == selected.id, k.Revision.status == "pending")
+                .order_by(k.Revision.created_at).limit(100))).all()
+            if q.strip():
+                try:
+                    results = await k.search(db, selected.id, q)
+                except k.KnowledgeError as exc:
+                    results = {"results": [], "mode": "text", "warning": str(exc)}
+                await audit.record(db, tool="knowledge.search", decision="read", detail={"collection": selected.id})
+    return render(request, "knowledge.html", collections=collections, selected=selected, documents=documents,
+                  proposals=proposals, results=results, q=q, kinds=k.KINDS,
+                  semantic=knowledge_index.backend() is not None)
+
+
+@router.post("/ui/knowledge/collections")
+async def create(request: Request):
+    form = await request.form()
+    try:
+        async with session() as db:
+            await k.lock_writes(db)
+            res = await k.create_collection(db, str(form.get("name", "")).strip(), str(form.get("description", "")))
+            await audit.record(db, tool="knowledge.collection.create", decision="saved", detail={"collection": res.id})
+            rid = res.id
+    except (k.KnowledgeError, IntegrityError) as exc:
+        return redirect("/ui/knowledge", str(exc) if isinstance(exc, k.KnowledgeError) else "Collection already exists.")
+    return redirect("/ui/knowledge?collection=" + rid, "Collection created. Grant agents access using Access rules.")
+
+
+@router.post("/ui/knowledge/{rid}/publish")
+async def publish(request: Request, rid: str):
+    form = await request.form()
+    try:
+        body, version = str(form.get("body", "")), ""
+        path = str(form.get("path", ""))
+        source = str(form.get("source", ""))
+        if form.get("import_git") == "1":
+            body, version = await k.git_markdown(path)
+            source = "git:" + path
+        async with session() as db:
+            await k.lock_writes(db)
+            rev = await k.propose(db, rid, path=path, title=str(form.get("title", "")), body=body,
+                kind=str(form.get("kind", "documentation")), source=source, source_version=version,
+                expected_revision=str(form.get("expected_revision", "")) or None,
+                retention_days=int(form.get("retention_days", "30")))
+            await k.review(db, rev.id, True)
+            await audit.record(db, tool="knowledge.publish", decision="published",
+                detail={"collection": rid, "revision": rev.id, "sha256": rev.sha256, "source_version": version})
+    except (k.KnowledgeError, ValueError, IntegrityError) as exc:
+        return redirect("/ui/knowledge?collection=" + rid,
+            str(exc) if isinstance(exc, k.KnowledgeError) else "Invalid or conflicting document; refresh and retry.")
+    return redirect("/ui/knowledge?collection=" + rid, "Published and text-indexed. Rebuild the semantic index to update it.")
+
+
+@router.get("/ui/knowledge/documents/{did}")
+async def document(request: Request, did: str, download: bool = False):
+    async with session() as db:
+        doc = await db.get(k.Document, did)
+        if not doc:
+            return redirect("/ui/knowledge", "Document not found.")
+        try:
+            res = await k.collection(db, doc.resource_id)
+            data = await k.get_document(db, res.id, did)
+        except k.KnowledgeError as exc:
+            return redirect("/ui/knowledge", str(exc))
+        await audit.record(db, tool="knowledge.get", decision="read", detail={"document": did, "revision": data["revision"]})
+    if download:
+        return PlainTextResponse(data["markdown"], media_type="text/markdown",
+                                 headers={"Content-Disposition": 'attachment; filename="knowledge.md"'})
+    return render(request, "knowledge_document.html", doc=data, collection=res, kinds=k.KINDS)
+
+
+@router.get("/ui/knowledge/proposals/{revision_id}")
+async def proposal(request: Request, revision_id: str):
+    async with session() as db:
+        rev = await db.get(k.Revision, revision_id)
+        if not rev:
+            return redirect("/ui/knowledge", "Proposal not found.")
+        doc = await db.get(k.Document, rev.document_id)
+        try:
+            res = await k.collection(db, doc.resource_id)
+            body = k.markdown(rev)
+            old = await db.get(k.Revision, doc.current_revision) if doc.current_revision else None
+            previous = k.markdown(old) if old else ""
+        except k.KnowledgeError as exc:
+            return redirect("/ui/knowledge", str(exc))
+        diff = "".join(difflib.unified_diff(previous.splitlines(True), body.splitlines(True),
+                                          fromfile="Current published Markdown", tofile="Proposed Markdown"))
+    return render(request, "knowledge_proposal.html", revision=rev, doc=doc, collection=res, body=body, diff=diff)
+
+
+@router.post("/ui/knowledge/proposals/{revision_id}")
+async def review(request: Request, revision_id: str):
+    form = await request.form()
+    try:
+        if form.get("action") not in ("approve", "reject"):
+            raise k.KnowledgeError("Choose approve or reject.")
+        async with session() as db:
+            await k.lock_writes(db)
+            rev = await k.review(db, revision_id, form["action"] == "approve")
+            doc = await db.get(k.Document, rev.document_id)
+            rid = doc.resource_id
+            await audit.record(db, tool="knowledge.review", decision=rev.status,
+                               detail={"revision": rev.id, "collection": rid, "sha256": rev.sha256})
+    except k.KnowledgeError as exc:
+        return redirect("/ui/knowledge/proposals/" + revision_id, str(exc))
+    return redirect("/ui/knowledge?collection=" + rid, "Proposal " + rev.status + ".")
+
+
+@router.post("/ui/knowledge/{rid}/archive")
+async def archive(request: Request, rid: str):
+    form = await request.form()
+    try:
+        async with session() as db:
+            await k.lock_writes(db)
+            await k.archive(db, rid, str(form.get("document_id", "")), str(form.get("expected_revision", "")))
+            await audit.record(db, tool="knowledge.archive", decision="archived",
+                               detail={"collection": rid, "document": str(form.get("document_id", ""))})
+    except k.KnowledgeError as exc:
+        return redirect("/ui/knowledge?collection=" + rid, str(exc))
+    return redirect("/ui/knowledge?collection=" + rid, "Archived. This document is no longer returned to agents.")
+
+
+@router.post("/ui/knowledge/{rid}/reindex")
+async def reindex(rid: str):
+    try:
+        async with session() as db:
+            count = await k.reindex(db, rid)
+            res = await k.collection(db, rid)
+            res.config = {**res.config, "knowledge_indexed_at": now().isoformat(), "knowledge_indexed_chunks": count}
+            await audit.record(db, tool="knowledge.reindex", decision="indexed", detail={"collection": rid, "chunks": count})
+    except (k.KnowledgeError, knowledge_index.IndexUnavailable) as exc:
+        return redirect("/ui/knowledge?collection=" + rid, str(exc))
+    return redirect("/ui/knowledge?collection=" + rid, f"Indexed {count} chunks for hybrid retrieval.")
+
+
+@router.post("/ui/knowledge/{rid}/rechunk")
+async def rechunk(rid: str):
+    try:
+        async with session() as db:
+            await k.lock_writes(db)
+            result = await k.rechunk(db, rid)
+            await audit.record(db, tool="knowledge.rechunk", decision="rechunked", detail={"collection": rid, **result})
+    except k.KnowledgeError as exc:
+        return redirect("/ui/knowledge?collection=" + rid, str(exc))
+    message = (f"Updated search passages for {result['changed_documents']} documents. "
+               "Published content and review history are unchanged.")
+    if result["changed_documents"] and knowledge_index.backend() is not None:
+        message += " Rebuild the semantic index to include the new passages."
+    return redirect("/ui/knowledge?collection=" + rid, message)

keywright_server/web/mail_ui.py

@@ -0,0 +1,190 @@
+"""Owner-authenticated inbox, rule editor, and delivery history."""
+from urllib.parse import quote
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import Response
+from sqlalchemy import func, or_, select
+
+from .. import audit, mail, settings_store
+from ..db import session
+from ..models import Agent, MailMessage, MailRule, Resource
+from . import auth
+from .admin import redirect, render
+from .security import require_same_origin
+
+router = APIRouter(dependencies=[Depends(require_same_origin), Depends(auth.require_admin)])
+
+
+async def get_message(db, cfg, identifier):
+    message = await db.get(MailMessage, identifier)
+    if not message or message.source != mail.source(cfg):
+        raise HTTPException(404, "Message not found")
+    return message
+
+
+@router.get('/ui/mail')
+async def inbox(request: Request, selected: str = '', status: str = '', q: str = '', page: int = 1,
+                view: str = 'inbox'):
+    async with session() as db:
+        cfg = await mail.config(db)
+        conditions = [MailMessage.source == mail.source(cfg)]
+        if view != 'history':
+            conditions.append(MailMessage.present.is_(True))
+        if status in mail.STATUS:
+            conditions.append(MailMessage.status == status)
+        if q:
+            conditions.append(or_(MailMessage.subject.contains(q[:200], autoescape=True),
+                                  MailMessage.sender.contains(q[:200], autoescape=True)))
+        total = await db.scalar(select(func.count()).select_from(MailMessage).where(*conditions))
+        pages = max(1, (total + 49) // 50)
+        page = max(1, min(page, pages))
+        messages = (await db.scalars(select(MailMessage).where(*conditions)
+                    .order_by(MailMessage.date.desc(), MailMessage.created_at.desc())
+                    .offset((page - 1) * 50).limit(50))).all()
+        message, error = None, ''
+        if selected:
+            message = await get_message(db, cfg, selected)
+            try:
+                await mail.body(db, cfg, message)
+            except mail.MailError as exc:
+                error = str(exc)
+        counts = dict((await db.execute(select(MailMessage.status, func.count()).where(
+            MailMessage.source == mail.source(cfg), MailMessage.present.is_(True)
+        ).group_by(MailMessage.status))).all())
+        return render(request, 'mail.html', cfg=cfg, messages=messages, message=message, counts=counts,
+                      statuses=mail.STATUS, selected=selected, status=status, q=q, page=page, pages=pages,
+                      total=total, view=view, error=error)
+
+
+@router.post('/ui/mail/sync')
+async def sync_mail():
+    async with mail.lock, session() as db:
+        try:
+            await mail.sync(db, await mail.config(db))
+        except mail.MailError as exc:
+            return redirect('/ui/mail', str(exc))
+        except Exception:  # noqa: BLE001 - upstream connection failures must not expose credentials
+            return redirect('/ui/mail', 'Mailbox sync failed. Check the email connection and audit log.')
+    return redirect('/ui/mail', 'Inbox refreshed.')
+
+
+@router.post('/ui/mail/{identifier}/run')
+async def run_message(identifier: str):
+    async with mail.lock, session() as db:
+        cfg = await mail.config(db)
+        message = await get_message(db, cfg, identifier)
+        if message.status == 'failed' and message.plan:
+            # Keep the original plan and receipts: a retry never silently changes destinations.
+            message.status, message.request_id = 'queued', None
+            await db.commit()
+        else:
+            await mail.queue(db, cfg, message)
+        if message.status in {'queued', 'running', 'pending'}:
+            await mail.advance(db, cfg, message)
+        await audit.record(db, tool='mail_run', decision='allow', detail={'message': identifier})
+    return redirect('/ui/mail?selected=' + identifier)
+
+
+@router.get('/ui/mail/{identifier}/attachment')
+async def download(identifier: str, name: str):
+    async with session() as db:
+        cfg = await mail.config(db)
+        message = await get_message(db, cfg, identifier)
+        try:
+            await mail.verify_message(db, cfg, message)
+            content = await mail.attachment(db, cfg, message, name)
+        except mail.MailError as exc:
+            return redirect('/ui/mail?selected=' + identifier, str(exc))
+    return Response(content, media_type='application/pdf', headers={
+        'Content-Disposition': "attachment; filename*=UTF-8''" + quote(name, safe=''),
+        'Cache-Control': 'no-store',
+    })
+
+
+@router.get('/ui/mail/rules')
+async def rule_page(request: Request, edit: str = ''):
+    async with session() as db:
+        entries = await mail.rules(db)
+        rule = await db.get(MailRule, edit) if edit else None
+        return render(request, 'mail_rules.html', rules=entries, rule=rule)
+
+
+@router.post('/ui/mail/rules/save')
+async def save_rule(request: Request):
+    form = await request.form()
+    async with mail.lock, session() as db:
+        identifier = str(form.get('id') or '')
+        rule = await db.get(MailRule, identifier) if identifier else MailRule()
+        if rule is None:
+            raise HTTPException(404, 'Rule not found')
+        name, sender, subject = (str(form.get(k) or '').strip() for k in ('name', 'sender', 'subject'))
+        action, target = str(form.get('action') or ''), str(form.get('target') or '').strip()
+        if not name or len(name) > 120 or not (sender or subject) or len(sender) > 320 or len(subject) > 200:
+            return redirect('/ui/mail/rules', 'Give the rule a name and a sender or subject filter.')
+        if action not in {'pdf', 'mark_read', 'move'} or (action == 'move' and not target):
+            return redirect('/ui/mail/rules', 'Choose an action and a destination folder when moving mail.')
+        if len(target) > 200 or any(ord(c) < 32 for c in target):
+            return redirect('/ui/mail/rules', 'Use a valid destination folder name.')
+        try:
+            position = int(str(form.get('position') or '100'))
+            if not 0 <= position <= 9999:
+                raise ValueError()
+        except ValueError:
+            return redirect('/ui/mail/rules', 'Priority must be between 0 and 9999.')
+        rule.name, rule.sender, rule.subject = name, sender, subject
+        rule.action, rule.target, rule.position = action, target, position
+        rule.enabled = form.get('enabled') == 'on'
+        db.add(rule)
+        await db.flush()
+        await audit.record(db, tool='mail_rule_save', decision='allow', detail={'rule': rule.id, 'action': action})
+    return redirect('/ui/mail/rules', 'Rule saved. It applies to new mail; use Run rules for existing messages.')
+
+
+@router.post('/ui/mail/rules/{identifier}/toggle')
+async def toggle_rule(identifier: str):
+    async with mail.lock, session() as db:
+        rule = await db.get(MailRule, identifier)
+        if not rule:
+            raise HTTPException(404, 'Rule not found')
+        rule.enabled = not rule.enabled
+        await audit.record(db, tool='mail_rule_toggle', decision='allow', detail={'rule': identifier, 'enabled': rule.enabled})
+    return redirect('/ui/mail/rules')
+
+
+@router.get('/ui/mail/settings')
+async def settings_page(request: Request):
+    async with session() as db:
+        cfg = await mail.config(db)
+        resources = (await db.scalars(select(Resource).where(Resource.kind == 'mcp').order_by(Resource.name))).all()
+        agents = (await db.scalars(select(Agent).where(Agent.disabled_at.is_(None)).order_by(Agent.name))).all()
+        return render(request, 'mail_settings.html', cfg=cfg, resources=resources, agents=agents)
+
+
+@router.post('/ui/mail/settings')
+async def save_settings(request: Request):
+    form = await request.form()
+    async with mail.lock, session() as db:
+        cfg = await mail.config(db)
+        resource = await db.get(Resource, str(form.get('resource') or ''))
+        agent = await db.get(Agent, str(form.get('agent') or ''))
+        if not resource or resource.kind != 'mcp' or not agent or agent.disabled:
+            return redirect('/ui/mail/settings', 'Choose an email resource and an enabled agent.')
+        try:
+            endpoint = mail.budget_url(str(form.get('budget_url'))) if form.get('budget_url') else ''
+            account, mailbox = (str(form.get(k) or '').strip() for k in ('account', 'mailbox'))
+            if not account or not mailbox or max(len(account), len(mailbox)) > 200:
+                raise mail.MailError('Account and mailbox are required (up to 200 characters).')
+            token = str(form.get('budget_token') or '').strip()
+            if token and (not token.startswith('ba_docs_') or len(token) > 200):
+                raise mail.MailError('Use a document delivery token from Budget settings.')
+            if endpoint != cfg.get('budget_url', '') and endpoint and not token:
+                raise mail.MailError('Enter a delivery token when changing the budget server.')
+        except mail.MailError as exc:
+            return redirect('/ui/mail/settings', str(exc))
+        updated = {**cfg, 'resource': resource.id, 'agent': agent.id, 'account': account, 'mailbox': mailbox,
+                   'budget_url': endpoint, 'budget_token': token or cfg.get('budget_token', ''),
+                   'enabled': form.get('enabled') == 'on'}
+        await settings_store.put(db, 'mail', updated)
+        await audit.record(db, tool='mail_settings_save', decision='allow', detail={
+            'resource': resource.id, 'agent': agent.id, 'enabled': updated['enabled']})
+    return redirect('/ui/mail/settings', 'Connection saved. Refresh the inbox to check access.')

keywright_server/web/mcp_oauth_ui.py

@@ -0,0 +1,87 @@
+"""Administrator consent for broker-owned upstream OAuth connections."""
+from __future__ import annotations
+
+import secrets
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from .. import audit, mcp_oauth, mcp_proxy
+from ..db import session
+from ..models import Resource
+from . import auth
+from .security import _origin, require_same_origin
+
+router = APIRouter(dependencies=[Depends(require_same_origin), Depends(auth.require_admin)])
+COOKIE = "kw_mcp_oauth_flow"
+COOKIE_PATH = "/ui/mcp-oauth"
+
+
+def failure(message: str):
+    # Only fixed local ConnectionError messages, never provider responses.
+    from html import escape
+    response = HTMLResponse(
+        '<!doctype html><title>Connect MCP</title><h1>Connection unsuccessful</h1>'
+        f'<p>{escape(message)}</p><p><a href="/ui/resources">Return to resources</a></p>', status_code=400,
+    )
+    response.delete_cookie(COOKIE, path=COOKIE_PATH, secure=True, httponly=True, samesite="lax")
+    return response
+
+
+async def resource(rid: str) -> Resource:
+    async with session() as db:
+        res = await db.get(Resource, rid)
+    if not res or res.kind != "mcp" or res.config.get("auth_type") != "oauth":
+        raise mcp_oauth.ConnectionError("Save an HTTP MCP resource with OAuth authentication first.")
+    return res
+
+
+@router.post("/ui/mcp-oauth/{rid}/connect")
+async def connect(request: Request, rid: str):
+    try:
+        res = await resource(rid)
+        if _origin(str(request.url)) != _origin(mcp_oauth.callback_url()):
+            raise mcp_oauth.ConnectionError("Open Keywright at its configured public HTTPS URL to connect OAuth.")
+        browser = secrets.token_urlsafe(32)
+        url = await mcp_oauth.begin(res.config, browser, request.cookies.get(auth.COOKIE, ""))
+        mcp_proxy.forget(res.name)
+    except mcp_oauth.ConnectionError as exc:
+        return failure(str(exc))
+    # A cross-origin redirect after a form POST is blocked by form-action 'self'
+    # in browsers such as Safari and Chromium. Finish the POST with a page that
+    # starts a fresh navigation, retaining our same-origin form policy.
+    from .admin import render
+    response = render(request, "mcp_oauth_continue.html", authorization_url=url,
+                      resource_name=res.name, resource_id=res.id)
+    response.set_cookie(COOKIE, browser, max_age=mcp_oauth.FLOW_TTL, path=COOKIE_PATH,
+                        secure=True, httponly=True, samesite="lax")
+    return response
+
+
+@router.get(mcp_oauth.CALLBACK_PATH)
+async def callback(request: Request):
+    try:
+        rid = await mcp_oauth.finish(request.query_params, request.cookies.get(COOKIE, ""),
+                                     request.cookies.get(auth.COOKIE, ""))
+        res = await resource(rid)
+    except mcp_oauth.ConnectionError as exc:
+        return failure(str(exc))
+    mcp_proxy.forget(res.name)
+    async with session() as db:
+        await audit.record(db, tool="admin.mcp_oauth.connect", decision="allow", detail={"resource_id": rid})
+    response = RedirectResponse(f"/ui/resources/{rid}", status_code=303)
+    response.delete_cookie(COOKIE, path=COOKIE_PATH, secure=True, httponly=True, samesite="lax")
+    return response
+
+
+@router.post("/ui/mcp-oauth/{rid}/disconnect")
+async def disconnect(request: Request, rid: str):
+    try:
+        res = await resource(rid)
+        await mcp_oauth.disconnect(res.config)
+    except mcp_oauth.ConnectionError as exc:
+        return failure(str(exc))
+    mcp_proxy.forget(res.name)
+    async with session() as db:
+        await audit.record(db, tool="admin.mcp_oauth.disconnect", decision="allow", detail={"resource_id": rid})
+    return RedirectResponse(f"/ui/resources/{rid}", status_code=303)