Updated CLI

trustgraph-flow/trustgraph/gateway/capabilities.py

@@ -1,18 +1,36 @@
 """
-Capability vocabulary and OSS role bundles.
+Capability vocabulary, role definitions, and authorisation helpers.
 
 See docs/tech-specs/capabilities.md for the authoritative description.
-The mapping below is the data form of the OSS bundle table in that
-spec.  Enterprise editions may replace this module with their own
-role table; the vocabulary (capability strings) is shared.
+The data here is the OSS bundle table in that spec.  Enterprise
+editions may replace this module with their own role table; the
+vocabulary (capability strings) is shared.
 
-The module also exposes:
+Role model
+----------
+A role has two dimensions:
 
-- ``PUBLIC`` — a sentinel indicating an endpoint requires no
-  authentication (login, bootstrap).
-- ``AUTHENTICATED`` — a sentinel indicating an endpoint requires a
-  valid identity but no specific capability (e.g. change-password).
-- ``check(roles, capability)`` — the union-of-bundles membership test.
+  1. **capability set** — which operations the role grants.
+  2. **workspace scope** — which workspaces the role is active in.
+
+The authorisation question is: *given the caller's roles, a required
+capability, and a target workspace, does any role grant the
+capability AND apply to the target workspace?*
+
+Workspace scope values recognised here:
+
+  - ``"assigned"`` — the role applies only to the caller's own
+    assigned workspace (stored on their user record).
+  - ``"*"`` — the role applies to every workspace.
+
+Enterprise editions can add richer scopes (explicit permitted-set,
+patterns, etc.) without changing the wire protocol.
+
+Sentinels
+---------
+- ``PUBLIC`` — endpoint requires no authentication.
+- ``AUTHENTICATED`` — endpoint requires a valid identity, no
+  specific capability.
 """
 
 from aiohttp import web
@@ -23,8 +41,8 @@ AUTHENTICATED = "__authenticated__"
 
 
 # Capability vocabulary.  Mirrors the "Capability list" tables in
