feat: IAM service, gateway auth middleware, capability model, and CLIs (#849)

Replaces the legacy GATEWAY_SECRET shared-token gate with an IAM-backed
identity and authorisation model.  The gateway no longer has an
"allow-all" or "no auth" mode; every request is authenticated via the
IAM service, authorised against a capability model that encodes both
the operation and the workspace it targets, and rejected with a
deliberately-uninformative 401 / 403 on any failure.

IAM service (trustgraph-flow/trustgraph/iam, trustgraph-base/schema/iam)
-----------------------------------------------------------------------
* New backend service (iam-svc) owning users, workspaces, API keys,
  passwords and JWT signing keys in Cassandra.  Reached over the
  standard pub/sub request/response pattern; gateway is the only
  caller.
* Operations: bootstrap, resolve-api-key, login, get-signing-key-public,
  rotate-signing-key, create/list/get/update/disable/delete/enable-user,
  change-password, reset-password, create/list/get/update/disable-
  workspace, create/list/revoke-api-key.
* Ed25519 JWT signing (alg=EdDSA).  Key rotation writes a new kid and
  retires the previous one; validation is grace-period friendly.
* Passwords: PBKDF2-HMAC-SHA-256, 600k iterations, per-user salt.
* API keys: 128-bit random, SHA-256 hashed.  Plaintext returned once.
* Bootstrap is explicit: --bootstrap-mode {token,bootstrap} is a
  required startup argument with no permissive default.  Masked
  "auth failure" errors hide whether a refused bootstrap request was
  due to mode, state, or authorisation.

Gateway authentication (trustgraph-flow/trustgraph/gateway/auth.py)
-------------------------------------------------------------------
* IamAuth replaces the legacy Authenticator.  Distinguishes JWTs
  (three-segment dotted) from API keys by shape; verifies JWTs
  locally using the cached IAM public key; resolves API keys via
  IAM with a short-TTL hash-keyed cache.  Every failure path
  surfaces the same 401 body ("auth failure") so callers cannot
  enumerate credential state.
* Public key is fetched at gateway startup with a bounded retry loop;
  traffic does not begin flowing until auth has started.

Capability model (trustgraph-flow/trustgraph/gateway/capabilities.py)
---------------------------------------------------------------------
* Roles have two dimensions: a capability set and a workspace scope.
  OSS ships reader / writer / admin; the first two are workspace-
  assigned, admin is cross-workspace ("*").  No "cross-workspace"
  pseudo-capability — workspace permission is a property of the role.
* check(identity, capability, target_workspace=None) is the single
  authorisation test: some role must grant the capability *and* be
  active in the target workspace.
* enforce_workspace validates a request-body workspace against the
  caller's role scopes and injects the resolved value.  Cross-
  workspace admin is permitted by role scope, not by a bypass.
* Gateway endpoints declare a required capability explicitly — no
  permissive default.  Construction fails fast if omitted.  Enterprise
  editions can replace the role table without changing the wire
  protocol.

WebSocket first-frame auth (dispatch/mux.py, endpoint/socket.py)
----------------------------------------------------------------
* /api/v1/socket handshake unconditionally accepts; authentication
  runs on the first WebSocket frame ({"type":"auth","token":"..."})
  with {"type":"auth-ok","workspace":"..."} / {"type":"auth-failed"}.
  The socket stays open on failure so the client can re-authenticate
  — browsers treat a handshake-time 401 as terminal, breaking
  reconnection.
* Mux.receive rejects every non-auth frame before auth succeeds,
  enforces the caller's workspace (envelope + inner payload) using
  the role-scope resolver, and supports mid-session re-auth.
* Flow import/export streaming endpoints keep the legacy ?token=
  handshake (URL-scoped short-lived transfers; no re-auth need).

Auth surface
------------
* POST /api/v1/auth/login — public, returns a JWT.
* POST /api/v1/auth/bootstrap — public; forwards to IAM's bootstrap
  op which itself enforces mode + tables-empty.
* POST /api/v1/auth/change-password — any authenticated user.
* POST /api/v1/iam — admin-only generic forwarder for the rest of
  the IAM API (per-op REST endpoints to follow in a later change).

Removed / breaking
------------------
* GATEWAY_SECRET / --api-token / default_api_token and the legacy
  Authenticator.permitted contract.  The gateway cannot run without
  IAM.
* ?token= on /api/v1/socket.
* DispatcherManager and Mux both raise on auth=None — no silent
  downgrade path.

CLI tools (trustgraph-cli)
--------------------------
tg-bootstrap-iam, tg-login, tg-create-user, tg-list-users,
tg-disable-user, tg-enable-user, tg-delete-user, tg-change-password,
tg-reset-password, tg-create-api-key, tg-list-api-keys,
tg-revoke-api-key, tg-create-workspace, tg-list-workspaces.  Passwords
read via getpass; tokens / one-time secrets written to stdout with
operator context on stderr so shell composition works cleanly.
AsyncSocketClient / SocketClient updated to the first-frame auth
protocol.

Specifications
--------------
* docs/tech-specs/iam.md updated with the error policy, workspace
  resolver extension point, and OSS role-scope model.
* docs/tech-specs/iam-protocol.md (new) — transport, dataclasses,
  operation table, error taxonomy, bootstrap modes.
* docs/tech-specs/capabilities.md (new) — capability vocabulary, OSS
  role bundles, agent-as-composition note, enforcement-boundary
  policy, enterprise extensibility.

Tests
-----
* test_auth.py (rewritten) — IamAuth + JWT round-trip with real
  Ed25519 keypairs + API-key cache behaviour.
* test_capabilities.py (new) — role table sanity, check across
  role x workspace combinations, enforce_workspace paths,
  unknown-cap / unknown-role fail-closed.
* Every endpoint test construction now names its capability
  explicitly (no permissive defaults relied upon).  New tests pin
  the fail-closed invariants: DispatcherManager / Mux refuse
  auth=None; i18n path-traversal defense is exercised.
* test_socket_graceful_shutdown rewritten against IamAuth.

tests/unit/test_gateway/test_socket_graceful_shutdown.py

@@ -1,4 +1,15 @@
-"""Unit tests for SocketEndpoint graceful shutdown functionality."""
+"""Unit tests for SocketEndpoint graceful shutdown functionality.
+
+These tests exercise SocketEndpoint in its handshake-auth
+configuration (``in_band_auth=False``) — the mode used in production
+for the flow import/export streaming endpoints.  The mux socket at
+``/api/v1/socket`` uses ``in_band_auth=True`` instead, where the
+handshake always accepts and authentication runs on the first
+WebSocket frame; that path is covered by the Mux tests.
+
+Every endpoint constructor here passes an explicit capability — no
+permissive default is relied upon.
+"""
 
 import pytest
 import asyncio
@@ -6,13 +17,31 @@ from unittest.mock import AsyncMock, MagicMock, patch
 from aiohttp import web, WSMsgType
 from trustgraph.gateway.endpoint.socket import SocketEndpoint
 from trustgraph.gateway.running import Running
+from trustgraph.gateway.auth import Identity
+
+
+# Representative capability used across these tests — corresponds to
+# the flow-import streaming endpoint pattern that uses this class.
+TEST_CAP = "graph:write"
+
+
+def _valid_identity(roles=("admin",)):
+    return Identity(
+        user_id="test-user",
+        workspace="default",
+        roles=list(roles),
+        source="api-key",
+    )
 
 
 @pytest.fixture
 def mock_auth():
-    """Mock authentication service."""
+    """Mock IAM-backed authenticator.  Successful by default —
+    ``authenticate`` returns a valid admin identity.  Tests that
+    need the auth failure path override the ``authenticate``
+    attribute locally."""
     auth = MagicMock()
-    auth.permitted.return_value = True
+    auth.authenticate = AsyncMock(return_value=_valid_identity())
     return auth
 
 
@@ -25,7 +54,7 @@ def mock_dispatcher_factory():
         dispatcher.receive = AsyncMock()
         dispatcher.destroy = AsyncMock()
         return dispatcher
-    
+
     return dispatcher_factory
 
 
@@ -35,7 +64,8 @@ def socket_endpoint(mock_auth, mock_dispatcher_factory):
     return SocketEndpoint(
         endpoint_path="/test-socket",
         auth=mock_auth,
-        dispatcher=mock_dispatcher_factory
+        dispatcher=mock_dispatcher_factory,
+        capability=TEST_CAP,
     )
 
 
@@ -61,7 +91,10 @@ def mock_request():
 @pytest.mark.asyncio
 async def test_listener_graceful_shutdown_on_close():
     """Test listener handles websocket close gracefully."""
-    socket_endpoint = SocketEndpoint("/test", MagicMock(), AsyncMock())
+    socket_endpoint = SocketEndpoint(
+        "/test", MagicMock(), AsyncMock(),
+        capability=TEST_CAP,
+    )
     
     # Mock websocket that closes after one message
     ws = AsyncMock()
@@ -99,9 +132,9 @@ async def test_listener_graceful_shutdown_on_close():
 
 @pytest.mark.asyncio
 async def test_handle_normal_flow():
-    """Test normal websocket handling flow."""
+    """Valid bearer → handshake accepted, dispatcher created."""
     mock_auth = MagicMock()
-    mock_auth.permitted.return_value = True
+    mock_auth.authenticate = AsyncMock(return_value=_valid_identity())
 
     dispatcher_created = False
     async def mock_dispatcher_factory(ws, running, match_info):
@@ -111,7 +144,10 @@ async def test_handle_normal_flow():
         dispatcher.destroy = AsyncMock()
         return dispatcher
 
-    socket_endpoint = SocketEndpoint("/test", mock_auth, mock_dispatcher_factory)
+    socket_endpoint = SocketEndpoint(
+        "/test", mock_auth, mock_dispatcher_factory,
+        capability=TEST_CAP,
+    )
 
     request = MagicMock()
     request.query = {"token": "valid-token"}
@@ -155,7 +191,7 @@ async def test_handle_normal_flow():
 async def test_handle_exception_group_cleanup():
     """Test exception group triggers dispatcher cleanup."""
     mock_auth = MagicMock()
-    mock_auth.permitted.return_value = True
+    mock_auth.authenticate = AsyncMock(return_value=_valid_identity())
 
     mock_dispatcher = AsyncMock()
     mock_dispatcher.destroy = AsyncMock()
@@ -163,7 +199,10 @@ async def test_handle_exception_group_cleanup():
     async def mock_dispatcher_factory(ws, running, match_info):
         return mock_dispatcher
 
-    socket_endpoint = SocketEndpoint("/test", mock_auth, mock_dispatcher_factory)
+    socket_endpoint = SocketEndpoint(
+        "/test", mock_auth, mock_dispatcher_factory,
+        capability=TEST_CAP,
+    )
 
     request = MagicMock()
     request.query = {"token": "valid-token"}
@@ -222,7 +261,7 @@ async def test_handle_exception_group_cleanup():
 async def test_handle_dispatcher_cleanup_timeout():
     """Test dispatcher cleanup with timeout."""
     mock_auth = MagicMock()
-    mock_auth.permitted.return_value = True
+    mock_auth.authenticate = AsyncMock(return_value=_valid_identity())
 
     # Mock dispatcher that takes long to destroy
     mock_dispatcher = AsyncMock()
@@ -231,7 +270,10 @@ async def test_handle_dispatcher_cleanup_timeout():
     async def mock_dispatcher_factory(ws, running, match_info):
         return mock_dispatcher
 
-    socket_endpoint = SocketEndpoint("/test", mock_auth, mock_dispatcher_factory)
+    socket_endpoint = SocketEndpoint(
+        "/test", mock_auth, mock_dispatcher_factory,
+        capability=TEST_CAP,
+    )
 
     request = MagicMock()
     request.query = {"token": "valid-token"}
@@ -285,49 +327,67 @@ async def test_handle_dispatcher_cleanup_timeout():
 
 @pytest.mark.asyncio
 async def test_handle_unauthorized_request():
-    """Test handling of unauthorized requests."""
+    """A bearer that the IAM layer rejects causes the handshake to
+    fail with 401.  IamAuth surfaces an HTTPUnauthorized; the
+    endpoint propagates it.  Note that the endpoint intentionally
+    does NOT distinguish 'bad token', 'expired', 'revoked', etc. —
+    that's the IAM error-masking policy."""
     mock_auth = MagicMock()
-    mock_auth.permitted.return_value = False  # Unauthorized
-    
-    socket_endpoint = SocketEndpoint("/test", mock_auth, AsyncMock())
-    
+    mock_auth.authenticate = AsyncMock(side_effect=web.HTTPUnauthorized(
+        text='{"error":"auth failure"}',
+        content_type="application/json",
+    ))
+
+    socket_endpoint = SocketEndpoint(
+        "/test", mock_auth, AsyncMock(),
+        capability=TEST_CAP,
+    )
+
     request = MagicMock()
     request.query = {"token": "invalid-token"}
-    
+
     result = await socket_endpoint.handle(request)
-    
-    # Should return HTTP 401
+
     assert isinstance(result, web.HTTPUnauthorized)
-    
-    # Should have checked permission
-    mock_auth.permitted.assert_called_once_with("invalid-token", "socket")
+    # authenticate must have been invoked with a synthetic request
+    # carrying Bearer <the-token>.  The endpoint wraps the query-
+    # string token into an Authorization header for a uniform auth
+    # path — the IAM layer does not look at query strings directly.
+    mock_auth.authenticate.assert_called_once()
+    passed_req = mock_auth.authenticate.call_args.args[0]
+    assert passed_req.headers["Authorization"] == "Bearer invalid-token"
 
 
 @pytest.mark.asyncio
 async def test_handle_missing_token():
-    """Test handling of requests with missing token."""
+    """Request with no ``token`` query param → 401 before any
+    IAM call is made (cheap short-circuit)."""
     mock_auth = MagicMock()
-    mock_auth.permitted.return_value = False
-    
-    socket_endpoint = SocketEndpoint("/test", mock_auth, AsyncMock())
-    
+    mock_auth.authenticate = AsyncMock(
+        side_effect=AssertionError(
+            "authenticate must not be invoked when no token is present"
+        ),
+    )
+
+    socket_endpoint = SocketEndpoint(
+        "/test", mock_auth, AsyncMock(),
+        capability=TEST_CAP,
+    )
+
     request = MagicMock()
     request.query = {}  # No token
-    
+
     result = await socket_endpoint.handle(request)
-    
-    # Should return HTTP 401
+
     assert isinstance(result, web.HTTPUnauthorized)
-    
-    # Should have checked permission with empty token
-    mock_auth.permitted.assert_called_once_with("", "socket")
+    mock_auth.authenticate.assert_not_called()
 
 
 @pytest.mark.asyncio
 async def test_handle_websocket_already_closed():
     """Test handling when websocket is already closed."""
     mock_auth = MagicMock()
-    mock_auth.permitted.return_value = True
+    mock_auth.authenticate = AsyncMock(return_value=_valid_identity())
 
     mock_dispatcher = AsyncMock()
     mock_dispatcher.destroy = AsyncMock()
@@ -335,7 +395,10 @@ async def test_handle_websocket_already_closed():
     async def mock_dispatcher_factory(ws, running, match_info):
         return mock_dispatcher
 
-    socket_endpoint = SocketEndpoint("/test", mock_auth, mock_dispatcher_factory)
+    socket_endpoint = SocketEndpoint(
+        "/test", mock_auth, mock_dispatcher_factory,
+        capability=TEST_CAP,
+    )
 
     request = MagicMock()
     request.query = {"token": "valid-token"}