connection-hub 0.0.3__tar.gz

connection_hub-0.0.3/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: connection-hub
+Version: 0.0.3
+Summary: Connection Hub delegated-access authority and client SDK.
+Author: Elena Viter
+License: MIT
+Project-URL: Homepage, https://github.com/elenaviter/app-ecosystem
+Project-URL: Repository, https://github.com/elenaviter/app-ecosystem
+Project-URL: Documentation, https://github.com/elenaviter/app-ecosystem/tree/main/docs/connection-hub
+Project-URL: Issues, https://github.com/elenaviter/app-ecosystem/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp<4,>=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Requires-Dist: pytest-asyncio<2,>=0.23; extra == "test"
+
+# Connection Hub
+
+The Python library and client SDK for the Connection Hub product.
+
+Connection Hub gives every agent, automation, and connected application its own
+delegated-access card. The card records whose authority the caller uses, which
+resources and operations it may reach, which connected accounts it may use,
+and when that authority expires. A service resolves the current card and
+current capability catalog at the operation boundary, so an edit or revocation
+applies to the next call.
+
+## Install
+
+```bash
+python -m pip install connection-hub
+```
+
+`0.0.3` is an alpha release. It contains the portable implementation used by
+the Connection Hub application in this repository:
+
+- versioned delegated cards and capability catalogs;
+- live card/catalog admission for managed REST, MCP, and named-service calls;
+- delegated OAuth client and connected-account policy contracts;
+- structured, actionable denial results;
+- direct protected-service admission with an opaque delegated bearer and an
+  independent replay-protected workload proof;
+- explicit host ports for storage, identity, dispatch, secrets, and live
+  delivery.
+
+The same product is currently hosted in KDCube under the technical app id
+[`connection-hub@1-0`](../../apps/connection-hub@1-0/README.md). The library
+owns portable authority semantics and client contracts; the application host
+supplies authenticated sessions, storage, secret resolution, Redis protocol
+state, HTTP surfaces, and the user interface.
+
+## Direct Protected-Service Admission
+
+An external backend can accept a user's opaque delegated bearer and ask the
+Connection Hub for a live decision about one concrete operation. The backend
+also signs the request with its own registered workload secret; possession of
+the user bearer alone is not service identity.
+
+```python
+import secrets
+import time
+
+from connection_hub.delegated_credentials.admission import (
+    AdmissionRequest,
+    sign_admission_request,
+)
+
+request = AdmissionRequest(
+    resource="https://api.example.test/customers",
+    operation="customers.search",
+)
+timestamp = str(int(time.time()))
+nonce = secrets.token_urlsafe(24)
+signature = sign_admission_request(
+    secret=service_signing_secret,
+    service_id="crm-api",
+    timestamp=timestamp,
+    nonce=nonce,
+    delegated_token=user_delegated_bearer,
+    request=request,
+)
+```
+
+The service sends the semantic request body and the four `X-Connection-Hub-*` proof
+headers to the configured Connection Hub admission endpoint, with the opaque
+delegated bearer in `Authorization: Bearer ...`. An allow response contains a
+service-scoped subject and only the bounded authority relevant to that
+operation. It never returns provider credentials or the platform's internal
+user id.
+
+See the runnable
+[`direct-admission-service`](../../examples/connection-hub/direct-admission-service/README.md)
+and the [deployment recipe](../../docs/connection-hub/recipes/direct-protected-service.md).
+
+## Integration Boundaries
+
+- The service registry authenticates workloads and binds each service to
+  resource selectors. It does not duplicate the operation/grant catalog.
+- Every decision intersects the delegated bearer with the current card and
+  active catalog. A cached allow is not an authority source.
+- Connected-account credential resolution is a separate trusted operation;
+  direct admission does not export provider secrets.
+- A protected backend still applies its own domain authorization after
+  Connection Hub admission.
+
+## Documentation
+
+- [Connection Hub architecture and semantic requirements](../../docs/connection-hub/connection-hub-architecture.md)
+- [Delegated authority and admission](../../docs/connection-hub/package/delegated-authority-and-admission.md)
+- [Delegated access cards](../../docs/connection-hub/package/delegated-cards.md)
+- [OAuth delegated credential protocol](../../docs/connection-hub/package/oauth-delegated-credential-protocol.md)
+- [Package extraction boundary](../../docs/connection-hub/package/extraction-architecture.md)
+- [Package release procedure](../../docs/package-releases.md)
+
+License: MIT. Source: https://github.com/elenaviter/app-ecosystem

connection_hub-0.0.3/README.md