-# capabilities.md.  Kept as a set of valid strings so the gateway can
-# fail-closed on an endpoint that declares an unknown capability.
+# capabilities.md.  Kept as a set so the gateway can fail-closed on
+# an endpoint that declares an unknown capability.
 KNOWN_CAPABILITIES = {
     # Data plane
     "agent",
@@ -47,7 +65,7 @@ KNOWN_CAPABILITIES = {
 }
 
 
-# OSS role → capability set.  Enterprise overrides this mapping.
+# Capability sets used below.
 _READER_CAPS = {
     "agent",
     "graph:read",
@@ -81,23 +99,62 @@ _ADMIN_CAPS = _WRITER_CAPS | {
     "metrics:read",
 }
 
-ROLE_CAPABILITIES = {
-    "reader": _READER_CAPS,
-    "writer": _WRITER_CAPS,
-    "admin": _ADMIN_CAPS,
+
+# Role definitions.  Each role has a capability set and a workspace
+# scope.  Enterprise overrides this mapping.
+ROLE_DEFINITIONS = {
+    "reader": {
+        "capabilities": _READER_CAPS,
+        "workspace_scope": "assigned",
+    },
+    "writer": {
+        "capabilities": _WRITER_CAPS,
+        "workspace_scope": "assigned",
+    },
+    "admin": {
+        "capabilities": _ADMIN_CAPS,
+        "workspace_scope": "*",
+    },
 }
 
 
-def check(roles, capability):
-    """Return True if any of ``roles`` grants ``capability``.
-
-    Unknown roles contribute zero capabilities (deterministic fail-
-    closed behaviour per the spec)."""
-    if capability not in KNOWN_CAPABILITIES:
-        # Endpoint misconfiguration.  Fail closed.
+def _scope_permits(role_name, target_workspace, assigned_workspace):
+    """Does the given role apply to ``target_workspace``?"""
+    role = ROLE_DEFINITIONS.get(role_name)
+    if role is None:
         return False
-    for r in roles:
-        if capability in ROLE_CAPABILITIES.get(r, ()):
+    scope = role["workspace_scope"]
+    if scope == "*":
+        return True
+    if scope == "assigned":
+        return target_workspace == assigned_workspace
+    # Future scope types (lists, patterns) extend here.
+    return False
+
+
+def check(identity, capability, target_workspace=None):
+    """Is ``identity`` permitted to invoke ``capability`` on
+    ``target_workspace``?
+
+    Passes iff some role held by the caller both (a) grants
+    ``capability`` and (b) is active in ``target_workspace``.
+
+    ``target_workspace`` defaults to the caller's assigned workspace,
+    which makes this function usable for system-level operations and
+    for authenticated endpoints that don't take a workspace argument
+    (the call collapses to "do any of my roles grant this cap?")."""
+    if capability not in KNOWN_CAPABILITIES:
+        return False
+
+    target = target_workspace or identity.workspace
+
+    for role_name in identity.roles:
+        role = ROLE_DEFINITIONS.get(role_name)
+        if role is None:
+            continue
+        if capability not in role["capabilities"]:
+            continue
+        if _scope_permits(role_name, target, identity.workspace):
             return True
     return False
 
@@ -117,18 +174,21 @@ def auth_failure():
 
 
 async def enforce(request, auth, capability):
-    """Authenticate + capability-check in one step.  Returns an
-    ``Identity`` (or ``None`` for ``PUBLIC`` endpoints) or raises
-    the appropriate HTTPException.
+    """Authenticate + capability-check for endpoints that carry no
+    workspace dimension on the request (metrics, i18n, etc.).
 
-    Usage in an endpoint handler:
+    For endpoints that carry a workspace field on the body, call
+    :func:`enforce_workspace` *after* parsing the body to validate
+    the workspace and re-check the capability in that scope.  Most
+    endpoints do both.
 
-        identity = await enforce(request, self.auth, self.capability)
-
-    - ``PUBLIC``: no authentication attempted, returns ``None``.
-    - ``AUTHENTICATED``: any valid identity is accepted.
-    - any capability string: identity must carry a role granting it.
-    """
+    - ``PUBLIC``: no authentication, returns ``None``.
+    - ``AUTHENTICATED``: any valid identity.
+    - capability string: identity must have it, checked against the
+      caller's assigned workspace (adequate for endpoints whose
+      capability is system-level, e.g. ``metrics:read``, or where
+      the real workspace-aware check happens in
+      :func:`enforce_workspace` after body parsing)."""
     if capability == PUBLIC:
         return None
 
@@ -137,27 +197,42 @@ async def enforce(request, auth, capability):
     if capability == AUTHENTICATED:
         return identity
 
-    if not check(identity.roles, capability):
+    if not check(identity, capability):
         raise access_denied()
 
     return identity
 
 
-def enforce_workspace(data, identity):
-    """Validate + inject the workspace field on a request body.
+def enforce_workspace(data, identity, capability=None):
+    """Resolve + validate the workspace on a request body.
 
-    OSS behaviour:
-      - If ``data["workspace"]`` is present and differs from the
-        caller's assigned workspace → 403.
-      - Otherwise, set ``data["workspace"]`` to the caller's assigned
-        workspace.
+    - Target workspace = ``data["workspace"]`` if supplied, else the
+      caller's assigned workspace.
+    - At least one of the caller's roles must (a) be active in the
+      target workspace and, if ``capability`` is given, (b) grant
+      ``capability``.  Otherwise 403.
+    - On success, ``data["workspace"]`` is overwritten with the
+      resolved value — callers can rely on the outgoing message
+      having the gateway's chosen workspace rather than any
+      caller-supplied value.
 
-    Enterprise editions will plug in a different resolver that
-    checks a permitted-set instead of a single value; the wire
-    protocol is unchanged."""
-    requested = data.get("workspace", "") if isinstance(data, dict) else ""
-    if requested and requested != identity.workspace:
-        raise access_denied()
-    if isinstance(data, dict):
-        data["workspace"] = identity.workspace
-    return data
+    For ``capability=None`` the workspace scope alone is checked —
+    useful when the body has a workspace but the endpoint already
+    passed its capability check (e.g. via :func:`enforce`)."""
+    if not isinstance(data, dict):
+        return data
+
+    requested = data.get("workspace", "")
+    target = requested or identity.workspace
+
+    for role_name in identity.roles:
+        role = ROLE_DEFINITIONS.get(role_name)
+        if role is None:
+            continue
+        if capability is not None and capability not in role["capabilities"]:
+            continue
+        if _scope_permits(role_name, target, identity.workspace):
+            data["workspace"] = target
+            return data
+
+    raise access_denied()

trustgraph-flow/trustgraph/gateway/dispatch/mux.py

@@ -122,35 +122,34 @@ class Mux:
                 })
                 return
 
-            # Workspace resolution.  Authenticated sockets override
-            # any client-supplied workspace — on both the envelope and
-            # the inner request payload — with the resolved value from
-            # the identity.  A mismatched value at either layer is an
-            # access-denied error.  Injecting into the inner request
-            # means clients don't have to repeat the workspace in
-            # every payload; the same convenience HTTP callers get
-            # via enforce_workspace.
+            # Workspace resolution.  On authenticated sockets the
+            # gateway's role-scope rules apply: role workspace scope
+            # determines which target workspaces are permitted.  The
+            # resolved value is written to both the envelope and the
+            # inner request payload so clients don't have to repeat it
+            # per-message (same convenience HTTP callers get via
+            # enforce_workspace).
             if self.identity is not None:
-                for layer, blob in (
-                        ("envelope", data),
-                        ("inner", data.get("request")),
-                ):
-                    if not isinstance(blob, dict):
-                        continue
-                    req = blob.get("workspace", "")
-                    if req and req != self.identity.workspace:
-                        await self.ws.send_json({
-                            "id": request_id,
-                            "error": {
-                                "message": "access denied",
-                                "type": "access-denied",
-                            },
-                            "complete": True,
-                        })
-                        return
-                    blob["workspace"] = self.identity.workspace
+                from ..capabilities import enforce_workspace
+                from aiohttp import web as _web
 
-                workspace = self.identity.workspace
+                try:
+                    enforce_workspace(data, self.identity)
+                    inner = data.get("request")
+                    if isinstance(inner, dict):
+                        enforce_workspace(inner, self.identity)
+                except _web.HTTPForbidden:
+                    await self.ws.send_json({
+                        "id": request_id,
+                        "error": {
+                            "message": "access denied",
+                            "type": "access-denied",
+                        },
+                        "complete": True,
+                    })
+                    return
+
+                workspace = data["workspace"]
             else:
                 workspace = data.get("workspace", "default")
 

trustgraph-flow/trustgraph/gateway/endpoint/manager.py

@@ -168,7 +168,7 @@ class _RoutedSocketEndpoint:
             )
         except web.HTTPException as e:
             return e
