A connection is one signed-in account; the SDK reads them per account

The grant slot dies. oauth_connections holds one row per sign-in — N per
provider — owned by the druks account that completed the consent, and the
engine's cache and refresh lock key on the connection id. The declaration
becomes Gmail.with_scopes(...): it feeds the consent union, and workflow
code loops the sign-ins through it — list_for_account(account_id), then
mint_access_token() on each connection.

The connect door creates a connection for the session account, or
reconsents an existing one via ?connection=<id>. Settings grows the
Connections page — everything the user has authenticated to, revoked per
connection — and the service detail lists that service's sign-ins. MCP
keeps its one-per-(server, account) policy over the same table.

Author: czpython

backend/druks/mcp/models.py

@@ -17,7 +17,7 @@
 from druks.mcp.helpers import get_grant_account, grant_provider
 from druks.models import Base
 from druks.secrets.fields import EncryptedJsonField, EncryptedTextField, Secret
-from druks.services.models import OauthGrant
+from druks.services.models import OauthConnection
 
 
 class McpServer(Base, Uuid7Pk):
@@ -109,7 +109,9 @@ def get_resolved(cls, account_id: str | None) -> dict[str, dict]:
                 if server["identity_mode"]:
                     grant_account = get_grant_account(server["identity_mode"], account_id)
                     server["has_token"] = bool(
-                        OauthGrant.get_for_account(grant_provider(server["name"]), grant_account)
+                        OauthConnection.list_for_account(
+                            grant_provider(server["name"]), grant_account
+                        )
                     )
             else:
                 server["has_token"] = bool(server["token"])
@@ -174,7 +176,7 @@ class McpClientRegistration(Base, Uuid7Pk):
 
     # One RFC 7591 registration per grant: druks registers a fresh client on
     # every connect, so each account's grant refreshes as the client it
-    # consented through. The grant itself lives on the platform's OauthGrant.
+    # consented through. The refresh token lives on the platform's OauthConnection.
     server_id: Mapped[str] = mapped_column(ForeignKey("mcp_servers.id", ondelete="CASCADE"))
     account_id: Mapped[str] = mapped_column(
         ForeignKey("accounts.id", ondelete="RESTRICT"), default=SYSTEM_ACCOUNT_ID

backend/druks/mcp/oauth.py

@@ -12,7 +12,7 @@
 from druks.mcp.models import McpClientRegistration, McpServer
 from druks.services import OauthClient, OauthExchangeError, OauthRefreshError
 from druks.services.constants import OAUTH_MINT_WAIT_ATTEMPTS, OAUTH_MINT_WAIT_INTERVAL_SECONDS
-from druks.services.models import OauthGrant
+from druks.services.models import OauthConnection
 from druks.services.oauth import complete_connect as complete_oauth_exchange
 
 
@@ -21,12 +21,14 @@ def _http() -> httpx.AsyncClient:
     return httpx.AsyncClient(timeout=30.0, follow_redirects=True)
 
 
-def get_grant(name: str, account_id: str) -> OauthGrant | None:
-    return OauthGrant.get_for_account(grant_provider(name), account_id)
+def get_connection(name: str, account_id: str) -> OauthConnection | None:
+    # One connection per (server, account) — MCP's policy over the shared table.
+    rows = OauthConnection.list_for_account(grant_provider(name), account_id)
+    return rows[0] if rows else None
 
 
-def list_grants(name: str) -> list[OauthGrant]:
-    return OauthGrant.list_for_provider(grant_provider(name))
+def list_connections(name: str) -> list[OauthConnection]:
+    return OauthConnection.list_for_provider(grant_provider(name))
 
 
 def _origin(url: str) -> str:
@@ -232,22 +234,31 @@ async def complete_connect(*, state: str, code: str) -> str:
         client_id=pending["client_id"],
         client_secret=pending["client_secret"],
     )
-    OauthGrant.store(
-        provider=grant_provider(name),
-        account_id=account_id,
-        refresh_token=tokens["refresh_token"],
-    )
-    # A reconsent's stale cached token must not serve until its TTL runs out.
-    await evict_access_token(name, account_id)
+    connection = get_connection(name, account_id)
+    if connection:
+        connection.reconnect(refresh_token=tokens["refresh_token"], scopes=[])
+        # A reconsent's stale cached token must not serve until its TTL runs out.
+        await evict_access_token(name, account_id)
+    else:
+        OauthConnection.create(
+            provider=grant_provider(name),
+            account_id=account_id,
+            refresh_token=tokens["refresh_token"],
+            scopes=[],
+        )
     return name
 
 
 async def evict_access_token(name: str, account_id: str) -> None:
-    await OauthClient(provider=grant_provider(name)).evict_access_token(account_id)
+    connection = get_connection(name, account_id)
+    if connection:
+        await OauthClient(provider=grant_provider(name)).evict_access_token(connection.id)
 
 
 async def disconnect(name: str, account_id: str) -> None:
-    await OauthClient(provider=grant_provider(name)).disconnect(account_id)
+    connection = get_connection(name, account_id)
+    if connection:
+        await OauthClient(provider=grant_provider(name)).disconnect(connection)
     registration = McpClientRegistration.get_for_account(name, account_id)
     if registration:
         registration.delete()
@@ -257,9 +268,10 @@ async def mint_access_token(name: str, account_id: str) -> str:
     """The delivery-side token for a connected server, minted by the shared
     engine from this server's grant — delivery never ships a server the agent
     can't authenticate to."""
+    connection = get_connection(name, account_id)
     registration = McpClientRegistration.get_for_account(name, account_id)
     server = McpServer.get_for_name(name)
-    if not registration or not server:
+    if not connection or not registration or not server:
         raise MissingGrantError(name, account_id)
     client = OauthClient(
         provider=grant_provider(name),
@@ -273,6 +285,6 @@ async def mint_access_token(name: str, account_id: str) -> str:
         mint_wait_attempts=OAUTH_MINT_WAIT_ATTEMPTS,
     )
     try:
-        return await client.mint_access_token(account_id=account_id)
+        return await client.mint_access_token(connection=connection)
     except OauthRefreshError as error:
         raise GrantRefreshError(name, error.reason) from error

backend/druks/mcp/routes.py

@@ -163,11 +163,11 @@ async def remove_mcp_server(name: str) -> None:
     server = McpServer.get_for_name(name)
     if not server:
         raise HTTPException(status_code=404, detail=f"MCP server {name!r} not found")
-    grants = oauth.list_grants(name)
+    connections = oauth.list_connections(name)
     server.delete()
-    for grant in grants:
-        grant.delete()
-        await oauth.evict_access_token(name, grant.account_id)
+    for connection in connections:
+        await oauth.evict_access_token(name, connection.account_id)
+        connection.delete()
 
 
 @router.post("/{name}/connect", response_model=ConnectMcpServerResponse)