@@ -0,0 +1,99 @@
+# Connection Hub
+
+The Python library and client SDK for the Connection Hub product.
+
+Connection Hub gives every agent, automation, and connected application its own
+delegated-access card. The card records whose authority the caller uses, which
+resources and operations it may reach, which connected accounts it may use,
+and when that authority expires. A service resolves the current card and
+current capability catalog at the operation boundary, so an edit or revocation
+applies to the next call.
+
+## Install
+
+```bash
+python -m pip install connection-hub
+```
+
+`0.0.3` is an alpha release. It contains the portable implementation used by
+the Connection Hub application in this repository:
+
+- versioned delegated cards and capability catalogs;
+- live card/catalog admission for managed REST, MCP, and named-service calls;
+- delegated OAuth client and connected-account policy contracts;
+- structured, actionable denial results;
+- direct protected-service admission with an opaque delegated bearer and an
+  independent replay-protected workload proof;
+- explicit host ports for storage, identity, dispatch, secrets, and live
+  delivery.
+
+The same product is currently hosted in KDCube under the technical app id
+[`connection-hub@1-0`](../../apps/connection-hub@1-0/README.md). The library
+owns portable authority semantics and client contracts; the application host
+supplies authenticated sessions, storage, secret resolution, Redis protocol
+state, HTTP surfaces, and the user interface.
+
+## Direct Protected-Service Admission
+
+An external backend can accept a user's opaque delegated bearer and ask the
+Connection Hub for a live decision about one concrete operation. The backend
+also signs the request with its own registered workload secret; possession of
+the user bearer alone is not service identity.
+
+```python
+import secrets
+import time
+
+from connection_hub.delegated_credentials.admission import (
+    AdmissionRequest,
+    sign_admission_request,
+)
+
+request = AdmissionRequest(
+    resource="https://api.example.test/customers",
+    operation="customers.search",
+)
+timestamp = str(int(time.time()))
+nonce = secrets.token_urlsafe(24)
+signature = sign_admission_request(
+    secret=service_signing_secret,
+    service_id="crm-api",
+    timestamp=timestamp,
+    nonce=nonce,
+    delegated_token=user_delegated_bearer,
+    request=request,
+)
+```
+
+The service sends the semantic request body and the four `X-Connection-Hub-*` proof
+headers to the configured Connection Hub admission endpoint, with the opaque
+delegated bearer in `Authorization: Bearer ...`. An allow response contains a
+service-scoped subject and only the bounded authority relevant to that
+operation. It never returns provider credentials or the platform's internal
+user id.
+
+See the runnable
+[`direct-admission-service`](../../examples/connection-hub/direct-admission-service/README.md)
+and the [deployment recipe](../../docs/connection-hub/recipes/direct-protected-service.md).
+
+## Integration Boundaries
+
+- The service registry authenticates workloads and binds each service to
+  resource selectors. It does not duplicate the operation/grant catalog.
+- Every decision intersects the delegated bearer with the current card and
+  active catalog. A cached allow is not an authority source.
+- Connected-account credential resolution is a separate trusted operation;
+  direct admission does not export provider secrets.
+- A protected backend still applies its own domain authorization after
+  Connection Hub admission.
+
+## Documentation
+
+- [Connection Hub architecture and semantic requirements](../../docs/connection-hub/connection-hub-architecture.md)
+- [Delegated authority and admission](../../docs/connection-hub/package/delegated-authority-and-admission.md)
+- [Delegated access cards](../../docs/connection-hub/package/delegated-cards.md)
+- [OAuth delegated credential protocol](../../docs/connection-hub/package/oauth-delegated-credential-protocol.md)
+- [Package extraction boundary](../../docs/connection-hub/package/extraction-architecture.md)
+- [Package release procedure](../../docs/package-releases.md)
+
+License: MIT. Source: https://github.com/elenaviter/app-ecosystem

connection_hub-0.0.3/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "connection-hub"
+version = "0.0.3"
+description = "Connection Hub delegated-access authority and client SDK."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Elena Viter" }]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = [
+    "aiohttp>=3.9,<4",
+    "httpx>=0.27,<1",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8,<10",
+    "pytest-asyncio>=0.23,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/elenaviter/app-ecosystem"
+Repository = "https://github.com/elenaviter/app-ecosystem"
+Documentation = "https://github.com/elenaviter/app-ecosystem/tree/main/docs/connection-hub"
+Issues = "https://github.com/elenaviter/app-ecosystem/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+connection_hub = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

connection_hub-0.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

connection_hub-0.0.3/src/connection_hub/__init__.py