-        if not check(identity.roles, cap):
+        if not check(identity, cap):
             return access_denied()
 
         # Delegate the websocket handling to a standalone SocketEndpoint

trustgraph-flow/trustgraph/gateway/endpoint/socket.py

@@ -97,7 +97,7 @@ class SocketEndpoint:
             except web.HTTPException as e:
                 return e
             if self.capability != AUTHENTICATED:
-                if not check(identity.roles, self.capability):
+                if not check(identity, self.capability):
                     return access_denied()
 
         # 50MB max message size

trustgraph-flow/trustgraph/iam/service/iam.py

@@ -234,6 +234,8 @@ class IamService:
                 return await self.handle_update_user(v)
             if op == "disable-user":
                 return await self.handle_disable_user(v)
+            if op == "enable-user":
+                return await self.handle_enable_user(v)
             if op == "create-workspace":
                 return await self.handle_create_workspace(v)
             if op == "list-workspaces":
@@ -711,6 +713,23 @@ class IamService:
 
         return IamResponse()
 
+    async def handle_enable_user(self, v):
+        """Re-enable a previously disabled user.  Does not restore
+        API keys — those have to be re-issued by the admin."""
+        if not v.workspace:
+            return _err("invalid-argument", "workspace required")
+        if not v.user_id:
+            return _err("invalid-argument", "user_id required")
+
+        _, err = await self._user_in_workspace(v.user_id, v.workspace)
+        if err is not None:
+            return err
+
+        await self.table_store.update_user_enabled(
+            id=v.user_id, enabled=True,
+        )
+        return IamResponse()
+
     # ------------------------------------------------------------------
     # Workspace CRUD
     # ------------------------------------------------------------------