feat(auth): portal_delegate key scope + single-route fence (ent#163) (#1869)

* feat(auth): portal_delegate key scope + single-route fence (ent#163)

The OSS half of delegated portal identity: the scope, its containment, and the
admin-only mint. The endpoint that decides *whether* an email may be delegated
stays in the entitled module — core owns the enforcement primitive only, the
same split as `PORTAL_SESSION_SCOPE` (#78) and `users.suspended_at` (#995).

Why a new scope rather than reusing `scope='user'`: the capability lets its
holder act as another person and read their conversations. Riding it on an
ordinary user key would silently turn EVERY user key into a fleet-wide
impersonation key. It is admin-issued, listed and revocable like any other key,
and revoking it stops delegation on the next request.

The fence is the load-bearing part. A delegate key resolves to the KEY OWNER,
exactly like every other MCP key, so unfenced it would simply BE an admin's
credential handed to a third party. `get_current_user` confines it to one
(method, path) — the exchange route — at the single auth entry point, mirroring
the connector fence (ent#46): centrally, not in the portal router, because the
many endpoints doing inline access checks resolve this principal to the owner
and would otherwise treat it as that human.

Deliberately ONE route, not a prefix: the minted portal session — not this key —
drives the portal surface afterwards, so the key never needs breadth, and a
prefix would silently grant every portal endpoint added in future.

Minting is admin AND human-only. `assert_admin` alone is insufficient: it
rejects connector principals but not agent-scoped ones, and an agent key
resolves to its owner carrying the owner's role, which on a default admin-owned
install passes a bare role check (trinity-ops-agent#232). The db layer
independently refuses any scope outside `{user, portal_delegate}` so
agent/connector/system keys — which carry an agent binding and are minted by
their own paths — can never be forged through this endpoint.

Incidental fix in the same function: `create_mcp_api_key` now sets `is_active=1`
explicitly instead of relying on a column default that exists in only one of the
two schema sources — `schema.py` declares `is_active INTEGER DEFAULT 1` but
`db/tables.py` (the Core/Alembic source) declares a bare `Column(...)`. A table
built from the metadata yields NULL, and `validate_mcp_api_key` treats falsy
`is_active` as revoked, so every minted key would be born invalid. Harmless on
both live schema paths; found because it broke a test built from the metadata.

Tests: `test_163_portal_delegate_scope.py` — structural (the fence is one route,
the model defaults to False, the db creatable-set excludes agent scopes) plus
behavioural, driving the real `get_current_user`: a delegate key is accepted on
the exchange route and 403s on the fleet, the user list, key minting, the portal
surface itself, and the right path with the wrong method. Verified the
behavioural half fails (5 tests) with the fence disabled.

103 passed across the auth-surface suites; 692 passed over the wider
key/auth/portal selection. Enterprise-docs guard clean.

Related to trinity-enterprise#163

* feat(ui): surface portal_delegate keys in Settings → MCP Keys (ent#163)

The issue's AC asks for the scope to be "admin-issued, listed and revocable in
Settings → MCP Keys". Listing and revoking already worked — but a
`portal_delegate` key rendered with NO badge, falling through the
`agent`/`system` v-if chain and looking exactly like an ordinary user key. For a
credential that can act as any end user with portal access, that is misleading
in precisely the place an admin audits keys. And there was no way to create one
from the UI at all, so "admin-issued" meant "curl only".

Two small additions:

* an amber **Portal Delegate** badge, deliberately distinct from the purple
  Agent / red System badges, with a title explaining what the key can do
* an admin-only checkbox on the create modal (`v-if="isAdmin"`), opt-in rather
  than a default — minting a key that acts as other people should be a
  conscious choice, never a stray click. The scope is omitted entirely (not sent
  as null) for an ordinary key, so nothing changes for existing callers.

Verified live: badge renders on both delegate keys; the checkbox appears for an
admin and mints a working `scope=portal_delegate` key. The end-to-end flow was
driven against local dev — mint → fenced (403 on /api/agents, /api/users,
/api/mcp/keys) → exchange for two different end users from ONE key → disjoint
rosters (bob→[evt-boss], carol→[evt-worker]) → unauthorized email 403 → revoke →
401.

Related to trinity-enterprise#163

Author: dolho

docs/memory/architecture.md

@@ -1280,7 +1280,7 @@ CREATE TABLE mcp_api_keys (
     is_active INTEGER DEFAULT 1,
     user_id INTEGER NOT NULL,
     agent_name TEXT,                 -- non-null for agent-scoped keys
-    scope TEXT DEFAULT 'user',       -- user | agent | system
+    scope TEXT DEFAULT 'user',       -- user | agent | system | connector | portal_delegate
     FOREIGN KEY (user_id) REFERENCES users(id)
 );
 ```
@@ -1982,6 +1982,7 @@ Enforced at the **MCP server layer** (`src/mcp-server/src/tools/`), not the back
 | `user` | Owner/admin/shared checks | Owner/admin/shared checks |
 | `agent` | Explicit permission list (`agent_permissions`) | Resolves to owner user; ownership/sharing checks only |
 | `system` | **Bypasses all checks** | Resolves to owner user (system agent owner) |
+| `portal_delegate` | n/a (not an MCP tool principal) | **Fenced to a single route** — may only exchange an asserted end-user email for a portal session; every other path 403s (ent#163) |
 
 ### 7. External Credentials (Agent → External Services)
 

src/backend/db/mcp_keys.py

@@ -90,12 +90,27 @@ def _row_to_mcp_api_key(row) -> McpApiKey:
             scope=scope
         )
 
+    # ent#163: the scopes this endpoint may mint. `agent`, `connector` and
+    # `system` are deliberately absent — they are bound to an agent and are
+    # minted by their own code paths; accepting them here would let a caller
+    # forge an agent principal with no agent behind it.
+    _USER_CREATABLE_SCOPES = ("user", "portal_delegate")
+
     def create_mcp_api_key(self, username: str, key_data: McpApiKeyCreate) -> Optional[McpApiKeyWithSecret]:
-        """Create a new MCP API key for a user (scope: user)."""
+        """Create a new MCP API key for a user.
+
+        Scope defaults to `user`. `portal_delegate` (ent#163) is admin-gated at
+        the router; this layer only refuses anything outside the creatable set
+        so a bad value can never reach the column.
+        """
         user = self._user_ops.get_user_by_username(username)
         if not user:
             return None
 
+        scope = getattr(key_data, "scope", None) or "user"
+        if scope not in self._USER_CREATABLE_SCOPES:
+            return None
+
         key_id = self._generate_id()
         api_key = self._generate_mcp_api_key()
         key_hash = self._hash_api_key(api_key)
@@ -112,7 +127,17 @@ def create_mcp_api_key(self, username: str, key_data: McpApiKeyCreate) -> Option
                     created_at=now,
                     user_id=user["id"],
                     agent_name=None,
-                    scope="user",
+                    scope=scope,
+                    # Set explicitly rather than leaning on the column default:
+                    # `schema.py` declares `is_active INTEGER DEFAULT 1` but
+                    # `db/tables.py` (the Core/Alembic source) declares a bare
+                    # `Column("is_active", Integer)` with no default, so a table
+                    # built from the metadata yields NULL here — and
+                    # `validate_mcp_api_key` treats a falsy is_active as revoked,
+                    # i.e. every minted key would be born invalid. Harmless today
+                    # (both live schema paths carry the DDL default) but a real
+                    # trap for anything built off the metadata.
+                    is_active=1,
                 )
             )
 
@@ -129,7 +154,7 @@ def create_mcp_api_key(self, username: str, key_data: McpApiKeyCreate) -> Option
             username=username,
             user_email=user.get("email"),
             agent_name=None,
-            scope="user",
+            scope=scope,
             api_key=api_key
         )
 

src/backend/db_models.py

@@ -87,6 +87,11 @@ class AgentShareRequest(BaseModel):
 class McpApiKeyCreate(BaseModel):
     name: str
     description: Optional[str] = None
+    # ent#163: normally omitted → a plain `user` key. The only other value a
+    # caller may request is `portal_delegate`, and the router gates that on
+    # admin. Agent/connector/system keys are minted by their own code paths,
+    # never by this endpoint, so they are not accepted here.
+    scope: Optional[str] = None
 
 
 class McpApiKey(BaseModel):

src/backend/dependencies.py

@@ -183,6 +183,38 @@ def decode_mfa_challenge(token: str) -> Optional[dict]:
 PORTAL_SESSION_SCOPE = "portal_session"
 PORTAL_SESSION_EXPIRE_HOURS = 12
 
+# --- Delegated portal identity (ent#163) ---------------------------------
+#
+# A `portal_delegate` MCP key lets a TRUSTED backend assert which of *its* end
+# users a request is for, and exchange that assertion for a portal session
+# token. It is how a licensee runs their own customer portal against Trinity
+# while keeping their own IdP: they already authenticated bob@example.com and
+# want Trinity to act as bob, not as the key owner.
+#
+# Why a dedicated scope rather than reusing `scope='user'`: this capability
+# reads another person's chat history. Riding it on an ordinary user key would
+# silently turn EVERY user key into a fleet-wide impersonation key. It is
+# admin-issued, and revoking the key stops delegation immediately.
+#
+# Why a mint rather than a per-request `X-On-Behalf-Of` header: a header puts
+# impersonation in the auth path of every current *and future* portal endpoint —
+# an ambient capability each new route silently inherits. A mint is one
+# auditable event, and everything downstream keeps using the portal session
+# token it already understands.
+#
+# Edition-agnostic, exactly like PORTAL_SESSION_SCOPE above: OSS owns the scope,
+# the containment fence, and the mint primitive; the entitled module owns the
+# endpoint that decides *whether* this email may be delegated. In an OSS-only
+# build the fenced path is not registered, so such a key can reach nothing.
+PORTAL_DELEGATE_SCOPE = "portal_delegate"
+
+# The ONLY (method, path) a portal_delegate key may reach. Deliberately a single
+# exchange route, not a prefix: the minted portal session — not this key — is
+# what drives the portal surface afterwards, so this key never needs breadth.
+PORTAL_DELEGATE_ALLOWED_ROUTES = {
+    ("POST", "/api/enterprise/client-portal/auth/exchange"),
+}
+
 
 def create_portal_session_token(email: str, mode: str = "prod") -> str:
     """Mint a Client Portal session token for a verified email. Carries no
@@ -330,6 +362,24 @@ async def get_current_user(request: Request, token: str = Depends(oauth2_scheme)
             # agent (see _enforce_connector_scope). The key is minted by an
             # entitled module; core only recognizes + enforces the scope.
             connector_agent = mcp_key_info.get("agent_name") if scope == "connector" else None
+            # ent#163: a delegated-portal key is fenced to the single exchange
+            # route. Enforced HERE at the one auth entry point — not only in the
+            # portal router — for the same reason as the connector fence above:
+            # this principal resolves to the key OWNER, so any endpoint doing an
+            # inline access check would otherwise treat it as that human. The
+            # key's whole job is to mint a portal session; it never needs to
+            # reach anything else, including the portal endpoints themselves.
+            portal_delegate = scope == PORTAL_DELEGATE_SCOPE
+            if portal_delegate and (
+                (request.method.upper(), request.url.path) not in PORTAL_DELEGATE_ALLOWED_ROUTES
+            ):
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=(
+                        "Portal delegate keys may only exchange an end-user email "
+                        "for a portal session"
+                    ),
+                )
             if connector_agent:
                 # Central containment (ent#46): a connector key may reach ONLY
                 # its bound agent's chat + connector playbook list. Enforced here
@@ -365,6 +415,7 @@ async def get_current_user(request: Request, token: str = Depends(oauth2_scheme)
                 role=user["role"],
                 agent_name=agent_name,
                 connector_agent=connector_agent,
+                portal_delegate=portal_delegate,
             )
 
     # Both JWT and MCP key failed

src/backend/models.py

@@ -207,6 +207,13 @@ class User(BaseModel):
     # key itself is minted by an entitled module (core-primitive + enterprise-
     # knob, same shape as users.suspended_at #995).
     connector_agent: Optional[str] = None
+    # ent#163: True for a `portal_delegate` MCP key — a trusted issuer that may
+    # exchange an asserted end-user email for a portal session, and NOTHING else
+    # (fenced centrally in `dependencies.get_current_user`). Like every MCP key
+    # it resolves to the key OWNER, so a consumer must branch on this flag
+    # rather than on the resolved user: the whole point of the request is that
+    # it concerns somebody other than the owner.
+    portal_delegate: bool = False
 
 
 class Token(BaseModel):

src/backend/routers/mcp_keys.py

@@ -6,7 +6,12 @@
 
 from models import User
 from database import db, McpApiKeyCreate, McpApiKey, McpApiKeyWithSecret
-from dependencies import get_current_user
+from dependencies import (
+    PORTAL_DELEGATE_SCOPE,
+    assert_admin,
+    get_current_user,
+    reject_agent_principal,
+)
 from services.platform_audit_service import platform_audit_service, AuditEventType
 
 router = APIRouter(prefix="/api/mcp", tags=["mcp"])
@@ -21,7 +26,27 @@ async def create_mcp_api_key_endpoint(
     """
     Create a new MCP API key for the current user.
     The full API key is only returned once during creation - store it securely.
+
+    Scope is `user` unless explicitly requested. `portal_delegate` (ent#163) is
+    admin-only: it lets the holder act as any end user who has portal access, so
+    it must never be self-issuable by an ordinary account.
     """
+    requested_scope = (getattr(key_data, "scope", None) or "user").strip()
+    if requested_scope != "user":
+        if requested_scope != PORTAL_DELEGATE_SCOPE:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unsupported key scope '{requested_scope}'",
+            )
+        # Human-only AND admin. `assert_admin` alone is not enough: it rejects
+        # connector principals but not agent-scoped ones, and an agent key
+        # resolves to its OWNER carrying the owner's role — on a default
+        # admin-owned install that passes a bare role check outright
+        # (trinity-ops-agent#232). Minting an impersonation key is a human
+        # decision, so the agent guard runs first.
+        reject_agent_principal(current_user)
+        assert_admin(current_user)
+
     try:
         api_key = db.create_mcp_api_key(current_user.username, key_data)
 

src/frontend/src/components/settings/McpKeysTab.vue

@@ -86,6 +86,14 @@
                   <span v-else-if="key.scope === 'system'" class="ml-2 inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-status-urgent-100 dark:bg-status-urgent-900/50 text-status-urgent-800 dark:text-status-urgent-300">
                     System
                   </span>
+                  <!-- ent#163: this key can act as ANY end user with portal
+                       access, so it must never render like an ordinary user
+                       key on the page where an admin audits keys. -->
+                  <span v-else-if="key.scope === 'portal_delegate'"
+                        class="ml-2 inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-status-warning-100 dark:bg-status-warning-900/50 text-status-warning-800 dark:text-status-warning-300"
+                        title="Can exchange an end-user email for a portal session — treat as a delegated-identity credential">
+                    Portal Delegate
+                  </span>
                 </div>
                 <p v-if="key.description" class="mt-1 text-sm text-gray-500 dark:text-gray-400">{{ key.description }}</p>
                 <div class="mt-1 flex items-center text-xs text-gray-400 dark:text-gray-500 space-x-4">
@@ -158,6 +166,23 @@
                   placeholder="Used for..."
                 ></textarea>
               </div>
+
+              <!-- ent#163. Admin-only, and deliberately opt-in rather than a
+                   default: a delegate key acts as other people, so creating one
+                   should be a conscious choice, never a stray click. -->
+              <div v-if="isAdmin">
+                <label class="flex items-start gap-2 cursor-pointer">
+                  <input type="checkbox" v-model="newKey.portalDelegate" class="mt-0.5 rounded text-action-primary-600 focus:ring-action-primary-500" />
+                  <span class="text-sm text-gray-700 dark:text-gray-300">
+                    Portal delegate key
+                    <span class="block text-xs text-gray-500 dark:text-gray-400">
+                      Lets a trusted backend exchange one of your client emails for a
+                      portal session — it acts as that person. It can do nothing else:
+                      every other endpoint is refused. Revoke it to stop delegation.
+                    </span>
+                  </span>
+                </label>
+              </div>
             </div>
           </div>
 
@@ -326,7 +351,8 @@ const copiedConfig = ref(false)
 
 const newKey = ref({
   name: '',
-  description: ''
+  description: '',
+  portalDelegate: false
 })
 
 const confirmDialog = reactive({
@@ -432,7 +458,10 @@ const createKey = async () => {
       },
       body: JSON.stringify({
         name: newKey.value.name,
-        description: newKey.value.description || null
+        description: newKey.value.description || null,
+        // Omitted (not `null`) for an ordinary key so the backend
+        // default stands and nothing changes for existing callers.
+        ...(newKey.value.portalDelegate ? { scope: 'portal_delegate' } : {})
       })
     })
 
@@ -441,7 +470,7 @@ const createKey = async () => {
       createdApiKey.value = data.api_key
       showCreateModal.value = false
       showKeyModal.value = true
-      newKey.value = { name: '', description: '' }
+      newKey.value = { name: '', description: '', portalDelegate: false }
       await fetchApiKeys()
     } else {
       const error = await response.json()