@@ -0,0 +1,58 @@
+"""Connection Hub delegated-access authority and client SDK.
+
+Every caller has its own identity card, authority lives in one central record,
+and a guarded boundary resolves current authority on every call.
+
+Version 0.0.3 is a development release. It contains the host-neutral authority
+core, delegated card/catalog contracts, OAuth and connected-account policy,
+named-service admission, and direct protected-service admission. Host storage,
+identity, and transport adapters remain explicit integration responsibilities.
+See the repository for status: https://github.com/elenaviter/app-ecosystem
+"""
+
+from importlib import import_module
+from typing import Any
+
+__version__ = "0.0.3"
+
+_EXPORTS: dict[str, str] = {}
+for name in (
+    "NAMESPACE",
+    "CONNECTION_CATALOG",
+    "CONNECTION_STATUS",
+    "CONNECTION_GET_TOKEN",
+    "CONNECTION_DISCONNECT",
+    "OAUTH_START",
+    "AGENT_GRANT_GET_TOKEN",
+    "AGENT_GRANT_CHECK",
+    "CONNECTION_OPERATIONS",
+    "ConnectionOperationSpec",
+    "build_connection_operations",
+    "Connection",
+    "ConnectionToken",
+    "CatalogEntry",
+    "ClientApp",
+    "AmbiguousConnectionAccount",
+):
+    _EXPORTS[name] = "connection_hub.contract"
+for name in ("ConnectionsClient", "ConnectionsError", "ConnectionsTransport"):
+    _EXPORTS[name] = "connection_hub.client"
+for name in (
+    "AuthorityProviderSpec",
+    "AuthorityRegistry",
+    "AuthorityResolution",
+    "CredentialEnvelope",
+    "authority_provider_spec_from_declaration",
+):
+    _EXPORTS[name] = "connection_hub.authority_registry"
+
+__all__ = ["__version__", *_EXPORTS]
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _EXPORTS.get(name)
+    if not module_name:
+        raise AttributeError(name)
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value