@@ -179,7 +179,7 @@ async def connect_mcp_server(
     server = McpServer.get_resolved(current_account_id.get()).get(name)
     if not server or server["token_source"] != TokenSource.OAUTH:
         raise HTTPException(status_code=404, detail=f"MCP server {name!r} is not an OAuth server.")
-    if oauth.list_grants(name) and server["identity_mode"] != identity_mode:
+    if oauth.list_connections(name) and server["identity_mode"] != identity_mode:
         raise HTTPException(
             status_code=409,
             detail=f"MCP server {name!r} already uses {server['identity_mode']!r} identity.",
@@ -238,14 +238,14 @@ async def disconnect_mcp_server(name: str) -> None:
     if not server["identity_mode"]:
         raise HTTPException(status_code=404, detail=f"MCP server {name!r} has no grant.")
     account_id = get_grant_account(server["identity_mode"], current_account_id.get())
-    grant = oauth.get_grant(name, account_id)
-    if not grant:
+    connection = oauth.get_connection(name, account_id)
+    if not connection:
         raise HTTPException(
             status_code=404,
             detail=f"MCP server {name!r} has no grant for account {account_id!r}.",
         )
     await oauth.disconnect(name, account_id)
-    if not oauth.list_grants(name):
+    if not oauth.list_connections(name):
         # The last grant leaving reopens the mode choice: the next connect is
         # a first connect again.
         server_row = McpServer.get_for_name(name)

backend/druks/services/base.py

@@ -2,21 +2,48 @@
 
 from pydantic import BaseModel, ValidationError
 
-from druks.accounts.constants import SYSTEM_ACCOUNT_ID
 from druks.extensions.base import NAME_RE
 from druks.extensions.loader import iter_extensions
 from druks.extensions.registry import services
 from druks.extensions.settings import field_kind, field_multiline
 
 from .exceptions import ServiceConnectError, ServiceNotConnectedError
-from .models import OauthGrant, ServiceIdentity
+from .models import OauthConnection, ServiceIdentity
 from .oauth import OauthClient
 
 
-class ServiceConnection:
-    """One extension's declared use of a service — the class attribute
-    (``acme = Acme.connection("profile.read")``) is both the declaration
-    and the mint handle."""
+class Connection:
+    """One signed-in provider account, reached through the extension's
+    declared handle. Mint and disconnect act on this sign-in only."""
+
+    def __init__(self, service: "type[Service]", row: OauthConnection) -> None:
+        self.service = service
+        self.row = row
+
+    @property
+    def id(self) -> str:
+        return self.row.id
+
+    @property
+    def scopes(self) -> list[str]:
+        return self.row.scopes
+
+    @property
+    def connected_at(self):
+        return self.row.connected_at
+
+    async def mint_access_token(self) -> str:
+        return await self.service.get_oauth_client().mint_access_token(connection=self.row)
+
+    async def disconnect(self) -> None:
+        await OauthClient(provider=self.service.name).disconnect(self.row)
+
+
+class ScopedService:
+    """A service seen through one extension's declared scopes
+    (``gmail = Gmail.with_scopes("gmail.readonly")``). The declaration
+    feeds the consent union; the handle reads the connections that grant
+    it."""
 
     def __init__(self, service: "type[Service]", scopes: tuple[str, ...]) -> None:
         self.service = service
@@ -30,8 +57,16 @@ def __set_name__(self, owner: type, name: str) -> None:
     def label(self) -> str:
         return f"{self.owner.name}.{self.name}"
 
-    async def mint_access_token(self) -> str:
-        return await self.service.mint_access_token()
+    def list_for_account(self, account_id: str) -> list[Connection]:
+        return [
+            Connection(self.service, row)
+            for row in OauthConnection.list_for_account(self.service.name, account_id)
+        ]
+
+    def get(self, connection_id: str) -> Connection | None:
+        row = OauthConnection.get(connection_id)
+        if row and row.provider == self.service.name:
+            return Connection(self.service, row)
 
 
 class Service:
@@ -115,53 +150,28 @@ def get(cls) -> ServiceIdentity:
         return ServiceIdentity.get(cls.name)
 
     @classmethod
-    def connection(cls, *scopes: str) -> ServiceConnection:
+    def with_scopes(cls, *scopes: str) -> ScopedService:
         """Declare this extension's use of the service and the scopes its
         calls need."""
         if not cls.token_endpoint:
             raise TypeError(f"{cls.__name__} declares no OAuth endpoints")
-        return ServiceConnection(cls, scopes)
+        return ScopedService(cls, scopes)
 
     @classmethod
-    def connections(cls) -> "list[ServiceConnection]":
+    def declarations(cls) -> "list[ScopedService]":
         return [
             value
             for extension in iter_extensions()
             for value in vars(extension).values()
-            if isinstance(value, ServiceConnection) and value.service is cls
+            if isinstance(value, ScopedService) and value.service is cls
         ]
 
     @classmethod
     def required_scopes(cls) -> tuple[str, ...]:
         """The union of every installed declaration's scopes — the consent ask."""
-        scopes = {scope for connection in cls.connections() for scope in connection.scopes}
+        scopes = {scope for declaration in cls.declarations() for scope in declaration.scopes}
         return tuple(sorted(scopes))
 
-    # The grant is the appliance's own consent at the provider; v1 holds one,
-    # under the system account.
-    @classmethod
-    def get_grant(cls) -> "OauthGrant | None":
-        return OauthGrant.get_for_account(cls.name, SYSTEM_ACCOUNT_ID)
-
-    @classmethod
-    async def store_grant(cls, *, refresh_token: str, scopes: list[str]) -> None:
-        OauthGrant.store(
-            provider=cls.name,
-            account_id=SYSTEM_ACCOUNT_ID,
-            refresh_token=refresh_token,
-            scopes=scopes,
-        )
-        # A reconsent's narrower cached token must not serve until its TTL runs out.
-        await OauthClient(provider=cls.name).evict_access_token(SYSTEM_ACCOUNT_ID)
-
-    @classmethod
-    async def disconnect_grant(cls) -> None:
-        await OauthClient(provider=cls.name).disconnect(SYSTEM_ACCOUNT_ID)
-
-    @classmethod
-    async def mint_access_token(cls) -> str:
-        return await cls.get_oauth_client().mint_access_token(account_id=SYSTEM_ACCOUNT_ID)
-
     @classmethod
     def get_oauth_client(cls) -> OauthClient:
         """The connected identity as a configured ``OauthClient``, keyed by