connection_hub-0.0.3/src/connection_hub/agent_account_scope.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Elena Viter
+
+"""Request-scoped per-agent account binding for connected-account resolution.
+
+The broker (`delegated_to_kdcube.broker.ensure_claim`) decides which connected
+account satisfies a provider claim. The calling AGENT may be bound, per
+provider, to specific account(s) AND — per account — to specific claims
+(`account_scope: {provider_id: {account_id: [claims]}}` on its grant card). That
+binding must reach the broker, but the shared resolver
+(`integrations.connected_accounts.resolve_connected_account_claim`) runs
+downstream of the door through a generic transport with no HTTP request.
+
+Whoever HAS the agent's credential sets the binding into this contextvar at the
+boundary — the door bridge from `request.state.delegated_credential`; a native
+agent gate from the same view — and the resolver reads back the per-account
+claim map for the provider it is resolving.
+
+Default-closed for delegated callers: when an agent identity is bound for the
+turn and the provider has NO binding entry, the resolver receives an EMPTY
+mapping — "agent turn, nothing granted on this provider" — and the broker
+denies with the agent-grant reason until the user binds an account. Only
+non-agent turns (no delegated identity — the user's own trusted tools) resolve
+to None, meaning no restriction. An agent never inherits the accounts the user
+connected; the binding is the grant.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from contextlib import contextmanager
+from typing import Any, Mapping
+
+_ACCOUNT_SCOPE: contextvars.ContextVar[dict] = contextvars.ContextVar(
+    "kdcube_agent_account_scope", default={}
+)
+
+# The calling agent's delegated identity (client_id + delegated-resource id) for
+# the current turn. The connected-account resolver reads it to route a
+# per-account claim miss to THIS agent's grant card (Delegated by KDCube) instead
+# of a connect-a-provider banner. Set alongside the account scope by the gate
+# that holds the agent's credential; unset / non-agent turns leave it empty.
+_AGENT_IDENTITY: contextvars.ContextVar[dict] = contextvars.ContextVar(
+    "kdcube_agent_identity", default={}
+)
+
+
+def normalize_account_scope(
+    scope: Mapping[str, Any] | None,
+) -> dict[str, dict[str, tuple[str, ...]]]:
+    """Normalize exact per-provider, per-account claim authority."""
+    normalized: dict[str, dict[str, tuple[str, ...]]] = {}
+    for provider, entry in dict(scope or {}).items():
+        pkey = str(provider or "").strip()
+        if not pkey:
+            continue
+        accounts: dict[str, tuple[str, ...]] = {}
+        if isinstance(entry, Mapping):
+            for account_id, claims in entry.items():
+                akey = str(account_id or "").strip()
+                if not akey:
+                    continue
+                cl = tuple(str(c).strip() for c in (claims or ()) if str(c or "").strip())
+                accounts[akey] = cl or ("*",)
+        else:
+            for account_id in (entry or []):
+                akey = str(account_id or "").strip()
+                if akey:
+                    accounts[akey] = ("*",)
+        if accounts:
+            normalized[pkey] = accounts
+    return normalized
+
+
+def set_agent_account_scope(scope: Mapping[str, Any] | None) -> None:
+    """Bind the current agent's per-account claim scope
+    ({provider_id: {account_id: [claims]}}). Accepts the legacy list form
+    ({provider_id: [account_ids]}) and migrates it (account -> any claim)."""
+    _ACCOUNT_SCOPE.set(normalize_account_scope(scope))
+
+
+def clear_agent_account_scope() -> None:
+    _ACCOUNT_SCOPE.set({})
+    _AGENT_IDENTITY.set({})
+
+
+def set_agent_identity(*, client_id: str = "", resource: str = "") -> None:
+    """Bind the current agent's delegated identity (its
+    ``kdcube-agent:<app>:<agent>`` or ``dcr-…`` client id and the
+    delegated-resource id its grant is keyed under). The client id alone is
+    enough to mark the turn as a delegated (agent) turn — and with it the
+    default-closed account binding; the resource additionally lets a claim
+    miss deep-link the exact grant card. An empty client id clears the field."""
+    cid = str(client_id or "").strip()
+    res = str(resource or "").strip()
+    _AGENT_IDENTITY.set({"client_id": cid, "resource": res} if cid else {})
+
+
+@contextmanager
+def bind_agent_account_scope(
+    scope: Mapping[str, Any] | None,
+    *,
+    client_id: str,
+    resource: str = "",
+):
+    """Bind one delegated provider invocation and restore prior task state."""
+
+    cid = str(client_id or "").strip()
+    res = str(resource or "").strip()
+    scope_token = _ACCOUNT_SCOPE.set(normalize_account_scope(scope))
+    identity_token = _AGENT_IDENTITY.set(
+        {"client_id": cid, "resource": res} if cid else {}
+    )
+    try:
+        yield
+    finally:
+        _AGENT_IDENTITY.reset(identity_token)
+        _ACCOUNT_SCOPE.reset(scope_token)
+
+
+def agent_identity() -> dict:
+    """The current agent's delegated identity ``{client_id, resource}``, or an
+    empty dict on a non-agent turn / when it was not set."""
+    return dict(_AGENT_IDENTITY.get() or {})
+
+
+def account_claim_scope_for(provider_id: str) -> dict[str, tuple[str, ...]] | None:
+    """The current agent's per-account claim binding for ``provider_id`` —
+    ``{account_id: (claims...)}`` (account "*" = any account, claim "*" = any
+    claim).
+
+    Returns None ONLY on a non-agent turn (no delegated identity bound): the
+    user's own trusted tools are unrestricted. On an agent turn with no binding
+    entry for this provider it returns an EMPTY mapping — default-closed: the
+    agent is bound to no account there, and the broker denies with the
+    agent-grant reason until the user grants one."""
+    entry = _ACCOUNT_SCOPE.get().get(str(provider_id or "").strip())
+    if not entry:
+        return {} if _AGENT_IDENTITY.get() else None
+    return {
+        str(account_id).strip(): tuple(claims)
+        for account_id, claims in dict(entry).items()
+        if str(account_id or "").strip()
+    }
+
+
+__all__ = [
+    "set_agent_account_scope",
+    "clear_agent_account_scope",
+    "account_claim_scope_for",
+    "set_agent_identity",
+    "agent_identity",
+    "bind_agent_account_scope",
+    "normalize_account_scope",
+]

connection_hub-0.0.3/src/connection_hub/authenticators/__init__.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Elena Viter
+
+"""Host-neutral request-authenticator contracts."""
+
+from connection_hub.authenticators.authority import (
+    AuthRequestHints,
+    AuthorityIdentity,
+    SurfaceGuardRequirement,
+    select_authenticator_candidates,
+)
+from connection_hub.authenticators.models import (
+    AuthenticatedRequest,
+    AuthenticatorRegistration,
+    RequestEnvelope,
+)
+from connection_hub.authenticators.client import (
+    DEFAULT_CONNECTION_HUB_BUNDLE_ID,
+    REQUEST_AUTHENTICATE_OPERATION,
+    ConnectionHubAuthenticatorsClient,
+)
+
+__all__ = [
+    "AuthRequestHints",
+    "AuthenticatedRequest",
+    "AuthenticatorRegistration",
+    "AuthorityIdentity",
+    "ConnectionHubAuthenticatorsClient",
+    "DEFAULT_CONNECTION_HUB_BUNDLE_ID",
+    "REQUEST_AUTHENTICATE_OPERATION",
+    "RequestEnvelope",
+    "SurfaceGuardRequirement",
+    "select_authenticator_candidates",
+]